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

package/README.md

@@ -1,8 +1,67 @@
-# OpenCodeReview CLI
+<p align="center">
+  <a href="https://alibaba.github.io/open-code-review/">
+    <img src="imgs/logo.svg" alt="OpenCodeReview logo" width="240" height="240">
+  </a>
+</p>
+<p align="center">The open source AI code review agent.</p>
+<p align="center">
+  <a href="https://www.npmjs.com/package/@alibaba-group/open-code-review"><img alt="npm" src="https://img.shields.io/npm/v/@alibaba-group/open-code-review?style=flat-square" /></a>
+  <a href="https://github.com/alibaba/open-code-review/actions/workflows/release.yml"><img alt="Build status" src="https://img.shields.io/github/actions/workflow/status/alibaba/open-code-review/release.yml?style=flat-square" /></a>
+  <a href="https://github.com/alibaba/open-code-review/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/alibaba/open-code-review?style=flat-square" /></a>
+</p>
+<p align="center">
+  English | <a href="README.zh-CN.md">简体中文</a>
+</p>
 
-AI-powered code review tool that reads Git diffs, sends changed files to a configurable LLM via OpenAI-compatible API, and generates structured review comments. It goes beyond surface-level analysis — the Agent can read project context for deep reviews.
+---
 
-## Install
+## What is Open Code Review?
+
+Open Code Review is an AI-powered code review CLI tool. It originated as Alibaba Group's internal official AI code review assistant — over the past two years, it has served tens of thousands of developers and identified millions of code defects. After thorough validation at massive scale, we incubated it into an open source project for the community. Simply configure a model endpoint to get started.
+
+It reads Git diffs, sends changed files to a configurable LLM via an agent with tool-use capabilities, and generates structured review comments with line-level precision. The agent can read full file contents, search the codebase, inspect other changed files for context, and produce deep reviews — not just surface-level diff feedback.
+
+![Highlights](imgs/highlights-en.png)
+
+## Why Open Code Review?
+
+### The Problem with General-Purpose Agents
+
+If you've used general-purpose agents like Claude Code with Skills for code review, you've likely encountered these pain points:
+
+- **Incomplete coverage** — On larger changesets, agents tend to "cut corners," selectively reviewing only some files and missing others.
+- **Position drift** — Reported issues frequently don't match the actual code location, with line numbers or file references drifting off target.
+- **Unstable quality** — Natural-language-driven Skills are hard to debug, and review quality fluctuates significantly with minor prompt variations.
+
+The root cause: a purely language-driven architecture lacks hard constraints on the review process.
+
+### Core Design: Deterministic Engineering × Agent Hybrid
+
+Open Code Review's core philosophy is to combine deterministic engineering with an agent, each handling what it does best.
+
+**Deterministic Engineering — Hard Constraints**
+
+For review steps that *must not go wrong*, engineering logic — not the language model — guarantees correctness:
+
+- **Precise file selection** — Determines exactly which files need review and which should be filtered, ensuring no important change is missed.
+- **Smart file bundling** — Groups related files into a single review unit (e.g., `message_en.properties` and `message_zh.properties` are bundled together). Each bundle runs as a sub-agent with isolated context — a divide-and-conquer strategy that stays stable on very large changesets and naturally supports concurrent review.
+- **Fine-grained rule matching** — Matches review rules to each file's characteristics, keeping the model's attention sharply focused and eliminating information noise at the source. Compared to purely language-driven rule guidance, template-engine-based rule matching is more stable and predictable.
+- **External positioning and reflection modules** — Independent comment-positioning and comment-reflection modules systematically improve both the location accuracy and content accuracy of AI feedback.
+
+**Agent — Dynamic Decision-Making**
+
+The agent's strengths are concentrated where they matter most — dynamic decisions and dynamic context retrieval:
+
+- **Scenario-tuned prompts** — Prompt templates deeply optimized for code review, improving effectiveness while reducing token consumption.
+- **Scenario-tuned toolset** — Distilled from deep analysis of tool-call traces in large-scale production data — including call frequency distributions, per-tool repetition rates, and the impact of new tools on the overall call chain — resulting in a purpose-built toolset that is more stable and predictable for code review than a generic agent toolkit.
+
+## How to Use
+
+### CLI
+
+#### Install
+
+**Via NPM (Recommended)**
 
 ```bash
 npm install -g @alibaba-group/open-code-review
@@ -10,86 +69,283 @@ npm install -g @alibaba-group/open-code-review
 
 After installation, the `ocr` command is available globally.
 
-### Version Control
+**From GitHub Release**
+
+Download the latest binary from [GitHub Releases](https://github.com/alibaba/open-code-review/releases):
 
 ```bash
