open-code-review Documentation

File: README.md Copy Chapter

What is Open Code Review? Copy Chapter

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 for more details.

Benchmark Copy Chapter

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.

Why Open Code Review? Copy Chapter

The Problem with General-Purpose Agents Copy Section

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 Copy Section

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 Copy Chapter

Prerequisites Copy Section

• Git >= 2.41 — Open Code Review relies on Git for diff generation, code search, and repository operations.

CLI Copy Section

Install

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.

Quick Start

1. Configure LLM

You must configure an LLM before reviewing code, unless you use Delegation Mode.

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.

2. Review

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 <session-id>

# 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 <session-id>   # 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 Copy Chapter

Full documentation lives at open-codereview.ai/docs:

• Quickstart — install and run your first review
• Installation — all platforms and package managers
• CLI Reference — every command and flag
• Review Rules — customize review rules with path filtering and targeting
• Configuration — config keys and environment variables
• MCP Server — extend the review agent with external tools
• Coding Agent Integrations — choose the platform you use
  • Claude Code — install a plugin with review slash commands
  • Codex — install a plugin with callable review skills
  • Cursor — install a plugin with portable review skills
  • OpenCode — install native review tools and slash commands
  • QCA Forward — run delegation mode with the QCA host model and a ready-to-publish template
  • Skill-compatible agents — install the portable agent skill
• Review Execution Modes — after integration, choose which LLM performs the review
  • Default (OCR-managed) — OCR runs the review using its configured LLM
  • Delegation Mode — your coding agent runs the review using its own LLM; no OCR API key required
• CI/CD Integration — GitHub Actions, GitLab CI, GitFlic CI, and Gerrit integration
• Session Viewer — browse and replay review sessions in browser
• Telemetry — OpenTelemetry integration for observability
• FAQ — common questions and troubleshooting

Contributing Copy Chapter

This project exists thanks to all the people who contribute. See CONTRIBUTING.md for development setup, coding guidelines, and how to submit pull requests.

License Copy Chapter

Apache-2.0 — Copyright 2026 Alibaba

File: examples/gitlab_ci/README.md Copy Chapter

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 Copy Chapter

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/<target> --to <commit_sha> --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 Copy Chapter

1. Copy the pipeline and script files Copy Section

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):

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):

include:
  - local: 'ci_demo/gitlab_ci/.gitlab-ci.yml'

2. Configure CI/CD Variables Copy Section

Go to your project's Settings → CI/CD → Variables and add:

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 Copy Section

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 Copy Chapter

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 Copy Section

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 Copy Chapter

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 Copy Chapter

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 Copy Section

Set the OCR_VERSION CI/CD variable (e.g. 1.8.8 or ~1.8). Unset defaults to latest.

Add custom review rules Copy Section

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 Copy Section

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 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):

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) Copy Section

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).

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 Copy Section

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 Copy Section

Set the OCR_REVIEW_CONCURRENCY CI/CD variable (passed to ocr review --concurrency). For large MRs, lowering this caps concurrent LLM requests:

variables:
  OCR_REVIEW_CONCURRENCY: "5"

Provide background context Copy Section

Set the OCR_BACKGROUND CI/CD variable (passed to ocr review --background). A common choice is the MR title:

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 Copy Section

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 Copy Section

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 Copy Section

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.

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 Copy Chapter

Common Issues Copy Section

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 Copy Section

Add verbose output to the review step:

script:
  - cat .ocr/ocr-result.json
  - cat .ocr/ocr-stderr.log

Testing Copy Chapter

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.

