企业官网建设流程全解析

OpenCode Review 委托模式（Delegation Mode）实战指南：让宿主 Agent 用自己的 LLM 完成代码审查

【免费下载链接】open-code-reviewFast, efficient, battle-tested at Alibaba's scale. Hybrid architecture code review tool: deterministic pipelines + LLM Agent, precise line-level comments, built-in multi-language ruleset (NPE, thread-safety, XSS, SQL injection), OpenAI & Anthropic compatible.项目地址: https://gitcode.com/GitHub_Trending/op/open-code-review

本文档为委托模式（Delegation Mode）的完整技术指南。委托模式是 OpenCode Review（OCR）为订阅制 AI 编码 Agent 设计的一种集成方式：OCR 只负责文件筛选、规则解析等确定性工程，实际的代码审查推理由宿主 Agent（如 Claude Code、Codex、Cursor、Open Code、Qoder）借助其自身的 LLM 订阅额度完成，OCR 侧完全不调用任何 LLM 端点。读完本文，你将掌握ocr delegate preview/ocr delegate rule两个子命令的完整用法、共享 flag 的语义与限制、JSON 输出契约，以及如何把委托模式接入自己的 Agent 工作流。

什么是委托模式：OCR 做脚手架，Agent 做审查

在 OCR 的三种集成模式中，委托模式是唯一一种「LLM 调用方」不在 OCR 侧的模式：

委托模式的设计动机非常直白：如果你已经在使用按订阅付费的 AI 编码 Agent，那么与其再为 OCR 单独配置一套模型端点（ocr config set …或环境变量），不如直接复用宿主 Agent 已有的订阅额度。OCR 退居幕后，只输出两份「审查规格」（review spec）：

1. ocr delegate preview—— 决定审什么：输出审查模式、ref 元数据和可审查文件清单；
2. ocr delegate rule <path...>—— 提供审查依据：为文件清单解析出按内容分组的审查规则。

从源码结构看，委托模式在 cmd/opencodereview/delegate_cmd.go 中被实现为delegate命令下的两个子命令，其 Long 描述直接点明了设计意图：“Output review spec for host-agent delegation (no LLM required)”。

何时使用委托模式

委托模式针对以下三类场景设计：

1. 你的 AI 编码 Agent 是订阅制，希望复用已有配额做代码审查——无需额外 API Key 或模型配置；
2. 你只想让 OCR 提供工程脚手架（文件过滤、规则解析、排除逻辑），LLM 推理全部交给宿主 Agent；
3. 你在构建自定义 Agent 流水线，需要一个结构化的输入（文件清单 + 规则）来驱动自己的审查步骤。

前置条件

只需安装ocrCLI，无需任何 LLM 配置：

which ocr || npm install -g @alibaba-group/open-code-review

委托模式在 OCR 侧从不调用 LLM，因此不需要ocr config set …，也不需要设置任何模型相关的环境变量。这一点在 skills/open-code-review-delegate/SKILL.md 的compatibility字段中有明确声明：“Does NOT require a configured LLM endpoint — delegation mode is LLM-free on the OCR side”。

安装 Skill / Command

Claude Code —— Command 方式

mkdir -p .claude/commands curl -o .claude/commands/delegate-review.md \ https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/claude-code/commands/delegate-review.md

安装后，Claude Code 中即可通过该命令触发委托模式。命令的 manifest 位于 plugins/open-code-review/claude-code/commands/delegate-review.md，其中内置了完整的五步工作流指引：先ocr delegate preview拿到模式/ref 元数据，再ocr delegate rule获取规则清单，然后按模式构造 git diff 命令逐个文件审查，最后按严重级别分类并自动修复 High/Medium 问题。

任意 Agent —— Skill 方式

推荐使用 skills CLI 安装：

npx skills add alibaba/open-code-review --skill open-code-review-delegate

也可以手动拷贝 manifest：

cp -R /path/to/open-code-review/skills/open-code-review-delegate ~/.claude/skills/

