mirror of
https://github.com/alibaba/open-code-review.git
synced 2026-10-22 14:50:15 +00:00
b3badd376f
* feat(raw): capture raw LLM traffic via SDK middleware (opt-in) Add opt-in raw capture (OCR_RAW_LOGGING=1) built on the SDK HTTP middleware seam: every real HTTP attempt against the LLM endpoint is recorded verbatim - raw request body after extra_body merging and session-key expansion, raw response body (SSE bodies stored as text), redacted headers, model, duration and per-attempt identity from RequestMeta - to ~/.opencodereview/raw/<repo>/<session>.jsonl. The holder/writer split mirrors the RetryCollector pattern: the holder is created with the client in loadLLMRuntime, the per-session writer is bound from the cmd layer once the session exists. Default off mounts no middleware and changes nothing. * fix(raw): harden raw capture for Windows CI and partial writes Finalize the session in the bind tests so the session JSONL handle is released before TempDir cleanup, which fails on Windows while the file is open. Replace the Unix-only HOME failure injection in TestRawFileWriter_OpenFailure with a cross-platform squat on the target raw directory path. Marshal each record in memory before writing so a failed disk write cannot leave a partial JSONL line that corrupts the next record. * fix(raw): harden raw capture per review findings 1. Register the raw middleware before the retry observer. Registering it after placed it innermost in the SDK middleware chain, so the observer's next() covered raw's full-body read and synchronous disk write; under streaming that turned DurationToHeadersMS from a headers-only measurement into the whole generation time whenever OCR_RAW_LOGGING=1. Add a regression test with a deliberately slow writer that turns red under the old order. 2. An empty request body produced a zero-length RawMessage, which fails json.Marshal and made RawFileWriter silently drop the whole record. Leave Request nil in that case so the record is written with "request": null. Extend the empty-bodies test with an encodability assertion. 3. Add status_code to RawRecord so HTTP-level failures are visible without parsing the body, and document the capture-point semantics: on Bedrock the records show the pre-signing Anthropic-shaped request and the SSE-normalized streaming response, because the bedrock adaptation runs closer to the wire. Drop the "exactly what was sent" claim the Bedrock path never honoured. 4. UseTestSessions now redirects rawSubDir to "test-raw" alongside the session redirect, and TestRawSubDirIsSeparateFromSessions pins the literals instead of comparing two already-redirected variables. 5. A request-body read failure is now replayed to the SDK via errReader, mirroring the response side, instead of handing it a clean truncated body that turns a client-side fault into a server-side 400. The record carries the error and leaves Request nil, since the partial bytes are not valid JSON and would fail Encode. 6. A failed write no longer kills later captures: records go straight to the file, a failed encode or write warns once on stderr and drops only that record, and the next one retries. The truncate/offset recovery machinery was removed entirely: after a failed Truncate the anchor could drift and a later recovery could cut into records already on disk, and a partial line from a rare short write is acceptable — readers skip unparseable lines. Also correct the reopen test's stale claim that resume reuses the session ID; every run gets a fresh one. 7. Repeated request headers survive as an RFC 9110 comma-joined list instead of being truncated to the first value. 8. When the request-body read fails and next() fails too, the record keeps both errors instead of letting next's error overwrite the root cause. 9. Non-JSON request bytes fall back to a request_text field, mirroring the response side, so a malformed body cannot fail the record's encode and drop it whole. Unreachable while the SDK marshals every body; the guard completes the writer-level invariant that every record encodes. 10. The raw writer's closer detaches the holder before closing the file (holder.Set(nil)), so LLM calls that run after the closer bypass capture instead of writing to a closed file. The no-write-after-close guarantee was structurally absent and only held through defer registration order. 11. The telemetry docs (five languages) now state that with raw capture on, streaming responses are read in full before the capture hands them on to the rest of the processing, and that capture redacts request headers but records request and response bodies as-is. 12. Timestamp is now the attempt start instead of the moment next() returned. It previously sat between the two ends of the interval duration_ms measures — under streaming, headers arrive in the first second while the stream runs for minutes — so no arithmetic on (timestamp, duration_ms) could place the attempt on a timeline. The two fields now share one base: the interval is exactly [timestamp, timestamp + duration_ms]. A TTFB-shaped regression test turns red under the old capture point. * feat(raw): capture response headers in raw records Response headers were discarded entirely. They carry the server-side request ID (x-request-id, Anthropic request-id, x-amzn-requestid), which often exists nowhere in the body, so raw captures could not be reconciled against provider or gateway logs — the primary debugging workflow this switch exists for. Rate-limit headers on 429s and content-type (SSE vs JSON) come along for the same reason. - Name every part of the record explicitly, in a <direction>_<part>[_<encoding>] scheme: headers becomes request_headers, request becomes request_body, request_text becomes request_body_text, and the response side mirrors all three. A bare `request` already carried three senses in one record (the body here, while request_id is the attempt and request_no the logical request), and once headers were named the body was the only part left implicit. The schema is unreleased, so this costs nothing now and freezes correctly later. - Add response_headers with the same redaction — Set-Cookie is a credential too — and RFC 9110 comma-joining, via a captureHeaders helper shared by both sides. The key is omitted when next() failed and no response exists. - Generalize the telemetry docs' redaction note from request headers to headers, in all five languages, now that both directions are captured. - Tests cover passthrough, Set-Cookie redaction, and JSON-key omission on transport errors. |
||
|---|---|---|
| .agents/plugins | ||
| .claude/commands | ||
| .claude-plugin | ||
| .github | ||
| .opencodereview | ||
| bin | ||
| cmd/opencodereview | ||
| examples | ||
| extensions/vscode | ||
| imgs | ||
| internal | ||
| npm | ||
| pages | ||
| plugins/open-code-review | ||
| scripts | ||
| skills | ||
| .gitattributes | ||
| .gitignore | ||
| .npmignore | ||
| action.yml | ||
| AGENTS.md | ||
| ASSURANCE_CASE.md | ||
| CLAUDE.md | ||
| CODE_OF_CONDUCT.md | ||
| CONTRIBUTING.ja-JP.md | ||
| CONTRIBUTING.ko-KR.md | ||
| CONTRIBUTING.md | ||
| CONTRIBUTING.ru-RU.md | ||
| CONTRIBUTING.zh-CN.md | ||
| go.mod | ||
| go.sum | ||
| GOVERNANCE.md | ||
| install.ps1 | ||
| install.sh | ||
| LICENSE | ||
| Makefile | ||
| package.json | ||
| README.ja-JP.md | ||
| README.ko-KR.md | ||
| README.md | ||
| README.ru-RU.md | ||
| README.zh-CN.md | ||
| ROADMAP.md | ||
| SECURITY.md | ||
OpenCodeReview
English | 简体中文 | 日本語 | 한국어 | Русский
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 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.
| 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.propertiesandmessage_zh.propertiesare 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
npm install -g @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
# Save results to a file (recommended for AI host agents)
ocr review --format json --output result.json
# 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:
- 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
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
Apache-2.0 — Copyright 2026 Alibaba