coderabbit

CodeRabbit

AI 驱动的拉取请求和本地更改代码审查工具。

快速导航

任务	参考文档
安装并运行 CLI	cli-usage.md
配置 .coderabbit.yaml	configuration.md
支持的工具（40+ 个 Linter）	tools.md
Git 平台设置	platforms.md
PR 命令（@coderabbitai）	pr-commands.md
Claude/Cursor/Codex 工作流	agent-integration.md
分类调查结果	triage.md
修复单个问题	fix.md
报告与指标	end-to-end-workflow.md
端到端工作流	end-to-end-workflow.md
Windows/WSL 设置	windows-wsl.md

前置条件检查（审查前必须运行）

运行 CodeRabbit CLI 前，请确认以下条件全部满足：

# 1. CLI installed?
which coderabbit || echo "MISSING: install with: curl -fsSL https://cli.coderabbit.ai/install.sh | sh"

# 2. Authenticated?
coderabbit auth status 2>&1 | grep -q "Logged in" || echo "MISSING: run coderabbit auth login"

# 3. Git repo has at least one commit? (CRITICAL — CLI crashes with GitError on empty repos)
git rev-parse HEAD >/dev/null 2>&1 || echo "MISSING: repo has no commits — make at least one commit first"

# 4. Base branch exists? (CLI defaults to 'main')
git rev-parse main >/dev/null 2>&1 || echo "WARNING: 'main' branch not found — use --base <branch>"

如果任何检查未通过，请先修复，再运行审查。请勿在状态异常时继续操作。

**身份验证失败处理规则：**如果身份验证检查（第 2 步）未通过，Agent 必须：

1. 立即停止 — 不要尝试运行审查
2. 告知用户 CodeRabbit CLI 尚未完成身份验证
3. 向用户显示确切的身份验证命令：coderabbit auth login
4. 等待用户完成身份验证后再重试
5. 不要代替用户运行 coderabbit auth login — 该命令需要通过交互式浏览器重定向完成

快速开始

运行审查

# AI agent workflow (most common) — note: 'review' subcommand is optional
coderabbit review --prompt-only --type uncommitted --no-color

# If base branch is not 'main' (e.g., master, develop):
coderabbit review --prompt-only --type uncommitted --base master --no-color

# Plain text output (human-readable)
coderabbit review --plain --type uncommitted --no-color

本地捕获脚本

将输出保存到文件，以便稍后分析：

# IMPORTANT: use absolute path to the skill's script directory
python3 ~/.claude/skills/coderabbit/scripts/run_coderabbit.py --output coderabbit-report.txt

选项：

• --output 用于指定其他文件名（保存到仓库根目录下的 .code-review/）
• --timeout 用于调整超时时间（秒；默认值：1800）
• --base 用于指定基准分支（默认值：从 git 自动检测）

PR 命令

@coderabbitai review          # Incremental review
@coderabbitai full review     # Complete review
@coderabbitai simplify        # Apply targeted simplifications to changed files
@coderabbitai fix merge conflict  # Attempt automatic merge-conflict resolution
@coderabbitai pause           # Stop auto-reviews
@coderabbitai resume          # Resume auto-reviews
@coderabbitai resolve         # Mark comments resolved

严重程度矩阵

严重程度	操作	示例
CRITICAL	立即修复	安全、数据丢失、租户隔离
HIGH	应当修复	可靠性、性能、架构违规
MEDIUM	酌情处理	可维护性、类型安全（快速见效）
LOW	跳过	风格/格式、主观的小问题

AI Agent 工作流模式

Implement [feature] and then run CodeRabbit CLI in a background terminal.
Wait for it to complete, then read the report. Fix CRITICAL/HIGH issues. Ignore nits.

分步操作：

1. 运行前置条件检查（见上文）— 继续前修复所有问题
2. 检测基准分支：git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null，如果失败则使用 main/master
3. 在后台运行 CLI：coderabbit review --prompt-only --type uncommitted --base <branch> --no-color
4. 审查需要 7-30+ 分钟 — 在后台运行（run_in_background=true）
5. 进程完成后读取输出
6. 修复 CRITICAL/HIGH 级别的问题，跳过 LOW 级别的问题
7. 最多进行 2-3 轮审查

故障排查

出现 [error] stopping cli，但没有详细信息

使用 DEBUG=* 运行，以查看实际错误：

DEBUG=* coderabbit review --prompt-only --type uncommitted 2>&1 | grep -E "(ERROR|error|GitError)"

检查日志文件：

ls -t ~/.coderabbit/logs/ | head -1 | xargs -I{} cat ~/.coderabbit/logs/{}

常见错误

错误	原因	修复方法
GitError（无详细信息）	仓库中没有提交	至少创建一次提交
Failed to get commit SHA for branch main	基础分支不存在	使用 --base master 或 --base <your-branch>
Raw mode is not supported	在非 TTY 环境中使用交互模式	始终使用 --prompt-only 或 --plain
认证后出现 [error] stopping cli	令牌已过期	重新运行 coderabbit auth login
CLI 卡住／没有输出	变更集过大	使用 --type uncommitted 限定范围

检查认证状态

coderabbit auth status

已关联的仓库（2026-02-18）

CodeRabbit 可以在 PR 审查期间分析已关联的仓库，以发现跨仓库问题（API／类型／依赖变更不一致）。

• 在知识库设置中配置已关联的仓库。
• 截至 2026-03-11，Pro 计划最多可关联 2 个仓库进行多仓库分析。
• 当一个仓库中的变更影响另一个仓库中的契约时，请使用此功能。
• 如果跨仓库发现的问题表明存在运行时不兼容，请将其视为 HIGH／CRITICAL。