Skill 的完整定义在 skills/open-code-review-delegate/SKILL.md，它是一个纯指令型 skill：不依赖任何外部工具调用，只是把「预览 → 取规则 → 取 diff → 审查 → 报告」这一套协议写清楚，让宿主 Agent 照着执行。

工作流：五步完成委托审查

Step 1：Preview —— 确定要审查什么

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

输出内容包括：

• mode—— workspace / range / commit 三种之一；
• ref 元数据—— from、to、commit、merge_base；
• 可审查文件清单—— 路径、状态、增删行数；
• 被排除文件—— 附排除原因。

常用调用方式：

模式判定逻辑：从 delegate_cmd.go 的reviewMode()实现可以看到，三种模式的优先级是commit>range>workspace：只要提供了--commit就是 commit 模式；否则若--from与--to同时给出则是 range 模式；两者都没有则为 workspace 模式。对应的组合校验在 delegate_helpers_test.go 的TestValidateDelegateOptions中覆盖：from缺to、to缺from、commit 与 range 混用都会被拒绝。

merge_base 的计算：range 模式下，mergeBase()（见 delegate_cmd.go）通过diff.NewProvider计算两个 ref 的合并基点并写入输出。这个merge_base正是 Step 3 构造git diff命令的关键参数；其他模式下它为空字符串。

安全性：loadDelegateContext在加载上下文时会调用validateReviewRefs拒绝 ref 选项注入（见 delegate_cmd.go），防止通过--from/--to/--commit注入恶意参数。

无副作用保证：preview 既不运行也不落盘审查会话。测试 delegate_exec_test.go 中的TestExecuteDelegatePreviewCreatesNoSession专门断言：preview 之后~/.opencodereview/sessions目录不会被创建——因为 preview 阶段根本没有打开持久化。

Step 2：获取文件规则

ocr delegate rule <path1> <path2> ...

把 Step 1 输出的可审查路径作为参数传入。输出按规则内容分组：共享同一条规则的文件会归入同一组，避免重复输出。

分组算法位于 internal/delegate/rulegroup.go 的GroupRules：它要求source（custom/project/global/system）、matched pattern、规则文本三者完全一致才归为同一组（以source\x00pattern\x00text作为分组 key）。也就是说，两条规则文本完全相同但来源不同的文件（例如分别命中项目规则和系统默认规则）会留在不同的组，从而保证每组内Source/Pattern元数据对每个文件都准确。

Markdown 输出由 internal/delegate/format.go 的RuleGroupsMarkdown渲染，每个组以### Rule Group N: <source> / <pattern>标题开头，列出适用文件后给出#### Content规则正文；组之间以---分隔。对应的渲染断言见 internal/delegate/format_test.go。

Step 3：获取 Diff

根据 Step 1 的 mode / ref 信息，直接用 git 取 diff：

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

git diff <merge_base>..<to> -- <path>

Commit 模式：

git show <commit> -- <path>

Workspace 模式：

git diff HEAD -- <path> # 已跟踪文件 cat <path> # 新增的未跟踪文件

注意 workspace 模式下，preview 会把未跟踪文件一并纳入清单；对于这些文件，git diff 拿不到内容，直接读取文件本身即可（整个文件都是新代码）。

Step 4：逐个文件审查

对每个可审查文件：

1. 获取其 diff（Step 3）；
2. 对照其所属 Rule Group 的规则正文（Step 2）作为审查清单；
3. 结合上下文探索工具，进行彻底审查，只评论变更行（+ 行）。

审查维度建议覆盖：正确性、安全性、性能、错误处理、并发、可维护性。对于大型变更，按共享规则与 diff 大小分批处理；不要在发现第一个 High 级问题后就停止。

Step 5：报告

按严重级别分类每个发现：

• Critical/High—— bug、安全问题、数据丢失风险。必须报告；
• Medium—— 性能隐患、错误处理缺口、可维护性问题。带上上下文报告；
• Low—— 风格 nit、小建议。除非明显有价值，否则静默丢弃。

