oh-my-claudecode Planner 角色提示词契约解析：Prompt SSOT 单源生成与规划角色运行规范

本文面向使用或二次开发 oh-my-claudecode（基于 Claude Code 的多 Agent 团队协作编排框架）的开发者，解读 Tier-0 Planner 角色的系统提示词投影文件 generated/prompt-ssot/role-planner.md。本文会讲清该文件在“提示词单一事实源（Prompt SSOT）”体系中的生成位置、六个章节的语义边界、只读规划约束的强制执行方式，以及它如何与 Planner Agent 运行时配置 对接，帮助读者理解并正确使用这一整套提示词工程资产。

一、文件定位：一份“由机器生成”的角色投影（Projection）

打开 role-planner.md，文件头部是一段被注释包裹的生成元数据：

PROMPT-SSOT:GENERATED
schemaVersion: 1
projection: role-planner
sourceRevision: 2026-08-13.1
overlay.provider: none
overlay.modelTier: none
sha256: c155324ee8af33b16495e8dd29b8ce5faad2f2d3e32ff5cbd9cf5e9ef5bc17b6
Regenerate: npm run prompt-ssot:build. Do not edit by hand.

这段头信息明确了两点：

1. 该文件不可手改，必须通过 npm run prompt-ssot:build 重新生成；
2. 它是一个 role-planner 投影——即从“提示词单一事实源”仓库中选取若干规范章节、按确定性顺序拼装出来的产物。

oh-my-claudecode 的提示词体系由四处源码资产构成（设计文档见 docs/design/issue-3704-prompt-ssot/README.md）：

• sections.ts：每个规范章节只在此“author 一次”，并带 id、kind、owner、version 属性；
• manifest.ts：声明 schemaVersion、sourceRevision、必选章节、投影目录与回滚历史；
• compose.ts：确定性拼装器，负责章节选择、排序、拼接与哈希；
• digest.ts：负责文本归一化（CRLF→LF、去行尾空白、空行折叠）与 SHA-256 摘要计算。

在 manifest.ts 的投影目录中，role-planner 与 role-executor、role-reviewer、role-verifier 由同一个工厂函数生成（见 manifest.ts），它们与 coordinator 投影一起构成 Tier-0 角色投影集合。设计文档指出，这四个 role-* 投影 id 与 src/workflow/registry.ts 中的 WORKFLOW_ROLES 一一对应，是工作流注册表在提示词侧的镜像。

二、role-planner 投影由哪些 SSOT 章节拼成

对照 manifest.ts 可以看到，每个角色投影固定选择 6 个章节：

章节 id	kind	对应正文小节
policy/operating-principles	policy	Operating Principles
task-contract/verification	task-contract	Verification
task-contract/execution-protocols	task-contract	Execution Protocols
safety/hard-boundaries	safety	Safety Boundaries
role/planner	role-delta	Role: Planner
output/evidence-contract	output-contract	Output Contract

值得注意的差异点是：coordinator 投影独享 policy/delegation-rules、policy/model-routing、policy/commit-protocol、policy/cancellation 以及两个工作流章节（Deep Interview、Ralplan），而 role-planner 等角色投影刻意不含这些内容（对比可见 coordinator.md）。这符合角色分工原则——执行细节委托规则属于协调者职责，规划者只需聚焦“如何规划与验证”。

manifest.ts 同时声明了两个必选章节：

requiredSections: ['policy/operating-principles', 'safety/hard-boundaries'],

如果任何投影在拼装时缺失这两个章节，compose.ts 会在编译期直接抛出 PromptSsotError，即“必选章节 fail closed”。

三、确定性拼装：为什么每次生成都逐字节一致

compose.ts 的 composeProjection 函数是整套体系的引擎。它按以下步骤工作：

1. selectSections 依据 manifest 的投影定义收集章节 id，并附加 overlay 章节（若有）；
2. 按 (kind 排序位, section id) 做规范排序——排序只依赖 kind 等级与 id，与 manifest 中的声明顺序无关；
3. 用单个空行连接各章节正文并经 normalizePromptText 归一化；
4. 对归一化正文计算投影级摘要，并对每个章节计算 id@version 绑定摘要；
5. 把 schema 头信息与正文拼成最终 fileText。

