Oh My Codex Verifier 共享指引片段解析：verifier-shared.md 的证据型判定契约与提示词同步机制

Oh My Codex Verifier 共享指引片段解析：verifier-shared.md 的证据型判定契约与提示词同步机制

【免费下载链接】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

本文围绕 Oh My Codex（OmX）仓库中的 verifier-shared.md 展开，逐条解读这 4 条“验证者共享行为指引”的语义与适用场景，并结合 prompts/verifier.md 的落地结构、sync-prompt-guidance-fragments.ts 的片段注入/漂移检查机制，以及 prompt-guidance-contract.ts 的正则契约测试，说明 OmX 如何把一个抽象的行为规范变成可同步、可回归验证的提示词工程实践。

1. verifier-shared.md 在提示词体系中的位置

OmX 在 Issue #2007 之后对齐了 OpenAI 官方的 GPT-5.6 提示词指引（prompt guidance），并把这套行为契约拆分成多层表面，其结构在 prompt-guidance-contract.md 中定义为：

verifier-shared.md 属于“共享片段层”中专属于Verifier（验证者）角色的通用行为基线。同目录下与它构成同一片段家族的文件包括：

• verifier-constraints.md：注入到角色提示的<constraints>区块；
• verifier-investigation.md：注入到<verification_loop>区块；
• executor-shared.md、planner-shared.md：其他核心角色的同名共享片段。

