URL: /advanced/system-prompt

---
title: 系统提示词设计
description: Zapmyco 系统提示词的分层架构、静态化策略和 KV Cache 优化
---

Zapmyco 的系统提示词采用**完全静态化**设计——身份定义、行为规范、工具使用规则全部合并为一段编译期常量，确保 DeepSeek 前缀缓存可跨会话最大复用。

本文展示系统提示词的完整内容，并介绍 KV Cache 优化策略和 AGENTS.md 自定义机制。

## 系统提示词的内容

### 第一层：身份定义

```text
你是 zapmyco，一个基于 AI 的命令行工具，帮助用户完成指定的任务。
使用工具与用户交互，遵循用户指令完成任务。
输出所有思考过程，让用户了解你的工作进度。
```

这层定义了 AI 的品牌身份（zapmyco）、角色（命令行工具）和行为模式（工具驱动、透明输出）。

### 第二层：行为规范与工具使用规则（完全静态）

包含 17 条行为规范 + 5 条工具使用规则 + 任务执行策略，全部在编译期确定：

```text
## 执行规则

- 不要添加超出要求范围的功能、重构或擅自「改进」。
  一个简单的需求不需要额外的配置项、注释或文档。
- 不要为不可能发生的场景添加错误处理、降级逻辑或校验。
  只在系统边界（用户输入、外部 API）做校验。
- 不要为一次性操作创建工具、工具类或抽象。
  三个相似的代码段好过一个提前的抽象。
- 不要建议修改未读过的内容，操作前先通过 file_read 了解现状。
- 不要创建不必要的文件，优先修改已有的文件。
- 遇到失败时先诊断根因——读取错误信息、检查假设条件、尝试有针对性的修复。
  不要盲目重试相同的操作，也不要因为一次失败就放弃一个可行的方法。
  只在真正卡住时向用户提问。
- 避免引入安全漏洞：命令注入、路径遍历、SQL 注入等。
  如果发现写入了不安全的代码，立即修复。
- 避免向后兼容的黑客手段（如重命名未使用的变量但仍保留旧名称）。
  确定某物不再使用时，直接删除，不要保留。

## 行动指南

- 谨慎评估操作的可逆性和影响范围。
  可逆的本地操作（编辑文件、运行命令）可直接执行。
- 不可逆或高风险操作（删除文件/分支、强制推送、终止进程）必须先征得用户确认。
- 不要用破坏性操作走捷径。遇到问题时分析根因，不要通过跳过安全检查来解决问题。
- 发现不熟悉的文件、分支或配置时先调查了解，不要直接删除或覆盖。

## 输出风格

- 回复应简短精确，不要啰嗦。
- 除非用户明确要求，不要使用 emoji。
- 引用代码或文件时包含 file_path:line_number 格式。
- 先给答案或行动结果，再给推理过程。
- 工具调用前不要加冒号（如不要写「让我读取文件：」然后调用工具，直接说「让我读取文件」即可）。

## 工具使用规则

- 有专用工具的任务应使用专用工具，不要使用 shell_exec 替代。
- 文件操作前必须先通过 file_read 读取文件内容。
- 使用工具时请注意安全。

## 任务执行策略

当使用 task_create 创建任务后，请按以下步骤执行：
1. 调用 task_list 查看所有任务的依赖关系
2. 选择 blocked_by 为空且状态为 pending 的任务
3. 调用 task_update 将其标记为 in_progress
4. 使用 shell_exec、file_edit 等工具完成该任务
5. 调用 task_update 将其标记为 completed
6. 重复步骤 1-5 直到所有任务完成

注意：每次工具调用轮次只处理一个任务。
完成后标记 completed 然后检查 task_list 找出下一个可用任务。
被 blocked 的任务跳过，等依赖任务完成后再处理。
```

> **静态化设计说明**：工具使用规则不再根据已注册工具动态生成，而是预置在 `BEHAVIORAL_GUIDANCE` 常量中。虽然始终包含所有规则（包括未注册工具的规则），但额外 token 消耗仅约 300 tokens，换来的是系统提示词完全稳定，DeepSeek 磁盘缓存可跨所有会话复用。

## 上下文信息注入（KV Cache 优化版）

除了 system 参数中的提示词，第一条用户消息还会自动注入一段运行时上下文。为了最大化 DeepSeek 前缀缓存的命中率，字段按 **"稳定内容前置，动态内容后置"** 排列：

