@alibaba-group/open-code-review 1.2.4 → 1.2.5

package/README.zh-CN.md

@@ -7,10 +7,11 @@
 <p align="center">
   <a href="https://www.npmjs.com/package/@alibaba-group/open-code-review"><img alt="npm" src="https://img.shields.io/npm/v/@alibaba-group/open-code-review?style=flat-square" /></a>
   <a href="https://github.com/alibaba/open-code-review/actions/workflows/release.yml"><img alt="Build status" src="https://img.shields.io/github/actions/workflow/status/alibaba/open-code-review/release.yml?style=flat-square" /></a>
+  <a href="https://goreportcard.com/report/github.com/alibaba/open-code-review"><img alt="Go Report Card" src="https://goreportcard.com/badge/github.com/alibaba/open-code-review?style=flat-square" /></a>
   <a href="https://github.com/alibaba/open-code-review/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/alibaba/open-code-review?style=flat-square" /></a>
 </p>
 <p align="center">
-  <a href="README.md">English</a> | 简体中文 | <a href="README.ja-JP.md">日本語</a>
+  <a href="README.md">English</a> | 简体中文 | <a href="README.ja-JP.md">日本語</a> | <a href="README.ko-KR.md">한국어</a>
 </p>
 
 ---
@@ -116,18 +117,22 @@ sudo cp dist/opencodereview /usr/local/bin/ocr
 # 方式 A：交互式配置
 ocr config set llm.url https://api.anthropic.com/v1/messages
 ocr config set llm.auth_token your-api-key-here
+ocr config set llm.auth_header x-api-key
 ocr config set llm.model claude-opus-4-6
 ocr config set llm.use_anthropic true
 
 # 方式 B：环境变量（优先级最高）
 export OCR_LLM_URL=https://api.anthropic.com/v1/messages
 export OCR_LLM_TOKEN=your-api-key-here
