refactor(skill): upgrade open-code-review skill to modular structure with v1.9.1 features

skills/open-code-review/references/flags.md

@@ -0,0 +1,42 @@
+# Flag Reference
+
+## Shared Flags (review + scan)
+
+| Flag | Short | Default | Description |
+|------|-------|---------|-------------|
+| `--audience` | | `human` | `human` (progress UI) or `agent` (summary only). **Always use `agent`.** |
+| `--format` | `-f` | `text` | `text` or `json` |
+| `--background` | `-b` | `""` | Business context string |
+| `--rule` | | `""` | Path to custom rule.json |
+| `--repo` | | cwd | Git repository root directory |
+| `--exclude` | | `""` | Comma-separated gitignore-style exclude patterns |
+| `--concurrency` | | `8` | Maximum concurrent file worker count |
+| `--timeout` | | `10` | Per-file timeout in minutes |
+| `--max-tools` | | Template default | Maximum tool-call turns per file (review mode: min 10; scan mode: only takes effect when greater than template default) |
+| `--max-git-procs` | | `16` | Maximum concurrent git sub-processes |
+| `--max-tokens-budget` | | `0` (unlimited) | Token budget cap; outputs partial results gracefully if exceeded |
+| `--provider` | | Configured Provider | Per-run override for LLM Provider (e.g. `openai`, `anthropic`) |
+| `--model` | | Configured Model | Per-run override for LLM model |
+| `--max-tokens` | | `0` | Per-run override for per-file prompt token limit (0 = template/configured default) |
+| `--resume` | | `""` | Resumes an interrupted session ID (`scan` supports all; `review` requires `--from/--to` or `--commit`) |
+| `--tools` | | Built-in | Path to JSON tools configuration file |
+| `--preview` | `-p` | `false` | Dry-run: lists target files without invoking LLM (supports `--format json`) |
+
+## Review-Only Flags
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--from` | | Source ref in Range mode |
+| `--to` | | Target ref in Range mode |
+| `--commit` | `-c` | Single commit hash (compared against its parent) |
+| `--background-file` | `-B` | Markdown file path as business context (max 1 MB) |
+
+## Scan-Only Flags
+
+| Flag | Description |
+|------|-------------|
+| `--path` | Comma-separated directories/files |
+| `--batch` | `none` \| `by-language` \| `by-directory` |
+| `--no-plan` | Skip pre-review planning phase |
+| `--no-dedup` | Skip cross-file deduplication |
+| `--no-summary` | Skip repository-level summary |

skills/open-code-review/references/llm-config.md

@@ -0,0 +1,103 @@
+# Installation & LLM Configuration
+
+## Installation
+
+```bash
+npm install -g @alibaba-group/open-code-review
+# or via pnpm
+pnpm add -g @alibaba-group/open-code-review
+```
+
+## LLM Configuration
+
+If LLM connectivity fails or you need to switch providers:
+
+### Recommended: Interactive Configuration
+
+```bash
+ocr config provider
+```
+
+TUI guides provider selection, API key entry, model selection, and connectivity test.
+
+### Option: Environment Variables (Suitable for CI / Temporary Setup)
+
+```bash
+export OCR_LLM_URL=https://api.anthropic.com/v1/messages
+export OCR_LLM_TOKEN=<api-key>
+export OCR_LLM_MODEL=claude-opus-5
+export OCR_LLM_PROTOCOL=anthropic
+
+# Optional extended variables
+export OCR_LLM_AUTH_HEADER="Authorization: Bearer <api-key>"  # Custom auth header
+export OCR_LLM_EXTRA_HEADERS='{"X-Custom": "value"}'          # Extra request headers (JSON)
+export OCR_USE_ANTHROPIC=1                                    # Force Anthropic protocol (OCR_LLM_PROTOCOL takes priority)
+export OCR_LLM_TIMEOUT=120                                    # LLM request timeout (seconds)
+export OCR_CONFIG_PATH=/path/to/config.json                   # Custom config path (read-only commands only, e.g. ocr llm test)
+```
+
+Supported protocols: `anthropic`, `openai`, `openai-responses`.
+
+### Option: Per-Run CLI Overrides (No Global Config Modification Required)
+
+Override provider, model, or per-file token limit directly during execution:
+
+```bash
+ocr review --provider anthropic --model claude-opus-5 --max-tokens 200000 --audience agent --format json
+```
+
+Model names as listed by `ocr llm providers`.
+
+### Option: Persistent Configuration
+
+```bash
+# Recommended: provider-level config (active provider takes priority over legacy llm.*; having both emits a warning)
+ocr config set provider anthropic
+ocr config set providers.anthropic.api_key <api-key>
+ocr config set providers.anthropic.url https://api.anthropic.com/v1/messages
+ocr config set providers.anthropic.model claude-opus-5
+ocr config set providers.anthropic.protocol anthropic
+
+# Custom provider (e.g. OpenAI-compatible gateway)
+ocr config set custom_providers.my-gateway.url https://gateway.internal.com/v1
+ocr config set custom_providers.my-gateway.protocol openai
+ocr config set custom_providers.my-gateway.api_key <api-key>
+
+# Legacy llm.* keys
+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-5
+ocr config set llm.protocol anthropic
+
+# Advanced options (provider fields: api_key, url, protocol, model, models, auth_header, extra_body, extra_headers, retry_codes)
+ocr config set llm.retry_codes 403,400         # Add custom 4xx retry codes (4xx only; 408/409/429 and all 5xx are already retried by the SDK)
+ocr config set llm.timeout_sec 120             # LLM request timeout (seconds)
+ocr config set llm.auth_header "Bearer <key>"  # Custom auth header
+ocr config set llm.extra_headers '{"X-Custom": "v"}'  # Extra request headers (JSON object)
+ocr config set llm.extra_body '{"temperature": 0.1}'  # Extra request body fields (JSON object)
+ocr config set max_tokens 200000               # Per-file token limit
+```
+
+## Resolution Priority (High → Low)
+
+1. **CLI Flags** (`--provider` / `--model` / `--max-tokens`)
+2. **Configuration file** (`~/.opencodereview/config.json`) — checks active provider block, then legacy `llm.*` block
+3. **`OCR_LLM_*` environment variables**
+4. **Claude Code fallback** (`ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`)
+5. **Shell rc files** (parses `~/.zshrc`, `~/.bashrc`, `~/.bash_profile`, `~/.profile`)
+
+## Common Commands
+
+> **Do not run `ocr llm test` pre-emptively.** Run review/scan directly; use test commands only when troubleshooting errors.
+
+```bash
+ocr llm test          # Test LLM connectivity
+ocr llm providers     # List all built-in provider presets and available models
+ocr config provider   # Interactive provider configuration (TUI)
+ocr config model      # Interactive model selection (TUI)
+ocr config unset llm.url           # Remove a single config key
+ocr config unset custom_providers.my-gateway  # Remove an entire custom provider
+ocr config set language 中文       # Change review comment language (default: English)
+```
+
+**Never invent or hardcode API keys.** Stop and ask the user for credentials when missing.

skills/open-code-review/references/mcp.md

@@ -0,0 +1,53 @@
+# MCP Server Integration
+
+OCR review agents can invoke external MCP server tools (e.g. database schema lookup, API doc search) to enrich review context.
+
+## Configuration Examples
+
+```bash
+# stdio transport (sub-process)
+ocr config set mcp_servers.docs.type stdio
+ocr config set mcp_servers.docs.command npx
+ocr config set mcp_servers.docs.args '["@org/docs-mcp-server"]'
+
+# remote transport (Streamable HTTP)
+ocr config set mcp_servers.api.type remote
+ocr config set mcp_servers.api.url https://mcp.example.com/sse
+ocr config set mcp_servers.api.headers '{"Authorization": "Bearer $MCP_TOKEN"}'
+
+# Filter tools with allowlist
+ocr config set mcp_servers.docs.tools '["search_docs", "get_schema"]'
+
+# Remove server
+ocr config unset mcp_servers.docs
+```
+
+## Supported Fields
+
+| Field | Description |
+|-------|-------------|
+| `type` | `stdio` (default) or `remote` |
+| `command` | Sub-process command (stdio) |
+| `args` | JSON array of arguments (stdio) |
+| `env` | JSON array of `KEY=VALUE` (stdio) |
+| `url` | Service endpoint URL (remote; http/https only) |
+| `headers` | JSON object; values support `$ENV_VAR` expansion (remote) |
+| `tools` | JSON array allowlist filter |
+| `setup` | Shell command executed before startup (stdio) |
+
+## Behavioral Details
+
+- `headers` values must be non-empty (validated on `set`); an empty value after `$ENV_VAR` expansion fails at runtime.
+- MCP tools whose names collide with built-in tools are skipped with a warning; tools in the `tools` allowlist that do not exist on the server are also warned about.
+- `setup` runs in the repository root directory with a 5-minute timeout; on failure it prints an error and skips that server — the review proceeds without it.
+- Invalid JSON in `args` / `env` / `tools` / `headers` reports an error.
+
+## Built-in Tools
+
+MCP server tools are registered alongside the following built-in agent tools:
+
+- `file_read` — Reads file content with line ranges
+- `code_search` — Searches codebase with regex
+- `file_find` — Finds files by pattern
+- `file_read_diff` — Reads diff of other changed files
+- `code_comment` — Submits structured review comment

skills/open-code-review/references/rules.md

@@ -0,0 +1,46 @@
+# Custom Review Rules
+
+## Resolution Priority (High → Low)
+
+1. `--rule <path>` flag
+2. `<repo>/.opencodereview/rule.json` (Project-level)
+3. `~/.opencodereview/rule.json` (Global-level)
+4. Built-in system default rules
+
+## Rule File Format
+
+```json
+{
+  "rules": [
+    {
+      "path": "**/*.java",
+      "rule": "All new methods must validate required parameters for null",
+      "merge_system_rule": true
+    },
+    {
+      "path": "**/*.ts",
+      "rule": "rules/typescript-security.md"
+    }
+  ],
+  "include": ["src/**"],
+  "exclude": ["**/*.gen.*", "vendor/**"]
+}
+```
+
+- `rule` value: inline string OR file reference (`.md`, `.txt`, `.markdown`; max 512 KB)
+- `merge_system_rule: true`: merges with matching system rules (instead of replacing them)
+- `include`/`exclude`: top-level file filtering (gitignore-style glob, supports `**` and `{a,b}`)
+
+## Debugging Rule Matching
+
+```bash
+ocr rules check src/main/java/com/example/Foo.java
+```
+
+Displays effective rules, source hierarchy (Custom/Project/Global/System), and matched patterns.
+
+## Behavioral Details
+
+- **Case-insensitive matching**: `path` patterns and matched file paths are compared in lowercase.
+- **include/exclude take effect at a single level**: only the highest-priority layer that configures include/exclude is used (Custom > Project > Global); layers are not merged.
+- **File references are heuristic**: only a value that is a single line, contains no spaces, and has a supported extension (`.md`/`.txt`/`.markdown`) is treated as a file path; inline text containing spaces is treated as inline. Relative paths resolve against the repository root and cannot escape it. On read failure (missing/oversized/unsupported extension), the rule is emptied with a WARNING rather than an error.

skills/open-code-review/references/troubleshooting.md

@@ -0,0 +1,60 @@
+# Troubleshooting & Performance Tuning
+
+## Performance Tuning
+
+| Symptom | Action |
+|---------|--------|
+| Rate limit errors | Lower `--concurrency` to 2-4 |
+| Frequent 429 / 5xx errors | 429 and all 5xx are already retried by the SDK by default; if still failing, lower `--concurrency` or add custom 4xx retry codes (`ocr config set llm.retry_codes 403,400`) |
+| Excessive token cost | Set `--max-tokens-budget 500000` (or lower) |
+| Single large file truncated | Set `--max-tokens 200000` or `ocr config set max_tokens 200000` |
+| Large file timeouts | Increase `--timeout 20` |
+| Excessive agent tool turns | Set `--max-tools 15` |
+| Windows git overhead | Lower `--max-git-procs 8` |
+| Slow LLM response | Set `OCR_LLM_TIMEOUT=120` (seconds) |
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `ocr: command not found` | Not installed | Run `pnpm add -g @alibaba-group/open-code-review` |
+| `ocr llm test` fails | LLM not configured | Run `ocr config provider` or set environment variables |
+| Exit code ≠ 0 | Every selected item failed or run-level failure | Inspect the failure JSON on stderr; partial failures (`status: "partial"`) exit 0 — check `warnings` array |
+| `status: "partial"` | Partial file failures | Check warnings; run `--resume <id>` to retry failed files |
+| Token overflow | File diff too large | Use `--exclude`, set `--max-tokens` or `--max-tokens-budget` |
+| Rate limited | Concurrency too high | Lower `--concurrency` (429 is already retried by the SDK; `retry_codes` supports extra 4xx codes only) |
+| Wrong comment language | Default English | Run `ocr config set language 中文` |
+| Tool Output truncation / corrupted JSON | stdout exceeds the host agent's tool output buffer | **No need to re-run `ocr`**: use `ocr session comments <session-id> --severity high,critical --json`; or redirect to a file upfront (`ocr ... > result.json`) and read it with a file tool. Windows PowerShell: use `Out-File -Encoding utf8` instead of `>` (PowerShell 5 writes UTF-16) |
+| `--resume` fails | Review workspace mode | Review resume requires `--from/--to` or `--commit`; or use `scan --resume` |
+| `--preview` + `--resume` error | Mutually exclusive | Use one or the other |
+
+## Session Management
+
+Large reviews or full-file scans can be resumed after interruption (`scan` mode and `review` range/commit modes support resume; `review` workspace mode does not).
+
+```bash
+# List recent sessions
+ocr session list [--limit 10] [--json]
+
+# View session details
+ocr session show <session-id> [--json]
+
+# Extract and filter saved comments
+ocr session comments <session-id> [--json] [--severity critical,high] [--category security,bug]
+
+# Resume interrupted review or scan
+ocr review --audience agent --format json --resume <session-id>
+ocr scan --audience agent --format json --resume <session-id>
+```
+
+Resume reuses already completed file reviews and re-runs only failed or pending files.
+
+All `session` subcommands support `--repo <path>` to select the repository directory (default: current directory).
+
+## Session Viewer
+
+Launch Web UI to browse and replay review session history (supports comment tag filters & repository filters):
+
+```bash
+ocr viewer --addr localhost:5483
+```