@alibaba-group/open-code-review 1.1.7 → 1.1.8

package/.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"
+    }
+  ]
+}

package/CONTRIBUTING.md

@@ -0,0 +1,219 @@
+# Contributing to OpenCodeReview
+
+Thank you for your interest in contributing to OpenCodeReview! Every contribution matters — whether it's fixing a typo, reporting a bug, or implementing a new feature.
+
+[简体中文版](CONTRIBUTING.zh-CN.md)
+
+## Code of Conduct
+
+By participating in this project, you agree to maintain a respectful and inclusive environment. Please be kind and constructive in all interactions.
+
+## Ways to Contribute
+
+There are many ways to contribute beyond writing code:
+
+- **Report bugs** — Found something broken? Open an issue with reproduction steps.
+- **Suggest features** — Have an idea for improvement? You can start a conversation in [GitHub Discussions](https://github.com/alibaba/open-code-review/discussions/categories/ideas) or open a [Feature Request](https://github.com/alibaba/open-code-review/issues/new?template=feature_request.yml) issue.
+- **Improve documentation** — Fix typos, clarify explanations, or add examples. You can also open a [Documentation Issue](https://github.com/alibaba/open-code-review/issues/new?template=docs_report.yml) to report problems.
+- **Review pull requests** — Help us review code from other contributors.
+- **Write code** — Fix bugs, add features, or improve performance.
+
+## Getting Started
+
+### Prerequisites
+
+- [Go 1.25+](https://go.dev/dl/)
+- [Git](https://git-scm.com/)
+- [Make](https://www.gnu.org/software/make/)
+
+### Setup
+
+```bash
+# 1. Fork the repository on GitHub
+
+# 2. Clone your fork
+git clone https://github.com/<your-username>/open-code-review.git
+cd open-code-review
+
+# 3. Add upstream remote (for syncing updates from the main repo)
+git remote add upstream https://github.com/alibaba/open-code-review.git
+
+# 4. Build the project
+make build
+
+# 5. Run tests
+make test
+```
+
+If everything passes, you're ready to contribute.
+
+> **Note:** The `upstream` remote is read-only for contributors — it is used to pull the latest changes from the main repository. You cannot push directly to upstream. All contributions must be pushed to your fork (`origin`) and submitted via Pull Request.
+
+## Development Workflow
+
+### Branching
+
+Create a feature branch from `main`:
+
+```bash
+git checkout main
+git pull upstream main
+git checkout -b feat/your-feature-name
+```
+
+Use prefixes to indicate the type of change:
+
+| Prefix      | Purpose                               |
+| ----------- | ------------------------------------- |
+| `feat/`     | New feature                           |
+| `fix/`      | Bug fix                               |
+| `docs/`     | Documentation only                    |
+| `refactor/` | Code refactoring (no behavior change) |
+| `test/`     | Adding or updating tests              |
+| `chore/`    | Build, CI, or tooling changes         |
+
+### Commit Messages
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/) format:
+
+```
+<type>(<scope>): <short summary>
+
+[optional body]
+```
+
+Examples:
+
+```
+feat(agent): add support for custom tool definitions
+fix(llm): handle timeout errors in Anthropic API calls
+docs(README): update configuration examples
+```
+
+### Code Quality
+
+Before submitting your changes, make sure they pass all checks:
+
+```bash
+# Format and lint (Go standard tooling)
+go fmt ./...
+go vet ./...
+
+# Run tests with race detection
+make test
+
+# Build successfully
+make build
+```
+
+### Project Structure
+
+```
+├── cmd/opencodereview/   # CLI entry point
+├── internal/
+│   ├── agent/            # Review agent logic
+│   ├── config/           # Configuration management
+│   ├── diff/             # Git diff parsing
+│   ├── llm/              # LLM API client (Anthropic & OpenAI)
+│   ├── model/            # Data models
+│   ├── session/          # Review session management
+│   ├── tool/             # Built-in tools (file_read, code_search, etc.)
+│   ├── telemetry/        # OpenTelemetry integration
+│   └── viewer/           # WebUI session viewer
+├── pages/                # WebUI frontend
+├── scripts/              # Build & install scripts
+└── bin/                  # NPM wrapper
+```
+
+## Contributing to Documentation
+
+Documentation is a crucial part of OpenCodeReview. We welcome improvements to README files, inline code comments, configuration examples, and any user-facing text.
+
+### What Counts as a Documentation Contribution
+
+- Fixing typos, grammar errors, or broken links
+- Clarifying confusing explanations or adding missing context
+- Adding usage examples for commands or configuration options
+- Updating outdated content (e.g., after a feature change)
+- Translating or improving the Chinese documentation (`README.zh-CN.md`, `CONTRIBUTING.zh-CN.md`)
+
+### Documentation Workflow
+
+1. If you spot an issue but don't plan to fix it yourself, open a [Documentation Issue](https://github.com/alibaba/open-code-review/issues/new?template=docs_report.yml).
+2. If you'd like to fix it, fork the repo, make your changes, and submit a PR with the `docs/` branch prefix (e.g., `docs/fix-config-example`).
+3. Documentation-only PRs don't require test changes, but please verify that any commands or code snippets you include are accurate.
+
+### Documentation Files
+
+| File                    | Purpose                              |
+| ----------------------- | ------------------------------------ |
+| `README.md`             | Main project documentation (English) |
+| `README.zh-CN.md`       | Chinese translation                  |
+| `CONTRIBUTING.md`       | Contribution guide (English)         |
+| `CONTRIBUTING.zh-CN.md` | Contribution guide (Chinese)         |
+| `NPM-README.md`         | Description shown on npm registry    |
+
+## Submitting Changes
+
+### Opening an Issue
+
+Before working on a significant change, please open an issue first to discuss the approach. This prevents duplicate work and ensures your contribution aligns with the project's direction.
+
+When reporting a bug, include:
+
+1. OpenCodeReview version (`ocr version`)
+2. OS and architecture
+3. Steps to reproduce
+4. Expected vs. actual behavior
+5. Relevant logs or error messages
+
+### Pull Request Process
+
+1. **Keep PRs focused** — One logical change per PR. If you have multiple independent changes, submit separate PRs.
+2. **Write tests** — Add or update tests for any behavior changes.
+3. **Update docs** — If your change affects user-facing behavior, update the relevant documentation.
+4. **Sign the CLA** — All contributors must sign the Contributor License Agreement before their PR can be merged (see below).
+5. **Fill in the PR template** — Describe what your change does and why.
+
+### PR Title Format
+
+Use the same Conventional Commits format as commit messages:
+
+```
+feat(agent): add support for custom tool definitions
+```
+
+### Review Process
+
+- A maintainer will review your PR, usually within a few business days.
+- We may request changes — this is normal and collaborative, not adversarial.
+- Once approved, a maintainer will merge your PR.
+
+## Contributor License Agreement (CLA)
+
+We require all contributors to sign the Alibaba Open Source Contributor License Agreement before we can merge your contributions. This ensures that the project can be distributed under its license terms.
+
+When you open your first PR, a CLA bot will post a comment with instructions. Simply follow the link to sign electronically — it only takes a minute.
+
+## First-Time Contributors
+
+New to the project? Look for issues labeled:
+
+- [`good first issue`](https://github.com/alibaba/open-code-review/labels/good%20first%20issue) — Small, well-scoped tasks ideal for getting started.
+- [`help wanted`](https://github.com/alibaba/open-code-review/labels/help%20wanted) — Issues where we'd appreciate community help.
+
+Some good areas to start:
+
+- Improving error messages and CLI output
+- Writing tests for untested code paths
+- Documentation improvements
+
+## Community
+
+- **Bug Reports** — [GitHub Issues](https://github.com/alibaba/open-code-review/issues)
+- **Feature Suggestions** — [GitHub Discussions (Ideas)](https://github.com/alibaba/open-code-review/discussions/categories/ideas) or [Feature Request Issue](https://github.com/alibaba/open-code-review/issues/new?template=feature_request.yml)
+- **Questions & Help** — If you have any questions about using OpenCodeReview, feel free to ask in [GitHub Discussions](https://github.com/alibaba/open-code-review/discussions)
+
+## License
+
+By contributing to OpenCodeReview, you agree that your contributions will be licensed under the [Apache License 2.0](LICENSE).

package/CONTRIBUTING.zh-CN.md

@@ -0,0 +1,219 @@
+# 贡献指南
+
+感谢你对 OpenCodeReview 的关注！无论是修复拼写错误、报告 Bug，还是实现新功能，每一份贡献都很有价值。
+
+[English version](CONTRIBUTING.md)
+
+## 行为准则
+
+参与本项目即表示你同意维护一个尊重和包容的环境。请在所有交流中保持友善和建设性。
+
+## 贡献方式
+
+除了写代码，还有很多方式可以参与贡献：
+
+- **报告 Bug** — 发现问题？请提交 issue 并附上复现步骤。
+- **建议功能** — 有改进想法？可以在 [GitHub Discussions](https://github.com/alibaba/open-code-review/discussions/categories/ideas) 中发起讨论，或直接提交一个 [Feature Request](https://github.com/alibaba/open-code-review/issues/new?template=feature_request.yml) issue。
+- **改进文档** — 修复错别字、完善说明或补充示例。也可以提交一个 [Documentation Issue](https://github.com/alibaba/open-code-review/issues/new?template=docs_report.yml) 来报告文档问题。
+- **审查 PR** — 帮助我们审查其他贡献者的代码。
+- **编写代码** — 修复 Bug、添加功能或提升性能。
+
+## 快速开始
+
+### 前置条件
+
+- [Go 1.25+](https://go.dev/dl/)
+- [Git](https://git-scm.com/)
+- [Make](https://www.gnu.org/software/make/)
+
+### 环境搭建
+
+```bash
+# 1. 在 GitHub 上 Fork 本仓库
+
+# 2. 克隆你的 Fork
+git clone https://github.com/<你的用户名>/open-code-review.git
+cd open-code-review
+
+# 3. 添加上游远端（用于同步主仓库的最新变更）
+git remote add upstream https://github.com/alibaba/open-code-review.git
+
+# 4. 构建项目
+make build
+
+# 5. 运行测试
+make test
+```
+
+如果一切通过，就可以开始贡献了。
+
+> **注意：** `upstream` 远端对贡献者是只读的，仅用于拉取主仓库的最新更新。你不能直接向 upstream 推送代码，所有贡献必须推送到你的 fork（`origin`），然后通过 Pull Request 提交。
+
+## 开发工作流
+
+### 分支管理
+
+从 `main` 创建功能分支：
+
+```bash
+git checkout main
+git pull upstream main
+git checkout -b feat/your-feature-name
+```
+
+使用前缀标明变更类型：
+
+| 前缀        | 用途                   |
+| ----------- | ---------------------- |
+| `feat/`     | 新功能                 |
+| `fix/`      | Bug 修复               |
+| `docs/`     | 仅文档变更             |
+| `refactor/` | 代码重构（无行为变化） |
+| `test/`     | 添加或更新测试         |
+| `chore/`    | 构建、CI 或工具链变更  |
+
+### 提交信息
+
+遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范：
+
+```
+<type>(<scope>): <简短描述>
+
+[可选的详细说明]
+```
+
+示例：
+
+```
+feat(agent): add support for custom tool definitions
+fix(llm): handle timeout errors in Anthropic API calls
+docs(README): update configuration examples
+```
+
+### 代码质量
+
+提交前请确保通过以下检查：
+
+```bash
+# 格式化和静态检查
+go fmt ./...
+go vet ./...
+
+# 带竞态检测运行测试
+make test
+
+# 构建成功
+make build
+```
+
+### 项目结构
+
+```
+├── cmd/opencodereview/   # CLI 入口
+├── internal/
+│   ├── agent/            # 评审 Agent 逻辑
+│   ├── config/           # 配置管理
+│   ├── diff/             # Git diff 解析
+│   ├── llm/              # LLM API 客户端（Anthropic & OpenAI）
+│   ├── model/            # 数据模型
+│   ├── session/          # 评审会话管理
+│   ├── tool/             # 内置工具（file_read, code_search 等）
+│   ├── telemetry/        # OpenTelemetry 集成
+│   └── viewer/           # WebUI 会话查看器
+├── pages/                # WebUI 前端
+├── scripts/              # 构建和安装脚本
+└── bin/                  # NPM 包装器
+```
+
+## 文档贡献
+
+文档是 OpenCodeReview 的重要组成部分。我们欢迎对 README、代码注释、配置示例以及任何面向用户的文本进行改进。
+
+### 哪些算文档贡献
+
+- 修复错别字、语法错误或失效链接
+- 完善表述不清的说明或补充缺失的上下文
+- 为命令或配置项添加使用示例
+- 更新过时的内容（例如功能变更后的文档同步）
+- 翻译或改进中英文文档（`README.zh-CN.md`、`CONTRIBUTING.zh-CN.md`）
+
+### 文档贡献流程
+
+1. 如果你发现问题但暂时不打算自己修复，请提交一个 [Documentation Issue](https://github.com/alibaba/open-code-review/issues/new?template=docs_report.yml)。
+2. 如果你想直接修复，fork 仓库后修改，提交 PR 时使用 `docs/` 分支前缀（例如 `docs/fix-config-example`）。
+3. 纯文档 PR 不需要修改测试，但请确保文中涉及的命令和代码片段准确无误。
+
+### 文档文件一览
+
+| 文件                    | 用途                 |
+| ----------------------- | -------------------- |
+| `README.md`             | 项目主文档（英文）   |
+| `README.zh-CN.md`       | 中文翻译             |
+| `CONTRIBUTING.md`       | 贡献指南（英文）     |
+| `CONTRIBUTING.zh-CN.md` | 贡献指南（中文）     |
+| `NPM-README.md`         | npm 发布页展示的说明 |
+
+## 提交变更
+
+### 提交 Issue
+
+在进行重大修改之前，请先开一个 issue 讨论方案。这可以避免重复劳动，并确保你的贡献与项目方向一致。
+
+报告 Bug 时请包含：
+
+1. OpenCodeReview 版本（`ocr version`）
+2. 操作系统和架构
+3. 复现步骤
+4. 预期行为与实际行为
+5. 相关日志或错误信息
+
+### Pull Request 流程
+
+1. **保持 PR 聚焦** — 每个 PR 只包含一个逻辑变更。多个独立改动请分别提交 PR。
+2. **编写测试** — 为行为变更添加或更新测试。
+3. **更新文档** — 如果变更影响用户侧行为，请同步更新相关文档。
+4. **签署 CLA** — 所有贡献者需在 PR 合并前签署贡献者许可协议（详见下方）。
+5. **填写 PR 模板** — 描述你的改动是什么以及为什么这样做。
+
+### PR 标题格式
+
+使用与 commit message 相同的 Conventional Commits 格式：
+
+```
+feat(agent): add support for custom tool definitions
+```
+
+### 审查流程
+
+- 维护者通常会在几个工作日内审查你的 PR。
+- 我们可能会要求修改——这很正常，是协作而非对立。
+- 一旦批准，维护者会合并你的 PR。
+
+## 贡献者许可协议（CLA）
+
+我们要求所有贡献者在合并代码前签署阿里巴巴开源贡献者许可协议（CLA）。这确保项目可以在其许可条款下合法分发。
+
+当你首次提交 PR 时，CLA bot 会自动发布评论并附上签署说明。只需点击链接进行电子签署即可，整个过程只需一分钟。
+
+## 新手推荐
+
+第一次参与？可以关注以下标签的 issue：
+
+- [`good first issue`](https://github.com/alibaba/open-code-review/labels/good%20first%20issue) — 小型、范围明确的任务，适合快速上手。
+- [`help wanted`](https://github.com/alibaba/open-code-review/labels/help%20wanted) — 我们希望得到社区帮助的问题。
+
+适合入手的方向：
+
+- 改善错误信息和 CLI 输出
+- 为未覆盖的代码路径编写测试
+- 文档改进
+
+## 社区
+
+- **Bug 报告** — [GitHub Issues](https://github.com/alibaba/open-code-review/issues)
+- **功能建议** — [GitHub Discussions (Ideas)](https://github.com/alibaba/open-code-review/discussions/categories/ideas) 或 [Feature Request Issue](https://github.com/alibaba/open-code-review/issues/new?template=feature_request.yml)
+- **使用疑问与帮助** — 对 OpenCodeReview 的使用有任何疑问，欢迎在 [GitHub Discussions](https://github.com/alibaba/open-code-review/discussions) 中提问交流
+
+## 许可证
+
+向 OpenCodeReview 贡献代码即表示你同意你的贡献将以 [Apache License 2.0](LICENSE) 进行许可。

package/README.zh-CN.md

@@ -15,15 +15,53 @@
 
 ---
 
-AI 驱动的代码审查 CLI 工具，读取 Git diff，通过具备工具调用能力的 Agent 将变更文件发送至可配置的 LLM，生成具有行级精度的结构化审查意见。
+## Open Code Review 是什么？
 
-Agent 可以读取完整文件内容、搜索代码库、检查其他变更文件以获取上下文，从而进行深度审查 —— 而非仅停留在表面的 diff 反馈。
+Open Code Review 是一款 AI 驱动的代码审查 CLI 工具。它的前身是阿里集团内部官方 AI 代码审查助手，过去两年在内部服务了数万开发者，识别了数百万个代码缺陷。经过大规模充分验证后，我们将其孵化为开源项目，对社区开放。只需配置一个模型端点即可使用。
 
-![Open Benchmark](imgs/open-benchmark.png)
+它读取 Git diff，通过具备工具调用能力的 Agent 将变更文件发送至可配置的 LLM，生成具有行级精度的结构化审查意见。Agent 可以读取完整文件内容、搜索代码库、检查其他变更文件以获取上下文，从而进行深度审查——而非仅停留在表面的 diff 反馈。
 
-## 安装
+![Highlights](imgs/highlights-zh.png)
 
-### 通过 NPM 安装（推荐）
+## 为什么选择 Open Code Review？
+
+### 通用 Agent 的局限
+
+如果你深度用过 Claude Code 等通用 Agent + Skills 方案做代码审查，可能对以下问题深有同感：
+
+- **覆盖不全** —— 变更较大时，Agent 倾向于"偷懒"，选择性地审查部分文件，导致遗漏。
+- **位置漂移** —— 报告的问题与实际代码位置常常对不上，出现行号或文件偏移。
+- **效果不稳定** —— 基于自然语言驱动的 Skills 难以调试，审查质量因提示词的细微差异而大幅波动。
+
+这些问题的根源在于：纯语言驱动的架构缺乏对审查流程的强约束。
+
+### 核心设计：确定性工程 × Agent 混合驱动
+
+Open Code Review 的核心设计理念是将确定性工程与 Agent 结合，各司其职。
+
+**确定性工程——负责强约束**
+
+对代码审查场景中"不能出错"的环节，由工程逻辑而非语言模型来保证：
+
+- **精准的文件筛选** —— 明确哪些文件需要审查、哪些应当过滤，确保真正重要的改动一个不漏。
+- **智能的文件打包** —— 将关联文件归并为同一审查单元（例如 `message_en.properties` 与 `message_zh.properties` 会被打包在一起）。每个包会作为 sub-agent 进行任务，它们之间的上下文是隔离的——这一分治策略在超大变更场景下表现更为稳定，同时天然支持并发审查。
+- **精细化规则匹配** —— 针对不同文件的特征，匹配对应的审查规则，确保模型的注意力足够聚焦，从源头规避信息噪声的干扰。相比纯语言驱动的规则引导，基于模板引擎的规则匹配行为更稳定、结果更可预期。
+- **外挂的定位与反思组件** —— 独立的评论定位模块与评论反思模块，系统性地提升 AI 反馈的位置准确性与内容准确性。
+
+**Agent——负责动态决策**
+
+将 Agent 的优势集中发挥在它真正擅长的地方——动态决策、动态召回上下文：
+
+- **场景化提示词调优** —— 针对代码审查场景深度优化提示词模板，在提升效果的同时有效降低 Token 消耗。
+- **场景化工具集沉淀** —— 基于对大量线上数据中工具调用轨迹的深入分析，包括不同工具的调用频率分布、单一工具的重复调用率、新增工具对整体调用链路的影响等多维度分析，从而对通用 Agent 工具集进行取舍与拆分，最终沉淀出一套在代码审查场景下效果更稳定、行为更可预期的专属工具集。
+
+## 如何使用
+
+### CLI
+
+#### 安装
+
+**通过 NPM 安装（推荐）**
 
 ```bash
 npm install -g @alibaba-group/open-code-review
@@ -31,7 +69,7 @@ npm install -g @alibaba-group/open-code-review
 
 安装后，`ocr` 命令即可全局使用。
 
-### 从 GitHub Release 下载
+**从 GitHub Release 下载**
 
 从 [GitHub Releases](https://github.com/alibaba/open-code-review/releases) 下载最新二进制文件：
 
@@ -53,7 +91,7 @@ curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/downloa
 chmod +x ocr && sudo mv ocr /usr/local/bin/ocr
 ```
 
-### 从源码构建
+**从源码构建**
 
 ```bash
 git clone https://github.com/alibaba/open-code-review.git
@@ -62,9 +100,9 @@ make build
 sudo cp dist/opencodereview /usr/local/bin/ocr
 ```
 
-## 快速开始
+#### 快速开始
 
-### 1. 配置 LLM
+**1. 配置 LLM**
 
 **在审查代码之前，必须先配置 LLM。**
 
@@ -84,15 +122,15 @@ export OCR_USE_ANTHROPIC=true
 
 配置存储于 `~/.opencodereview/config.json`。
 
-工具也会回退使用 Claude Code 环境变量（`ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_MODEL`），并解析 `~/.zshrc` / `~/.bashrc` 中的相关导出。
+同时兼容了 Claude Code 环境变量（`ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_MODEL`），并解析 `~/.zshrc` / `~/.bashrc` 中的相关导出。
 
-### 2. 测试连通性
+**2. 测试连通性**
 
 ```bash
 ocr llm test
 ```
 
-### 3. 开始审查
+**3. 开始审查**
 
 ```bash
 cd your-project
@@ -107,6 +145,53 @@ ocr review --from main --to feature-branch
 ocr review --commit abc123
 ```
 
+### 集成到编程 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)。
+
 ## 命令
 
 | 命令 | 别名 | 描述 |
@@ -196,20 +281,6 @@ OCR 通过四层优先级链解析评审规则。每层采用首次匹配原则
 - 在每一层内，规则按声明顺序评估 —— 首次匹配生效。
 - 如果规则文件不存在，将被静默跳过。
 
-## 架构
-
-审查 Agent 遵循**三阶段工作流**：
-
-1. **计划阶段** —— 对于超过 50 行的变更，Agent 会在审查前进行风险分析。较小的 diff 直接跳至主阶段。
-2. **主任务循环** —— 每个变更文件分配独立的 goroutine。LLM 在对话循环中与内置工具交互（读取文件、搜索代码、读取 diff、提交评论），直到调用 `task_done`。
-3. **记忆压缩** —— 当提示上下文超过 token 阈值（异步 60%，同步 80%）时，Agent 使用三区分区（冻结 / 压缩 / 活跃）管理上下文窗口大小。
-
-### 关键设计决策
-
-- **按文件并发处理** —— 文件并行审查（默认 8 个 worker）。超时机制防止单个文件阻塞其他文件。
-- **双协议支持** —— 同时支持 Anthropic Messages API 和 OpenAI Chat Completions API，自动 URL 规范化。
-- **工具调用 Agent** —— LLM 可以访问领域特定工具（`code_search`、`file_read`、`code_comment`、`file_find`、`file_read_diff`），实现跨引用的上下文感知审查，而非孤立的 diff 扫描。
-
 ## 配置参考
 
 配置文件：`~/.opencodereview/config.json`
@@ -237,48 +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 | 单次工具请求超时时间 |
-
-## 内置工具
-
-审查过程中 LLM Agent 可调用的工具：
-
-| 工具 | 可用阶段 | 用途 |
-|------|----------|------|
-| `task_done` | main_task | 终止审查（DONE/FAILED） |
-| `code_comment` | main_task | 提交行级审查意见 |
-| `file_read` | main_task | 按行范围读取文件内容 |
-| `code_search` | plan + main | 跨文件搜索文本/正则表达式 |
-| `file_read_diff` | plan + main | 查看其他变更文件的 diff 内容 |
-| `file_find` | plan + main | 按文件名关键词查找文件 |
-
-## 系统审查规则
-
-按文件类型通过 glob 模式匹配的内置审查清单，定义于 `internal/config/rules/system_rules.json`：
-
-| 模式 | 关注领域 |
-|------|----------|
-| `*.java` | NPE 风险、死循环、switch 穿透、N+1 查询、线程安全 |
-| `*.{ts,js,tsx,jsx}` | 代码质量、React 最佳实践、异步规范、XSS/安全 |
-| `*.kt` | 空安全、协程使用、惯用模式 |
-| `*{go,py,ets,lua,dart,swift,groovy}` | 逻辑缺陷、拼写错误 |
-| `*{cpp,cc,hpp}` | 智能指针、RAII、STL、const 正确性 |
-| `*.c` | malloc/free 配对、缓冲区溢出 |
-| `pom.xml` / `build.gradle` | 禁止 SNAPSHOT 版本 |
-| `package.json` | latest/通配符版本、依赖冲突 |
-| `*mapper*.xml` / `*dao*.xml` | SQL 注入、性能、逻辑错误 |
-| `*.properties` | 拼写检测、重复键、安全问题 |
-
-可通过 `--rule path/to/rules.json` 覆盖。
 
 ## 遥测
 
@@ -292,15 +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       # 完整发布流水线
-```
+参见 [CONTRIBUTING.zh-CN.md](CONTRIBUTING.zh-CN.md) 了解开发环境搭建、编码规范以及如何提交 Pull Request。
 
 ## 许可证
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alibaba-group/open-code-review",
-  "version": "1.1.7",
+  "version": "1.1.8",
   "description": "OpenCodeReview CLI — AI-powered code review tool",
   "bin": {
     "ocr": "bin/ocr.js"

package/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"
+}

package/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.

package/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