企业官网建设流程全解析

oh-my-openagent 的 comment-checker-core：apply-patch 解析与 AI 废话注释拦截 Runner 内核深度剖析

【免费下载链接】oh-my-openagentOmO: Just type "mass ulw" keyword with your prompt. Now you are the master of graph engineering.项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent

导读：本文围绕 oh-my-openagent 仓库中的@oh-my-opencode/comment-checker-core包展开，它是 AI 编程助手（omo-opencode 与 omo-codex 两个版本）共用的「代码注释质量守卫」核心：一端负责把 LLM 生成的 apply-patch 编辑协议解析为结构化的CheckerEdit[]，另一端负责拉起外部@code-yeongyu/comment-checker二进制，检测改动代码中「AI 味」注释（restating 代码行为、filler 废话、无意义分隔线、无上下文的 TODO 等）并在落地前拦截。读完本文，你将掌握该核心模块的完整公开 API、apply-patch 解析协议细节、子进程运行契约（退出码 / 超时 / 优雅终止）以及它在两大消费端（OpenCode hooks 与 Codex plugin）中的实际接线方式。

一、模块定位：一个核心，两种职责

从 packages/comment-checker-core/AGENTS.md 的定义看，comment-checker-core承担两项正交职责：

1. 解析职责：把 LLM 输出的 apply-patch 编辑文本（*** Add/Update/Delete File:协议）解析为结构化CheckerEdit[]，从而知道「这次改动到底动了哪些文件的哪些内容」；
2. 运行职责：以子进程方式运行外部二进制@code-yeongyu/comment-checker，把待检查内容通过 stdin 以 JSON 形式喂给它，再读取 stdout/stderr 判定是否存在「AI-slop comments」。

关键的架构决策在于派生进程是依赖注入的（SpawnFn，而非直接使用child_process.spawn）。这样做的收益很直接：omo-opencode（Bun 运行时）与 omo-codex（Codex plugin 运行时）两套运行环境可以驱动同一份解析与运行逻辑，但各自注入适合自己的 spawn 实现，核心代码不需要关心宿主环境差异。这一点在 runner.ts 的类型签名中体现得淋漓尽致——见下文第四节。

该包的 npm 名称为@oh-my-opencode/comment-checker-core（见 package.json），依赖仅有一个：@oh-my-opencode/utils（用到了其中的isRecord记录类型守卫，用于安全地读取未知形状的对象字段）。

消费端一览

根据核心 AGENTS.md 的 DEPENDENCIES & CONSUMERS 一节，该核心被两个版本的助手共同消费：

• omo-opencode 版：packages/omo-opencode/src/hooks/comment-checker/{hook,types,cli}.ts，注册为 Tool Guard tier 的 hook，在write/edit/multiedit/apply_patch工具执行后运行；
• omo-codex 版：packages/omo-codex/plugin/components/comment-checker/src/{core,core-values,apply-patch,request-extractor}.ts，通过PreToolUse/PostToolUse适配器接入。

以 omo-opencode 侧为例，hook.ts 中的createCommentCheckerHooks()工厂返回tool.execute.before/tool.execute.after两个钩子：before 阶段把filePath、content、oldString/newString、edits以PendingCall形式按callID登记；after 阶段取出对应 pending call（或对apply_patch工具直接从 metadata 里抽取编辑），解析 CLI 路径后执行检查，若发现问题则在工具输出中注入错误，迫使 Agent 修复。

二、公开 API 总览

核心的公共出口集中在 src/index.ts，汇总如下表（对应核心 AGENTS.md 的 PUBLIC API 一节）：

此外，index.ts还导出了若干内部辅助函数（getString、isRecord、joinPatchLines、makeAccumulator、readApplyPatchMetadataFiles）以及 17 个类型（CheckerEdit、HookInput、CheckResult、SpawnFn/SpawnProcess/SpawnSignal、ApplyPatchFileMetadata等），全部定义在 types.ts。

核心类型速览