+export OCR_LLM_AUTH_HEADER=x-api-key
 export OCR_LLM_MODEL=claude-opus-4-6
 export OCR_USE_ANTHROPIC=true
 ```
 
 配置存储于 `~/.opencodereview/config.json`。
 
+对于 Anthropic，标准 `sk-ant-*` API key 使用 `x-api-key`；OAuth token 使用 `authorization`。如果未配置 `llm.auth_header` / `OCR_LLM_AUTH_HEADER`，OCR 会保留现有的 `authorization` bearer-token 行为。
+
 同时兼容了 Claude Code 环境变量（`ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_MODEL`），并解析 `~/.zshrc` / `~/.bashrc` 中的相关导出。
 
 > **CC-Switch 用户特别提醒**：如果你使用 [CC-Switch](https://github.com/farion1231/cc-switch) 并开启了[路由服务](https://www.ccswitch.io/zh/docs?section=proxy&item=service)，可以将 `llm.url` 配置成 CC-Switch 启动的代理地址，无需额外配置：
@@ -183,7 +188,43 @@ npx skills add alibaba/open-code-review --skill open-code-review
 
 此命令注册 `/open-code-review:review` 斜杠命令，运行 OCR 并自动过滤和修复问题。
 
-#### 方式三：直接复制命令文件
+#### 方式三：作为 Codex Plugin 安装
+
+对于本地 Codex，可以从此仓库安装 Open Code Review plugin：
+
+```bash
+codex plugin marketplace add alibaba/open-code-review
+codex
+/plugins
+```
+
+对于本地 checkout 或 fork：
+
+```bash
+codex plugin marketplace add .
+codex
+/plugins
+```
+
+安装并启用 `Open Code Review` 后，启动新的 Codex thread 并显式调用：
+
+```text
+@Open Code Review review my current changes
+@Open Code Review review this branch against main
+@Open Code Review review and fix high-confidence issues
+```
+
+这会注册一个 Codex skill，用于运行本地 OCR CLI：
+
+```bash
+ocr review --audience agent
+```
+
+此集成不会改变 OCR 的内部 LLM backend，也不需要为 Codex 配置 OpenAI Responses API endpoint。OCR 本身仍需要按照 CLI setup 部分安装并配置 `ocr` CLI。
+
+韩文指南：[`plugins/open-code-review/CODEX.ko-KR.md`](plugins/open-code-review/CODEX.ko-KR.md)
+
+#### 方式四：直接复制命令文件
 
 如果不想使用任何包管理器，可以直接复制命令文件，在 Claude Code 中使用 `/open-code-review` 斜杠命令。
 
@@ -316,6 +357,48 @@ OCR 通过四层优先级链解析评审规则。每层采用首次匹配原则
 - 在每一层内，规则按声明顺序评估 —— 首次匹配生效。
 - 如果规则文件不存在，将被静默跳过。
 
+### 路径过滤
+
+规则文件同时支持 `include` 和 `exclude` 字段，用于控制哪些文件进入审查范围：
+
+```json
+{
+  "rules": [
+    {"path": "**/*.java", "rule": "检查空值安全"}
+  ],
+  "include": ["src/main/**/*.java", "lib/**/*.kt"],
+  "exclude": ["**/generated/**", "vendor/**"]
+}
+```
+
+**过滤决策优先级（从高到低）：**
+
+| 步骤 | 条件 | 结果 |
+|------|------|------|
+| 1 | 文件为二进制文件 | 排除 |
+| 2 | 路径匹配用户 `exclude` 模式 | 排除 |
+| 3 | 文件扩展名不在支持列表中 | 排除 |
+| 4 | 配置了 `include` 且路径匹配 | **纳入审查**（跳过步骤 5） |
+| 5 | 路径匹配内置默认排除模式（测试文件等） | 排除 |
+| 6 | 以上均不满足 | 纳入审查 |
+
+**生效逻辑：**
+
+- `include` 和 `exclude` 遵循与评审规则相同的优先级链（`--rule` > 项目配置 > 全局配置），取**最高优先级中配置了 include/exclude 的那一层**整体生效，不会跨层合并。
+- `exclude` 始终优先于 `include` —— 同时匹配两者的文件会被排除。
+- `include` 的作用是**绕过内置默认排除模式**（如测试文件），而非限制审查范围 —— 未匹配 `include` 的文件仍会正常进入后续的默认过滤判断。
+- 模式语法：支持 `**` 递归匹配、`*` 单级匹配和 `{a,b}` 大括号展开，匹配时不区分大小写。
+
+**内置默认排除模式**（用于过滤测试文件等，可通过 `include` 覆盖）：
+
+```
+**/*_test.go, **/*Test.java, **/*Tests.java, **/*_test.rs,
+**/*.test.{js,jsx,ts,tsx}, **/*.spec.{js,jsx,ts,tsx}, **/__tests__/**,
+**/src/test/java/**/*.java, **/src/test/**/*.kt,
+**/test/**/*_test.py, **/tests/**/*_test.py, **/*_test.py,
+**/*_spec.rb, **/spec/**/*_spec.rb, **/oh_modules/**
+```
+
 ## 配置参考
 
 配置文件：`~/.opencodereview/config.json`
@@ -324,6 +407,7 @@ OCR 通过四层优先级链解析评审规则。每层采用首次匹配原则
 |----|------|------|
 | `llm.url` | string | `https://api.openai.com/v1/chat/completions` |
 | `llm.auth_token` | string | `sk-xxxxxxx` |
+| `llm.auth_header` | string | 仅 Anthropic：`x-api-key` \| `authorization` |
 | `llm.model` | string | `claude-opus-4-6` |
 | `llm.use_anthropic` | boolean | `true` \| `false` |
 | `language` | string | `English` \| `Chinese`（默认：Chinese） |
@@ -340,6 +424,7 @@ OCR 通过四层优先级链解析评审规则。每层采用首次匹配原则
 |------|------|
 | `OCR_LLM_URL` | LLM API 端点 URL |
 | `OCR_LLM_TOKEN` | API 密钥 / 认证令牌 |
+| `OCR_LLM_AUTH_HEADER` | Anthropic 认证头（`x-api-key` 或 `authorization`） |
 | `OCR_LLM_MODEL` | 模型名称 |
 | `OCR_USE_ANTHROPIC` | `true` = Anthropic，`false` = OpenAI |
 

package/package.json

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

package/plugins/open-code-review/.codex-plugin/plugin.json

@@ -0,0 +1,34 @@
+{
+  "name": "open-code-review",
+  "version": "1.0.0",
+  "description": "Use Alibaba Open Code Review from local Codex.",
+  "author": {
+    "name": "Alibaba"
+  },
+  "homepage": "https://github.com/alibaba/open-code-review",
+  "repository": "https://github.com/alibaba/open-code-review",
+  "license": "Apache-2.0",
+  "keywords": [
+    "code-review",
+    "codex",
+    "ocr",
+    "open-code-review"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Open Code Review",
+    "shortDescription": "Run structured code reviews from local Codex.",
+    "longDescription": "Adds a Codex skill that invokes the local Open Code Review CLI to review Git workspace changes, commits, and branch comparisons.",
+    "developerName": "Alibaba",
+    "category": "Developer Tools",
+    "capabilities": [
+      "Read"
+    ],
+    "websiteURL": "https://github.com/alibaba/open-code-review",
+    "defaultPrompt": [
+      "Use Open Code Review to review my current changes.",
+      "Use Open Code Review to review this branch against main.",
+      "Use Open Code Review to review and fix high-confidence issues."
+    ]
+  }
+}

package/plugins/open-code-review/CODEX.ko-KR.md

@@ -0,0 +1,108 @@
+# Open Code Review Codex 플러그인 사용법
+
+이 문서는 로컬 Codex에서 Alibaba Open Code Review를 사용하는 방법을 설명합니다.
+
+## 개요
+
+이 플러그인은 Open Code Review를 Codex 내부 LLM backend로 바꾸지 않습니다. Codex에서 로컬 `ocr` CLI를 호출할 수 있도록 skill을 제공하는 통합입니다.
+
+```text
+Codex
+  └─ Open Code Review plugin
+      └─ ocr review --audience agent
+```
+
+## 사전 준비
+
+`ocr` CLI가 설치되어 있어야 합니다.
+
+```bash
+npm install -g @alibaba-group/open-code-review
+```
+
+설치 확인:
+
+```bash
+command -v ocr
+ocr version
+```
+
+OCR 자체의 LLM 설정도 필요합니다.
+
+```bash
+ocr llm test
+```
+
+이 명령이 실패하면 Codex 플러그인 설치와 별개로 OCR의 LLM 설정을 먼저 완료해야 합니다.
+
+## Codex에서 설치
+
+Codex에서 이 repo를 marketplace로 추가합니다.
+
+```bash
+codex plugin marketplace add alibaba/open-code-review
+codex
+```
+
+Codex 안에서 `/plugins`를 열고 `Open Code Review`를 설치 및 활성화합니다.
+
+로컬 checkout 또는 fork에서 테스트할 때는 다음을 사용할 수 있습니다.
+
+```bash
+codex plugin marketplace add .
+codex
+```
+
+## 사용 예시
+
+새 Codex thread에서 다음처럼 요청합니다.
+
+```text
+@Open Code Review review my current changes
+```
+
+브랜치 비교:
+
+```text
+@Open Code Review review this branch against main
+```
+
+검토 후 안전한 항목만 수정:
+
+```text
+@Open Code Review review and fix high-confidence issues
+```
+
+## 내부적으로 실행되는 명령
+
+현재 workspace 변경사항 검토:
+
+```bash
+ocr review --audience agent
+```
+
+특정 commit 검토:
+
+```bash
+ocr review --audience agent --commit <sha>
+```
+
+브랜치 비교:
+
+```bash
+ocr review --audience agent --from <base-ref> --to <head-ref>
+```
+
+미리보기:
+
+```bash
+ocr review --preview
+```
+
+## 주의사항
+
+- 이 플러그인은 OpenAI Responses API endpoint를 설정하지 않습니다.
+- 이 플러그인은 `OPENAI_API_KEY`나 `gpt-5.1-codex-max` 설정을 요구하지 않습니다.
+- OCR 자체는 별도의 LLM 설정이 필요합니다.
+- 파일 수정은 사용자가 명시적으로 요청한 경우에만 수행합니다.
+- commit 생성은 사용자가 명시적으로 요청한 경우에만 수행합니다.

package/plugins/open-code-review/skills/open-code-review/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: open-code-review
+description: >
+  Performs AI-powered code review on Git changes using the `ocr` CLI from
+  alibaba/open-code-review. Use when the user asks to review code, review
+  a pull request, review staged/unstaged changes, review a commit, or
+  compare branches for code quality issues. Produces line-level review
+  comments and can automatically apply fixes when requested. With appropriate
+  review rules, can detect various types of issues including bugs, security
+  vulnerabilities, performance problems, and code quality concerns.
+license: Apache-2.0
+compatibility: >
+  Requires the `ocr` CLI installed (via `npm install -g
+  @alibaba-group/open-code-review` or GitHub release binary). Requires a
+  configured LLM (Anthropic or OpenAI-compatible) before first run.
+metadata:
+  author: alibaba
+  homepage: https://github.com/alibaba/open-code-review
+  version: "1.0.0"
+---
+
+# Open Code Review
+
+This Codex plugin skill intentionally mirrors the canonical skill at
+`skills/open-code-review/SKILL.md`. Keep both files synchronized when updating
+OCR agent instructions; a symlink is avoided because plugin installs may only
+materialize the plugin subtree.
+
+A skill for invoking [open-code-review](https://github.com/alibaba/open-code-review) (`ocr`) — an open-source AI code review CLI that reads Git diffs and generates structured, line-level review comments.
+
+## Prerequisites check
+
+Before starting a review, verify the environment:
+
+```bash
+# 1. Check the CLI is installed
+which ocr || echo "NOT INSTALLED"
+
+# 2. Verify LLM connectivity
+ocr llm test
+```
+
+If `ocr` is not installed, install it first:
+
+```bash
+npm install -g @alibaba-group/open-code-review
+```
+
+If `ocr llm test` fails, the user must configure an LLM. Guide them with one of these options:
+
+**Option A — Environment variables (highest priority, recommended for CI):**
+
+```bash
+export OCR_LLM_URL=https://api.anthropic.com/v1/messages
+export OCR_LLM_TOKEN=<api-key>
+export OCR_LLM_MODEL=claude-opus-4-6
+export OCR_USE_ANTHROPIC=true
+```
+
+**Option B — Persistent config:**
+
+```bash
+ocr config set llm.url https://api.anthropic.com/v1/messages
+ocr config set llm.auth_token <api-key>
+ocr config set llm.model claude-opus-4-6
+ocr config set llm.use_anthropic true
+```
+
+Stop here and ask the user to provide credentials — never invent or hardcode API keys.
+
+## Workflow
+
+### Step 1: Gather Business Context
+
+Analyze the review target (commits, branch, or changes) to extract concise business context. Pass this context via `--background` to improve review quality.
+
+### Step 2: Run Code Review
+
+Run the OCR command with appropriate flags. **Always pass business context via `--background`** when available:
+
+```bash
+ocr review --audience agent --background "business context here" [user-args]
+```
+
+**Argument handling:**
+
+- **Background context** (RECOMMENDED): use `--background "context"` or `-b "context"` to provide business context for better review quality
+- **Default** (no user arguments): reviews staged, unstaged, and untracked changes (workspace mode)
+- **Specific commit**: use `--commit` or `-c` to review a single commit against its parent
+- **Branch comparison**: use `--from <ref>` and `--to <ref>` to review diff between two refs
+- **Timeout**: default timeout is 10 minutes per file; adjust with `--timeout <minutes>`
+- **Concurrency**: default concurrency is 8 file workers; reduce with `--concurrency <n>` if rate limits are hit
+- **Preview mode**: use `--preview` or `-p` to preview which files will be reviewed without running the LLM
+- **Installation**: if `ocr` command is not found, install it by running `npm i -g @alibaba-group/open-code-review`
+
+**Common invocation patterns:**
+
+| User says | Command to run |
+|-----------|---------------|
+| "review my changes" / "review the working copy" | `ocr review --audience agent -b "context"` |
+| "review this PR" / "review feature branch" | `ocr review --audience agent -b "context" --from main --to <branch>` |
+| "review commit abc123" | `ocr review --audience agent -b "context" --commit abc123` |
+| "what would be reviewed?" (dry-run) | `ocr review --preview` |
+
+**Output mode:**
+
+- Always use `--audience agent` to suppress progress UI and emit only the final summary
+
+### Step 3: Classify and Report
+
+For each comment from the review output, classify by priority and report all issues to the user:
+
+- **High**: Obvious bugs, security issues, clear mistakes, or well-founded suggestions with precise fix proposals
+- **Medium**: Reasonable concerns but context-dependent, style/performance suggestions, or fixes that require manual implementation
+- **Low**: Likely false positives, lacking sufficient context, nitpicks, or meaningless suggestions
+
+Report all comments grouped by priority level.
+
+### Step 4: Fix
+
+Before applying fixes, check whether the user requested automatic fixes:
+
+- If the user explicitly requested "review and fix" or similar, proceed with automatic fixes
+- If the user only requested "review" without fix intent, ask for permission before applying any changes
+
+When fixing issues and suggestions:
+
+- Focus on High and Medium priority items
+- Apply fixes directly to the code when safe and well-defined
+- For complex fixes requiring manual intervention, clearly describe what needs to be done
+- Always verify fixes with the user before committing
+
+## Output Format
+
+Each comment contains:
+
+- `path`: File path
+- `content`: Review comment text
+- `start_line` / `end_line`: Line range (both 0 means positioning failed)
+- `suggestion_code`: Optional fix suggestion
+- `existing_code`: Optional original code snippet
+- `thinking`: Optional LLM reasoning process
+
+After filtering comments by priority, present results using this template:
+
+```markdown
+## Code Review Results
+
+**Files reviewed**: N
+**Issues found**: X high priority / Y medium priority
+
+### High Priority
+
+- **`path/to/file.java:42`** — Brief description
+  > Recommendation: How to fix
+
+### Medium Priority
+
+- **`path/to/file.ts:88`** — Brief description
+  > Recommendation: How to fix (if applicable)
+```
+
+If the review found no issues after filtering, simply state: "Review complete — no issues found in N files."
+
+**Priority classification:**
+
+- **High**: Obvious bugs, security issues, clear mistakes, or well-founded suggestions with precise fix proposals
+- **Medium**: Reasonable concerns but context-dependent, style/performance suggestions, or fixes that require manual implementation
+- **Low**: Discarded silently (likely false positives, lacking context, nitpicks, or meaningless suggestions)
+
+**Handling mispositioned comments:**
+
+When `start_line` and `end_line` are both `0`, the comment failed to locate the exact position in the file. In such cases:
+
+1. Read the comment content to understand the issue
+2. Examine the target file mentioned in the comment
+3. Identify the relevant code section based on the comment's context
+4. Apply the fix or suggestion to the correct location
+
+## Custom Review Rules
+
+If the user wants project-specific rules, OCR resolves them in this priority order:
+
+1. `--rule <path>` flag (highest)
+2. `<repo>/.opencodereview/rule.json`
+3. `~/.opencodereview/rule.json`
+4. Built-in system defaults (lowest)
+
+Rule file format:
+
+```json
+{
+  "rules": [
+    {
+      "path": "**/*.java",
+      "rule": "All new methods must validate required parameters for null"
+    },
+    {
+      "path": "**/*mapper*.xml",
+      "rule": "Check SQL for injection risks and missing closing tags"
+    }
+  ]
+}
+```
+
+To preview which rule applies to a file before reviewing:
+
+```bash
+ocr rules check src/main/java/com/example/Foo.java
+```
+
+## Gotchas
+
+- **LLM must be configured first** — `ocr review` will fail loudly if no LLM is reachable. Always run `ocr llm test` before the first review.
+- **Working directory matters** — `ocr review` operates on the Git repo at the current directory. Use `--repo /path/to/repo` to run from elsewhere.
+- **Untracked files are reviewed in workspace mode** — running bare `ocr review` includes staged, unstaged, *and* untracked changes. Stage selectively if you want narrower scope.
+- **Large diffs may hit token limits** — files with very large diffs may be truncated. The default `MAX_TOKENS` is 58888 per request.
+- **Plan phase triggers at 50 lines** — diffs exceeding 50 changed lines run an extra risk-analysis phase before main review. This adds latency but improves quality.
+- **Don't pass `--audience human`** — it streams progress UI that pollutes output. Always use `--audience agent`.
+- **Comment language follows config** — set `language` config to `English` or `Chinese` (default: Chinese) to control review comment language.
+
+## Validation
+
+After the review completes, verify success by checking:
+
+1. The command exited with code 0
+2. Comments were generated (or "No comments generated" message appears)
+3. Warnings (if any) are displayed in stderr
+
+If errors occurred, check the stderr warnings for details about which files failed and why.
+
+## References
+
+- Full docs: https://github.com/alibaba/open-code-review
+- NPM package: https://www.npmjs.com/package/@alibaba-group/open-code-review
+- Issue tracker: https://github.com/alibaba/open-code-review/issues