提示词写作规范¶
oh-mai-agent 提示词统一写作风格。精简、指令式、中文关键词优先。
适用范围：prompt/templates/ 下的模板文件、prompt/builders/ 生成的动态片段、以及工具描述（tools/ 下各通道的 description）。
关键词¶
采用 RFC 2119 中文等价词，作为提示词的规范语言。关键词本身即是标记，禁止将其用于普通陈述。
| 关键词 | 优先级 | 含义 |
|---|---|---|
| 必须 | P0 | 绝对要求，不可违反。替换"请确保"、"一定要"。 |
| 禁止 | P0 | 绝对禁止。替换"不要"、"切勿"。与"必须"同权重。 |
| 应当 | P1 | 强烈推荐。有已知取舍时可偏离。替换"最好"、"建议"。 |
| 避免 | P1 | 强烈不推荐。替换"尽量别"、"不建议"。 |
| 建议 | P2 | 可选，提供参考但不强制。替换"可以"、"不妨"。 |
优先级规则：P0 > P1 > P2。高优先级覆盖低优先级。禁止和必须冲突时，禁止优先。
关键词不得用于：事实性描述（"此工具返回 JSON"）、代码块、示例、模板变量 {{var}} 占位语法。
当前模板示例：
标签语义¶
XML 标签是结构性标记，模型将其视为权威指令。每个标签的含义必须与其名称严格一致，禁止发明装饰性标签（<directives>、<protocol> 等）。
本仓库当前使用的标签：
| 标签 | 位置 | 用途 |
|---|---|---|
<plugin_injected_instruction> |
运行时注入 | 包裹插件动态指令，优先处理 |
<plugin_context_note> |
运行时注入 | 包裹上下文提示，用于理解对话 |
计划引入的标签（来自 oh-my-pi 实践，Wave 4 后启用）：
| 标签 | 位置 | 用途 |
|---|---|---|
<system-conventions> |
提示词开头 | 定义标签语义 + 关键词契约 |
<critical> |
开头 + 结尾 | 不可违反的规则。长提示（>150 行）必须在结尾重复 1-2 条最关键规则 |
<stakes> |
开头 | 领域基调，说明"为什么正确性重要" |
<communication> |
开头 | 语气、回复格式、人称 |
<completeness> |
结尾 | "完成"的定义，反收缩规则 |
<yielding> |
结尾 | 产出前检查清单 |
"迷失在中间"原则：模型对首尾内容的注意力显著高于中间部分（中间衰减约 20%）。关键约束必须放在开头和结尾，参考材料、环境配置和模板变量填充内容放在中间。
密度¶
提示词按 token 计费，每条句子必须有决策价值。每行只承载一个要点。
密度规则：
- 一行一意：每条要点只说一件事。子句若不影响行为则删除。
- 不用粗体标题后重复正文：标题命名了规则，正文无需再说一遍。
- 条件前置：
X？则 Y。替代如果 X，那么 Y。当 X 是快速判断时适用。 - 内联理由仅当改变决策：
"否则会重复"保留；"这样可以提高效率"删除。 - 符号优于文字：
→、=、+/-、1..5。枚举用紧凑格式。 - 战术级要点 5-15 字。更长的要点仅当包含多个不可拆分的子约束。
禁止压缩的范围：事实性参考（工具返回格式、参数定义）、完整示例（示例本身就是解释）、首次出现的非自明术语。
本仓库模板示例：
Good (agent_system.md):
规则：
1. 只完成当前任务，不要做额外的事情。
2. 使用工具获取信息、执行操作。工具列表已在请求中提供，
如需更多工具请先调用 list_tools 查看可按需发现的工具，
然后调用 get_tool_schema 获取其完整参数定义。
3. 需要向用户提问或确认时，使用 ask_user 工具。
4. 任务完成后直接输出最终结果，简洁明了，不要废话。
注意：现有模板较为简洁，后续重构时按本节规则进一步压缩。
语气规则¶
直接、指令式、第二人称。用"你必须"、"你禁止"，不用"你可能想"、"请注意"、"最好能"。
Bad: 你可能想用 list_tools 查看一下有哪些额外工具。
Good: 必须调用 list_tools 查看可发现工具。
Bad: 请注意，任务结束时应当说明完成情况。
Good: 禁止无结果结束。成功输出结果，失败说明原因。
否定必须配正向替代（替代方案不显然时）。否则 禁止 X。 可独立使用。
抗收缩措辞： - 用"持续执行直到完成"，不用"高效使用 token"（后者触发模型过早放弃） - 用"遇到困难必须坚持"，不用"请尽力"（后者暗示可以放弃） - 禁止在提示词中提及 token 预算、会话限制、轮次上限（属于引擎层配置，模型不应关心）
Checklist¶
提示词定稿前逐项自查：
- [ ] 所有指令性语句使用关键词（必须/禁止/应当/避免/建议），无口语化祈使
- [ ]
<critical>规则在开头和结尾均出现（长提示 > 150 行时要求更严） - [ ] 战术级要点 5-15 字；更长要点有明确的多子约束理由
- [ ] 粗体标题后未重复正文内容
- [ ] 否定配正向替代（替代方不显然时）
- [ ] 无装饰性/凑数标签
- [ ] 无礼貌填充（"请"、"谢谢"、"麻烦你"）
- [ ] 无贿赂（"我会给你小费"）
- [ ] 无关门总结（"以上就是..."、"祝你顺利"）
- [ ] 验证路径明确（测试命令、lint 命令、类型检查），不用"复查你的工作"
- [ ] 模板变量使用
{{var}}语法，变量名在index.json中声明 - [ ] 提示词中未硬编码运行时数据（任务标题、聊天记录等），均通过
{{var}}注入