## File: README.md --- ## 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. Beyond diff review, `ocr scan` reviews entire files for auditing unfamiliar codebases or directories that have no meaningful diff. Visit the [official website](https://open-codereview.ai) for more details. ## Benchmark > Compared to general-purpose agents (Claude Code), Open Code Review achieves significantly higher **Precision** and **F1** with the same underlying model, while consuming only **~1/9 of the tokens** and completing reviews faster. Note that its Recall is lower than general-purpose agents — a deliberate trade-off favoring precision over noise. A real-world code review benchmark built from **50** popular open-source repositories, **200** real Pull Requests, and **10** programming languages — cross-validated by 80+ senior engineers (**1,505** annotated ground-truth issues). [ Explore the AACR-Bench dataset on Hugging Face](https://huggingface.co/datasets/Alibaba-Aone/aacr-bench). | Metric | What it measures | Why it matters | |--------|-----------------|----------------| | **F1** | Harmonic mean of precision and recall | Best single number for overall review quality | | **Precision** | Proportion of reported issues that are real defects | Higher = fewer false alarms to triage | | **Recall** | Proportion of real defects that are found | Higher = fewer issues slip through review | | **Avg Time** | Wall-clock time per review | Matters for CI pipeline latency | | **Avg Token** | Total tokens consumed per review | Directly impacts API cost | ## 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 ### Prerequisites - **Git >= 2.41** — Open Code Review relies on Git for diff generation, code search, and repository operations. ### CLI #### Install ```bash npm install @alibaba-group/open-code-review ``` After installation, the `ocr` command is available globally. For other installation methods (install script, GitHub Release binary, from source), see [Installation](https://open-codereview.ai/docs/installation). #### Quick Start **1. Configure LLM** You must configure an LLM before reviewing code, unless you use [Delegation Mode](https://open-codereview.ai/docs/delegate). ```bash ocr config provider # Select a built-in provider or add a custom one ocr config model # Pick a model for the active provider ``` The interactive UI guides you through provider selection, API key entry, and model configuration, then automatically tests connectivity. For CLI setup, environment variables, custom providers, and other advanced configuration, see [Configuration](https://open-codereview.ai/docs/configuration). **2. Review** ```bash cd your-project # Workspace mode — review all staged, unstaged, and untracked changes ocr review # Branch range — reviews feature-branch's changes since it diverged from main (merge-base mode) ocr review --from main --to feature-branch # Single commit ocr review --commit abc123 # Resume an interrupted range or commit review ocr session list ocr review --from main --to feature-branch --resume # Full-file scan — review whole files instead of a diff (no git history needed) ocr scan # scan the entire repository ocr scan --path internal/agent # scan a directory or specific files ocr scan --resume # resume an interrupted full-file scan # Delegation mode — let your AI coding agent perform the review itself # OCR handles file selection and rule resolution; no LLM configuration needed ocr delegate preview ocr delegate rule src/main.go src/handler.go ``` ## Documentation Full documentation lives at **[open-codereview.ai/docs](https://open-codereview.ai/docs)**: - [Quickstart](https://open-codereview.ai/docs/quickstart) — install and run your first review - [Installation](https://open-codereview.ai/docs/installation) — all platforms and package managers - [CLI Reference](https://open-codereview.ai/docs/cli-reference) — every command and flag - [Review Rules](https://open-codereview.ai/docs/review-rules) — customize review rules with path filtering and targeting - [Configuration](https://open-codereview.ai/docs/configuration) — config keys and environment variables - [MCP Server](https://open-codereview.ai/docs/mcp) — extend the review agent with external tools - Coding Agent Integrations — choose the platform you use - [Claude Code](plugins/open-code-review/README.md#claude-code) — install a plugin with review slash commands - [Codex](plugins/open-code-review/README.md#codex) — install a plugin with callable review skills - [Cursor](plugins/open-code-review/README.md#cursor) — install a plugin with portable review skills - [OpenCode](plugins/open-code-review/opencode/README.md) — install native review tools and slash commands - [QCA Forward](plugins/open-code-review/qca/README.md) — run delegation mode with the QCA host model and a ready-to-publish template - [Skill-compatible agents](https://open-codereview.ai/docs/agent-skill) — install the portable agent skill - Review Execution Modes — after integration, choose which LLM performs the review - [Default (OCR-managed)](https://open-codereview.ai/docs/configuration) — OCR runs the review using its configured LLM - [Delegation Mode](https://open-codereview.ai/docs/delegate) — your coding agent runs the review using its own LLM; no OCR API key required - [CI/CD Integration](https://open-codereview.ai/docs/cicd) — GitHub Actions, GitLab CI, GitFlic CI, and Gerrit integration - [Session Viewer](https://open-codereview.ai/docs/viewer) — browse and replay review sessions in browser - [Telemetry](https://open-codereview.ai/docs/telemetry) — OpenTelemetry integration for observability - [FAQ](https://open-codereview.ai/docs/faq) — common questions and troubleshooting ## Contributing This project exists thanks to all the people who contribute. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding guidelines, and how to submit pull requests. ## License [Apache-2.0](LICENSE) — Copyright 2026 Alibaba --- ## File: examples/gitlab_ci/README.md # OpenCodeReview - GitLab CI Demo This demo shows how to integrate OpenCodeReview into your GitLab CI/CD pipeline to automatically review Merge Requests and post review comments as inline discussions. ## How It Works ``` MR Created/Updated → GitLab Pipeline Triggered → OCR Reviews Diff → Discussions Posted on MR ``` 1. When a Merge Request is opened or updated, the pipeline triggers 2. It installs OCR via npm in a `node:20` Docker image 3. Runs `ocr review --from origin/ --to --format json --audience agent` to analyze the diff (uses commit SHA to support fork MRs) 4. Parses the JSON output and posts inline discussions on the MR using GitLab's Discussions API ## Setup ### 1. Copy the pipeline and script files Copy **both** `.gitlab-ci.yml` and `post_review.py` to your repository root (or a subdirectory — adjust the `python3 post_review.py` path in the YAML if you place the script elsewhere): ```bash cp .gitlab-ci.yml post_review.py /path/to/your/repo/ ``` Or use GitLab's `include` feature in your existing `.gitlab-ci.yml` (the script path is relative to the pipeline file's location): ```yaml include: - local: 'ci_demo/gitlab_ci/.gitlab-ci.yml' ``` ### 2. Configure CI/CD Variables Go to your project's **Settings → CI/CD → Variables** and add: | Variable | Required | Masked | Description | |----------|----------|--------|-------------| | `OCR_LLM_URL` | Yes | No | LLM API endpoint URL (e.g., `https://api.openai.com/v1/chat/completions`) | | `OCR_LLM_AUTH_TOKEN` | Yes | Yes | API authentication token | | `OCR_LLM_MODEL` | Yes | No | Model name (e.g., `gpt-4o`) — OCR has no built-in default model and fails when this is unset | | `GITLAB_API_TOKEN` | No | Yes | GitLab access token with `api` scope (falls back to `CI_JOB_TOKEN` if not set) | | `OCR_VERSION` | No | No | npm version spec for `@alibaba-group/open-code-review` (default: `latest`). Pin it (e.g. `1.8.8` or `~1.8`) for reproducible reviews. | | `OCR_LANGUAGE` | No | No | Review output language, written via `ocr config set language` (e.g. `English`, `Chinese`). Defaults to OCR's built-in default. | | `OCR_LLM_AUTH_HEADER` | No | No | Custom auth header name, written via `ocr config set llm.auth_header` (e.g. `x-api-key` for some providers). | | `OCR_LLM_EXTRA_HEADERS` | No | No | Extra headers `K=V,K=V`, written via `ocr config set llm.extra_headers`. | | `OCR_LLM_TIMEOUT` | No | No | LLM request timeout in seconds (read natively by OCR from the env). Unset/empty = OCR's default. | | `OCR_REVIEW_CONCURRENCY` | No | No | Max concurrent file reviews, passed via `ocr review --concurrency` (default: 8). | | `OCR_BACKGROUND` | No | No | Business/requirement context, passed via `ocr review --background` (e.g. the MR title). | | `OCR_RULE` | No | No | Path to a custom rules JSON file, passed via `ocr review --rule`. | > **Note:** GitLab CI/CD does not support variables with values shorter than 8 characters, so `use_anthropic` cannot be set as a CI variable. The pipeline sets it to `false` by default. If you need to use Anthropic Claude models, you'll need to modify the `.gitlab-ci.yml` script directly. > > The pipeline also configures `llm.extra_body` to disable thinking mode for compatibility with various LLM providers. ### 3. Create a GitLab Access Token You need a token with `api` scope to post discussions on MRs. Options: - **Project Access Token** (recommended): Settings → Access Tokens → Create with `api` scope - **Personal Access Token**: User Settings → Access Tokens → Create with `api` scope - **Group Access Token**: For organization-wide usage > **Note:** The built-in `CI_JOB_TOKEN` has limited API scope and may not support all discussion features (e.g., creating new threads on older GitLab versions). If `GITLAB_API_TOKEN` is not set, the pipeline falls back to `CI_JOB_TOKEN` automatically — but for best results, a dedicated token with `api` scope is recommended. > > **Tip:** For Project Access Tokens and Group Access Tokens, the token name determines the bot name shown in MR discussions. For example, naming your token `OpenCodeReview Bot` will make review comments appear as posted by `OpenCodeReview Bot`. ## Example Output When an MR is reviewed, comments appear as: - **Inline discussions**: Directly on the changed lines in the MR diff view, each prefixed with a `[category · severity]` badge when the LLM provided that metadata - **Summary note**: A single note (updated in place across runs by default) summarizing the total number of issues found, with mutually-exclusive counts (inline / summary / routed / skipped / failed) and a detailed warnings list - **Fallback notes**: Findings that could not be posted inline (no line info, routed by policy, or whose position could not be resolved against the diff) are collected into the summary note, each tagged with the reason it ended up there ### Inline Discussion Example Comments are posted using GitLab's Discussion API with position data, so they appear directly next to the relevant code in the "Changes" tab. Each comment carries an HTML-comment id tag (invisible when rendered) that the script uses to avoid duplicate posts on retry. ## Supported LLM Providers OCR supports both OpenAI and Anthropic API formats: - **OpenAI-compatible APIs** (default): - OpenAI (GPT-4o, GPT-4, etc.) - Azure OpenAI - Self-hosted models (vLLM, Ollama, etc.) - **Anthropic APIs** (modify `.gitlab-ci.yml` to set `use_anthropic: true`): - Anthropic Claude models ## Customization Most review behavior is configurable via CI/CD Variables (see the table above) — no YAML edits required. The recipes below cover the remaining cases. ### Use a specific OCR version Set the `OCR_VERSION` CI/CD variable (e.g. `1.8.8` or `~1.8`). Unset defaults to `latest`. ### Add custom review rules Set the `OCR_RULE` CI/CD variable to the path of a custom rules JSON file (passed to `ocr review --rule`). For rules that live inside the repo, commit the file and point `OCR_RULE` at its path. ### Adjust retry and delay settings When posting review discussions, the script includes rate-limit handling with exponential backoff (with jitter), `Retry-After` header support, and proactive throttling based on GitLab's `RateLimit-Remaining` response header. All API requests — including summary notes and MR version fetches — use the same retry logic. See [GitLab Rate Limits](https://docs.gitlab.com/security/rate_limits/) for details on GitLab's rate-limiting policies and recommended handling. You can configure the retry and delay behavior via **CI/CD Variables** (Settings → CI/CD → Variables): | Variable | Default | Description | |----------|---------|-------------| | `OCR_RETRY_BASE_DELAY` | `2000` | Base delay (ms) for exponential backoff when a rate-limit error is hit | | `OCR_MAX_RETRIES` | `3` | Maximum retry attempts per discussion when rate-limited | | `OCR_MAX_RETRY_DELAY` | `60000` | Maximum delay (ms) per single retry, caps both `Retry-After` and backoff | | `OCR_SUCCESS_DELAY` | `2000` | Delay (ms) after a successful discussion post to pace subsequent requests | | `OCR_FAILURE_DELAY` | `1000` | Delay (ms) after a non-rate-limit failure to pace subsequent requests | | `OCR_RATE_LIMIT_THRESHOLD` | `10` | Proactively slow down when GitLab `RateLimit-Remaining` is at/below this value (set `0` to disable). Applies to both writes (doubles the pacing delay) and reads (switches to the longer read spacing). | | `OCR_READ_SUCCESS_DELAY` | `500` | Delay (ms) after a successful read (`list_notes`/`list_discussions`/`get_mr_diffs`) to pace read API calls, mirroring the GitHub Action's `readWithPacing`. | | `OCR_READ_LOW_REMAINING_SPACING` | `5000` | Longer delay (ms) used after a read when the remaining quota is at/below `OCR_RATE_LIMIT_THRESHOLD`. | | `OCR_ROUTE_SEVERITY_BELOW` | _(empty)_ | Optional severity threshold (`critical`, `high`, `medium`, `low`) that routes findings at-or-below it from inline comments to summary notes (fail-open: never drops a finding). Empty or unknown values disable severity routing. | | `OCR_ROUTE_CATEGORIES` | _(empty)_ | Optional comma-separated categories (`bug`, `security`, `performance`, `maintainability`, `test`, `style`, `documentation`, `other`) routed from inline to summary notes. Unknown tokens are ignored. Combine with `OCR_ROUTE_SEVERITY_BELOW` to route on either condition. | These variables are optional — if not configured, sensible defaults are used. Consider increasing delays for self-hosted GitLab instances with aggressive rate-limit configurations or for large MRs that generate numerous review comments. The `OCR_RATE_LIMIT_THRESHOLD` variable enables proactive throttling: when GitLab reports low remaining quota in the `RateLimit-Remaining` response header, the script automatically doubles the pacing delay to avoid hitting 429 errors. When the primary rate limit is exhausted (`RateLimit-Remaining: 0`), the script additionally honors GitLab's `RateLimit-Reset` header, sleeping until the limit resets (defensively handling both epoch-seconds and seconds-until-reset formats). This mirrors the GitHub Action's `x-ratelimit-reset` handling. ### Publication behavior (aligned with the GitHub Action) The posting script implements the same publication behaviors as the GitHub Action (`scripts/github-actions/post-review-comments.js`), exposed as optional CI/CD variables. All default to no-op / current behavior except `OCR_STICKY_SUMMARY`, which defaults to `true` (the summary note is updated in place across runs instead of accumulating one note per run). | Variable | Default | Description | |----------|---------|-------------| | `OCR_STICKY_SUMMARY` | `true` | Update the summary note in place across runs (find-by-marker then `PUT /notes/:id`). Set `false` to post a fresh note each run. | | `OCR_INCREMENTAL` | `false` | Skip comments whose line range overlaps a prior bot discussion on the same path (so re-runs only append new findings). Uses an IoU threshold for multi-line spans. | | `OCR_INCREMENTAL_OVERLAP_THRESHOLD` | `0.6` | IoU (0–1) above which two multi-line comments are considered the same. Single-line comments match only on the exact same line; a single-line and multi-line comment never match. | | `OCR_ROUTE_SEVERITY_BELOW` | _(empty)_ | Route findings whose severity is at-or-below this level to the summary note instead of posting them inline (e.g. `low` keeps only critical/high/medium inline). Unknown severities never match (fail-open). | | `OCR_ROUTE_CATEGORIES` | _(empty)_ | Comma-separated categories to route to the summary (e.g. `style,documentation`). Routed findings never enter the inline write path, so they cannot be double-posted on retry. | | `OCR_FAIL_ON_SEVERITY` | _(empty)_ | Fail the CI job (non-zero exit) when any comment's severity is at-or-above this level (e.g. `critical`). The summary note is still posted before the job fails, so visibility is preserved. | Additional behaviors ported from the GitHub Action (always on, no variable): - **Category/severity badge**: each inline discussion and fallback entry is prefixed with `[category · severity]` (using a middot, U+00B7) when the LLM provided that metadata, byte-matching the CLI's badge rendering. - **Deterministic ordering**: comments are sorted by `path → start_line → end_line → original index` before posting, so identical reruns produce identical post sequences (which is what makes idempotency reconciliation reproducible). - **Detailed warnings**: warnings are rendered as a bulleted list (`file (type): message`) rather than a bare count. - **Backtick-safe fences**: fallback Before/After code blocks use a fence long enough to enclose any backticks in the code (the inline suggestion keeps the fixed triple-backtick `suggestion:-0+0` form so GitLab's "Apply suggestion" button keeps working). - **Idempotent retry**: each inline discussion carries an invisible HTML-comment id tag (``). When a `POST /discussions` fails with a 5xx/408/network error (the request may still have landed), the script queries existing discussions for the id before retrying; if found it is treated as success (no duplicate), and if the read API is unavailable it skips the retry rather than risk a duplicate. - **400 line-resolution fallback**: when a discussion `POST` returns 400 indicating a position problem, the script fetches the MR diff (`GET /merge_requests/:iid/diffs`), classifies the comment as valid/invalid/unknown, and drops provably-out-of-diff findings to the summary rather than blindly retrying. Unknown cases keep the existing fallback behavior. ### CI outputs and artifacts The pipeline exposes the following to downstream jobs: - **dotenv report** (`.ocr/ocr-stats.env`): `OCR_COMMENTS_TOTAL`, `OCR_COMMENTS_INLINE`, `OCR_COMMENTS_SUMMARY`, `OCR_COMMENTS_ROUTED`, `OCR_COMMENTS_SKIPPED`, `OCR_COMMENTS_FAILED`, and `OCR_SUMMARY_URL`. Consume them in later stages via the `dotenv` artifact. - **Artifacts** (`when: always`, 1 week retention): `.ocr/ocr-result.json` (raw review JSON) and `.ocr/ocr-stderr.log` (OCR stderr), so you can inspect a failed review even when the job fails. Paths are project-relative (under `.ocr/`) because GitLab Runner refuses to upload artifacts outside the build directory. ### Limit concurrency Set the `OCR_REVIEW_CONCURRENCY` CI/CD variable (passed to `ocr review --concurrency`). For large MRs, lowering this caps concurrent LLM requests: ```yaml variables: OCR_REVIEW_CONCURRENCY: "5" ``` ### Provide background context Set the `OCR_BACKGROUND` CI/CD variable (passed to `ocr review --background`). A common choice is the MR title: ```yaml variables: OCR_BACKGROUND: "$CI_MERGE_REQUEST_TITLE" ``` This is particularly useful when your MR titles follow semantic conventions (e.g., `feat(auth): add OAuth2 support`) that clearly summarize what the MR implements. The background information helps OCR provide more relevant and context-aware review comments. ### Change the trigger events By default, the pipeline uses `only: [merge_requests]`, which triggers on **all** MR events (creation, updates, reopen). GitLab CI does not natively support fine-grained control to trigger **only on MR creation**. To avoid re-reviewing on every push to an existing MR (and wasting LLM API tokens), you can check for existing OCR reviews **before** running `ocr review`. Use a wrapper script that skips the review step if OCR comments already exist: ``` /* Detailed source-code truncated for AI context efficiency. */ ``` The key logic: the Python wrapper checks for existing OCR comments before running `ocr review`. If found, it exits early with `sys.exit(0)` before consuming any LLM tokens. To re-trigger a review, users can manually delete the previous OCR comments. ### Self-hosted GitLab The script automatically uses `CI_SERVER_URL` to determine the GitLab API base URL, so it works with self-hosted GitLab instances out of the box. ### Use a Service Account as Review Bot By default, review comments are posted using the user who owns the access token configured in `GITLAB_API_TOKEN`. You can create a dedicated service account bot to post reviews with a custom identity, making it easier to distinguish automated reviews from human comments. For more details about GitLab service accounts, see the [GitLab Service Accounts documentation](https://docs.gitlab.com/ee/user/profile/service_accounts.html). #### Step 1: Create a Service Account Create a service account in your project: 1. Go to your **Project → Settings → Service Accounts** 2. Click **New service account** 3. Fill in the following: - **Name**: e.g., `OpenCodeReview Bot` (this will be the bot name shown in MR discussions) - **Username**: Will be auto-generated based on the name 4. Click **Create service account** #### Step 2: Invite the Service Account to Your Project After the service account is created, invite it to your project with appropriate permissions: 1. Go to your **Project → Settings → Members** 2. Click **Invite member** 3. Search for the service account by name (e.g., `OpenCodeReview Bot`) 4. Select the service account and assign a role (`Developer` or `Maintainer` required for posting discussions) 5. Click **Invite** #### Step 3: Create an Access Token Generate an access token for the service account: 1. Go to your **Project → Settings → Service Accounts** 2. Click on the service account to view its details 3. Click **Add new token** 4. Configure the token: - **Name**: e.g., `ocr-review-token` - **Expiration**: As needed - **Scope**: Select `api` (required for Discussions API) 5. Click **Create token** and copy the token value #### Step 4: Update CI/CD Variables Update the `GITLAB_API_TOKEN` variable in your project's CI/CD settings: Go to **Settings → CI/CD → Variables** and update `GITLAB_API_TOKEN` with the service account's token. Now review comments will be posted with your service account identity (e.g., `OpenCodeReview Bot`), providing a clear and professional appearance for automated code reviews. ## Troubleshooting ### Common Issues 1. **"API error 403"**: The `GITLAB_API_TOKEN` lacks `api` scope or doesn't have access to the project 2. **"Failed to parse OCR output"**: Check that `OCR_LLM_URL` and `OCR_LLM_AUTH_TOKEN` variables are correctly set 3. **"Cannot find merge-base"**: Ensure `GIT_DEPTH: 0` is set (full clone) 4. **Inline comments on wrong lines**: GitLab requires exact SHA matching; the script fetches MR version metadata to get correct diff refs ### Debugging Add verbose output to the review step: ```yaml script: - cat .ocr/ocr-result.json - cat .ocr/ocr-stderr.log ``` ## Testing The posting logic is unit-tested with no network access and no wall-clock sleep cost. Tests use only the standard-library `unittest` and cover: comment formatting (badge, suggestion, fallback), the publication policy (severity/category routing), deterministic sort, warning rendering, safe-fence code blocks, the full `publish()` flow (partition → sticky summary → fallback), incremental overlap (IoU, single-vs-multi, bot detection), the GitLab transport (retry/backoff/jitter/`Retry-After`/rate-limit/auth/network errors), idempotent `post_discussion` reconciliation, the 400 line-resolution fallback classification, wait-until-reset, and the dotenv stats / severity-gating helpers. ```bash # From the example directory cd examples/gitlab_ci python3 post_review_test.py # From the repo root python3 -m unittest discover -s examples/gitlab_ci -p '*_test.py' ``` --- ## File: examples/github_actions/README.md # OpenCodeReview - GitHub Actions Workflow This directory provides a ready-to-use GitHub Actions workflow demo that integrates OpenCodeReview into your repository to automatically review Pull Requests and post inline review comments. Copy it into `.github/workflows/` and configure the required secrets/vars. ## Quick Start: `ocr-review.yml` The simplest adoption path: this demo delegates every step — checkout, OCR install, review, comment posting, artifact upload — to the official reusable composite action at [`action.yml`](../../action.yml) via a single `uses: alibaba/open-code-review@main` step. It covers both automatic PR review (`pull_request_target: opened/synchronize/reopened`) and on-demand re-review via comments (`/open-code-review` or `@open-code-review`). No inline scripts to maintain — `@main` always runs the latest action; see [Reproducible pinning](#reproducible-pinning) when you need runs to be repeatable. ```bash mkdir -p .github/workflows cp ocr-review.yml .github/workflows/ocr-review.yml ``` The core of the demo is a single action step: ```yaml - uses: alibaba/open-code-review@main with: llm_url: ${{ secrets.OCR_LLM_URL }} llm_auth_token: ${{ secrets.OCR_LLM_AUTH_TOKEN }} llm_model: ${{ vars.OCR_LLM_MODEL }} llm_use_anthropic: ${{ vars.OCR_LLM_USE_ANTHROPIC }} ``` See [`action.yml`](../../action.yml) for the full list of inputs, outputs, security guidance, and the four comment-posting modes (sticky summary + incremental). ## Reproducible pinning The Action is an orchestrator: it installs the OCR CLI from npm at run time (`ocr_version`, default `latest`). Pinning only the Action reference therefore does **not** freeze review behavior — a new CLI release still changes what runs. For a fully reproducible setup, pin both: ```yaml - uses: alibaba/open-code-review@ # vX.Y.Z with: ocr_version: 'X.Y.Z' llm_url: ${{ secrets.OCR_LLM_URL }} llm_auth_token: ${{ secrets.OCR_LLM_AUTH_TOKEN }} llm_model: ${{ vars.OCR_LLM_MODEL }} llm_use_anthropic: ${{ vars.OCR_LLM_USE_ANTHROPIC }} ``` Take the commit SHA from the [releases page](https://github.com/alibaba/open-code-review/releases) and keep the `# vX.Y.Z` comment next to it so update tooling (Dependabot, Renovate) can track it. Every action referenced *inside* [`action.yml`](../../action.yml) is itself pinned to a full commit SHA (enforced by `scripts/verify-action-pins.sh` in CI), so the outer SHA transitively freezes the whole workflow — only the two coordinates above are yours to choose. ## Running on a self-hosted runner The demo above runs on GitHub-hosted runners (`runs-on: ubuntu-latest`) and pulls the action from `alibaba/open-code-review@main`. If you prefer to run OCR on your own self-hosted runner — to reach private network resources, keep LLM traffic on-prem, or avoid runner-minute costs — the OCR project itself does exactly this in its own CI. See [`.github/workflows/ocr-review.yml`](../../.github/workflows/ocr-review.yml) for that workflow. It runs on `runs-on: self-hosted` inside a `node:24` container. One important caveat: it invokes the action with `uses: ./` only because `action.yml` lives in that same repository — that is an internal shortcut and will not resolve in your repo. As an external user, keep `uses: alibaba/open-code-review@main` (the runner fetches the action automatically); only the runner environment needs to change. What is worth borrowing from it: - `runs-on: self-hosted`, optionally with a `container:` image such as `node:24` (the action needs Node.js; git is installed automatically if missing). - Marking the workspace as a trusted git `safe.directory` when running inside a container (e.g. `git config --global --replace-all safe.directory '*'`) to avoid "dubious ownership" errors. Use `--replace-all` (not `--add`) so repeated runs across multiple self-hosted actions replace rather than accumulate entries in the global git config. - Pinning action inputs explicitly (`sticky_summary`, `incremental`, `upload_artifacts`, `llm_extra_body`, etc.). The action performs its own full `fetch-depth: 0` checkout of the PR internally, so no extra checkout step is needed for the review diff. Adapt the runner settings to your environment and secret layout. ## How It Works ``` PR Created/Updated → GitHub Actions Triggered → OCR Reviews Diff → Comments Posted on PR OR Comment with trigger keyword ↗ ``` 1. When a PR is opened, the workflow triggers (uses `pull_request_target` for fork secret access). 2. Alternatively, when a comment containing `/open-code-review` or `@open-code-review` is posted on a PR, the workflow triggers. 3. The reusable action installs OCR, fetches the PR head blobs, computes `git merge-base`, and runs `ocr review --from --to --format json`. 4. It parses the JSON output and posts inline review comments on the PR via the Pull Request Review API, plus a summary comment (an issue comment on the PR). ## Setup ### Configure secrets and variables Go to your repository's **Settings → Secrets and variables → Actions**. **Secrets:** | Secret | Required | Description | |--------|----------|-------------| | `OCR_LLM_URL` | Yes | LLM API endpoint URL (e.g., `https://api.openai.com/v1/chat/completions`) | | `OCR_LLM_AUTH_TOKEN` | Yes | API authentication token (mapped to env `OCR_LLM_TOKEN` internally) | **Variables:** | Variable | Required | Description | |----------|----------|-------------| | `OCR_LLM_MODEL` | Yes | Model name | | `OCR_LLM_USE_ANTHROPIC` | Yes | `true` for Anthropic Claude, `false` for OpenAI-compatible | > **Note:** `GITHUB_TOKEN` is automatically provided by GitHub Actions with the required `pull-requests: write` permission. The action also sets `llm.extra_body` to disable thinking mode for compatibility with various LLM providers. ## Customization > These knobs are action inputs — they apply to the demo workflow and any workflow calling `alibaba/open-code-review@main`. See [`action.yml`](../../action.yml) for the full input list. Workflow-level settings (triggers, keywords) are edited in the workflow file itself. ### Change the trigger events Modify the `on.pull_request_target.types` array in the workflow file: ```yaml on: pull_request_target: types: [opened, synchronize, reopened, ready_for_review] ``` ### Customize comment trigger keywords By default the workflow also re-reviews on demand when a PR comment starts with `/open-code-review` or `@open-code-review`. The `if` condition is more defensive than a bare keyword check — it gates comment triggers so only authorized humans can spend LLM quota: ```yaml if: | github.event_name == 'pull_request_target' || ( github.event_name == 'issue_comment' && github.event.issue.pull_request && github.event.comment.user.type != 'Bot' && ( github.event.comment.author_association == 'MEMBER' || github.event.comment.author_association == 'OWNER' || github.event.comment.author_association == 'COLLABORATOR' ) && ( startsWith(github.event.comment.body, '/open-code-review') || startsWith(github.event.comment.body, '@open-code-review') ) ) ``` Each clause guards against a different abuse vector: - `github.event.issue.pull_request` — the comment must be on a PR, not a regular issue. - `github.event.comment.user.type != 'Bot'` — ignore bot comments. `GITHUB_TOKEN` already suppresses events from comments it posted, but a PAT or GitHub App token would not, so this is a safety net against self-triggering loops. - `author_association == 'MEMBER' | 'OWNER' | 'COLLABORATOR'` — only repository collaborators can trigger a (billable) re-review, preventing arbitrary commenters from draining LLM quota. - The `startsWith(...)` pair — the actual trigger keywords. To change the keywords, edit only that final pair (e.g. `/review` and `@mybot`), or swap `startsWith` for `contains` to match a substring anywhere in the comment body. Keep the preceding guards intact. The same predicate is mirrored in the workflow's `concurrency.group`: matching events share a per-PR group (`ocr-`) so a new review cancels any stale one, while non-matching comments land in a unique `noop-` group and are skipped instantly without disrupting a running review. If you change the keywords in `if`, mirror the change in `concurrency.group` too. ### Use a specific OCR version ```yaml - uses: alibaba/open-code-review@main with: ocr_version: 1.0.0 ``` ### Add custom review rules ```yaml - uses: alibaba/open-code-review@main with: rule: ./my-rules.json ``` > Security: do not point `rule` at a file sourced from the PR branch when secrets are in scope; use a trusted rules file from your base branch. ### Control comment posting (sticky summary & incremental) The action posts a summary issue comment plus inline review comments. Two inputs select the posting mode (combined, they give the four modes referenced above); a third tunes the incremental overlap test: | Input | Default | Description | |-------|---------|-------------| | `sticky_summary` | `'true'` | Update an existing summary comment in place instead of posting a new one each run. | | `incremental` | `'false'` | Only append inline comments whose `(path, line range)` does not overlap an existing bot review comment. History is never deleted (non-destructive). | | `incremental_overlap_threshold` | `'0.6'` | IoU threshold `incremental` uses to decide whether a multi-line comment overlaps an existing one. Two single-line comments match on the same line; single- vs multi-line never match. Ignored unless `incremental` is `'true'`. | ```yaml - uses: alibaba/open-code-review@main with: sticky_summary: 'true' incremental: 'true' incremental_overlap_threshold: '0.75' ``` > `sticky_summary` and `incremental` must be quoted strings (`'true'`/`'false'`); the action compares them as strings, so an unquoted YAML boolean will not match. ### Adjust retry and delay settings When posting review comments individually (fallback mode), the action honors GitHub rate-limit headers (`retry-after`, `x-ratelimit-*`) with exponential backoff. The retry strategy follows GitHub's documented guidance for REST API rate limits — see [Rate limits for the REST API](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api?apiVersion=2026-03-10) for details on primary/secondary rate limits and recommended retry behavior: - **Primary rate limit exhausted** (`x-ratelimit-remaining=0`): wait until `x-ratelimit-reset`. - **Secondary rate limit with a `retry-after` header**: wait exactly that long. - **Secondary rate limit with no header**: wait at least one minute, then use exponential backoff on continued failures. These are environment variables read by the posting module with sensible defaults; set them at the **job `env:` level** to tune (they propagate into the action): | Variable | Default | Description | |----------|---------|-------------| | `OCR_RETRY_BASE_DELAY` | `60000` | Base delay (ms) for exponential backoff when no retry header is present | | `OCR_RETRY_MAX_DELAY` | `300000` | Maximum delay (ms) cap applied to every computed wait | | `OCR_MAX_RETRIES` | `3` | Maximum retry attempts per comment when rate-limited | | `OCR_SUCCESS_DELAY` | `2000` | Delay (ms) after a successful comment post | | `OCR_FAILURE_DELAY` | `1000` | Delay (ms) after a non-retryable failure | | `OCR_LOW_REMAINING_THRESHOLD` | `3` | When x-ratelimit-remaining is at or below this value, proactively increase request spacing | | `OCR_LOW_REMAINING_SPACING` | `10000` | Request spacing (ms) used when remaining quota is low | | `OCR_READ_SUCCESS_DELAY` | `500` | Delay (ms) after a successful read API call (`listReviews` / `listReviewComments` / `listIssueComments`) used for the idempotency check. Reads are cheaper than writes, so the default is shorter | | `OCR_READ_LOW_REMAINING_SPACING` | `5000` | Request spacing (ms) for read calls when remaining quota is low | For example, to raise the per-comment retry count to 5, set `OCR_MAX_RETRIES` on the **job's** `env:` — not on the `uses:` step. A composite action does not forward the caller's step-level `env:` into its internal steps' process environment, so a step-level value would be silently ignored; the job-level value is inherited by the action's comment-posting step and read via `process.env`: ```yaml jobs: code-review: runs-on: ubuntu-latest env: OCR_MAX_RETRIES: 5 steps: - uses: alibaba/open-code-review@main with: llm_url: ${{ secrets.OCR_LLM_URL }} # ...other inputs ``` These variables are optional. See GitHub's [Rate limits for the REST API](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api). #### Idempotency: avoiding duplicate review comments When the batch `createReview` call fails with a `5xx` error, the request may still have landed on the GitHub server (the response was simply lost). Before retrying per-comment, the action queries existing reviews and review comments — each tagged with a per-run HTML comment (e.g. ``) — and only retries the comments that are actually missing. This prevents duplicate review posts. The summary comment is deduplicated too: in sticky mode (the default) the action finds the existing summary by its persistent marker and updates it in place rather than posting a new one; in non-sticky mode it reuses this run's summary if it already exists. If the read API is unavailable, it skips posting the summary rather than risking a duplicate. If the read API itself is unavailable (rate-limited or `5xx`), the check returns *unknown* rather than assuming the comment was not posted. In that case the action **skips retrying** to avoid risking a duplicate, and surfaces the uncertainty in the summary instead of silently producing duplicates. ### Limit LLM concurrency ```yaml - uses: alibaba/open-code-review@main with: review_concurrency: 5 ``` ### Provide background context ```yaml - uses: alibaba/open-code-review@main with: background: ${{ github.event.pull_request.title }} ``` Particularly useful when PR titles follow semantic conventions (e.g., `feat(auth): add OAuth2 support`). > Note: `github.event.pull_request.title` is only present on `pull_request_target` events, so it is empty for comment-triggered re-reviews. To cover both trigger types, have the pr-context step also output the title and fall back to it: > > ```yaml > # inside the pr-context script (which only runs for issue_comment): > core.setOutput('title', pullRequest.title); > ``` > ```yaml > - uses: alibaba/open-code-review@main > with: > background: ${{ steps.pr-context.outputs.title || github.event.pull_request.title }} > ``` ### Customize the review comment author with GitHub App By default, review comments are posted using the built-in `GITHUB_TOKEN`, which appears as `github-actions[bot]`. You can customize this by creating a GitHub App and using its credentials instead. For more details about GitHub Apps, see the [GitHub Apps documentation](https://docs.github.com/en/apps). #### Step 1: Create a GitHub App 1. Go to your organization or personal account **Settings → Developer settings → GitHub Apps → New GitHub App** 2. Fill in the following: - **GitHub App name**: e.g., `OpenCodeReview Bot` - **Homepage URL**: Your repository or documentation URL - **Webhook**: Uncheck "Active" (not needed for this use case) 3. Under **Repository permissions**, set: - **Pull requests**: Read and write - **Contents**: Read-only (for fetching diffs) - **Metadata**: Read-only (required) 4. Click **Create GitHub App** #### Step 2: Generate a Private Key 1. After creating the app, scroll down to **Private keys** 2. Click **Generate a private key** 3. Download and save the `.pem` file securely Note your App ID from the app settings page. #### Step 3: Install the App 1. In the left sidebar, click **Install App** 2. Select the repositories where you want to use OCR 3. After installation, note the **Installation ID** from the URL (e.g., `https://github.com/settings/installations/12345` → Installation ID is `12345`) #### Step 4: Configure Repository Secrets Add the following secrets to your repository (**Settings → Secrets and variables → Actions**): | Secret | Description | |--------|-------------| | `GITHUB_APP_ID` | Your GitHub App's ID | | `GITHUB_APP_PRIVATE_KEY` | Contents of the `.pem` file (including `-----BEGIN RSA PRIVATE KEY-----` and `-----END RSA PRIVATE KEY-----`) | | `GITHUB_APP_INSTALLATION_ID` | (Optional) The Installation ID from Step 3 — only needed for apps with multiple installations | #### Step 5: Pass the App token to the action Mint a token with `actions/create-github-app-token` and pass it via the `github_token` input: ```yaml - name: Get GitHub App Token id: app-token uses: actions/create-github-app-token@main with: app-id: ${{ secrets.GITHUB_APP_ID }} private-key: ${{ secrets.GITHUB_APP_PRIVATE_KEY }} - uses: alibaba/open-code-review@main with: github_token: ${{ steps.app-token.outputs.token }} llm_url: ${{ secrets.OCR_LLM_URL }} llm_auth_token: ${{ secrets.OCR_LLM_AUTH_TOKEN }} llm_model: ${{ vars.OCR_LLM_MODEL }} llm_use_anthropic: ${{ vars.OCR_LLM_USE_ANTHROPIC }} ``` Now review comments will be posted with your custom GitHub App identity (e.g., `OpenCodeReview Bot`), providing a more professional and distinguishable appearance in your PRs. ## Example Output The action posts two kinds of output on the PR: a **summary issue comment** (in the PR conversation) and **inline review comments** (in the "Files changed" tab). ### Summary comment A single comment — updated in place on each run when `sticky_summary` is `'true'` (the default) — carries the review outcome and posting statistics. - ✅ No issues: `✅ **OpenCodeReview**: No comments generated. Looks good to me.` - 🔍 Issues found: a header line plus per-outcome counts, for example: ```markdown 🔍 **OpenCodeReview** found **3** issue(s) in this PR. - ✅ Successfully posted inline: 2 comment(s) - 📝 In summary (no line info): 1 comment(s) ``` The counts are mutually exclusive and sum to the total: `inline` (landed as review inline comments), `summary` (no line info, rendered in the summary body), `skipped` (suppressed by incremental overlap filtering), and `failed` (had line info but could not be posted). Any warnings are appended as a bulleted list. ### Inline comments Comments with valid line info are posted as PR review comments in "Files changed". Each carries the review content plus, when a fix is available, a GitHub-native `suggestion` block so reviewers can apply it with one click: ````markdown **Suggestion:** ```suggestion // Fixed code here ``` ```` Comments that have no line info, or that could not be posted inline (e.g. their line fell outside the current diff), are rendered in the summary body instead — each under a `### 📄 ` heading, with a collapsible `` "💡 Suggested Change" (Before/After) when a fix is available. ## Supported LLM Providers OCR supports both OpenAI and Anthropic API formats: - **OpenAI-compatible APIs** (default): - OpenAI (GPT-4o, GPT-4, etc.) - Azure OpenAI - Self-hosted models (vLLM, Ollama, etc.) - **Anthropic APIs** (set variable `OCR_LLM_USE_ANTHROPIC=true`, i.e. `llm_use_anthropic: true`): - Anthropic Claude models ## Troubleshooting ### Common Issues 1. **Job fails / "Failed to parse OCR output"**: When `ocr review` exits non-zero the action fails the job with that exit code (the comment-posting step is skipped); a zero exit with malformed JSON surfaces as a parse error in the summary. In both cases, check that `OCR_LLM_URL` and `OCR_LLM_AUTH_TOKEN` are set correctly, then inspect the uploaded `ocr-stderr.log` artifact (also printed in the "Run OpenCodeReview" step log) for the underlying error. 2. **"Cannot find merge-base"**: The action fetches full history (`fetch-depth: 0`) and the PR head (`git fetch origin pull//head`); if this still fails, ensure `permissions: contents: read` is set and the base branch is accessible (e.g., not deleted). 3. **Review comments not on the expected lines**: Comments are attached to the PR head commit. If a comment's line falls outside the current diff (the PR was force-pushed or updated mid-review), GitHub rejects the inline post and the comment is rendered in the summary instead. The workflow's concurrency group cancels stale runs on new pushes. 4. **No summary or comments at all**: Confirm the job's `permissions` include `pull-requests: write`, and that `github_token` (defaults to `${{ github.token }}`) is not overridden with a token lacking those scopes. ### Debugging The action does not use an `OCR_DEBUG` flag. To diagnose a run: - **Artifacts**: with `upload_artifacts: 'true'` (the default), the raw `ocr-result.json` and `ocr-stderr.log` are uploaded as workflow artifacts named `ocr-review-result--`. Download them from the run's **Artifacts** section. - **Step log**: the "Run OpenCodeReview" step prints both the JSON result and stderr to the workflow log. - **Action outputs**: the step exposes `comments_total`, `comments_inline`, `comments_skipped`, `comments_failed`, and `summary_comment_url` outputs — inspect them in the job's step outputs. - **GitHub step debug**: for verbose Actions runner diagnostics, enable the repository secret `ACTIONS_STEP_DEBUG=true` (standard GitHub Actions mechanism). To stop uploading the raw artifacts, set `upload_artifacts: 'false'`. --- ## File: examples/README.md # 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 - **[bitbucket_pipelines/](./bitbucket_pipelines/)** - Bitbucket Pipelines integration example - **[gitflic_ci/](./gitflic_ci/)** - GitFlic CI integration example - **[gerrit_ci/](./gerrit_ci/)** - Gerrit (Jenkins / Gerrit Trigger) integration example Each subdirectory contains its own README with detailed setup instructions. --- ## File: extensions/vscode/README.md # Open Code Review (VS Code Extension) A VS Code code-review extension built on the [`open-code-review`](https://www.npmjs.com/package/@alibaba-group/open-code-review) (`ocr`) CLI. It recreates the prototype experience with a Preact WebView and brings AI code review into the editor: start reviews from the sidebar, stream logs live, and apply / dismiss / flag-as-false-positive each comment inline — kept in sync with the sidebar both ways. --- ## Features - **Three review modes**: workspace changes, branch comparison (`--from` / `--to`), and a single commit (`--commit`). - **Files-to-review preview**: lists changed files from the current Git state; click a file to view its changes in the native diff view. - **Custom review prompt**: optionally append a `--background` hint for the current review. - **Streaming logs**: tail the CLI output live during review, cancel anytime. - **Results + two-way sync**: on completion, comment cards appear in the sidebar while CommentThreads render in the editor; apply / dismiss / false-positive actions stay in sync on both sides. - **Empty / cancelled / failed states**: dedicated views for no issues, user cancellation, and CLI failure (failures are retryable and surface the real error returned by the CLI). - **Configuration management**: view / edit the LLM provider config inside the extension (persisted via `ocr config set`). - **Model switching / connectivity test**: switch models and test connectivity to the LLM from the status bar. --- ## Prerequisites 1. Install the `ocr` CLI globally: ```bash npm i @alibaba-group/open-code-review ``` 2. Configure a working LLM (endpoint, API key, model). Configure it via the CLI directly, or in the extension's config view: ```bash ocr config set llm.url https://api.anthropic.com/v1/messages ocr config set llm.auth_token sk-... ocr config set llm.model claude-opus-4-6 ocr config set llm.use_anthropic true ``` The config is written to `~/.opencodereview/config.json`. --- ## Development ### Environment - Node.js ≥ 18, with **Yarn** as the package manager (the repo ships a `yarn.lock`). - VS Code ≥ 1.74. - A globally available `ocr` CLI (see "Prerequisites" above) — the extension is essentially a GUI front-end for `ocr`. ### Start the dev environment ```bash cd extensions/vscode yarn install # install dependencies yarn watch # watch-mode dev build (recommended: rebuilds out/ on change) ``` Then open the `extensions/vscode` folder in VS Code and press **F5** to launch the Extension Development Host (debug config is provided in `.vscode/launch.json`). In the new window, open a project with Git changes — you'll see the Open Code Review icon in the activity bar and can start a review. > After editing code: WebView changes require **reopening the sidebar** in the dev host window > (or running `Developer: Reload Webviews`); Extension Host changes require **restarting the > debug session** (the ⟳ button on the debug toolbar, or `Cmd+R` in the host window). ### Scripts ```bash yarn compile # one-off dev build (webpack development) yarn watch # watch-mode dev build yarn build # production build (webpack production; runs automatically before packaging) yarn test # run Jest unit tests yarn lint # ESLint yarn package # produce a distributable .vsix package (see "Build a release package") ``` ### Debugging notes - **Two-way messaging**: the WebView and Extension Host communicate via `postMessage`; message types live in `src/shared/messages.ts`. Both sides route through `dispatch` / `handle` — start there when debugging. - **CLI invocation**: all `ocr` sub-commands run via `child_process.spawn` in `src/extension/services/CliService.ts`. `runRaw` rejects on a non-zero CLI exit code and includes the `Error:` text from stderr, which helps diagnose "review failed / connection failed". - **Config read/write**: `ConfigService` reads `~/.opencodereview/config.json` and delegates writes to `ocr config set`. WebView fields are camelCase (e.g. `useAnthropic`) while the disk/CLI side is snake_case (e.g. `use_anthropic`); the conversion lives in `src/extension/services/configParse.ts`. --- ## Build ### Compile artifacts only ```bash yarn build # production build (webpack production) ``` Artifacts: `out/extension.js` (Extension Host) + `out/webview.js` (WebView SPA). ### Build a release package (.vsix) ```bash yarn package # = vsce package --no-yarn ``` This command: 1. Triggers `vscode:prepublish` → runs the `yarn build` production build; 2. Excludes source, tests, and dev files per `.vscodeignore`; 3. Produces `open-code-review-vscode-.vsix` in the current directory. > The packaging tool is `@vscode/vsce`, installed as a devDependency — no global install or network > download needed. `--no-yarn` skips vsce's default npm dependency-tree check (this project uses Yarn). The release package contains only the runtime essentials: `package.json`, `README.md`, `resources/icon.svg`, `out/extension.js`, `out/webview.js`. ### Install / verify locally ```bash code --install-extension open-code-review-vscode-.vsix ``` Or in VS Code: Extensions panel → top-right `⋯` → **Install from VSIX…** → pick the generated `.vsix` file. > To publish to the Marketplace, use `vsce publish` instead (requires a publisher account and PAT); > for everyday distribution the `.vsix` above is enough. --- ## Architecture It uses a **Monolithic WebView + Thin Extension Host** design: - The **WebView** is a separately built Preact SPA that reproduces the full visual and interactive prototype. - The **Extension Host** layer is thin, handling only CLI invocation, the file system, Git operations, and editor comments. - The two communicate via `postMessage`, with shared TypeScript types in `src/shared/` for type safety. ``` src/ ├── extension/ Extension Host (Node.js): services / providers / commands ├── webview/ WebView SPA (Preact): views / components / store / bridge └── shared/ shared types and the postMessage protocol (no vscode dependency) ``` --- ## License Apache-2.0 --- ## File: extensions/vscode/README.zh-CN.md # Open Code Review (VSCode 插件) 基于 [`open-code-review`](https://www.npmjs.com/package/@alibaba-group/open-code-review) (`ocr`) CLI 的 VSCode 代码审查插件。以 Preact WebView 还原原型交互体验，把 AI 代码审查能力集成进编辑器：在侧边栏发起审查、流式查看日志、在编辑器内逐条应用/忽略/标记误报评论，并与侧边栏双向同步。 --- ## 功能 - **三种审查模式**：工作区变更、分支对比（`--from` / `--to`）、单次提交（`--commit`）。 - **待审查文件预览**：基于当前 Git 状态展示变更文件列表，点击文件可在原生 diff 视图中查看改动。 - **自定义审查提示词**：可选地为本次审查追加 `--background` 提示。 - **流式日志**：审查过程中实时滚动 CLI 输出，支持随时取消。 - **结果展示 + 双向同步**：完成后在侧边栏列出评论卡片，同时在编辑器内渲染 CommentThread；应用/忽略/误报操作在两侧同步。 - **空 / 取消 / 失败态**：无问题、用户取消、CLI 失败均有对应视图（失败可重试，并展示 CLI 返回的真实错误）。 - **配置管理**：在插件内查看/编辑 LLM 提供商配置（写入通过 `ocr config set`）。 - **模型切换 / 连通性测试**：状态栏切换模型、测试与 LLM 的连通性。 --- ## 前置依赖 1. 全局安装 `ocr` CLI： ```bash npm i @alibaba-group/open-code-review ``` 2. 配置可用的 LLM（接口地址、API Key、模型）。可用 CLI 直接配置，或在插件内的配置视图填写： ```bash ocr config set llm.url https://api.anthropic.com/v1/messages ocr config set llm.auth_token sk-... ocr config set llm.model claude-opus-4-6 ocr config set llm.use_anthropic true ``` 配置写入 `~/.opencodereview/config.json`。 --- ## 开发 ### 环境准备 - Node.js ≥ 18，包管理器使用 **Yarn**（仓库自带 `yarn.lock`）。 - VS Code ≥ 1.74。 - 全局可用的 `ocr` CLI（见上文「前置依赖」），插件本质上是 `ocr` 的图形前端。 ### 启动开发环境 ```bash cd extensions/vscode yarn install # 安装依赖 yarn watch # 监听式开发构建（推荐：改代码自动重新打包 out/） ``` 然后在 VS Code 中打开 `extensions/vscode` 目录，按 **F5** 启动 Extension Development Host （调试配置已在 `.vscode/launch.json` 提供）。在弹出的新窗口里打开一个有 Git 变更的项目， 即可在活动栏看到 Open Code Review 图标并发起审查。 > 改了代码后：WebView 改动需在开发宿主窗口里 **重新打开侧边栏**（或执行命令 `Developer: Reload Webviews`）； > Extension Host 改动需 **重启调试**（调试工具栏的 ⟳ 或在宿主窗口按 `Cmd+R`）。 ### 常用脚本 ```bash yarn compile # 单次开发构建（webpack development） yarn watch # 监听式开发构建 yarn build # 生产构建（webpack production，打包前自动执行） yarn test # 运行 Jest 单测 yarn lint # ESLint 检查 yarn package # 生成可分发的 .vsix 安装包（见下文「构建发布包」） ``` ### 调试要点 - **双端通信**：WebView 与 Extension Host 通过 `postMessage` 通信，消息类型定义在 `src/shared/messages.ts`。两端发收都走 `dispatch` / `handle`，定位问题先看这里。 - **CLI 调用**：所有 `ocr` 子命令由 `src/extension/services/CliService.ts` 通过 `child_process.spawn` 执行。 `runRaw` 会在 CLI 退出码非 0 时 reject 并带上 stderr 中的 `Error:` 文本，便于排查“审查失败/连接失败”。 - **配置读写**：`ConfigService` 读取 `~/.opencodereview/config.json`，写入则委托 `ocr config set`。 WebView 端字段为 camelCase（如 `useAnthropic`），磁盘/CLI 端为 snake_case（如 `use_anthropic`）， 转换在 `src/extension/services/configParse.ts`。 --- ## 构建 ### 仅编译产物 ```bash yarn build # 生产构建（webpack production） ``` 产物：`out/extension.js`（Extension Host）+ `out/webview.js`（WebView SPA）。 ### 构建发布包（.vsix） ```bash yarn package # = vsce package --no-yarn ``` 该命令会： 1. 自动触发 `vscode:prepublish` → 执行 `yarn build` 生产构建； 2. 按 `.vscodeignore` 排除源码、测试、开发文件； 3. 在当前目录生成 `open-code-review-vscode-.vsix`。 > 打包工具为 `@vscode/vsce`，已作为 devDependency 安装，无需全局安装或联网下载。 > `--no-yarn` 用于跳过 vsce 默认的 npm 依赖树校验（本项目用 Yarn）。 发布包只包含运行必需文件：`package.json`、`README.md`、`resources/icon.svg`、`out/extension.js`、`out/webview.js`。 ### 本地安装 / 验证 ```bash code --install-extension open-code-review-vscode-.vsix ``` 或在 VS Code 中：扩展面板 → 右上角 `⋯` → **Install from VSIX…** → 选择生成的 `.vsix` 文件。 > 发布到 Marketplace 时改用 `vsce publish`（需要 publisher 账号与 PAT），日常分发用上面的 `.vsix` 即可。 --- ## 架构 采用 **Monolithic WebView + Thin Extension Host** 方案： - **WebView** 是独立构建的 Preact SPA，还原原型的全部视觉与交互。 - **Extension Host** 层轻薄，只负责 CLI 调用、文件系统、Git 操作、编辑器评论。 - 两者通过 `postMessage` 通信，用 `src/shared/` 中的 TypeScript 共享类型保证类型安全。 ``` src/ ├── extension/ Extension Host（Node.js）：services / providers / commands ├── webview/ WebView SPA（Preact）：views / components / store / bridge └── shared/ 双端共享类型与 postMessage 协议（不依赖 vscode） ``` --- ## License Apache-2.0 --- ## File: README.ja-JP.md --- ## Open Code Reviewとは？ Open Code ReviewはAIを活用したコードレビューCLIツールです。もともとはAlibaba Group社内の公式AIコードレビューアシスタントとして誕生し、過去2年間で数万人の開発者にサービスを提供し、数百万件のコード欠陥を発見してきました。大規模な環境で徹底的に検証された後、コミュニティ向けのオープンソースプロジェクトとして公開されました。モデルのエンドポイントを設定するだけで使い始められます。 Gitのdiffを読み取り、変更されたファイルをツール利用機能を持つエージェント経由で設定可能なLLMに送信し、行レベルの精度で構造化されたレビューコメントを生成します。エージェントはファイル全体の内容を読み取り、コードベースを検索し、コンテキストのために他の変更ファイルを参照し、深いレビューを生成できます — 単なる表面的なdiffへのフィードバックではありません。diffレビュー以外にも、`ocr scan` はファイル全体をレビューできます。不慣れなコードベースの監査や、意味のあるdiffがないディレクトリの検査に便利です。 詳細は[公式サイト](https://open-codereview.ai)をご覧ください。 ## ベンチマーク > 汎用エージェント（Claude Code）と比較して、Open Code Reviewは同じ基盤モデルで有意に高い**精度（Precision）**と**F1スコア**を達成し、トークン消費量は**約1/9**にとどまり、レビューもより高速です。ただし、リコール（Recall）は汎用エージェントより低くなります——これはノイズを抑え精度を優先する設計上のトレードオフです。 実際のコードレビューに基づくベンチマーク。**50**の人気オープンソースリポジトリから**200**の実際のPull Requestを厳選し、**10**のプログラミング言語をカバー——80人以上のシニアエンジニアによるクロスバリデーション（**1,505**件のアノテーション済み欠陥）。 [ Hugging FaceでAACR-Benchデータセットを見る](https://huggingface.co/datasets/Alibaba-Aone/aacr-bench)。 | 指標 | 測定内容 | 重要性 | |------|----------|--------| | **F1** | 精度とリコールの調和平均 | レビュー品質を示す最良の単一指標 | | **精度 (Precision)** | 報告された問題のうち実際の欠陥の割合 | 高い = 確認すべき偽陽性が少ない | | **リコール (Recall)** | 実際の欠陥のうち発見された割合 | 高い = 見逃しが少ない | | **平均時間 (Avg Time)** | レビューあたりの実時間 | CIパイプラインの待機時間に影響 | | **平均トークン (Avg Token)** | レビューあたりの総トークン消費量 | APIコストに直接影響 | ## なぜOpen Code Reviewなのか？ ### 汎用エージェントの問題点 Claude CodeのSkillsのような汎用エージェントをコードレビューに使ったことがあれば、次のような課題に直面したことがあるはずです： - **不完全なカバレッジ** — 大きな変更セットでは、エージェントが「手を抜き」、一部のファイルだけを選択的にレビューして他を見落としがちです。 - **位置のずれ** — 報告された問題が実際のコード位置と一致せず、行番号やファイル参照がターゲットからずれることが頻繁にあります。 - **不安定な品質** — 自然言語駆動のSkillsはデバッグが難しく、わずかなプロンプトの違いでレビュー品質が大きく変動します。 根本原因は、純粋に言語駆動のアーキテクチャにはレビュープロセスに対するハードな制約が欠けていることです。 ### コア設計: 決定論的エンジニアリング × エージェントのハイブリッド Open Code Reviewのコア哲学は、決定論的エンジニアリングとエージェントを組み合わせ、それぞれが得意とする領域を担当させることです。 **決定論的エンジニアリング — ハードな制約** *絶対に間違えてはならない*レビューステップについては、言語モデルではなくエンジニアリングロジックが正しさを保証します： - **正確なファイル選択** — どのファイルをレビューし、どのファイルをフィルタリングすべきかを正確に決定し、重要な変更が見落とされないようにします。 - **スマートなファイルバンドル** — 関連するファイルを単一のレビューユニットにグループ化します（例：`message_en.properties`と`message_zh.properties`はまとめてバンドルされます）。各バンドルは分離されたコンテキストを持つサブエージェントとして実行されます — 非常に大きな変更セットでも安定する分割統治戦略で、自然に並行レビューもサポートします。 - **きめ細かなルールマッチング** — 各ファイルの特性に応じてレビュールールをマッチングし、モデルの注意を鋭く集中させ、情報ノイズを発生源から排除します。純粋に言語駆動のルール誘導と比べて、テンプレートエンジンベースのルールマッチングはより安定的で予測可能です。 - **外部の位置特定・リフレクションモジュール** — 独立したコメント位置特定モジュールとコメントリフレクションモジュールにより、AIフィードバックの位置精度と内容精度の両方を体系的に向上させます。 **エージェント — 動的な意思決定** エージェントの強みは、最も重要な領域 — 動的な意思決定と動的なコンテキスト取得 — に集中させています： - **シナリオに最適化されたプロンプト** — コードレビュー向けに深く最適化されたプロンプトテンプレートにより、効果を高めつつトークン消費を削減します。 - **シナリオに最適化されたツールセット** — 大規模な本番データにおけるツール呼び出しトレースの詳細な分析 — 呼び出し頻度の分布、ツールごとの繰り返し率、新しいツールが呼び出しチェーン全体に与える影響など — から抽出された、汎用エージェントツールキットよりもコードレビューにおいて安定的で予測可能な専用ツールセットです。 ## 使い方 ### 前提条件 - **Git >= 2.41** — Open Code Review は diff 生成、コード検索、リポジトリ操作に Git を利用します。 ### CLI #### インストール ```bash npm install @alibaba-group/open-code-review ``` インストール後、`ocr`コマンドがグローバルに利用可能になります。 その他のインストール方法（インストールスクリプト、GitHub Release バイナリ、ソースビルド）については、[インストールガイド](https://open-codereview.ai/docs/installation)を参照してください。 #### クイックスタート **1. LLMの設定** コードレビューの前にLLMの設定が必要です。[デリゲートモード](https://open-codereview.ai/docs/delegate)を使用する場合は不要です。 ```bash ocr config provider # ビルトインプロバイダーを選択またはカスタムプロバイダーを追加 ocr config model # アクティブなプロバイダーのモデルを選択 ``` 対話的UIがプロバイダーの選択、APIキーの入力、モデル設定をガイドし、完了後に自動的に接続テストを行います。 CLIセットアップ、環境変数、カスタムプロバイダーなどの高度な設定については、[設定ガイド](https://open-codereview.ai/docs/configuration)を参照してください。 **2. レビュー** ```bash cd your-project # ワークスペースモード — ステージ済み・未ステージ・未追跡のすべての変更をレビュー ocr review # ブランチ範囲 — main から分岐した後の feature-branch の変更をレビュー（マージベースモード） ocr review --from main --to feature-branch # 単一コミット ocr review --commit abc123 # 中断した範囲または単一 commit レビューを再開 ocr session list ocr review --from main --to feature-branch --resume # フルファイルスキャン — diffではなくファイル全体をレビュー（git履歴不要） ocr scan # リポジトリ全体をスキャン ocr scan --path internal/agent # ディレクトリまたは特定のファイルをスキャン ocr scan --resume # 中断したフルファイルスキャンを再開 # デリゲートモード — AI コーディングエージェントが自らレビューを実行 # OCR はファイル選択とルール解決を担当。LLM 設定不要 ocr delegate preview ocr delegate rule src/main.go src/handler.go ``` ## ドキュメント 完全なドキュメントは **[open-codereview.ai/docs](https://open-codereview.ai/docs)** にあります： - [クイックスタート](https://open-codereview.ai/docs/quickstart) — インストールして最初のレビューを実行 - [インストール](https://open-codereview.ai/docs/installation) — すべてのプラットフォームとパッケージマネージャー - [CLI リファレンス](https://open-codereview.ai/docs/cli-reference) — すべてのコマンドとフラグ - [レビュールール](https://open-codereview.ai/docs/review-rules) — レビュールールのカスタマイズ、パスフィルタリングとターゲティング - [設定](https://open-codereview.ai/docs/configuration) — 設定キーと環境変数 - [MCP サーバー](https://open-codereview.ai/docs/mcp) — 外部ツールでレビューエージェントを拡張 - コーディングエージェント連携 — 使用するプラットフォームを選択 - [Claude Code](plugins/open-code-review/README.md#claude-code) — レビュー用スラッシュコマンドを含むプラグインをインストール - [Codex](plugins/open-code-review/README.md#codex) — 呼び出し可能なレビュースキルを含むプラグインをインストール - [Cursor](plugins/open-code-review/README.md#cursor) — 移植可能なレビュースキルを含むプラグインをインストール - [OpenCode](plugins/open-code-review/opencode/README.md) — ネイティブレビュー・ツールとスラッシュコマンドをインストール - [QCA Forward](plugins/open-code-review/qca/README.md) — QCA ホストモデルと公開可能なテンプレートで委任モードを実行 - [Skill 対応エージェント](https://open-codereview.ai/docs/agent-skill) — 移植可能なエージェントスキルをインストール - レビュー実行モード — 連携後、どの LLM がレビューを実行するかを選択 - [デフォルト（OCR が管理）](https://open-codereview.ai/docs/configuration) — OCR が設定済みの LLM を使用してレビューを実行 - [デリゲートモード](https://open-codereview.ai/docs/delegate) — コーディングエージェントが自身の LLM を使用してレビューを実行。OCR の API キーは不要 - [CI/CD 連携](https://open-codereview.ai/docs/cicd) — GitHub Actions、GitLab CI、GitFlic CI、Gerrit との統合 - [セッションビューアー](https://open-codereview.ai/docs/viewer) — ブラウザでレビューセッションを閲覧・再生 - [テレメトリー](https://open-codereview.ai/docs/telemetry) — 可観測性のためのOpenTelemetry統合 - [FAQ](https://open-codereview.ai/docs/faq) — よくある質問とトラブルシューティング ## コントリビューション このプロジェクトは、貢献してくださるすべての方々のおかげで成り立っています。開発環境のセットアップ、コーディングガイドライン、プルリクエストの提出方法については[CONTRIBUTING.ja-JP.md](CONTRIBUTING.ja-JP.md)を参照してください。 ## ライセンス [Apache-2.0](LICENSE) — Copyright 2026 Alibaba --- ## File: README.ko-KR.md --- ## Open Code Review란? Open Code Review는 AI 기반 코드 리뷰 CLI 도구입니다. Alibaba Group의 내부 공식 AI 코드 리뷰 어시스턴트에서 시작했으며, 지난 2년 동안 수만 명의 개발자에게 제공되어 수백만 건의 코드 결함을 찾아냈습니다. 대규모 환경에서 충분히 검증한 뒤 커뮤니티를 위해 오픈 소스 프로젝트로 공개했습니다. 모델 endpoint만 설정하면 바로 사용할 수 있습니다. 이 도구는 Git diff를 읽고, 변경 파일을 tool-use 기능을 가진 agent를 통해 설정 가능한 LLM으로 전달한 뒤, 라인 단위 위치 정보가 포함된 구조화된 리뷰 코멘트를 생성합니다. agent는 전체 파일 내용 읽기, 코드베이스 검색, 다른 변경 파일 확인 등을 통해 맥락을 확보하고 표면적인 diff 피드백이 아닌 깊이 있는 리뷰를 수행할 수 있습니다. diff 리뷰 외에도 `ocr scan`은 전체 파일을 리뷰할 수 있어, 익숙하지 않은 코드베이스를 감사하거나 의미 있는 diff가 없는 디렉터리를 검토하는 데 유용합니다. 자세한 내용은 [공식 웹사이트](https://open-codereview.ai)를 참조하세요. ## 벤치마크 > 범용 Agent(Claude Code)와 비교할 때, Open Code Review는 동일한 기반 모델에서 유의미하게 높은 **정밀도(Precision)**와 **F1 점수**를 달성하며, 토큰 소비량은 **약 1/9** 수준이고 리뷰 속도도 더 빠릅니다. 다만 재현율(Recall)은 범용 Agent보다 낮습니다 — 이는 노이즈를 줄이고 정밀도를 우선하는 설계적 트레이드오프입니다. 실제 코드 리뷰 기반 벤치마크. **50**개 인기 오픈소스 저장소에서 **200**개 실제 Pull Request를 엄선하고, **10**개 프로그래밍 언어를 커버 — 80명 이상의 시니어 엔지니어가 교차 검증(**1,505**개 어노테이션된 결함). [ Hugging Face에서 AACR-Bench 데이터셋 살펴보기](https://huggingface.co/datasets/Alibaba-Aone/aacr-bench). | 지표 | 측정 내용 | 중요한 이유 | |------|-----------|-------------| | **F1** | 정밀도와 재현율의 조화 평균 | 리뷰 품질을 나타내는 최적의 단일 지표 | | **정밀도 (Precision)** | 보고된 이슈 중 실제 결함 비율 | 높을수록 확인할 오탐이 적음 | | **재현율 (Recall)** | 실제 결함 중 발견된 비율 | 높을수록 놓치는 이슈가 적음 | | **평균 시간 (Avg Time)** | 리뷰당 실제 소요 시간 | CI 파이프라인 대기 시간에 영향 | | **평균 토큰 (Avg Token)** | 리뷰당 총 토큰 소비량 | API 비용에 직접 영향 | ## 왜 Open Code Review인가? ### 범용 Agent의 문제 Claude Code Skills 같은 범용 agent로 코드 리뷰를 해봤다면 다음 문제를 경험했을 수 있습니다. - **불완전한 커버리지**: 큰 changeset에서는 일부 파일만 선택적으로 리뷰하고 중요한 파일을 놓치기 쉽습니다. - **위치 드리프트**: 지적된 문제가 실제 코드 위치와 맞지 않거나 라인 번호와 파일 참조가 어긋나는 일이 자주 발생합니다. - **불안정한 품질**: 자연어 기반 Skill은 디버깅이 어렵고, 작은 prompt 변화에도 리뷰 품질이 크게 흔들릴 수 있습니다. 근본 원인은 순수 언어 중심 아키텍처가 리뷰 프로세스에 강한 제약을 제공하지 못한다는 점입니다. ### 핵심 설계: 결정적 엔지니어링과 Agent의 하이브리드 Open Code Review의 핵심 철학은 결정적 엔지니어링과 agent를 결합해 각자가 가장 잘하는 일을 맡기는 것입니다. **결정적 엔지니어링: 강한 제약** 반드시 정확해야 하는 리뷰 단계는 언어 모델이 아니라 엔지니어링 로직이 보장합니다. - **정확한 파일 선택**: 어떤 파일을 리뷰하고 어떤 파일을 필터링할지 결정해 중요한 변경이 누락되지 않도록 합니다. - **스마트 파일 번들링**: 관련 파일을 하나의 리뷰 단위로 묶습니다. 예를 들어 `message_en.properties`와 `message_zh.properties`를 함께 묶습니다. 각 번들은 독립된 context를 가진 sub-agent로 실행되며, 대규모 changeset에서도 안정적인 divide-and-conquer 전략과 동시 리뷰를 지원합니다. - **세밀한 rule 매칭**: 각 파일의 특성에 맞는 리뷰 rule을 매칭해 모델의 주의를 집중시키고 정보 노이즈를 줄입니다. 순수 자연어 기반 rule 안내보다 template engine 기반 rule 매칭이 더 안정적이고 예측 가능합니다. - **외부 위치 지정 및 reflection 모듈**: 독립적인 comment positioning과 comment reflection 모듈이 AI 피드백의 위치 정확도와 내용 정확도를 체계적으로 개선합니다. **Agent: 동적 의사결정** agent의 강점은 동적 판단과 동적 context 검색이 중요한 지점에 집중됩니다. - **시나리오 최적화 prompt**: 코드 리뷰에 깊이 최적화된 prompt template으로 효과를 높이고 token 사용량을 줄입니다. - **시나리오 최적화 toolset**: 대규모 production 데이터의 tool-call trace를 분석해 도출했습니다. 호출 빈도 분포, tool별 반복률, 신규 tool이 전체 call chain에 미치는 영향 등을 반영해 범용 agent toolkit보다 코드 리뷰에 더 안정적이고 예측 가능한 전용 toolset을 제공합니다. ## 사용 방법 ### 사전 요구 사항 - **Git >= 2.41** — Open Code Review는 diff 생성, 코드 검색, 저장소 작업에 Git을 사용합니다. ### CLI #### 설치 ```bash npm install @alibaba-group/open-code-review ``` 설치 후 `ocr` 명령을 전역에서 사용할 수 있습니다. 기타 설치 방법(설치 스크립트, GitHub Release binary, 소스 빌드)은 [설치 가이드](https://open-codereview.ai/docs/installation)를 참조하세요. #### Quick Start **1. LLM 설정** 코드 리뷰 전에 LLM 설정이 필요합니다. [위임 모드](https://open-codereview.ai/docs/delegate)를 사용하는 경우에는 불필요합니다. ```bash ocr config provider # built-in provider 선택 또는 custom provider 추가 ocr config model # 활성 provider의 model 선택 ``` 대화형 UI가 provider 선택, API key 입력, model 설정을 안내하며, 완료 후 자동으로 연결 테스트를 수행합니다. CLI 설정, 환경 변수, 커스텀 provider 등 고급 설정은 [설정 가이드](https://open-codereview.ai/docs/configuration)를 참조하세요. **2. 리뷰 실행** ```bash cd your-project # Workspace mode: staged, unstaged, untracked 변경을 모두 리뷰 ocr review # 브랜치 범위 — main에서 분기된 이후 feature-branch의 변경 사항을 리뷰합니다 (머지베이스 모드) ocr review --from main --to feature-branch # 단일 commit ocr review --commit abc123 # 중단된 range 또는 단일 commit review 재개 ocr session list ocr review --from main --to feature-branch --resume # 전체 파일 스캔 — diff 대신 파일 전체를 리뷰 (git 이력 불필요) ocr scan # 전체 repository 스캔 ocr scan --path internal/agent # 디렉터리 또는 특정 파일 스캔 ocr scan --resume # 중단된 전체 파일 스캔 재개 # 위임 모드 — AI 코딩 에이전트가 직접 리뷰 수행 # OCR은 파일 선택과 규칙 해석만 담당; LLM 설정 불필요 ocr delegate preview ocr delegate rule src/main.go src/handler.go ``` ## Documentation 전체 문서는 **[open-codereview.ai/docs](https://open-codereview.ai/docs)** 에서 확인할 수 있습니다: - [빠른 시작](https://open-codereview.ai/docs/quickstart) — 설치하고 첫 리뷰 실행하기 - [설치](https://open-codereview.ai/docs/installation) — 모든 플랫폼 및 패키지 매니저 - [CLI 레퍼런스](https://open-codereview.ai/docs/cli-reference) — 모든 명령어와 플래그 - [리뷰 규칙](https://open-codereview.ai/docs/review-rules) — 리뷰 규칙 커스터마이징, 경로 필터링 및 타겟팅 - [설정](https://open-codereview.ai/docs/configuration) — 설정 키와 환경 변수 - [MCP 서버](https://open-codereview.ai/docs/mcp) — 외부 도구로 리뷰 에이전트 확장 - 코딩 에이전트 연동 — 사용하는 플랫폼 선택 - [Claude Code](plugins/open-code-review/README.md#claude-code) — 리뷰 슬래시 명령이 포함된 플러그인 설치 - [Codex](plugins/open-code-review/README.md#codex) — 호출 가능한 리뷰 스킬이 포함된 플러그인 설치 - [Cursor](plugins/open-code-review/README.md#cursor) — 이식 가능한 리뷰 스킬이 포함된 플러그인 설치 - [OpenCode](plugins/open-code-review/opencode/README.md) — 네이티브 리뷰 도구와 슬래시 명령 설치 - [QCA Forward](plugins/open-code-review/qca/README.md) — QCA 호스트 모델과 게시 가능한 템플릿으로 위임 모드 실행 - [Skill 호환 에이전트](https://open-codereview.ai/docs/agent-skill) — 이식 가능한 에이전트 스킬 설치 - 리뷰 실행 모드 — 연동 후 리뷰를 수행할 LLM 선택 - [기본 모드(OCR 관리)](https://open-codereview.ai/docs/configuration) — OCR이 설정된 LLM을 사용해 리뷰 수행 - [위임 모드](https://open-codereview.ai/docs/delegate) — 코딩 에이전트가 자체 LLM을 사용해 리뷰 수행; OCR API 키 불필요 - [CI/CD 연동](https://open-codereview.ai/docs/cicd) — GitHub Actions, GitLab CI, GitFlic CI, Gerrit 통합 - [세션 뷰어](https://open-codereview.ai/docs/viewer) — 브라우저에서 리뷰 세션 탐색 및 재생 - [텔레메트리](https://open-codereview.ai/docs/telemetry) — 관측성을 위한 OpenTelemetry 통합 - [FAQ](https://open-codereview.ai/docs/faq) — 자주 묻는 질문과 문제 해결 ## Contributing 이 프로젝트는 기여해 주신 모든 분들 덕분에 존재합니다. 개발 환경 설정, coding guideline, pull request 제출 방법은 [CONTRIBUTING.ko-KR.md](CONTRIBUTING.ko-KR.md)를 참고하세요. ## License [Apache-2.0](LICENSE) Copyright 2026 Alibaba --- ## File: README.ru-RU.md --- ## Что такое Open Code Review? Open Code Review — это CLI-инструмент для код-ревью на основе ИИ. Он появился как внутренний официальный ИИ-ассистент код-ревью Alibaba Group: за последние два года им воспользовались десятки тысяч разработчиков, и он выявил миллионы дефектов в коде. После тщательной проверки в огромных масштабах мы превратили его в open-source-проект для сообщества. Чтобы начать работу, достаточно настроить эндпоинт модели. Инструмент читает git-диффы, отправляет изменённые файлы настраиваемой LLM через агента с поддержкой вызова инструментов (tool use) и генерирует структурированные ревью-комментарии с точностью до строки. Агент может читать полное содержимое файлов, искать по кодовой базе, заглядывать в другие изменённые файлы за контекстом и выполнять глубокое ревью — а не только давать поверхностные замечания по диффу. Помимо ревью диффов, `ocr scan` позволяет проверять файлы целиком — удобно для аудита незнакомой кодовой базы или каталогов без значимого диффа. Подробнее на [официальном сайте](https://open-codereview.ai). ## Бенчмарк > По сравнению с агентами общего назначения (Claude Code), Open Code Review при той же базовой модели достигает значительно более высоких показателей **Precision** и **F1**, потребляя лишь **~1/9 токенов** и выполняя ревью быстрее. При этом показатель Recall ниже, чем у агентов общего назначения — это осознанный компромисс в пользу точности и минимального шума. Бенчмарк собран на основе реальных код-ревью и включает **50** популярных open-source-репозиториев, **200** реальных пул-реквестов и **10** языков программирования. Разметку из **1 505** дефектов перекрёстно проверили более 80 ведущих инженеров. [ Открыть датасет AACR-Bench на Hugging Face](https://huggingface.co/datasets/Alibaba-Aone/aacr-bench). | Метрика | Что измеряет | Почему важна | |---------|-------------|--------------| | **F1** | Гармоническое среднее precision и recall | Лучший единый показатель качества ревью | | **Precision** | Доля найденных проблем, являющихся реальными дефектами | Выше = меньше ложных срабатываний | | **Recall** | Доля реальных дефектов, которые были найдены | Выше = меньше пропущенных проблем | | **Avg Time** | Время выполнения одного ревью | Влияет на задержки в CI-пайплайне | | **Avg Token** | Суммарное потребление токенов за ревью | Прямо влияет на стоимость API | ## Почему Open Code Review? ### Проблема агентов общего назначения Если вы использовали для код-ревью агентов общего назначения, например Claude Code со Skills, вы наверняка сталкивались с такими проблемами: - **Неполное покрытие** — на крупных ченджсетах агенты склонны «срезать углы»: выборочно проверяют часть файлов и пропускают остальные. - **Дрейф позиций** — найденные проблемы часто не совпадают с реальным местом в коде: номера строк и ссылки на файлы «уезжают» от цели. - **Нестабильное качество** — Skills, управляемые естественным языком, трудно отлаживать, и качество ревью заметно колеблется при небольших изменениях промпта. Первопричина: чисто языковая архитектура не накладывает жёстких ограничений на процесс ревью. ### Ключевая идея: детерминированная инженерия × агент Ключевая философия Open Code Review — сочетать детерминированную инженерию и агента так, чтобы каждый занимался тем, что у него получается лучше всего. **Детерминированная инженерия — жёсткие гарантии** Для тех шагов ревью, где *нельзя ошибаться*, корректность гарантирует инженерная логика, а не языковая модель: - **Точный отбор файлов** — точно определяет, какие файлы нуждаются в ревью, а какие следует отфильтровать, гарантируя, что ни одно важное изменение не будет упущено. - **Группировка связанных файлов** — объединяет связанные файлы в одну единицу ревью (например, `message_en.properties` и `message_zh.properties`). Каждая группа обрабатывается отдельным субагентом в изолированном контексте. Подход «разделяй и властвуй» сохраняет стабильность при очень больших изменениях и позволяет выполнять ревью параллельно. - **Точное сопоставление правил** — подбирает правила ревью с учётом особенностей каждого файла, удерживая внимание модели на задаче и устраняя лишний информационный шум. Сопоставление по шаблонам работает стабильнее и предсказуемее, чем управление правилами только на естественном языке. - **Внешние модули позиционирования и рефлексии** — независимые модули позиционирования комментариев и рефлексии над комментариями системно повышают точность как расположения, так и содержания замечаний ИИ. **Агент — динамические решения** Сильные стороны агента сосредоточены там, где они важнее всего, — в динамических решениях и динамическом доборе контекста: - **Промпты, заточенные под сценарий** — шаблоны промптов, глубоко оптимизированные под код-ревью: выше качество при меньшем расходе токенов. - **Специализированный набор инструментов** — создан на основе анализа вызовов инструментов в реальных проектах: частоты вызовов, доли повторных обращений к каждому инструменту и влияния новых инструментов на всю цепочку. Такой набор работает при код-ревью стабильнее и предсказуемее, чем универсальные инструменты агента. ## Как использовать ### Предварительные требования - **Git >= 2.41** — Open Code Review использует Git для генерации diff, поиска по коду и операций с репозиторием. ### CLI #### Установка ```bash npm install @alibaba-group/open-code-review ``` После установки команда `ocr` доступна глобально. Другие способы установки (скрипт установки, бинарный файл из GitHub Release, сборка из исходников) описаны в [руководстве по установке](https://open-codereview.ai/docs/installation). #### Быстрый старт **1. Настройте LLM** Перед запуском ревью необходимо настроить LLM, если только вы не используете [режим делегирования](https://open-codereview.ai/docs/delegate). ```bash ocr config provider # Выбрать встроенного провайдера или добавить пользовательский ocr config model # Выбрать модель для активного провайдера ``` Интерактивный UI проведёт вас через выбор провайдера, ввод API-ключа и настройку модели, после чего автоматически проверит подключение. Настройка через CLI, переменные окружения, пользовательские провайдеры и другие расширенные параметры описаны в [руководстве по конфигурации](https://open-codereview.ai/docs/configuration). **2. Запустите ревью** ```bash cd your-project # Режим рабочей копии — ревью всех staged, unstaged и untracked изменений ocr review # Диапазон веток — просматривает изменения feature-branch с момента её отделения от main (режим merge-base) ocr review --from main --to feature-branch # Один коммит ocr review --commit abc123 # Возобновить прерванное ревью диапазона или одного коммита ocr session list ocr review --from main --to feature-branch --resume # Полнофайловое сканирование — ревью целых файлов вместо диффа (история git не нужна) ocr scan # сканировать весь репозиторий ocr scan --path internal/agent # сканировать каталог или конкретные файлы ocr scan --resume # возобновить прерванное полнофайловое сканирование # Режим делегирования — ИИ-агент сам выполняет ревью # OCR отвечает за выбор файлов и разрешение правил; настройка LLM не требуется ocr delegate preview ocr delegate rule src/main.go src/handler.go ``` ## Документация Полная документация доступна на **[open-codereview.ai/docs](https://open-codereview.ai/docs)**: - [Быстрый старт](https://open-codereview.ai/docs/quickstart) — установка и запуск первого ревью - [Установка](https://open-codereview.ai/docs/installation) — все платформы и менеджеры пакетов - [Справочник CLI](https://open-codereview.ai/docs/cli-reference) — все команды и флаги - [Правила ревью](https://open-codereview.ai/docs/review-rules) — кастомизация правил ревью, фильтрация и таргетинг по путям - [Конфигурация](https://open-codereview.ai/docs/configuration) — ключи конфигурации и переменные окружения - [MCP-сервер](https://open-codereview.ai/docs/mcp) — расширение агента ревью внешними инструментами - Интеграции с кодинг-агентами — выберите используемую платформу - [Claude Code](plugins/open-code-review/README.md#claude-code) — установка плагина со slash-командами для ревью - [Codex](plugins/open-code-review/README.md#codex) — установка плагина с вызываемыми навыками ревью - [Cursor](plugins/open-code-review/README.md#cursor) — установка плагина с переносимыми навыками ревью - [OpenCode](plugins/open-code-review/opencode/README.md) — установка нативных инструментов ревью и slash-команд - [QCA Forward](plugins/open-code-review/qca/README.md) — запуск режима делегирования с хост-моделью QCA и готовым к публикации шаблоном - [Агенты с поддержкой Skill](https://open-codereview.ai/docs/agent-skill) — установка переносимого навыка агента - Режимы выполнения ревью — после интеграции выберите, какая LLM выполняет ревью - [По умолчанию (под управлением OCR)](https://open-codereview.ai/docs/configuration) — OCR выполняет ревью с помощью настроенной LLM - [Режим делегирования](https://open-codereview.ai/docs/delegate) — кодинг-агент выполняет ревью с помощью собственной LLM; API-ключ для OCR не требуется - [Интеграция с CI/CD](https://open-codereview.ai/docs/cicd) — GitHub Actions, GitLab CI, GitFlic CI и Gerrit - [Просмотр сессий](https://open-codereview.ai/docs/viewer) — просмотр и воспроизведение сессий ревью в браузере - [Телеметрия](https://open-codereview.ai/docs/telemetry) — интеграция с OpenTelemetry для наблюдаемости - [FAQ](https://open-codereview.ai/docs/faq) — частые вопросы и устранение неполадок ## Участие в разработке Этот проект существует благодаря всем, кто вносит свой вклад. В [CONTRIBUTING.ru-RU.md](CONTRIBUTING.ru-RU.md) описаны настройка окружения разработки, рекомендации по коду и порядок отправки пул-реквестов. ## Лицензия [Apache-2.0](LICENSE) — Copyright 2026 Alibaba --- ## File: README.zh-CN.md --- ## Open Code Review 是什么？ Open Code Review 是一款 AI 驱动的代码审查 CLI 工具。它的前身是阿里集团内部官方 AI 代码审查助手，过去两年在内部服务了数万开发者，识别了数百万个代码缺陷。经过大规模充分验证后，我们将其孵化为开源项目，对社区开放。只需配置一个模型端点即可使用。 它读取 Git diff，通过具备工具调用能力的 Agent 将变更文件发送至可配置的 LLM，生成具有行级精度的结构化审查意见。Agent 可以读取完整文件内容、搜索代码库、检查其他变更文件以获取上下文，从而进行深度审查——而非仅停留在表面的 diff 反馈。除了 diff 审查，`ocr scan` 可以审查整个文件，适用于审计不熟悉的代码库或没有有意义 diff 的目录。 访问[官方网站](https://open-codereview.ai)了解更多信息。 ## 基准测试 > 相比通用 Agent（Claude Code），Open Code Review 在相同底层模型下取得了显著更高的 **准确率（Precision）** 与 **F1 综合得分**，同时仅消耗 **约 1/9 的 token**、审查更快。但召回率（Recall）低于通用 Agent——这是以精准度换取低噪声的设计取舍。 基于真实场景的代码审查基准测试，从 **50** 个热门开源仓库中精选 **200** 个真实的 Pull Request，覆盖 **10** 种编程语言——由 80+ 位资深工程师交叉标注验证（共 **1,505** 个标注缺陷）。 [ 在 Hugging Face 上探索 AACR-Bench 数据集](https://huggingface.co/datasets/Alibaba-Aone/aacr-bench)。 | 指标 | 含义 | 为什么重要 | |------|------|-----------| | **F1** | 准确率与召回率的调和均值 | 综合衡量审查质量的最佳单一指标 | | **准确率 (Precision)** | 报告的问题中真正有效的比例 | 越高 = 误报越少，减少人工确认成本 | | **召回率 (Recall)** | 真实缺陷中被发现的比例 | 越高 = 漏报越少，更多问题不会遗漏 | | **平均耗时 (Avg Time)** | 每次审查的实际耗时 | 决定 CI 流水线的等待时间 | | **平均 Token (Avg Token)** | 每次审查消耗的总 token 数 | 直接影响 API 使用成本 | ## 为什么选择 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 工具集进行取舍与拆分，最终沉淀出一套在代码审查场景下效果更稳定、行为更可预期的专属工具集。 ## 如何使用 ### 前置条件 - **Git >= 2.41** — Open Code Review 依赖 Git 进行 diff 生成、代码搜索和仓库操作。 ### CLI #### 安装 ```bash npm install @alibaba-group/open-code-review ``` 安装后，`ocr` 命令即可全局使用。 其他安装方式（安装脚本、GitHub Release 二进制、源码构建），详见[安装指南](https://open-codereview.ai/docs/installation)。 #### 快速开始 **1. 配置 LLM** 在审查代码之前，必须先配置 LLM。除非你使用[委托模式](https://open-codereview.ai/docs/delegate)。 ```bash ocr config provider # 选择内置供应商或添加自定义供应商 ocr config model # 为当前供应商选择模型 ``` 交互式界面会引导你完成供应商选择、API Key 输入和模型配置，完成后自动测试连通性。 命令行设置、环境变量、自定义供应商等高级配置，详见[配置指南](https://open-codereview.ai/docs/configuration)。 **2. 开始审查** ```bash cd your-project # 工作区模式 —— 审查所有暂存、未暂存和未跟踪的变更 ocr review # 分支范围 —— 评审 feature-branch 自与 main 分叉以来的变更（合并基准模式） ocr review --from main --to feature-branch # 单个提交 ocr review --commit abc123 # 恢复中断的区间或单 commit 评审 ocr session list ocr review --from main --to feature-branch --resume # 全量文件扫描 —— 审查整个文件而非 diff（无需 git 历史） ocr scan # 扫描整个仓库 ocr scan --path internal/agent # 扫描指定目录或文件 ocr scan --resume # 恢复中断的全量文件扫描 # 委托模式 — 让你的 AI 编程 agent 自己执行评审 # OCR 负责文件选择和规则解析；无需配置 LLM ocr delegate preview ocr delegate rule src/main.go src/handler.go ``` ## 文档 完整文档见 **[open-codereview.ai/docs](https://open-codereview.ai/docs)**： - [快速开始](https://open-codereview.ai/docs/quickstart) —— 安装并运行你的第一次评审 - [安装](https://open-codereview.ai/docs/installation) —— 覆盖各平台与包管理器 - [CLI 参考](https://open-codereview.ai/docs/cli-reference) —— 所有命令与参数 - [评审规则](https://open-codereview.ai/docs/review-rules) —— 深度定制规则进行评审，过滤路径、指定路径等 - [配置](https://open-codereview.ai/docs/configuration) —— 配置项与环境变量 - [MCP 服务器](https://open-codereview.ai/docs/mcp) —— 用外部工具扩展评审 agent - 编程 Agent 集成 —— 选择你使用的平台 - [Claude Code](plugins/open-code-review/README.md#claude-code) —— 安装包含评审斜杠命令的插件 - [Codex](plugins/open-code-review/README.md#codex) —— 安装包含可调用评审 Skill 的插件 - [Cursor](plugins/open-code-review/README.md#cursor) —— 安装包含可移植评审 Skill 的插件 - [OpenCode](plugins/open-code-review/opencode/README.md) —— 安装原生评审工具和斜杠命令 - [QCA Forward](plugins/open-code-review/qca/README.md) —— 使用 QCA 宿主模型运行委托模式，并提供可发布的模板 - [兼容 Skill 的 Agent](https://open-codereview.ai/docs/agent-skill) —— 安装可移植的 Agent Skill - 评审执行模式 —— 完成集成后，选择由哪个 LLM 执行评审 - [默认模式（OCR 驱动）](https://open-codereview.ai/docs/configuration) —— OCR 使用其已配置的 LLM 执行评审 - [委托模式](https://open-codereview.ai/docs/delegate) —— 编程 Agent 使用自身的 LLM 执行评审；无需 OCR API Key - [CI/CD 集成](https://open-codereview.ai/docs/cicd) —— 支持 GitHub Actions、GitLab CI、GitFlic CI、Gerrit 集成 - [会话查看器](https://open-codereview.ai/docs/viewer) —— 在浏览器中浏览和回放评审会话 - [遥测](https://open-codereview.ai/docs/telemetry) —— OpenTelemetry 集成，用于可观测性 - [FAQ](https://open-codereview.ai/docs/faq) —— 常见问题与故障排查 ## 贡献 感谢所有为本项目做出贡献的人。参见 [CONTRIBUTING.zh-CN.md](CONTRIBUTING.zh-CN.md) 了解开发环境搭建、编码规范以及如何提交 Pull Request。 ## 许可证 [Apache-2.0](LICENSE) — Copyright 2026 Alibaba