vrr/open-code-review
2
0
Fork 0
mirror of https://github.com/alibaba/open-code-review.git synced 2026-07-09 17:28:58 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

docs(README): update

Browse source
This commit is contained in:
kite 2026-05-30 19:17:53 +08:00
parent 103a213d77
commit 4fe9f0ef84
2 changed files with 72 additions and 274 deletions
Download patch file Download diff file Expand all files Collapse all files

173
README.md
View file

@ -145,90 +145,52 @@ ocr review --from main --to feature-branch
ocr review --commit abc123
```
### Integrate with Your Coding Agent
### Integrate with Coding Agents
OCR is designed to work seamlessly with coding agents. Use the `--audience agent` flag to produce structured, machine-readable output optimized for agent consumption.
OCR can be seamlessly integrated into AI coding agents as a slash command, enabling code review directly within your agent workflow.
#### Claude Code
#### Option 1: Install as a Skill
OCR provides a ready-to-use [Claude Code slash command](https://docs.anthropic.com/en/docs/claude-code/slash-commands). Create the following file in your project:
`.claude/commands/open-code-review.md`:
~~~markdown
# /open-code-review
Invoke the professional code review Agent CLI tool OpenCodeReview (OCR) to review current code changes, and let the Agent autonomously decide whether to apply fixes.
## Workflow
### Step 1: Run Code Review
Run the OCR command:
Use `npx` to install the OCR skill into your project:
```bash
ocr review --audience agent [user-args]
```
- Default (no user arguments): reviews staged, unstaged, and untracked changes (workspace mode).
- If the user provides `--commit` or `--c`: pass through as-is.
- If the user provides `--from` and `--to`: pass through as-is.
- (Optional) Provide `--background "requirement context"` to review whether the requirements are correctly implemented.
- Capture full stdout. Set a 5-minute timeout.
- If the `ocr` command is not found, install it by running `npm i -g @alibaba-group/open-code-review`.
### Step 2: Filter and Evaluate
For each comment, assess its validity and quality:
- **High**: Obvious bugs, security issues, clear mistakes, or well-founded suggestions with precise fix proposals
- **Medium**: Reasonable concerns but context-dependent, style/performance suggestions, or fixes that require manual implementation
- **Low**: Likely false positives, lacking sufficient context, nitpicks, or meaningless suggestions
Silently discard low-confidence comments. Display the remaining comments.
### Step 3: Fix
Automatically fix issues and suggestions that are worth adopting.
~~~
Then use `/open-code-review` in Claude Code to run a review. The slash command will run OCR, filter and evaluate each comment, and automatically fix issues worth adopting.
#### Cursor / Windsurf
Add the following instruction to your `.cursorrules` or `.windsurfrules` file:
```
## Code Review
When asked to review code, run the following command:
ocr review --audience agent
Parse the output and evaluate each comment by confidence level:
- High: Obvious bugs, security issues, clear mistakes — fix these automatically.
- Medium: Reasonable concerns — present to the user for decision.
- Low: Likely false positives or nitpicks — silently discard.
If the `ocr` command is not found, install it: npm i -g @alibaba-group/open-code-review
npx skills add alibaba/open-code-review --skill open-code-review
```
#### Other Coding Agents
This installs the `open-code-review` skill from the [skills registry](skills/open-code-review/SKILL.md), which teaches your coding agent how to invoke `ocr` for code review, classify issues by priority, and optionally apply fixes.
Any coding agent that can execute shell commands can integrate with OCR:
#### Option 2: Install as a Claude Code Plugin
For [Claude Code](https://docs.anthropic.com/en/docs/claude-code), install the command plugin through the following command in Claude Code:
```bash
# Machine-readable output for agent consumption
ocr review --audience agent
# With requirement context for targeted review
ocr review --audience agent --background "describe what the changes should do"
# Review specific commit or branch range
ocr review --audience agent --commit abc123
ocr review --audience agent --from main --to feature-branch
/plugin marketplace add alibaba/open-code-review
/plugin install open-code-review@open-code-review
```
The `--audience agent` flag suppresses progress UI and outputs a concise structured summary. The `--background` flag provides requirement context so OCR can verify whether the implementation matches intent.
This registers the `/open-code-review:review` slash command, which runs OCR and automatically filters and fixes issues.
#### Option 3: Copy the Command File Directly
For a quick setup without any package manager, simply copy the command file to use the `/open-code-review` slash command in Claude Code.
**Project-level** (shared with team via git):
```bash
mkdir -p .claude/commands
curl -o .claude/commands/open-code-review.md \
https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/commands/review.md
```
**User-level** (personal global use across all projects):
```bash
mkdir -p ~/.claude/commands
curl -o ~/.claude/commands/open-code-review.md \
https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/commands/review.md
```
> **Prerequisite**: All integration methods require the `ocr` CLI to be installed and an LLM configured. See [Install](#install) and [Configure LLM](#1-configure-llm) above.
## Commands
@ -346,16 +308,6 @@ Environment variables take precedence over the config file.
| `OCR_LLM_MODEL` | Model name |
| `OCR_USE_ANTHROPIC` | `true` = Anthropic, `false` = OpenAI |
### Template Parameters
Internal defaults defined in `internal/config/template/task_template.json`:
| Parameter | Default | Description |
|-----------|---------|-------------|
| `MAX_TOKENS` | 58888 | Max tokens per LLM request |
| `MAX_TOOL_REQUEST_TIMES` | 20 | Max tool-use iterations per file |
| `PLAN_MODE_LINE_THRESHOLD` | 50 | Skip plan phase below this line count |
| `TOOL_REQUEST_WAIT_TIME_MS` | 10000 | Per-tool-request timeout |
## Telemetry
@ -369,62 +321,9 @@ ocr config set telemetry.otlp_endpoint localhost:4317
Set `telemetry.content_logging` to include LLM prompts and responses in exported data.
## Development
## Contributing
```bash
make build # Build for current platform
make test # Run tests with race detection
make clean # Remove dist/
make build-all # Cross-compile (linux/amd64, linux/arm64, darwin/amd64, darwin/arm64)
make dist # Full release pipeline
```
## Integration into Coding Agents
OCR can be seamlessly integrated into AI coding agents as a slash command, enabling code review directly within your agent workflow.
### Option 1: Install as a Skill
Use `npx` to install the OCR skill into your project:
```bash
npx skills add alibaba/open-code-review --skill open-code-review
```
This installs the `open-code-review` skill from the [skills registry](skills/open-code-review/SKILL.md), which teaches your coding agent how to invoke `ocr` for code review, classify issues by priority, and optionally apply fixes.
### Option 2: Install as a Claude Code Plugin
For [Claude Code](https://docs.anthropic.com/en/docs/claude-code), install the command plugin through the following command in Claude Code:
```bash
/plugin marketplace add alibaba/open-code-review
/plugin install open-code-review@open-code-review
```
This registers the `/open-code-review:review` slash command, which runs OCR and automatically filters and fixes issues.
### Option 3: Copy the Command File Directly
For a quick setup without any package manager, simply copy the command file to use the `/open-code-review` slash command in Claude Code.
**Project-level** (shared with team via git):
```bash
mkdir -p .claude/commands
curl -o .claude/commands/open-code-review.md \
https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/commands/review.md
```
**User-level** (personal global use across all projects):
```bash
mkdir -p ~/.claude/commands
curl -o ~/.claude/commands/open-code-review.md \
https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/commands/review.md
```
> **Prerequisite**: All integration methods require the `ocr` CLI to be installed and an LLM configured. See [Install](#install) and [Configure LLM](#1-configure-llm) above.
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding guidelines, and how to submit pull requests.
## License

173
README.zh-CN.md
View file

@ -145,90 +145,52 @@ ocr review --from main --to feature-branch
ocr review --commit abc123
```
### 集成到你的 Coding Agent
### 集成到编程 Agent
OCR 天然适配各类 Coding Agent。使用 `--audience agent` 标志可输出结构化的机器可读结果，方便 Agent 消费。
OCR 可以无缝集成到 AI 编程 Agent 中，作为斜杠命令使用，在 Agent 工作流中直接进行代码审查。
#### Claude Code
#### 方式一：作为 Skill 安装
OCR 提供了开箱即用的 [Claude Code 斜杠命令](https://docs.anthropic.com/en/docs/claude-code/slash-commands)。在你的项目中创建以下文件：
`.claude/commands/open-code-review.md`：
~~~markdown
# /open-code-review
调用专业代码审查 Agent CLI 工具 OpenCodeReview (OCR) 审查当前代码变更，并由 Agent 自主决定是否修复。
## 工作流
### 第 1 步：执行代码审查
运行 OCR 命令：
使用 `npx` 将 OCR skill 安装到项目中：
```bash
ocr review --audience agent [user-args]
```
- 默认（无用户参数）：审查所有暂存、未暂存和未跟踪的变更（工作区模式）。
- 如果用户提供了 `--commit` 或 `-c`：原样传递。
- 如果用户提供了 `--from` 和 `--to`：原样传递。
- （可选）提供 `--background "需求上下文"` 以审查需求是否被正确实现。
- 捕获完整 stdout，设置 5 分钟超时。
- 如果未找到 `ocr` 命令，运行 `npm i -g @alibaba-group/open-code-review` 安装。
### 第 2 步：过滤与评估
对每条评论，评估其有效性与质量：
- **高**：明显的 bug、安全问题、明确的错误，或提出了精准修复方案的建议
- **中**：合理但依赖上下文的建议、风格/性能建议，或需要手动实现的修复
- **低**：大概率误报、缺乏充分上下文、吹毛求疵或无意义的建议
静默丢弃低置信度评论，展示其余评论。
### 第 3 步：修复
自动修复值得采纳的问题和建议。
~~~
然后在 Claude Code 中使用 `/open-code-review` 即可运行审查。该斜杠命令会运行 OCR、过滤评估每条评论，并自动修复值得采纳的问题。
#### Cursor / Windsurf
将以下指令添加到你的 `.cursorrules` 或 `.windsurfrules` 文件中：
```
## 代码审查
当被要求审查代码时，运行以下命令：
ocr review --audience agent
解析输出并按置信度评估每条评论：
- 高：明显的 bug、安全问题、明确的错误 —— 自动修复。
- 中：合理的建议 —— 展示给用户决定。
- 低：大概率误报或吹毛求疵 —— 静默丢弃。
如果未找到 `ocr` 命令，运行安装：npm i -g @alibaba-group/open-code-review
npx skills add alibaba/open-code-review --skill open-code-review
```
#### 其他 Coding Agent
此命令从 [skills 注册表](skills/open-code-review/SKILL.md)安装 `open-code-review` skill，教会你的编程 Agent 如何调用 `ocr` 进行代码审查、按优先级分类问题，并可选择性地应用修复。
任何能执行 shell 命令的 Coding Agent 都可以集成 OCR：
#### 方式二：作为 Claude Code Plugin 安装
对于 [Claude Code](https://docs.anthropic.com/en/docs/claude-code)，在 Claude Code 中通过以下命令安装命令插件：
```bash
# 机器可读输出，适合 Agent 消费
ocr review --audience agent
# 带需求上下文，进行针对性审查
ocr review --audience agent --background "描述变更应该实现的功能"
# 审查特定提交或分支范围
ocr review --audience agent --commit abc123
ocr review --audience agent --from main --to feature-branch
/plugin marketplace add alibaba/open-code-review
/plugin install open-code-review@open-code-review
```
`--audience agent` 标志会抑制进度 UI，输出简洁的结构化摘要。`--background` 标志提供需求上下文，让 OCR 可以验证实现是否符合意图。
此命令注册 `/open-code-review:review` 斜杠命令，运行 OCR 并自动过滤和修复问题。
#### 方式三：直接复制命令文件
如果不想使用任何包管理器，可以直接复制命令文件，在 Claude Code 中使用 `/open-code-review` 斜杠命令。
**项目级**（通过 git 与团队共享）：
```bash
mkdir -p .claude/commands
curl -o .claude/commands/open-code-review.md \
https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/commands/review.md
```
**用户级**（个人全局使用，适用于所有项目）：
```bash
mkdir -p ~/.claude/commands
curl -o ~/.claude/commands/open-code-review.md \
https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/commands/review.md
```
> **前置条件**：所有集成方式都需要安装 `ocr` CLI 并配置 LLM。参见上方[安装](#安装)和[配置 LLM](#1-配置-llm)。
## 命令
@ -346,16 +308,6 @@ OCR 通过四层优先级链解析评审规则。每层采用首次匹配原则
| `OCR_LLM_MODEL` | 模型名称 |
| `OCR_USE_ANTHROPIC` | `true` = Anthropic，`false` = OpenAI |
### 模板参数
内部默认值定义于 `internal/config/template/task_template.json`：
| 参数 | 默认值 | 描述 |
|------|--------|------|
| `MAX_TOKENS` | 58888 | 每次 LLM 请求最大 token 数 |
| `MAX_TOOL_REQUEST_TIMES` | 20 | 每个文件最大工具调用迭代次数 |
| `PLAN_MODE_LINE_THRESHOLD` | 50 | 低于此行数跳过计划阶段 |
| `TOOL_REQUEST_WAIT_TIME_MS` | 10000 | 单次工具请求超时时间 |
## 遥测
@ -369,62 +321,9 @@ ocr config set telemetry.otlp_endpoint localhost:4317
设置 `telemetry.content_logging` 可在导出数据中包含 LLM 提示词和响应。
## 开发
## 贡献
```bash
make build # 为当前平台构建
make test # 带竞态检测运行测试
make clean # 清除 dist/
make build-all # 交叉编译（linux/amd64, linux/arm64, darwin/amd64, darwin/arm64）
make dist # 完整发布流水线
```
## 集成到编程 Agent
OCR 可以无缝集成到 AI 编程 Agent 中，作为斜杠命令使用，在 Agent 工作流中直接进行代码审查。
### 方式一：作为 Skill 安装
使用 `npx` 将 OCR skill 安装到项目中：
```bash
npx skills add alibaba/open-code-review --skill open-code-review
```
此命令从 [skills 注册表](skills/open-code-review/SKILL.md)安装 `open-code-review` skill，教会你的编程 Agent 如何调用 `ocr` 进行代码审查、按优先级分类问题，并可选择性地应用修复。
### 方式二：作为 Claude Code Plugin 安装
对于 [Claude Code](https://docs.anthropic.com/en/docs/claude-code)，在 Claude Code 中通过以下命令安装命令插件：
```bash
/plugin marketplace add alibaba/open-code-review
/plugin install open-code-review@open-code-review
```
此命令注册 `/open-code-review:review` 斜杠命令，运行 OCR 并自动过滤和修复问题。
### 方式三：直接复制命令文件
如果不想使用任何包管理器，可以直接复制命令文件，在 Claude Code 中使用 `/open-code-review` 斜杠命令。
**项目级**（通过 git 与团队共享）：
```bash
mkdir -p .claude/commands
curl -o .claude/commands/open-code-review.md \
https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/commands/review.md
```
**用户级**（个人全局使用，适用于所有项目）：
```bash
mkdir -p ~/.claude/commands
curl -o ~/.claude/commands/open-code-review.md \
https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/commands/review.md
```
> **前置条件**：所有集成方式都需要安装 `ocr` CLI 并配置 LLM。参见上方[安装](#安装)和[配置 LLM](#1-配置-llm)。
参见 [CONTRIBUTING.zh-CN.md](CONTRIBUTING.zh-CN.md) 了解开发环境搭建、编码规范以及如何提交 Pull Request。
## 许可证