系统提示词设计
Zapmyco 系统提示词的分层架构、静态化策略和 KV Cache 优化
Zapmyco 的系统提示词采用完全静态化设计——身份定义、行为规范、工具使用规则全部合并为一段编译期常量,确保 DeepSeek 前缀缓存可跨会话最大复用。
本文展示系统提示词的完整内容,并介绍 KV Cache 优化策略和 AGENTS.md 自定义机制。
系统提示词的内容
第一层:身份定义
你是 zapmyco,一个基于 AI 的命令行工具,帮助用户完成指定的任务。
使用工具与用户交互,遵循用户指令完成任务。
输出所有思考过程,让用户了解你的工作进度。这层定义了 AI 的品牌身份(zapmyco)、角色(命令行工具)和行为模式(工具驱动、透明输出)。
第二层:行为规范与工具使用规则(完全静态)
包含 17 条行为规范 + 5 条工具使用规则 + 任务执行策略,全部在编译期确定:
## 执行规则
- 不要添加超出要求范围的功能、重构或擅自「改进」。
一个简单的需求不需要额外的配置项、注释或文档。
- 不要为不可能发生的场景添加错误处理、降级逻辑或校验。
只在系统边界(用户输入、外部 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 前缀缓存的命中率,字段按 "稳定内容前置,动态内容后置" 排列:
<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 | 随时变化 | 最后 |
优化要点
- 稳定内容(OS、Shell、locale、工具列表)前置:确保前缀缓存的前 64-token 块对齐稳定内容
- 日期精度从
YYYY-MM-DD HH:MM降为YYYY-MM-DD:从每分钟变化降为每天变化一次,同一天内任意调用共享缓存 - Git 状态移到最后:即使变化也只影响最后一个缓存块
- 仅注入一次:
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 格式,每一条指令单独一段。