From 4fe9f0ef84ab0c88faf93d94c02365fe46fb5303 Mon Sep 17 00:00:00 2001 From: kite Date: Sat, 30 May 2026 19:17:53 +0800 Subject: [PATCH] docs(README): update --- README.md | 173 ++++++++++-------------------------------------- README.zh-CN.md | 173 ++++++++++-------------------------------------- 2 files changed, 72 insertions(+), 274 deletions(-) diff --git a/README.md b/README.md index b30eb96..eddc538 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/README.zh-CN.md b/README.zh-CN.md index 0619d70..c78a77d 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -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。 ## 许可证