企业官网建设流程全解析

OmX 的 Verifier 角色深度解析：基于可复现证据的完成度验证与 PASS/FAIL/PARTIAL 判定契约

【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex

导读

本文聚焦 OmX（Oh My codeX）提示词体系中专职负责完成度验证的 Verifier 角色，讲解它如何把抽象的"任务是否完成"问题转化为可观察文件、diff、命令、诊断、测试与验收标准上的直接证据，并给出 PASS / FAIL / PARTIAL 三态判定。你将掌握 Verifier 的完整提示词契约（身份、约束、执行循环、输出契约、场景处理），理解它与其他角色（Executor、Planner）的职责边界，以及如何在多层 Agent 团队中利用验证回路与显式停止条件保证结论的可信度。

Verifier 在 OmX 提示词体系中的位置

OmX 将可安装的专家角色提示词统一收敛在 prompts/ 目录下，其中prompts/verifier.md定义了"完成证据与验证专家（Completion evidence and verification specialist, STANDARD）"的标准提示词。与它并列的核心角色还包括：

• Executor：把已分配、已限定范围的任务转化为可用且已验证的结果，负责实现与聚焦验证，最终交付"变更 + 证据"式的完成报告；
• Planner：把请求转化为可执行、有证据支撑的工作计划，只做规划与交接，不写代码；
• Verifier：既不实现也不规划，专职证明或证伪"完成"——把主张与验收标准翻译成 PASS / FAIL / PARTIAL 判定。

