Agent-System-Documents/docs/guides/prompt-library-design.md

提示词库设计与扩展指南

状态：active（feature/prompt-library 交付）｜维护对象：modules/backend/internal/prompts/

本指南总结 Agent-System 提示词体系的设计思路，供后续新增/修改提示词时遵循。 方法来源：Claude Code 提示词体系的分层组装与技能化模式（2026-04 目录分析）， 结合本系统的画像/设置/意图闸门/命令总线既有机制落地。

1. 分层模型：提示词不是一段话，是一组有职责的块

层	职责	组装时机	示例
base	常驻基座：身份/行为/谨慎/工具/风格	每次 run，画像可裁剪	base.identity
env	动态环境事实（占位符）	每次 run，随运行填充	env.runtime
task	任务技能：有触发条件	命中才注入（同层取优先级最高）	task.doc-minutes
agent	子代理/小队角色人设	派生 run 时取用	agent.sub.explore
tool	工具描述文案（模型侧）	声明工具时覆盖注册表默认	tool.knowledge_search
aux	辅助模板（压缩/标题/解释）	功能接线时取用（可先入库）	aux.session-compact
style	表达变体	画像显式引用才启用	style.explanatory

设计动机：技能塞基座 = 永久占用上下文 + 干扰无关任务。分层后基座保持小而稳， 技能按需进场，风格可选叠加——上下文预算花在刀刃上。

2. 模块设计八法（写一个好模块的检查清单）

1. 角色定义：第一句说清"你是谁、对什么负责"。子代理尤其要写边界 （"你是规划者，不是实现者"）。
2. 权限/只读约束：凡不该做的事显式禁止（探索代理：不写入不修改）。 约束写在提示里 + 机制上配工具白名单，双层防线。
3. 输出契约：结构化产出必须定义形态（几个部分、各含什么）。 契约同时是验收标准——人可以按契约检查交付。
4. 强制裁决格式：程序要消费的结论给固定格式（验证代理以 VERDICT: PASS|FAIL|PARTIAL 结尾；标题生成只输出 JSON）。
5. 反模式禁令：点名常见错误（"不要把发言当决议"、"不要把外部知识冒充文档内容"、 "不要为简短丢信息"）。禁令比正面要求更能纠正模型默认行为。
6. 失败与缺失的表述规则：查不到/原文没有时怎么说（"文档未提及"、列出已检索范围）， 防止编造兜底。
7. 详略授权：明确"默认完整、压缩需用户明示"还是相反——输出质量的直接杠杆。
8. 防污染：过程性指令不得泄漏进产出（压缩摘要不提压缩这件事本身）。

3. 触发设计

• intent：关键词子串匹配。关键词要任务特有（"纪要"好于"会议"）， 避免日常闲聊误触发。文档类技能加 requiresAttachments: true 门槛。
• command：/xxx 显式命令。命令是显式用户意图，不受附件门槛约束。 技能命令出现在 / 菜单（source=prompt-skill），发送时跳过命令总线走正常 run。
• attachment：本轮有附件（可叠加关键词）。
• manual：永不自动触发，仅画像引用/程序显式调用。
• 多命中取舍：task 层同轮多技能命中时注入优先级（priority，大者胜）最高者， 其余记录让位（可观测）。同优先级保持库 ID 序。

4. 文件格式与命名

库文件：internal/prompts/library/<layer>-<name>.md，frontmatter + 正文：

---
id: task.doc-minutes          # <layer>.<name>，与文件名一致
layer: task
version: 1                    # 文案有实质变更时 +1（触发用户副本 drift 提示）
title: 会议纪要生成
description: 一句话用途（/ 菜单与设置界面展示）
priority: 70
requiresAttachments: true
outputContract: |
  多行输出契约
triggers:
- kind: intent
  keywords: 纪要, 会议记录
- kind: command
  command: /minutes
---
正文：给模型的指令（Markdown）。

frontmatter 刻意最小（无 YAML 依赖，解析器在 parse.go）；正文即 body； {{date}} {{weekday}} {{model}} {{attachments}} 占位符仅 env 层使用。

5. 覆盖链与版本

builtin（embed 文件）→ user（DB prompt_modules 表）。 用户副本记录 basedOnVersion；内置版本前进后副本标记 drifted（提示、不强制覆盖）。 删除用户副本即回到内置。改内置文案：改文件 + version+1 + 走 PR 评审。

6. 组装与可观测

