codereview-skill

CodeReview skill 的跨平台安装工具。为 Cursor、Claude Code、OpenAI Codex、Trae、Qoder 及其他兼容 SKILL.md 的 AI 编辑器安装代码审查能力。

快速开始

# 零安装启动（推荐）
npx codereview-skill@latest init

# 全局安装
npm install -g codereview-skill
codereview init

安装

交互式安装

codereview init

安装程序会自动检测当前项目中已安装的 AI 编辑器，并提示你选择目标平台。检测到的平台会自动勾选，你也可以手动增减。

非交互模式

适合脚本和 CI/CD 环境：

# 安装到指定平台
codereview init --tools cursor
codereview init --tools cursor,claude,qoder

# 安装到所有支持的平台
codereview init --tools all

# 在指定目录安装
codereview init ./my-project

旧版配置迁移

如果你之前通过 install.sh 安装过（配置位于 .cursor/codereview/），使用 --force 自动迁移：

codereview init --force

这会：

• 将 .cursor/codereview/config.yaml 迁移到全局 codereview/config.yaml
• 将 .cursor/codereview/waivers.yaml 迁移到全局 codereview/waivers.yaml
• 将旧版模板迁移到全局 codereview/templates/
• 保留原始文件不被删除（备份为 .from-legacy）

安装选项

| 选项 | 说明 | |--------|-------------| | --tools <list> | 逗号分隔的平台 ID，或 all/none | | --force | 自动迁移旧版配置，不提示确认 |

使用 CodeReview

安装完成后，在你的 AI 编辑器中使用 /cr 命令触发代码审查。

三种审查模式

| 模式 | 用途 | 典型场景 | |------|------|---------| | assistant | 提交前自查，快速发现问题 | 写完代码后想检查一下 | | gate | 分支级风险门禁，输出合并建议 | 准备合入主分支前的最后检查 | | workspace | 多仓联合审查，识别跨仓边界问题 | 前后端、SDK 等多个仓库同时修改 |

assistant 模式

提交前助手，优先帮助开发者快速发现风险并减少返工。

# 默认 assistant 模式
/cr

# 检查暂存区变更
/cr --assistant --staged

# 检查指定文件
/cr src/auth.ts --assistant

# 检查指定目录
/cr src/utils/ --assistant

# 检查整个项目
/cr --all --assistant

输出示例：

✓ CodeReview 完成！
📄 报告: CodeReview/2026-04-22-103000.md
🧭 模式: assistant
⚠️ 风险评分: 32/100（摘要）
🔧 Should Fix: 2 | 📝 Notes: 3

gate 模式

分支级风险门禁，输出 approve / caution / block 合并建议。

# 对比 main 分支
/cr --gate --base main

# 对比 origin/main 并限制到指定目录
/cr src/api/ --gate --base origin/main

# 提供了 --base 但未指定 mode 时，默认进入 gate 模式
/cr --base main

输出示例：

✓ CodeReview 完成！
📄 报告: CodeReview/2026-04-22-103510.md
🧭 模式: gate
🚦 Merge Recommendation: caution
🛑 Active Blockers: 0 | ⚠️ Waived Issues: 1 | 🔁 Recheck: 1

workspace 模式

同一 workspace 下多个独立仓库联合审查，自动发现有变更的仓库，扩展受影响的仓库，并输出跨仓联合结论。

# 自动发现 workspace 下有变更的仓库
/cr --workspace

# 指定 workspace 根目录
/cr --workspace --workspace-root ~/workspace

输出示例：

✓ CodeReview 完成！
📄 报告: CodeReview/2026-04-22-203000.md
🧭 模式: workspace
🚦 Workspace Recommendation: caution
📦 Changed Repos: 2 | 🧩 Affected Repos: 1 | 🔗 Cross-Repo Findings: 3

配置

安装后会在项目根目录创建 codereview/ 目录，其中 config.yaml 是核心配置文件。

