prompt-template-guide

# Prompt Template 指南 ## 数据边界 `config/prompts_config.json` 是所有 Prompt Template 的唯一配置源。顶层 `agents.{template_name}` 包含 `description`、`sections`、`preambles`，可选 `template_variables`。`data/system_prompt.json` 是 main Prompt 缓存， `data/prompt_history.json` 是修改历史，二者都不是编辑源。 Agent Definition 的 `prompt_template` 引用模板 key。涉及 Agent 类型或工具权限时加载 `agent-definition-guide`；涉及 Workflow 节点变量块时同时加载 `workflow-guide`。 ## 修改前检查 1. 用 `list_agent_types` 或 `GET /api/prompt-templates` 列出模板。 2. 用 `get_system_prompt(agent_type=...)` 或 `GET /api/prompt-sections?prompt_type=...&include_content=true` 读取完整 sections。 3. 检查 Agent Definition 对模板的引用；删除或改名必须先迁移引用。 4. 区分通用 section、仅聊天 section、仅 Workflow section 和类型级追加指令。 5. 明确要改变内容、顺序、启用状态还是变量声明，避免整份配置重写。 ## Section 字段 | 字段 | 作用 | |---|---| | `name` | 模板内唯一稳定标识；重命名使用专用 API | | `content` | Markdown 内容，可包含已注册占位符 | | `enabled` | 是否参与组装 | | `order` | 升序组装顺序 | | `workflow_only` | 只在 Workflow 上下文注入 | | `chat_only` | 只在非 Workflow 上下文注入 | | `cache_break` | 标记缓存边界 | | `cache_break_reason` | 解释为何此处需要缓存边界 | 不要同时把 `workflow_only` 与 `chat_only` 设为 true。缓存边界会影响成本和命中率，只有 内容确实随会话或运行频繁变化时才启用。 ## 占位符规则 Section 中的 `{{name}}` 不会自动读取任意 Workflow 变量。可渲染的值来自两类： - Core 注册的系统变量，如 `session_meta`、`workflow_overview`、`skills_section`； - 当前模板在 `template_variables` 中声明的自定义变量块。 Workflow Agent 节点通过 `node_params.template_values` 给自定义变量块赋值；变量块的值 本身可再引用 Workflow 变量。未注册占位符会保留为字面量，不能把未替换文本当成成功。 自定义变量声明保持最小：稳定 `key`、清晰展示名、用途说明和必要默认值。删除变量前搜索 全部 section 内容与 Workflow 节点 `template_values`。 ## 操作面 工具适合读取和精确更新已有 section： - `get_system_prompt(agent_type=...)` - `update_system_prompt(section_name=..., new_content=..., reason=..., agent_type=...)` - `list_agent_types` 完整管理使用 Web 或 API： | 操作 | API | |---|---| | 列出 sections | `GET /api/prompt-sections?prompt_type={type}` | | 读取配置与变量 | `GET /api/prompt-sections/config?prompt_type={type}` | | 更新单个/批量 | `PUT /api/prompt-sections/{name}`、`PUT /api/prompt-sections` | | 新增/删除 | `POST /api/prompt-sections`、`DELETE /api/prompt-sections/{name}` | | 重命名 | `POST /api/prompt-sections/{name}/rename` | | 更新变量声明 | `PUT /api/prompt-sections/template-variables` | | 重载 | `POST /api/prompt-sections/reload` | 所有 sections API 都要传正确的 `prompt_type`。使用更新工具时提供 `reason`，让 main 模板 修改进入历史。直接编辑配置仅用于项目级版本变更；编辑后必须 reload。 ## 设计原则 - 一个 section 只承担一个稳定职责，名称描述目的，不描述临时内容。 - 通用行为放模板，某个 Agent 类型的短差异放 Agent Definition `system_prompt_template`，单次任务上下文放任务消息。 - 通过结构和工具描述传递已知信息，避免在多个 section 重复同一规则。 - `order` 留出间隔不是必要设计；排序只依赖数值。 - 修改时优先 patch 单个 section，避免覆盖其他并发配置变更。 ## 验收清单 - JSON 可解析，模板 key 唯一，section name 在模板内唯一。 - Agent Definition 的每个 `prompt_template` 都存在。 - reload 成功，读取 API 返回更新后内容与顺序。 - 分别在 Chat 与 Workflow 上下文验证 `workflow_only/chat_only` 过滤。 - 自定义变量被实际渲染，未知占位符没有意外残留。 - main 模板修改后新建或刷新会话；不要只检查缓存文件。 ## 常见错误 - 把模板名与 Agent 类型强制同名：它们可以不同，但引用必须存在。 - 编辑 `data/system_prompt.json`：下次重建会覆盖。 - 在 section 中直接写 `{{workflow_input}}` 却未声明自定义变量块。 - 删除 section 后仍有工具或治理指令引用其语义。 - 为静态内容设置 `cache_break`，无收益地降低缓存效率。