前端团队 Review 指南（open-code-review 版）

前端团队的 Code Review 长期卡在同一个矛盾上：该查的东西很多，能投入的人很少。异步函数没有 catch、innerHTML 直接插了用户输入、Hooks 依赖没写全------这些「跑起来才炸」的问题靠人眼盯不稳定。把 diff 一股脑丢给通用 AI Agent 也有另一组问题：文件一多它只挑一部分看，报出来的问题落不到对应代码行，同样的代码两次审查结论还不一致。

Open Code Review（下称 OCR，阿里开源）把文件筛选、分组、规则匹配、评论定位交给确定性工程逻辑，LLM 只负责理解上下文。对前端团队更实用的是：审查可以委托给你已经在用的 AI 编程 Agent------Trae、Claude Code、Cursor 用自己的模型干活，OCR 只负责「审哪些文件、按什么规则审、评论落哪一行」，不需要为 OCR 单独购买或配置任何 API。

下面按顺序走完整个配置：装工具、写规则、跑第一次审查、加 CI 门禁。每一步都有命令和预期输出，照着敲就行。

一、开工前先搞懂：谁查什么

四个层次各管一段，不要让 OCR 干别的工具的活：

层次	负责	不负责
ESLint / Prettier	代码规范：缩进、分号、命名、导入顺序	语义缺陷
TypeScript 类型检查	类型错误、空值可能	运行时逻辑
OCR（语义审查）	语义缺陷：错误处理缺失、XSS 风险、竞态条件	格式、架构决策
人工 Review	架构决策、业务正确性、可维护性取舍	逐行格式检查

别让 OCR 承担 ESLint 已经覆盖的格式检查，那只会产生噪音，让开发者对审查结果失去信任。

对产出也要有正确预期。官方 Benchmark（50 个开源仓库、200 个真实 PR、1505 条人工交叉验证的缺陷标注）显示：相同模型下 OCR 精度约为通用 Agent 的 4.7 倍、token 消耗约 1/9，但召回率更低------这是刻意取舍：宁可少报，报出来的都是真问题。所以 OCR 是「低噪音高精度」的第一道过滤器，不能替代人工全量把关。

二、第 1 步：环境自检

OCR 依赖 Git 做 diff 生成和仓库操作，要求 Git ≥ 2.41，低于此版本会直接不可用：

bash 复制代码

git --version
# 预期输出类似：git version 2.46.0 ------ 主版本号 ≥ 2.41 即可

npm 安装方式还需要 Node.js 环境（装有 npm 即可）；没有 Node 也没关系，下一步有不需要 Node 的安装方式。

三、第 2 步：安装 ocr CLI

三种方式任选其一。

方式 A：npm（推荐）

bash 复制代码

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

npm 方式默认自动保持最新（后台静默升级，检查间隔 18 分钟）。不想要自动更新：

bash 复制代码

export OCR_NO_UPDATE=1    # 写进 ~/.zshrc 或 ~/.bashrc

方式 B：Homebrew（macOS / Linux）

bash 复制代码

brew install open-code-review

方式 C：安装脚本（无 Node 环境时）

bash 复制代码

# macOS / Linux
curl -fsSL https://open-codereview.ai/install.sh | sh

# Windows（PowerShell 5.1+）
irm https://open-codereview.ai/install.ps1 | iex

验证安装：

bash 复制代码

ocr version
# 预期输出：版本号 + Git commit + 平台 + 构建日期

OCR 在你机器上放了什么（想干净卸载，删掉 ~/.opencodereview/ 目录即可，不会碰你的项目）：

路径	内容
`~/.opencodereview/config.json`	模型端点、语言等配置（委托模式基本用不到）
`~/.opencodereview/rule.json`	可选的全局个人规则
`~/.opencodereview/sessions/`	每次审查的完整记录（供 viewer 回放）
`<项目>/.opencodereview/rule.json`	项目级规则（第 6 步要写的，可提交入库）

四、第 3 步：选执行模式------本指南走委托模式

OCR 有两种执行模式，先选对再往下走：

	Default	Delegation（委托）
