oh-my-claudecode 中 analyst 智能体：规划前需求分析师的提示词设计与源码实现

analyst 是 oh-my-claudecode（Teams-first Multi-agent orchestration for Claude Code）多智能体体系中的一个"规划前顾问"（Pre-planning consultant），专职把已经确定的产品范围转换成可实施、可验收的需求描述，并在计划（planning）开始之前找出缺失问题、未定义护栏、范围风险与未验证假设。读完后你能理解：一份结构化子智能体提示词是如何用 XML 分节组织角色、约束、调查协议与输出契约的；disallowedTools、model 等 YAML frontmatter 字段是如何被运行时解析并强制执行的；以及 analyst 在 planner / architect / critic 交接链中的定位。

analyst 是什么：规划前的需求缺口探测器

agents/analyst.md 定义了 analyst 的完整提示词。它的文件头（YAML frontmatter）声明了四个关键字段：

字段	取值	含义
name	analyst	智能体标识，与文件名、注册键一致
description	Pre-planning consultant for requirements analysis (Opus)	一句话职责描述
model	opus	固定使用 Opus 模型，属于 HIGH 层
level	3	提示词中的能力层级标注
disallowedTools	Write, Edit	明确禁止写入类工具，保证只读

正文以 <Agent_Prompt> 为根节点，用 XML 分节组织。其核心立场可以概括为三条（对应文档中的 <Role>、<Why_This_Matters>、<Constraints> 三节）：

• 职责边界：analyst 负责"找出缺失的问题、未定义的护栏、范围风险、未验证的假设、缺失的验收标准和边缘情况"；它不负责市场/用户价值排序（那是产品决策）、代码分析（architect 的职责）、计划编写（planner 的职责）、计划评审（critic 的职责）。
• 价值主张：基于不完整需求做出的计划会产生偏离目标的实现。在规划前发现需求缺口，比在生产环境发现要便宜得多——analyst 的存在就是为了阻止"我以为你的意思是……"这类返工。
• 硬约束：只读（Write/Edit 被屏蔽）；聚焦"可实现性"而非"市场策略"，问"这个需求可测试吗？"而不是"这个功能有价值吗？"；从 architect 收到任务时按最佳努力分析并在输出中记录代码上下文缺口，而不是再退回 architect（禁止循环交接）。

交接方向也在约束中明确：需求收集完成后交给 planner；需要代码分析时交给 architect；计划已存在需要评审时交给 critic。

七步调查协议：需求分析的工作流

文档的 <Investigation_Protocol> 节给出了 analyst 处理任意需求输入时的标准流程，共七步：

1. 解析请求/会话，提取已陈述的需求；
2. 对每条需求逐一追问：是否完整？可测试？无歧义？
3. 识别那些被默认做出却未经验证的假设；
4. 划定范围边界：哪些在范围内，哪些被显式排除；
5. 检查依赖：开工之前必须存在什么前置条件？
6. 枚举边缘情况：异常输入、异常状态、时序条件；
7. 对发现结果排序：关键缺口在前，锦上添花在后。

配套的 <Success_Criteria> 规定了完成标准：所有未提出的问题都要被识别并解释为什么重要；护栏要给出具体建议边界；范围蔓延区域要配预防策略；每条假设都要有验证方法；验收标准必须可测试（pass/fail，而非主观判断）。

工具使用（<Tool_Usage>）仅允许两类只读动作：用 Read 检查被引用的文档或规格说明；用 Grep/Glob 验证被引用的组件或模式在代码库中确实存在。执行策略（<Execution_Policy>）说明运行时 effort 继承自父 Claude Code 会话，行为上的 effort 指引为"高"（彻底做缺口分析），当所有需求类别都被评估且发现已排序时停止。

结构化输出格式：Analyst Review 契约

<Output_Format> 节定义了 analyst 必须产出的报告骨架，这是它交付物的核心：

## Analyst Review: [主题]

### Missing Questions
1. [未被提出的问题] - [为什么重要]

### Undefined Guardrails
1. [需要划定边界的东西] - [建议的定义]

### Scope Risks
1. [容易蔓延的区域] - [如何预防]

### Unvalidated Assumptions
1. [假设] - [如何验证]

### Missing Acceptance Criteria
1. [成功是什么样] - [可度量的标准]

### Edge Cases
1. [异常场景] - [如何处理]

### Recommendations
- [规划之前需要澄清的事项优先级列表]

此外还有两条容易遗漏的输出规则：