# 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 Copy Chapter

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` Copy Chapter

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 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 when you need runs to be repeatable.

mkdir -p .github/workflows
cp ocr-review.yml .github/workflows/ocr-review.yml

The core of the demo is a single action step:

- 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 for the full list of inputs, outputs, security guidance, and the four comment-posting modes (sticky summary + incremental).

Reproducible pinning Copy Chapter

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:

- uses: alibaba/open-code-review@<full-commit-sha> # 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 and keep the # vX.Y.Z comment next to it so update tooling (Dependabot, Renovate) can track it. Every action referenced inside 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 Copy Chapter

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 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 Copy Chapter

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 <merge-base> --to <head> --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 Copy Chapter

Configure secrets and variables Copy Section

Go to your repository's Settings → Secrets and variables → Actions.

Secrets:

Variables:

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 Copy Chapter

These knobs are action inputs — they apply to the demo workflow and any workflow calling alibaba/open-code-review@main.

See action.yml for the full input list. Workflow-level settings (triggers, keywords) are edited in the workflow file itself.

Change the trigger events Copy Section

Modify the on.pull_request_target.types array in the workflow file:

on:
  pull_request_target:
    types: [opened, synchronize, reopened, ready_for_review]

Customize comment trigger keywords Copy Section

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:

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-<run_id> 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 Copy Section

- uses: alibaba/open-code-review@main
  with:
    ocr_version: 1.0.0

Add custom review rules Copy Section

- 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) Copy Section

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:

- 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 Copy Section

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 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):

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:

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.

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 Copy Section

- uses: alibaba/open-code-review@main
  with:
    review_concurrency: 5

Provide background context Copy Section

- 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 Copy

# inside the pr-context script (which only runs for issue_comment):
core.setOutput('title', pullRequest.title);

yaml Copy

- 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 Copy Section

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.

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):

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:

- 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 Copy Chapter

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 Copy Section

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:

🔍 **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 Copy Section

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:

**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 Copy Chapter

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 Copy Chapter

Common Issues Copy Section

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/<n>/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 Copy Section

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-<run_id>-<run_attempt>. 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 Copy Chapter

CI/CD Integration Examples

This directory contains examples for integrating OpenCodeReview (OCR) into various CI/CD pipelines.

Contents Copy Chapter

• github_actions/ - GitHub Actions integration example
• gitlab_ci/ - GitLab CI integration example
• bitbucket_pipelines/ - Bitbucket Pipelines integration example
• gitflic_ci/ - GitFlic CI integration example
• gerrit_ci/ - Gerrit (Jenkins / Gerrit Trigger) integration example

Each subdirectory contains its own README with detailed setup instructions.

File: extensions/vscode/README.md Copy Chapter

Open Code Review (VS Code Extension)

A VS Code code-review extension built on the 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 Copy Chapter

• 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 Copy Chapter

1. Install the ocr CLI globally:

   bash Copy

   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 Copy

   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 Copy Chapter

Environment Copy Section

• 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 Copy Section

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 Copy Section

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 Copy Section

• 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 Copy Chapter

Compile artifacts only Copy Section

yarn build        # production build (webpack production)

Artifacts: out/extension.js (Extension Host) + out/webview.js (WebView SPA).

Build a release package (.vsix) Copy Section

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-<version>.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 Copy Section

code --install-extension open-code-review-vscode-<version>.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 Copy Chapter

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 Copy Chapter

Apache-2.0

File: extensions/vscode/README.zh-CN.md Copy Chapter

Open Code Review (VSCode 插件)

基于 open-code-review (ocr) CLI 的 VSCode 代码审查插件。以 Preact WebView 还原原型交互体验，把 AI 代码审查能力集成进编辑器：在侧边栏发起审查、流式查看日志、在编辑器内逐条应用/忽略/标记误报评论，并与侧边栏双向同步。

功能 Copy Chapter

• 三种审查模式：工作区变更、分支对比（--from / --to）、单次提交（--commit）。
• 待审查文件预览：基于当前 Git 状态展示变更文件列表，点击文件可在原生 diff 视图中查看改动。
• 自定义审查提示词：可选地为本次审查追加 --background 提示。
• 流式日志：审查过程中实时滚动 CLI 输出，支持随时取消。
• 结果展示 + 双向同步：完成后在侧边栏列出评论卡片，同时在编辑器内渲染 CommentThread；应用/忽略/误报操作在两侧同步。
• 空 / 取消 / 失败态：无问题、用户取消、CLI 失败均有对应视图（失败可重试，并展示 CLI 返回的真实错误）。
• 配置管理：在插件内查看/编辑 LLM 提供商配置（写入通过 ocr config set）。
• 模型切换 / 连通性测试：状态栏切换模型、测试与 LLM 的连通性。

前置依赖 Copy Chapter

1. 全局安装 ocr CLI：

   bash Copy

   npm i @alibaba-group/open-code-review

2. 配置可用的 LLM（接口地址、API Key、模型）。可用 CLI 直接配置，或在插件内的配置视图填写：

   bash Copy

   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。

开发 Copy Chapter

环境准备 Copy Section

• Node.js ≥ 18，包管理器使用 Yarn（仓库自带 yarn.lock）。
• VS Code ≥ 1.74。
• 全局可用的 ocr CLI（见上文「前置依赖」），插件本质上是 ocr 的图形前端。

启动开发环境 Copy Section

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）。

常用脚本 Copy Section

yarn compile      # 单次开发构建（webpack development）
yarn watch        # 监听式开发构建
yarn build        # 生产构建（webpack production，打包前自动执行）
yarn test         # 运行 Jest 单测
yarn lint         # ESLint 检查
yarn package      # 生成可分发的 .vsix 安装包（见下文「构建发布包」）

调试要点 Copy Section

• 双端通信：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。

构建 Copy Chapter

仅编译产物 Copy Section

yarn build        # 生产构建（webpack production）

产物：out/extension.js（Extension Host）+ out/webview.js（WebView SPA）。

构建发布包（.vsix） Copy Section

yarn package      # = vsce package --no-yarn

该命令会：

1. 自动触发 vscode:prepublish → 执行 yarn build 生产构建；
2. 按 .vscodeignore 排除源码、测试、开发文件；
3. 在当前目录生成 open-code-review-vscode-<version>.vsix。

打包工具为 @vscode/vsce，已作为 devDependency 安装，无需全局安装或联网下载。
--no-yarn 用于跳过 vsce 默认的 npm 依赖树校验（本项目用 Yarn）。

发布包只包含运行必需文件：package.json、README.md、resources/icon.svg、out/extension.js、out/webview.js。

本地安装 / 验证 Copy Section

code --install-extension open-code-review-vscode-<version>.vsix

或在 VS Code 中：扩展面板 → 右上角 ⋯ → Install from VSIX… → 选择生成的 .vsix 文件。

发布到 Marketplace 时改用 vsce publish（需要 publisher 账号与 PAT），日常分发用上面的 .vsix 即可。

架构 Copy Chapter

采用 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 Copy Chapter

Apache-2.0

File: README.ja-JP.md Copy Chapter

Open Code Reviewとは？ Copy Chapter

Open Code ReviewはAIを活用したコードレビューCLIツールです。もともとはAlibaba Group社内の公式AIコードレビューアシスタントとして誕生し、過去2年間で数万人の開発者にサービスを提供し、数百万件のコード欠陥を発見してきました。大規模な環境で徹底的に検証された後、コミュニティ向けのオープンソースプロジェクトとして公開されました。モデルのエンドポイントを設定するだけで使い始められます。

Gitのdiffを読み取り、変更されたファイルをツール利用機能を持つエージェント経由で設定可能なLLMに送信し、行レベルの精度で構造化されたレビューコメントを生成します。エージェントはファイル全体の内容を読み取り、コードベースを検索し、コンテキストのために他の変更ファイルを参照し、深いレビューを生成できます — 単なる表面的なdiffへのフィードバックではありません。diffレビュー以外にも、ocr scan はファイル全体をレビューできます。不慣れなコードベースの監査や、意味のあるdiffがないディレクトリの検査に便利です。

詳細は公式サイトをご覧ください。

ベンチマーク Copy Chapter

汎用エージェント（Claude Code）と比較して、Open Code Reviewは同じ基盤モデルで有意に高い精度（Precision）とF1スコアを達成し、トークン消費量は約1/9にとどまり、レビューもより高速です。ただし、リコール（Recall）は汎用エージェントより低くなります——これはノイズを抑え精度を優先する設計上のトレードオフです。

実際のコードレビューに基づくベンチマーク。50の人気オープンソースリポジトリから200の実際のPull Requestを厳選し、10のプログラミング言語をカバー——80人以上のシニアエンジニアによるクロスバリデーション（1,505件のアノテーション済み欠陥）。

Hugging FaceでAACR-Benchデータセットを見る。

なぜOpen Code Reviewなのか？ Copy Chapter

汎用エージェントの問題点 Copy Section

Claude CodeのSkillsのような汎用エージェントをコードレビューに使ったことがあれば、次のような課題に直面したことがあるはずです：

• 不完全なカバレッジ — 大きな変更セットでは、エージェントが「手を抜き」、一部のファイルだけを選択的にレビューして他を見落としがちです。
• 位置のずれ — 報告された問題が実際のコード位置と一致せず、行番号やファイル参照がターゲットからずれることが頻繁にあります。
• 不安定な品質 — 自然言語駆動のSkillsはデバッグが難しく、わずかなプロンプトの違いでレビュー品質が大きく変動します。

根本原因は、純粋に言語駆動のアーキテクチャにはレビュープロセスに対するハードな制約が欠けていることです。

コア設計: 決定論的エンジニアリング × エージェントのハイブリッド Copy Section

Open Code Reviewのコア哲学は、決定論的エンジニアリングとエージェントを組み合わせ、それぞれが得意とする領域を担当させることです。

決定論的エンジニアリング — ハードな制約

絶対に間違えてはならないレビューステップについては、言語モデルではなくエンジニアリングロジックが正しさを保証します：

• 正確なファイル選択 — どのファイルをレビューし、どのファイルをフィルタリングすべきかを正確に決定し、重要な変更が見落とされないようにします。
• スマートなファイルバンドル — 関連するファイルを単一のレビューユニットにグループ化します（例：message_en.propertiesとmessage_zh.propertiesはまとめてバンドルされます）。各バンドルは分離されたコンテキストを持つサブエージェントとして実行されます — 非常に大きな変更セットでも安定する分割統治戦略で、自然に並行レビューもサポートします。
• きめ細かなルールマッチング — 各ファイルの特性に応じてレビュールールをマッチングし、モデルの注意を鋭く集中させ、情報ノイズを発生源から排除します。純粋に言語駆動のルール誘導と比べて、テンプレートエンジンベースのルールマッチングはより安定的で予測可能です。
• 外部の位置特定・リフレクションモジュール — 独立したコメント位置特定モジュールとコメントリフレクションモジュールにより、AIフィードバックの位置精度と内容精度の両方を体系的に向上させます。

エージェント — 動的な意思決定

エージェントの強みは、最も重要な領域 — 動的な意思決定と動的なコンテキスト取得 — に集中させています：

• シナリオに最適化されたプロンプト — コードレビュー向けに深く最適化されたプロンプトテンプレートにより、効果を高めつつトークン消費を削減します。
• シナリオに最適化されたツールセット — 大規模な本番データにおけるツール呼び出しトレースの詳細な分析 — 呼び出し頻度の分布、ツールごとの繰り返し率、新しいツールが呼び出しチェーン全体に与える影響など — から抽出された、汎用エージェントツールキットよりもコードレビューにおいて安定的で予測可能な専用ツールセットです。

使い方 Copy Chapter

前提条件 Copy Section

• Git >= 2.41 — Open Code Review は diff 生成、コード検索、リポジトリ操作に Git を利用します。

CLI Copy Section

インストール

npm install @alibaba-group/open-code-review

インストール後、ocrコマンドがグローバルに利用可能になります。

その他のインストール方法（インストールスクリプト、GitHub Release バイナリ、ソースビルド）については、インストールガイドを参照してください。

クイックスタート

1. LLMの設定

コードレビューの前にLLMの設定が必要です。デリゲートモードを使用する場合は不要です。

ocr config provider          # ビルトインプロバイダーを選択またはカスタムプロバイダーを追加
ocr config model             # アクティブなプロバイダーのモデルを選択

対話的UIがプロバイダーの選択、APIキーの入力、モデル設定をガイドし、完了後に自動的に接続テストを行います。

CLIセットアップ、環境変数、カスタムプロバイダーなどの高度な設定については、設定ガイドを参照してください。

2. レビュー

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 <session-id>

# フルファイルスキャン — diffではなくファイル全体をレビュー（git履歴不要）
ocr scan                          # リポジトリ全体をスキャン
ocr scan --path internal/agent    # ディレクトリまたは特定のファイルをスキャン
ocr scan --resume <session-id>   # 中断したフルファイルスキャンを再開

# デリゲートモード — AI コーディングエージェントが自らレビューを実行
# OCR はファイル選択とルール解決を担当。LLM 設定不要
ocr delegate preview
ocr delegate rule src/main.go src/handler.go

ドキュメント Copy Chapter

完全なドキュメントは open-codereview.ai/docs にあります：

• クイックスタート — インストールして最初のレビューを実行
• インストール — すべてのプラットフォームとパッケージマネージャー
• CLI リファレンス — すべてのコマンドとフラグ
• レビュールール — レビュールールのカスタマイズ、パスフィルタリングとターゲティング
• 設定 — 設定キーと環境変数
• MCP サーバー — 外部ツールでレビューエージェントを拡張
• コーディングエージェント連携 — 使用するプラットフォームを選択
  • Claude Code — レビュー用スラッシュコマンドを含むプラグインをインストール
  • Codex — 呼び出し可能なレビュースキルを含むプラグインをインストール
  • Cursor — 移植可能なレビュースキルを含むプラグインをインストール
  • OpenCode — ネイティブレビュー・ツールとスラッシュコマンドをインストール
  • QCA Forward — QCA ホストモデルと公開可能なテンプレートで委任モードを実行
  • Skill 対応エージェント — 移植可能なエージェントスキルをインストール
• レビュー実行モード — 連携後、どの LLM がレビューを実行するかを選択
  • デフォルト（OCR が管理） — OCR が設定済みの LLM を使用してレビューを実行
  • デリゲートモード — コーディングエージェントが自身の LLM を使用してレビューを実行。OCR の API キーは不要
• CI/CD 連携 — GitHub Actions、GitLab CI、GitFlic CI、Gerrit との統合
• セッションビューアー — ブラウザでレビューセッションを閲覧・再生
• テレメトリー — 可観測性のためのOpenTelemetry統合
• FAQ — よくある質問とトラブルシューティング

コントリビューション Copy Chapter

このプロジェクトは、貢献してくださるすべての方々のおかげで成り立っています。開発環境のセットアップ、コーディングガイドライン、プルリクエストの提出方法についてはCONTRIBUTING.ja-JP.mdを参照してください。

ライセンス Copy Chapter

Apache-2.0 — Copyright 2026 Alibaba

File: README.ko-KR.md Copy Chapter

Open Code Review란? Copy Chapter

Open Code Review는 AI 기반 코드 리뷰 CLI 도구입니다. Alibaba Group의 내부 공식 AI 코드 리뷰 어시스턴트에서 시작했으며, 지난 2년 동안 수만 명의 개발자에게 제공되어 수백만 건의 코드 결함을 찾아냈습니다. 대규모 환경에서 충분히 검증한 뒤 커뮤니티를 위해 오픈 소스 프로젝트로 공개했습니다. 모델 endpoint만 설정하면 바로 사용할 수 있습니다.

이 도구는 Git diff를 읽고, 변경 파일을 tool-use 기능을 가진 agent를 통해 설정 가능한 LLM으로 전달한 뒤, 라인 단위 위치 정보가 포함된 구조화된 리뷰 코멘트를 생성합니다. agent는 전체 파일 내용 읽기, 코드베이스 검색, 다른 변경 파일 확인 등을 통해 맥락을 확보하고 표면적인 diff 피드백이 아닌 깊이 있는 리뷰를 수행할 수 있습니다. diff 리뷰 외에도 ocr scan은 전체 파일을 리뷰할 수 있어, 익숙하지 않은 코드베이스를 감사하거나 의미 있는 diff가 없는 디렉터리를 검토하는 데 유용합니다.

자세한 내용은 공식 웹사이트를 참조하세요.

벤치마크 Copy Chapter

범용 Agent(Claude Code)와 비교할 때, Open Code Review는 동일한 기반 모델에서 유의미하게 높은 **정밀도(Precision)**와 F1 점수를 달성하며, 토큰 소비량은 약 1/9 수준이고 리뷰 속도도 더 빠릅니다. 다만 재현율(Recall)은 범용 Agent보다 낮습니다 — 이는 노이즈를 줄이고 정밀도를 우선하는 설계적 트레이드오프입니다.

실제 코드 리뷰 기반 벤치마크. 50개 인기 오픈소스 저장소에서 200개 실제 Pull Request를 엄선하고, 10개 프로그래밍 언어를 커버 — 80명 이상의 시니어 엔지니어가 교차 검증(1,505개 어노테이션된 결함).

Hugging Face에서 AACR-Bench 데이터셋 살펴보기.

왜 Open Code Review인가? Copy Chapter

범용 Agent의 문제 Copy Section

Claude Code Skills 같은 범용 agent로 코드 리뷰를 해봤다면 다음 문제를 경험했을 수 있습니다.

• 불완전한 커버리지: 큰 changeset에서는 일부 파일만 선택적으로 리뷰하고 중요한 파일을 놓치기 쉽습니다.
• 위치 드리프트: 지적된 문제가 실제 코드 위치와 맞지 않거나 라인 번호와 파일 참조가 어긋나는 일이 자주 발생합니다.
• 불안정한 품질: 자연어 기반 Skill은 디버깅이 어렵고, 작은 prompt 변화에도 리뷰 품질이 크게 흔들릴 수 있습니다.

근본 원인은 순수 언어 중심 아키텍처가 리뷰 프로세스에 강한 제약을 제공하지 못한다는 점입니다.

핵심 설계: 결정적 엔지니어링과 Agent의 하이브리드 Copy Section

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을 제공합니다.

사용 방법 Copy Chapter

사전 요구 사항 Copy Section

• Git >= 2.41 — Open Code Review는 diff 생성, 코드 검색, 저장소 작업에 Git을 사용합니다.

CLI Copy Section

설치

npm install @alibaba-group/open-code-review

설치 후 ocr 명령을 전역에서 사용할 수 있습니다.

기타 설치 방법(설치 스크립트, GitHub Release binary, 소스 빌드)은 설치 가이드를 참조하세요.

Quick Start

1. LLM 설정

코드 리뷰 전에 LLM 설정이 필요합니다. 위임 모드를 사용하는 경우에는 불필요합니다.

ocr config provider          # built-in provider 선택 또는 custom provider 추가
ocr config model             # 활성 provider의 model 선택

대화형 UI가 provider 선택, API key 입력, model 설정을 안내하며, 완료 후 자동으로 연결 테스트를 수행합니다.

CLI 설정, 환경 변수, 커스텀 provider 등 고급 설정은 설정 가이드를 참조하세요.

2. 리뷰 실행

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 <session-id>

# 전체 파일 스캔 — diff 대신 파일 전체를 리뷰 (git 이력 불필요)
ocr scan                          # 전체 repository 스캔
ocr scan --path internal/agent    # 디렉터리 또는 특정 파일 스캔
ocr scan --resume <session-id>   # 중단된 전체 파일 스캔 재개

# 위임 모드 — AI 코딩 에이전트가 직접 리뷰 수행
# OCR은 파일 선택과 규칙 해석만 담당; LLM 설정 불필요
ocr delegate preview
ocr delegate rule src/main.go src/handler.go

Documentation Copy Chapter

전체 문서는 open-codereview.ai/docs 에서 확인할 수 있습니다:

• 빠른 시작 — 설치하고 첫 리뷰 실행하기
• 설치 — 모든 플랫폼 및 패키지 매니저
• CLI 레퍼런스 — 모든 명령어와 플래그
• 리뷰 규칙 — 리뷰 규칙 커스터마이징, 경로 필터링 및 타겟팅
• 설정 — 설정 키와 환경 변수
• MCP 서버 — 외부 도구로 리뷰 에이전트 확장
• 코딩 에이전트 연동 — 사용하는 플랫폼 선택
  • Claude Code — 리뷰 슬래시 명령이 포함된 플러그인 설치
  • Codex — 호출 가능한 리뷰 스킬이 포함된 플러그인 설치
  • Cursor — 이식 가능한 리뷰 스킬이 포함된 플러그인 설치
  • OpenCode — 네이티브 리뷰 도구와 슬래시 명령 설치
  • QCA Forward — QCA 호스트 모델과 게시 가능한 템플릿으로 위임 모드 실행
  • Skill 호환 에이전트 — 이식 가능한 에이전트 스킬 설치
• 리뷰 실행 모드 — 연동 후 리뷰를 수행할 LLM 선택
  • 기본 모드(OCR 관리) — OCR이 설정된 LLM을 사용해 리뷰 수행
  • 위임 모드 — 코딩 에이전트가 자체 LLM을 사용해 리뷰 수행; OCR API 키 불필요
• CI/CD 연동 — GitHub Actions, GitLab CI, GitFlic CI, Gerrit 통합
• 세션 뷰어 — 브라우저에서 리뷰 세션 탐색 및 재생
• 텔레메트리 — 관측성을 위한 OpenTelemetry 통합
• FAQ — 자주 묻는 질문과 문제 해결

Contributing Copy Chapter

이 프로젝트는 기여해 주신 모든 분들 덕분에 존재합니다. 개발 환경 설정, coding guideline, pull request 제출 방법은 CONTRIBUTING.ko-KR.md를 참고하세요.

License Copy Chapter

Apache-2.0 Copyright 2026 Alibaba

File: README.ru-RU.md Copy Chapter

Что такое Open Code Review? Copy Chapter

Open Code Review — это CLI-инструмент для код-ревью на основе ИИ. Он появился как внутренний официальный ИИ-ассистент код-ревью Alibaba Group: за последние два года им воспользовались десятки тысяч разработчиков, и он выявил миллионы дефектов в коде. После тщательной проверки в огромных масштабах мы превратили его в open-source-проект для сообщества. Чтобы начать работу, достаточно настроить эндпоинт модели.

Инструмент читает git-диффы, отправляет изменённые файлы настраиваемой LLM через агента с поддержкой вызова инструментов (tool use) и генерирует структурированные ревью-комментарии с точностью до строки. Агент может читать полное содержимое файлов, искать по кодовой базе, заглядывать в другие изменённые файлы за контекстом и выполнять глубокое ревью — а не только давать поверхностные замечания по диффу. Помимо ревью диффов, ocr scan позволяет проверять файлы целиком — удобно для аудита незнакомой кодовой базы или каталогов без значимого диффа.

Подробнее на официальном сайте.

Бенчмарк Copy Chapter

По сравнению с агентами общего назначения (Claude Code), Open Code Review при той же базовой модели достигает значительно более высоких показателей Precision и F1, потребляя лишь ~1/9 токенов и выполняя ревью быстрее. При этом показатель Recall ниже, чем у агентов общего назначения — это осознанный компромисс в пользу точности и минимального шума.

Бенчмарк собран на основе реальных код-ревью и включает 50 популярных open-source-репозиториев, 200 реальных пул-реквестов и 10 языков программирования. Разметку из 1 505 дефектов перекрёстно проверили более 80 ведущих инженеров.

Открыть датасет AACR-Bench на Hugging Face.

Почему Open Code Review? Copy Chapter

Проблема агентов общего назначения Copy Section

Если вы использовали для код-ревью агентов общего назначения, например Claude Code со Skills, вы наверняка сталкивались с такими проблемами:

• Неполное покрытие — на крупных ченджсетах агенты склонны «срезать углы»: выборочно проверяют часть файлов и пропускают остальные.
• Дрейф позиций — найденные проблемы часто не совпадают с реальным местом в коде: номера строк и ссылки на файлы «уезжают» от цели.
• Нестабильное качество — Skills, управляемые естественным языком, трудно отлаживать, и качество ревью заметно колеблется при небольших изменениях промпта.

Первопричина: чисто языковая архитектура не накладывает жёстких ограничений на процесс ревью.

Ключевая идея: детерминированная инженерия × агент Copy Section

Ключевая философия Open Code Review — сочетать детерминированную инженерию и агента так, чтобы каждый занимался тем, что у него получается лучше всего.

Детерминированная инженерия — жёсткие гарантии

Для тех шагов ревью, где нельзя ошибаться, корректность гарантирует инженерная логика, а не языковая модель:

• Точный отбор файлов — точно определяет, какие файлы нуждаются в ревью, а какие следует отфильтровать, гарантируя, что ни одно важное изменение не будет упущено.
• Группировка связанных файлов — объединяет связанные файлы в одну единицу ревью (например, message_en.properties и message_zh.properties). Каждая группа обрабатывается отдельным субагентом в изолированном контексте. Подход «разделяй и властвуй» сохраняет стабильность при очень больших изменениях и позволяет выполнять ревью параллельно.
• Точное сопоставление правил — подбирает правила ревью с учётом особенностей каждого файла, удерживая внимание модели на задаче и устраняя лишний информационный шум. Сопоставление по шаблонам работает стабильнее и предсказуемее, чем управление правилами только на естественном языке.
• Внешние модули позиционирования и рефлексии — независимые модули позиционирования комментариев и рефлексии над комментариями системно повышают точность как расположения, так и содержания замечаний ИИ.

Агент — динамические решения

Сильные стороны агента сосредоточены там, где они важнее всего, — в динамических решениях и динамическом доборе контекста:

• Промпты, заточенные под сценарий — шаблоны промптов, глубоко оптимизированные под код-ревью: выше качество при меньшем расходе токенов.
• Специализированный набор инструментов — создан на основе анализа вызовов инструментов в реальных проектах: частоты вызовов, доли повторных обращений к каждому инструменту и влияния новых инструментов на всю цепочку. Такой набор работает при код-ревью стабильнее и предсказуемее, чем универсальные инструменты агента.

Как использовать Copy Chapter

Предварительные требования Copy Section

• Git >= 2.41 — Open Code Review использует Git для генерации diff, поиска по коду и операций с репозиторием.

CLI Copy Section

Установка

npm install @alibaba-group/open-code-review

После установки команда ocr доступна глобально.

Другие способы установки (скрипт установки, бинарный файл из GitHub Release, сборка из исходников) описаны в руководстве по установке.

Быстрый старт

1. Настройте LLM

Перед запуском ревью необходимо настроить LLM, если только вы не используете режим делегирования.

ocr config provider          # Выбрать встроенного провайдера или добавить пользовательский
ocr config model             # Выбрать модель для активного провайдера

Интерактивный UI проведёт вас через выбор провайдера, ввод API-ключа и настройку модели, после чего автоматически проверит подключение.

Настройка через CLI, переменные окружения, пользовательские провайдеры и другие расширенные параметры описаны в руководстве по конфигурации.

2. Запустите ревью

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 <session-id>

# Полнофайловое сканирование — ревью целых файлов вместо диффа (история git не нужна)
ocr scan                          # сканировать весь репозиторий
ocr scan --path internal/agent    # сканировать каталог или конкретные файлы
ocr scan --resume <session-id>   # возобновить прерванное полнофайловое сканирование

# Режим делегирования — ИИ-агент сам выполняет ревью
# OCR отвечает за выбор файлов и разрешение правил; настройка LLM не требуется
ocr delegate preview
ocr delegate rule src/main.go src/handler.go

Документация Copy Chapter

Полная документация доступна на open-codereview.ai/docs:

• Быстрый старт — установка и запуск первого ревью
• Установка — все платформы и менеджеры пакетов
• Справочник CLI — все команды и флаги
• Правила ревью — кастомизация правил ревью, фильтрация и таргетинг по путям
• Конфигурация — ключи конфигурации и переменные окружения
• MCP-сервер — расширение агента ревью внешними инструментами
• Интеграции с кодинг-агентами — выберите используемую платформу
  • Claude Code — установка плагина со slash-командами для ревью
  • Codex — установка плагина с вызываемыми навыками ревью
  • Cursor — установка плагина с переносимыми навыками ревью
  • OpenCode — установка нативных инструментов ревью и slash-команд
  • QCA Forward — запуск режима делегирования с хост-моделью QCA и готовым к публикации шаблоном
  • Агенты с поддержкой Skill — установка переносимого навыка агента
• Режимы выполнения ревью — после интеграции выберите, какая LLM выполняет ревью
  • По умолчанию (под управлением OCR) — OCR выполняет ревью с помощью настроенной LLM
  • Режим делегирования — кодинг-агент выполняет ревью с помощью собственной LLM; API-ключ для OCR не требуется
• Интеграция с CI/CD — GitHub Actions, GitLab CI, GitFlic CI и Gerrit
• Просмотр сессий — просмотр и воспроизведение сессий ревью в браузере
• Телеметрия — интеграция с OpenTelemetry для наблюдаемости
• FAQ — частые вопросы и устранение неполадок

Участие в разработке Copy Chapter

Этот проект существует благодаря всем, кто вносит свой вклад. В CONTRIBUTING.ru-RU.md описаны настройка окружения разработки, рекомендации по коду и порядок отправки пул-реквестов.

Лицензия Copy Chapter

Apache-2.0 — Copyright 2026 Alibaba

File: README.zh-CN.md Copy Chapter

Open Code Review 是什么？ Copy Chapter

Open Code Review 是一款 AI 驱动的代码审查 CLI 工具。它的前身是阿里集团内部官方 AI 代码审查助手，过去两年在内部服务了数万开发者，识别了数百万个代码缺陷。经过大规模充分验证后，我们将其孵化为开源项目，对社区开放。只需配置一个模型端点即可使用。

它读取 Git diff，通过具备工具调用能力的 Agent 将变更文件发送至可配置的 LLM，生成具有行级精度的结构化审查意见。Agent 可以读取完整文件内容、搜索代码库、检查其他变更文件以获取上下文，从而进行深度审查——而非仅停留在表面的 diff 反馈。除了 diff 审查，ocr scan 可以审查整个文件，适用于审计不熟悉的代码库或没有有意义 diff 的目录。

访问官方网站了解更多信息。

基准测试 Copy Chapter

相比通用 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 数据集。

为什么选择 Open Code Review？ Copy Chapter

通用 Agent 的局限 Copy Section

如果你深度用过 Claude Code 等通用 Agent + Skills 方案做代码审查，可能对以下问题深有同感：

• 覆盖不全 —— 变更较大时，Agent 倾向于"偷懒"，选择性地审查部分文件，导致遗漏。
• 位置漂移 —— 报告的问题与实际代码位置常常对不上，出现行号或文件偏移。
• 效果不稳定 —— 基于自然语言驱动的 Skills 难以调试，审查质量因提示词的细微差异而大幅波动。

这些问题的根源在于：纯语言驱动的架构缺乏对审查流程的强约束。

核心设计：确定性工程 × Agent 混合驱动 Copy Section

Open Code Review 的核心设计理念是将确定性工程与 Agent 结合，各司其职。

确定性工程——负责强约束

对代码审查场景中"不能出错"的环节，由工程逻辑而非语言模型来保证：

• 精准的文件筛选 —— 明确哪些文件需要审查、哪些应当过滤，确保真正重要的改动一个不漏。
• 智能的文件打包 —— 将关联文件归并为同一审查单元（例如 message_en.properties 与 message_zh.properties 会被打包在一起）。每个包会作为 sub-agent 进行任务，它们之间的上下文是隔离的——这一分治策略在超大变更场景下表现更为稳定，同时天然支持并发审查。
• 精细化规则匹配 —— 针对不同文件的特征，匹配对应的审查规则，确保模型的注意力足够聚焦，从源头规避信息噪声的干扰。相比纯语言驱动的规则引导，基于模板引擎的规则匹配行为更稳定、结果更可预期。
• 外挂的定位与反思组件 —— 独立的评论定位模块与评论反思模块，系统性地提升 AI 反馈的位置准确性与内容准确性。

Agent——负责动态决策

将 Agent 的优势集中发挥在它真正擅长的地方——动态决策、动态召回上下文：

• 场景化提示词调优 —— 针对代码审查场景深度优化提示词模板，在提升效果的同时有效降低 Token 消耗。
• 场景化工具集沉淀 —— 基于对大量线上数据中工具调用轨迹的深入分析，包括不同工具的调用频率分布、单一工具的重复调用率、新增工具对整体调用链路的影响等多维度分析，从而对通用 Agent 工具集进行取舍与拆分，最终沉淀出一套在代码审查场景下效果更稳定、行为更可预期的专属工具集。

如何使用 Copy Chapter

前置条件 Copy Section

• Git >= 2.41 — Open Code Review 依赖 Git 进行 diff 生成、代码搜索和仓库操作。

CLI Copy Section

安装

npm install @alibaba-group/open-code-review

安装后，ocr 命令即可全局使用。

其他安装方式（安装脚本、GitHub Release 二进制、源码构建），详见安装指南。

快速开始

1. 配置 LLM

在审查代码之前，必须先配置 LLM。除非你使用委托模式。

ocr config provider          # 选择内置供应商或添加自定义供应商
ocr config model             # 为当前供应商选择模型

交互式界面会引导你完成供应商选择、API Key 输入和模型配置，完成后自动测试连通性。

命令行设置、环境变量、自定义供应商等高级配置，详见配置指南。

2. 开始审查

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 <session-id>

# 全量文件扫描 —— 审查整个文件而非 diff（无需 git 历史）
ocr scan                          # 扫描整个仓库
ocr scan --path internal/agent    # 扫描指定目录或文件
ocr scan --resume <session-id>   # 恢复中断的全量文件扫描

# 委托模式 — 让你的 AI 编程 agent 自己执行评审
# OCR 负责文件选择和规则解析；无需配置 LLM
ocr delegate preview
ocr delegate rule src/main.go src/handler.go

文档 Copy Chapter

完整文档见 open-codereview.ai/docs：

• 快速开始 —— 安装并运行你的第一次评审
• 安装 —— 覆盖各平台与包管理器
• CLI 参考 —— 所有命令与参数
• 评审规则 —— 深度定制规则进行评审，过滤路径、指定路径等
• 配置 —— 配置项与环境变量
• MCP 服务器 —— 用外部工具扩展评审 agent
• 编程 Agent 集成 —— 选择你使用的平台
  • Claude Code —— 安装包含评审斜杠命令的插件
  • Codex —— 安装包含可调用评审 Skill 的插件
  • Cursor —— 安装包含可移植评审 Skill 的插件
  • OpenCode —— 安装原生评审工具和斜杠命令
  • QCA Forward —— 使用 QCA 宿主模型运行委托模式，并提供可发布的模板
  • 兼容 Skill 的 Agent —— 安装可移植的 Agent Skill
• 评审执行模式 —— 完成集成后，选择由哪个 LLM 执行评审
  • 默认模式（OCR 驱动） —— OCR 使用其已配置的 LLM 执行评审
  • 委托模式 —— 编程 Agent 使用自身的 LLM 执行评审；无需 OCR API Key
• CI/CD 集成 —— 支持 GitHub Actions、GitLab CI、GitFlic CI、Gerrit 集成
• 会话查看器 —— 在浏览器中浏览和回放评审会话
• 遥测 —— OpenTelemetry 集成，用于可观测性
• FAQ —— 常见问题与故障排查

贡献 Copy Chapter

感谢所有为本项目做出贡献的人。参见 CONTRIBUTING.zh-CN.md 了解开发环境搭建、编码规范以及如何提交 Pull Request。

许可证 Copy Chapter

Apache-2.0 — Copyright 2026 Alibaba