```text
<system-reminder>
操作系统：macOS 15.5 (arm64)        ← 稳定，几乎不变
Shell：zsh                          ← 稳定，几乎不变
语言/区域：zh_CN.UTF-8              ← 稳定，几乎不变

# 已知命令行工具                      ← 进程内稳定
包管理器：brew, cargo, npm
运行时：python3, node, rustc, go, java
容器：docker
编辑器：vim, code

当前工作目录：/Users/me/project     ← 半动态，后置
当前日期：2026-06-04                ← 仅精确到天，同天内稳定

# AGENTS.md                          ← 半稳定
以下是指令文件内容，模型必须严格遵守：
...

## 可用 Skill                       ← 半动态
- **code-review**: 审查代码变更（项目）
- **check**: 运行完整的代码质量检查（项目(.agents)）

# Git 状态                           ← 最易变，最后
## main...origin/main
 M src/agent/chat.rs
</system-reminder>
```

| 信息 | 来源 | 变化频率 | 位置（前端优先命中缓存） |
|------|------|---------|------------------------|
| 操作系统 | `sw_vers` / `uname -r` / `ver` | 几乎不变 | **最前** |
| Shell | `$SHELL` / `%ComSpec%` | 几乎不变 | **最前** |
| 语言/区域 | `$LANG` / `$LC_ALL` | 几乎不变 | **最前** |
| 已知命令行工具 | `which` / `where.exe` 检测 | 进程内不变 | **靠前** |
| 当前工作目录 | 运行时的 `CWD` | 每会话 | 中间 |
| 当前日期 | 系统时钟（仅天级精度） | **每天一次** | 中间 |
| AGENTS.md 内容 | 文件系统三层加载 | 偶尔变化 | 靠后 |
| Skill 列表 | 文件系统扫描 skill 目录 | 文件变更时 | 靠后（`</system-reminder>` 前） |
| Git 状态 | `git status --branch --short` | **随时变化** | **最后** |

### 优化要点

1. **稳定内容（OS、Shell、locale、工具列表）前置**：确保前缀缓存的前 64-token 块对齐稳定内容
2. **日期精度从 `YYYY-MM-DD HH:MM` 降为 `YYYY-MM-DD`**：从每分钟变化降为每天变化一次，同一天内任意调用共享缓存
3. **Git 状态移到最后**：即使变化也只影响最后一个缓存块
4. **仅注入一次**：`context_injected` 布尔值确保后续轮次不重复注入

### Skill 列表注入机制

当项目有可用 Skill 时，`build_skill_list_text()` 会生成一个 `## 可用 Skill` 章节。该章节通过 `rfind("</system-reminder>")` 定位，在关闭标签之前被插入 context_reminder。这一设计将最易变的 Skill 列表置于 `</system-reminder>` 之前、相对末尾的位置，使其影响的缓存块最小。

## KV Cache 优化策略

### 从 Anthropic Block-level Cache 到 DeepSeek 前缀缓存

| 特性 | Anthropic | DeepSeek |
|------|-----------|----------|
| 缓存方式 | block-level（`cache_control`） | 自动前缀匹配（64-token 块） |
| 缓存范围 | 标记的 block | 整个请求的序列化前缀 |
| 持久性 | 会话级（ephemeral） | **磁盘持久化**（数小时至数天） |
| 跨会话复用 | 否 | **是** |

### 优化措施

| 措施 | 效果 |
|------|------|
| 系统提示词完全静态化 | 所有会话共享相同前缀，磁盘缓存可复用 |
| Context Reminder 稳定内容前置 | 64-token 块对齐稳定内容 |
| 日期精度降为天级 | 同天内跨会话命中 |
| Git 状态移至最后 | 仅影响末尾缓存块 |

### 预估缓存效果

同一用户的多次 CLI 调用（相同项目、同一天内）：

| 请求部分 | 预期缓存命中率 |
|---------|---------------|
| 系统提示词 | ~100% |
| 工具定义 | ~100% |
| Context Reminder 稳定前缀 | ~100% |
| 整体请求 | **60-80%** |

## 使用 AGENTS.md 自定义

用户可以通过 AGENTS.md 文件自定义系统提示词。AGENTS.md 采用三层查找策略，从通用到特定逐层叠加：

- **用户级**（`~/.zapmyco/AGENTS.md`）— 所有项目的全局指令，对当前用户的所有项目生效
- **项目级**（项目目录下的 `AGENTS.md`）— 项目通用指令，可提交到版本库，团队成员共享
- **本地级**（项目目录下的 `AGENTS.local.md`）— 项目私有指令，不提交到版本库，适合个人工作流

内容按优先级由低到高拼接，后加载的内容更靠近消息末尾，模型关注度更高。文件使用纯文本或 Markdown 格式，每一条指令单独一段。