• Open Questions 落盘约定（<Open_Questions> 节）：当分析暴露出"规划开始前必须有答案"的问题时，要在响应中以 ### Open Questions 小节输出，每条格式为 - [ ] [问题或待决策项] — [为什么重要]。analyst 本身不允许把这些问题写进文件（Write/Edit 被禁用），由编排器或 planner 代为持久化到 .omc/plans/open-questions.md。
• 最终消息契约（<Final_Response_Contract> 节）：最后一条助手消息就是交付物，必须完整包含上述结构化内容；不允许把实质分析留在早期消息或工具评论里；禁止以"done""complete""looks good"等无内容结尾收场——违反此契约即视为 agent 合约失效。

失败模式对照与 Good/Bad 示例

<Failure_Modes_To_Avoid> 节列举了 analyst 最容易犯的五个错误，以及文档给出的正/反示例：

1. 市场分析：评估"该不该做这个"而不是"能不能把这件事说清楚"——应聚焦可实现性；
2. 含糊的发现：只说"需求不清晰"是错误示范；正确示范是"createUser() 在邮箱已存在时的错误处理未定义：应返回 409 Conflict 还是静默更新？"——发现必须具体且带建议解法；
3. 过度分析：给一个简单功能找出 50 个边缘情况——应按影响面和出现概率排序；
4. 漏掉显而易见的问题：抓住了微妙边缘情况，却漏掉核心 happy path 根本没有定义；
5. 循环交接：从 architect 收到工作后又退回去——应处理并记录缺口。

文档中的对比示例：

• Good：请求是"Add user deletion（增加用户删除）"。analyst 指出：软删除还是硬删除未定义；用户文章的级联行为未提及；数据保留策略缺失；活动会话如何处理未说明——每个缺口都附建议解法。
• Bad：同样的请求，analyst 只回一句"考虑一下用户删除对系统的影响"——含糊且不可执行。

文末 <Final_Checklist> 还要求自检六项：每条需求是否检查了完整性与可测试性、发现是否具体且带建议解法、是否把关键缺口排在次要事项之前、验收标准是否可度量、是否避开了价值判断、open questions 是否出现在响应的 ### Open Questions 小节。

源码实现：从 Markdown 到运行时智能体配置

提示词文件只是"原料"，src/agents/analyst.ts 才把它注册成可被编排器调度的智能体。关键实现有三层：

1. 注册与元数据。 analystAgent 通过 loadAgentPrompt('analyst') 加载 agents/analyst.md 的内容作为 prompt，并固定 model: 'opus' / defaultModel: 'opus'。配套的 ANALYST_PROMPT_METADATA 声明了路由元数据：

export const ANALYST_PROMPT_METADATA: AgentPromptMetadata = {
  category: 'planner',
  cost: 'EXPENSIVE',
  promptAlias: 'analyst',
  triggers: [
    {
      domain: 'Pre-Planning',
      trigger: 'Hidden requirements, edge cases, risk analysis',
    },
  ],
  useWhen: [
    'Before creating a work plan',
    'When requirements seem incomplete',
    'To identify hidden assumptions',
    'Risk analysis before implementation',
    'Scope validation',
  ],
  avoidWhen: [
    'Simple, well-defined tasks',
    'During implementation phase',
    'When plan already reviewed',
  ],
};

这里的 useWhen/avoidWhen 会被 src/agents/utils.ts 中的 buildUseAvoidSection() 和 buildKeyTriggersSection() 自动渲染进编排器的委托表（delegation table），即主智能体的系统提示词中会出现"Pre-Planning → analyst: Hidden requirements, edge cases, risk analysis"这样的触发指引。元数据的类型定义在 src/agents/types.ts：AgentPromptMetadata 包含 category（planner 属于战略规划类）、cost（FREE | CHEAP | EXPENSIVE 三档，analyst 为 EXPENSIVE）、triggers 等字段。

2. 提示词加载与安全校验。 loadAgentPrompt()（src/agents/utils.ts）的加载链路值得注意：

• 先用正则 /^[a-z0-9-]+$/i 校验智能体名，阻止 ../../etc/passwd 之类的路径穿越；
• 优先读取构建期注入的 __AGENT_PROMPTS__ 内嵌映射（esbuild 打 CJS 包时替换），不可用时回退到从包根目录的 agents/ 文件夹运行时读取文件；
• 读取后调用 stripFrontmatter() 剥掉 --- 之间的 YAML 头——也就是说，frontmatter 是给运行时的"配置"，正文才是给模型的"提示词"，二者在同一文件内分离。