• CheckerEdit：解析结果的最小单元，{ filePath, before, after }三段式，即「哪个文件，改前内容，改后内容」；
• ApplyPatchFileMetadata：metadata 形态的编辑描述，除三段式外还可携带movePath（文件移动目标）与type（操作类型）；
• CheckResult：运行结果，{ hasComments: boolean, message: string }；
• HookInput：喂给外部二进制的输入 JSON，其字段镜像 OpenCodetool.execute.before的输入 schema（session_id、tool_name、transcript_path、cwd、hook_event_name、tool_input、tool_response）；
• SpawnFn/SpawnProcess/SpawnSignal：抽象出的进程接口，见第四节。

三、apply-patch 解析器：从协议文本到结构化编辑

解析器位于 apply-patch-edits.ts，是整个核心最「算法化」的部分。它的输入是 LLM 输出的一段 apply-patch 协议文本，输出是CheckerEdit[]。

3.1 支持的操作指令

parseApplyPatchRequests逐行扫描 patch 文本（按/\r?\n/切分，兼容 CRLF 与 LF），识别以下指令（对应核心 AGENTS.md 中的协议描述）：

有一个值得注意的细节：*** Delete File:指令本身会被记录进 accumulator，但 flush 时不会产出编辑（delete 分支没有任何 push 逻辑）。这是合理的——删除操作不产生新代码，自然无需做注释检查。

另一个细节是joinPatchLines：解析出的行数组在拼回字符串时会统一追加结尾换行（lines.length === 0 ? "" : lines.join("\n") + "\n"），且 add 操作若最终没有有效内容（after 为空）也会被丢弃，避免产出空编辑。

3.2 三段式 flush 模型：ApplyPatchAccumulator

解析过程使用一个状态机式的 accumulator（ApplyPatchAccumulator，同样定义在 types.ts）：{ operation, filePath, movePath?, oldLines, newLines }。每当遇到新的*** Add/Update/Delete File:指令，先flush()掉上一个文件块的累积结果，再创建新的 accumulator——这正是makeAccumulator的职责。

3.3 高层抽取器与 metadata 回退链

extractApplyPatchEdits(details, args?)给出了更「务实」的抽取策略，优先级如下：

1. 先尝试getApplyPatchMetadataFiles(details)：从details.files→details.result.files→details.metadata.files逐层读取结构化文件元数据（这是readApplyPatchMetadataFiles的实现，支持filePath/file_path/path、before/old/oldString/old_string、after/new/newString/new_string、type/operation等多套字段别名）；
2. metadata 中type为delete（大小写不敏感）的文件会被过滤掉，不参与检查；
3. 若 metadata 文件非空，直接映射为CheckerEdit[]返回（移动文件用movePath ?? filePath作为最终路径）；
4. 若 metadata 为空，回退到args中的 patch 文本：依次尝试patchText、input、patch、command四个键（getString按序取第一个字符串值），再交给parseApplyPatchRequests；
5. 两者都拿不到就返回空数组。

这一设计的价值在于兼容不同的 hook 宿主：OpenCode 的 apply_patch 可能携带结构化 metadata，而 Codex 等环境的适配器可能只暴露 patch 文本，核心层通过回退链把两种情况统一成同一种CheckerEdit[]。

3.4 测试佐证

apply-patch-edits.test.ts 验证了 metadata 读取的「legacy record 语义」：即使details是一个被挂上files属性的数组（isRecord对数组返回 true），也能正确读出[{ filePath, before, after }]。这保证了向后兼容的容错能力——不同版本宿主传入的 metadata 容器形状可能不同，解析器需要尽量宽容。

四、Runner 内核：二进制解析、stdin 管道与退出码契约

运行职责由 runner.ts 承担，分为「解析二进制路径」与「执行检查」两个函数。

4.1 resolveCommentCheckerBinary：三级查找策略

resolveCommentCheckerBinary(input)的解析顺序是：

1. 缓存路径优先：若cachedBinaryPath非空且existsSync确认文件存在，直接返回（省去每次模块解析开销）；
2. createRequire 探测：以importMetaUrl为基准构造createRequire，require.resolve("@code-yeongyu/comment-checker/package.json")拿到包根目录，再拼上bin/<binaryName>子路径；只有existsSync确认存在才返回；
3. 降级返回 null：找不到则返回null，调用方（hook 层）据此优雅跳过检查，而不是抛异常中断整个工具执行。