-# Install specific version
-OCR_VERSION=v1.0.0 npm install -g @alibaba-group/open-code-review
-```
+# macOS (Apple Silicon)
+curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-darwin-arm64
+chmod +x ocr && sudo mv ocr /usr/local/bin/ocr
 
-## Prerequisites
+# macOS (Intel)
+curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-darwin-amd64
+chmod +x ocr && sudo mv ocr /usr/local/bin/ocr
+
+# Linux (x86_64)
+curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-linux-amd64
+chmod +x ocr && sudo mv ocr /usr/local/bin/ocr
+
+# Linux (ARM64)
+curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-linux-arm64
+chmod +x ocr && sudo mv ocr /usr/local/bin/ocr
+```
 
-**You must configure an LLM provider before using `ocr`.** The tool requires access to an OpenAI-compatible API endpoint (OpenAI, Claude, local models, etc.).
+**From Source**
 
 ```bash
-ocr config set llm.url https://api.anthropic.com/v1/messages \
-    && ocr config set llm.auth_token {{your-api-key}} \
-    && ocr config set llm.model claude-opus-4-6 \
-    && ocr config set llm.use_anthropic true  \
-    && ocr config set language Chinese
+git clone https://github.com/alibaba/open-code-review.git
+cd open-code-review
+make build
+sudo cp dist/opencodereview /usr/local/bin/ocr
 ```
 
-Config is stored in `~/.opencodereview/config.json`.
+#### Quick Start
+
+**1. Configure LLM**
 
-Or via environment variables:
+**You must configure an LLM before reviewing code.**
 
 ```bash
+# Option A: Interactive config
+ocr config set llm.url https://api.anthropic.com/v1/messages
+ocr config set llm.auth_token your-api-key-here
+ocr config set llm.model claude-opus-4-6
+ocr config set llm.use_anthropic true
+
+# Option B: Environment variables (highest priority)
 export OCR_LLM_URL=https://api.anthropic.com/v1/messages
-export OCR_LLM_TOKEN=your-api-key
+export OCR_LLM_TOKEN=your-api-key-here
 export OCR_LLM_MODEL=claude-opus-4-6
+export OCR_USE_ANTHROPIC=true
 ```
 
-### Test Connectivity
+Config is stored in `~/.opencodereview/config.json`.
+
+It is also compatible with Claude Code environment variables (`ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`) and parses `~/.zshrc` / `~/.bashrc` for those exports.
+
+**2. Test Connectivity**
 
 ```bash
 ocr llm test
 ```
 
-## Quick Start
-
-Navigate to any Git repository and run:
+**3. Review**
 
 ```bash
-# Review all workspace changes
+cd your-project
+
+# Workspace mode — review all staged, unstaged, and untracked changes
 ocr review
 
-# Review diff between two branches
+# Branch range — compare two refs
 ocr review --from main --to feature-branch
 
-# Review a single commit
+# Single commit
 ocr review --commit abc123
 ```
 
