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
2026-07-09 17:28:58 +00:00 · 2026-05-29 10:19:25 +08:00 · 2026-05-29 10:19:25 +08:00 · 2d7697a7fe
commit 2d7697a7fe
parent e6bac87344
6 changed files with 382 additions and 0 deletions
--- a/.claude-plugin/marketplace.json
+++ 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"
+    }
+  ]
+}
--- 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
--- 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
--- a/plugins/open-code-review/.claude-plugin/plugin.json
+++ 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"
+}
--- a/plugins/open-code-review/commands/review.md
+++ 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.
--- a/skills/open-code-review/SKILL.md
+++ 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=<api-key>
+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 <api-key>
+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 <ref>` and `--to <ref>` to review diff between two refs
+- **Timeout**: default timeout is 10 minutes per file; adjust with `--timeout <minutes>`
+- **Concurrency**: default concurrency is 8 file workers; reduce with `--concurrency <n>` 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 <branch>` |
+| "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 <path>` flag (highest)
+2. `<repo>/.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