谁执行审查	OCR 调用自己配置的 LLM	你的 AI 编程 Agent 用自己的模型
OCR 的职责	全流程	只做文件选择、分组、规则匹配
是否需要给 OCR 配模型	需要	不需要
计费	按 token 走 OCR 的 provider	走 Agent 已有的订阅或额度
适用场景	无人值守的 CI 门禁	日常开发中人在回路

本指南主线走委托模式：团队已经在用 AI 编程 Agent 写代码，审查算力直接复用 Agent 的订阅额度，OCR 侧不用配任何模型。要配模型的只有第 9 步的 CI 门禁。

避开一个坑：不要把 OCR 的 provider 直接指向各家编码订阅套餐（如 GLM Coding Plan）的端点。这类套餐普遍限制「仅官方支持的客户端使用、禁止自动化批量处理」，直连会被拒，或者绕过套餐额度按 token 扣账号余额。想让订阅额度参与审查，正解就是委托模式。

五、第 4 步：配置你的 AI Agent（委托宿主）

用 skills CLI 安装（通用）

OCR 的委托技能可以用官方 skills CLI 一条命令装进支持的客户端：

bash 复制代码

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

装完后重启客户端（或新开会话），Agent 就能通过这个技能调用 ocr 完成委托审查。凡是支持 skills 规范的 Agent 都适用，这是最省事的接入方式。

用客户端原生插件安装

Claude Code------在 Claude Code 会话里执行两条命令：

text 复制代码

/plugin marketplace add alibaba/open-code-review
/plugin install open-code-review@open-code-review

装完输入 / 应能看到 open-code-review 相关命令。

Codex：

bash 复制代码

codex plugin marketplace add alibaba/open-code-review
# 然后在 /plugins 中启用 Open Code Review

Cursor ：把仓库 plugins/open-code-review/ 目录复制到 ~/.cursor/plugins/local/open-code-review/，重载窗口。

以上任一方式装完，重启客户端（或新开会话）让技能加载。之后对 Agent 说「用委托模式审查我的改动」即可触发------SKILL.md 把委托流程的每一步都写给了 Agent。

如果 Agent 里同时装有只支持 Default 模式的旧版 open-code-review 技能（里面全是 ocr review），而 OCR 没配模型，它会一跑就报错，还容易和委托技能抢触发。禁用旧技能，只留委托技能。

验证委托链路已就绪（不花 token）。在任意一个 Git 项目里跑：

bash 复制代码

cd 你的前端项目
ocr delegate preview

预期输出（真实格式）：

text 复制代码

# Files (N reviewable / M total)

- mode: workspace
- ......文件清单，每行带 [modified] +行数/-行数
~~- `docs/xxx.md` [modified] +4/-3 (excluded: unsupported_ext)~~

能列出文件清单和排除原因，说明 OCR 的「审前工程」部分已就绪，与是否配了模型无关。

六、第 5 步：写项目规则 `.opencodereview/rule.json`

6.1 先知道一个必踩的坑

OCR 内置语义规则只匹配 **/*.{ts,js,tsx,jsx,mjs,cjs}，没有 **/*.vue 这一条。不自己补规则，Vue 项目里最核心的 .vue 单文件组件会全部落进无差别的 default 规则，拿不到任何针对性检查。前端项目接入，第一件事就是把 Vue 规则写进去。

6.2 创建规则文件

在项目根目录创建 .opencodereview/rule.json（可直接抄，按自己项目调整路径）：

json 复制代码

{
  "exclude": [
    "**/__mocks__/**",
    "**/generated/**",
    "**/*.stories.tsx"
  ],
  "rules": [
    {
      "path": "**/*.vue",
      "rule": "Vue 组件审查清单：1) 禁止 v-html 直接渲染用户输入，用户输入必须转义或用文本插值；2) computed 中禁止产生副作用（API 调用、修改外部状态）；3) v-for 必须绑定稳定 key，禁止用 index 作为动态列表的 key；4) beforeUnmount 中清理定时器、事件监听和第三方实例；5) props 必须声明类型与默认值；6) watch 异步回调必须有错误处理。"
    },
    {
      "path": "src/utils/**/*.{js,ts}",
      "rule": "工具与请求层审查：所有异步函数必须有 try/catch 或等价错误处理并向调用方传递错误；禁止业务硬编码（URL、数字常量）；注意竞态条件（并发请求乱序返回）；空值取值前必须判空。"
    },
    {
      "path": "src/**/*.{js,ts,tsx,jsx}",
      "rule": "通用前端审查：禁止 var，一律 const/let；禁止 ==/!=，一律 ===/!==；不允许嵌套三元；禁止 eval() 和 Function() 构造函数；死代码（不可达分支、未使用变量、大段注释代码）要指出。"
    }
  ]
}