3. disallowedTools 的解析与执行。 agents/analyst.md 里的 disallowedTools: Write, Edit 并不是装饰。src/agents/definitions.ts 的 getAgentDefinitions() 在汇总全部智能体时执行：

const disallowedTools = agentConfig.disallowedTools ?? parseDisallowedTools(name);

即优先取 TS 配置里显式声明的 disallowedTools，否则调用 parseDisallowedTools()（src/agents/utils.ts）从 Markdown frontmatter 中解析 disallowedTools: 行并拆成逗号分隔列表——analyst 的 Write, Edit 就来自这里。src/agents/utils.ts 还提供 createAgentToolRestrictions(blockedTools)，把工具名转小写后生成 { tools: { write: false, edit: false } } 形式的限制映射，可展开进智能体配置，从机制上落实了提示词里"Read-only"的承诺。

Open Questions 持久化链路

analyst 提示词中"由编排器或 planner 代为持久化到 .omc/plans/open-questions.md"这句话在代码里有对应实现：

• src/agents/utils.ts 导出常量 OPEN_QUESTIONS_PATH = '.omc/plans/open-questions.md'，并提供 formatOpenQuestions(topic, questions) 生成形如 ## <topic> - <date> 加 - [ ] 问题 — 原因 条目的 Markdown 片段，供编排器追加写入；
• src/config/plan-output.ts 将 open-questions 定义为一种 PlanOutputKind，测试 src/config/__tests__/plan-output.test.ts 断言 resolveOpenQuestionsPlanPath() 恰好返回 .omc/plans/open-questions.md。

这意味着"analyst 只产出、编排器落盘"是一个被类型、常量和测试共同约束的约定，而不是提示词里的口头承诺。

模型分层：为什么 analyst 固定用 Opus

docs/shared/agent-tiers.md 是全仓库智能体分层的唯一事实来源（single source of truth）。在其 Tier Matrix 中：

Domain	LOW (Haiku)	MEDIUM (Sonnet)	HIGH (Opus)
Pre-Planning	-	-	analyst

任务类型选择表也明确："Pre-planning analysis → analyst → HIGH"。这解释了 frontmatter 中 model: opus 的由来：需求缺口分析需要对整份需求的隐含依赖做全局推理，属于典型的 HIGH 层复杂任务，且 Pre-Planning 域只有 Opus 一档，没有更便宜的降级选择。作为对照，src/agents/types.ts 的 getDefaultModelForCategory() 按类别给出默认模型（如 advisor 类默认 opus、orchestration 类默认 sonnet），但 analyst 通过 model/defaultModel 显式指定，不依赖类别默认值。

在多智能体交接链中的位置

analyst 的提示词约束（"Hand off to planner / architect / critic"）与路由配置互相印证：

• 在 src/features/delegation-routing/types.ts 的 ROLE_CATEGORY_DEFAULTS 中，analyst 被列为 Advisory roles (high complexity) 一档，与 architect、planner、critic 并列，默认映射到同名 Claude 子智能体；
• 在类型系统中 analyst 的 category 为 planner（见 src/agents/types.ts 的 AgentCategory 注释："Strategic planning"）；
• 它的三个交接对象在 agents/ 目录下各有对应的提示词文件：agents/planner.md、agents/architect.md、agents/critic.md，构成"需求分析（analyst）→ 代码分析（architect）→ 计划编写（planner）→ 计划评审（critic）"的规划前流水线。

从这套设计可以推断，oh-my-claudecode 把"需求澄清"从规划流程里独立出来，靠三个机制保证 analyst 不越界、不偷懒：工具层禁止写操作（disallowedTools + 工具限制映射）、提示词层规定结构化输出与最终消息契约、路由层用 metadata 的 useWhen/avoidWhen 引导编排器只在"写计划之前、需求不完整、要做风险/范围验证"时派发任务，在"任务简单明确、实施阶段、计划已评审"时避开它。

小结

agents/analyst.md 展示了一种可复制的子智能体定义范式：YAML frontmatter 承载运行时配置（模型、禁用的工具），XML 分节的正文承载行为契约（角色、成功标准、调查协议、输出格式、失败模式、自检清单），而 src/agents/analyst.ts、src/agents/utils.ts、src/agents/definitions.ts 负责把这两部分解析成受约束的运行时智能体。如果你要在自己的多智能体系统中添加一个"规划前顾问"，analyst 的提示词结构（七步调查协议、六段式 Analyst Review 输出、Final Response Contract、Open Questions 落盘约定）以及"提示词声明只读 + 代码强制工具禁用"的双层防护，都是可以直接参考的实现样本。