oh-my-openagent 的 comment-checker-coreapply-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承担两项正交职责解析职责把 LLM 输出的 apply-patch 编辑文本*** Add/Update/Delete File:协议解析为结构化CheckerEdit[]从而知道「这次改动到底动了哪些文件的哪些内容」运行职责以子进程方式运行外部二进制code-yeongyu/comment-checker把待检查内容通过 stdin 以 JSON 形式喂给它再读取 stdout/stderr 判定是否存在「AI-slop comments」。关键的架构决策在于派生进程是依赖注入的SpawnFn而非直接使用child_process.spawn。这样做的收益很直接omo-opencodeBun 运行时与 omo-codexCodex 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 一节Export实现源文件职责parseApplyPatchRequests(patch)apply-patch-edits.ts解析*** Add/Update/Delete File:与*** Move to:协议配合上下文行与/-标记产出CheckerEdit[]extractApplyPatchEdits(details, args?)同上高层抽取器优先读 metadata 文件否则回退到 patch 文本patchText/input/patch/command键getApplyPatchMetadataFiles(details)同上从嵌套的details.files/result.files/metadata.files中读取结构化文件元数据resolveCommentCheckerBinary(input)runner.ts通过createRequire定位code-yeongyu/comment-checker的二进制路径runCommentChecker(input, options)同上把HookInputJSON 写入子进程 stdin读取 stdout/stderr返回CheckResult此外index.ts还导出了若干内部辅助函数getString、isRecord、joinPatchLines、makeAccumulator、readApplyPatchMetadataFiles以及 17 个类型CheckerEdit、HookInput、CheckResult、SpawnFn/SpawnProcess/SpawnSignal、ApplyPatchFileMetadata等全部定义在 types.ts。核心类型速览CheckerEdit解析结果的最小单元{ filePath, before, after }三段式即「哪个文件改前内容改后内容」ApplyPatchFileMetadatametadata 形态的编辑描述除三段式外还可携带movePath文件移动目标与type操作类型CheckResult运行结果{ hasComments: boolean, message: string }HookInput喂给外部二进制的输入 JSON其字段镜像 OpenCodetool.execute.before的输入 schemasession_id、tool_name、transcript_path、cwd、hook_event_name、tool_input、tool_responseSpawnFn/SpawnProcess/SpawnSignal抽象出的进程接口见第四节。三、apply-patch 解析器从协议文本到结构化编辑解析器位于 apply-patch-edits.ts是整个核心最「算法化」的部分。它的输入是 LLM 输出的一段 apply-patch 协议文本输出是CheckerEdit[]。3.1 支持的操作指令parseApplyPatchRequests逐行扫描 patch 文本按/\r?\n/切分兼容 CRLF 与 LF识别以下指令对应核心 AGENTS.md 中的协议描述指令语义处理逻辑*** Begin Patch/*** End Patch补丁起止围栏直接跳过*** Add File: path新增文件累积newLinesflush 时生成{ filePath, before: , after }*** Update File: path更新文件分别累积-行oldLines与行newLinesflush 时生成{ before, after }*** Delete File: path删除文件不产出CheckerEdit删除没有可检查的「新内容」*** Move to: path文件移动目标仅在当前操作是 update 时生效写入current.movePath最终以movePath ?? filePath作为输出路径开头hunk 上下文头跳过前缀行新增行add 操作下收集进newLinesupdate 操作下同样收集进newLines-前缀行删除行仅 update 操作下收集进oldLines有一个值得注意的细节*** Delete File:指令本身会被记录进 accumulator但 flush 时不会产出编辑delete 分支没有任何 push 逻辑。这是合理的——删除操作不产生新代码自然无需做注释检查。另一个细节是joinPatchLines解析出的行数组在拼回字符串时会统一追加结尾换行lines.length 0 ? : lines.join(\n) \n且 add 操作若最终没有有效内容after 为空也会被丢弃避免产出空编辑。3.2 三段式 flush 模型ApplyPatchAccumulator解析过程使用一个状态机式的 accumulatorApplyPatchAccumulator同样定义在 types.ts{ operation, filePath, movePath?, oldLines, newLines }。每当遇到新的*** Add/Update/Delete File:指令先flush()掉上一个文件块的累积结果再创建新的 accumulator——这正是makeAccumulator的职责。3.3 高层抽取器与 metadata 回退链extractApplyPatchEdits(details, args?)给出了更「务实」的抽取策略优先级如下先尝试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等多套字段别名metadata 中type为delete大小写不敏感的文件会被过滤掉不参与检查若 metadata 文件非空直接映射为CheckerEdit[]返回移动文件用movePath ?? filePath作为最终路径若 metadata 为空回退到args中的 patch 文本依次尝试patchText、input、patch、command四个键getString按序取第一个字符串值再交给parseApplyPatchRequests两者都拿不到就返回空数组。这一设计的价值在于兼容不同的 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)的解析顺序是缓存路径优先若cachedBinaryPath非空且existsSync确认文件存在直接返回省去每次模块解析开销createRequire 探测以importMetaUrl为基准构造createRequirerequire.resolve(code-yeongyu/comment-checker/package.json)拿到包根目录再拼上bin/binaryName子路径只有existsSync确认存在才返回降级返回 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 runCommentCheckerJSON-in、stdout/stderr-out 的进程契约runCommentChecker(input, options)的执行流程前置守卫binaryPath为 null 或文件不存在时直接返回EMPTY_RESULT{ hasComments: false, message: }拼装参数[binaryPath, check]若传入customPrompt则追加--prompt prompt写入输入把HookInput序列化为 JSON 写入process.stdin并end()并发竞速同时等待三个 Promise——stdout 文本、stderr 文本、exited退出码——并与超时 Promise 进行Promise.race按退出码判定结果这就是核心 AGENTS.md 强调的exit-code contract。退出码契约总结如下normalizeMessage会先把\r\n归一化为\n退出码语义返回结果0干净无问题注释{ hasComments: false, message: }2检测到问题注释{ hasComments: true, message: normalizeMessage(stderr) }其他任意码 / 超时 / 运行错误视为不可信结果静默返回{ hasComments: false, message: }注意这个「fail-closed 还是 fail-open」的取向任何非 0、非 2 的异常退出都按「无注释」处理fail-open避免二进制自身崩溃或环境问题阻断正常工具调用——代价是异常情况下检查被静默跳过这与 hook 层「CLI 不可用则优雅跳过」的整体策略一致。4.3 超时与优雅终止SIGTERM → SIGKILL 升级核心 AGENTS.md 明确了两组数字默认超时 30 秒timeoutMs ?? 30_0001 秒 kill 宽限期killGraceMs ?? 1_000。超时触发后的终止路径是两段式升级先发SIGTERM给进程一个「收拾残局」的机会等待killGraceMs毫秒后若进程仍未退出再发SIGKILL强制终结。killProcessSafely对 kill 调用本身做了 try/catch 防御例如进程已自行退出时 kill 可能抛错。定时器与清除函数同样可注入setTimeoutFn/clearTimeoutFn便于在测试环境中用假时钟控制时序。竞速过程中一旦超时胜出立即返回EMPTY_RESULTfinally块中会清掉尚未触发的定时器避免悬挂。4.4 SpawnProcess刻意不用 Node ChildProcess 的注入接口这是该核心最值得一提的抽象。SpawnProcesstypes.ts 中的定义只暴露运行检查所需的极小子集type SpawnProcess { stdin: { write(input: string): void; end(): void } stdout: ReadableStreamUint8Array stderr: ReadableStreamUint8Array exited: Promisenumber kill(signal: SpawnSignal): void }它刻意不是Node 的ChildProcess类型而是把 NodeChildProcess的stdoutReadable适配为 Web 标准的ReadableStreamUint8Array。这带来两个直接好处runCommentChecker内部可以用new Response(process.stdout).text()这类 Web API 读取输出无需依赖 Node 专属的事件 API从而让同一份核心代码在 Bunomo-opencode与 Codex plugin 运行时中都成立测试时可以注入完全内存化的假进程stdin记录写入内容exited返回预设退出码从而无需真的拉起二进制即可验证退出码契约与超时逻辑。SpawnFn (args: readonly string[]) SpawnProcess则是「进程工厂」RunCommentCheckerOptions.spawn字段就是它的注入点。五、HookInput镜像 OpenCode schema 的跨环境输入契约核心 AGENTS.md 特别强调HookInput与 OpenCodetool.execute.before的输入 schema 完全一致。HookInput的字段包括session_id会话 IDtool_name触发的工具名如write、edit、apply_patchtranscript_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里以多别名方式抽取filePathfilePath/file_path/path、oldStringoldString/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.tsmetadata 数组包装的兼容性验证二进制解析测试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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考