写完提交入库（git add .opencodereview/rule.json），全团队共用同一套标准。

6.3 字段语义（准确版）

rules 是 {path, rule} 数组，按声明顺序求值，第一个 path glob 命中的条目决定该文件用哪份清单审。所以越具体的规则放得越靠前（上面顺序：.vue → utils → 通用）。默认命中用户规则会替换内置系统规则；想让两者叠加，在该条目上加 "merge_system_rule": true。
exclude 是禁止审查的模式。测试文件（*.test.*、*.spec.*、__tests__）、node_modules、dist、.next、.nuxt 等已被内置默认排除覆盖，不用重复写，只补充项目特有的噪音目录。
include 不是白名单，而是绕行通道：命中它的文件会跳过 unsupported_ext、default_path 两道内置闸门，用于拯救被误杀的文件。
硬保护：.env 及其变体、.ssh、.npmrc 等密钥路径永不审查，include 也救不回来。

6.4 验证规则：零 token、秒级返回

bash 复制代码

# 看每个文件最终命中哪条规则
ocr delegate rule src/utils/request.js src/views/example/index.vue

预期输出（真实格式）：

text 复制代码

### Rule Group 1: project / **/*.vue

Applies to:
- src/views/example/index.vue

#### Content

Vue 组件审查清单：1) 禁止 v-html 直接渲染用户输入......

---

### Rule Group 2: system / **/*.{ts,js,tsx,jsx,mjs,cjs}

Applies to:
- src/utils/request.js

#### Content

#### Code Quality Checks
- **Variable Declarations**: Using `var` is strictly prohibited ......

