OmX `$analyze` 技能实战：基于证据的只读深度仓库分析工作流

$analyze 是 oh-my-codex（OmX）内置的只读深度分析技能，用于回答仓库问题并输出带置信度评级的综合结论、精确文件引用与证据/推断边界。它适用于需要跨文件追因、解释架构行为、评估影响与权衡、并在任何改动前确认信心的场景；本文从技能文档（plugins/oh-my-codex/skills/analyze/SKILL.md）出发，结合仓库源码、路由注册与契约测试，完整讲解其触发方式、执行方法、输出契约与停止条件，帮助你把它当作可复现、可审计的"仓库取证"工具来使用。

一、技能定位：分析不是实现，证据不是猜测

$analyze 的核心定义只有一句话：用 grounded（有据可依）的只读证据回答仓库问题，解释代码"最可能在说什么"（Explain what the code most likely says），而不是把分析变成实现或通用修复规划。这一原则被契约测试固化在 src/hooks/tests/analyze-skill-contract.test.ts 中：技能文件必须声明 grounded, read-only evidence、do not turn analysis into implementation or generic fix planning、Do not use it for edits, implementation。

在 OmX 的整体工作流里，$analyze 属于"理解"（understand）阶段而非"执行"（execute）阶段。顶层操作契约 templates/AGENTS.md 明确定义默认工作流为 understand -> execute -> verify -> report，而 $analyze 正是该链条中理解环节的专用技能；技能文档也明确指出，共享的操作、委派、状态、hook、团队、取消与验证不变量统一以 templates/AGENTS.md 为准，技能本身不重复这些规则。

二、何时使用 $analyze：触发边界

适用场景

根据 plugins/oh-my-codex/skills/analyze/SKILL.md 的 Use when 定义，满足以下任一条件即应启用：

• 用户需要因果、架构、行为、影响或权衡层面的解释；
• 回答需要追踪多个文件或边界，或在多个可能的解释之间排序；
• 用户在做出任何改动前需要置信度与具体证据。

不适用场景

以下情况不要使用 $analyze：

• 编辑或实现代码；
• 制定新产品计划；
• 单个文件的简单查找；
• OmX 团队运行时（team-runtime）的操作。

判断"单文件查找"与"深度分析"的分界，正是技能存在的意义：如果只需定位一个符号或读一个文件，直接用常规仓库检索即可；只有当问题横跨多个文件、存在竞争性解释、或结论会影响后续改动方向时，才需要 $analyze 的排序式综合。

三、触发机制：$analyze 与 investigate 关键字路由

在 OmX 中，$analyze 通过原生 hook 的关键字检测自动路由。路由注册表位于 src/hooks/keyword-registry.ts，定义如下：

关键字	目标技能	优先级	引导语
$analyze	analyze	7	Activate deep analysis workflow
investigate	analyze	7	Activate deep analysis workflow

两个触发词的优先级同为 7，低于 $autopilot（10）、$deep-interview（8）、$ralplan（11）等编排型技能，属于"按需激活"的工作流技能。值得注意的是，templates/AGENTS.md 的关键字兜底规则明确了两点：

1. 裸技能名不会自动激活技能——仅仅提到 "analyze" 这个单词不会触发 $analyze，技能名激活需要显式的 $skill 调用形式；
2. 自然语言路由短语可以映射到工作流——例如 analyze / investigate → $analyze，用于只读深度分析。

关键字检测的单元测试覆盖了这一行为（src/hooks/tests/keyword-detector.test.ts）：$analyze $analyze root cause 会被去重为单个 analyze 技能，please run $team and then analyze the result 不会把 "analyze" 误判为独立触发，且裸词 "analyze" 不触发技能。

路由契约测试 src/hooks/tests/analyze-routing-contract.test.ts 进一步保证了两件事：一是 AGENTS 模板与根级 keyword registry 中必须同时存在 analyze、investigate、$analyze 三者的路由行；二是 analyze 不能被路由到 prompts/debugger.md 或兼容别名——这是历史演进中刻意划出的边界，确保深度分析走独立的 $analyze 技能，而不是被调试器提示词"吸收"。

四、执行方法：五步证据导向的探测流程

技能文档 Inputs and method 定义了五步方法，核心思想是"用最小的探测面回答问题"：

1. 重述问题并定义有证据支撑的范围（Restate the question and define the evidence-backed scope）——先明确"到底要回答什么"以及"哪些边界之外不回答"；
2. 识别最可能回答问题的少量文件、测试、配置与文档（Identify the smallest files, tests, configs, and docs）——优先选择最小集合，而非漫无目的地扫全库；
3. 先读直接代码路径与契约，只在必要时追踪边界（Read direct code paths and contracts first; trace boundaries only as far as needed）——直接证据优先，边界追踪按需收敛；
4. 比较竞争性解释，按支持强度排序，并标记未决点（Compare competing explanations, rank them by support, and mark unresolved points）——不要只给出单一答案，而是给出排序后的候选集；
5. 证据足够时立即停止；否则指出能消除剩余不确定性的最小只读探测（Stop when the question is answered with sufficient evidence, or name the smallest read-only probe）——把"下一步该查什么"也作为输出的一部分。

契约测试 analyze-skill-contract.test.ts 对以上方法逐条断言，确保技能文件持续保留"有界调查方法 + 排序综合输出"的完整骨架，任何删减都会导致测试失败。