这意味着：同一份 manifest + sections + overlay，无论何时何地运行，输出文本与摘要都逐字节一致。正文第一行那句 “Do not edit by hand” 并非装饰——项目同时提供构建门禁，防止任何手工改动破坏这一不变量。

四、六个章节的语义深读

1. Operating Principles：协作与克制的最低纲领

该章节来自 policy/operating-principles（正文源码见 sections.ts），是 coordinator 与所有角色投影共享的“公共底座”，共 8 条：

• Delegate specialized or tool-heavy work to the most appropriate agent.（把专业化/重工具任务委托给最合适的 Agent。）
• Prefer clear evidence over assumptions：结论前先验证，证据优先于假设。
• Choose the lightest-weight path：在直接执行、MCP、委托 Agent 之间选择“最轻但保住质量”的路径。
• Consult official documentation：使用 SDK、框架或 API 前先查官方文档。
• Prefer deletion over addition：能删不加。
• Reuse existing utilities and patterns：先复用现有工具与模式，再谈引入新东西。
• Do not add new dependencies without an explicit request or approval.（未明确请求/批准不得新增依赖。）
• Keep diffs small, reversible, and easy to review.（保持差异小、可回滚、易评审。）

对 Planner 而言，这 8 条定义了它的“人格底座”：规划角色同样受最小改动与证据优先约束，规划产物本身也必须保持轻量。

2. Execution Protocols：并行与串行的调度纪律

规划者必须遵守四条协议：

• 宽泛且目标不明确的需求 → 先探索，后规划（Explore first, then plan）；
• 独立任务并行执行，有依赖任务串行执行；
• 编写与评审必须分为独立 pass，同一 pass 内不得自我批准；
• 安装、构建、测试等耗时操作放到后台执行。

这条章节对 Planner 的直接影响是：面对“broad requests with no clear target”，Planner 必须先完成探索（exploration）再产出计划，这正好与 planner.ts 元数据中 “Comprehensive work plans, interview-style consultation” 的触发场景互相印证。

3. Verification：完成声明前必须自证

Verification 章节是全文的“硬门槛”，原文定义了完整的闭环：

Verify before claiming completion: identify what proves the claim, run the verification, read the output, then report with evidence. If verification fails, keep iterating rather than reporting incomplete work. Before concluding, confirm: zero pending tasks, tests passing, zero errors, verification evidence collected.

它拆解为四个可执行动作：① 找到能证明该断言的证据 → ② 实际运行验证 → ③ 读取输出 → ④ 带着证据汇报。验证失败时必须持续迭代而非上报半成品；收尾前必须确认三件事：无遗留任务、测试通过、零错误、验证证据齐备。

4. Safety Boundaries：advisory 与 hard checks 的双轨安全模型

这是全文最具体系设计意味的章节，定义了两种安全检查的默认语义：

• Advisory checks（建议性检查）fail open：仅产生“有界的、可见的警告”，绝不阻塞日常例行工作；
• Hard checks（硬性检查）fail closed，且仅限五类场景：secrets/privacy（密钥与隐私）、destructive mutation（破坏性变更）、release/publish authority（发布权限）、proven corruption or integrity risk（已证实的损坏或完整性风险）、security boundaries（安全边界）；
• 迁移期未知故障默认归为 advisory，且必须在任何旧机制移除前完成归类（classify before any legacy removal）。

这一设计保证了“例行工作不被误伤，高危操作不被放过”——轻风险走可见警告，重风险一律拒绝放行。

5. Role: Planner：规划通道与只读边界

角色增量章节是本文件区别于其他投影的核心：

You are the planning lane. Sequence work into ordered, verifiable steps; flag risks, dependencies, and rollback boundaries. Planning output is read-only: never edit product source, run mutating commands, commit, push, or open PRs before explicit execution approval.

它定义了 Planner 的两条硬约束：

1. 职责是排序：把工作编排成“有序、可验证的步骤”，并显式标记风险（risks）、依赖（dependencies）与回滚边界（rollback boundaries）；
2. 产物只读：在获得明确的执行授权前，禁止修改产品源码、运行变更类命令、提交（commit）、推送（push）或开 PR。

“Planning output is read-only”是规划与执行分离的授权边界在提示词层的落地。对照 planner.ts 中 Agent 描述 “NEVER implements - only plans”，以及 role-executor.md 中 Executor “implement the assigned bounded slice end to end” 的角色定义，可以清晰看到：Planner 负责设计“边界切片（bounded slice）”，Executor 负责实施它——二者通过授权边界解耦，绝不越权。