从源码结构看，*-shared.md三个文件采用统一的命名约定，面向“报告与判定”这一更通用场景措辞；而*-constraints.md/*-investigation.md则是角色提示中标记区块（marker block）的直接注入源。对比两者可以发现，verifier-shared.md 的 4 条指引与 verifier-constraints.md、verifier-investigation.md 的 3+1 条是同一套行为基线的两种措辞——这正体现了 OmX 契约中“措辞可以按角色/场景差异化，但行为语义必须保持一致”的原则（见 prompt-guidance-contract.md 贡献者清单第 2 条）。

2. 四条共享指引逐条解读

原文全文只有 4 个要点，每一条都对应 GPT-5.6 契约中的核心行为模式，以下逐条给出原文、语义解读与仓库内的落地证据。

2.1 默认输出“结论先行、证据密集”的判定

Default reports to outcome-first, evidence-dense verdicts: name the claim, success criteria, validation evidence, gaps, and stop condition before adding process detail.

这条对应 GPT-5.6 契约五大核心模式中的第 1 条——Outcome-first, success-criteria-led prompts：先给出目标结果、成功标准、约束、可用证据、期望输出和停止条件，再谈过程细节。

对 Verifier 角色而言，“结果”不是实现描述，而是一个PASS / FAIL / PARTIAL 判定，且判定前必须先点名五要素：待证声明（claim）、成功标准（success criteria）、验证证据（validation evidence）、证据缺口（gaps）、停止条件（stop condition）。这一要求在 prompts/verifier.md 的<output_contract>中被结构化为四个固定章节：

## 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]

其中Evidence章节要求每条证据写成「命令或工件 — 证明了/证伪了哪条标准」的形式，Gaps章节强制显式暴露缺口（完整时写 "None"）——这正是“name the claim, success criteria, validation evidence, gaps, and stop condition”在输出层的可执行版本。

2.2 证据不足时继续取证，够了就停

If correctness depends on additional tests, diagnostics, or inspection, keep using those tools until the verdict is grounded; stop once enough evidence proves the core claim.

这条对应契约第 5 条——Evidence budgets, validation, and explicit stop rules：只要正确性还依赖仓库检查、测试、诊断等证据，就继续用工具；一旦足够证据支撑核心声明，立即停止。

两个关键词值得注意：

• verdict is grounded（判定有根基）：停止的判据不是“跑了几轮工具”，而是“判定是否已被证据支撑”。同一片段家族中，verifier-constraints.md 第 3 条进一步补上了反向边界——“直到判定有根基或必需的证明来源不可用为止”；
• stop once enough：停止条件显式化，避免无界循环。

在 prompts/verifier.md 的<execution_loop>中，这一条被展开为 5 步循环：先声明精确的 claim 与验收标准 → 检查实现、diff、工件与既有证据 → 运行能直接证明每条标准的最小检查并读完整输出 → 调和冲突证据、识别缺口与风险，只在判定有根基时停止→ 若证明不可用，点名缺失来源与已获得的“最强有界证据”。

2.3 更多验证不等于无关工具空转

More verification effort does not mean unrelated tool churn; gather the proof that matters, not every possible artifact.

这条是前一条的“防过度”对偶：验证预算不等于无限取证。tool churn（工具空转）指为了“显得更严谨”而收集与核心声明无关的产物。同家族的 verifier-constraints.md 第 2 条把同一语义表述为“保持验证路径简洁，收集真正重要的证明，而非无关工具输出”。

值得注意的是，这条指引在契约测试中是被正则锚定的：prompt-guidance-contract.ts 中CORE_ROLE_PATTERNS.verifier要求 prompts/verifier.md 必须匹配proof that matters|tool churn——也就是说，“收集重要证据、不空转”不是一个可有可无的风格建议，而是 CI 会用正则回归验证的提示词不变量。同组锚点还包括：

2.4 新的用户指令按“局部覆盖”处理

If a newer user instruction only changes the current verification target or report shape, apply that override locally without discarding earlier non-conflicting acceptance criteria.

这条对应契约第 4 条——Localized task-update overrides：用户的后续消息（例如“换个报告格式”“改查另一个模块”）应被视为作用域受限的局部覆盖，而不是整份提示词的重置；与它不冲突的既有验收标准必须保留。

verifier-investigation.md 是同一语义的角色注入版本，并额外要求保留“从每条声明到证据、或到显式证明缺口的可追溯性”。在 prompts/verifier.md 的<scenario_handling>中，这一原则有两个具体场景示例：

• 用户说continue：继续收集所需证据，而不是重述一个部分判定；
• 用户说merge if CI green：先确认相关检查确实变绿，才能报告合入门槛已满足——这与契约测试中verifier-scenarios要求的user saysmerge if CI green``、gather.*evidence|validation evidence模式（见 prompt-guidance-contract.ts）一一对应。

3. 片段如何被注入角色提示：marker 同步机制

共享片段的价值不仅在于文本本身，更在于它作为**唯一事实源（SSOT）**被机械同步到各提示表面。核心机制在 sync-prompt-guidance-fragments.ts：

1. 读取片段：脚本读取 docs/prompt-guidance-fragments/ 下的片段文件并trim()（sync-prompt-guidance-fragments.ts）；

2. 定位标记区块：每个目标文件（如 prompts/verifier.md）中用 HTML 注释标记出一对边界，例如 prompts/verifier.md 里的：

   <!-- OMX:GUIDANCE:VERIFIER:CONSTRAINTS:START --> - Use outcome-first, evidence-dense verdicts: name the claim, ... <!-- OMX:GUIDANCE:VERIFIER:CONSTRAINTS:END -->

3. 替换区块内容：replaceBetween()用片段全文覆盖标记之间的内容；标记缺失会直接抛错Markers not found（sync-prompt-guidance-fragments.ts）；

4. 漂移检查：以--check模式运行时，脚本不写文件，而是把“期望内容 ≠ 实际内容”的文件收集为漂移项，最终以prompt_guidance_fragment_drift:<file列表>报错退出（sync-prompt-guidance-fragments.ts）。

对 Verifier 角色的注入目标是 prompts/verifier.md 的两个区块：VERIFIER:CONSTRAINTS（来自 verifier-constraints.md）与VERIFIER:INVESTIGATION（来自 verifier-investigation.md），见 sync-prompt-guidance-fragments.ts。

需要说明的一个事实边界：从当前同步脚本的注入清单看（sync-prompt-guidance-fragments.ts），verifier-shared.md与executor-shared.md、planner-shared.md一样，尚未被列入自动注入目标——脚本只注入各角色的 constraints/investigation/output 片段与根模板的 operating/specialist-routing/verifyseq 片段。因此可以推断，*-shared.md目前是作为共享行为基线的“规范文本”存在于片段家族中，其语义通过同源的 constraints/investigation 片段与契约测试正则进入各角色提示。

3.1 三重回归防护

围绕这套同步机制，仓库配置了三层回归测试：

1. 片段-表面一致性测试：src/hooks/tests/prompt-guidance-fragments.test.ts 的 “syncs verifier guidance fragments” 用例从 prompts/verifier.md 中抽出两个标记区块，断言其内容与对应片段文件逐字相等；
2. 契约正则测试：src/hooks/prompt-guidance-contract.ts 导出CORE_ROLE_CONTRACTS（含 verifier 条目，prompt-guidance-contract.ts），由prompt-guidance-contract.test.ts等测试执行，防止角色提示的行为措辞漂移；其注释明确说明这是文本层契约：“these patterns prevent prompt-surface drift; they do not enforce runtime harness behavior”（prompt-guidance-contract.ts）；
3. 漂移检查端到端测试：generated-artifact-drift.test.ts 在干净树上运行dist/scripts/sync-prompt-guidance-fragments.js --check要求退出码 0；generated-artifact-drift.test.ts 则故意向 templates/AGENTS.md 的标记区块注入DRIFT_INJECTED_BY_TEST，验证--check能报出prompt_guidance_fragment_drift并以非零码失败。

此外，prompt-inventory.ts 提供提示词表面的盘点工具：统计各表面行数、近似 token 数、绝对指令词（MUST/NEVER/ALWAYS/ONLY 等，见 prompt-inventory.ts）行数与 marker 命中，并检测跨文件重复的片段家族——这为“共享片段应集中存放、避免在多处复述”的契约目标提供了审计手段。

4. 相关文档与延伸阅读

• 行为契约总纲：docs/prompt-guidance-contract.md——定义五大核心模式、绝对用语规则（MUST/NEVER只用于真正的不变量）与验证工作流；
• 结构布局契约：docs/guidance-schema.md 定义 AGENTS/worker 表面的章节布局，与行为契约分工使用（结构归 schema，行为归 guidance contract）；
• 同目录其他片段：core-operating-principles.md、core-verification-and-sequencing.md、leader-specialist-routing.md 等，共同构成共享片段家族。

5. 实操验证：如何确认契约当前是绿的

在仓库根目录下（前提：已完成npm install），可以按 prompt-guidance-contract.md 给出的验证工作流运行提示词契约回归：

npm run build node --test \ dist/hooks/__tests__/prompt-guidance-contract.test.js \ dist/hooks/__tests__/prompt-guidance-fragments.test.js \ dist/hooks/__tests__/prompt-guidance-scenarios.test.js \ dist/hooks/__tests__/prompt-guidance-catalog.test.js

其中prompt-guidance-fragments.test.js直接守护“片段文件 ↔ 标记区块”的逐字一致，prompt-guidance-contract.test.js守护本文第 2.3 节列出的 verifier 正则锚点。单独验证漂移检查可用：

node dist/scripts/sync-prompt-guidance-fragments.js --check

干净树上应输出prompt guidance check ok并以退出码 0 结束（见 generated-artifact-drift.test.ts）。更完整的覆盖还包括 src/scripts/tests/prompt-inventory.test.ts 等提示词盘点测试；大范围改动时建议直接运行npm test。

6. 适用前提与限制

• 版本适用性：本文结论基于当前仓库快照（OmX 0.21.x 世代文档树）。prompt-guidance-contract.md 提到prompts/sisyphus-lite.md已在 OMX 0.21 移除，说明提示词表面随版本演进，跨版本引用本文时应以对应仓库快照为准；
• 文本契约 ≠ 运行时强制：契约测试是纯正则/文本断言，防止的是提示词表面漂移，并不在运行时拦截模型行为（prompt-guidance-contract.ts 注释已明示）；
• 片段作用边界：verifier-shared.md 是行为基线文本，真正进入 prompts/verifier.md 的是同家族的 constraints/investigation 片段；直接编辑 shared 片段而不同步修改对应角色片段与正则锚点，不会自动传导到角色提示，这正是该目录存在“漂移检查 + 一致性测试”的原因。

综上，verifier-shared.md 用 4 条极简指引刻画了 OmX Verifier 角色的完整行为契约：结论先行的证据型判定、有根基才停的取证循环、反对工具空转的证据预算、以及局部覆盖式的指令更新语义；再配合 marker 注入、--check漂移检查与正则契约测试，这套 4 行文本成为整个提示词体系中可审计、可回归的验证者行为标准。

【免费下载链接】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