五、证据纪律：Evidence / Inference / Unknown 三分类

技能的核心价值在于显式的证据分级。每个实质性论断必须标注为三类之一（Evidence discipline）：

• Evidence（证据）——直接由代码、测试、生成产物、配置或文档展示的事实；
• Inference（推断）——基于已引用证据得出的推理结论；
• Unknown（未知）——仓库证据未能确定的内容。

纪律要求包括：优先使用直接路径与独立佐证，而非上下文线索；绝不把猜测包装成证据或推断；绝不夸大确定性（never overclaim certainty）。这条纪律在测试中被显式锁定（analyze-skill-contract.test.ts），包括 Never present guesses as evidence or inference 与 never overclaim certainty 两句原文。

六、输出契约：先答问题，再给排序综合

$analyze 的输出有固定形状（Output contract），要求先直接回答被问的问题，然后按以下结构展开：

Question（问题重述）

简要重述被分析的问题，确保结论与提问对齐。

Ranked synthesis（排序综合）

Rank	Explanation	Confidence	Basis
1	...	High / Medium / Low	strongest supporting evidence
2	...	High / Medium / Low	why it trails
3	...	High / Medium / Low	why it remains possible

表格的设计意图明确：Rank 1 是支持证据最强的解释；Rank 2 说明它为什么排在后面；Rank 3 说明为什么它仍有可能。每一行都必须给出置信度（High / Medium / Low）与依据，禁止无依据的并列。

Evidence（证据）

以 path/to/file:line-line 形式列出直接观察与佐证观察，例如：

• src/hooks/keyword-registry.ts:18-19 — 直接观察：$analyze 与 investigate 均路由至 analyze 技能，优先级 7。
• src/hooks/__tests__/analyze-routing-contract.test.ts:39-49 — 佐证观察：analyze 不允许路由到 debugger 提示词。

Inference（推断）

• 证据最强地暗示了什么结论；
• 为什么更弱的备选解释被降级。

Unknowns / limits（未知项与局限）

• 仓库未能确立什么；
• 有需要时，指出下一个具有区分度的只读探测（next discriminating read-only probe）。

七、停止条件：证据边界即行动边界

Stop conditions 给出了三条硬性约束：

• 不编辑文件、不运行实现通道、不给出证据无法支撑的建议；
• 答案与置信度边界确定后立即停止搜索，不做无谓的继续检索；
• 证据不足时明确报告局限，而不是制造确定性的假象。

这与 OmX 顶层"验证后才声称完成"（Verify before claiming completion）的验证循环（templates/AGENTS.md）一脉相承：$analyze 的产物本身就是一份可验证的证据清单，任何后续实现决策都应建立在这份清单之上。

八、技能的组织与安装形态

analyze 技能以 SKILL.md 形式存在于仓库中的两个位置，由插件镜像机制保持同步：

• 主目录技能：skills/analyze/SKILL.md（仓库根级 skills 目录）；
• 插件分发副本：plugins/oh-my-codex/skills/analyze/SKILL.md。

在技能目录清单（src/catalog/manifest.json）中，analyze 被归类为 shortcut（快捷工作流） 类别，状态为 active，与 $autopilot、$ralplan 等"planning"类技能区分——它不产生规划产物，而是按需激活的分析快捷通道。安装后，技能文件会被部署到 ~/.codex/skills（或项目级 ./.codex/skills），并通过 omx setup 完成组件安装、omx doctor 验证安装状态（见 templates/AGENTS.md）。

九、一次完整的 $analyze 调用形态

技能文档末尾的模板是 Task: {{ARGUMENTS}}，即调用时由用户问题填充参数。一次典型调用形如：

$analyze 为什么任务在团队模式下偶发超时？请给出证据排序

对应的产出即按第六节契约组织：先重述问题（团队模式下任务偶发超时的根因），再给排序综合表（如 Rank 1：任务状态推进依赖 omx team api ... --json 持久化分发，最可能是队列等待而非执行超时；Rank 2：...；Rank 3：...），随后列出 path/to/file:line-line 形式的证据、推断与未知项，最后给出消除剩余不确定性所需的最小只读探测。

十、从源码结构看它的工程价值

从源码结构看，$analyze 的价值体现在三处刻意设计上：

1. 路由与实现解耦：关键字定义集中在 src/hooks/keyword-registry.ts，技能内容独立成 SKILL.md，两者通过 UserPromptSubmit 原生 hook 衔接（plugins/oh-my-codex/hooks/hooks.json），新增触发词不需要改动技能本体；
2. 契约测试锁定质量：analyze-skill-contract.test.ts 逐句断言技能文件必须包含"只读证据""三分类纪律""排序综合输出契约"，防止技能在演进中被稀释成普通问答提示词；
3. 回归防线明确：analyze-routing-contract.test.ts 同时检查模板 AGENTS 与根级 registry，防止 analyze 被历史遗留的 debugger 路由或兼容别名"劫持"。

这三重设计共同保证了：$analyze 无论何时被触发，输出的都是有证据边界、有置信度分级、可审计、可复现的仓库分析结论——这正是它与普通"帮我看看代码"式问答的本质区别，也是它在任何改动建议落地之前作为最后一道理解关卡的价值所在。