From 2d7697a7fe7d2710e12b7da11f09fc236b2d2e16 Mon Sep 17 00:00:00 2001 From: Lei Zhang Date: Fri, 29 May 2026 10:19:25 +0800 Subject: [PATCH] Feat: add support for plugins and skills installation (#5) * feat: add open-code-review skill for agent integration Add skills/open-code-review/SKILL.md that teaches coding agents how to invoke ocr for code review, classify issues by priority, and optionally apply fixes. * feat: add Claude Code plugin for open-code-review Add .claude-plugin/marketplace.json and plugins/open-code-review/ with plugin configuration and review command, enabling installation as a Claude Code slash command plugin. * docs: add agent integration section to README (EN/ZH) Add 'Integration into Coding Agents' section covering three methods: skill installation, Claude Code plugin, and direct command file copy. Bilingual update for both README.md and README.zh-CN.md. * docs: update manual setup curl URLs to new plugin path --- .claude-plugin/marketplace.json | 16 ++ README.md | 47 ++++ README.zh-CN.md | 47 ++++ .../.claude-plugin/plugin.json | 6 + plugins/open-code-review/commands/review.md | 35 +++ skills/open-code-review/SKILL.md | 231 ++++++++++++++++++ 6 files changed, 382 insertions(+) create mode 100644 .claude-plugin/marketplace.json create mode 100644 plugins/open-code-review/.claude-plugin/plugin.json create mode 100644 plugins/open-code-review/commands/review.md create mode 100644 skills/open-code-review/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..725cfd0 --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,16 @@ +{ + "name": "open-code-review", + "owner": { + "name": "alibaba" + }, + "description": "AI-powered code review agent that reads Git diffs, analyzes changed files with LLM tool-use capabilities, and generates structured line-level review comments with cross-referential context awareness.", + "plugins": [ + { + "name": "open-code-review", + "source": "./plugins/open-code-review", + "description": "Perform AI code review on Git diffs — supports workspace changes, branch ranges, and single commits with concurrent per-file analysis, codebase search, and deep context-aware review.", + "version": "1.0.0", + "license": "Apache-2.0" + } + ] +} diff --git a/README.md b/README.md index 448b842..f674eed 100644 --- a/README.md +++ b/README.md @@ -302,6 +302,53 @@ make build-all # Cross-compile (linux/amd64, linux/arm64, darwin/amd64, darwin/ 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. + ## License [Apache-2.0](LICENSE) — Copyright 2026 Alibaba diff --git a/README.zh-CN.md b/README.zh-CN.md index 88956d0..6fecbcb 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -302,6 +302,53 @@ make build-all # 交叉编译（linux/amd64, linux/arm64, darwin/amd64, darwin/ 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)。 + ## 许可证 [Apache-2.0](LICENSE) — Copyright 2026 Alibaba diff --git a/plugins/open-code-review/.claude-plugin/plugin.json b/plugins/open-code-review/.claude-plugin/plugin.json new file mode 100644 index 0000000..2560e0c --- /dev/null +++ b/plugins/open-code-review/.claude-plugin/plugin.json @@ -0,0 +1,6 @@ +{ + "name": "open-code-review", + "commands": "./commands", + "description": "Perform AI code review on Git diffs — supports workspace changes, branch ranges, and single commits with concurrent per-file analysis, codebase search, and deep context-aware review.", + "version": "1.0.0" +} \ No newline at end of file diff --git a/plugins/open-code-review/commands/review.md b/plugins/open-code-review/commands/review.md new file mode 100644 index 0000000..82a1e99 --- /dev/null +++ b/plugins/open-code-review/commands/review.md @@ -0,0 +1,35 @@ +--- +description: Run OpenCodeReview (OCR) to review code changes and autonomously apply fixes. +--- + +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: + +```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. \ No newline at end of file diff --git a/skills/open-code-review/SKILL.md b/skills/open-code-review/SKILL.md new file mode 100644 index 0000000..ff61473 --- /dev/null +++ b/skills/open-code-review/SKILL.md @@ -0,0 +1,231 @@ +--- +name: open-code-review +description: > + Performs AI-powered code review on Git changes using the `ocr` CLI from + alibaba/open-code-review. Use when the user asks to review code, review + a pull request, review staged/unstaged changes, review a commit, or + compare branches for code quality issues. Produces line-level review + comments and can automatically apply fixes when requested. With appropriate + review rules, can detect various types of issues including bugs, security + vulnerabilities, performance problems, and code quality concerns. +license: Apache-2.0 +compatibility: > + Requires the `ocr` CLI installed (via `npm install -g + @alibaba-group/open-code-review` or GitHub release binary). Requires a + configured LLM (Anthropic or OpenAI-compatible) before first run. +metadata: + author: alibaba + homepage: https://github.com/alibaba/open-code-review + version: "1.0.0" +--- + +# Open Code Review + +A skill for invoking [open-code-review](https://github.com/alibaba/open-code-review) (`ocr`) — an open-source AI code review CLI that reads Git diffs and generates structured, line-level review comments. + +## Prerequisites check + +Before starting a review, verify the environment: + +```bash +# 1. Check the CLI is installed +which ocr || echo "NOT INSTALLED" + +# 2. Verify LLM connectivity +ocr llm test +``` + +If `ocr` is not installed, install it first: + +```bash +npm install -g @alibaba-group/open-code-review +``` + +If `ocr llm test` fails, the user must configure an LLM. Guide them with one of these options: + +**Option A — Environment variables (highest priority, recommended for CI):** + +```bash +export OCR_LLM_URL=https://api.anthropic.com/v1/messages +export OCR_LLM_TOKEN= +export OCR_LLM_MODEL=claude-opus-4-6 +export OCR_USE_ANTHROPIC=true +``` + +**Option B — Persistent config:** + +```bash +ocr config set llm.url https://api.anthropic.com/v1/messages +ocr config set llm.auth_token +ocr config set llm.model claude-opus-4-6 +ocr config set llm.use_anthropic true +``` + +Stop here and ask the user to provide credentials — never invent or hardcode API keys. + +## Workflow + +### Step 1: Gather Business Context + +Analyze the review target (commits, branch, or changes) to extract concise business context. Pass this context via `--background` to improve review quality. + +### Step 2: Run Code Review + +Run the OCR command with appropriate flags. **Always pass business context via `--background`** when available: + +```bash +ocr review --audience agent --background "business context here" [user-args] +``` + +**Argument handling:** + +- **Background context** (RECOMMENDED): use `--background "context"` or `-b "context"` to provide business context for better review quality +- **Default** (no user arguments): reviews staged, unstaged, and untracked changes (workspace mode) +- **Specific commit**: use `--commit` or `-c` to review a single commit against its parent +- **Branch comparison**: use `--from ` and `--to ` to review diff between two refs +- **Timeout**: default timeout is 10 minutes per file; adjust with `--timeout ` +- **Concurrency**: default concurrency is 8 file workers; reduce with `--concurrency ` if rate limits are hit +- **Preview mode**: use `--preview` or `-p` to preview which files will be reviewed without running the LLM +- **Installation**: if `ocr` command is not found, install it by running `npm i -g @alibaba-group/open-code-review` + +**Common invocation patterns:** + +| User says | Command to run | +|-----------|---------------| +| "review my changes" / "review the working copy" | `ocr review --audience agent -b "context"` | +| "review this PR" / "review feature branch" | `ocr review --audience agent -b "context" --from main --to ` | +| "review commit abc123" | `ocr review --audience agent -b "context" --commit abc123` | +| "what would be reviewed?" (dry-run) | `ocr review --preview` | + +**Output mode:** + +- Always use `--audience agent` to suppress progress UI and emit only the final summary + +### Step 3: Classify and Report + +For each comment from the review output, classify by priority and report all issues to the user: + +- **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 + +Report all comments grouped by priority level. + +### Step 4: Fix + +Before applying fixes, check whether the user requested automatic fixes: + +- If the user explicitly requested "review and fix" or similar, proceed with automatic fixes +- If the user only requested "review" without fix intent, ask for permission before applying any changes + +When fixing issues and suggestions: + +- Focus on High and Medium priority items +- Apply fixes directly to the code when safe and well-defined +- For complex fixes requiring manual intervention, clearly describe what needs to be done +- Always verify fixes with the user before committing + +## Output Format + +Each comment contains: + +- `path`: File path +- `content`: Review comment text +- `start_line` / `end_line`: Line range (both 0 means positioning failed) +- `suggestion_code`: Optional fix suggestion +- `existing_code`: Optional original code snippet +- `thinking`: Optional LLM reasoning process + +After filtering comments by priority, present results using this template: + +```markdown +## Code Review Results + +**Files reviewed**: N +**Issues found**: X high priority / Y medium priority + +### High Priority + +- **`path/to/file.java:42`** — Brief description + > Recommendation: How to fix + +### Medium Priority + +- **`path/to/file.ts:88`** — Brief description + > Recommendation: How to fix (if applicable) +``` + +If the review found no issues after filtering, simply state: "Review complete — no issues found in N files." + +**Priority classification:** + +- **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**: Discarded silently (likely false positives, lacking context, nitpicks, or meaningless suggestions) + +**Handling mispositioned comments:** + +When `start_line` and `end_line` are both `0`, the comment failed to locate the exact position in the file. In such cases: + +1. Read the comment content to understand the issue +2. Examine the target file mentioned in the comment +3. Identify the relevant code section based on the comment's context +4. Apply the fix or suggestion to the correct location + +## Custom Review Rules + +If the user wants project-specific rules, OCR resolves them in this priority order: + +1. `--rule ` flag (highest) +2. `/.opencodereview/rule.json` +3. `~/.opencodereview/rule.json` +4. Built-in system defaults (lowest) + +Rule file format: + +```json +{ + "rules": [ + { + "path": "**/*.java", + "rule": "All new methods must validate required parameters for null" + }, + { + "path": "**/*mapper*.xml", + "rule": "Check SQL for injection risks and missing closing tags" + } + ] +} +``` + +To preview which rule applies to a file before reviewing: + +```bash +ocr rules check src/main/java/com/example/Foo.java +``` + +## Gotchas + +- **LLM must be configured first** — `ocr review` will fail loudly if no LLM is reachable. Always run `ocr llm test` before the first review. +- **Working directory matters** — `ocr review` operates on the Git repo at the current directory. Use `--repo /path/to/repo` to run from elsewhere. +- **Untracked files are reviewed in workspace mode** — running bare `ocr review` includes staged, unstaged, *and* untracked changes. Stage selectively if you want narrower scope. +- **Large diffs may hit token limits** — files with very large diffs may be truncated. The default `MAX_TOKENS` is 58888 per request. +- **Plan phase triggers at 50 lines** — diffs exceeding 50 changed lines run an extra risk-analysis phase before main review. This adds latency but improves quality. +- **Don't pass `--audience human`** — it streams progress UI that pollutes output. Always use `--audience agent`. +- **Comment language follows config** — set `language` config to `English` or `Chinese` (default: Chinese) to control review comment language. + +## Validation + +After the review completes, verify success by checking: + +1. The command exited with code 0 +2. Comments were generated (or "No comments generated" message appears) +3. Warnings (if any) are displayed in stderr + +If errors occurred, check the stderr warnings for details about which files failed and why. + +## References + +- Full docs: https://github.com/alibaba/open-code-review +- NPM package: https://www.npmjs.com/package/@alibaba-group/open-code-review +- Issue tracker: https://github.com/alibaba/open-code-review/issues