open-code-review-delegate

Open Code Review — 委托模式

一种执行 AI 代码审查的技能，其中 OCR 提供确定性的工程处理（文件筛选、规则解析），而宿主 Agent 使用自身的智能和工具执行实际审查。

工作流

第 1 步：预览 — 确定要审查的内容

ocr delegate preview --format json [--from <ref> --to <ref>] [--commit <hash>] [--exclude <patterns>]

输出包括：

• mode（workspace / range / commit）
• from / to / commit / merge_base — 用于构造 git 命令的 ref 元数据
• 可审查文件列表 — 路径、状态、插入/删除行数
• 被排除的文件 — 附排除原因

常见调用方式：

场景	命令
工作区变更	ocr delegate preview
分支比较	ocr delegate preview --from main --to feature
单个提交	ocr delegate preview -c abc123

第 2 步：获取文件的规则

ocr delegate rule --format json <path1> <path2> ...

传入第 1 步中得到的可审查文件路径。输出按规则内容分组 — 共享同一规则的文件会出现在同一组下，避免重复。

第 3 步：获取差异

使用第 1 步中的 mode 和 refs 选择 diff 命令。审查期间每次调用 Git 都使用 git --no-pager。

这些 diff 命令会禁用外部 diff 程序、文本转换和颜色，以生成纯文本补丁。

Range 模式（预览输出中提供了 merge_base）：

git --no-pager diff --no-ext-diff --no-textconv --no-color <merge_base>..<to> -- "<path>"

Commit 模式：

git --no-pager show --no-ext-diff --no-textconv --no-color <commit> -- "<path>"

Workspace 模式：

# Tracked files
git --no-pager diff --no-ext-diff --no-textconv --no-color HEAD -- "<path>"
# New untracked files — read directly (entire file is new code)
cat "<path>"

读取上下文：

git --no-pager log --no-color --oneline -- "<path>"
git --no-pager blame --no-textconv -- "<path>"
git --no-pager show --no-ext-diff --no-textconv --no-color "<ref>:<path>"

对于大型 diff，在所选模式的命令中添加 --output="<absolute-diff-file>"。选择一个仓库之外的唯一绝对路径，并创建其父目录。在文件读取工具调用中使用相同的路径：

git --no-pager diff --no-ext-diff --no-textconv --no-color --output="<absolute-diff-file>" <merge_base>..<to> -- "<path>"

在 Git 以代码 0 退出后，分块读取并审查整个文件，然后将其删除。如果 Git 失败或超时，请重试，或记录为 skipped 并附上错误信息。将意外为空的输出与最新的预览进行核对。

第 4 步：审查每个文件

创建一个包含每个 reviewable_files 条目的检查清单。对于每个可审查文件：

使用 (path, status) 作为检查清单的标识。当暂存删除之后又发生未跟踪的重新创建时，Workspace 模式可能报告同一路径两次。

1. 获取其 diff（第 3 步）
2. 查阅其规则分组（来自第 2 步）以获取审查检查清单
3. 进行全面审查，按需使用适当的上下文工具
4. 将文件标记为 reviewed，或标记为 skipped 并附上具体原因

对于大型变更，按共享规则和 diff 大小分组，分批进行有界审查。不要找到第一个高严重性问题后就停止。

第 5 步：格式化输出

每条评论必须遵循以下结构：

字段	类型	必填	描述
path	string	是	相对文件路径
content	string	是	描述问题的审查评论
start_line	integer	否	新文件中的起始行
end_line	integer	否	新文件中的结束行
category	enum	否	bug、security、performance、maintainability、test、style、documentation、other
severity	enum	否	critical、high、medium、low

第 6 步：分类并报告

在报告之前，确认每个已预览的文件都已纳入统计。在摘要中包含 total_files、reviewed_files、skipped_files 和 coverage_rate。被跳过的文件必须包含其原因。

按严重性对发现进行分组：

• Critical/High：Bug、安全问题、数据丢失风险 — 始终报告
• Medium：性能问题、错误处理缺口、可维护性问题 — 附上下文报告
• Low：风格细节、次要建议 — 仅在明显有价值时报告

静默丢弃可能的误报。

第 7 步：修复（可选）

如果用户要求“审查并修复”：

• 直接应用 High/Critical 的修复
• 描述需要人工干预的 Medium 修复
• 跳过低优先级项目，除非其微不足道

子命令参考

命令	用途
ocr delegate preview	需要审查哪些文件 + 模式/ref 元数据
ocr delegate rule <path...>	按内容分组的审查规则

通用标志

标志	描述
--from <ref>	范围模式的源 ref
--to <ref>	范围模式的目标 ref
-c, --commit <hash>	单提交模式
--repo <path>	仓库根目录（默认：当前工作目录）
--rule <path>	自定义 rule.json 路径
--exclude <patterns>	逗号分隔的排除模式
-b, --background <text>	业务上下文
-B, --background-file <path>	从 Markdown 文件读取业务上下文（优先于 -b）
-f, --format <text|json>	输出格式；使用 json 以便与 Agent 集成

注意事项

• OCR 侧无需大模型 — 委托模式从不调用大模型。所有智能均来自宿主 Agent。
• 规则会分组 — 共享同一规则的文件会在输出中归为一组。每次调用可传入任意数量的路径；对于大型变更，可在审查过程中按批次获取规则。
• 工作目录很重要 — ocr delegate 操作当前目录下的 Git 仓库。使用 --repo /path 可覆盖。
• 工作区模式下的未跟踪文件 — preview 会包含未跟踪文件。对于这些文件，请直接读取文件而不是使用 git diff。
• 背景上下文 — 当你有需求上下文时，向 preview 传入 --background；它会出现在输出中，供你在审查期间参考。
• 覆盖率是强制要求 — 每个 reviewable_files 条目最终都必须标记为已审查或明确跳过；不要静默省略文件。

恢复过大的背景上下文

--background-file 有两个独立的限制。原始文件不得超过 1 MiB，且净化后的内容不得超过 8000 个字符。任一 条件都会中止命令。当命令报告任一限制时：

1. 不要静默截断源文件。
2. 对原始材料进行摘要，同时保留其需求、 约束、验收标准以及其他对审查至关重要的细节。
3. 通过将摘要作为一个 shell 安全的 参数传入来重试受影响的命令（例如，使用宿主 shell 生成带引号/转义的参数，或将其写入一个新的有大小限制的文件并传入该文件）。不要 将不可信的摘要文本直接放入双引号 shell 模板中； $()、反引号、引号和变量引用仍可能被求值。 省略原来的 --background-file，以免 CLI 重新加载同一个 过大文件并再次失败。
4. 如果无法忠实摘要，请完全省略 OCR 背景， 并在审查期间直接阅读原始材料。

CLI 版本兼容性故障排除

--format 标志在 ocr v1.9.0 及更高版本中可用。Skill 与 已安装的 CLI 可以独立更新。如果请求的 preview 或 rule 命令带 --format json 时特别因 unknown flag: --format 而失败， 请在不带该标志的情况下重新运行，并在本次委托 运行的其余部分使用文本输出。请保留该输出中的显式模式、ref、文件和规则信息； 不要将文本输出解析为 JSON，也不要臆造缺失的 schema 字段。 对于任何其他错误，不要在不带该标志的情况下重试；请报告错误并停止受影响的 工作流。

宿主 Agent Skill 可能会使用等效的文本输出来完成其 审查清单。需要 schema_version 或其他 JSON 字段的 程序化集成则必须要求具备 JSON 能力的 CLI：使用 ocr --version 验证，并在必要时升级：

npm install -g @alibaba-group/open-code-review