从 docs/prompt-guidance-contract.md 看，prompts/*.md是"规范化的 XML 标签角色提示词表面"，同时被原生 Agent 生成与内部角色提示词组合使用，其正文源文件视为权威版本（canonical），安装后会落到~/.codex/prompts/等位置。这意味着对verifier.md的任何改动，都应当同步反映在安装产物与回归测试中。

身份定位：证明或证伪，而不是复述

prompts/verifier.md的开篇用<identity>块给出了角色的唯一使命：

You are Verifier. Prove or disprove completion with direct, reproducible evidence. Turn claims and acceptance criteria into a PASS, FAIL, or PARTIAL verdict.

三个关键词定义了 Verifier 的行为基调：

• Prove or disprove（证明或证伪）：双向取证。验证者既要找支持完成的证据，也要主动寻找证伪点，而不是顺着实现者的总结往下走；
• Direct, reproducible evidence（直接、可复现的证据）：证据必须能被第三方重放，例如一个可以重新执行的命令、一个可重新打开的 diff；
• PASS / FAIL / PARTIAL（三态判定）：拒绝非黑即白的模糊结论，允许"部分完成"这一中间状态存在。

这一身份设计也对应 OmX 中"验证必须由证据支撑"的整体行为契约。在 docs/prompt-guidance-contract.md 的"5 大 GPT-5.6 模式"中，第 5 条"证据预算、验证与显式停止规则"明确要求：当正确性依赖仓库检查、官方文档、诊断、测试、引用或验证时，应继续使用工具，但避免只为改进措辞或收集非必要证据的多余循环——这正是 Verifier 约束条目的直接来源。

约束层：什么能信、什么不能信

<constraints>块规定了 Verifier 的取证边界，共 5 条硬约束：

1. 对可观察对象验证：Verify claims against observable files, diffs, commands, diagnostics, tests, artifacts, and acceptance criteria.——主张必须落到可观察的文件、diff、命令、诊断、测试、产物与验收标准上，而不是模型的自述；
2. 不信实现总结：Do not trust implementation summaries; distinguish failed behavior from unavailable proof.——必须区分"行为真的失败"与"只是拿不到证明"这两种情况；
3. 偏好新鲜且有目标的证据：Prefer fresh, targeted evidence and state exactly what each check proves.——每一项检查都要说清楚它到底证明了什么；
4. 验证规模与主张成正比：Keep verification proportional to the claim; do not substitute a narrow check for end-to-end proof.——不能用一次狭窄的检查冒充端到端证明；
5. 显式点名缺口：Call out missing evidence, residual risks, and unavailable proof sources explicitly.——缺失证据、残余风险、不可用的证明来源必须显式点名。

此外，约束块内嵌了两组OMX:GUIDANCE片段（由 docs/prompt-guidance-fragments/ 中的共享片段注入）：

• verifier-constraints.md：要求"结果优先、证据密集"的判定——点名主张、成功标准、验证证据、缺口与停止条件；验证路径保持精简，只收集关键证明而非无关工具输出；持续检查直到判定有据可依，或某个必需证明来源不可用。
• verifier-investigation.md：规定当一条较新的用户指令只改变验证目标或报告形态时，应局部应用该变更，同时保留无关的验收标准，以及每条主张到证据或显式证据缺口之间的可追溯性。

这两组片段与共享片段 verifier-shared.md 一起，把"outcome-first、证据密集、验证充分即停、局部覆盖不丢弃旧验收标准"的原则固化进了角色提示词。

执行循环：五步取证到有据判定

<execution_loop>定义了 Verifier 的标准工作流，恰好对应从"声明"到"判定"的完整链路：

1. 声明主张与验收标准：State the exact claim and acceptance criteria that must be proven.——先明确要证明什么，验收标准必须是可测试的；
2. 检查证据来源：Inspect the relevant implementation, diff, artifacts, and prior evidence.——审阅相关实现、diff、产物与既有证据；
3. 运行最小化直接检查：Run or review the smallest checks that directly prove each criterion; read their complete results.——只运行能直接证明某项标准的最小检查，并且必须读取完整输出，不能只看摘要；
4. 调和冲突证据：Reconcile conflicting evidence, identify gaps and risks, and stop only at a grounded verdict.——当证据互相矛盾时进行调和，识别缺口与风险，只在判定有据可依时停止；
5. 证据不可用时明确命名缺失源：If proof is unavailable, name the missing source and the strongest bounded evidence obtained.——给出缺失的证明来源，以及目前能拿到的最强有界证据。

这一循环与 docs/prompt-guidance-fragments/core-verification-and-sequencing.md 中的"验证回路"完全同构：定义主张与成功标准 → 运行能证明它的最小验证 → 读取输出 → 携带证据报告；验证失败则迭代，验证无法运行则解释原因并使用次优检查。同时该片段还补充了两条排序原则：依赖任务顺序执行，启动下游动作前先验证前置条件；编码类工作优先用针对性测试验证变更行为，再按需做 typecheck / lint / build / smoke 检查，没有新鲜证据或显式验证缺口就不得宣称完成。

输出契约：Verdict / Evidence / Gaps / Risks 四段式报告

<output_contract>是 Verifier 报告的唯一默认形态，固定为四段结构：

## Verdict - PASS / FAIL / PARTIAL — [one-line result] ## Evidence - `[command or artifact]` — [criterion proved or disproved] ## Gaps - [Missing or inconclusive proof; "None" when complete] ## Risks - [Remaining uncertainty or follow-up; "None" when clear]

• Verdict：第一行给出三态判定与一行结论摘要，是全篇的核心；
• Evidence：逐条列出命令或产物 → 被证明或被证伪的标准，保证每条判定都能被复现核对；
• Gaps：显式记录缺失的或无法得出结论的证明，完整时写None；
• Risks：记录剩余的不确定性或后续动作，明确时写None。

这个结构刻意规避了"过程流水账"，强制实现"结果优先、证据密集"。它与 Executor 的输出契约（Changes Made / Verification / Assumptions / Summary）形成互补：Executor 汇报"我改了什么、验证证明了什么"，Verifier 则独立判定"这些证据是否真的证明完成"。从 docs/prompt-guidance-contract.md 的"终端交接契约"来看，涉及活跃工作流的终结回复还必须点名显式结局（如finished、blocked、failed），并附上支撑该结局的证据或阻塞原因——Verifier 的 Verdict + Evidence 恰好满足这一要求。

场景处理：continue 与 merge if CI green

<scenario_handling>针对两种高频用户指令给出行为约定：

• continue：keep gathering required evidence instead of restating a partial verdict.——用户说"继续"时，不要重复一个不完整的判定，而应继续收集必需证据。这与 Executor 的"留在当前实现分支上补齐缺失证据"、Planner 的"继续当前规划分支"语义一致；
• merge if CI green：confirm the relevant checks are green before reporting the merge gate as satisfied.——报告合并门槛已满足之前，必须亲自确认相关检查是绿的，不能把用户的指令本身当作证据。

这两条场景规则直接呼应了 docs/prompt-guidance-contract.md 第 4 条模式"局部化任务更新覆盖"：较新的用户指令是对当前任务的局部覆盖，不得丢弃此前未冲突的指令，也不得把"用户要求合并"误当成"CI 已通过"这一事实主张。

源码级的回归保障：验证契约如何被测试守护

Verifier 提示词并非只停留在文档层面，仓库通过回归测试确保其行为契约不被意外破坏。从 src/hooks/tests/prompt-guidance-fragments.test.ts 与 src/hooks/tests/prompt-guidance-wave-two.test.ts 中均可检索到 verifier 相关断言，它们隶属于 docs/prompt-guidance-contract.md 列出的契约测试族（prompt-guidance-contract、prompt-guidance-wave-two、prompt-guidance-scenarios、prompt-guidance-catalog、skill-guidance-contract、prompt-guidance-fragments）。该文档还给出了改动提示词后的验证工作流：

npm run build node --test \ dist/hooks/__tests__/prompt-guidance-contract.test.js \ dist/hooks/__tests__/prompt-guidance-wave-two.test.js \ dist/hooks/__tests__/prompt-guidance-scenarios.test.js \ dist/hooks/__tests__/prompt-guidance-catalog.test.js \ dist/hooks/__tests__/skill-guidance-contract.test.js \ dist/hooks/__tests__/prompt-guidance-fragments.test.js \ dist/hooks/__tests__/explicit-terminal-stop-docs-contract.test.js

任何修改 Verifier 提示词文本的 PR，都应保证上述测试仍然通过；若涉及角色路由或原生 Agent 元数据，则改的是路由层而非行为契约（两者边界见 docs/prompt-guidance-contract.md 的"这个契约是什么——以及不是什么"一节）。从源码结构可以推断，这些测试的作用是把"outcome-first、证据密集、显式停止规则"等行为条款固化为可机器校验的断言，防止角色提示词在演进中回归成纯流程清单。

在团队工作流中的定位与边界

综合 prompts/executor.md、prompts/planner.md 与 Verifier 提示词可以看出，三者在验证职责上是分层的：

• Executor 负责自验证：用针对性测试、typecheck、lint、build 证明自己的改动成立，报告里必须给出验证命令与结果，不得无证据宣称完成；
• Verifier 负责独立验收：不信任实现者的总结，重新面向可观察对象取证，输出三态判定与缺口/风险清单；
• Planner 负责在计划阶段就把验收标准、验证命令与停止条件写进计划（Verification: [commands or evidence that prove each criterion]），为 Verifier 提供可追溯的验收目标。

同时，docs/prompt-guidance-contract.md 的"编排锐度规则"强调 Leader 与 Worker 职责分离：Leader 选择模式、拥有验证并整合成果；Worker 执行分片并向上汇报阻塞。Verifier 的独立取证能力正是 Leader 履行"拥有验证"职责时的核心工具——当团队产出被汇总后，需要一个不偏向任何实现者、只对证据负责的角色来给出最终判定。

小结

prompts/verifier.md用极简的 XML 结构封装了一套严谨的验证方法论：身份上只认"直接、可复现的证据"，不信任实现总结；约束上要求验证与主张成正比、显式点名缺口与风险；流程上遵循"声明 → 检查 → 最小验证 → 调和 → 停止"五步循环，只在判定有据可依时停止；输出上固定为 Verdict / Evidence / Gaps / Risks 四段式；场景上对continue与merge if CI green给出了防止"把指令当证据"的行为约定。配合共享片段与回归测试，OmX 把"验证者不轻信、结论必须可复现"这一原则做成了可维护、可测试的产品契约，为多 Agent 协作中的完成度判定提供了可靠的最后一道防线。

【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex