CodeRocket CLI

让每一次 git commit 都经过 AI 代码审查

基于多 AI 引擎(Gemini / OpenCode / ClaudeCode)的智能 Git 提交审查工具。零侵入接入现有工作流:提交即审查,推送即建 MR,报告自动落盘。

⚡ 30 秒上手

# 1. 一键安装(执行的是仓库内 install.sh,可先审阅后运行,见「安装」章节)
curl -fsSL https://raw.githubusercontent.com/im47cn/coderocket-cli/main/install.sh | bash

# 2. 为项目启用(自动在项目内生成 .env.example 模板)
cd your-project && coderocket setup

# 3. 配置 GitLab Token(用于自动创建 MR)
cp .env.example .env                     # 在项目内填写 GITLAB_PERSONAL_ACCESS_TOKEN

# 4. 像往常一样提交 —— 审查自动发生
git commit -m "feat: 添加用户认证功能"
ls review_logs/                          # ✅ 结构化审查报告已生成

💡 Token 也可写入 ~/.coderocket/env 全局生效;克隆目录下的 .env 不会被项目 Hook 加载。

兼容性说明:CodeRocket 前身名为 CodeReview CLI,coderocket、codereview-cli、cr 三个命令完全等价,老用户无需任何迁移。

✨ 核心特性

🔍 自动化代码审查

每次 git commit 后自动触发深度审查:不止于 diff 表面——AI 会基于提交信息进行全局代码搜索,从功能完整性、代码质量、可维护性、扩展性多维度评估,产出结构化 Markdown 报告并写入 review_logs/,文件名自带审查结论(✅ / ⚠️ / ❌ / 🔍),一眼定位问题提交。

🤖 多 AI 引擎 + 智能故障转移

引擎	接入方式	说明
Gemini(默认)	本地 CLI(`gemini -p`)	免费额度充足,开箱即用
OpenCode	统一 HTTP 端点模块	密钥不进命令行参数
ClaudeCode	统一 HTTP 端点模块	密钥不进命令行参数

单一引擎遇到 429 限流、认证失败或网络超时时,自动按优先级切换到下一个可用引擎并给出明确提示——审查链路不因单点故障而中断。

👥 多 Agent 并行审查

coderocket review-multi 在单引擎审查之外提供多视角交叉审查:自动检测环境中已安装的 agent CLI(Claude Code / Codex / Gemini / OpenCode / Hermes / Oh My Pi / Pi 等),并行发出审查指令并汇总为单一报告。在 herdr(面向编码 agent 的终端多路复用器)会话内运行时,优先通过 herdr 面板编排——各 agent 在独立面板中工作,过程与结果可随时回看。

cr review-multi                              # 自动检测全部已安装 agent 并行审查
cr review-multi --list                       # 仅列出检测到的 agent
cr review-multi --agents claude,codex        # 指定 agent
cr review-multi --diff 'main..HEAD' --timeout 120

详见多 Agent 并行审查指南。

📝 智能 MR 创建

git push 时自动创建 GitLab Merge Request(支持自建实例):AI 基于提交内容生成有意义的标题与描述,自动检测目标分支,适配多种分支命名规范,并防止重复创建。

🛡️ 供应链安全设计

一键安装亦可审计:一键命令执行的正是本仓库中的 install.sh,支持「下载 → 检查 → 执行」;安装代码仅来自本仓库,系统依赖(Node.js / Python3)仅经 brew / apt-get / yum 等系统包管理器安装,AI CLI 仅经 npm 安装,不执行任何远程安装脚本
密钥不落 argv:OpenCode/ClaudeCode 的 API Key 通过权限受限(chmod 600)的临时文件传递,不暴露在进程参数中
环境变量前缀白名单:Hook 从 .env、~/.coderocket/env(含旧版 ~/.codereview-cli/env 兼容路径)加载变量时,仅导入 AI_ / GITLAB_ / GEMINI_ / OPENCODE_ / CLAUDECODE_ / REVIEW_ 白名单前缀的变量,不向 Hook 环境注入无关配置
无自动更新后门:不含任何自动拉取执行远程代码的模块,更新完全由你掌控

🧩 无缝集成体验

VS Code 完全兼容:IDE 内提交/推送与命令行行为一致
一次安装,全局生效:全局安装后,git init 的新仓库自动携带 CodeRocket
纯 Bash 实现:除 Node.js 与 Python3 外零额外依赖,轻量、透明、可审计

🧭 工作原理

flowchart LR
    A["git commit"] --> B["post-commit hook"]
    B --> C["AI 智能审查<br/>Gemini → OpenCode → ClaudeCode<br/>(自动故障转移)"]
    C --> D["审查报告<br/>review_logs/"]

    E["git push"] --> F["pre-push hook"]
    F --> G["自动创建 GitLab MR"]

    style C fill:#e1f5fe
    style D fill:#e8f5e9
    style G fill:#fff3e0

Git Hook	触发时机	职责
`post-commit`(默认)	提交完成后	执行 AI 代码审查,生成报告
`pre-commit`(可选)	提交前	提交前审查,可拦截问题代码(设置 `REVIEW_TIMING=pre-commit`)
`pre-push`	推送前	自动创建 GitLab MR

📦 安装

环境要求

依赖	版本要求	用途
操作系统	macOS / Linux / Windows(WSL)	—
Git	≥ 2.0	Hook 机制与版本控制
Node.js	≥ 14.0.0	运行 AI 服务 CLI
Python3	≥ 3.6	GitLab API 调用与 JSON 处理
AI 服务	Gemini / OpenCode / ClaudeCode 任选其一	审查引擎(默认 Gemini)

方式一:一键安装

curl -fsSL https://raw.githubusercontent.com/im47cn/coderocket-cli/main/install.sh | bash

一键命令执行的正是仓库中的 install.sh。管道非交互环境下自动采用全局安装模式,并跳过交互式步骤(其他仓库批量配置、AI 服务配置),安装完成后在项目内运行 coderocket setup、随时运行 coderocket config 补全;在终端直接运行则进入完整交互引导。

方式二:下载后执行(先审阅)

curl -fsSL https://raw.githubusercontent.com/im47cn/coderocket-cli/main/install.sh -o /tmp/coderocket-install.sh
less /tmp/coderocket-install.sh     # 先检查脚本内容,再决定执行
bash /tmp/coderocket-install.sh

方式三:源码安装

git clone https://github.com/im47cn/coderocket-cli.git
cd coderocket-cli
./install.sh

安装脚本会引导你选择安装模式,并在缺依赖时给出对应平台的安装指引。

安装模式对比

	全局安装(推荐)	项目安装
新建仓库自动启用	✅ 通过 Git 模板(`init.templateDir`)	❌ 需逐项目安装
全局命令 `coderocket` / `cr`	✅	✅
现有仓库启用	`coderocket setup` 一次即可	每个项目单独安装

安装过程中还会询问是否在项目内创建提示词文档:

选 y:生成 prompts/git-commit-review-prompt.md,可为该项目定制审查规则
选 n(多数用户的推荐):使用全局默认提示词,项目目录保持干净

安装 AI 服务 CLI

根据所选引擎安装对应工具(配置命令可用 coderocket config 查看):

npm install -g @google/gemini-cli       # Gemini(默认)
gemini config                            # 按提示完成认证

npm install -g @opencode/cli            # OpenCode(可选)
npm install -g @anthropic-ai/claude-code  # ClaudeCode(可选)

OpenCode / ClaudeCode 无需本地登录,API Key 通过环境变量或 .env 提供(见下方「配置」章节)。

安装验证

coderocket version                                # 全局命令可用
git config --global init.templateDir              # 全局模式:模板已配置
gemini --version                                  # AI CLI 可用
cd your-project && coderocket                     # 试跑一次审查

🚀 使用

命令参考

coderocket、codereview-cli、cr 三命令完全等价,以下以 cr 为例:

命令	说明
`cr`	在 Git 仓库中直接审查最新提交(默认行为)
`cr review`	同上,显式指定
`cr review-multi`	多 Agent 并行审查(自动检测已安装的 agent CLI)
`cr setup`	为当前项目安装 CodeRocket hooks
`cr config`	查看 AI 服务配置入口
`cr timing`	配置审查时机(提交前 / 提交后)
`cr update`	更新 CodeRocket(git 安装自动 `git pull`)
`cr version`	查看版本与安装路径
`cr help`	帮助信息

典型工作流

# 新项目(全局安装后,git init 即自动启用)
git init my-project && cd my-project
vim src/main.js
git add src/main.js
git commit -m "feat: 添加用户认证功能"   # ← 审查自动触发

ls review_logs/                          # 查看报告
cat "review_logs/20260915_1430_✅_6efa8d_添加用户认证功能.md"

git push origin feature/user-auth        # ← MR 自动创建

# 现有项目
cd existing-project
coderocket setup                         # 一次设置,此后全自动

VS Code 集成

VS Code 内置 Git 工具的提交与推送同样触发审查与 MR 创建。若环境变量未生效,重启 VS Code 即可加载。详见 VS Code 设置指南。

审查状态

状态	含义
✅ 通过	功能完整,代码质量良好
⚠️ 警告	功能基本实现,存在质量问题或优化空间
❌ 失败	功能未实现、实现错误或存在严重 bug
🔍 调查	发现疑似遗漏,需进一步分析

⚙️ 配置

环境变量

必需(启用 MR 自动创建时):

变量	说明	示例
`GITLAB_PERSONAL_ACCESS_TOKEN`	GitLab 个人访问令牌(需 `api`、`read_repository`、`write_repository` 权限)	`glpat-xxxx…`

AI 服务(按所选引擎配置):

变量	说明	默认值
`AI_SERVICE`	审查引擎:`gemini` / `opencode` / `claudecode`	`gemini`
`GEMINI_API_KEY`	Gemini API Key(配合 CLI 使用)	—
`OPENCODE_API_KEY` / `OPENCODE_API_URL`	OpenCode 凭证与端点	`https://api.opencode.com/v1`
`CLAUDECODE_API_KEY` / `CLAUDECODE_API_URL`	ClaudeCode 凭证与端点	`https://api.claudecode.com/v1`

行为微调:

变量	说明	默认值
`REVIEW_TIMING`	审查时机:`post-commit`(不打断提交流程)/ `pre-commit`(可拦截问题提交)	`post-commit`
`AI_AUTO_SWITCH`	引擎故障时自动切换	`true`
`AI_RETRY_DELAY`	引擎重试间隔(秒)	`1`
`GITLAB_API_URL`	自建 GitLab 的 API 地址	`https://gitlab.com/api/v4`
`REVIEW_MULTI_AGENTS`	追加参与并行审查的 agent(逗号分隔)	—
`AGENT_<NAME>_CMD`	覆盖某 agent 的调用命令模板(`%PROMPT_FILE%` 占位符)	内置模板
`REVIEW_MULTI_TIMEOUT`	并行审查单 agent 超时(秒)	`300`
`REVIEW_MULTI_MAX_PARALLEL`	并行审查并发上限	`4`

获取 Gemini API Key:https://aistudio.google.com/app/apikey 获取 GitLab Token:Settings → Access Tokens → Personal Access Tokens

配置文件与优先级

CodeRocket 按以下顺序解析配置(高优先级生效):

环境变量 → 项目 .ai-config → 全局 ~/.coderocket/ai-config

Hook 运行时从以下位置加载环境变量文件(仅导入白名单前缀的变量;另兼容读取旧版 ~/.codereview-cli/env,升级用户无需迁移配置):

项目 .env  +  全局 ~/.coderocket/env  (+ 旧版 ~/.codereview-cli/env 兼容)

快速上手建议:复制模板 cp .env.example .env,填入 Token 即可。完整变量说明见模板内注释。

切换 AI 引擎

# 方式一:环境变量
export AI_SERVICE=opencode          # 或 gemini / claudecode

# 方式二:配置文件
echo "AI_SERVICE=opencode" > .ai-config                 # 仅当前项目
echo "AI_SERVICE=opencode" > ~/.coderocket/ai-config    # 全局生效

# 方式三:交互式工具
./lib/ai-config.sh select           # 选择引擎
./lib/ai-config.sh timing           # 选择审查时机
./lib/ai-config.sh configure gemini # 配置特定引擎

自定义审查规则

审查行为由提示词文档驱动,项目级覆盖全局:

prompts/git-commit-review-prompt.md          ← 项目级(存在则优先生效)
~/.coderocket/prompts/git-commit-review-prompt.md   ← 全局默认

在项目级提示词中加入团队约定,即可让 AI 按你的标准审查:

### 项目特定关注点
- 必须遵循的编码规范
- 架构约束(如禁止直接访问数据库层)
- 性能与安全红线