仪表板和报告（2026-03-12）

• 仪表板指标现分为 Git 平台审查 和 IDE／CLI 审查。
• 报告页面现包括 Git 平台页面（如知识库、合并前检查和报告），以及 IDE／CLI 页面（如摘要、组织趋势和数据指标）。
• 所有仪表板均支持团队筛选；当需要按团队而非仅按仓库区分审查量或发现的问题时，请使用这些筛选器。

简化代码（公开测试版，Pro）（2026-03-13）

• @coderabbitai simplify 会对 PR 中已更改的文件执行 Agent 式清理。
• 它专注于提取可复用的辅助函数、简化条件语句并消除冗余，同时保持行为不变。
• CodeRabbit 会使用仓库现有的测试套件验证结果，并可创建后续 PR 或直接提交到分支。
• 不适用于分叉 PR 的直接提交模式。

聊天访问控制（GitHub 组织）（2026-03-16）

• 如果 PR 评论中的聊天必须仅限组织成员使用，请在 .coderabbit.yaml 中设置 chat.allow_non_org_members: false。
• 这只影响评论线程中的交互；自动 PR 审查行为不变。
• 默认值仍为 true，因此除非主动选择退出，否则公共仓库中的聊天仍然开放。

解决合并冲突（公开测试版，Pro）（2026-03-17）

• CodeRabbit 可以在 PR 审查期间检测合并冲突，并提供一键解决或通过评论触发解决的选项。
• 在 GitHub 上使用 @coderabbitai fix merge conflict 或 Walkthrough 复选框触发。
• 成功时，它会创建正式的合并提交；但如果解决方案存在歧义，或涉及身份验证、加密、机密信息或访问控制等安全关键逻辑，则会拒绝处理。
• 如果任何冲突文件被拒绝，整个自动解决尝试都会中止，且不会创建部分提交。

Betterleaks（取代 Gitleaks）（2026-03-19）

• 现在使用 Betterleaks 进行机密信息扫描（相比 Gitleaks，检测能力有所提升）。
• .coderabbit.yaml 中的 gitleaks 配置键现在用于控制 Betterleaks。
• 默认仍为启用；现有的机密信息扫描会继续运行，无需更改。

低质量内容检测（2026-03-24）

• 自动检测公共 GitHub 仓库中由 AI 生成的低质量 PR。
• 在 PR Walkthrough 评论中标记。
• 选择启用标签标记：

reviews:
  slop_detection:
    enabled: true # default
    label: "slop" # optional label

Bitbucket Data Center（2026-03-24）

• 全面支持 Bitbucket Data Center 作为 Git 平台。
• 支持 OAuth 2.0、自动配置 webhook 以及完整的 PR 审查功能。

审计日志（2026-03-25）

• 为整个工作区的每项管理操作提供防篡改审计日志。
• 涵盖席位分配与移除、角色变更、组织／仓库变更、订阅事件、配置更新和 API 密钥操作。
• 可通过设置界面或 REST API 访问，以便自动导出。

CLI Agent 模式（2026-03-31）

• coderabbit review --agent 以结构化 JSON 格式输出结果，供 Skills 和 Agent 集成使用。

CLI 0.4.x（2026-04-01 至 2026-04-06）

• coderabbit auth login 可在浏览器中完整完成。
• --agent 现在能更好地覆盖适用于 Agent 环境的身份验证工作流。
• --dir 取代 --cwd，用于限定子目录范围的审查。
• coderabbit stats 可用于本地审查遥测。

GitLab SSH 访问（2026-04-02）

• 自托管的 GitLab 可使用 SSH 克隆凭据，而非 HTTPS。
• 如果 GitLab 实例不提供 HTTPS 克隆，或强制仅通过 SSH 访问仓库，这项功能会很有用。

Codex 插件（2026-04-14）

• 除独立 CLI 外，CodeRabbit 还提供专用的 Codex 插件。
• 该插件会验证 CLI 安装和身份验证，通过自然语言或 @coderabbit 触发审查，并将审查结果保留在 Agent 循环中，以便后续修复。

全局覆盖项（2026-04-16）

• 组织管理员可以在所有仓库中强制应用优先级最高的配置覆盖项。
• 嵌套对象会与较低层级的配置合并；数组和标量值则会替换较低层级的值。

自定义收尾操作配方（抢先体验）（2026-02-23）

定义可复用的命名“收尾操作”配方，对 PR 应用 Agent 式代码更改。

请参阅 configuration.md 查看最简示例。

最简配置

# .coderabbit.yaml
language: en-US
reviews:
  profile: chill
  high_level_summary: true
  tools:
    gitleaks:
      enabled: true
    ruff:
      enabled: true

重要禁令

• 不要在生产代码中引入回退方案、模拟对象或存根
• 不要将范围扩大到 CodeRabbit 标记的问题之外
• 不要“修复”由格式化工具／代码检查工具处理的风格细节
• 不要忽略 CRITICAL 级别的问题；如有疑问，请升级处理
• 修复代码之前，先停止并解决 CLI 错误（身份验证／网络）
• 不要在没有提交记录的仓库上运行 CLI——它会静默崩溃

链接

• 文档
• 更新日志
• GitHub
• 架构

模板

• coderabbit.minimal.yaml — 最简配置
• coderabbit.full.yaml — 包含所有选项的完整示例
• agent-prompts.md — 可直接使用的 AI Agent 提示词