+### Integrate with 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.
+
+### CI/CD Integration
+
+OCR can be integrated into CI/CD pipelines to automate code review on Merge Requests / Pull Requests.
+
+The core command for CI integration:
+
+```bash
+ocr review \
+  --from "origin/main" \
+  --to "origin/feature-branch" \
+  --format json \
+  --audience agent
+```
+
+The `--format json` and `--audience agent` flags output machine-readable results suitable for parsing in CI scripts.
+
+See the [`examples/`](./examples/) directory for integration examples:
+
+- [`github_actions/`](./examples/github_actions/) — GitHub Actions integration example
+- [`gitlab_ci/`](./examples/gitlab_ci/) — GitLab CI integration example
+
 ## Commands
 
-| Command | Description |
-|---------|-------------|
-| `ocr review` / `ocr r` | Start code review |
-| `ocr config set <key> <value>` | Manage configuration |
-| `ocr llm test` | Test LLM connectivity |
-| `ocr viewer` | Start WebUI session viewer |
-| `ocr version` | Show version info |
+| Command | Alias | Description |
+|---------|-------|-------------|
+| `ocr review` | `ocr r` | Start a code review |
+| `ocr rules check <file>` | — | Preview which review rule applies to a file path |
+| `ocr config set <key> <value>` | — | Set configuration values |
+| `ocr llm test` | — | Test LLM connectivity |
+| `ocr viewer` | `ocr v` | Launch WebUI session viewer on `localhost:5483` |
+| `ocr version` | — | Show version info |
 
-## Common Options
+### `ocr review` Flags
 
 | Flag | Shorthand | Default | Description |
 |------|-----------|---------|-------------|
-| `--repo` | | current dir | Git repository root |
-| `--from` | | | Source ref (e.g., `main`) |
-| `--to` | | | Target ref (e.g., `feature-branch`) |
-| `--commit` | `-c` | | Review a single commit |
+| `--repo` | — | current dir | Git repository root |
+| `--from` | — | — | Source ref (e.g., `main`) |
+| `--to` | — | — | Target ref (e.g., `feature-branch`) |
+| `--commit` | `-c` | — | Single commit to review |
+| `--preview` | `-p` | `false` | Preview which files will be reviewed without running the LLM |
 | `--format` | `-f` | `text` | Output format: `text` or `json` |
