Zapmyco
进阶

系统提示词设计

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随时变化最后

优化要点

  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 前缀缓存

特性AnthropicDeepSeek
缓存方式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 格式,每一条指令单独一段。

On this page