解析过程对「旧式 Bun 运行时抛非 Error 值」做了防御：早期嵌入式 Bun 的模块解析会抛出ResolveMessage对象而非Error实例。代码里明确判断了error.name === "ResolveMessage"这种情况并视同为解析失败返回null，而其他不可预期的异常则原样上抛。runner-resolution.test.ts 用mock.module("node:module")分别注入ResolveMessage与UnrelatedFailure两种抛出值，断言前者降级为 cache miss（返回 null）、后者继续抛错——精确锁定了「只有缺包才算失败」的契约。

4.2 runCommentChecker：JSON-in、stdout/stderr-out 的进程契约

runCommentChecker(input, options)的执行流程：

1. 前置守卫：binaryPath为 null 或文件不存在时，直接返回EMPTY_RESULT（{ hasComments: false, message: "" }）；
2. 拼装参数：[binaryPath, "check"]，若传入customPrompt则追加--prompt <prompt>；
3. 写入输入：把HookInput序列化为 JSON 写入process.stdin并end()；
4. 并发竞速：同时等待三个 Promise——stdout 文本、stderr 文本、exited退出码——并与超时 Promise 进行Promise.race；
5. 按退出码判定结果（这就是核心 AGENTS.md 强调的exit-code contract）。

退出码契约总结如下（normalizeMessage会先把\r\n归一化为\n）：

注意这个「fail-closed 还是 fail-open」的取向：任何非 0、非 2 的异常退出都按「无注释」处理（fail-open），避免二进制自身崩溃或环境问题阻断正常工具调用——代价是异常情况下检查被静默跳过，这与 hook 层「CLI 不可用则优雅跳过」的整体策略一致。

4.3 超时与优雅终止：SIGTERM → SIGKILL 升级

核心 AGENTS.md 明确了两组数字：

• 默认超时 30 秒（timeoutMs ?? 30_000）；
• 1 秒 kill 宽限期（killGraceMs ?? 1_000）。

超时触发后的终止路径是两段式升级：先发SIGTERM给进程一个「收拾残局」的机会，等待killGraceMs毫秒后若进程仍未退出，再发SIGKILL强制终结。killProcessSafely对 kill 调用本身做了 try/catch 防御（例如进程已自行退出时 kill 可能抛错）。定时器与清除函数同样可注入（setTimeoutFn/clearTimeoutFn），便于在测试环境中用假时钟控制时序。竞速过程中一旦超时胜出，立即返回EMPTY_RESULT；finally块中会清掉尚未触发的定时器，避免悬挂。

4.4 SpawnProcess：刻意不用 Node ChildProcess 的注入接口

这是该核心最值得一提的抽象。SpawnProcess（types.ts 中的定义）只暴露运行检查所需的极小子集：

type SpawnProcess = { stdin: { write(input: string): void; end(): void } stdout: ReadableStream<Uint8Array> stderr: ReadableStream<Uint8Array> exited: Promise<number> kill(signal: SpawnSignal): void }

它刻意不是Node 的ChildProcess类型，而是把 NodeChildProcess的stdout（Readable）适配为 Web 标准的ReadableStream<Uint8Array>。这带来两个直接好处：

1. runCommentChecker内部可以用new Response(process.stdout).text()这类 Web API 读取输出，无需依赖 Node 专属的事件 API，从而让同一份核心代码在 Bun（omo-opencode）与 Codex plugin 运行时中都成立；
2. 测试时可以注入完全内存化的假进程：stdin记录写入内容，exited返回预设退出码，从而无需真的拉起二进制即可验证退出码契约与超时逻辑。

SpawnFn = (args: readonly string[]) => SpawnProcess则是「进程工厂」，RunCommentCheckerOptions.spawn字段就是它的注入点。

五、HookInput：镜像 OpenCode schema 的跨环境输入契约

核心 AGENTS.md 特别强调：HookInput与 OpenCodetool.execute.before的输入 schema 完全一致。HookInput的字段包括：

• session_id：会话 ID；
• tool_name：触发的工具名（如write、edit、apply_patch）；
• transcript_path：会话转录文件路径；
• cwd：当前工作目录；
• hook_event_name：钩子事件名；
• tool_input：工具入参，含file_path、content、old_string、new_string，以及edits: { old_string, new_string }[]（对应多编辑工具）；
• tool_response?：工具响应（可选，after 场景下可能携带）。