详见提示词设置指南。

📊 审查报告

命名规则

review_logs/YYYYMMDD_HHmm_[状态]_[commit哈希前6位]_[简短描述].md

报告结构

每份报告包含:基本信息(提交哈希 / 作者 / 时间)→ 审查摘要(状态与总体评价)→ 全局代码搜索分析 → 逐文件详细审查 → 分级改进建议(立即修复 / 短期改进 / 长期优化)→ 总结。

问题标记系统

审查报告使用统一的行内标记,便于 grep 与后续处理:

标记	含义
`//MISSING`	遗漏的重要修改(如改了实现没改测试)
`//FIXME`	必须修复的 bug
`//WARNING`	潜在风险
`//SECURITY`	安全问题(如密钥明文)
`//PERFORMANCE`	性能问题
`//OPTIMIZE`	可优化代码
`//TODO`	待补充功能
`//RULE`	可提炼的通用规则
`//DEPENDENCY`	依赖问题

# 例:快速筛查所有提交中的安全隐患
grep -r "SECURITY" review_logs/

🧩 架构概览

bin/coderocket                  全局命令入口(严格模式仅限于此,不泄漏进被 Hook source 的库)
├── githooks/post-commit        审查驱动:加载环境 → 组装上下文 → 调用 AI 编排层
├── githooks/pre-push           MR 创建:AI 生成标题描述 → 调用 GitLab API
└── lib/
    ├── ai-service-manager.sh   AI 编排:引擎选择、智能故障转移、错误分类
    ├── ai-service-endpoint.sh  OpenCode/ClaudeCode 统一 HTTP 端点模块(密钥经临时文件传递)
    ├── ai-error-classifier.sh  错误分类器:429 / 认证 / 网络 / 未安装
    ├── ai-config.sh            交互式配置工具
    ├── mr-generator.sh         MR 内容生成
    └── banner.sh, version*.sh  展示与版本辅助

纯 Bash、模块化、每个库文件可独立被 Hook source——深入阅读请见架构总览与 API 参考。

🔄 更新

coderocket update          # git 安装:自动 git pull(失败时给出恢复步骤)

# 或手动更新
cd ~/.coderocket && git pull origin main

非 git 安装无法自动更新时,coderocket update 会打印「下载 → 检查 → 执行」三步指引。

🧯 故障排除

症状	处理
`pre-push 脚本不存在`	在项目内重跑 `coderocket setup`
AI 服务无响应	`./lib/ai-service-manager.sh status` 检查引擎状态;确认对应 CLI 已安装或 API Key 已配置
Hook 未执行	`chmod +x .git/hooks/post-commit .git/hooks/pre-push`
报告生成失败	确认 `review_logs/` 目录可写:`mkdir -p review_logs && chmod 755 review_logs`
MR 创建失败	检查 Token 是否具备 `api` / `read_repository` / `write_repository` 权限
VS Code 内变量未加载	重启 VS Code;`echo $GITLAB_PERSONAL_ACCESS_TOKEN` 验证

需要更详细的排查?见故障排除指南。

📚 文档中心

主题	文档
快速上手	快速入门指南
AI 引擎配置与故障转移	AI 服务指南 · 故障转移配置 · 多服务概览
多 Agent 并行审查	多 Agent 并行审查指南
提示词定制	提示词设置指南
IDE 集成	VS Code 设置 · VS Code 测试
深入理解	架构总览 · API 参考 · 性能优化
运维	部署指南 · 更新机制 · 版本管理
求助	故障排除指南

🤝 贡献

欢迎 Issue 与 PR!开发流程、代码规范与提交要求见贡献指南。

git clone https://github.com/im47cn/coderocket-cli.git
cd coderocket-cli
./install-hooks.sh        # 开发环境安装项目 hooks

📄 许可证

让 AI 成为你代码质量的守护者 🛡️

报告问题 · 功能建议 · Star 支持

Name		Name	Last commit message	Last commit date
bin		bin
docs		docs
githooks		githooks
lib		lib
prompts		prompts
.ai-config		.ai-config
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
VERSION		VERSION
install-hooks.sh		install-hooks.sh
install.sh		install.sh
update.tar.gz		update.tar.gz

Latest commit

History

Folders and files

Repository files navigation