prompts.Service.ResolveSystem(profile, triggerCtx, env) 产出多段 system 消息： 基座（画像 promptModules 引用或缺省 base+env）→ 命中技能 → 画像 systemPrompt 兼容段。 每次组装产出命中记录，注入 ctxasm Report（"上下文构成"面板可见）： prompt(task.doc-minutes v1 · intent:纪要)、skill-yield(task.summarize · superseded-by:...)。 改了提示词，观测里能看到它进没进场——这是排查提示问题的第一入口。

7. 新增一个技能的步骤

1. 写 library/task-<name>.md（对照八法检查；定触发词与优先级； 文档类加附件门槛；提供 / 命令别名）。
2. 若需新占位符：EnvData 加字段 + resolvePlaceholders 加映射。
3. 测试：prompts_test.go 加触发用例（命中/未命中/门槛/让位）； TestDefaultLibraryParses 自动覆盖格式合法性。
4. 观测验证：真实 run 的上下文构成面板确认 prompt(task.xxx · 命中原因)。
5. 若是程序消费的裁决类输出：消费端同步解析逻辑 + 固定格式测试。

8. 反模式（不要这样做）

• ❌ 把技能指令写进 base 或画像 systemPrompt（永久占上下文、不可触发观测）。
• ❌ 提示词内联在 Go 代码里（不可评审、不可覆盖、发版才能改）。
• ❌ 无 version 的文案变更（用户副本漂移不可知）。
• ❌ 触发词太泛（"文件"、"帮我"）造成误触发。
• ❌ 只有正面要求没有反模式禁令与缺失表述规则（模型会用默认行为填空）。

9. 外部提示词目录的移植判定（以 Claude Code 目录为例）

借鉴外部提示词体系时，逐条判定能否入库，标准只有两条（满足其一）：

1. 有承载机制：我们的系统里存在该提示词描述的对象（工具/角色/模式/功能）， 注入后有真实消费方。
2. 有可挂接的未来功能位：功能虽未实现，但属于系统演进的合理档位—— 以 aux/agent 模板先行入库，frontmatter 描述注明接线点。

两条都不满足的，不入库：给不存在的工具写描述、为不存在的模式写行为规范， 一旦被组装注入就是错误指引，死数据比缺数据更糟。

按此标准对 Claude Code 提示词目录的处置（46 个已入库 + 明确不移植清单）：

目录条目	处置	落点
1.1-1.2 身份/简介、2.1 双用途安全	合并	base.identity
1.4 任务执行	移植	base.behavior
1.5 谨慎操作	移植	base.caution
1.6 工具使用	移植	base.tools
1.7-1.8 语气/输出效率	合并	base.style
1.9 环境信息	移植	env.runtime
1.3 系统行为、1.10 hooks/临时目录/token 预算	不移植	描述 Claude 运行时机制（权限模式/system-reminder/hooks/自动压缩），我们无对应机制；机制落地时按 env/base 块补
2.2 卧底模式	不移植	隐藏 AI 身份的提交伪装；无提交代理场景，且与"如实报告"基座冲突，需独立授权框架
3.1 自主模式（Sleep/tick）	不移植	需常驻调度器，无该运行档
3.2 协调器模式	语义已承载	agent.squad.* + tool.squad_orchestrate
3.3 队友通信 SendMessage	不移植	无该工具
4.1-4.5 通用/探索/规划/验证	移植	agent.sub.*
4.6 向导	移植	agent.docs-wizard
4.7 记忆提取	移植	agent.memory-extractor
5.9 WebFetch、5.10 WebSearch	移植	tool.tavily_search / tool.web_search（后端经 Agent-Native TavilyProvider 注册；未配置密钥时不注册，模块不生效）
5.x 其余工具描述（13 个）	按需移植	仅本系统真实存在的工具；其余（Bash/FileRead/FileWrite/FileEdit/Glob/Grep/Sleep/Skill/AskUserQuestion/NotebookEdit/Brief）不移植——无对应工具
6.1 会话压缩	移植	aux.session-compact
6.2 Session Memory	移植	aux.session-memory
6.3 Magic Docs	移植	aux.magic-docs
7.1-7.2 输出风格	移植	style.explanatory / style.learning
8.1 标题生成、8.2 命令解释	移植	aux.title-gen / aux.command-explain
8.3 伴侣气泡	不移植	UI 功能不存在
8.4 Chrome 自动化	不移植	无浏览器工具
附录 组装架构	已实现	prompts.Service 代码本身（不是提示词数据）

新增系统的真实机制（新工具、新角色、新档位）时，回头检查此表补齐对应模块。