your-project/
└── codereview/
    ├── config.yaml      # 审查策略配置
    ├── waivers.yaml     # 风险豁免管理
    └── templates/
        └── review-report.md  # 报告模板

关键配置项

review:
  # 默认审查模式
  default_mode: "assistant"

  # 默认审查范围
  default_scope: "changed-symbols"

  # 模式级策略
  modes:
    assistant:
      baseline: "auto-local"    # 优先暂存区，否则工作树
    gate:
      baseline: "base-branch"   # 对比分支
      base_branch: "main"       # 默认对比分支
      adjudication: true        # 开启裁决过滤

  # Blocker 判定阈值
  decision:
    blocker:
      min_severity: "high"      # 最小严重等级
      min_confidence: "high"    # 最小置信度
      require_blocking_rationale: true

  # 风险豁免
  waiver:
    enabled: true
    file: "codereview/waivers.yaml"

  # 重新检查
  recheck:
    enabled: true
    on_waiver_match: true

  # 输出
  output:
    directory: "CodeReview"
    include_risk_score: true

风险豁免（Waiver）

codereview/waivers.yaml 是团队共享的风险记忆文件，应纳入版本控制。

格式

waivers:
  - issue_id: "auth-log-token-leak"
    reason: "日志中的 token 问题已在其他层面解决，暂不修复"
    waived_by: "张三"
    created_at: "2026-04-22T10:00:00Z"
    status: "active"  # active 或 revoked

规则

• waiver 是仓库级、纳入版本控制、长期有效的记录
• 默认跨分支复用
• 命中已有 waiver 的问题归类为 Waived Issue，不会阻塞合并
• status 为 active 的 waiver 才参与匹配
• 不要将 codereview/waivers.yaml 加入 .gitignore

报告

审查报告默认保存在 CodeReview/YYYY-MM-DD-HHMMSS.md 目录。

建议在 .gitignore 中添加：

CodeReview/

gate 模式报告结构

# CodeReview 报告

**模式**: gate
**Merge Recommendation**: caution

## 🛑 Active Blockers
## 🔧 Should Fix
## 📝 Notes
## 🟦 Waived Issues
## 🔁 Recheck Results

assistant 模式报告结构

# CodeReview 报告

**模式**: assistant

## 执行摘要
## 🔍 关键发现
## 📝 其他建议
## ✅ 做得好的地方

支持的平台

| 平台 | 检测标志 | Skill 目录 | 命令入口 | |----------|-----------|-----------------|----------| | Cursor | .cursor/ | .cursor/skills/codereview/ | .cursor/commands/cr.md | | Claude Code | .claude/ | .claude/skills/codereview/ | SKILL.md 自动触发 | | OpenAI Codex | .agents/ | .agents/skills/codereview/ | /skills 或 $codereview | | Trae | .trae/ | .trae/skills/codereview/ | SKILL.md 自动触发 | | Qoder | .qoder/ | .qoder/skills/codereview/ | SKILL.md 自动触发 |

常见问题

Q: 如何切换到 gate 模式？

A: 使用 /cr --gate --base <branch>，例如 /cr --gate --base main。

Q: 如何做 workspace 级联审？

A: 使用 /cr --workspace。会自动发现 workspace 下有变更的仓库，并分层展示 Cross-Repo Findings 与 Per-Repo Findings。

Q: 为什么风险分数不再直接决定合并结果？

A: v2 中 risk_score 只是摘要指标。gate 模式真正依赖的是 blocker 判定、waiver 和 merge recommendation。

Q: waiver 文件应该提交吗？

A: 应该。waiver 是团队共享的风险记忆，应纳入版本控制并接受 review。

Q: 升级安装会覆盖我已有的配置吗？

A: 不会。如果 config.yaml 或 waivers.yaml 已存在，新模板会以 .new 形式落盘，供人工合并。

Q: 如何自定义审查策略？

A: 编辑 codereview/config.yaml，可自定义 mode、baseline、gate 阈值、waiver 行为等。

开发

npm install
npm run build
npm run dev -- init        # 本地运行

License

MIT