diff --git a/pages/src/content/docs/en/configuration.md b/pages/src/content/docs/en/configuration.md index addbfe4..b8443cb 100644 --- a/pages/src/content/docs/en/configuration.md +++ b/pages/src/content/docs/en/configuration.md @@ -4,185 +4,43 @@ sidebar: order: 5 --- -## Endpoint resolution +The config file lives at `~/.opencodereview/config.json`. You have three ways +to edit it: -When `ocr review` or `ocr llm test` runs, it tries four sources **in order** -and uses the first one that yields a complete `(URL, token, model)` triple: +- **Interactive TUI** — `ocr config provider` / `ocr config model`, with guided menus. +- **Command line** — `ocr config set `, ideal for scripts and CI. +- **Manual edit (not recommended)** — the JSON file directly (it gets reformatted on the next `ocr config set` write). -| Priority | Source | What it reads | -|---|---|---| -| 1 | `~/.opencodereview/config.json` | If `provider` is set, resolves via the `providers`/`custom_providers` maps (provider-first; see [Built-in providers](#built-in-providers)). Only falls back to the legacy `llm` section when no provider is set. | -| 2 | OCR environment variables | `OCR_LLM_URL`, `OCR_LLM_TOKEN`, `OCR_LLM_MODEL`, `OCR_USE_ANTHROPIC`, `OCR_LLM_AUTH_HEADER`. | -| 3 | Claude Code environment variables | `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`. | -| 4 | Shell rc files | `export ANTHROPIC_*=…` lines parsed out of `~/.zshrc`, `~/.bashrc`, `~/.bash_profile`, `~/.profile`. | +## Configuring a model -For Claude Code-style sources, if `ANTHROPIC_BASE_URL` lacks a versioned -path (`/v1/...`), OCR appends `/v1/messages` automatically. - -If no strategy yields a complete triple, OCR exits with: - -``` -no valid LLM endpoint configured; one of OCR_LLM_URL/OCR_LLM_TOKEN/OCR_LLM_MODEL, -~/.opencodereview/config.json, or ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN/ -ANTHROPIC_MODEL must be set -``` - -> Resolution stops at the first source that **errors**, not just the first -> that's empty. In particular, if `provider` is set in `config.json` but the -> entry is misconfigured (unknown provider name, missing `api_key` with no -> env-var fallback, missing `model`, a custom provider lacking `url`/`protocol`), -> OCR exits with that error and does **not** fall through to the OCR env, -> Claude Code, or rc-file sources. To switch to env-based config, unset the -> `provider` key first. - -> Source priority means the **environment overrides nothing** when the -> config file is fully populated. To force the environment to win, either -> delete the relevant `llm.*` keys from `~/.opencodereview/config.json` or -> use `ocr config set` to switch to the new values. - -## `ocr config set` — managing `~/.opencodereview/config.json` - -```bash -ocr config set -``` - -`config set` mutates the file via key/value pairs with schema-aware -parsing. The interactive TUI commands `ocr config provider` and -`ocr config model` also write to the same file (see -[Interactive setup](#interactive-setup--ocr-config-provider--ocr-config-model)). -Recognised keys: - -| Key | Type | Notes | -|---|---|---| -| `provider` | string | Set the active provider (built-in name or custom). Switching provider clears the model. | -| `model` | string | Set the model for the active provider (stored under the provider entry, or top-level `model` if no provider is set). | -| `providers..` | varies | Per-provider fields for built-in providers: `api_key`, `url`, `protocol`, `model`, `models`, `auth_header`, `extra_body`. | -| `custom_providers..` | varies | Same fields as above, for custom (non-built-in) providers. Custom providers must set at least `url` and `protocol`. | -| `llm.url` | string | Endpoint URL. For Anthropic, full Messages URL like `https://api.anthropic.com/v1/messages`. For OpenAI-compatible, the chat-completions URL. | -| `llm.auth_token` | string | API key. Sent as `Authorization: Bearer …` (OpenAI) or, for the legacy Anthropic path, `Authorization: Bearer …` by default (the preset `anthropic` provider defaults to `x-api-key` instead). Use `x-api-key` only by explicitly setting `llm.auth_header`. | -| `llm.auth_header` | string | Auth header name (`x-api-key`, `authorization`, or `bearer`). Anthropic-only; required for some Anthropic setups that need `x-api-key`. | -| `llm.model` | string | Model name. A `[m]` suffix is stripped automatically. | -| `llm.use_anthropic` | boolean | `true` (default) → Anthropic Messages protocol. `false` → OpenAI Chat Completions. | -| `llm.extra_body` | JSON object | Vendor-specific request fields merged into every chat request body. Example: `'{"thinking":{"type":"disabled"}}'`. | -| `language` | string | Forwarded into a directive appended to the system prompt; defaults to `English` when unset. See [Choosing a language](#choosing-a-language). | -| `telemetry.enabled` | boolean | Master switch for OpenTelemetry export. Off by default. | -| `telemetry.exporter` | string | `console` or `otlp`. | -| `telemetry.otlp_endpoint` | string | OTLP collector address (e.g., `localhost:4317`). | -| `telemetry.content_logging` | boolean | Include LLM prompts / responses in exported event data. | - -Examples: - -```bash -ocr config set llm.url https://api.anthropic.com/v1/messages -ocr config set llm.auth_token sk-ant-xxxxxxxxxx -ocr config set llm.model claude-opus-4-6 -ocr config set llm.use_anthropic true -ocr config set llm.extra_body '{"thinking":{"type":"disabled"}}' -ocr config set language English -ocr config set telemetry.enabled true -ocr config set telemetry.exporter otlp -ocr config set telemetry.otlp_endpoint localhost:4317 - -# Provider-based setup (recommended) -ocr config set provider anthropic -ocr config set model claude-opus-4-6 -ocr config set providers.anthropic.api_key "$ANTHROPIC_API_KEY" - -# Custom (non-built-in) provider -ocr config set provider my-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.model llama-3-70b -ocr config set custom_providers.my-gateway.api_key "$MY_API_KEY" -``` - -Booleans accept anything Go's `strconv.ParseBool` accepts (`true`, `false`, -`1`, `0`, `t`, `f`, …). `llm.extra_body` must be valid JSON. - -## File schema reference - -After the commands above, `~/.opencodereview/config.json` looks like: - -```json -{ - "llm": { - "url": "https://api.anthropic.com/v1/messages", - "auth_token": "sk-ant-xxxxxxxxxx", - "auth_header": "x-api-key", - "model": "claude-opus-4-6", - "use_anthropic": true, - "extra_body": { - "thinking": { "type": "disabled" } - } - }, - "language": "English", - "telemetry": { - "enabled": true, - "exporter": "otlp", - "otlp_endpoint": "localhost:4317" - } -} -``` - -The provider-based form uses `provider`, `model`, `providers`, and -`custom_providers` instead of the legacy `llm` block: - -```json -{ - "provider": "anthropic", - "model": "claude-opus-4-6", - "providers": { - "anthropic": { - "api_key": "sk-ant-xxxxxxxxxx", - "model": "claude-opus-4-6" - } - }, - "custom_providers": { - "my-gateway": { - "url": "https://gateway.internal.com/v1", - "protocol": "openai", - "model": "llama-3-70b", - "models": ["llama-3-70b", "llama-3-8b"], - "api_key": "gw-xxxxxxxxxx", - "auth_header": "authorization" - } - }, - "language": "English" -} -``` - -When `provider` is set, the `providers`/`custom_providers` maps drive -resolution; the legacy `llm` section is ignored for that config. - -You can edit this file by hand if you prefer, but `ocr config set` will -remarshal with `" "` indent on the next write. - -## Interactive setup — `ocr config provider` / `ocr config model` - -For provider and model selection without typing keys, OCR ships two -interactive Bubble Tea TUIs that also mutate `~/.opencodereview/config.json`. +### Recommended: interactive setup ```bash ocr config provider +``` + +It lets you pick a built-in or custom provider, enter an API key, choose a model, saves everything to the config file, and then runs `ocr llm test` once to verify the endpoint. To switch models later: + +```bash ocr config model ``` -- `ocr config provider` — Interactive TUI for selecting a built-in or custom - provider, then entering URL / protocol / API key / model. Saves the choice - to config and runs `ocr llm test` automatically to verify the endpoint. - For built-in providers, the API key may be read from the provider's env var - (see [Built-in providers](#built-in-providers)) when not entered directly. - Selecting a manual configuration populates the legacy `llm.*` block instead. -- `ocr config model` — Interactive TUI for selecting a model from the current - provider's preset list, plus any user-added models stored under - `providers..models` / `custom_providers..models`. Requires a - provider to be set first (`ocr config provider`). +### Non-interactive setup (CI / no-TUI environments) -## Built-in providers +Write to the same config with `ocr config set`: -The following providers ship with OCR. Each has a preset `BaseURL`, -`Protocol`, and (where applicable) an API key environment variable used as a -fallback when `providers..api_key` is unset. +```bash +ocr config set provider anthropic +ocr config set model claude-opus-4-6 +ocr config set providers.anthropic.api_key sk-ant-xxxxxxxxxx +``` + +### Built-in providers + +The following providers ship with OCR, with the Base URL and protocol +preset — once selected, you only need to fill in the API key. If +`providers..api_key` is unset, OCR falls back to the corresponding +environment variable. | Name | Protocol | Base URL | API key env var | |---|---|---|---| @@ -200,84 +58,53 @@ fallback when `providers..api_key` is unset. | `minimax` | openai | `https://api.minimaxi.com/v1` | `MINIMAX_API_KEY` | | `baidu-qianfan` | openai | `https://qianfan.baidubce.com/v2` | `QIANFAN_API_KEY` | -Any other provider name is treated as custom and must be configured under -`custom_providers` with at least `url` and `protocol`. +### Custom providers -## Environment variable reference - -| Variable | Purpose | -|---|---| -| `OCR_LLM_URL` | Endpoint URL — same shape as `llm.url`. | -| `OCR_LLM_TOKEN` | API key — same as `llm.auth_token`. | -| `OCR_LLM_MODEL` | Model name. | -| `OCR_LLM_AUTH_HEADER` | Auth header name (`x-api-key`, `authorization`, or `bearer`). Anthropic-only; same as `llm.auth_header`. Defaults to `authorization` when unset. | -| `OCR_USE_ANTHROPIC` | Unset → Anthropic protocol (default). Set to `true` / `1` / `yes` (case-insensitive) → Anthropic. Set to anything else (`false`, `0`, `no`, typos, …) → OpenAI. | -| `ANTHROPIC_BASE_URL` | Claude Code-compatible base URL. | -| `ANTHROPIC_AUTH_TOKEN` | Claude Code-compatible API key. | -| `ANTHROPIC_MODEL` | Claude Code-compatible model. | -| `OCR_ENABLE_TELEMETRY` | `1` to enable telemetry from env. | -| `OTEL_SERVICE_NAME` | Override service name in spans/metrics. | -| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP collector address — also forces the exporter to `otlp`. | -| `OTEL_EXPORTER_OTLP_PROTOCOL` | OTLP transport protocol (`grpc`, `http/protobuf`, or `http/json`). Defaults to `grpc`. | -| `OCR_CONTENT_LOGGING` | `1` to include prompts/responses in telemetry events. | - -Per-provider API keys (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, -`DASHSCOPE_API_KEY`, …) are used as a fallback when a built-in provider's -`api_key` field is unset. See the [Built-in providers](#built-in-providers) -table for each provider's env var name. - -## Why `extra_body` exists - -Some hosted providers add non-standard fields to the request body (for -example, Bedrock-style `thinking`, vendor-specific `temperature_strategy`, -streaming options). `llm.extra_body` is merged into every outgoing request, -so you can ship those fields without patching the source. +Any provider name not in the table above is treated as custom and must +supply at least `url` and `protocol` (`protocol` is either `anthropic` or +`openai`): ```bash -ocr config set llm.extra_body '{"thinking":{"type":"enabled","budget_tokens":2048}}' +ocr config set provider my-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.model llama-3-70b +ocr config set custom_providers.my-gateway.api_key "$MY_API_KEY" ``` -## Choosing a language - -The `language` key controls one thing only: a directive appended to every -system-role message in the review and `ocr llm test` prompts. The exact -string injected is: - -``` -\n\nAlways respond in . -``` - -- *Unset* or empty — treated as `English`. -- `Chinese`, `English`, or any other string — passed through verbatim. - -There is no language switching on built-in rule docs. The files embedded -under `internal/config/rules/rule_docs/` are loaded by fixed filename and -are mostly written in Chinese (with `default.md` as an English exception); -they appear in the prompt as-is regardless of the `language` setting. When -`language` is `English`, the prompt therefore contains an English directive -on top of mostly-Chinese rule text — strong models honour the directive and -produce English comments, weaker models may emit mixed output. - -`language` has no environment-variable, CLI-flag, or per-project override — -the only place it can be set is the global `~/.opencodereview/config.json`, -via [`ocr config set`](#ocr-config-set--managing-opencodereviewconfigjson): +### Verify connectivity ```bash +ocr llm test +``` + +### Reuse existing environment variables + +If you already have Claude Code's `ANTHROPIC_*` or OCR's own `OCR_LLM_*` +environment variables configured, OCR picks them up automatically — no +config file needed. + +### Send vendor-specific fields + +Some providers require non-standard request fields (such as Bedrock-style +`thinking`). Use `extra_body` (merged into every request) to send them +without patching the source: + +```bash +ocr config set providers.anthropic.extra_body '{"thinking":{"type":"disabled"}}' +``` + +## Configuring the review language + +`language` determines which language review comments are written in; +it defaults to English when unset: + +```bash +ocr config set language 中文 ocr config set language English ``` -If you need fully English rule text, supply your own rules via `--rule`, -`/.opencodereview/rule.json`, or `~/.opencodereview/rule.json` (see -[Review Rules](../review-rules/#priority-chain)). - -## Per-project vs. global config - -The CLI itself is configured globally (`~/.opencodereview/config.json`) — -there is no project-local LLM config. **Review rules** *are* per-project, -however; see [Review Rules](../review-rules/#priority-chain). - ## See Also - [QuickStart](../quickstart/) — minimal setup and first review. - [CLI Reference](../cli-reference/) — every flag the review command accepts. -- [Telemetry](../telemetry/) — how to wire up OTLP / console exporters. diff --git a/pages/src/content/docs/en/faq.md b/pages/src/content/docs/en/faq.md index e00bce0..dbded44 100644 --- a/pages/src/content/docs/en/faq.md +++ b/pages/src/content/docs/en/faq.md @@ -19,7 +19,7 @@ no valid LLM endpoint configured; one of OCR_LLM_URL/OCR_LLM_TOKEN/OCR_LLM_MODEL ANTHROPIC_MODEL must be set ``` -OCR ran the four-source resolution chain ([Configuration](../configuration/#endpoint-resolution)) +OCR ran the full endpoint-resolution chain ([Configuration](../configuration/#reuse-existing-environment-variables)) and didn't find a complete `(URL, token, model)` triple. Either: - Run `ocr config set llm.url …` / `llm.auth_token …` / `llm.model …` diff --git a/pages/src/content/docs/en/installation.md b/pages/src/content/docs/en/installation.md index 908bb7c..36d57b3 100644 --- a/pages/src/content/docs/en/installation.md +++ b/pages/src/content/docs/en/installation.md @@ -4,46 +4,64 @@ sidebar: order: 4 --- -There are four supported ways to install the `ocr` CLI. They all produce -the same binary — pick whichever fits your environment. +There are four supported ways to install the `ocr` CLI. ## NPM (recommended) +#### Install + ```bash npm install -g @alibaba-group/open-code-review ``` -The NPM package ships a small wrapper script (`bin/ocr.js`) plus a -[postinstall hook](https://github.com/alibaba/open-code-review/blob/main/scripts/install.js) -that: - -1. Detects your platform (`darwin-amd64`, `darwin-arm64`, `linux-amd64`, - `linux-arm64`, `windows-amd64`, `windows-arm64`). -2. Downloads the matching binary from GitHub Releases. -3. Verifies it (when checksum data is present) and places it next to the - wrapper. - -If a platform-specific npm package (e.g. `@alibaba-group/ocr-darwin-arm64`) -is installed as an optional dependency, the binary is used directly and the -download is skipped. - -When you run `ocr`, the wrapper just `exec`s the downloaded binary, so the -overhead is effectively zero after first run. - -### Updating +Pin a specific version: ```bash -npm update -g @alibaba-group/open-code-review -# or pin a specific version: npm install -g @alibaba-group/open-code-review@ ``` -### Uninstalling +#### Updating + +When installed via NPM, `ocr` keeps itself up to date automatically by +default (the static binary opts out of this mechanism). On each `ocr` run, +the wrapper silently checks the registry for the latest version in the +background and upgrades automatically when an update is found, without +affecting the current review. There's an 18-minute cooldown between checks, +tunable with `OCR_UPDATE_INTERVAL` (minutes). + +To turn off auto-updates, set `OCR_NO_UPDATE` to any non-empty value: + +```bash +export OCR_NO_UPDATE=1 +``` + +#### Uninstalling ```bash npm uninstall -g @alibaba-group/open-code-review ``` +## Install script (curl | sh) + +A convenience installer that wraps the GitHub Release binary download +(with checksum verification) — handy for CI base images and headless +machines: + +```bash +curl -fsSL https://raw.githubusercontent.com/alibaba/open-code-review/main/install.sh | sh +``` + +It honours two environment variables: + +| Variable | Default | Purpose | +|---|---|---| +| `OCR_INSTALL_DIR` | `/usr/local/bin` | Where to place the `ocr` binary. | +| `OCR_VERSION` | latest release | Pin a specific release tag (e.g. `v1.2.3`). | + +The script supports `darwin` and `linux` on `amd64` / `arm64`; for +Windows, use the [GitHub Release binary](#github-release-binary) or +[NPM](#npm-recommended) path instead. + ## GitHub Release binary If you don't want Node.js, grab the static binary directly from the @@ -81,39 +99,18 @@ curl -LO https://github.com/alibaba/open-code-review/releases/latest/download/sh shasum -a 256 -c sha256sum.txt --ignore-missing ``` -## Install script (curl | sh) - -A convenience installer that wraps the GitHub Release binary download -(with checksum verification) — handy for CI base images and headless -machines: - -```bash -curl -fsSL https://raw.githubusercontent.com/alibaba/open-code-review/main/install.sh | sh -``` - -It honours two environment variables: - -| Variable | Default | Purpose | -|---|---|---| -| `OCR_INSTALL_DIR` | `/usr/local/bin` | Where to place the `ocr` binary. | -| `OCR_VERSION` | latest release | Pin a specific release tag (e.g. `v1.2.3`). | - -The script supports `darwin` and `linux` on `amd64` / `arm64`; for -Windows, use the [GitHub Release binary](#github-release-binary) or -[NPM](#npm-recommended) path instead. - ## Build from source You only need this path if you're hacking on OCR or running on a platform without a pre-built binary. -### Prerequisites +#### Prerequisites - [Go ≥ 1.25](https://go.dev/dl/) - [Git](https://git-scm.com/) - [Make](https://www.gnu.org/software/make/) -### Build +#### Build ```bash git clone https://github.com/alibaba/open-code-review.git @@ -122,7 +119,7 @@ make build # writes dist/opencodereview sudo cp dist/opencodereview /usr/local/bin/ocr ``` -### Build for another platform +#### Build for another platform ```bash make build-linux-amd64 @@ -139,7 +136,7 @@ make sha256sum # also produce sha256sum.txt file alongside the binaries — that's exactly what the release pipeline runs. -### Run tests +#### Run tests ```bash make test # LC_ALL=C go test -v -race -count=1 ./... @@ -170,7 +167,7 @@ echo $PATH | `~/.opencodereview/config.json` | LLM endpoint, language, telemetry config (managed by `ocr config set`). | | `~/.opencodereview/rule.json` | Optional global review rules. | | `~/.opencodereview/sessions//.jsonl` | Streaming JSONL transcript of every review session, used by `ocr viewer`. | -| `~/.opencodereview/{last-update-check,update.lock,update-available}` | NPM wrapper's background update-check state. The wrapper polls for a newer release (every ~18 min by default) and prints an upgrade hint. Disable with `OCR_NO_UPDATE=1`, or tune the interval with `OCR_UPDATE_INTERVAL` (seconds). Not written by the static binary. | +| `~/.opencodereview/{last-update-check,update.lock,update-available}` | NPM wrapper's background update-check state. The wrapper polls for a newer release (every ~18 min by default) and prints an upgrade hint. Disable with `OCR_NO_UPDATE=1`, or tune the interval with `OCR_UPDATE_INTERVAL` (minutes). Not written by the static binary. | | `/.opencodereview/rule.json` | Optional per-project review rules — safe to commit. | OCR never writes outside `~/.opencodereview/` (besides the transient binary diff --git a/pages/src/content/docs/en/quickstart.md b/pages/src/content/docs/en/quickstart.md index daac209..7ab60e3 100644 --- a/pages/src/content/docs/en/quickstart.md +++ b/pages/src/content/docs/en/quickstart.md @@ -4,156 +4,52 @@ sidebar: order: 3 --- -Install OCR, point it at any LLM that speaks the Anthropic Messages API or -the OpenAI Chat Completions API, and run your first code review. +Get your first code review running in a few minutes. ## Prerequisites -- A working **Git** install — OCR drives Git as a subprocess to read diffs. -- An **API key** for an Anthropic-compatible or OpenAI-compatible LLM. -- One of: - - **Node.js ≥ 18** (recommended; minimum supported: Node 14 — installs via NPM). - - Or just `curl` + `chmod` to drop the static binary into `$PATH`. - - Or **Go ≥ 1.25** if you prefer to build from source. +- **Git ≥ 2.41** +- **Node.js ≥ 18** +- **LLM API key** ## Step 1 — Install the CLI -### Option A: NPM (recommended) - ```bash npm install -g @alibaba-group/open-code-review +ocr version ``` -The NPM package installs a small wrapper that downloads the right binary for -your OS / architecture on install (via a postinstall hook). If the binary is -missing at run time, the wrapper errors out rather than downloading. After -install, you have a global `ocr` command: - -```bash -ocr --version -``` - -### Option B: GitHub Release binary - -Pick the binary for your platform from the -[releases page](https://github.com/alibaba/open-code-review/releases) and -drop it into your `$PATH`: - -```bash -# macOS (Apple Silicon) -curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-darwin-arm64 -chmod +x ocr && sudo mv ocr /usr/local/bin/ocr - -# macOS (Intel) -curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-darwin-amd64 -chmod +x ocr && sudo mv ocr /usr/local/bin/ocr - -# Linux x86_64 -curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-linux-amd64 -chmod +x ocr && sudo mv ocr /usr/local/bin/ocr - -# Linux ARM64 -curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-linux-arm64 -chmod +x ocr && sudo mv ocr /usr/local/bin/ocr - -# Windows (AMD64) -curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-amd64.exe - -# Windows (ARM64) -curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-arm64.exe -``` - -### Option C: Build from source - -```bash -git clone https://github.com/alibaba/open-code-review.git -cd open-code-review -make build -sudo cp dist/opencodereview /usr/local/bin/ocr -``` - -> See the [Installation](../installation/) page for details on each option, -> including how the NPM wrapper resolves the platform binary. +> See [Installation](../installation/) for more methods. ## Step 2 — Configure an LLM -OCR will refuse to run a review until it can resolve a complete LLM -endpoint (URL + token + model). It searches four sources in priority order: - -1. `~/.opencodereview/config.json` -2. OCR-specific environment variables (`OCR_LLM_*`) -3. Claude Code environment variables (`ANTHROPIC_*`) -4. `export ANTHROPIC_*` lines parsed out of your shell rc files - (`~/.zshrc`, `~/.bashrc`, `~/.bash_profile`, `~/.profile`) - -### Quickest path: `ocr config set` - ```bash -ocr config set llm.url https://api.anthropic.com/v1/messages -ocr config set llm.auth_token sk-ant-xxxxxxxxxx -ocr config set llm.model claude-opus-4-6 -ocr config set llm.use_anthropic true +ocr config provider ``` -These values are persisted to `~/.opencodereview/config.json`. - -### Alternative: environment variables - -Highest priority — useful in CI / containers where you don't want a config -file on disk: +It lets you pick a built-in or custom provider, enter an API key, choose a model, saves everything to the config file, and then runs `ocr llm test` once to verify the endpoint. To switch models later: ```bash -export OCR_LLM_URL=https://api.anthropic.com/v1/messages -export OCR_LLM_TOKEN=sk-ant-xxxxxxxxxx -export OCR_LLM_MODEL=claude-opus-4-6 -export OCR_USE_ANTHROPIC=true # default true; set false for OpenAI protocol +ocr config model ``` -### Already using Claude Code? +### Alternative: non-interactive command -OCR transparently picks up the same vars Claude Code uses, so no extra setup: +In CI or a no-TUI environment, write to the same config directly with `ocr config set`: ```bash -export ANTHROPIC_BASE_URL=https://api.anthropic.com -export ANTHROPIC_AUTH_TOKEN=sk-ant-xxxxxxxxxx -export ANTHROPIC_MODEL=claude-opus-4-6 +ocr config set provider anthropic +ocr config set model claude-opus-4-6 +ocr config set providers.anthropic.api_key sk-ant-xxxxxxxxxx ``` -If `ANTHROPIC_BASE_URL` lacks a versioned path, OCR appends `/v1/messages` -automatically. - -### Using an OpenAI-compatible endpoint? - -Set `llm.use_anthropic` to `false` (or `OCR_USE_ANTHROPIC=false`): - -```bash -ocr config set llm.url https://api.openai.com/v1/chat/completions -ocr config set llm.auth_token sk-xxxxxxxxxx -ocr config set llm.model gpt-4o -ocr config set llm.use_anthropic false -``` - -> See [Configuration](../configuration/) for the full key reference, -> including `llm.extra_body` for vendor-specific request fields and -> `language` for switching review-comment language. - ## Step 3 — Test connectivity ```bash ocr llm test ``` -Expected output (model name varies): - -``` -Source: OCR config file -URL: https://api.anthropic.com/v1/messages -Model: claude-opus-4-6 -Hello! … -``` - -If you instead get an error like `no valid LLM endpoint configured`, recheck -the config keys above. A 401 / 403 means the token is wrong or expired. +If you get an error like `no valid LLM endpoint configured`, recheck the Step 2 config. A 401 / 403 means the token is wrong or expired. ## Step 4 — Run your first review @@ -172,71 +68,28 @@ ocr review --from main --to feature-branch ocr review --commit abc123 ``` -You should see a stream of progress lines, finishing with one or more review -comments per file. +> See [CLI Reference](../cli-reference/) for the complete list of `ocr review` flags (concurrency tuning, output format, audience mode, background context, and more) plus every other sub-command. -> Workspace mode includes **untracked** files. If you only want to review -> what you've staged, `git add` selectively beforehand. - -> The three modes above are the basics. See [CLI Reference](../cli-reference/) -> for the complete list of `ocr review` flags — concurrency tuning, output -> format, audience mode, background context, and more — plus every other -> sub-command (`config`, `rules`, `llm test`, `viewer`). - -### Want to see what *would* be reviewed first? +### Want to see what would be reviewed first? ```bash -ocr review --preview # workspace -ocr review -c abc123 -p # commit +ocr review --preview # workspace +ocr review -c abc123 --preview # commit ``` -`--preview` runs every filter step but never calls the LLM, so it's free. -It prints the file list with each file's status (`added` / `modified` / -`deleted` / `renamed` / `binary`) and, for excluded files, the reason -(`binary`, `unsupported_ext`, `default_path`, `user_exclude`, `deleted`). +### JSON output for systems -### JSON output for tooling +`--audience agent` suppresses the human-friendly progress UI so the only thing on stdout is the JSON / final summary — exactly what an upstream agent or CI script wants. ```bash ocr review --format json --audience agent > review.json ``` -- `--format json` emits a machine-readable array of comments, each with - `path`, `content`, `start_line`, `end_line`, `existing_code`, - `suggestion_code` and optional `thinking`. -- `--audience agent` suppresses the human-friendly progress UI so the only - thing on stdout is the JSON / final summary — exactly what an upstream - agent or CI script wants. - -## Step 5 — Review the results - -Each comment includes: - -| Field | Meaning | -|---|---| -| `path` | File that the comment is about. | -| `content` | The review comment itself, in the configured `language`. | -| `start_line` / `end_line` | Line range in the **new** version of the file. Both `0` means OCR couldn't precisely position the comment — the issue is real but you'll need to find the exact spot yourself. | -| `existing_code` | The snippet from the diff the comment refers to. Used internally for line resolution; useful when `start_line` is `0`. | -| `suggestion_code` | Optional fix snippet. | -| `thinking` | Optional model reasoning. Only present for some models. | - -## Step 6 — Inspect a past session - -Every review is persisted to `~/.opencodereview/sessions/...` as a -JSONL transcript. Browse them in a local web UI: - -```bash -ocr viewer # http://localhost:5483 -ocr viewer --addr :3000 -``` - -> See [Session Viewer](../viewer/) for the full UI tour. - ## See Also +- [Installation](../installation/) — every install method and OCR's state directory. +- [Configuration](../configuration/) — every env var, config key, and built-in provider. - [CLI Reference](../cli-reference/) — every sub-command, flag, and output mode. - [Review Rules](../review-rules/) — customize what gets reviewed. - [Integrations](../integrations/) — embed OCR in Claude Code, an Agent skill, or CI. -- [Telemetry](../telemetry/) — ship traces and metrics over OTLP. - [FAQ](../faq/) — known errors and remedies. diff --git a/pages/src/content/docs/ja/configuration.md b/pages/src/content/docs/ja/configuration.md index a7db64b..f60f569 100644 --- a/pages/src/content/docs/ja/configuration.md +++ b/pages/src/content/docs/ja/configuration.md @@ -4,181 +4,43 @@ sidebar: order: 5 --- -## エンドポイントの解決 +設定ファイルは `~/.opencodereview/config.json` にあります。編集方法は 3 つあります。 -`ocr review` または `ocr llm test` が実行されると、4 つの来源を順に試し、 -完全な `(URL, token, model)` の三つ組を最初に返せた来源を使用します。 +- **インタラクティブ TUI** —— `ocr config provider` / `ocr config model`。ガイド付きメニューが表示されます。 +- **コマンドライン** —— `ocr config set `。スクリプトや CI に適しています。 +- **手動編集（非推奨）** —— この JSON ファイルを直接編集（次回の `ocr config set` 書き込み時に再フォーマットされます）。 -| 優先度 | 来源 | 読み取る内容 | -|---|---|---| -| 1 | `~/.opencodereview/config.json` | `provider` が設定されている場合は `providers`/`custom_providers` マッピングを通じて解決します（provider が優先。[組み込み provider](#built-in-providers) を参照）。provider が設定されていない場合にのみ、レガシーの `llm` セクションにフォールバックします。 | -| 2 | OCR 環境変数 | `OCR_LLM_URL`、`OCR_LLM_TOKEN`、`OCR_LLM_MODEL`、`OCR_USE_ANTHROPIC`、`OCR_LLM_AUTH_HEADER`。 | -| 3 | Claude Code 環境変数 | `ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_MODEL`。 | -| 4 | シェルの rc ファイル | `~/.zshrc`、`~/.bashrc`、`~/.bash_profile`、`~/.profile` から解析された `export ANTHROPIC_*=…` 行。 | +## モデルを設定する -Claude Code 風の来源については、`ANTHROPIC_BASE_URL` にバージョン付きのパス -（`/v1/...`）がない場合、OCR は自動的に `/v1/messages` を追加します。 - -いずれの戦略でも完全な三つ組が得られない場合、OCR は次のメッセージで終了します。 - -``` -no valid LLM endpoint configured; one of OCR_LLM_URL/OCR_LLM_TOKEN/OCR_LLM_MODEL, -~/.opencodereview/config.json, or ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN/ -ANTHROPIC_MODEL must be set -``` - -> 解決は、単に最初に空だった来源ではなく、最初に**エラーとなった**来源で停止します。特に注意してください。 -> `config.json` に `provider` が設定されているのにその項目の設定が誤っている場合（不明な provider 名、 -> 環境変数のフォールバックもなく `api_key` が欠落、`model` が欠落、カスタム provider の -> `url`/`protocol` が欠落）、OCR はそのエラーで終了し、OCR 環境変数、 -> Claude Code、rc ファイルの来源にフォールバックすることは**ありません**。環境変数ベースの設定に切り替えるには、まず -> `provider` key を解除してください。 - -> 来源の優先順位により、設定ファイルが完全に埋まっている場合、**環境変数はいかなる値も上書きしません**。 -> 環境変数を有効にするには、`~/.opencodereview/config.json` から該当する `llm.*` key を削除するか、 -> `ocr config set` で新しい値に切り替えてください。 - -## `ocr config set` ——`~/.opencodereview/config.json` を管理する - -```bash -ocr config set -``` - -`config set` は key/value ペアでファイルを変更し、schema を認識した解析を行います。インタラクティブな TUI -コマンド `ocr config provider` と `ocr config model` も同じファイルに書き込みます（ -[インタラクティブ設定](#interactive-setup--ocr-config-provider--ocr-config-model) を参照）。認識される -key： - -| Key | 型 | 説明 | -|---|---|---| -| `provider` | string | 現在の provider を設定します（組み込み名またはカスタム）。provider を切り替えると model がクリアされます。 | -| `model` | string | 現在の provider に model を設定します（provider 項目の下に保存。provider がない場合はトップレベルの `model` に保存）。 | -| `providers..` | varies | 組み込み provider のフィールドごとの設定：`api_key`、`url`、`protocol`、`model`、`models`、`auth_header`、`extra_body`。 | -| `custom_providers..` | varies | 同じフィールド。カスタム（非組み込み）provider 用。カスタム provider には少なくとも `url` と `protocol` を設定する必要があります。 | -| `llm.url` | string | エンドポイント URL。Anthropic では完全な Messages URL（例：`https://api.anthropic.com/v1/messages`）を使用します。OpenAI 互換では chat-completions URL を使用します。 | -| `llm.auth_token` | string | API key。`Authorization: Bearer …` として送信されます（OpenAI）。レガシーの Anthropic パスもデフォルトで `Authorization: Bearer …`（プリセットの `anthropic` provider ではデフォルトが `x-api-key` に変わります）。`llm.auth_header` を明示的に設定した場合にのみ `x-api-key` を使用します。 | -| `llm.auth_header` | string | Auth header 名（`x-api-key`、`authorization`、または `bearer`）。Anthropic のみで使用します。`x-api-key` を必要とする一部の Anthropic 設定で必須です。 | -| `llm.model` | string | モデル名。`[<数字>m]` サフィックスは自動的に除去されます。 | -| `llm.use_anthropic` | boolean | `true`（デフォルト）→ Anthropic Messages プロトコル。`false` → OpenAI Chat Completions。 | -| `llm.extra_body` | JSON object | ベンダー固有のリクエストフィールド。各 chat リクエストボディにマージされます。例：`'{"thinking":{"type":"disabled"}}'`。 | -| `language` | string | system prompt に追加される指示として転送されます。未設定の場合はデフォルトで `English`。[言語の選択](#choosing-a-language) を参照。 | -| `telemetry.enabled` | boolean | OpenTelemetry エクスポートのマスタースイッチ。デフォルトは無効。 | -| `telemetry.exporter` | string | `console` または `otlp`。 | -| `telemetry.otlp_endpoint` | string | OTLP collector のアドレス（例：`localhost:4317`）。 | -| `telemetry.content_logging` | boolean | エクスポートされるイベントデータに LLM の prompt / レスポンスを含めます。 | - -例： - -```bash -ocr config set llm.url https://api.anthropic.com/v1/messages -ocr config set llm.auth_token sk-ant-xxxxxxxxxx -ocr config set llm.model claude-opus-4-6 -ocr config set llm.use_anthropic true -ocr config set llm.extra_body '{"thinking":{"type":"disabled"}}' -ocr config set language English -ocr config set telemetry.enabled true -ocr config set telemetry.exporter otlp -ocr config set telemetry.otlp_endpoint localhost:4317 - -# provider ベースの設定（推奨） -ocr config set provider anthropic -ocr config set model claude-opus-4-6 -ocr config set providers.anthropic.api_key "$ANTHROPIC_API_KEY" - -# カスタム（非組み込み）provider -ocr config set provider my-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.model llama-3-70b -ocr config set custom_providers.my-gateway.api_key "$MY_API_KEY" -``` - -boolean は Go の `strconv.ParseBool` が受け付ける任意の形式（`true`、`false`、`1`、`0`、 -`t`、`f`……）を受け付けます。`llm.extra_body` は正しい JSON でなければなりません。 - -## ファイル schema リファレンス - -上記のコマンドを実行すると、`~/.opencodereview/config.json` は次のようになります。 - -```json -{ - "llm": { - "url": "https://api.anthropic.com/v1/messages", - "auth_token": "sk-ant-xxxxxxxxxx", - "auth_header": "x-api-key", - "model": "claude-opus-4-6", - "use_anthropic": true, - "extra_body": { - "thinking": { "type": "disabled" } - } - }, - "language": "English", - "telemetry": { - "enabled": true, - "exporter": "otlp", - "otlp_endpoint": "localhost:4317" - } -} -``` - -provider ベースの形式では、レガシーの `llm` ブロックではなく `provider`、`model`、`providers`、 -`custom_providers` を使用します。 - -```json -{ - "provider": "anthropic", - "model": "claude-opus-4-6", - "providers": { - "anthropic": { - "api_key": "sk-ant-xxxxxxxxxx", - "model": "claude-opus-4-6" - } - }, - "custom_providers": { - "my-gateway": { - "url": "https://gateway.internal.com/v1", - "protocol": "openai", - "model": "llama-3-70b", - "models": ["llama-3-70b", "llama-3-8b"], - "api_key": "gw-xxxxxxxxxx", - "auth_header": "authorization" - } - }, - "language": "English" -} -``` - -`provider` が設定されている場合、解決は `providers`/`custom_providers` マッピングによって駆動されます。この設定では -レガシーの `llm` セクションは無視されます。 - -このファイルを手動で編集することもできますが、次回の書き込み時に `ocr config set` が `" "` インデントで -再シリアライズします。 - -## インタラクティブ設定——`ocr config provider` / `ocr config model` - -provider と model を選択するために key を手動で入力する手間を省くため、OCR は 2 つのインタラクティブな Bubble Tea TUI を提供します。 -どちらも同様に `~/.opencodereview/config.json` を変更します。 +### 推奨：インタラクティブ設定 ```bash ocr config provider +``` + +組み込みまたはカスタムの provider を選択し、API key を入力し、model を選び、すべてを設定ファイルに保存したうえで、`ocr llm test` を 1 回実行してエンドポイントを検証します。あとで model を切り替えるには： + +```bash ocr config model ``` -- `ocr config provider`——組み込みまたはカスタムの provider を選択し、URL / protocol / - API key / model を入力するインタラクティブな TUI です。選択内容は config に保存され、自動的に `ocr llm test` を実行して - エンドポイントを検証します。組み込み provider の場合、直接入力しなければ API key はその provider の環境変数から - 読み取れます（[組み込み provider](#built-in-providers) を参照）。手動設定を選んだ場合は、レガシーの - `llm.*` ブロックに代わりに書き込みます。 -- `ocr config model`——現在の provider のプリセットリスト、および - `providers..models` / `custom_providers..models` の下でユーザーが追加した - model からモデルを選択するインタラクティブな TUI です。先に provider を設定しておく必要があります（`ocr config provider`）。 +### 非インタラクティブ設定（CI / TUI なし環境） -## 組み込み provider +`ocr config set` で同じ設定に書き込みます。 -以下の provider が OCR に同梱されています。それぞれにプリセットの `BaseURL`、`Protocol`、および -（該当する場合）`providers..api_key` が未設定のときにフォールバックとなる API key 環境変数があります。 +```bash +ocr config set provider anthropic +ocr config set model claude-opus-4-6 +ocr config set providers.anthropic.api_key sk-ant-xxxxxxxxxx +``` -| 名称 | Protocol | Base URL | API key 環境変数 | +### 組み込み provider + +以下の provider が OCR に同梱されており、Base URL とプロトコルがプリセット +されています——選択後は API key を入力するだけです。`providers..api_key` +が未設定の場合は、対応する環境変数に自動的にフォールバックします。 + +| 名称 | プロトコル | Base URL | API key 環境変数 | |---|---|---|---| | `anthropic` | anthropic | `https://api.anthropic.com` | `ANTHROPIC_API_KEY` | | `openai` | openai | `https://api.openai.com/v1` | `OPENAI_API_KEY` | @@ -194,78 +56,53 @@ ocr config model | `minimax` | openai | `https://api.minimaxi.com/v1` | `MINIMAX_API_KEY` | | `baidu-qianfan` | openai | `https://qianfan.baidubce.com/v2` | `QIANFAN_API_KEY` | -その他の provider 名はすべてカスタムとみなされ、`custom_providers` の下で設定する必要があり、少なくとも -`url` と `protocol` が必要です。 +### カスタム provider -## 環境変数リファレンス - -| 変数 | 用途 | -|---|---| -| `OCR_LLM_URL` | エンドポイント URL——`llm.url` と同形。 | -| `OCR_LLM_TOKEN` | API key——`llm.auth_token` と同じ。 | -| `OCR_LLM_MODEL` | モデル名。 | -| `OCR_LLM_AUTH_HEADER` | Auth header 名（`x-api-key`、`authorization`、または `bearer`）。Anthropic のみ。`llm.auth_header` と同じ。未設定の場合はデフォルトで `authorization`。 | -| `OCR_USE_ANTHROPIC` | 未設定 → Anthropic プロトコル（デフォルト）。`true` / `1` / `yes`（大文字小文字を区別しない）に設定 → Anthropic。その他の値（`false`、`0`、`no`、スペルミス……）に設定 → OpenAI。 | -| `ANTHROPIC_BASE_URL` | Claude Code 互換の base URL。 | -| `ANTHROPIC_AUTH_TOKEN` | Claude Code 互換の API key。 | -| `ANTHROPIC_MODEL` | Claude Code 互換の model。 | -| `OCR_ENABLE_TELEMETRY` | `1` で環境変数からテレメトリを有効化します。 | -| `OTEL_SERVICE_NAME` | span/metric の service name を上書きします。 | -| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP collector のアドレス——同時に exporter を `otlp` に強制します。 | -| `OTEL_EXPORTER_OTLP_PROTOCOL` | OTLP のトランスポートプロトコル（`grpc`、`http/protobuf`、または `http/json`）。デフォルトは `grpc`。 | -| `OCR_CONTENT_LOGGING` | `1` でテレメトリイベントに prompt/レスポンスを含めます。 | - -各 provider の API key（`ANTHROPIC_API_KEY`、`OPENAI_API_KEY`、 -`DASHSCOPE_API_KEY`……）は、組み込み provider の `api_key` フィールドが未設定のときにフォールバックとなります。 -各 provider の環境変数名は [組み込み provider](#built-in-providers) の表を参照してください。 - -## なぜ `extra_body` があるのか - -一部のホスト型 provider は、リクエストボディに非標準のフィールドを追加します（例：Bedrock 風の `thinking`、 -ベンダー固有の `temperature_strategy`、ストリーミングオプション）。`llm.extra_body` は発行される各リクエストに -マージされるため、ソースコードを変更せずにこれらのフィールドを送信できます。 +上記の表にない provider 名はすべてカスタムとみなされ、少なくとも `url` と +`protocol` を指定する必要があります（`protocol` は `anthropic` または +`openai`）。 ```bash -ocr config set llm.extra_body '{"thinking":{"type":"enabled","budget_tokens":2048}}' +ocr config set provider my-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.model llama-3-70b +ocr config set custom_providers.my-gateway.api_key "$MY_API_KEY" ``` -## 言語の選択 - -`language` key は 1 つのことだけを制御します。それは、レビューと `ocr llm test` の prompt 内の各 -system-role メッセージに追加される 1 つの指示です。注入される正確な文字列は次のとおりです。 - -``` -\n\nAlways respond in . -``` - -- *未設定* または空——`English` として扱われます。 -- `Chinese`、`English`、またはその他任意の文字列——そのまま透過されます。 - -組み込みの rule docs は言語の切り替えをサポートしません。`internal/config/rules/rule_docs/` の下に埋め込まれたファイルは -固定のファイル名で読み込まれ、ほとんどが中国語で書かれています（`default.md` は英語の例外）。`language` -の設定にかかわらず、それらはそのまま prompt に現れます。したがって `language` を `English` に設定した場合、prompt -には英語の指示と大量の中国語の rule テキストが重なります——強力なモデルは指示に従って英語のコメントを生成し、 -弱いモデルは中国語と英語が混在した内容を出力する可能性があります。 - -`language` には環境変数、CLI 引数、プロジェクトレベルの上書きがありません——設定できる唯一の場所はグローバルな -`~/.opencodereview/config.json` で、 -[`ocr config set`](#ocr-config-set--managing-opencodereviewconfigjson) を通じて設定します。 +### 接続性を検証する ```bash +ocr llm test +``` + +### 既存の環境変数を再利用する + +Claude Code の `ANTHROPIC_*` や OCR 独自の `OCR_LLM_*` 環境変数をすでに +設定している場合、OCR はそれらを自動的に認識するため、設定ファイルを書く +必要はありません。 + +### ベンダー固有のフィールドを送信する + +一部の provider は非標準のリクエストフィールド（Bedrock 風の `thinking` など）を +必要とします。`extra_body`（各リクエストにマージされます）を使えば、ソースコードを +変更せずにそれらを送信できます。 + +```bash +ocr config set providers.anthropic.extra_body '{"thinking":{"type":"disabled"}}' +``` + +## レビュー言語を設定する + +`language` はレビューコメントをどの言語で出力するかを決めます。未設定の場合は +デフォルトで英語になります。 + +```bash +ocr config set language 中文 ocr config set language English ``` -純粋な英語の rule テキストが必要な場合は、`--rule`、`/.opencodereview/rule.json`、 -または `~/.opencodereview/rule.json` を通じて独自のルールを提供してください（ -[レビュールール](../review-rules/#priority-chain) を参照）。 - -## プロジェクトレベル vs グローバル設定 - -CLI 自体はグローバルに設定されます（`~/.opencodereview/config.json`）——プロジェクトレベルの LLM 設定はありません。 -ただし**レビュールール**はプロジェクトレベルです。[レビュールール](../review-rules/#priority-chain) を参照してください。 - ## 関連項目 - [クイックスタート](../quickstart/)——最小限のセットアップと初回のレビュー。 - [CLI リファレンス](../cli-reference/)——review コマンドが受け入れる各引数。 -- [テレメトリ](../telemetry/)——OTLP / console exporter への接続方法。 diff --git a/pages/src/content/docs/ja/faq.md b/pages/src/content/docs/ja/faq.md index 9def2c0..b2d541a 100644 --- a/pages/src/content/docs/ja/faq.md +++ b/pages/src/content/docs/ja/faq.md @@ -18,7 +18,7 @@ no valid LLM endpoint configured; one of OCR_LLM_URL/OCR_LLM_TOKEN/OCR_LLM_MODEL ANTHROPIC_MODEL must be set ``` -OCR は 4 つのソースからなる解決チェーン（[設定](../configuration/#endpoint-resolution)）を +OCR はエンドポイント解決チェーン全体（[設定](../configuration/#既存の環境変数を再利用する)）を たどりましたが、完全な `(URL, token, model)` の三つ組を見つけられませんでした。次のいずれかを 行ってください。 diff --git a/pages/src/content/docs/ja/installation.md b/pages/src/content/docs/ja/installation.md index 9230e7e..7abc977 100644 --- a/pages/src/content/docs/ja/installation.md +++ b/pages/src/content/docs/ja/installation.md @@ -4,44 +4,62 @@ sidebar: order: 4 --- -`ocr` CLI をインストールするには、サポートされた 4 つの方法があります。いずれも生成されるのは同じバイナリなので、 -環境に合わせて選んでください。 +`ocr` CLI をインストールするには、サポートされた 4 つの方法があります。 ## NPM（推奨） +#### インストール + ```bash npm install -g @alibaba-group/open-code-review ``` -NPM パッケージには、小さな wrapper スクリプト（`bin/ocr.js`）と -[postinstall hook](https://github.com/alibaba/open-code-review/blob/main/scripts/install.js) -が付属しており、以下を行います。 - -1. お使いのプラットフォームを検出します（`darwin-amd64`、`darwin-arm64`、`linux-amd64`、 - `linux-arm64`、`windows-amd64`、`windows-arm64`）。 -2. GitHub Releases から一致するバイナリをダウンロードします。 -3. （チェックサムデータが存在する場合は）検証し、wrapper の隣に配置します。 - -プラットフォーム固有の npm パッケージ（例：`@alibaba-group/ocr-darwin-arm64`）が -optional dependency としてインストールされている場合は、そのバイナリを直接使用し、ダウンロードをスキップします。 - -`ocr` を実行すると、wrapper はダウンロード済みのバイナリを単に `exec` するだけなので、初回実行後の実際のオーバーヘッド -はゼロです。 - -### 更新 +特定のバージョンに固定： ```bash -npm update -g @alibaba-group/open-code-review -# または特定のバージョンに固定： npm install -g @alibaba-group/open-code-review@ ``` -### アンインストール +#### 更新 + +NPM 経由でインストールした場合、`ocr` はデフォルトで自動的に最新の状態を保ちます +（静的バイナリはこのメカニズムの対象外です）。`ocr` を実行するたびに、wrapper は +バックグラウンドで registry の最新バージョンを静かにチェックし、更新が見つかると +今回のレビューに影響を与えることなく自動的にアップグレードします。チェックの間には +18 分のクールダウンがあり、`OCR_UPDATE_INTERVAL`（分）で調整できます。 + +自動更新をオフにするには、`OCR_NO_UPDATE` に空でない任意の値を設定します。 + +```bash +export OCR_NO_UPDATE=1 +``` + +#### アンインストール ```bash npm uninstall -g @alibaba-group/open-code-review ``` +## インストールスクリプト（curl | sh） + +GitHub Release バイナリのダウンロード（検証付き）をラップした便利なインストーラーです——CI のベース +イメージやヘッドレス環境に適しています。 + +```bash +curl -fsSL https://raw.githubusercontent.com/alibaba/open-code-review/main/install.sh | sh +``` + +2 つの環境変数を認識します。 + +| 変数 | デフォルト値 | 用途 | +|---|---|---| +| `OCR_INSTALL_DIR` | `/usr/local/bin` | `ocr` バイナリを配置する場所。 | +| `OCR_VERSION` | 最新 release | 特定の release tag に固定します（例：`v1.2.3`）。 | + +このスクリプトは `darwin` と `linux` の `amd64` / `arm64` をサポートします。Windows では +[GitHub Release バイナリ](#github-release-binary) または [NPM](#npm-recommended) +の方法を使用してください。 + ## GitHub Release バイナリ Node.js をインストールしたくない場合は、 @@ -79,37 +97,17 @@ curl -LO https://github.com/alibaba/open-code-review/releases/latest/download/sh shasum -a 256 -c sha256sum.txt --ignore-missing ``` -## インストールスクリプト（curl | sh） - -GitHub Release バイナリのダウンロード（検証付き）をラップした便利なインストーラーです——CI のベース -イメージやヘッドレス環境に適しています。 - -```bash -curl -fsSL https://raw.githubusercontent.com/alibaba/open-code-review/main/install.sh | sh -``` - -2 つの環境変数を認識します。 - -| 変数 | デフォルト値 | 用途 | -|---|---|---| -| `OCR_INSTALL_DIR` | `/usr/local/bin` | `ocr` バイナリを配置する場所。 | -| `OCR_VERSION` | 最新 release | 特定の release tag に固定します（例：`v1.2.3`）。 | - -このスクリプトは `darwin` と `linux` の `amd64` / `arm64` をサポートします。Windows では -[GitHub Release バイナリ](#github-release-binary) または [NPM](#npm-recommended) -の方法を使用してください。 - ## ソースからビルドする OCR 自体を変更する場合、またはプリコンパイル済みバイナリのないプラットフォームで実行する場合にのみ、この方法が必要です。 -### 前提条件 +#### 前提条件 - [Go ≥ 1.25](https://go.dev/dl/) - [Git](https://git-scm.com/) - [Make](https://www.gnu.org/software/make/) -### ビルド +#### ビルド ```bash git clone https://github.com/alibaba/open-code-review.git @@ -118,7 +116,7 @@ make build # dist/opencodereview を生成 sudo cp dist/opencodereview /usr/local/bin/ocr ``` -### 他のプラットフォーム向けにビルドする +#### 他のプラットフォーム向けにビルドする ```bash make build-linux-amd64 @@ -134,7 +132,7 @@ make sha256sum # sha256sum.txt も生成 `make dist` は `clean → build-all → sha256sum` を実行し、バイナリの隣に `VERSION` ファイルを書き込みます——これはまさに release パイプラインが実行するステップです。 -### テストの実行 +#### テストの実行 ```bash make test # LC_ALL=C go test -v -race -count=1 ./... @@ -164,7 +162,7 @@ echo $PATH | `~/.opencodereview/config.json` | LLM エンドポイント、言語、テレメトリ設定（`ocr config set` で管理）。 | | `~/.opencodereview/rule.json` | オプションのグローバルレビュールール。 | | `~/.opencodereview/sessions//.jsonl` | レビューセッションごとのストリーミング JSONL トランスクリプト。`ocr viewer` で使用します。 | -| `~/.opencodereview/{last-update-check,update.lock,update-available}` | NPM wrapper のバックグラウンド更新チェックの状態。wrapper はより新しい release があるかをポーリングし（デフォルトで約 18 分ごと）、アップグレードの案内を表示します。`OCR_NO_UPDATE=1` で無効化するか、`OCR_UPDATE_INTERVAL`（秒）で間隔を調整します。静的バイナリはこれらのファイルを書き込みません。 | +| `~/.opencodereview/{last-update-check,update.lock,update-available}` | NPM wrapper のバックグラウンド更新チェックの状態。wrapper はより新しい release があるかをポーリングし（デフォルトで約 18 分ごと）、アップグレードの案内を表示します。`OCR_NO_UPDATE=1` で無効化するか、`OCR_UPDATE_INTERVAL`（分）で間隔を調整します。静的バイナリはこれらのファイルを書き込みません。 | | `/.opencodereview/rule.json` | オプションのプロジェクトレベルのレビュールール——安全にコミットできます。 | OCR は `~/.opencodereview/` の外に書き込むことは決してありません（NPM が一時的にバイナリをダウンロードする場合を除く）。 diff --git a/pages/src/content/docs/ja/quickstart.md b/pages/src/content/docs/ja/quickstart.md index 759fbbb..a29e594 100644 --- a/pages/src/content/docs/ja/quickstart.md +++ b/pages/src/content/docs/ja/quickstart.md @@ -4,232 +4,92 @@ sidebar: order: 3 --- -OCR をインストールし、Anthropic Messages API または OpenAI Chat Completions API -に対応した任意の LLM に接続して、初回のコードレビューを実行しましょう。 +数分で初回のコードレビューを実行できます。 ## 前提条件 -- 動作する **Git** のインストール——OCR は Git をサブプロセスとして駆動し diff を読み取ります。 -- Anthropic または OpenAI 互換の LLM の **API key**。 -- 以下のいずれか： - - **Node.js ≥ 18**（推奨。最低サポートは Node 14——NPM 経由でインストール）。 - - または `curl` + `chmod` だけで静的バイナリを `$PATH` に配置。 - - またはソースからビルドしたい場合は **Go ≥ 1.25**。 +- **Git ≥ 2.41** +- **Node.js ≥ 18** +- **LLM API key** -## ステップ 1——CLI をインストールする - -### 方法 A：NPM（推奨） +## ステップ 1 —— CLI をインストールする ```bash npm install -g @alibaba-group/open-code-review +ocr version ``` -NPM パッケージは小さな wrapper をインストールし、インストール時に（postinstall hook を通じて）お使いの -OS / アーキテクチャ向けの正しいバイナリをダウンロードします。実行時にバイナリが存在しない場合、wrapper はエラーを出し、 -ダウンロードは行いません。インストール後、グローバルな `ocr` コマンドが利用できます。 +> その他の方法は [インストール](../installation/) を参照してください。 + +## ステップ 2 —— LLM を設定する ```bash -ocr --version +ocr config provider ``` -### 方法 B：GitHub Release バイナリ - -[releases ページ](https://github.com/alibaba/open-code-review/releases) -から対応プラットフォームのバイナリを選び、`$PATH` に配置します。 +組み込みまたはカスタムの provider を選択し、API key を入力し、model を選び、すべてを設定ファイルに保存したうえで、`ocr llm test` を 1 回実行してエンドポイントを検証します。あとで model を切り替えるには： ```bash -# macOS (Apple Silicon) -curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-darwin-arm64 -chmod +x ocr && sudo mv ocr /usr/local/bin/ocr - -# macOS (Intel) -curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-darwin-amd64 -chmod +x ocr && sudo mv ocr /usr/local/bin/ocr - -# Linux x86_64 -curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-linux-amd64 -chmod +x ocr && sudo mv ocr /usr/local/bin/ocr - -# Linux ARM64 -curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-linux-arm64 -chmod +x ocr && sudo mv ocr /usr/local/bin/ocr - -# Windows (AMD64) -curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-amd64.exe - -# Windows (ARM64) -curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-arm64.exe +ocr config model ``` -### 方法 C：ソースからビルドする +### 代替方法：非インタラクティブコマンド + +CI や TUI のない環境では、`ocr config set` で同じ設定に直接書き込みます。 ```bash -git clone https://github.com/alibaba/open-code-review.git -cd open-code-review -make build -sudo cp dist/opencodereview /usr/local/bin/ocr +ocr config set provider anthropic +ocr config set model claude-opus-4-6 +ocr config set providers.anthropic.api_key sk-ant-xxxxxxxxxx ``` -> 各インストール方法の詳細は [インストール](../installation/) を参照してください。NPM wrapper が -> プラットフォームバイナリをどのように解決するかも含まれています。 - -## ステップ 2——LLM を設定する - -完全な LLM エンドポイント（URL + token + model）を解決できるまで、OCR はレビューの実行を拒否します。 -以下の優先順位で 4 つの来源を探索します。 - -1. `~/.opencodereview/config.json` -2. OCR 専用の環境変数（`OCR_LLM_*`） -3. Claude Code の環境変数（`ANTHROPIC_*`） -4. シェルの rc ファイル（`~/.zshrc`、`~/.bashrc`、`~/.bash_profile`、 - `~/.profile`）から解析された `export ANTHROPIC_*` 行 - -### 最速の経路：`ocr config set` - -```bash -ocr config set llm.url https://api.anthropic.com/v1/messages -ocr config set llm.auth_token sk-ant-xxxxxxxxxx -ocr config set llm.model claude-opus-4-6 -ocr config set llm.use_anthropic true -``` - -これらの値は `~/.opencodereview/config.json` に永続化されます。 - -### 代替方法：環境変数 - -優先度が最も高く、ディスクに設定ファイルを残したくない CI / コンテナに適しています。 - -```bash -export OCR_LLM_URL=https://api.anthropic.com/v1/messages -export OCR_LLM_TOKEN=sk-ant-xxxxxxxxxx -export OCR_LLM_MODEL=claude-opus-4-6 -export OCR_USE_ANTHROPIC=true # デフォルトは true。false にすると OpenAI プロトコルを使用 -``` - -### すでに Claude Code を使っている場合 - -OCR は Claude Code が使用するのと同じ変数群を自動的に読み取るため、追加の設定は不要です。 - -```bash -export ANTHROPIC_BASE_URL=https://api.anthropic.com -export ANTHROPIC_AUTH_TOKEN=sk-ant-xxxxxxxxxx -export ANTHROPIC_MODEL=claude-opus-4-6 -``` - -`ANTHROPIC_BASE_URL` にバージョン付きのパスがない場合、OCR は自動的に -`/v1/messages` を追加します。 - -### OpenAI 互換エンドポイントを使う場合 - -`llm.use_anthropic` を `false` に設定します（または `OCR_USE_ANTHROPIC=false`）。 - -```bash -ocr config set llm.url https://api.openai.com/v1/chat/completions -ocr config set llm.auth_token sk-xxxxxxxxxx -ocr config set llm.model gpt-4o -ocr config set llm.use_anthropic false -``` - -> 完全な key のリファレンスは [設定](../configuration/) を参照してください。ベンダー固有のリクエストフィールド -> 用の `llm.extra_body` や、レビューコメントの言語を切り替える `language` も含まれています。 - -## ステップ 3——接続性をテストする +## ステップ 3 —— 接続性をテストする ```bash ocr llm test ``` -期待される出力（モデル名は異なります）： +`no valid LLM endpoint configured` のようなエラーが出た場合は、ステップ 2 の設定を再確認してください。401 / 403 は token が誤っているか期限切れであることを示します。 -``` -Source: OCR config file -URL: https://api.anthropic.com/v1/messages -Model: claude-opus-4-6 -Hello! … -``` - -代わりに `no valid LLM endpoint configured` のようなエラーが出た場合は、上記の -設定 key を再確認してください。401 / 403 は token が誤っているか期限切れであることを示します。 - -## ステップ 4——初回のレビューを実行する +## ステップ 4 —— 初回のレビューを実行する 任意の Git リポジトリに移動して実行します。 ```bash cd path/to/your-repo -# ワークスペースモード——staged + unstaged + untracked の変更をレビュー（デフォルト） +# ワークスペースモード —— staged + unstaged + untracked の変更をレビュー（デフォルト） ocr review -# ブランチ区間——`main..feature-branch` をレビュー +# ブランチ区間 —— `main..feature-branch` をレビュー ocr review --from main --to feature-branch -# 単一 commit——その commit が導入した diff をレビュー +# 単一 commit —— その commit が導入した diff をレビュー ocr review --commit abc123 ``` -進捗情報が継続的に出力され、最後に各ファイルに 1 つ以上のレビューコメントが表示されます。 +> `ocr review` の完全な引数（並行数のチューニング、出力形式、audience モード、背景コンテキストなど）と、その他すべてのサブコマンドは [CLI リファレンス](../cli-reference/) を参照してください。 -> ワークスペースモードには **untracked** ファイルが含まれます。すでにステージされた内容だけをレビューしたい場合は、まず -> `git add` で選択的にステージしてください。 - -> 上記の 3 つは基本的な使い方です。`ocr review` の完全な引数（並行数のチューニング、出力形式、 -> audience モード、背景コンテキストなど）と、その他すべてのサブコマンド（`config`、`rules`、 -> `llm test`、`viewer`）は [CLI リファレンス](../cli-reference/) を参照してください。 - -### 先に *何が* レビューされるか見てみたい場合 +### 先に何がレビューされるか見てみたい場合 ```bash -ocr review --preview # ワークスペース -ocr review -c abc123 -p # commit +ocr review --preview # ワークスペース +ocr review -c abc123 --preview # commit ``` -`--preview` は各フィルタステップを実行しますが LLM は一切呼び出さないため、token を消費しません。ファイルリストと -各ファイルのステータス（`added` / `modified` / `deleted` / `renamed` / `binary`）を出力し、 -除外されたファイルについてはその理由（`binary`、`unsupported_ext`、`default_path`、 -`user_exclude`、`deleted`）も示します。 +### システム向けの JSON 出力 -### ツール向けの JSON 出力 +`--audience agent` は人間向けの進捗 UI を抑制し、stdout を JSON / 最終サマリーだけにします —— 上流の agent や CI スクリプトが必要とするものです。 ```bash ocr review --format json --audience agent > review.json ``` -- `--format json` は機械可読なコメント配列を出力します。各コメントには `path`、`content`、 - `start_line`、`end_line`、`existing_code`、`suggestion_code`、およびオプションの - `thinking` が含まれます。 -- `--audience agent` は人間向けの進捗 UI を抑制し、stdout を JSON / 最終 - サマリーだけにします——上流の agent や CI スクリプトが必要とするものです。 - -## ステップ 5——結果を確認する - -各コメントには以下が含まれます。 - -| フィールド | 意味 | -|---|---| -| `path` | そのコメントが対象とするファイル。 | -| `content` | レビューコメント本体。設定された `language` を使用します。 | -| `start_line` / `end_line` | ファイルの **新しい** バージョンにおける行範囲。両方が `0` の場合は OCR がコメントを正確に配置できなかったことを意味します——問題は本物ですが、正確な位置は自分で特定する必要があります。 | -| `existing_code` | コメントが指す diff の断片。内部的に行解決に使われます。`start_line` が `0` のときに役立ちます。 | -| `suggestion_code` | オプションの修正断片。 | -| `thinking` | オプションのモデルの推論。一部のモデルにのみ存在します。 | - -## ステップ 6——過去のセッションを閲覧する - -各レビューは JSONL トランスクリプトとして -`~/.opencodereview/sessions/...` に永続化されます。ローカルの Web UI でそれらを閲覧できます。 - -```bash -ocr viewer # http://localhost:5483 -ocr viewer --addr :3000 -``` - -> UI の完全な紹介は [セッションビューア](../viewer/) を参照してください。 - ## 関連項目 -- [CLI リファレンス](../cli-reference/)——各サブコマンド、引数、出力モード。 -- [レビュールール](../review-rules/)——レビュー内容をカスタマイズします。 -- [インテグレーション](../integrations/)——OCR を Claude Code、Agent skill、CI に組み込みます。 -- [テレメトリ](../telemetry/)——OTLP 経由で trace と metrics を送信します。 -- [FAQ](../faq/)——既知のエラーと対策。 +- [インストール](../installation/) —— すべてのインストール方法と OCR の状態ディレクトリ。 +- [設定](../configuration/) —— 各環境変数、config key、組み込み provider。 +- [CLI リファレンス](../cli-reference/) —— 各サブコマンド、引数、出力モード。 +- [レビュールール](../review-rules/) —— レビュー内容をカスタマイズします。 +- [インテグレーション](../integrations/) —— OCR を Claude Code、Agent skill、CI に組み込みます。 +- [FAQ](../faq/) —— 既知のエラーと対策。 diff --git a/pages/src/content/docs/zh/configuration.md b/pages/src/content/docs/zh/configuration.md index 8f38b43..51ad3b1 100644 --- a/pages/src/content/docs/zh/configuration.md +++ b/pages/src/content/docs/zh/configuration.md @@ -4,182 +4,42 @@ sidebar: order: 5 --- -## 端点解析 +配置文件在 `~/.opencodereview/config.json`，你有三种方式编辑它： -当 `ocr review` 或 `ocr llm test` 运行时，它会按顺序尝试四个来源， -并使用第一个能给出完整 `(URL, token, model)` 三元组的来源： +- **交互式 TUI** —— `ocr config provider` / `ocr config model`，带引导菜单。 +- **命令行** —— `ocr config set `，适合脚本与 CI。 +- **手动编辑（不推荐）** —— 该 JSON 文件（下次 `ocr config set` 写入时会重新格式化）。 -| 优先级 | 来源 | 读取内容 | -|---|---|---| -| 1 | `~/.opencodereview/config.json` | 若设置了 `provider`，则通过 `providers`/`custom_providers` 映射解析（provider 优先；见[内置 provider](#built-in-providers)）。仅当未设置 provider 时才回退到遗留的 `llm` 段。 | -| 2 | OCR 环境变量 | `OCR_LLM_URL`、`OCR_LLM_TOKEN`、`OCR_LLM_MODEL`、`OCR_USE_ANTHROPIC`、`OCR_LLM_AUTH_HEADER`。 | -| 3 | Claude Code 环境变量 | `ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_MODEL`。 | -| 4 | Shell rc 文件 | 从 `~/.zshrc`、`~/.bashrc`、`~/.bash_profile`、`~/.profile` 中解析出的 `export ANTHROPIC_*=…` 行。 | +## 配置模型 -对于 Claude Code 风格的来源，若 `ANTHROPIC_BASE_URL` 缺少带版本的路径 -（`/v1/...`），OCR 会自动追加 `/v1/messages`。 - -如果没有一种策略能给出完整三元组，OCR 会以如下信息退出： - -``` -no valid LLM endpoint configured; one of OCR_LLM_URL/OCR_LLM_TOKEN/OCR_LLM_MODEL, -~/.opencodereview/config.json, or ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN/ -ANTHROPIC_MODEL must be set -``` - -> 解析在第一个**报错**的来源处停止，而不仅仅是第一个为空的来源。尤其要注意： -> 如果 `config.json` 中设置了 `provider` 但该条目配置有误（未知的 provider 名、 -> 缺少 `api_key` 且无环境变量回退、缺少 `model`、自定义 provider 缺少 -> `url`/`protocol`），OCR 会以该错误退出，并**不会**继续回退到 OCR 环境变量、 -> Claude Code 或 rc 文件来源。要切换到基于环境变量的配置，请先取消 -> 设置 `provider` key。 - -> 来源优先级意味着当配置文件已完整填充时，**环境变量不会覆盖任何值**。要让 -> 环境变量生效，要么从 `~/.opencodereview/config.json` 删除相关 `llm.*` key， -> 要么用 `ocr config set` 切换到新值。 - -## `ocr config set` ——管理 `~/.opencodereview/config.json` - -```bash -ocr config set -``` - -`config set` 通过 key/value 对修改文件，并做具备 schema 感知的解析。交互式 TUI -命令 `ocr config provider` 和 `ocr config model` 也写入同一个文件（见 -[交互式设置](#interactive-setup--ocr-config-provider--ocr-config-model)）。识别的 -key： - -| Key | 类型 | 说明 | -|---|---|---| -| `provider` | string | 设置当前 provider（内置名或自定义）。切换 provider 会清空 model。 | -| `model` | string | 为当前 provider 设置 model（存在 provider 条目下；若无 provider 则存到顶层 `model`）。 | -| `providers..` | varies | 内置 provider 的按字段设置：`api_key`、`url`、`protocol`、`model`、`models`、`auth_header`、`extra_body`。 | -| `custom_providers..` | varies | 同上字段，用于自定义（非内置）provider。自定义 provider 至少要设置 `url` 和 `protocol`。 | -| `llm.url` | string | 端点 URL。Anthropic 用完整的 Messages URL，如 `https://api.anthropic.com/v1/messages`。OpenAI 兼容则用 chat-completions URL。 | -| `llm.auth_token` | string | API key。以 `Authorization: Bearer …` 发送（OpenAI）；遗留 Anthropic 路径默认也是 `Authorization: Bearer …`（预设 `anthropic` provider 改为默认 `x-api-key`）。仅在显式设置 `llm.auth_header` 时才用 `x-api-key`。 | -| `llm.auth_header` | string | Auth header 名（`x-api-key`、`authorization` 或 `bearer`）。仅 Anthropic 用；某些需要 `x-api-key` 的 Anthropic 设置必需。 | -| `llm.model` | string | 模型名。`[<数字>m]` 后缀会被自动去除。 | -| `llm.use_anthropic` | boolean | `true`（默认）→ Anthropic Messages 协议。`false` → OpenAI Chat Completions。 | -| `llm.extra_body` | JSON object | 厂商专属的请求字段，合并进每次 chat 请求体。示例：`'{"thinking":{"type":"disabled"}}'`。 | -| `language` | string | 转发为追加到 system prompt 的指令；未设置时默认 `English`。见[选择语言](#choosing-a-language)。 | -| `telemetry.enabled` | boolean | OpenTelemetry 导出的总开关。默认关闭。 | -| `telemetry.exporter` | string | `console` 或 `otlp`。 | -| `telemetry.otlp_endpoint` | string | OTLP collector 地址（如 `localhost:4317`）。 | -| `telemetry.content_logging` | boolean | 在导出的事件数据中包含 LLM prompt / 响应。 | - -示例： - -```bash -ocr config set llm.url https://api.anthropic.com/v1/messages -ocr config set llm.auth_token sk-ant-xxxxxxxxxx -ocr config set llm.model claude-opus-4-6 -ocr config set llm.use_anthropic true -ocr config set llm.extra_body '{"thinking":{"type":"disabled"}}' -ocr config set language English -ocr config set telemetry.enabled true -ocr config set telemetry.exporter otlp -ocr config set telemetry.otlp_endpoint localhost:4317 - -# 基于 provider 的设置（推荐） -ocr config set provider anthropic -ocr config set model claude-opus-4-6 -ocr config set providers.anthropic.api_key "$ANTHROPIC_API_KEY" - -# 自定义（非内置）provider -ocr config set provider my-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.model llama-3-70b -ocr config set custom_providers.my-gateway.api_key "$MY_API_KEY" -``` - -布尔值接受 Go `strconv.ParseBool` 接受的任何形式（`true`、`false`、`1`、`0`、 -`t`、`f`……）。`llm.extra_body` 必须是合法 JSON。 - -## 文件 schema 参考 - -执行上述命令后，`~/.opencodereview/config.json` 形如： - -```json -{ - "llm": { - "url": "https://api.anthropic.com/v1/messages", - "auth_token": "sk-ant-xxxxxxxxxx", - "auth_header": "x-api-key", - "model": "claude-opus-4-6", - "use_anthropic": true, - "extra_body": { - "thinking": { "type": "disabled" } - } - }, - "language": "English", - "telemetry": { - "enabled": true, - "exporter": "otlp", - "otlp_endpoint": "localhost:4317" - } -} -``` - -基于 provider 的形式使用 `provider`、`model`、`providers` 和 -`custom_providers`，而非遗留的 `llm` 块： - -```json -{ - "provider": "anthropic", - "model": "claude-opus-4-6", - "providers": { - "anthropic": { - "api_key": "sk-ant-xxxxxxxxxx", - "model": "claude-opus-4-6" - } - }, - "custom_providers": { - "my-gateway": { - "url": "https://gateway.internal.com/v1", - "protocol": "openai", - "model": "llama-3-70b", - "models": ["llama-3-70b", "llama-3-8b"], - "api_key": "gw-xxxxxxxxxx", - "auth_header": "authorization" - } - }, - "language": "English" -} -``` - -当设置了 `provider` 时，由 `providers`/`custom_providers` 映射驱动解析；该配置下 -遗留的 `llm` 段被忽略。 - -你也可以手动编辑此文件，但下次写入时 `ocr config set` 会以 `" "` 缩进 -重新序列化。 - -## 交互式设置——`ocr config provider` / `ocr config model` - -为免去手动键入 key 来选择 provider 和 model，OCR 提供两个交互式 Bubble Tea TUI， -二者同样会修改 `~/.opencodereview/config.json`。 +### 推荐：交互式设置 ```bash ocr config provider +``` + +它会让你选择一个内置或自定义 provider、填入 API key、挑选 model，保存到配置文件后自动运行一次 `ocr llm test` 验证端点。之后想换模型： + +```bash ocr config model ``` -- `ocr config provider`——选择内置或自定义 provider，并输入 URL / protocol / - API key / model 的交互式 TUI。选择会保存到 config，并自动运行 `ocr llm test` - 验证端点。对于内置 provider，若未直接输入，API key 可从该 provider 的环境变量 - 读取（见[内置 provider](#built-in-providers)）。若选择手动配置，则改为填充遗留的 - `llm.*` 块。 -- `ocr config model`——从当前 provider 的预设列表，以及 - `providers..models` / `custom_providers..models` 下用户添加的 - model 中选择模型的交互式 TUI。需要先设置 provider（`ocr config provider`）。 +### 非交互设置（CI / 无 TUI 环境） -## 内置 provider +用 `ocr config set` 写入同一份配置： -以下 provider 随 OCR 发布。每个都有预设的 `BaseURL`、`Protocol`，以及 -（如适用）一个 API key 环境变量，在 `providers..api_key` 未设置时作为 -回退。 +```bash +ocr config set provider anthropic +ocr config set model claude-opus-4-6 +ocr config set providers.anthropic.api_key sk-ant-xxxxxxxxxx +``` -| 名称 | Protocol | Base URL | API key 环境变量 | +### 内置 provider + +下列 provider 随 OCR 发布，已预置 Base URL 与协议，选中后只需填 API key。 +若 `providers..api_key` 未设置，会自动回退到对应的环境变量。 + +| 名称 | 协议 | Base URL | API key 环境变量 | |---|---|---|---| | `anthropic` | anthropic | `https://api.anthropic.com` | `ANTHROPIC_API_KEY` | | `openai` | openai | `https://api.openai.com/v1` | `OPENAI_API_KEY` | @@ -195,78 +55,47 @@ ocr config model | `minimax` | openai | `https://api.minimaxi.com/v1` | `MINIMAX_API_KEY` | | `baidu-qianfan` | openai | `https://qianfan.baidubce.com/v2` | `QIANFAN_API_KEY` | -任何其他 provider 名都被视为自定义，必须在 `custom_providers` 下配置，且至少 -要有 `url` 和 `protocol`。 +### 自定义 provider -## 环境变量参考 - -| 变量 | 用途 | -|---|---| -| `OCR_LLM_URL` | 端点 URL——与 `llm.url` 同形。 | -| `OCR_LLM_TOKEN` | API key——与 `llm.auth_token` 相同。 | -| `OCR_LLM_MODEL` | 模型名。 | -| `OCR_LLM_AUTH_HEADER` | Auth header 名（`x-api-key`、`authorization` 或 `bearer`）。仅 Anthropic；与 `llm.auth_header` 相同。未设置时默认 `authorization`。 | -| `OCR_USE_ANTHROPIC` | 未设置 → Anthropic 协议（默认）。设为 `true` / `1` / `yes`（不区分大小写）→ Anthropic。设为其他值（`false`、`0`、`no`、拼写错误……）→ OpenAI。 | -| `ANTHROPIC_BASE_URL` | Claude Code 兼容的 base URL。 | -| `ANTHROPIC_AUTH_TOKEN` | Claude Code 兼容的 API key。 | -| `ANTHROPIC_MODEL` | Claude Code 兼容的 model。 | -| `OCR_ENABLE_TELEMETRY` | `1` 表示从环境变量启用遥测。 | -| `OTEL_SERVICE_NAME` | 覆盖 span/metric 中的 service name。 | -| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP collector 地址——同时强制 exporter 为 `otlp`。 | -| `OTEL_EXPORTER_OTLP_PROTOCOL` | OTLP 传输协议（`grpc`、`http/protobuf` 或 `http/json`）。默认 `grpc`。 | -| `OCR_CONTENT_LOGGING` | `1` 表示在遥测事件中包含 prompt/响应。 | - -各 provider 的 API key（`ANTHROPIC_API_KEY`、`OPENAI_API_KEY`、 -`DASHSCOPE_API_KEY`……）在内置 provider 的 `api_key` 字段未设置时作为回退。 -各 provider 的环境变量名见[内置 provider](#built-in-providers)表。 - -## 为什么有 `extra_body` - -一些托管 provider 会在请求体中加入非标准字段（例如 Bedrock 风格的 `thinking`、 -厂商专属的 `temperature_strategy`、流式选项）。`llm.extra_body` 会被合并进每个 -发出的请求，因此你无需改源码即可发送这些字段。 +任何不在上表中的 provider 名都视为自定义，至少要提供 `url` 和 `protocol` +（`protocol` 取 `anthropic` 或 `openai`）： ```bash -ocr config set llm.extra_body '{"thinking":{"type":"enabled","budget_tokens":2048}}' +ocr config set provider my-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.model llama-3-70b +ocr config set custom_providers.my-gateway.api_key "$MY_API_KEY" ``` -## 选择语言 - -`language` key 只控制一件事：追加到评审和 `ocr llm test` prompt 中每条 -system-role 消息的一条指令。注入的精确字符串是： - -``` -\n\nAlways respond in . -``` - -- *未设置*或为空——按 `English` 对待。 -- `Chinese`、`English` 或任何其他字符串——原样透传。 - -内置 rule docs 不支持语言切换。`internal/config/rules/rule_docs/` 下嵌入的文件按 -固定文件名加载，多数以中文撰写（`default.md` 是英文例外）；无论 `language` -如何设置，它们都原样出现在 prompt 中。因此当 `language` 设为 `English` 时，prompt -里会是一条英文指令叠加大段中文 rule 文本——强模型会遵从指令产出英文评论， -弱模型可能输出中英混杂的内容。 - -`language` 没有环境变量、CLI 参数或项目级覆盖——唯一能设置它的地方是全局 -`~/.opencodereview/config.json`，通过 -[`ocr config set`](#ocr-config-set--managing-opencodereviewconfigjson)： +### 验证连通性 ```bash +ocr llm test +``` + +### 复用已有的环境变量 + +如果你已经配好了 Claude Code 的 `ANTHROPIC_*`，或 OCR 自己的 `OCR_LLM_*`环境变量，OCR 会自动识别，无需再写配置文件。 + +### 发送厂商专属字段 + +某些 provider 需要非标准的请求字段（如 Bedrock 风格的 `thinking`）。用`extra_body`（合并进每次请求）即可发送，无需改源码： + +```bash +ocr config set providers.anthropic.extra_body '{"thinking":{"type":"disabled"}}' +``` + +## 配置评审语言 + +`language` 决定评审评论用哪种语言输出，未设置时默认英文： + +```bash +ocr config set language 中文 ocr config set language English ``` -如果你需要纯英文 rule 文本，请通过 `--rule`、`/.opencodereview/rule.json` -或 `~/.opencodereview/rule.json` 提供自己的规则（见 -[评审规则](../review-rules/#priority-chain)）。 - -## 项目级 vs 全局配置 - -CLI 本身是全局配置的（`~/.opencodereview/config.json`）——没有项目级 LLM 配置。 -但**评审规则**是项目级的；见[评审规则](../review-rules/#priority-chain)。 - ## 另见 - [快速开始](../quickstart/)——最小化设置与首次评审。 - [CLI 参考](../cli-reference/)——review 命令接受的每个参数。 -- [遥测](../telemetry/)——如何接入 OTLP / console exporter。 diff --git a/pages/src/content/docs/zh/faq.md b/pages/src/content/docs/zh/faq.md index 262ee05..838c8b7 100644 --- a/pages/src/content/docs/zh/faq.md +++ b/pages/src/content/docs/zh/faq.md @@ -17,7 +17,7 @@ no valid LLM endpoint configured; one of OCR_LLM_URL/OCR_LLM_TOKEN/OCR_LLM_MODEL ANTHROPIC_MODEL must be set ``` -OCR 走完了四来源解析链（[配置](../configuration/#endpoint-resolution)）但没 +OCR 走完了整条端点解析链（[配置](../configuration/#复用已有的环境变量)）但没 找到完整的 `(URL, token, model)` 三元组。要么： - 运行 `ocr config set llm.url …` / `llm.auth_token …` / `llm.model …` 填充 diff --git a/pages/src/content/docs/zh/installation.md b/pages/src/content/docs/zh/installation.md index 8229860..d6dca95 100644 --- a/pages/src/content/docs/zh/installation.md +++ b/pages/src/content/docs/zh/installation.md @@ -4,44 +4,60 @@ sidebar: order: 4 --- -安装 `ocr` CLI 有四种受支持的方式。它们产出的都是同一个二进制——按你的 -环境选择即可。 +安装 `ocr` CLI 有四种受支持的方式。 ## NPM（推荐） +#### 安装 + ```bash npm install -g @alibaba-group/open-code-review ``` -NPM 包附带一个小的 wrapper 脚本（`bin/ocr.js`）和一个 -[postinstall hook](https://github.com/alibaba/open-code-review/blob/main/scripts/install.js)， -它会： - -1. 探测你的平台（`darwin-amd64`、`darwin-arm64`、`linux-amd64`、 - `linux-arm64`、`windows-amd64`、`windows-arm64`）。 -2. 从 GitHub Releases 下载匹配的二进制。 -3. （当存在校验和数据时）验证它，并放到 wrapper 旁边。 - -如果某个平台专属 npm 包（如 `@alibaba-group/ocr-darwin-arm64`）作为 -optional dependency 被安装，则直接使用该二进制，跳过下载。 - -运行 `ocr` 时，wrapper 只是 `exec` 下载好的二进制，因此首次运行后实际开销 -为零。 - -### 更新 +固定到某个版本： ```bash -npm update -g @alibaba-group/open-code-review -# 或固定到某个版本： npm install -g @alibaba-group/open-code-review@ ``` -### 卸载 +#### 更新 + +通过 NPM 安装时，`ocr` 默认会自动保持最新（静态二进制不参与此机制）。每次运行 +`ocr` 时，wrapper 会在后台静默检查 registry 上的最新版本，发现更新即自动升级， +不影响本次评审。两次检查之间有 18 分钟冷却，可用 `OCR_UPDATE_INTERVAL`（分钟）调整。 + +关闭自动更新，将 `OCR_NO_UPDATE` 设为任意非空值即可： + +```bash +export OCR_NO_UPDATE=1 +``` + +#### 卸载 ```bash npm uninstall -g @alibaba-group/open-code-review ``` +## 安装脚本（curl | sh） + +一个便捷安装器，封装了 GitHub Release 二进制下载（带校验）——适合 CI 基础 +镜像和无界面环境： + +```bash +curl -fsSL https://raw.githubusercontent.com/alibaba/open-code-review/main/install.sh | sh +``` + +它识别两个环境变量： + +| 变量 | 默认值 | 用途 | +|---|---|---| +| `OCR_INSTALL_DIR` | `/usr/local/bin` | 放置 `ocr` 二进制的位置。 | +| `OCR_VERSION` | 最新 release | 固定到某个 release tag（如 `v1.2.3`）。 | + +该脚本支持 `darwin` 与 `linux` 的 `amd64` / `arm64`；Windows 请改用 +[GitHub Release 二进制](#github-release-binary)或 [NPM](#npm-recommended) +方式。 + ## GitHub Release 二进制 如果你不想装 Node.js，可直接从 @@ -79,37 +95,17 @@ curl -LO https://github.com/alibaba/open-code-review/releases/latest/download/sh shasum -a 256 -c sha256sum.txt --ignore-missing ``` -## 安装脚本（curl | sh） - -一个便捷安装器，封装了 GitHub Release 二进制下载（带校验）——适合 CI 基础 -镜像和无界面环境： - -```bash -curl -fsSL https://raw.githubusercontent.com/alibaba/open-code-review/main/install.sh | sh -``` - -它识别两个环境变量： - -| 变量 | 默认值 | 用途 | -|---|---|---| -| `OCR_INSTALL_DIR` | `/usr/local/bin` | 放置 `ocr` 二进制的位置。 | -| `OCR_VERSION` | 最新 release | 固定到某个 release tag（如 `v1.2.3`）。 | - -该脚本支持 `darwin` 与 `linux` 的 `amd64` / `arm64`；Windows 请改用 -[GitHub Release 二进制](#github-release-binary)或 [NPM](#npm-recommended) -方式。 - ## 从源码构建 仅当你要修改 OCR 本身，或在某个没有预编译二进制的平台上运行时才需要此方式。 -### 前置条件 +#### 前置条件 - [Go ≥ 1.25](https://go.dev/dl/) - [Git](https://git-scm.com/) - [Make](https://www.gnu.org/software/make/) -### 构建 +#### 构建 ```bash git clone https://github.com/alibaba/open-code-review.git @@ -118,7 +114,7 @@ make build # 产出 dist/opencodereview sudo cp dist/opencodereview /usr/local/bin/ocr ``` -### 为其他平台构建 +#### 为其他平台构建 ```bash make build-linux-amd64 @@ -134,7 +130,7 @@ make sha256sum # 同时产出 sha256sum.txt `make dist` 会运行 `clean → build-all → sha256sum`，并在二进制旁写入一个 `VERSION` 文件——这正是 release 流水线执行的步骤。 -### 运行测试 +#### 运行测试 ```bash make test # LC_ALL=C go test -v -race -count=1 ./... @@ -164,7 +160,7 @@ echo $PATH | `~/.opencodereview/config.json` | LLM 端点、语言、遥测配置（由 `ocr config set` 管理）。 | | `~/.opencodereview/rule.json` | 可选的全局评审规则。 | | `~/.opencodereview/sessions//.jsonl` | 每次评审会话的流式 JSONL 转录，供 `ocr viewer` 使用。 | -| `~/.opencodereview/{last-update-check,update.lock,update-available}` | NPM wrapper 的后台更新检查状态。wrapper 会轮询是否有更新的 release（默认约每 18 分钟一次）并打印升级提示。用 `OCR_NO_UPDATE=1` 禁用，或用 `OCR_UPDATE_INTERVAL`（秒）调整间隔。静态二进制不写入这些文件。 | +| `~/.opencodereview/{last-update-check,update.lock,update-available}` | NPM wrapper 的后台更新检查状态。wrapper 会轮询是否有更新的 release（默认约每 18 分钟一次）并打印升级提示。用 `OCR_NO_UPDATE=1` 禁用，或用 `OCR_UPDATE_INTERVAL`（分钟）调整间隔。静态二进制不写入这些文件。 | | `/.opencodereview/rule.json` | 可选的项目级评审规则——可安全提交。 | OCR 永远不会写入 `~/.opencodereview/` 之外（除 NPM 临时下载二进制外）。 diff --git a/pages/src/content/docs/zh/quickstart.md b/pages/src/content/docs/zh/quickstart.md index 1fa7aa0..10f8753 100644 --- a/pages/src/content/docs/zh/quickstart.md +++ b/pages/src/content/docs/zh/quickstart.md @@ -4,232 +4,92 @@ sidebar: order: 3 --- -安装 OCR，连接到任意支持 Anthropic Messages API 或 OpenAI Chat Completions API -的 LLM，然后运行你的第一次代码评审。 +几分钟内跑通第一次代码评审。 ## 前置条件 -- 一个可用的 **Git** 安装——OCR 以子进程方式驱动 Git 读取 diff。 -- 一个兼容 Anthropic 或 OpenAI 的 LLM 的 **API key**。 -- 以下之一： - - **Node.js ≥ 18**（推荐；最低支持 Node 14——通过 NPM 安装）。 - - 或仅用 `curl` + `chmod` 把静态二进制放进 `$PATH`。 - - 或 **Go ≥ 1.25**，如果你偏好从源码构建。 +- **Git ≥ 2.41** +- **Node.js ≥ 18** +- **LLM API key** -## 第 1 步——安装 CLI - -### 方式 A：NPM（推荐） +## 第 1 步 —— 安装 CLI ```bash npm install -g @alibaba-group/open-code-review +ocr version ``` -NPM 包安装一个小的 wrapper，它在安装时（通过 postinstall hook）为你的 -操作系统 / 架构下载正确的二进制。如果运行时二进制缺失，wrapper 会报错而 -不会去下载。安装后，你得到一个全局 `ocr` 命令： +> 更多方式见 [安装](../installation/)。 + +## 第 2 步 —— 配置 LLM ```bash -ocr --version +ocr config provider ``` -### 方式 B：GitHub Release 二进制 - -从 [releases 页面](https://github.com/alibaba/open-code-review/releases) -选择对应平台的二进制，放进你的 `$PATH`： +它会让你选择一个内置或自定义 provider、填入 API key、挑选 model，保存到配置文件后自动运行一次 `ocr llm test` 验证端点。之后想换模型： ```bash -# macOS (Apple Silicon) -curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-darwin-arm64 -chmod +x ocr && sudo mv ocr /usr/local/bin/ocr - -# macOS (Intel) -curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-darwin-amd64 -chmod +x ocr && sudo mv ocr /usr/local/bin/ocr - -# Linux x86_64 -curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-linux-amd64 -chmod +x ocr && sudo mv ocr /usr/local/bin/ocr - -# Linux ARM64 -curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-linux-arm64 -chmod +x ocr && sudo mv ocr /usr/local/bin/ocr - -# Windows (AMD64) -curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-amd64.exe - -# Windows (ARM64) -curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-arm64.exe +ocr config model ``` -### 方式 C：从源码构建 +### 备选:非交互命令 + +在 CI 或无 TUI 的环境里,用 `ocr config set` 直接写入同一份配置: ```bash -git clone https://github.com/alibaba/open-code-review.git -cd open-code-review -make build -sudo cp dist/opencodereview /usr/local/bin/ocr +ocr config set provider anthropic +ocr config set model claude-opus-4-6 +ocr config set providers.anthropic.api_key sk-ant-xxxxxxxxxx ``` -> 各安装方式的详情见 [安装](../installation/)，包括 NPM wrapper 如何解析 -> 平台二进制。 - -## 第 2 步——配置 LLM - -在能解析出一个完整的 LLM 端点（URL + token + model）之前，OCR 会拒绝运行 -评审。它按以下优先级顺序搜索四个来源： - -1. `~/.opencodereview/config.json` -2. OCR 专属环境变量（`OCR_LLM_*`） -3. Claude Code 环境变量（`ANTHROPIC_*`） -4. 从你的 shell rc 文件（`~/.zshrc`、`~/.bashrc`、`~/.bash_profile`、 - `~/.profile`）中解析出的 `export ANTHROPIC_*` 行 - -### 最快路径：`ocr config set` - -```bash -ocr config set llm.url https://api.anthropic.com/v1/messages -ocr config set llm.auth_token sk-ant-xxxxxxxxxx -ocr config set llm.model claude-opus-4-6 -ocr config set llm.use_anthropic true -``` - -这些值会持久化到 `~/.opencodereview/config.json`。 - -### 替代方式：环境变量 - -优先级最高——适合不想在磁盘上留配置文件的 CI / 容器： - -```bash -export OCR_LLM_URL=https://api.anthropic.com/v1/messages -export OCR_LLM_TOKEN=sk-ant-xxxxxxxxxx -export OCR_LLM_MODEL=claude-opus-4-6 -export OCR_USE_ANTHROPIC=true # 默认 true；设为 false 走 OpenAI 协议 -``` - -### 已经在用 Claude Code？ - -OCR 会自动读取 Claude Code 使用的同一批变量，无需额外配置： - -```bash -export ANTHROPIC_BASE_URL=https://api.anthropic.com -export ANTHROPIC_AUTH_TOKEN=sk-ant-xxxxxxxxxx -export ANTHROPIC_MODEL=claude-opus-4-6 -``` - -如果 `ANTHROPIC_BASE_URL` 缺少带版本的路径，OCR 会自动追加 -`/v1/messages`。 - -### 使用 OpenAI 兼容端点？ - -把 `llm.use_anthropic` 设为 `false`（或 `OCR_USE_ANTHROPIC=false`）： - -```bash -ocr config set llm.url https://api.openai.com/v1/chat/completions -ocr config set llm.auth_token sk-xxxxxxxxxx -ocr config set llm.model gpt-4o -ocr config set llm.use_anthropic false -``` - -> 完整的 key 参考见 [配置](../configuration/)，包括用于厂商专属请求字段 -> 的 `llm.extra_body`，以及用于切换评审评论语言的 `language`。 - -## 第 3 步——测试连通性 +## 第 3 步 —— 测试连通性 ```bash ocr llm test ``` -预期输出（模型名会有所不同）： +如果报出 `no valid LLM endpoint configured` 这类错误,请重新检查第 2 步的配置。 401 / 403 表示 token 错误或已过期。 -``` -Source: OCR config file -URL: https://api.anthropic.com/v1/messages -Model: claude-opus-4-6 -Hello! … -``` - -如果反而报出 `no valid LLM endpoint configured` 这类错误，请重新检查上面的 -配置 key。401 / 403 表示 token 错误或已过期。 - -## 第 4 步——运行第一次评审 +## 第 4 步 —— 运行第一次评审 进入任意 Git 仓库并运行： ```bash cd path/to/your-repo -# 工作区模式——评审 staged + unstaged + untracked 变更（默认） +# 工作区模式 —— 评审 staged + unstaged + untracked 变更（默认） ocr review -# 分支区间——评审 `main..feature-branch` +# 分支区间 —— 评审 `main..feature-branch` ocr review --from main --to feature-branch -# 单个 commit——评审该 commit 引入的 diff +# 单个 commit —— 评审该 commit 引入的 diff ocr review --commit abc123 ``` -你会看到持续输出的进度信息，最后每个文件出现一条或多条评审评论。 +> `ocr review` 的完整参数（并发调优、输出格式、audience模式、背景上下文等）及其他所有子命令见 [CLI 参考](../cli-reference/)。 -> 工作区模式包含 **untracked** 文件。如果你只想评审已暂存的内容，请先用 -> `git add` 选择性暂存。 - -> 以上三种是基础用法。`ocr review` 的完整参数（并发调优、输出格式、 -> audience 模式、背景上下文等）及其他所有子命令（`config`、`rules`、 -> `llm test`、`viewer`）见 [CLI 参考](../cli-reference/)。 - -### 想先看看 *会* 评审什么？ +### 想先看看会评审什么？ ```bash -ocr review --preview # 工作区 -ocr review -c abc123 -p # commit +ocr review --preview # 工作区 +ocr review -c abc123 --preview # commit ``` -`--preview` 运行每个过滤步骤但绝不调用 LLM，因此不消耗任何 token。它打印文件列表 -及每个文件的状态（`added` / `modified` / `deleted` / `renamed` / `binary`）， -对于被排除的文件还会给出原因（`binary`、`unsupported_ext`、`default_path`、 -`user_exclude`、`deleted`）。 +### 面向系统的 JSON 输出 -### 给工具用的 JSON 输出 +`--audience agent` 屏蔽人性化的进度 UI,让 stdout 只剩 JSON / 最终摘要 —— 正是上游 agent 或 CI 脚本所需。 ```bash ocr review --format json --audience agent > review.json ``` -- `--format json` 输出一个机器可读的评论数组，每条含 `path`、`content`、 - `start_line`、`end_line`、`existing_code`、`suggestion_code` 和可选的 - `thinking`。 -- `--audience agent` 屏蔽人性化的进度 UI，让 stdout 只剩 JSON / 最终 - 摘要——正是上游 agent 或 CI 脚本所需。 - -## 第 5 步——查看结果 - -每条评论包含： - -| 字段 | 含义 | -|---|---| -| `path` | 该评论所针对的文件。 | -| `content` | 评审评论本身，使用配置的 `language`。 | -| `start_line` / `end_line` | 文件 **新** 版本中的行范围。两者都为 `0` 表示 OCR 无法精确定位评论——问题是真实的，但需自行定位到准确位置。 | -| `existing_code` | 评论所指的 diff 片段。内部用于行解析；在 `start_line` 为 `0` 时有用。 | -| `suggestion_code` | 可选的修复片段。 | -| `thinking` | 可选的模型推理。仅部分模型存在。 | - -## 第 6 步——查看历史会话 - -每次评审都会以 JSONL 转录形式持久化到 -`~/.opencodereview/sessions/...`。在本地 Web UI 中浏览它们： - -```bash -ocr viewer # http://localhost:5483 -ocr viewer --addr :3000 -``` - -> 完整 UI 介绍见 [会话查看器](../viewer/)。 - ## 另见 -- [CLI 参考](../cli-reference/)——每个子命令、参数与输出模式。 -- [评审规则](../review-rules/)——自定义评审内容。 -- [集成](../integrations/)——把 OCR 嵌入 Claude Code、Agent skill 或 CI。 -- [遥测](../telemetry/)——经 OTLP 上报 trace 与 metrics。 -- [FAQ](../faq/)——已知错误与对策。 +- [安装](../installation/) —— 全部安装方式与 OCR 的状态目录。 +- [配置](../configuration/) —— 每个环境变量、config key 与内置 provider。 +- [CLI 参考](../cli-reference/) —— 每个子命令、参数与输出模式。 +- [评审规则](../review-rules/) —— 自定义评审内容。 +- [集成](../integrations/) —— 把 OCR 嵌入 Claude Code、Agent skill 或 CI。 +- [FAQ](../faq/) —— 已知错误与对策。