comment-review (cmr)

确定性注释审查 Harness。提取注释、检测过程性污染（日期、版本、评审历程、人物归因）、输出分级审查规范，由宿主 agent（ZCode/Codex/Claude Code）完成最终判别。

架构参考 alibaba/open-code-review 的 Delegation Mode：程序决定审什么，agent 负责推理。

判别准绳

注释回答"现在为什么是这样"，不叙述"怎么变成现在这样的"。 变更日期、版本历程、驳回定稿、人物归因的合法归宿是 git 提交消息。 例外：表达业务规则生效条件的日期（"自 2026 年 3 月起…"）是约束，保留但改写为无过程痕迹的陈述。

用法

cmr scan                          # 全库注释审计
cmr diff                          # 工作区新增/变化注释
cmr diff --from main --to feat/x  # 分支增量
cmr diff --commit <hash>          # 提交相对第一父提交的增量
cmr rules <file>...               # 查看规则解析
# 通用旗标：--format text|json  --min-severity p0|p1|p2|all  --rule <file>  --path <dir>

未全局安装时，将 cmr 替换为 node bin/cmr.js。运行 npm test 执行回归测试；无需安装第三方依赖，Git 相关用例使用独立临时仓库。

scan 可用于没有 Git 的目录，diff 需要 Git 仓库。工作区增量比较当前磁盘内容与 HEAD，并包含未跟踪文件；无首次提交时以空内容为基线。分支范围使用 merge-base(from, to) 到 to，提交模式使用第一父提交到目标提交。历史模式从 Git 对象读取源码和引用文件清单，不受工作区脏文件影响。

--path 限定文件或子目录，引用检查仍使用整个根目录的清单。diff 从子目录运行时自动定位 Git 根；显式相对路径仍以调用目录为准。严重级别大小写均可，p1 表示保留 P0 和 P1，all 包含 INFO。参数错误退出码为 2，读取/配置/Git 错误为 1；正常生成报告为 0，即使存在候选也不作为 CI 失败门禁。

分级语义

级别	判定	处置
P0	日期+过程信号 / 修订记录标题 / 强过程动词 / 确认失效引用	删除候选（git 已有历史）
P1	人物归因 / 新旧对比 / 方案演变 / 版本+过程 / 引用待核实	拆分改写：留约束、抹过程；引用按证据核实
P2	仅日期/版本	判别业务生效日 vs 变更日期
INFO	TODO/FIXME	台账（含截止日期）

规则分层（同 ocr 语义）

CLI --rule > 项目 .commentreview/rule.json > 用户 ~/.commentreview/rule.json > 内置。 Schema：{"rules":[{"path":"<glob>","rule":"<markdown>","merge_system_rule":true}],"excludes":["generated/**"]}，首个匹配 glob 生效。

按优先级选择首个存在的配置文件，不跨文件合并；项目配置向父目录查找。历史审查也使用当前配置。显式指定的规则文件不存在、JSON 或字段类型错误时会报错。

glob 支持 **、*、?，忽略大小写，不支持否定或花括号展开。excludes 相对于扫描根目录，仅排除审查候选，不移除引用目标。rules 输出匹配来源及完整规则文本，也支持 --format json。自定义规则文本交给宿主 agent，不改变内置正则候选检测器。

悬空引用：确认失效 vs 待核实

"本地找不到"不等于"注释错了"。引用分两级，每条候选附查找依据（仓库相对路径、源文件同目录、全库同名）与近似候选：

• 确认失效（P0）：仅在有结构性证据时判定——同名文件在别处、同干不同扩展名、文件名仅数字差异（疑似移动/改名），或目标目录存在而文件不在（疑似删除）。
• 待核实（P1，unverified_ref）：仓库外绝对路径与 ~ 家目录、构建/依赖目录（dist、lib、node_modules 等，本就不在清单内）、跨仓或仓库外的裸文件名（无法区分外部文件与已删除文件）、中英混排的疑似描述性文字。可选配置、生成产物、跨仓引用完全合法，由 agent 按证据定夺。

带目录路径按根目录或源文件目录解析，裸文件名允许全库同名匹配；URL 和引号内示例忽略；不校验章节与远端资源。

判定基线（人工样例库）

testdata/corpus/ 收录 56 条来自真实仓库审查的人工判定样例，分四类：过程记录（必须检出且级别一致）、业务约束/正常说明（不得误报）、待核实（必须以 P1 附证据列出）。test/corpus.test.js 输出分类记分卡并作为回归门禁：调整检测规则前后运行 npm test，防止修一类注释误伤另一类。判定先于工具输出记录，新增样例流程见 testdata/corpus/README.md；样例放在 test/ 之外，避免被测试执行器误当作测试。

以下上下文已按样例库裁决自动豁免：「兼容旧版 X」（存活兼容要求）；旧版/新版锚定业务对象（流程定义/节点/入口/路由/浏览器/钉钉等外部产品）；字段枚举文档（"外文版本：1是，0否"——版本 为更长业务词的尾部）；格式示例日期（"例如 2023年7月"、"格式 YYYY-MM，如 2026-08"）；库能力版本（"3.5.0 版本 增加 xxx"）；流程位置的"后续会签"；角色/操作词"副总/副总经理/汇总/手工/人工"（非人名称谓）；用法行尖括号占位符 <flow.json> 不算文件引用。

已知边界

• 提取器是轻量状态机，不含完整语法树：支持转义引号、多行模板字符串、Java 文本块和常见 Python 三引号文档；JS 正则、模板插值内注释、Vue/JSX 混合语法、Shell heredoc、YAML 块标量仍需人工核对。独立 Python 三引号按文档候选处理，不判定其是否处于合法 docstring 位置
• 增量按每个文件的注释文本及出现次数比较，移动注释不算新增；纯重命名按新文件处理。注释内容不变但所引用文档被删时，应运行 scan 检查全库
• 跳过符号链接/目录联接和常见构建目录，避免循环遍历。统计 files 为实际读取的支持语言文件数；读取失败直接报错，不输出假成功
• 悬空引用两级判定与证据输出见上文专节；正则候选仍不校验章节与远端资源
• CRUD 动词（新增/修改/删除）单独出现视为接口描述不告警，仅作组合证据
• 驳回/评审等词在 OA/工作流域是业务术语，已从过程词表移除

部署

npm i -g <本工程路径>          # 本机
# dev: scp 工程到 ~/work/tool/comment-review 后 npm i -g ~/work/tool/comment-review

配套 skill：~/.agents/skills/comment-review/SKILL.md（判别流程与输出格式）。 审查报告样例：reports/*.md。