6. Output Contract：最终汇报的内容契约

无论规划还是执行，最终报告必须包含四要素：

• changed files：变更过的文件；
• verification commands with their actual results：验证命令及其实测结果；
• simplifications made：做了哪些简化；
• remaining risks：剩余风险。

并明文禁止三类行为：把部分工作包装成完成态（present partial work as complete）、隐瞒失败测试（suppress failing tests）、伪造输出（fabricate outputs）。这份契约同时出现在 coordinator 与全部四个角色投影的末尾（参见 coordinator.md），是全局统一的汇报格式。

五、运行时侧：Planner Agent 的元数据与路由

提示词投影只是“一纸契约”，运行时行为由 Agent 配置驱动。src/agents/planner.ts 提供了配套的 plannerAgent 配置对象：

• description：Strategic planning consultant. Interviews users to understand requirements, then creates comprehensive work plans. NEVER implements - only plans.
• 模型选择：model: 'opus'，defaultModel: 'opus'——从配置看，规划任务默认路由到高能力模型；
• 成本档位：cost: 'EXPENSIVE'——元数据明确标注规划是高成本操作；
• promptAlias：planner。

其触发矩阵（PLANNER_PROMPT_METADATA，见 planner.ts）对何时启用 Planner 给出了精确指导：

维度	内容
triggers	战略规划域：综合性工作计划、访谈式需求澄清
useWhen	需要规划的复杂特性；需求需访谈澄清；创建综合工作计划；大型实现开始前
avoidWhen	简单直接的任务；本应直接开始实现的任务；已有现成计划时

最后一条 “avoidWhen: When a plan already exists” 与 Execution Protocols 的 “Explore first, then plan” 构成闭环——避免重复规划，已有计划直接进入执行。这也呼应 manifest 中对角色投影 “Tier-0 role prompt projection” 的定位（manifest.ts）。

六、从生成到门禁：如何维护这份提示词资产

若你希望本地复现或验证这份投影，项目提供了三条命令与配套测试：

1. 重新生成全部投影：npm run prompt-ssot:build（按文件头注释，重新生成 generated/prompt-ssot 下的全部 md）；
2. 新鲜度检查：npm run prompt-ssot:check——任一已提交投影的摘要/文本不匹配，或有游离文件，命令即以非零码退出，防止过期投影混入仓库；
3. 度量取证：npm run prompt-ssot:measure——由 scripts/measure-prompt-ssot.ts 输出机器可读的提示词度量证据。

单元测试方面，src/agents/prompt-ssot/tests/prompt-ssot.test.ts 覆盖了投影拼装的确定性行为——例如同一个 role-planner 投影在叠加 { provider, modelTier } overlay 后仍能保持规范文本不变（测试中直接以 role-planner 作为基准投影对象进行组合校验，见该测试文件中对 composeProjection(PROMPT_SSOT_MANIFEST, PROMPT_SECTIONS, 'role-planner', ...) 的调用）。

设计文档记录的实测结果也说明了这套单源体系的收益（数据来自 measurements.json）：与旧的 3 份 CLAUDE.md 投影加 19 份 agents/*.md 的语料相比，SSOT 章节语料将重复 token 从 15,888 降至 136（约减少 99.14%），重复子句比率从 0.9662 降至 0.3413，组合投影与已提交投影的最大漂移为 0。

七、小结：把 role-planner.md 当作一份“契约快照”来读

综合来看，role-planner.md 不是一份随意的提示词草稿，而是 oh-my-claudecode “Teams-first 多 Agent 编排”在规划通道上的契约快照：公共原则保证各角色行为一致，Verification 章节强制证据闭环，Safety Boundaries 用 fail-open/fail-closed 双轨划分风险处置，Role 章节锁定只读规划与授权边界，Output Contract 统一汇报格式。源码侧，manifest.ts 定义“选哪些章节”，compose.ts 保证“每次生成的字节一致”，sections.ts 保证“每条规范只写一次”，planner.ts 则把契约绑定到具体模型与触发策略。理解这条“章节 → 拼装 → 投影 → 运行时 Agent”的完整链路，是正确使用与扩展 oh-my-claudecode 提示词资产的前提。