-| `--concurrency` | | `4` | Max concurrent file reviews |
-| `--timeout` | | `10` | Per-file timeout (minutes) |
+| `--concurrency` | — | `8` | Max concurrent file reviews |
+| `--timeout` | — | `10` | Concurrent task timeout in minutes |
+| `--audience` | — | `human` | `human` (show progress) or `agent` (summary only) |
+| `--rule` | — | — | Path to custom JSON review rules |
+| `--tools` | — | — | Path to custom JSON tools config |
+
+## Examples
+
+```bash
+# Preview which files will be reviewed (no LLM calls)
+ocr review --preview
+ocr review -c abc123 -p
+
+# Review workspace changes with default settings
+ocr review
+
+# Review branch diff with higher concurrency
+ocr review --from main --to my-feature --concurrency 4
+
+# Review a specific commit with verbose JSON output
+ocr review --commit abc123 --format json --audience agent
+
+# Use custom review rules
+ocr review --rule /path/to/my-rules.json
+
+# Preview which rule applies to a file
+ocr rules check src/main/java/com/example/Foo.java
+ocr rules check --rule custom.json src/main/resources/mapper/UserMapper.xml
+
+# View review session history in browser
+ocr viewer
+ocr viewer --addr :3000
+```
+
+## Review Rules
+
+OCR resolves review rules using a four-layer priority chain. Each layer uses first-match-wins: if a file path matches a pattern, that rule is used; otherwise it falls through to the next layer.
+
+| Priority | Source | Path | Description |
+|----------|--------|------|-------------|
+| 1 (highest) | `--rule` flag | User-specified path | CLI explicit override |
+| 2 | Project config | `<repoDir>/.opencodereview/rule.json` | Per-project rules, can be committed to git |
+| 3 | Global config | `~/.opencodereview/rule.json` | User-wide personal preferences |
+| 4 (lowest) | System default | Embedded `system_rules.json` | Built-in rules covering common languages and file types |
+
+### Rule File Format
+
+Layers 1–3 share the same JSON format:
+
+```json
+{
+  "rules": [
+    {
+      "path": "force-api/**/*.java",
+      "rule": "All new methods must validate required parameters for null values"
+    },
+    {
+      "path": "**/*mapper*.xml",
+      "rule": "Check SQL for injection risks, parameter errors, and missing closing tags"
+    }
+  ]
+}
+```
+
+- `path` supports `**` recursive matching and `{java,kt}` brace expansion.
+- Within each layer, rules are evaluated in declaration order — the first match wins.
+- If a rule file does not exist, it is silently skipped.
+
+## Configuration Reference
+
+Config file: `~/.opencodereview/config.json`
+
+| Key | Type | Example |
+|-----|------|---------|
+| `llm.url` | string | `https://api.openai.com/v1/chat/completions` |
+| `llm.auth_token` | string | `sk-xxxxxxx` |
+| `llm.model` | string | `claude-opus-4-6` |
+| `llm.use_anthropic` | boolean | `true` \| `false` |
+| `language` | string | `English` \| `Chinese` (default: Chinese) |
+| `telemetry.enabled` | boolean | `true` \| `false` |
+| `telemetry.exporter` | string | `console` \| `otlp` |
+| `telemetry.otlp_endpoint` | string | OTLP collector address |
+| `telemetry.content_logging` | boolean | Include prompts in telemetry |
+
+Environment variables take precedence over the config file.
+
+### Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `OCR_LLM_URL` | LLM API endpoint URL |
+| `OCR_LLM_TOKEN` | API key / auth token |
+| `OCR_LLM_MODEL` | Model name |
+| `OCR_USE_ANTHROPIC` | `true` = Anthropic, `false` = OpenAI |
+
+
+## Telemetry
+
+OpenTelemetry integration for observability (spans, metrics). Disabled by default.
+
+```bash
+ocr config set telemetry.enabled true
+ocr config set telemetry.exporter otlp
+ocr config set telemetry.otlp_endpoint localhost:4317
+```
+
+Set `telemetry.content_logging` to include LLM prompts and responses in exported data.
 
-## Features
+## Contributing
 
-- **Three review modes**: workspace changes, branch range, single commit
-- **Context-aware**: Agent reads arbitrary files, searches code via `git grep`, inspects diffs
-- **Plan phase**: Large changes (>50 lines) get risk analysis first
-- **Any LLM**: Works with OpenAI, Claude-compatible endpoints, local models
-- **Concurrent**: Files reviewed in parallel (configurable workers)
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding guidelines, and how to submit pull requests.
 
 ## License
 
-Apache-2.0
+[Apache-2.0](LICENSE) — Copyright 2026 Alibaba

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,74 @@ 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)。
+
+### CI/CD 集成
+
+OCR 可以集成到 CI/CD 流水线中，在 Merge Request / Pull Request 时自动进行代码审查。
+
+CI 集成的核心命令：
+
+```bash
+ocr review \
+  --from "origin/main" \
+  --to "origin/feature-branch" \
+  --format json \
+  --audience agent
+```
+
+`--format json` 和 `--audience agent` 参数输出适合 CI 脚本解析的机器可读结果。
+
+集成示例请参见 [`examples/`](./examples/) 目录：
+
+- [`github_actions/`](./examples/github_actions/) — GitHub Actions 集成示例
+- [`gitlab_ci/`](./examples/gitlab_ci/) — GitLab CI 集成示例
+
 ## 命令
 
 | 命令 | 别名 | 描述 |
@@ -196,20 +302,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 +329,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 +342,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/examples/README.md

@@ -0,0 +1,10 @@
+# CI/CD Integration Examples
+
+This directory contains examples for integrating OpenCodeReview (OCR) into various CI/CD pipelines.
+
+## Contents
+
+- **[github_actions/](./github_actions/)** - GitHub Actions integration example
+- **[gitlab_ci/](./gitlab_ci/)** - GitLab CI integration example
+
+Each subdirectory contains its own README with detailed setup instructions.