核对三件事：.vue 文件命中了你写的 project / **/*.vue 组（而不是 default）；应该被排除的文件没出现在清单里；规则全文是你要的标准。这一步过关，清单才算真正生效。

七、第 6 步：跑第一次委托审查

以「审查一次功能提交」为例，从命令到拿到评论的完整过程。

第 1 步：拿到待审文件清单

bash 复制代码

ocr delegate preview -c <commit-id>     # 审某个提交
ocr delegate preview                    # 审当前工作区未提交的改动

预期输出（真实格式）：

text 复制代码

# Files (9 reviewable / 11 total)

- mode: commit
- commit: 4414b64b8
- background: fix(request): 请求层缺陷修复与缓存加固
- total_insertions: 119
- total_deletions: 88

~~- `AGENTS.md` [modified] +3/-1 (excluded: unsupported_ext)~~
  - `src/api/commApi/xdApi.js` [modified] +2/-1
  - `src/utils/apiCache.js` [modified] +24/-21
  - `src/utils/request.js` [modified] +74/-50
  - `src/views/legalAffairs/toolBox/onlineOutsource/index.vue` [modified] +2/-2
  - ......

读法：mode 是审查范围类型（workspace 工作区 / commit 单提交 / range 分支区间）；提交信息被自动提取为 background 审查背景；划线的是被排除文件及原因（unsupported_ext = 扩展名不支持，Markdown 文档本就不该进代码审查）。

第 2 步：拿到按规则分组的审查清单

bash 复制代码

ocr delegate rule <第 1 步列出的文件...>

输出即 6.4 节展示的 Rule Group 列表，连同文件清单一起交给 Agent。

第 3 步：Agent 取 diff 。由宿主 Agent 自己执行 Git，按 mode 对应取法：

mode	diff 取法
`workspace`	`git diff HEAD`（未跟踪的新文件直接读全文）
`commit`	`git show <commit-id>`
`range`	`git diff <merge-base>..<to-branch>`

第 4 步：逐文件审查。Agent 对照规则清单逐文件读 diff（文件多时分批），每个发现输出结构化定位：

text 复制代码

- path: src/utils/request.js
  start_line: 87
  end_line: 92
  category: 错误处理
  severity: high
  content: 请求拦截器的错误分支缺少 return，错误被吞掉后后续 .then 仍会以 undefined 继续执行

全部文件过完后按严重度（critical → high → medium → low）分组汇报，要求 100% 文件覆盖------不挑文件、不漏文件、评论落到行，这是和「把 diff 扔给 AI 一把过」的本质区别。

装了技能的 Agent 里，以上四步是一句话的事：对 Agent 说「审查这次提交」，它会自动走完全程。你要做的只是读结果：确认哪些是真问题（让 Agent 当场修，修完说「再审一轮」），哪些是误报（记下来，回填到下一节的规则调优里）。

八、第 7 步：规则持续调优

上线初期一定有噪音，迭代方法是：

先诊断再改：ocr delegate rule <误报文件> 看它命中了哪条规则，再决定改哪条，不盲改。
扩大 exclude：补充内置清单没覆盖的项目特有目录（__mocks__、locales、纯样式目录等）。
细化 rules 路径：请求层、工具层、组件层分开配规则，各自聚焦各自的毛病；顺序敏感，具体的放前面。
用 include 拯救误杀：确需审查被内置默认排除的文件，加进 include 绕过（密钥路径除外）。
临时换规则：单个 PR 需要不同侧重点时，ocr review --rule ./.review-for-this-pr.json。

九、第 8 步（可选）：CI 门禁

CI 是无人值守场景，只能走 Default 模式------这是全文唯一需要给 OCR 配模型凭据的地方。跳过本节不影响前面所有步骤的日常使用。

9.1 先在本机验证模型凭据可用（拿着公司买的 API Key，任选一种配置方式）：

bash 复制代码

# 交互式配置：选 Provider、填 Key、自动测连通性
ocr config provider
ocr config model
ocr llm test        # 预期输出连通性通过

或非交互式（以 Anthropic 为例）：

bash 复制代码

ocr config set llm.url https://api.anthropic.com/v1
ocr config set llm.auth_token your-api-key
ocr config set llm.model claude-opus-4-6
ocr config set llm.protocol anthropic   # anthropic / openai / openai-responses

9.2 配置 GitHub Actions 。仓库 Settings → Secrets and variables → Actions 中添加两个 Secret：OCR_LLM_URL（LLM API 端点）、OCR_LLM_AUTH_TOKEN（API 密钥）；可选 Variable：OCR_LLM_MODEL（模型名）、OCR_LLM_USE_ANTHROPIC（true 时用 Anthropic 协议）。GITHUB_TOKEN 自动提供，workflow 里声明 pull-requests: write 即可发评论。

下载官方 workflow 模板（评论发布是官方 Action 的内置能力）：

bash 复制代码

mkdir -p .github/workflows
curl -o .github/workflows/ocr-review.yml \
  https://raw.githubusercontent.com/alibaba/open-code-review/main/examples/github_actions/ocr-review.yml

模板内部调用形式如下，可按需调整参数：

yaml 复制代码

- uses: alibaba/open-code-review@main
  with:
    llm_url: ${{ secrets.OCR_LLM_URL }}
    llm_auth_token: ${{ secrets.OCR_LLM_AUTH_TOKEN }}
    llm_model: ${{ vars.OCR_LLM_MODEL }}
    llm_use_anthropic: ${{ vars.OCR_LLM_USE_ANTHROPIC }}
    effort: low
    max_tokens_budget: '5000000'

默认触发条件是 pull_request_target (opened)，以及 PR 评论中输入 /open-code-review 手动重审；结果以行内评论落到对应代码行。安全加固：官方所有 workflow 的 uses: 都固定到完整 commit SHA（防 pull_request_target 场景的供应链攻击），二次修改时保持这一做法。

GitLab 用户改用官方 examples/gitlab_ci/.gitlab-ci.yml：监听 merge_requests 事件，通过 Discussion API 发内联评论；变量同上，另需 GITLAB_API_TOKEN（缺省回退 CI_JOB_TOKEN）；浅克隆设 GIT_DEPTH: 0。

9.3 验证生效 ：提一个含已知问题（如 innerHTML 插值）的 PR，确认 Actions 触发、行内评论落在正确代码行；再评论 /open-code-review 确认手动重审可用。

十、日常运转

配置完成后，团队的 Review 流程收敛为三条线：

日常提交：Agent 写完代码，一句「审查这次改动」触发委托审查 → 行级问题清单 → 当场修 → 复审闭环。
PR 合并前：CI 门禁用 Default 模式再兜一层底，人工 Review 只看架构和业务逻辑。
规则演进：误报回填进 rule.json，标准越用越准。

大变更集（上百文件的重构）注意两点：委托模式下审查算力走 Agent，大重构可先让 Agent 粗筛、再按模块切区间精审；Default 模式（CI）下耗时 ≈ 组数 × 每组 LLM 往返 ÷ 并发度，先切分再审查------ocr review --commit <id> 逐提交审或按模块切区间，耗时与组数近似线性。CI 中可用 --effort low（轮数减半）、--max-tokens-budget 封顶总预算、ocr review --preview 零成本预检（too_large 状态的文件是白等，先排除或拆提交）。

CI 产生的审查有完整会话体系可回溯：

bash 复制代码

ocr session list                       # 历史审查会话
ocr session compare <before> <after>   # 对比两次审查：new / persisting / resolved
ocr session export <id>                # 导出自包含 HTML 报告
ocr viewer                             # 浏览器端回放，可标记已修复/忽略

附录 A：配置完成后的项目形状

bash 复制代码

your-frontend-project/
├── .github/
│   └── workflows/
│       └── ocr-review.yml        # 第 9 步：CI 门禁（可选）
├── .opencodereview/
│   └── rule.json                 # 第 6 步：项目规则（提交入库）
└── src/......

# 机器侧（自动生成，不用手动建）
~/.opencodereview/
├── config.json                   # 模型配置（仅 CI 场景需要；委托模式为空也能跑）
├── rule.json                     # 可选的全局个人规则
└── sessions/                     # 审查会话记录

附录：几个实用 Tips

先诊断再花钱 ：审查结果不对劲时，先用 ocr delegate preview 和 ocr delegate rule <文件>（零 token）确认审了哪些文件、命中了哪条规则，再决定改配置还是改规则。
Vue 项目先补规则 ：内置规则没有 **/*.vue，不补的话 .vue 文件会落进无差别的 default 组，审查意见会很泛（见 6.1）。
误报要回填 ：确认是误报的问题，把它对应的约束写进 rule.json，下次同类问题就不会再报；标准越用越准。
大变更集先切分 ：上百文件的改动别一次审，按提交或模块拆区间；CI 里加 --effort low 和 --max-tokens-budget 控制耗时与成本。
被跳过的文件看原因 ：preview 输出里标 too_large 的文件是 diff 超了模型上下文，白等一场，先排除或拆提交。
干净卸载 ：删掉 ~/.opencodereview/ 目录即可，OCR 不会在你的项目里留任何东西（.opencodereview/rule.json 是你自己提交的，留着）。

官方文档：open-codereview.ai/docs

前端团队 Review 指南（open-code-review 版）

一、开工前先搞懂：谁查什么

二、第 1 步：环境自检

三、第 2 步：安装 ocr CLI

四、第 3 步：选执行模式------本指南走委托模式

五、第 4 步：配置你的 AI Agent（委托宿主）

用 skills CLI 安装（通用）

用客户端原生插件安装

六、第 5 步：写项目规则 .opencodereview/rule.json

6.1 先知道一个必踩的坑

6.2 创建规则文件

6.3 字段语义（准确版）

6.4 验证规则：零 token、秒级返回

七、第 6 步：跑第一次委托审查

八、第 7 步：规则持续调优

九、第 8 步（可选）：CI 门禁

十、日常运转

附录 A：配置完成后的项目形状

附录：几个实用 Tips

六、第 5 步：写项目规则 `.opencodereview/rule.json`