Skill 对输出格式有更严格的要求（见 SKILL.md）：每条评论应遵循path / content / start_line / end_line / category / severity字段结构，其中category取值于bug, security, performance, maintainability, test, style, documentation, other，severity取值于critical, high, medium, low。报告前必须核对每个 preview 文件都已覆盖（reviewed 或带原因的 skipped），并在总结中给出total_files、reviewed_files、skipped_files、coverage_rate。

子命令参考

两个子命令共享同一套 flag 注册逻辑registerDelegateFlags（见 cmd/opencodereview/shared_flags.go）。

共享 Flags

几点需要注意的语义细节：

• --background-file优先于-b：测试 delegate_exec_test.go 的TestLoadDelegateContext_BackgroundFile验证了同时传入两者时，文件内容胜出、内联文本被忽略。
• 背景上下文有双重上限：原始文件不得超过 1 MiB，净化后的内容不得超过 8000 字符，任一超限都会中止命令。正确的恢复姿势是先总结再重试：不要静默截断源文件，而是把原文总结成保留需求、约束、验收标准的精简文本，作为单个 shell 安全参数传入（或用新的小文件传入），并且不要再传--background-file；若无法忠实总结，就直接省略 OCR 背景，在审查时自行阅读原文。
• --format json需要ocrv1.9.0+：如果preview/rule报unknown flag: --format，说明 CLI 版本过旧，去掉该 flag 改用文本输出继续跑完委托流程即可（不要解析文本当 JSON，也不要为其他错误去掉 flag 重试）。需要schema_version等 JSON 字段的程序化集成应先用ocr --version确认版本，必要时npm install -g @alibaba-group/open-code-review升级。这个降级与升级策略在 SKILL.md 的 Troubleshooting 一节有完整说明。
• sarif格式不被委托模式支持：validateDelegateOptions只接受text与json（见 delegate_helpers_test.go 中{"sarif format not supported by delegate", ..., true}用例），flag 的 completion 也只提供这两个枚举值。

JSON 输出契约（Agent 集成要点）

给 Agent 集成时使用--format json。preview的输出封套定义于 delegate_cmd.go，字段包括：

• schema_version—— 当前为"1"（常量delegateSchemaVersion）；
• mode—— workspace / range / commit；
• repository、from、to、commit、merge_base、background；
• total_files、reviewable_count、excluded_count；
• total_insertions、total_deletions；
• reviewable_files[]/excluded_files[]—— 每个条目含path、status、insertions、deletions，被排除的条目还带exclude_reason。

rule的输出封套（delegate_cmd.go）包含schema_version与groups[]，每组含group_id、source、pattern、files、rule。

测试 delegate_exec_test.go 对 JSON 契约做了断言：JSON 数组必须是非 null 的空数组（reviewable_files/excluded_files不能为 null，files同样必须序列化为[]而不是null），方便下游程序化消费。writeDelegateJSON使用带缩进、不转义 HTML 的编码器输出，保证可读性。

与其他集成模式的取舍

回到开头的对比表，三种模式的本质区别在于「谁在调用 LLM」：

• Agent Skill 模式：OCR 驱动完整审查（ocr review），由 OCR 调用 LLM，需要配置模型端点；
• Claude Code Command 模式：斜杠命令形式，同样是 OCR 驱动审查，且带自动修复能力；
• 委托模式：OCR 只做确定性工程，LLM 推理完全由宿主 Agent 承担，OCR 侧零 LLM 配置。

如果你的团队已经在使用订阅制 AI 编码工具，且希望审查逻辑与主开发 Agent 保持同一套「智能」，委托模式是最省配置的集成路径；如果希望审查独立于任何特定 Agent、可复现可审计，则应选择 OCR 自驱的 Agent Skill 或 Command 模式。更详细的对比可参见 Agent Skill 与 Command (Claude Code) 两篇文档。

【免费下载链接】open-code-reviewFast, efficient, battle-tested at Alibaba's scale. Hybrid architecture code review tool: deterministic pipelines + LLM Agent, precise line-level comments, built-in multi-language ruleset (NPE, thread-safety, XSS, SQL injection), OpenAI & Anthropic compatible.项目地址: https://gitcode.com/GitHub_Trending/op/open-code-review