正因为输入契约统一，同一个解析器（parseApplyPatchRequests/extractApplyPatchEdits）可以同时服务 OpenCode 的tool.execute.before/afterhook 与 Codex 的PreToolUse/PostToolUse适配器——这是「一个核心、双版本驱动」架构能成立的关键前提。

在 omo-opencode 的 hook.ts 中，PendingCall正是这个 schema 的运行时投影：before 阶段从output.args里以多别名方式抽取filePath（filePath/file_path/path）、oldString（oldString/old_string）等字段登记；after 阶段对apply_patch工具直接调用extractApplyPatchEdits(output.metadata, input.args)，对其他写工具则takePendingCall(callID)取回登记数据。两个路径最终都汇入「解析 CLI 路径 → 跑检查 → 有问题则注入错误」的统一流程。

六、下游配置与旁路机制（结合消费端）

虽然核心包自身只负责解析与运行，但它被消费时的行为由消费端配置驱动。以 omo-opencode 的 hook 为例（见 hooks/comment-checker/AGENTS.md）：

// .omo/omo.jsonc { "comment_checker": { "enabled": true, // 默认: true "severity": "error" // error 会拦截（注入工具错误）；warning 仅通知不拦截 } }

• custom_prompt会通过--prompt透传给外部二进制，见 hook.ts 中config?.custom_prompt的传递；
• 可通过"disabled_hooks": ["comment-checker"]整体禁用；
• 合法注释的旁路机制：行级前缀// @allow，或文件顶部标记// comment-checker-disable-file（应谨慎使用，否则守卫形同虚设）。

「AI-slop comment」的典型拦截对象包括：复述代码字面行为的注释（// increment counter）、空话填充（// obviously、// clearly、// simply）、无目的的分隔装饰线、对显而易见函数的冗余 JSDoc、无上下文的// TODO:，以及与周边代码矛盾的注释——权威拦截清单在@code-yeongyu/comment-checker侧维护。二进制来源是从固定版本的 GitHub release 下载并缓存，不依赖 npm 依赖或 lifecycle script 信任链；首次 hook 调用时惰性初始化并下载，下载不可用则当前进程优雅禁用。

七、结合源码的快速验证路径

如果你希望亲手验证本核心的行为，仓库提供了现成的测试与命令：

• 解析器测试：apply-patch-edits.test.ts（metadata 数组包装的兼容性验证）；
• 二进制解析测试：runner-resolution.test.ts（非 Error 抛出值的降级契约）；
• 包级测试命令：在 packages/comment-checker-core 下执行bun test src/*.test.ts（见 package.json 的testscript），类型检查用tsgo --noEmit -p tsconfig.json；
• 消费端集成测试：packages/omo-opencode/src/hooks/comment-checker/hook.before-after.test.ts、hook.apply-patch.test.ts与hook.lazy-init.test.ts覆盖了 before/after 全流程、apply_patch 抽取与惰性初始化路径。

从源码结构可以推断：核心层刻意保持「零副作用、纯逻辑」（package.json中"sideEffects": false，唯一依赖是@oh-my-opencode/utils），把「下载二进制、缓存、CLI 编排、pending-call 生命周期」全部留在消费端 hook 层——这保证了两个运行时版本能够以各自最合适的方式复用同一套解析与运行内核。

八、小结

comment-checker-core用约两百行 TypeScript 完成了两件小而关键的事：把不稳定的 LLM 补丁协议解析成稳定的结构化编辑，以及以可注入、可测试、fail-open 的方式驱动外部检查二进制。它的退出码契约（0/2/其他）、双段终止策略（SIGTERM→SIGKILL）、SpawnProcess接口抽象与HookInputschema 对齐，共同支撑起了 oh-my-openagent 在 OpenCode 与 Codex 两个运行时上一致的「AI 废话注释拦截」能力。对于想要在自己的 agent 框架中实现类似「工具后置质量守卫」的开发者，这个模块的解析回退链与进程注入抽象都是值得参考的最小实现范本。

【免费下载链接】oh-my-openagentOmO: Just type "mass ulw" keyword with your prompt. Now you are the master of graph engineering.项目地址: https://gitcode.com/gh_mirrors/oh/oh-my-openagent