From 817ddf9403b66f62584fe5794be7963b8935971f Mon Sep 17 00:00:00 2001 From: kite Date: Tue, 21 Jul 2026 17:12:31 +0800 Subject: [PATCH 1/5] docs(readme): link to docs site and collapse duplicated sections (#424) Reduce the large content overlap between the README files and the docs site (pages/src/content/docs). Add a Documentation section linking to open-codereview.ai/docs, and collapse the Commands, Review Rules, and Configuration Reference sections into one-line summaries plus links. This makes the docs site the single source of truth for reference content and cuts the multi-language maintenance burden. Applied consistently across all five localized READMEs (en/zh/ja/ko/ru). --- README.ja-JP.md | 336 +++-------------------------------------------- README.ko-KR.md | 294 +++-------------------------------------- README.md | 341 +++--------------------------------------------- README.ru-RU.md | 338 +++-------------------------------------------- README.zh-CN.md | 331 +++------------------------------------------- 5 files changed, 79 insertions(+), 1561 deletions(-) diff --git a/README.ja-JP.md b/README.ja-JP.md index d7a85b9d..72c754f2 100644 --- a/README.ja-JP.md +++ b/README.ja-JP.md @@ -514,129 +514,23 @@ GitHub 向けに、本リポジトリはリポジトリルートにすぐ使え 再現性を高めるため、バージョンタグまたはコミット SHA に固定してください。完全なワークフローデモ、inputs/outputs の全一覧、コメント投稿モード（スティッキーサマリー、非破壊的なインクリメンタル投稿）については [`examples/github_actions/`](./examples/github_actions/) ディレクトリを参照してください。 -## コマンド +## ドキュメント -| コマンド | エイリアス | 説明 | -|---------|-------|-------------| -| `ocr review` | `ocr r` | diffベースのコードレビューを開始 | -| `ocr scan` | `ocr s` | ファイル全体をレビュー（diff不要） | -| `ocr delegate preview` | `ocr d preview` | レビュー対象ファイル一覧をモード/参照メタデータ付きで出力（LLM 不要） | -| `ocr delegate rule ` | `ocr d rule` | 内容別にグループ化されたレビュールールを出力（LLM 不要） | -| `ocr rules check ` | — | ファイルパスに適用されるレビュールールをプレビュー | -| `ocr config provider` | — | 対話的プロバイダーセットアップ（ビルトイン、カスタム、手動） | -| `ocr config model` | — | アクティブなプロバイダーの対話的モデル選択 | -| `ocr config set ` | — | 設定値をセット | -| `ocr config unset custom_providers.` | — | カスタムプロバイダーを削除 | -| `ocr llm test` | — | LLMの疎通テスト | -| `ocr llm providers` | — | ビルトインLLMプロバイダーを一覧表示 | -| `ocr session list` | `ocr sessions list`, `ocr session ls` | 保存済みレビューセッションを一覧表示 | -| `ocr session show ` | `ocr sessions show ` | 1つのセッションとファイル単位のチェックポイントを表示 | -| `ocr viewer` | `ocr v` | `localhost:5483`でWebUIセッションビューアーを起動 | -| `ocr version` | — | バージョン情報を表示 | - -### `ocr review`のフラグ - -| フラグ | 短縮形 | デフォルト | 説明 | -|------|-----------|---------|-------------| -| `--repo` | — | カレントディレクトリ | Gitリポジトリのルート | -| `--from` | — | — | ソースref（例：`main`） | -| `--to` | — | — | ターゲットref（例：`feature-branch`） | -| `--commit` | `-c` | — | レビュー対象の単一コミット | -| `--exclude` | — | — | カンマ区切りのgitignoreスタイルパターンでスキップ対象を指定；rule.jsonのexcludesとマージ | -| `--preview` | `-p` | `false` | LLMを実行せずにレビュー対象ファイルをプレビュー | -| `--resume` | — | — | 以前の互換性のある範囲または単一 commit レビューセッションから再開 | -| `--format` | `-f` | `text` | 出力形式：`text`または`json` | -| `--concurrency` | — | `8` | ファイルレビューの最大同時実行数 | -| `--timeout` | — | `10` | 同時実行タスクのタイムアウト（分） | -| `--audience` | — | `human` | `human`（進捗を表示）または`agent`（サマリーのみ） | -| `--background` | `-b` | — | レビューのための任意の要件/ビジネスコンテキスト。`--commit`使用時に未指定の場合、コミットメッセージから自動取得 | -| `--background-file` | `-B` | — | Markdownファイルから読み込む任意の要件/ビジネスコンテキスト。`--background`と併用した場合はインラインの値が先に配置されます | -| `--model` | — | — | このレビューでLLMモデルを選択または上書き | -| `--rule` | — | — | カスタムJSONレビュールールへのパス | -| `--max-tools` | — | 組み込み値 | ファイルごとのツール呼び出しラウンドの上限。テンプレートのデフォルトより大きい場合のみ有効 | -| `--max-git-procs` | — | 組み込み値 | gitサブプロセスの最大同時実行数 | -| `--tools` | — | — | カスタムJSONツール設定へのパス | - -#### 再開可能なレビューとセッション - -すべての `ocr review` 実行は、`~/.opencodereview/sessions/` 配下にローカル -セッションログを保存します。正常終了したテキスト出力はレビュー結果に集中し、session ID -は表示しません。保存済みセッションは `ocr session list/show` で確認でき、 -`--format json` では機械可読出力に `session_id` が含まれます。範囲または単一 commit -レビューが中断された場合は、保存済みセッションを一覧表示し、同じレビュー対象に一致するセッションから再開します: +完全なドキュメントは **[open-codereview.ai/docs](https://open-codereview.ai/docs)** にあります： -```bash -ocr session list -ocr session show -ocr review --from main --to feature-branch --resume -ocr review --commit abc123 --resume -``` +- [クイックスタート](https://open-codereview.ai/docs/quickstart) — インストールして最初のレビューを実行 +- [インストール](https://open-codereview.ai/docs/installation) — すべてのプラットフォームとパッケージマネージャー +- [CLI リファレンス](https://open-codereview.ai/docs/cli-reference) — すべてのコマンドとフラグ +- [レビュールール](https://open-codereview.ai/docs/review-rules) — ルールの優先順位チェーン、ファイル形式、パスフィルタリング +- [設定](https://open-codereview.ai/docs/configuration) — 設定キーと環境変数 +- [MCP サーバー](https://open-codereview.ai/docs/mcp) — 外部ツールでレビューエージェントを拡張 +- [コーディングエージェント連携](https://open-codereview.ai/docs/claude-code) — Claude Code、Agent Skill、委譲モード +- [CI/CD 連携](https://open-codereview.ai/docs/cicd) — パイプラインでレビューを実行 +- [アーキテクチャ](https://open-codereview.ai/docs/architecture) · [ツール](https://open-codereview.ai/docs/tools) · [セッションビューアー](https://open-codereview.ai/docs/viewer) · [テレメトリー](https://open-codereview.ai/docs/telemetry) · [FAQ](https://open-codereview.ai/docs/faq) -再開は意図的に厳密です。範囲レビューと単一 commit レビューのみ対応し、ワークスペースレビューは再開できません。 -現在の `--from/--to` または `--commit` は保存済みセッションと一致する必要があります。`--preview` と `--resume` は併用できません。 - -`--format json` を使用すると、再開した実行には次が含まれます: - -- `session_id` — 現在の実行の session ID -- `resume.resumed_from` — 再開元の session ID -- `resume.reused_files` — 保存済みチェックポイントから再利用したファイル数 -- `resume.rerun_files` — 現在の実行で再レビューしたファイル数 - -### `ocr session`のフラグ - -| コマンド | フラグ | デフォルト | 説明 | -|---------|------|---------|------| -| `ocr session list` | `--repo` | カレントディレクトリ | 一覧表示するセッションのリポジトリ | -| `ocr session list` | `--json` | `false` | セッション概要をJSONで出力 | -| `ocr session list` | `--limit` | `20` | 一覧表示するセッション数の上限。`0` は無制限 | -| `ocr session show ` | `--repo` | カレントディレクトリ | 確認するセッションのリポジトリ | -| `ocr session show ` | `--json` | `false` | セッションメタデータとファイル単位の項目をJSONで出力 | - -### `ocr scan`のフラグ - -`ocr scan` はdiffではなくファイル全体をレビューします — 不慣れなコードベースの監査、マイグレーション前のスキャン、意味のあるdiffがないディレクトリなどに有用です。非gitディレクトリでも動作します（`.gitignore` を尊重するファイルシステムウォークにフォールバック）。 - -| フラグ | 短縮形 | デフォルト | 説明 | -|------|-----------|---------|-------------| -| `--path` | — | リポジトリ全体 | カンマ区切りのスキャン対象ディレクトリ/ファイル | -| `--exclude` | — | — | カンマ区切りのgitignoreスタイルパターンでスキップ対象を指定；rule.jsonのexcludesとマージ | -| `--preview` | `-p` | `false` | LLMを実行せずにスキャン対象ファイルを一覧表示 | -| `--max-tokens-budget` | — | `0`（無制限） | トークン使用量の上限；超過するとディスパッチを停止 | -| `--no-plan` | — | `false` | ファイルごとのプランニング前処理をスキップ | -| `--no-dedup` | — | `false` | バッチごとの類似コメント重複排除をスキップ | -| `--no-summary` | — | `false` | プロジェクトレベルのサマリーをスキップ | -| `--batch` | — | `by-language` | バッチ戦略：`none`、`by-language`、または `by-directory` | -| `--format` | `-f` | `text` | 出力形式：`text` または `json`（JSONには `project_summary` フィールドを含む） | -| `--concurrency` | — | `8` | 最大同時ファイルスキャン数 | -| `--rule` | — | — | カスタムJSONレビュールールへのパス | -| `--repo` | — | カレントディレクトリ | スキャン対象のリポジトリまたはディレクトリルート | - -各実行前に、`ocr scan` はおおまかなトークンコスト見積もりを表示します。`--preview` でまずファイルリストを確認し、`--max-tokens-budget` で大規模リポジトリの支出を制限できます。 - -### `ocr delegate` フラグ - -`ocr delegate` は AI コーディングエージェント向けのデリゲートモードです。LLM を呼び出さずに -確定的なファイル選択とルール解決を提供します — 実際のレビューはホストエージェントが -自身の能力で実行します。 - -| サブコマンド | 説明 | -|-------------|------| -| `ocr delegate preview` | レビュー対象ファイル一覧をモード/参照メタデータ付きで出力 | -| `ocr delegate rule ` | 内容別にグループ化されたレビュールールを出力 | - -両サブコマンドは以下のフラグを共有します： - -| フラグ | 短縮形 | デフォルト | 説明 | -|--------|--------|-----------|------| -| `--repo` | — | カレントディレクトリ | Git リポジトリルート | -| `--from` | — | — | ソース参照（例：`main`） | -| `--to` | — | — | ターゲット参照（例：`feature-branch`） | -| `--commit` | `-c` | — | 単一コミット | -| `--exclude` | — | — | カンマ区切りの gitignore スタイルの除外パターン | -| `--rule` | — | — | カスタム JSON レビュールールのパス | -| `--background` | `-b` | — | オプションの要件/ビジネスコンテキスト | -| `--background-file` | `-B` | — | Markdown ファイルからのビジネスコンテキスト | -| `--max-git-procs` | — | `16` | 最大並行 git サブプロセス数 | +## コマンド + +OCR は `review`、`scan`、`delegate`、`config`、`llm`、`session`、`viewer` などのコマンドを提供します。コマンドの完全な一覧とすべてのフラグ（再開可能なレビューや `ocr scan` / `ocr delegate` の全オプションを含む）については、**[CLI リファレンス](https://open-codereview.ai/docs/cli-reference)** を参照してください。 ## 例 @@ -726,209 +620,11 @@ OCR_VIEWER_ALLOWED_HOSTS=review.internal,ocr.lan ocr viewer --addr :3000 ## レビュールール -OCRは4層の優先度チェーンを使ってレビュールールを解決します。各層はファーストマッチ優先です：ファイルパスがパターンにマッチすればそのルールが使われ、マッチしなければ次の層にフォールスルーします。 - -| 優先度 | ソース | パス | 説明 | -|----------|--------|------|-------------| -| 1（最高） | `--rule`フラグ | ユーザー指定パス | CLIによる明示的なオーバーライド | -| 2 | プロジェクト設定 | `/.opencodereview/rule.json` | プロジェクトごとのルール。gitにコミット可能 | -| 3 | グローバル設定 | `~/.opencodereview/rule.json` | ユーザー全体の個人設定 | -| 4（最低） | システムデフォルト | 組み込みの`system_rules.json` | 一般的な言語とファイルタイプをカバーする組み込みルール | - -### ルールファイルの形式 - -第1〜3層は同じJSON形式を共有します： - -```json -{ - "rules": [ - { - "path": "force-api/**/*.java", - "rule": "All new methods must validate required parameters for null values", - "merge_system_rule": true - }, - { - "path": "**/*mapper*.xml", - "rule": "Check SQL for injection risks, parameter errors, and missing closing tags" - } - ] -} -``` - -- `path`は`**`による再帰マッチと`{java,kt}`のブレース展開をサポートします。 -- `merge_system_rule`は任意です。`true`の場合、一致した組み込みシステムルールがこのユーザールールとマージされます。 -- 各層の中では、ルールは宣言順に評価されます — 最初にマッチしたものが採用されます。 -- ルールファイルが存在しない場合は、何も出力せずスキップされます。 - -**`rule` フィールドはインラインコンテンツとファイルパスの両方をサポートします。** システムは次の順序で自動判別します： - -1. 値に改行が含まれる → **インラインコンテンツ**（複数行ルールがファイルパスと見なされることはありません）。 -2. 値が単一行で、スペースを含まず、`.md` / `.txt` / `.markdown` で終わる → **ファイルパス**。 - - 絶対パス（`/` で始まる）はそのまま使用されます。 - - 相対パスはプロジェクトルートで解決されます。パストラバーサル（例: `../../etc/passwd.md`）はブロックされます。見つからない場合は `[WARN]` を出力し、ルールはクリアされます（インラインへのフォールバックなし）。 - - ファイルはバリデーションを通過する必要があります：ホワイトリスト拡張子、≤ 512 KB、シンボリックリンク解決後のターゲットもホワイトリスト拡張子であること。バリデーションに失敗した場合、ルールはクリアされます。 -3. それ以外 → **インラインコンテンツ**。 - -```json -{ - "rules": [ - { - "path": "**/*mapper*.xml", - "rule": "docs/sql-rules.md" - }, - { - "path": "**/*.java", - "rule": "Always check for null safety and resource leaks" - }, - { - "path": "**/*.go", - "rule": "shared/go-concurrency.md" - }, - { - "path": "**/*.py", - "rule": "/Users/me/team-rules/python.md" - } - ] -} -``` - -- `docs/sql-rules.md` — 相対パス、`/docs/sql-rules.md` から読み込み。 -- `Always check for null safety…` — インライン文字列、そのまま使用。 -- `shared/go-concurrency.md` — 相対パス、同様に解決。 -- `/Users/me/team-rules/python.md` — 絶対パス、そのまま使用。 - -> 絶対パスはプロジェクト外のファイルにアクセスできますが、これは意図的な設計です。`rule.json` はメンテナが作成する信頼された入力のためです。共有ルールを共通パス（例：`/opt/company-rules/`）に置くことで、各プロジェクトへのコピーが不要になります。 - -### パスフィルタリング - -ルールファイルでは `include` と `exclude` フィールドも使用でき、どのファイルをレビュー対象にするかを制御できます： - -```json -{ - "rules": [ - {"path": "**/*.java", "rule": "null安全性をチェック"} - ], - "include": ["src/main/**/*.java", "lib/**/*.kt"], - "exclude": ["**/generated/**", "vendor/**"] -} -``` - -**フィルタ判定の優先度（高い順）：** - -| ステップ | 条件 | 結果 | -|------|-----------|--------| -| 1 | ファイルがバイナリ | 除外 | -| 2 | パスがユーザーの`exclude`パターンにマッチ | 除外 | -| 3 | ファイル拡張子がサポートリストにない | 除外 | -| 4 | `include`が設定されており、パスがマッチ | **レビュー対象**（ステップ5をスキップ） | -| 5 | パスが組み込みデフォルト除外パターン（テストファイル等）にマッチ | 除外 | -| 6 | 上記のいずれにも該当しない | レビュー対象 | - -**動作ロジック：** - -- `include`と`exclude`はレビュールールと同じ優先度チェーン（`--rule` > プロジェクト設定 > グローバル設定）に従います。**include/excludeが設定されている最も高い優先度の層**が一括で適用され、層を跨いだマージは行われません。 -- `exclude`は常に`include`より優先されます — 両方にマッチするファイルは除外されます。 -- `include`は**組み込みデフォルト除外パターンをバイパスする**ためのものであり（例：テストファイル）、排他的な許可リストではありません — `include`パターンにマッチしないファイルも通常通りデフォルトフィルタチェックに進みます。 -- パターン構文：`**`再帰マッチ、`*`単一セグメントマッチ、`{a,b}`ブレース展開をサポート。マッチングは大文字小文字を区別しません。 - -**組み込みデフォルト除外パターン**（テストファイル等をフィルタ — `include`でオーバーライド可能）： - -``` -**/*_test.go, **/*Test.java, **/*Tests.java, **/*_test.rs, -**/*.test.{js,jsx,ts,tsx}, **/*.spec.{js,jsx,ts,tsx}, **/__tests__/**, -**/src/test/java/**/*.java, **/src/test/**/*.kt, -**/test/**/*_test.py, **/tests/**/*_test.py, **/*_test.py, -**/*_spec.rb, **/spec/**/*_spec.rb, **/oh_modules/** -``` +OCR は 4 層の優先順位チェーン（`--rule` フラグ > プロジェクト設定 > グローバル設定 > 組み込みデフォルト）でレビュールールを解決し、インラインまたはファイルベースのルール、`**` グロブマッチング、`include` / `exclude` のパスフィルタリングをサポートします。ルールファイルの完全な形式とフィルタリングの意味については、**[レビュールール](https://open-codereview.ai/docs/review-rules)** を参照してください。 ## 設定リファレンス -設定ファイル：`~/.opencodereview/config.json` - -| キー | 型 | 例 | -|-----|------|---------| -| `provider` | string | `anthropic` \| `openai` \| `dashscope` \| `deepseek` \| `z-ai` | -| `providers..api_key` | string | プロバイダー固有のAPIキー | -| `providers..url` | string | プロバイダーのベースURLオーバーライド | -| `providers..protocol` | string | `anthropic` \| `openai` \| `openai-responses` | -| `providers..model` | string | プロバイダーのモデル名 | -| `providers..models` | array | 対話的選択に使う任意のプロバイダーモデル一覧 | -| `providers..auth_header` | string | `x-api-key` \| `authorization` | -| `providers..extra_body` | object | すべてのリクエストボディにマージされるJSONオブジェクト | -| `providers..timeout_sec` | integer | リクエストごとのHTTPタイムアウト（秒）、デフォルト `300` | -| `providers..extra_headers` | string | カンマ区切りの `key=value` HTTPヘッダー | -| `custom_providers..*` | — | 任意の`models`を含む`providers..*`と同じフィールド | -| `llm.url` | string | `https://api.openai.com/v1/chat/completions` | -| `llm.auth_token` | string | `sk-xxxxxxx` | -| `llm.auth_header` | string | Anthropicのみ：`x-api-key` \| `authorization` | -| `llm.extra_body` | object | すべてのリクエストボディにマージされるJSONオブジェクト | -| `llm.timeout_sec` | integer | リクエストごとのHTTPタイムアウト（秒）、デフォルト `300` | -| `llm.extra_headers` | string | カンマ区切りの `key=value` HTTPヘッダー | -| `llm.model` | string | `claude-opus-4-6` | -| `llm.protocol` | string | `anthropic` \| `openai` \| `openai-responses`；`llm.use_anthropic` より優先 | -| `llm.use_anthropic` | boolean | `true` \| `false`（レガシー；`llm.protocol` を推奨） | -| `mcp_servers..command` | string | MCPサーバーを起動するコマンド | -| `mcp_servers..args` | array | MCPサーバーのコマンドライン引数 | -| `mcp_servers..env` | array | 環境変数（`KEY=VALUE`形式） | -| `mcp_servers..tools` | array | 許可するツール名（空の場合はすべてのツール） | -| `mcp_servers..setup` | string | サーバー起動前に実行するセットアップコマンド | -| `language` | string | 任意の言語名、例：`English`、`Chinese`（デフォルト：`English`） | -| `telemetry.enabled` | boolean | `true` \| `false` | -| `telemetry.exporter` | string | `console` \| `otlp` | -| `telemetry.otlp_endpoint` | string | OTLPコレクターのアドレス | -| `telemetry.content_logging` | boolean | テレメトリーにプロンプトを含める | - -環境変数は設定ファイルより優先されます。 - -### MCPサーバー - -Open Code Reviewは[Model Context Protocol (MCP)](https://modelcontextprotocol.io/)サーバーをサポートしており、レビューエージェントがstdioトランスポートを介してコードレビュー中に外部ツールを使用できます。 - -CLIからMCPサーバーを設定します： - -```bash -# MCPサーバーを追加 -ocr config set mcp_servers..command -ocr config set mcp_servers..args '["arg1","arg2"]' -ocr config set mcp_servers..env '["KEY=VALUE"]' -ocr config set mcp_servers..tools '["tool_name"]' -ocr config set mcp_servers..setup '' - -# MCPサーバーを削除 -ocr config unset mcp_servers. -``` - -| フィールド | 必須 | 説明 | -|-----------|------|------| -| `command` | はい | MCPサーバーを起動する実行コマンド | -| `args` | いいえ | サーバーに渡すコマンドライン引数 | -| `env` | いいえ | 環境変数（`KEY=VALUE`形式） | -| `tools` | いいえ | 許可するツール名。空の場合、サーバーのすべてのツールが利用可能 | -| `setup` | いいえ | サーバー起動前に実行するシェルコマンド（例：インデックスの構築） | - -> **注意：** MCPツールの名前が組み込みツールと競合する場合、そのツールは警告付きでスキップされます。`setup`コマンドのタイムアウトは5分です。 - -**例：[CodeGraph](https://github.com/nicholasgasior/codegraph)を追加してコード構造分析を強化** - -```bash -ocr config set mcp_servers.codegraph.command codegraph -ocr config set mcp_servers.codegraph.args '["serve","--mcp"]' -ocr config set mcp_servers.codegraph.tools '["codegraph_explore"]' -ocr config set mcp_servers.codegraph.setup 'codegraph init && codegraph index' -``` - -### 環境変数 - -| 変数 | 用途 | -|----------|---------| -| `OCR_LLM_URL` | LLM APIエンドポイントURL | -| `OCR_LLM_TOKEN` | APIキー / 認証トークン | -| `OCR_LLM_AUTH_HEADER` | Anthropic認証ヘッダー（`x-api-key`または`authorization`） | -| `OCR_LLM_EXTRA_HEADERS` | カンマ区切りの `key=value` HTTPヘッダー | -| `OCR_LLM_MODEL` | モデル名 | -| `OCR_LLM_PROTOCOL` | プロトコル：`anthropic` \| `openai` \| `openai-responses`；`OCR_USE_ANTHROPIC` より優先 | -| `OCR_LLM_TIMEOUT` | リクエストごとのHTTPタイムアウト（秒）、設定ファイルの `timeout_sec` を上書き | -| `OCR_USE_ANTHROPIC` | `true` = Anthropic、`false` = OpenAI Chat Completions（レガシー；`OCR_LLM_PROTOCOL` を推奨） | +設定は `~/.opencodereview/config.json` にあり、環境変数で上書きできます。プロバイダー、モデル、MCP サーバー、言語、テレメトリーをカバーします。設定キーの完全なリファレンス、環境変数、MCP サーバーのセットアップについては、**[設定](https://open-codereview.ai/docs/configuration)** と **[MCP サーバー](https://open-codereview.ai/docs/mcp)** を参照してください。 ## テレメトリー diff --git a/README.ko-KR.md b/README.ko-KR.md index a214884b..a8db002d 100644 --- a/README.ko-KR.md +++ b/README.ko-KR.md @@ -514,129 +514,23 @@ GitHub의 경우, 이 리포지터리는 루트에 바로 사용할 수 있는 c 재현성을 위해 version tag나 commit SHA에 고정하세요. 전체 workflow 데모와 inputs/outputs, comment 게시 모드(sticky summary, incremental non-destructive posting)의 전체 목록은 [`examples/github_actions/`](./examples/github_actions/) 디렉터리를 참고하세요. -## Commands +## Documentation -| Command | Alias | Description | -|---------|-------|-------------| -| `ocr review` | `ocr r` | diff 기반 코드 리뷰 시작 | -| `ocr scan` | `ocr s` | 전체 파일 리뷰 (diff 불필요) | -| `ocr delegate preview` | `ocr d preview` | 리뷰 대상 파일 목록을 모드/참조 메타데이터와 함께 출력 (LLM 불필요) | -| `ocr delegate rule ` | `ocr d rule` | 내용별로 그룹화된 리뷰 규칙 출력 (LLM 불필요) | -| `ocr rules check ` | - | 파일 경로에 적용될 리뷰 rule 미리보기 | -| `ocr config provider` | - | 대화형 provider 설정 (built-in, custom, 수동) | -| `ocr config model` | - | 활성 provider의 대화형 model 선택 | -| `ocr config set ` | - | config 값 설정 | -| `ocr config unset custom_providers.` | - | custom provider 삭제 | -| `ocr llm test` | - | LLM 연결 테스트 | -| `ocr llm providers` | - | built-in LLM provider 목록 표시 | -| `ocr session list` | `ocr sessions list`, `ocr session ls` | 저장된 review session 목록 표시 | -| `ocr session show ` | `ocr sessions show ` | 단일 session과 파일별 checkpoint 확인 | -| `ocr viewer` | `ocr v` | `localhost:5483`에서 WebUI session viewer 실행 | -| `ocr version` | - | version 정보 표시 | - -### `ocr review` Flags - -| Flag | Shorthand | Default | Description | -|------|-----------|---------|-------------| -| `--repo` | - | current dir | Git repository root | -| `--from` | - | - | Source ref 예: `main` | -| `--to` | - | - | Target ref 예: `feature-branch` | -| `--commit` | `-c` | - | 리뷰할 단일 commit | -| `--exclude` | - | - | 건너뛸 파일의 쉼표 구분 gitignore 스타일 패턴; rule.json의 excludes와 병합 | -| `--preview` | `-p` | `false` | LLM 실행 없이 리뷰 대상 파일 미리보기 | -| `--resume` | - | - | 이전의 호환되는 range 또는 단일 commit review session에서 재개 | -| `--format` | `-f` | `text` | Output format: `text` 또는 `json` | -| `--concurrency` | - | `8` | 최대 동시 파일 리뷰 수 | -| `--timeout` | - | `10` | 동시 task timeout(분) | -| `--audience` | - | `human` | `human`(progress 표시) 또는 `agent`(summary only) | -| `--background` | `-b` | - | 리뷰를 위한 선택적 요구사항/비즈니스 컨텍스트. `--commit` 사용 시 미지정이면 commit message에서 자동 추출 | -| `--background-file` | `-B` | - | Markdown 파일에서 읽어오는 선택적 요구사항/비즈니스 컨텍스트. `--background`와 함께 사용하면 inline 값이 먼저 배치됩니다 | -| `--model` | - | - | 이번 리뷰에서 LLM model 선택 또는 override | -| `--rule` | - | - | custom JSON review rules 경로 | -| `--max-tools` | - | built-in | 파일별 최대 tool call round. template default보다 클 때만 적용 | -| `--max-git-procs` | - | built-in | 최대 동시 git subprocess 수 | -| `--tools` | - | - | custom JSON tools config 경로 | - -#### Resumable Reviews and Sessions - -모든 `ocr review` 실행은 `~/.opencodereview/sessions/` 아래에 local session log를 저장합니다. -정상 완료된 text output은 review 결과에 집중하며 session ID를 출력하지 않습니다. -저장된 session은 `ocr session list/show`로 찾을 수 있고, `--format json`을 사용하면 -machine-readable output에 `session_id`가 포함됩니다. range 또는 단일 commit review가 중단된 경우, -저장된 session을 나열한 뒤 동일한 review target과 일치하는 session에서 재개합니다. +전체 문서는 **[open-codereview.ai/docs](https://open-codereview.ai/docs)** 에서 확인할 수 있습니다: -```bash -ocr session list -ocr session show -ocr review --from main --to feature-branch --resume -ocr review --commit abc123 --resume -``` +- [빠른 시작](https://open-codereview.ai/docs/quickstart) — 설치하고 첫 리뷰 실행하기 +- [설치](https://open-codereview.ai/docs/installation) — 모든 플랫폼 및 패키지 매니저 +- [CLI 레퍼런스](https://open-codereview.ai/docs/cli-reference) — 모든 명령어와 플래그 +- [리뷰 규칙](https://open-codereview.ai/docs/review-rules) — 규칙 우선순위 체인, 파일 형식, 경로 필터링 +- [설정](https://open-codereview.ai/docs/configuration) — 설정 키와 환경 변수 +- [MCP 서버](https://open-codereview.ai/docs/mcp) — 외부 도구로 리뷰 에이전트 확장 +- [코딩 에이전트 연동](https://open-codereview.ai/docs/claude-code) — Claude Code, Agent Skill, 위임 모드 +- [CI/CD 연동](https://open-codereview.ai/docs/cicd) — 파이프라인에서 리뷰 실행 +- [아키텍처](https://open-codereview.ai/docs/architecture) · [도구](https://open-codereview.ai/docs/tools) · [세션 뷰어](https://open-codereview.ai/docs/viewer) · [텔레메트리](https://open-codereview.ai/docs/telemetry) · [FAQ](https://open-codereview.ai/docs/faq) + +## Commands -Resume은 의도적으로 엄격합니다. branch range와 단일 commit review만 지원하고 workspace review는 지원하지 않습니다. -현재 `--from/--to` 또는 `--commit`은 저장된 session과 일치해야 합니다. `--preview`와 `--resume`은 함께 사용할 수 없습니다. - -`--format json`을 사용하면 재개된 run에는 다음 field가 포함됩니다. - -- `session_id`: 현재 run의 session ID -- `resume.resumed_from`: source session ID -- `resume.reused_files`: 저장된 checkpoint에서 재사용한 파일 수 -- `resume.rerun_files`: 현재 run에서 다시 review한 파일 수 - -### `ocr session` Flags - -| Command | Flag | Default | Description | -|---------|------|---------|-------------| -| `ocr session list` | `--repo` | current dir | session을 나열할 repository | -| `ocr session list` | `--json` | `false` | session summary를 JSON으로 출력 | -| `ocr session list` | `--limit` | `20` | 나열할 session 수 제한. `0`은 unlimited | -| `ocr session show ` | `--repo` | current dir | 확인할 session의 repository | -| `ocr session show ` | `--json` | `false` | session metadata와 파일별 item을 JSON으로 출력 | - -### `ocr scan` Flags - -`ocr scan`은 diff가 아닌 전체 파일을 리뷰합니다 — 익숙하지 않은 코드베이스 감사, 마이그레이션 전 스캔, 의미 있는 diff가 없는 디렉터리 등에 유용합니다. 비-git 디렉터리에서도 작동합니다 (`.gitignore`를 따르는 파일 시스템 탐색으로 폴백). - -| Flag | Shorthand | Default | Description | -|------|-----------|---------|-------------| -| `--path` | - | 전체 repo | 스캔할 쉼표 구분 디렉터리/파일 | -| `--exclude` | - | - | 건너뛸 파일의 쉼표 구분 gitignore 스타일 패턴; rule.json의 excludes와 병합 | -| `--preview` | `-p` | `false` | LLM 실행 없이 스캔 대상 파일 목록 표시 | -| `--max-tokens-budget` | - | `0` (무제한) | 총 토큰 사용량 제한; 초과 시 dispatch 중단 | -| `--no-plan` | - | `false` | 파일별 planning 사전 처리 건너뛰기 | -| `--no-dedup` | - | `false` | 배치별 유사 comment 중복 제거 건너뛰기 | -| `--no-summary` | - | `false` | 프로젝트 수준 요약 건너뛰기 | -| `--batch` | - | `by-language` | 배치 전략: `none`, `by-language`, 또는 `by-directory` | -| `--format` | `-f` | `text` | Output format: `text` 또는 `json` (JSON에 `project_summary` 필드 포함) | -| `--concurrency` | - | `8` | 최대 동시 파일 스캔 수 | -| `--rule` | - | - | custom JSON review rules 경로 | -| `--repo` | - | current dir | 스캔할 repository 또는 디렉터리 루트 | - -각 실행 전에 `ocr scan`은 대략적인 토큰 비용 추정치를 출력합니다. `--preview`로 먼저 파일 목록을 확인하고, `--max-tokens-budget`으로 대규모 repository의 비용을 제한할 수 있습니다. - -### `ocr delegate` 플래그 - -`ocr delegate`는 AI 코딩 에이전트를 위한 위임 모드입니다. LLM을 호출하지 않고 -결정론적인 파일 선택과 규칙 해석을 제공합니다 — 실제 리뷰는 호스트 에이전트가 -자체 능력으로 수행합니다. - -| 하위 명령 | 설명 | -|-----------|------| -| `ocr delegate preview` | 리뷰 대상 파일 목록을 모드/참조 메타데이터와 함께 출력 | -| `ocr delegate rule ` | 내용별로 그룹화된 리뷰 규칙 출력 | - -두 하위 명령은 다음 플래그를 공유합니다: - -| 플래그 | 축약형 | 기본값 | 설명 | -|--------|--------|--------|------| -| `--repo` | — | 현재 디렉터리 | Git 저장소 루트 | -| `--from` | — | — | 소스 참조 (예: `main`) | -| `--to` | — | — | 대상 참조 (예: `feature-branch`) | -| `--commit` | `-c` | — | 단일 커밋 | -| `--exclude` | — | — | 쉼표로 구분된 gitignore 스타일 제외 패턴 | -| `--rule` | — | — | 커스텀 JSON 리뷰 규칙 경로 | -| `--background` | `-b` | — | 선택적 요구사항/비즈니스 컨텍스트 | -| `--background-file` | `-B` | — | Markdown 파일에서 비즈니스 컨텍스트 로드 | -| `--max-git-procs` | — | `16` | 최대 동시 git 하위 프로세스 수 | +OCR는 `review`, `scan`, `delegate`, `config`, `llm`, `session`, `viewer` 등의 명령어를 제공합니다. 전체 명령어 목록과 모든 플래그(재개 가능한 리뷰 및 `ocr scan` / `ocr delegate`의 전체 옵션 포함)는 **[CLI 레퍼런스](https://open-codereview.ai/docs/cli-reference)** 를 참조하세요. ## Examples @@ -726,167 +620,11 @@ OCR_VIEWER_ALLOWED_HOSTS=review.internal,ocr.lan ocr viewer --addr :3000 ## Review Rules -OCR은 네 계층의 priority chain으로 review rule을 해석합니다. 각 계층은 first-match-wins 방식입니다. 파일 경로가 pattern에 match되면 해당 rule을 사용하고, 아니면 다음 계층으로 넘어갑니다. - -| Priority | Source | Path | Description | -|----------|--------|------|-------------| -| 1 (highest) | `--rule` flag | User-specified path | CLI explicit override | -| 2 | Project config | `/.opencodereview/rule.json` | project별 rule, git commit 가능 | -| 3 | Global config | `~/.opencodereview/rule.json` | user-wide 개인 선호 | -| 4 (lowest) | System default | Embedded `system_rules.json` | 일반 language와 file type을 다루는 built-in rule | - -### Rule File Format - -모든 계층은 같은 JSON format을 공유합니다. - -```json -{ - "rules": [ - { - "path": "force-api/**/*.java", - "rule": "All new methods must validate required parameters for null values", - "merge_system_rule": true - }, - { - "path": "**/*mapper*.xml", - "rule": "Check SQL for injection risks, parameter errors, and missing closing tags" - } - ] -} -``` - -- `path`는 `**` recursive matching과 `{java,kt}` brace expansion을 지원합니다. -- `merge_system_rule`은 optional입니다. `true`이면 매칭된 built-in system rule을 이 user rule과 병합합니다. -- 각 계층 안에서는 rule이 선언 순서대로 평가되며 첫 번째 match가 선택됩니다. -- rule file이 없으면 조용히 건너뜁니다. - -**`rule` 필드는 인라인 콘텐츠와 파일 경로를 모두 지원합니다.** 시스템이 다음 순서로 자동 판별합니다: - -1. 값에 줄바꿈이 포함된 경우 → **인라인 콘텐츠** (여러 줄 규칙은 파일 경로로 간주되지 않습니다). -2. 값이 한 줄이고 공백이 없으며 `.md` / `.txt` / `.markdown`으로 끝나는 경우 → **파일 경로**. - - 절대 경로(`/`로 시작)는 그대로 사용됩니다. - - 상대 경로는 프로젝트 루트에서 확인합니다. 경로 탐색(예: `../../etc/passwd.md`)은 차단됩니다. 없으면 `[WARN]`을 출력하고 규칙이 지워집니다 (인라인으로 폴백 없음). - - 파일은 유효성 검사를 통과해야 합니다: 허용된 확장자, ≤ 512 KB, 심볼릭 링크 해석 후 대상도 허용된 확장자여야 합니다. 검증 실패 시 규칙이 지워집니다. -3. 그 외의 경우 → **인라인 콘텐츠**. - -```json -{ - "rules": [ - { - "path": "**/*mapper*.xml", - "rule": "docs/sql-rules.md" - }, - { - "path": "**/*.java", - "rule": "Always check for null safety and resource leaks" - }, - { - "path": "**/*.go", - "rule": "shared/go-concurrency.md" - }, - { - "path": "**/*.py", - "rule": "/Users/me/team-rules/python.md" - } - ] -} -``` - -- `docs/sql-rules.md` — 상대 경로, `/docs/sql-rules.md`에서 로드. -- `Always check for null safety…` — 인라인 문자열, 그대로 사용. -- `shared/go-concurrency.md` — 상대 경로, 동일하게 해결. -- `/Users/me/team-rules/python.md` — 절대 경로, 그대로 사용. - -> 절대 경로는 프로젝트 외부 파일에 접근할 수 있으며, 이는 의도된 설계입니다. `rule.json`은 프로젝트 메인테이너가 작성하는 신뢰된 입력입니다. 팀은 공유 규칙을 공통 경로(예: `/opt/company-rules/`)에 두어 각 프로젝트에 복사할 필요가 없습니다. +OCR는 4단계 우선순위 체인(`--rule` 플래그 > 프로젝트 설정 > 전역 설정 > 내장 기본값)으로 리뷰 규칙을 해석하며, 인라인 또는 파일 기반 규칙, `**` glob 매칭, `include` / `exclude` 경로 필터링을 지원합니다. 전체 규칙 파일 형식과 필터링 동작은 **[리뷰 규칙](https://open-codereview.ai/docs/review-rules)** 을 참조하세요. ## Configuration Reference -Config file: `~/.opencodereview/config.json` - -| Key | Type | Example | -|-----|------|---------| -| `provider` | string | `anthropic` \| `openai` \| `dashscope` \| `deepseek` \| `z-ai` | -| `providers..api_key` | string | Provider별 API key | -| `providers..url` | string | Provider base URL override | -| `providers..protocol` | string | `anthropic` \| `openai` \| `openai-responses` | -| `providers..model` | string | Provider의 model 이름 | -| `providers..models` | array | 대화형 선택에 사용할 optional provider model 목록 | -| `providers..auth_header` | string | `x-api-key` \| `authorization` | -| `providers..extra_body` | object | 모든 요청 본문에 병합되는 JSON 객체 | -| `providers..timeout_sec` | integer | 요청당 HTTP timeout(초), 기본값 `300` | -| `providers..extra_headers` | string | 쉼표로 구분된 `key=value` HTTP 헤더 | -| `custom_providers..*` | — | optional `models`를 포함한 `providers..*`과 동일한 필드 | -| `llm.url` | string | `https://api.openai.com/v1/chat/completions` | -| `llm.auth_token` | string | `sk-xxxxxxx` | -| `llm.auth_header` | string | Anthropic only: `x-api-key` \| `authorization` | -| `llm.extra_body` | object | 모든 요청 본문에 병합되는 JSON 객체 | -| `llm.timeout_sec` | integer | 요청당 HTTP timeout(초), 기본값 `300` | -| `llm.extra_headers` | string | 쉼표로 구분된 `key=value` HTTP 헤더 | -| `llm.model` | string | `claude-opus-4-6` | -| `llm.protocol` | string | `anthropic` \| `openai` \| `openai-responses`; `llm.use_anthropic`보다 우선 | -| `llm.use_anthropic` | boolean | `true` \| `false` (레거시; `llm.protocol` 권장) | -| `mcp_servers..command` | string | MCP 서버를 시작하는 명령어 | -| `mcp_servers..args` | array | MCP 서버의 커맨드라인 인수 | -| `mcp_servers..env` | array | 환경 변수 (`KEY=VALUE` 형식) | -| `mcp_servers..tools` | array | 허용할 도구 이름 (비어 있으면 모든 도구 허용) | -| `mcp_servers..setup` | string | 서버 시작 전에 실행할 설정 명령어 | -| `language` | string | 임의의 언어 이름, 예: `English`, `Chinese` (기본값: `English`) | -| `telemetry.enabled` | boolean | `true` \| `false` | -| `telemetry.exporter` | string | `console` \| `otlp` | -| `telemetry.otlp_endpoint` | string | OTLP collector address | -| `telemetry.content_logging` | boolean | telemetry에 prompt 포함 여부 | - -환경 변수는 config file보다 우선합니다. - -### MCP Server - -Open Code Review는 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 서버를 지원하여 리뷰 에이전트가 stdio 전송을 통해 코드 리뷰 중에 외부 도구를 사용할 수 있습니다. - -CLI로 MCP 서버를 설정합니다: - -```bash -# MCP 서버 추가 -ocr config set mcp_servers..command -ocr config set mcp_servers..args '["arg1","arg2"]' -ocr config set mcp_servers..env '["KEY=VALUE"]' -ocr config set mcp_servers..tools '["tool_name"]' -ocr config set mcp_servers..setup '' - -# MCP 서버 삭제 -ocr config unset mcp_servers. -``` - -| 필드 | 필수 | 설명 | -|------|------|------| -| `command` | 예 | MCP 서버를 시작하는 실행 명령어 | -| `args` | 아니오 | 서버에 전달할 커맨드라인 인수 | -| `env` | 아니오 | 환경 변수 (`KEY=VALUE` 형식) | -| `tools` | 아니오 | 허용할 도구 이름. 비어 있으면 서버의 모든 도구 사용 가능 | -| `setup` | 아니오 | 서버 시작 전에 실행할 셸 명령어 (예: 인덱스 빌드) | - -> **참고:** MCP 도구의 이름이 내장 도구와 충돌하면 경고와 함께 건너뜁니다. `setup` 명령어의 타임아웃은 5분입니다. - -**예시: [CodeGraph](https://github.com/nicholasgasior/codegraph)를 추가하여 코드 구조 분석 강화** - -```bash -ocr config set mcp_servers.codegraph.command codegraph -ocr config set mcp_servers.codegraph.args '["serve","--mcp"]' -ocr config set mcp_servers.codegraph.tools '["codegraph_explore"]' -ocr config set mcp_servers.codegraph.setup 'codegraph init && codegraph index' -``` - -### Environment Variables - -| Variable | Purpose | -|----------|---------| -| `OCR_LLM_URL` | LLM API endpoint URL | -| `OCR_LLM_TOKEN` | API key / auth token | -| `OCR_LLM_AUTH_HEADER` | Anthropic auth header (`x-api-key` 또는 `authorization`) | -| `OCR_LLM_EXTRA_HEADERS` | 쉼표로 구분된 `key=value` HTTP 헤더 | -| `OCR_LLM_MODEL` | Model name | -| `OCR_LLM_PROTOCOL` | 프로토콜: `anthropic` \| `openai` \| `openai-responses`; `OCR_USE_ANTHROPIC`보다 우선 | -| `OCR_LLM_TIMEOUT` | 요청당 HTTP timeout(초), config file의 `timeout_sec`를 override | -| `OCR_USE_ANTHROPIC` | `true` = Anthropic, `false` = OpenAI Chat Completions (레거시; `OCR_LLM_PROTOCOL` 권장) | +설정은 `~/.opencodereview/config.json`에 저장되며 환경 변수로 재정의할 수 있습니다. 프로바이더, 모델, MCP 서버, 언어, 텔레메트리를 다룹니다. 전체 설정 키 레퍼런스, 환경 변수, MCP 서버 설정은 **[설정](https://open-codereview.ai/docs/configuration)** 및 **[MCP 서버](https://open-codereview.ai/docs/mcp)** 를 참조하세요. ## Telemetry diff --git a/README.md b/README.md index 6724c323..4de72de3 100644 --- a/README.md +++ b/README.md @@ -516,134 +516,23 @@ For GitHub, this repository also ships a ready-to-use composite Action at the re Pin to a version tag or commit SHA for reproducibility. See the [`examples/github_actions/`](./examples/github_actions/) directory for a complete workflow demo and the full list of inputs, outputs, and comment-posting modes (sticky summary, incremental non-destructive posting). -## Commands +## Documentation -| Command | Alias | Description | -|---------|-------|-------------| -| `ocr review` | `ocr r` | Start a diff-based code review | -| `ocr scan` | `ocr s` | Review whole files (no diff required) | -| `ocr delegate preview` | `ocr d preview` | Preview reviewable files with mode/ref metadata (no LLM required) | -| `ocr delegate rule ` | `ocr d rule` | Output resolved review rules grouped by content (no LLM required) | -| `ocr rules check ` | — | Preview which review rule applies to a file path | -| `ocr config provider` | — | Interactive provider setup (built-in, custom, or manual) | -| `ocr config model` | — | Interactive model selection for the active provider | -| `ocr config set ` | — | Set configuration values | -| `ocr config unset custom_providers.` | — | Delete a custom provider | -| `ocr llm test` | — | Test LLM connectivity | -| `ocr llm providers` | — | List built-in LLM providers | -| `ocr session list` | `ocr sessions list`, `ocr session ls` | List saved review sessions | -| `ocr session show ` | `ocr sessions show ` | Inspect one session and its per-file checkpoints | -| `ocr viewer` | `ocr v` | Launch WebUI session viewer on `localhost:5483` | -| `ocr version` | — | Show version info | - -### `ocr review` Flags - -| Flag | Shorthand | Default | Description | -|------|-----------|---------|-------------| -| `--repo` | — | current dir | Git repository root | -| `--from` | — | — | Source ref (e.g., `main`) | -| `--to` | — | — | Target ref (e.g., `feature-branch`) | -| `--commit` | `-c` | — | Single commit to review | -| `--exclude` | — | — | Comma-separated gitignore-style patterns to skip; merged with rule.json excludes | -| `--preview` | `-p` | `false` | Preview which files will be reviewed without running the LLM | -| `--resume` | — | — | Resume from a previous compatible range or commit review session | -| `--format` | `-f` | `text` | Output format: `text` or `json` | -| `--concurrency` | — | `8` | Max concurrent file reviews | -| `--timeout` | — | `10` | Concurrent task timeout in minutes | -| `--audience` | — | `human` | `human` (show progress) or `agent` (summary only) | -| `--background` | `-b` | — | Optional requirement/business context for the review; auto-filled from commit message when using `--commit` | -| `--background-file` | `-B` | — | Optional requirement/business context from a Markdown file; Combined with `--background` the inline value is given first | -| `--model` | — | — | Select or override the LLM model for this review | -| `--rule` | — | — | Path to custom JSON review rules | -| `--max-tools` | — | built-in | Max tool call rounds per file; only takes effect when greater than template default | -| `--max-git-procs` | — | `16` | Max concurrent git subprocesses | -| `--tools` | — | built-in | Path to custom JSON tools config | - -#### Resumable Reviews and Sessions - -Every `ocr review` run persists a local session log under -`~/.opencodereview/sessions/`. Successful text output stays focused on review -results and does not print the session ID; use `ocr session list/show` to find -saved sessions, or `--format json` to include `session_id` in machine-readable -output. If a range or commit review is interrupted, list the saved sessions and -resume from the one that matches the same review target: +Full documentation lives at **[open-codereview.ai/docs](https://open-codereview.ai/docs)**: -```bash -ocr session list -ocr session show -ocr review --from main --to feature-branch --resume -ocr review --commit abc123 --resume -``` +- [Quickstart](https://open-codereview.ai/docs/quickstart) — install and run your first review +- [Installation](https://open-codereview.ai/docs/installation) — all platforms and package managers +- [CLI Reference](https://open-codereview.ai/docs/cli-reference) — every command and flag +- [Review Rules](https://open-codereview.ai/docs/review-rules) — rule priority chain, file format, and path filtering +- [Configuration](https://open-codereview.ai/docs/configuration) — config keys and environment variables +- [MCP Server](https://open-codereview.ai/docs/mcp) — extend the review agent with external tools +- [Coding Agent Integrations](https://open-codereview.ai/docs/claude-code) — Claude Code, Agent Skill, and delegation mode +- [CI/CD Integration](https://open-codereview.ai/docs/cicd) — run reviews in your pipeline +- [Architecture](https://open-codereview.ai/docs/architecture) · [Tools](https://open-codereview.ai/docs/tools) · [Session Viewer](https://open-codereview.ai/docs/viewer) · [Telemetry](https://open-codereview.ai/docs/telemetry) · [FAQ](https://open-codereview.ai/docs/faq) -Resume is intentionally strict: it only supports branch-range and single-commit -reviews, not workspace reviews, and the current `--from/--to` or `--commit` -must match the saved session. `--preview` cannot be combined with `--resume`. - -When `--format json` is used, resumed runs include: - -- `session_id` — the current run's session ID -- `resume.resumed_from` — the source session ID -- `resume.reused_files` — files reused from saved checkpoints -- `resume.rerun_files` — files reviewed again in the current run - -### `ocr session` Flags - -| Command | Flag | Default | Description | -|---------|------|---------|-------------| -| `ocr session list` | `--repo` | current dir | Repository whose sessions should be listed | -| `ocr session list` | `--json` | `false` | Emit session summaries as JSON | -| `ocr session list` | `--limit` | `20` | Cap listed sessions; use `0` for unlimited | -| `ocr session show ` | `--repo` | current dir | Repository whose session should be inspected | -| `ocr session show ` | `--json` | `false` | Emit session metadata and per-file items as JSON | - -### `ocr scan` Flags - -`ocr scan` reviews entire files rather than a diff — useful for auditing an unfamiliar -codebase, a pre-migration sweep, or any directory with no meaningful diff. It works in -non-git directories too (it falls back to a filesystem walk that honors `.gitignore`). - -| Flag | Shorthand | Default | Description | -|------|-----------|---------|-------------| -| `--path` | — | whole repo | Comma-separated dirs/files to scan | -| `--exclude` | — | — | Comma-separated gitignore-style patterns to skip; merged with rule.json excludes | -| `--preview` | `-p` | `false` | List which files would be scanned without running the LLM | -| `--max-tokens-budget` | — | `0` (unlimited) | Cap total token usage; dispatch stops once exceeded | -| `--no-plan` | — | `false` | Skip the per-file planning pre-pass | -| `--no-dedup` | — | `false` | Skip per-batch de-duplication of similar comments | -| `--no-summary` | — | `false` | Skip the project-level summary | -| `--batch` | — | `by-language` | Batching strategy: `none`, `by-language`, or `by-directory` | -| `--format` | `-f` | `text` | Output format: `text` or `json` (JSON includes a `project_summary` field) | -| `--concurrency` | — | `8` | Max concurrent file scans | -| `--rule` | — | — | Path to custom JSON review rules | -| `--repo` | — | current dir | Repository or directory root to scan | - -Before each run, `ocr scan` prints a rough token-cost estimate. Use `--preview` to see the -file list first, and `--max-tokens-budget` to cap spend on large repositories. - -### `ocr delegate` Flags - -`ocr delegate` is the delegation mode for AI coding agents. It provides deterministic -file selection and rule resolution without calling any LLM — the host agent performs -the actual review using its own capabilities. - -| Sub-command | Description | -|-------------|-------------| -| `ocr delegate preview` | Output reviewable file list with mode/ref metadata | -| `ocr delegate rule ` | Output resolved review rules grouped by content | - -Both sub-commands share these flags: - -| Flag | Shorthand | Default | Description | -|------|-----------|---------|-------------| -| `--repo` | — | current dir | Git repository root | -| `--from` | — | — | Source ref (e.g., `main`) | -| `--to` | — | — | Target ref (e.g., `feature-branch`) | -| `--commit` | `-c` | — | Single commit to review | -| `--exclude` | — | — | Comma-separated gitignore-style patterns to skip | -| `--rule` | — | — | Path to custom JSON review rules | -| `--background` | `-b` | — | Optional requirement/business context | -| `--background-file` | `-B` | — | Business context from a Markdown file | -| `--max-git-procs` | — | `16` | Max concurrent git subprocesses | +## Commands + +OCR provides `review`, `scan`, `delegate`, `config`, `llm`, `session`, and `viewer` commands. For the complete command list and every flag — including resumable reviews and the full `ocr scan` / `ocr delegate` options — see the **[CLI Reference](https://open-codereview.ai/docs/cli-reference)**. ## Examples @@ -733,209 +622,11 @@ This blocks DNS-rebinding attacks against the local viewer. ## Review Rules -OCR resolves review rules using a four-layer priority chain. Each layer uses first-match-wins: if a file path matches a pattern, that rule is used; otherwise it falls through to the next layer. - -| Priority | Source | Path | Description | -|----------|--------|------|-------------| -| 1 (highest) | `--rule` flag | User-specified path | CLI explicit override | -| 2 | Project config | `/.opencodereview/rule.json` | Per-project rules, can be committed to git | -| 3 | Global config | `~/.opencodereview/rule.json` | User-wide personal preferences | -| 4 (lowest) | System default | Embedded `system_rules.json` | Built-in rules covering common languages and file types | - -### Rule File Format - -Layers 1–3 share the same JSON format: - -```json -{ - "rules": [ - { - "path": "force-api/**/*.java", - "rule": "All new methods must validate required parameters for null values", - "merge_system_rule": true - }, - { - "path": "**/*mapper*.xml", - "rule": "Check SQL for injection risks, parameter errors, and missing closing tags" - } - ] -} -``` - -- `path` supports `**` recursive matching and `{java,kt}` brace expansion. -- `merge_system_rule` is optional. When `true`, the matched built-in system rule is merged with this user rule; otherwise the user rule replaces the system rule. -- Within each layer, rules are evaluated in declaration order — the first match wins. -- If a rule file does not exist, it is silently skipped. - -**The `rule` field supports both inline content and file paths.** The system auto-detects which one you mean: - -1. If the value contains newlines → **inline content** (multi-line rules are never file paths). -2. If the value is a single line, contains no spaces, and ends with `.md` / `.txt` / `.markdown` → **file path**. - - Absolute paths (starting with `/`) are used directly. - - Relative paths are resolved against the project root. Path traversal (e.g. `../../etc/passwd.md`) is blocked. If not found, a `[WARN]` is emitted and the rule is cleared (no fallback to inline). - - The file must pass validation: whitelisted extension, ≤ 512 KB, and resolved symlink target must also be a whitelisted extension. If validation fails, the rule is cleared. -3. Otherwise → **inline content**. - -```json -{ - "rules": [ - { - "path": "**/*mapper*.xml", - "rule": "docs/sql-rules.md" - }, - { - "path": "**/*.java", - "rule": "Always check for null safety and resource leaks" - }, - { - "path": "**/*.go", - "rule": "shared/go-concurrency.md" - }, - { - "path": "**/*.py", - "rule": "/Users/me/team-rules/python.md" - } - ] -} -``` - -- `docs/sql-rules.md` — relative path, resolved from `/docs/sql-rules.md`. -- `Always check for null safety…` — inline string, used directly. -- `shared/go-concurrency.md` — relative path, same resolution. -- `/Users/me/team-rules/python.md` — absolute path, used directly. - -> Absolute paths can access files outside the project directory — this is intentional. `rule.json` is authored by project maintainers, i.e. trusted input. Teams can store shared rules at a common path (e.g. `/opt/company-rules/`) instead of copying them into every project. - -### Path Filtering - -Rule files also support `include` and `exclude` fields to control which files enter the review scope: - -```json -{ - "rules": [ - {"path": "**/*.java", "rule": "Check for null safety"} - ], - "include": ["src/main/**/*.java", "lib/**/*.kt"], - "exclude": ["**/generated/**", "vendor/**"] -} -``` - -**Filter decision priority (highest to lowest):** - -| Step | Condition | Result | -|------|-----------|--------| -| 1 | File is binary | Excluded | -| 2 | Path matches user `exclude` pattern | Excluded | -| 3 | File extension not in supported list | Excluded | -| 4 | `include` is configured and path matches | **Reviewed** (skips step 5) | -| 5 | Path matches built-in default exclude pattern (test files, etc.) | Excluded | -| 6 | None of the above | Reviewed | - -**How it works:** - -- `include` and `exclude` follow the same priority chain as review rules (`--rule` > project config > global config). The **highest-priority layer that has include/exclude configured** takes effect as a whole — patterns are not merged across layers. -- `exclude` always wins over `include` — a file matching both is excluded. -- `include` acts as a **bypass for built-in default exclude patterns** (e.g., test files), not as an exclusive allowlist — files not matching any `include` pattern still proceed through the default filter checks normally. -- Pattern syntax: supports `**` recursive matching, `*` single-segment matching, and `{a,b}` brace expansion. Matching is case-insensitive. - -**Built-in default exclude patterns** (filters test files, etc. — can be overridden with `include`): - -``` -**/*_test.go, **/*Test.java, **/*Tests.java, **/*_test.rs, -**/*.test.{js,jsx,ts,tsx}, **/*.spec.{js,jsx,ts,tsx}, **/__tests__/**, -**/src/test/java/**/*.java, **/src/test/**/*.kt, -**/test/**/*_test.py, **/tests/**/*_test.py, **/*_test.py, -**/*_spec.rb, **/spec/**/*_spec.rb, **/oh_modules/** -``` +OCR resolves review rules through a four-layer priority chain (`--rule` flag > project config > global config > built-in defaults), and supports inline or file-based rules, `**` glob matching, and `include` / `exclude` path filtering. For the full rule file format and filtering semantics, see **[Review Rules](https://open-codereview.ai/docs/review-rules)**. ## Configuration Reference -Config file: `~/.opencodereview/config.json` - -| Key | Type | Example | -|-----|------|---------| -| `provider` | string | `anthropic` \| `openai` \| `dashscope` \| `deepseek` \| `z-ai` | -| `providers..api_key` | string | Provider-specific API key | -| `providers..url` | string | Provider base URL override | -| `providers..protocol` | string | `anthropic` \| `openai` \| `openai-responses` | -| `providers..model` | string | Model name for the provider | -| `providers..models` | array | Optional provider model list for interactive selection | -| `providers..auth_header` | string | `x-api-key` \| `authorization` | -| `providers..extra_body` | object | JSON object merged into every request body | -| `providers..timeout_sec` | integer | Per-request HTTP timeout in seconds (default: `300`) | -| `providers..extra_headers` | string | Comma-separated `key=value` HTTP headers | -| `custom_providers..*` | — | Same fields as `providers..*`, including optional `models` | -| `llm.url` | string | `https://api.openai.com/v1/chat/completions` | -| `llm.auth_token` | string | `sk-xxxxxxx` | -| `llm.auth_header` | string | Anthropic only: `x-api-key` \| `authorization` | -| `llm.extra_body` | object | JSON object merged into every request body | -| `llm.timeout_sec` | integer | Per-request HTTP timeout in seconds (default: `300`) | -| `llm.extra_headers` | string | Comma-separated `key=value` HTTP headers | -| `llm.model` | string | `claude-opus-4-6` | -| `llm.protocol` | string | `anthropic` \| `openai` \| `openai-responses`; takes priority over `llm.use_anthropic` | -| `llm.use_anthropic` | boolean | `true` \| `false` (legacy; prefer `llm.protocol`) | -| `mcp_servers..command` | string | Command to start the MCP server | -| `mcp_servers..args` | array | Command-line arguments for the MCP server | -| `mcp_servers..env` | array | Environment variables in `KEY=VALUE` format | -| `mcp_servers..tools` | array | Allowed tool names (empty = all tools) | -| `mcp_servers..setup` | string | Setup command to run before starting the server | -| `language` | string | Any language name, e.g. `English`, `Chinese` (default: `English`) | -| `telemetry.enabled` | boolean | `true` \| `false` | -| `telemetry.exporter` | string | `console` \| `otlp` | -| `telemetry.otlp_endpoint` | string | OTLP collector address | -| `telemetry.content_logging` | boolean | Include prompts in telemetry | - -Environment variables take precedence over the config file. - -### MCP Server - -Open Code Review supports [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers, allowing the review agent to use external tools during code review via the stdio transport. - -Configure MCP servers via the CLI: - -```bash -# Add an MCP server -ocr config set mcp_servers..command -ocr config set mcp_servers..args '["arg1","arg2"]' -ocr config set mcp_servers..env '["KEY=VALUE"]' -ocr config set mcp_servers..tools '["tool_name"]' -ocr config set mcp_servers..setup '' - -# Delete an MCP server -ocr config unset mcp_servers. -``` - -| Field | Required | Description | -|-------|----------|-------------| -| `command` | Yes | The executable command to start the MCP server | -| `args` | No | Command-line arguments passed to the server | -| `env` | No | Environment variables in `KEY=VALUE` format | -| `tools` | No | Allowed tool names; if empty, all tools from the server are available | -| `setup` | No | A shell command to run before starting the server (e.g. build an index) | - -> **Note:** If an MCP tool's name conflicts with a built-in tool, it will be skipped with a warning. The `setup` command has a 5-minute timeout. - -**Example: Add [CodeGraph](https://github.com/nicholasgasior/codegraph) for code structure analysis** - -```bash -ocr config set mcp_servers.codegraph.command codegraph -ocr config set mcp_servers.codegraph.args '["serve","--mcp"]' -ocr config set mcp_servers.codegraph.tools '["codegraph_explore"]' -ocr config set mcp_servers.codegraph.setup 'codegraph init && codegraph index' -``` - -### Environment Variables - -| Variable | Purpose | -|----------|---------| -| `OCR_LLM_URL` | LLM API endpoint URL | -| `OCR_LLM_TOKEN` | API key / auth token | -| `OCR_LLM_AUTH_HEADER` | Anthropic auth header (`x-api-key` or `authorization`) | -| `OCR_LLM_EXTRA_HEADERS` | Comma-separated `key=value` HTTP headers | -| `OCR_LLM_MODEL` | Model name | -| `OCR_LLM_PROTOCOL` | Protocol: `anthropic` \| `openai` \| `openai-responses`; takes priority over `OCR_USE_ANTHROPIC` | -| `OCR_LLM_TIMEOUT` | Per-request HTTP timeout in seconds (overrides config file `timeout_sec`) | -| `OCR_USE_ANTHROPIC` | `true` = Anthropic, `false` = OpenAI Chat Completions (legacy; prefer `OCR_LLM_PROTOCOL`) | +Configuration lives in `~/.opencodereview/config.json` and can be overridden by environment variables. It covers providers, models, MCP servers, language, and telemetry. For the complete key reference, environment variables, and MCP server setup, see **[Configuration](https://open-codereview.ai/docs/configuration)** and **[MCP Server](https://open-codereview.ai/docs/mcp)**. ## Telemetry diff --git a/README.ru-RU.md b/README.ru-RU.md index 99da66e7..dc78748b 100644 --- a/README.ru-RU.md +++ b/README.ru-RU.md @@ -516,131 +516,23 @@ ocr review \ Для воспроизводимости зафиксируйте тег версии или SHA коммита. Полный демо-воркфлоу, а также полный список входов, выходов и режимов публикации комментариев (закреплённая сводка, инкрементальная неразрушающая публикация) см. в каталоге [`examples/github_actions/`](./examples/github_actions/). -## Команды +## Документация -| Команда | Алиас | Описание | -|---------|-------|----------| -| `ocr review` | `ocr r` | Запустить код-ревью на основе диффа | -| `ocr scan` | `ocr s` | Ревью целых файлов (дифф не нужен) | -| `ocr delegate preview` | `ocr d preview` | Предварительный просмотр файлов для ревью с метаданными режима/ссылок (LLM не требуется) | -| `ocr delegate rule ` | `ocr d rule` | Вывод правил ревью, сгруппированных по содержимому (LLM не требуется) | -| `ocr rules check ` | — | Показать, какое правило ревью применяется к пути файла | -| `ocr config provider` | — | Интерактивная настройка провайдера (встроенный, пользовательский или ручной) | -| `ocr config model` | — | Интерактивный выбор модели для активного провайдера | -| `ocr config set ` | — | Установить значения конфигурации | -| `ocr config unset custom_providers.` | — | Удалить пользовательского провайдера | -| `ocr llm test` | — | Проверить подключение к LLM | -| `ocr llm providers` | — | Показать список встроенных LLM-провайдеров | -| `ocr session list` | `ocr sessions list`, `ocr session ls` | Показать сохранённые сессии ревью | -| `ocr session show ` | `ocr sessions show ` | Показать одну сессию и её checkpoint'ы по файлам | -| `ocr viewer` | `ocr v` | Запустить WebUI-просмотрщик сессий на `localhost:5483` | -| `ocr version` | — | Показать информацию о версии | - -### Флаги `ocr review` - -| Флаг | Короткая форма | По умолчанию | Описание | -|------|----------------|--------------|----------| -| `--repo` | — | текущий каталог | Корень git-репозитория | -| `--from` | — | — | Исходный ref (например, `main`) | -| `--to` | — | — | Целевой ref (например, `feature-branch`) | -| `--commit` | `-c` | — | Один коммит для ревью | -| `--exclude` | — | — | Паттерны в стиле gitignore через запятую для пропуска файлов; объединяются с excludes из rule.json | -| `--preview` | `-p` | `false` | Показать, какие файлы попадут в ревью, без запуска LLM | -| `--resume` | — | — | Возобновить предыдущую совместимую сессию ревью диапазона или одного коммита | -| `--format` | `-f` | `text` | Формат вывода: `text` или `json` | -| `--concurrency` | — | `8` | Максимум одновременных ревью файлов | -| `--timeout` | — | `10` | Таймаут конкурентной задачи в минутах | -| `--audience` | — | `human` | `human` (показывать прогресс) или `agent` (только сводка) | -| `--background` | `-b` | — | Необязательный контекст требований/бизнес-логики для ревью; при `--commit` автоматически заполняется из сообщения коммита | -| `--background-file` | `-B` | — | Необязательный контекст требований/бизнес-логики из Markdown-файла; при совместном использовании с `--background` встроенное значение идёт первым | -| `--model` | — | — | Выбрать или переопределить LLM-модель для этого ревью | -| `--rule` | — | — | Путь к пользовательским JSON-правилам ревью | -| `--max-tools` | — | встроенное | Максимум раундов вызова инструментов на файл; действует, только если больше значения шаблона по умолчанию | -| `--max-git-procs` | — | встроенное | Максимум одновременных git-подпроцессов | -| `--tools` | — | — | Путь к пользовательскому JSON-конфигу инструментов | - -#### Возобновляемые ревью и сессии - -Каждый запуск `ocr review` сохраняет локальный журнал сессии в -`~/.opencodereview/sessions/`. Успешный текстовый вывод остаётся сфокусированным -на результате ревью и не печатает session ID. Сохранённые сессии можно найти через -`ocr session list/show`, а `--format json` добавляет `session_id` в машиночитаемый -вывод. Если ревью диапазона или одного коммита было прервано, выберите сохранённую -сессию с тем же целевым ревью и возобновите её: +Полная документация доступна на **[open-codereview.ai/docs](https://open-codereview.ai/docs)**: -```bash -ocr session list -ocr session show -ocr review --from main --to feature-branch --resume -ocr review --commit abc123 --resume -``` +- [Быстрый старт](https://open-codereview.ai/docs/quickstart) — установка и запуск первого ревью +- [Установка](https://open-codereview.ai/docs/installation) — все платформы и менеджеры пакетов +- [Справочник CLI](https://open-codereview.ai/docs/cli-reference) — все команды и флаги +- [Правила ревью](https://open-codereview.ai/docs/review-rules) — цепочка приоритетов правил, формат файла и фильтрация путей +- [Конфигурация](https://open-codereview.ai/docs/configuration) — ключи конфигурации и переменные окружения +- [MCP-сервер](https://open-codereview.ai/docs/mcp) — расширение агента ревью внешними инструментами +- [Интеграция с кодинг-агентами](https://open-codereview.ai/docs/claude-code) — Claude Code, Agent Skill и режим делегирования +- [Интеграция с CI/CD](https://open-codereview.ai/docs/cicd) — запуск ревью в пайплайне +- [Архитектура](https://open-codereview.ai/docs/architecture) · [Инструменты](https://open-codereview.ai/docs/tools) · [Просмотр сессий](https://open-codereview.ai/docs/viewer) · [Телеметрия](https://open-codereview.ai/docs/telemetry) · [FAQ](https://open-codereview.ai/docs/faq) -Возобновление намеренно строгое: поддерживаются только ревью диапазона веток и одного -коммита, но не ревью рабочей копии. Текущие `--from/--to` или `--commit` должны -совпадать с сохранённой сессией. `--preview` нельзя использовать вместе с `--resume`. - -При `--format json` возобновлённый запуск включает: - -- `session_id` — session ID текущего запуска -- `resume.resumed_from` — исходный session ID -- `resume.reused_files` — файлы, повторно использованные из сохранённых checkpoint'ов -- `resume.rerun_files` — файлы, заново проверенные в текущем запуске - -### Флаги `ocr session` - -| Команда | Флаг | По умолчанию | Описание | -|---------|------|--------------|----------| -| `ocr session list` | `--repo` | текущий каталог | Репозиторий, для которого нужно показать сессии | -| `ocr session list` | `--json` | `false` | Вывести сводки сессий в JSON | -| `ocr session list` | `--limit` | `20` | Ограничить количество сессий; `0` означает без ограничения | -| `ocr session show ` | `--repo` | текущий каталог | Репозиторий, сессию которого нужно посмотреть | -| `ocr session show ` | `--json` | `false` | Вывести метаданные сессии и элементы по файлам в JSON | - -### Флаги `ocr scan` - -`ocr scan` проверяет целые файлы, а не дифф — удобно для аудита незнакомой кодовой базы, предмиграционного сканирования или любого каталога без значимого диффа. Работает и в каталогах без git (используется обход файловой системы с учётом `.gitignore`). - -| Флаг | Короткая форма | По умолчанию | Описание | -|------|----------------|--------------|----------| -| `--path` | — | весь репозиторий | Каталоги/файлы для сканирования через запятую | -| `--exclude` | — | — | Паттерны в стиле gitignore через запятую для пропуска файлов; объединяются с excludes из rule.json | -| `--preview` | `-p` | `false` | Показать список файлов для сканирования без запуска LLM | -| `--max-tokens-budget` | — | `0` (без ограничений) | Ограничить суммарное потребление токенов; при превышении диспетчеризация прекращается | -| `--no-plan` | — | `false` | Пропустить предварительное планирование по файлам | -| `--no-dedup` | — | `false` | Пропустить дедупликацию похожих комментариев в рамках батча | -| `--no-summary` | — | `false` | Пропустить сводку на уровне проекта | -| `--batch` | — | `by-language` | Стратегия батчинга: `none`, `by-language` или `by-directory` | -| `--format` | `-f` | `text` | Формат вывода: `text` или `json` (JSON включает поле `project_summary`) | -| `--concurrency` | — | `8` | Максимум одновременных сканирований файлов | -| `--rule` | — | — | Путь к пользовательским JSON-правилам ревью | -| `--repo` | — | текущий каталог | Корень репозитория или каталога для сканирования | - -Перед каждым запуском `ocr scan` выводит приблизительную оценку стоимости в токенах. Используйте `--preview`, чтобы сначала посмотреть список файлов, и `--max-tokens-budget`, чтобы ограничить расход на больших репозиториях. - -### Флаги `ocr delegate` - -`ocr delegate` — режим делегирования для AI-агентов. Он обеспечивает детерминированный -выбор файлов и разрешение правил без вызова LLM — фактическое ревью выполняет -хост-агент своими силами. - -| Подкоманда | Описание | -|------------|----------| -| `ocr delegate preview` | Вывод списка файлов для ревью с метаданными режима/ссылок | -| `ocr delegate rule ` | Вывод правил ревью, сгруппированных по содержимому | - -Обе подкоманды используют общие флаги: - -| Флаг | Сокращение | По умолчанию | Описание | -|------|-----------|--------------|----------| -| `--repo` | — | текущий каталог | Корень Git-репозитория | -| `--from` | — | — | Исходная ссылка (например, `main`) | -| `--to` | — | — | Целевая ссылка (например, `feature-branch`) | -| `--commit` | `-c` | — | Один коммит | -| `--exclude` | — | — | Паттерны исключения в стиле gitignore через запятую | -| `--rule` | — | — | Путь к файлу с пользовательскими JSON-правилами | -| `--background` | `-b` | — | Необязательный контекст требований/бизнеса | -| `--background-file` | `-B` | — | Бизнес-контекст из Markdown-файла | -| `--max-git-procs` | — | `16` | Макс. параллельных подпроцессов git | +## Команды + +OCR предоставляет команды `review`, `scan`, `delegate`, `config`, `llm`, `session`, `viewer` и другие. Полный список команд и все флаги — включая возобновляемые ревью и полные опции `ocr scan` / `ocr delegate` — см. в **[Справочнике CLI](https://open-codereview.ai/docs/cli-reference)**. ## Примеры @@ -730,209 +622,11 @@ OCR_VIEWER_ALLOWED_HOSTS=review.internal,ocr.lan ocr viewer --addr :3000 ## Правила ревью -OCR разрешает правила ревью по цепочке приоритетов из четырёх уровней. На каждом уровне действует принцип «первое совпадение побеждает»: если путь файла совпал с паттерном, используется это правило; иначе поиск продолжается на следующем уровне. - -| Приоритет | Источник | Путь | Описание | -|-----------|----------|------|----------| -| 1 (высший) | Флаг `--rule` | Путь, указанный пользователем | Явное переопределение из CLI | -| 2 | Конфиг проекта | `/.opencodereview/rule.json` | Правила уровня проекта, можно коммитить в git | -| 3 | Глобальный конфиг | `~/.opencodereview/rule.json` | Личные настройки пользователя | -| 4 (низший) | Системные по умолчанию | Встроенный `system_rules.json` | Встроенные правила для распространённых языков и типов файлов | - -### Формат файла правил - -Уровни 1–3 используют один и тот же JSON-формат: - -```json -{ - "rules": [ - { - "path": "force-api/**/*.java", - "rule": "Все новые методы должны проверять обязательные параметры на null", - "merge_system_rule": true - }, - { - "path": "**/*mapper*.xml", - "rule": "Проверять SQL на риски инъекций, ошибки в параметрах и незакрытые теги" - } - ] -} -``` - -- `path` поддерживает рекурсивное сопоставление `**` и расширение фигурных скобок `{java,kt}`. -- `merge_system_rule` необязателен. Если указано `true`, совпавшее встроенное системное правило объединяется с этим пользовательским правилом. -- Внутри каждого уровня правила проверяются в порядке объявления — побеждает первое совпадение. -- Если файл правил не существует, он молча пропускается. - -**Поле `rule` поддерживает как встроенный текст, так и пути к файлам.** Система определяет тип автоматически: - -1. Если значение содержит переносы строк → **встроенный текст** (многострочные правила никогда не считаются путями). -2. Если значение — одна строка, без пробелов, и заканчивается на `.md` / `.txt` / `.markdown` → **путь к файлу**. - - Абсолютные пути (начинающиеся с `/`) используются напрямую. - - Относительные пути проверяются в корне проекта. Выход за пределы директории (например, `../../etc/passwd.md`) блокируется. Если не найдены — выводится `[WARN]` и правило очищается (без fallback на inline). - - Файл должен пройти проверку: допустимое расширение, ≤ 512 KB, цель симлинка также должна иметь допустимое расширение. При ошибке проверки правило очищается. -3. Иначе → **встроенный текст**. - -```json -{ - "rules": [ - { - "path": "**/*mapper*.xml", - "rule": "docs/sql-rules.md" - }, - { - "path": "**/*.java", - "rule": "Always check for null safety and resource leaks" - }, - { - "path": "**/*.go", - "rule": "shared/go-concurrency.md" - }, - { - "path": "**/*.py", - "rule": "/Users/me/team-rules/python.md" - } - ] -} -``` - -- `docs/sql-rules.md` — относительный путь, загружается из `/docs/sql-rules.md`. -- `Always check for null safety…` — встроенная строка, используется напрямую. -- `shared/go-concurrency.md` — относительный путь, аналогично. -- `/Users/me/team-rules/python.md` — абсолютный путь, используется напрямую. - -> Абсолютные пути могут указывать на файлы вне директории проекта — это сделано намеренно. `rule.json` пишут мейнтейнеры проекта, это доверенный ввод. Команды могут хранить общие правила по единому пути (например, `/opt/company-rules/`) и не копировать их в каждый проект. - -### Фильтрация путей - -Файлы правил также поддерживают поля `include` и `exclude`, управляющие тем, какие файлы попадают в область ревью: - -```json -{ - "rules": [ - {"path": "**/*.java", "rule": "Проверять null-безопасность"} - ], - "include": ["src/main/**/*.java", "lib/**/*.kt"], - "exclude": ["**/generated/**", "vendor/**"] -} -``` - -**Приоритет решений фильтра (от высшего к низшему):** - -| Шаг | Условие | Результат | -|-----|---------|-----------| -| 1 | Файл бинарный | Исключён | -| 2 | Путь совпадает с пользовательским паттерном `exclude` | Исключён | -| 3 | Расширение файла не входит в список поддерживаемых | Исключён | -| 4 | `include` настроен и путь совпадает | **В ревью** (шаг 5 пропускается) | -| 5 | Путь совпадает со встроенным паттерном исключения по умолчанию (тестовые файлы и т. п.) | Исключён | -| 6 | Ничего из перечисленного | В ревью | - -**Как это работает:** - -- `include` и `exclude` следуют той же цепочке приоритетов, что и правила ревью (`--rule` > конфиг проекта > глобальный конфиг). Действует **целиком самый приоритетный уровень, на котором include/exclude настроены** — паттерны разных уровней не объединяются. -- `exclude` всегда сильнее `include` — файл, совпавший с обоими, исключается. -- `include` работает как **обход встроенных паттернов исключения по умолчанию** (например, тестовых файлов), а не как эксклюзивный allowlist: файлы, не совпавшие ни с одним паттерном `include`, всё равно обычным образом проходят проверки фильтра по умолчанию. -- Синтаксис паттернов: поддерживаются рекурсивное сопоставление `**`, односегментное `*` и расширение фигурных скобок `{a,b}`. Сопоставление регистронезависимое. - -**Встроенные паттерны исключения по умолчанию** (отфильтровывают тестовые файлы и т. п. — можно переопределить через `include`): - -``` -**/*_test.go, **/*Test.java, **/*Tests.java, **/*_test.rs, -**/*.test.{js,jsx,ts,tsx}, **/*.spec.{js,jsx,ts,tsx}, **/__tests__/**, -**/src/test/java/**/*.java, **/src/test/**/*.kt, -**/test/**/*_test.py, **/tests/**/*_test.py, **/*_test.py, -**/*_spec.rb, **/spec/**/*_spec.rb, **/oh_modules/** -``` +OCR разрешает правила ревью через четырёхуровневую цепочку приоритетов (флаг `--rule` > конфигурация проекта > глобальная конфигурация > встроенные значения по умолчанию) и поддерживает встроенные или файловые правила, сопоставление по `**`-шаблонам и фильтрацию путей через `include` / `exclude`. Полный формат файла правил и семантику фильтрации см. в разделе **[Правила ревью](https://open-codereview.ai/docs/review-rules)**. ## Справочник по конфигурации -Файл конфигурации: `~/.opencodereview/config.json` - -| Ключ | Тип | Пример | -|------|-----|--------| -| `provider` | string | `anthropic` \| `openai` \| `dashscope` \| `deepseek` \| `z-ai` | -| `providers..api_key` | string | API-ключ провайдера | -| `providers..url` | string | Переопределение base URL провайдера | -| `providers..protocol` | string | `anthropic` \| `openai` \| `openai-responses` | -| `providers..model` | string | Имя модели провайдера | -| `providers..models` | array | Необязательный список моделей для интерактивного выбора | -| `providers..auth_header` | string | `x-api-key` \| `authorization` | -| `providers..extra_body` | object | JSON-объект, добавляемый в каждое тело запроса | -| `providers..timeout_sec` | integer | Таймаут HTTP-запроса в секундах, по умолчанию `300` | -| `providers..extra_headers` | string | HTTP-заголовки `key=value` через запятую | -| `custom_providers..*` | — | Те же поля, что и `providers..*`, включая необязательное `models` | -| `llm.url` | string | `https://api.openai.com/v1/chat/completions` | -| `llm.auth_token` | string | `sk-xxxxxxx` | -| `llm.auth_header` | string | Только для Anthropic: `x-api-key` \| `authorization` | -| `llm.extra_body` | object | JSON-объект, добавляемый в каждое тело запроса | -| `llm.timeout_sec` | integer | Таймаут HTTP-запроса в секундах, по умолчанию `300` | -| `llm.extra_headers` | string | HTTP-заголовки `key=value` через запятую | -| `llm.model` | string | `claude-opus-4-6` | -| `llm.protocol` | string | `anthropic` \| `openai` \| `openai-responses`; имеет приоритет над `llm.use_anthropic` | -| `llm.use_anthropic` | boolean | `true` \| `false` (устаревшее; предпочтительнее `llm.protocol`) | -| `mcp_servers..command` | string | Команда для запуска MCP-сервера | -| `mcp_servers..args` | array | Аргументы командной строки для MCP-сервера | -| `mcp_servers..env` | array | Переменные окружения в формате `KEY=VALUE` | -| `mcp_servers..tools` | array | Разрешённые имена инструментов (пусто = все инструменты) | -| `mcp_servers..setup` | string | Команда настройки перед запуском сервера | -| `language` | string | Любое название языка, например `English`, `Chinese` (по умолчанию: `English`) | -| `telemetry.enabled` | boolean | `true` \| `false` | -| `telemetry.exporter` | string | `console` \| `otlp` | -| `telemetry.otlp_endpoint` | string | Адрес OTLP-коллектора | -| `telemetry.content_logging` | boolean | Включать промпты в телеметрию | - -Переменные окружения имеют приоритет над файлом конфигурации. - -### MCP-сервер - -Open Code Review поддерживает серверы [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), позволяя агенту ревью использовать внешние инструменты во время проверки кода через stdio-транспорт. - -Настройка MCP-серверов через CLI: - -```bash -# Добавить MCP-сервер -ocr config set mcp_servers..command -ocr config set mcp_servers..args '["arg1","arg2"]' -ocr config set mcp_servers..env '["KEY=VALUE"]' -ocr config set mcp_servers..tools '["tool_name"]' -ocr config set mcp_servers..setup '' - -# Удалить MCP-сервер -ocr config unset mcp_servers. -``` - -| Поле | Обязательно | Описание | -|------|-------------|----------| -| `command` | Да | Исполняемая команда для запуска MCP-сервера | -| `args` | Нет | Аргументы командной строки для сервера | -| `env` | Нет | Переменные окружения в формате `KEY=VALUE` | -| `tools` | Нет | Разрешённые имена инструментов; если пусто — доступны все инструменты сервера | -| `setup` | Нет | Shell-команда для выполнения перед запуском сервера (например, построение индекса) | - -> **Примечание:** Если имя MCP-инструмента конфликтует со встроенным инструментом, он будет пропущен с предупреждением. Таймаут команды `setup` составляет 5 минут. - -**Пример: добавление [CodeGraph](https://github.com/nicholasgasior/codegraph) для усиления анализа структуры кода** - -```bash -ocr config set mcp_servers.codegraph.command codegraph -ocr config set mcp_servers.codegraph.args '["serve","--mcp"]' -ocr config set mcp_servers.codegraph.tools '["codegraph_explore"]' -ocr config set mcp_servers.codegraph.setup 'codegraph init && codegraph index' -``` - -### Переменные окружения - -| Переменная | Назначение | -|------------|------------| -| `OCR_LLM_URL` | URL эндпоинта LLM API | -| `OCR_LLM_TOKEN` | API-ключ / токен авторизации | -| `OCR_LLM_AUTH_HEADER` | Заголовок авторизации Anthropic (`x-api-key` или `authorization`) | -| `OCR_LLM_EXTRA_HEADERS` | HTTP-заголовки `key=value` через запятую | -| `OCR_LLM_MODEL` | Имя модели | -| `OCR_LLM_PROTOCOL` | Протокол: `anthropic` \| `openai` \| `openai-responses`; имеет приоритет над `OCR_USE_ANTHROPIC` | -| `OCR_LLM_TIMEOUT` | Таймаут HTTP-запроса в секундах (переопределяет `timeout_sec` из файла конфигурации) | -| `OCR_USE_ANTHROPIC` | `true` = Anthropic, `false` = OpenAI Chat Completions (устаревшее; предпочтительнее `OCR_LLM_PROTOCOL`) | +Конфигурация хранится в `~/.opencodereview/config.json` и может быть переопределена переменными окружения. Она охватывает провайдеров, модели, MCP-серверы, язык и телеметрию. Полный справочник ключей, переменные окружения и настройку MCP-сервера см. в разделах **[Конфигурация](https://open-codereview.ai/docs/configuration)** и **[MCP-сервер](https://open-codereview.ai/docs/mcp)**. ## Телеметрия diff --git a/README.zh-CN.md b/README.zh-CN.md index ad6d7fba..33dd9380 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -514,126 +514,23 @@ ocr review \ 为保障可复现性，请固定到某个版本标签或 commit SHA。完整的 workflow 示例以及 inputs、outputs 与评论发布模式（置顶汇总、增量非破坏式发布）的完整列表，请参见 [`examples/github_actions/`](./examples/github_actions/) 目录。 -## 命令 - -| 命令 | 别名 | 描述 | -|------|------|------| -| `ocr review` | `ocr r` | 开始基于 diff 的代码审查 | -| `ocr scan` | `ocr s` | 审查整个文件（无需 diff） | -| `ocr delegate preview` | `ocr d preview` | 预览可评审文件列表及模式/引用元数据（无需 LLM） | -| `ocr delegate rule ` | `ocr d rule` | 输出按内容分组的评审规则（无需 LLM） | -| `ocr rules check ` | — | 预览某个文件路径生效的审查规则 | -| `ocr config provider` | — | 交互式供应商设置（内置、自定义或手动） | -| `ocr config model` | — | 为当前供应商交互式选择模型 | -| `ocr config set ` | — | 设置配置项 | -| `ocr config unset custom_providers.` | — | 删除自定义供应商 | -| `ocr llm test` | — | 测试 LLM 连通性 | -| `ocr llm providers` | — | 列出内置 LLM 供应商 | -| `ocr session list` | `ocr sessions list`, `ocr session ls` | 列出已保存的评审会话 | -| `ocr session show ` | `ocr sessions show ` | 查看单个会话及其逐文件检查点 | -| `ocr viewer` | `ocr v` | 启动 WebUI 会话查看器，地址 `localhost:5483` | -| `ocr version` | — | 显示版本信息 | - -### `ocr review` 参数 - -| 参数 | 缩写 | 默认值 | 描述 | -|------|------|--------|------| -| `--repo` | — | 当前目录 | Git 仓库根目录 | -| `--from` | — | — | 源引用（如 `main`） | -| `--to` | — | — | 目标引用（如 `feature-branch`） | -| `--commit` | `-c` | — | 审查单个提交 | -| `--exclude` | — | — | 以逗号分隔的 gitignore 风格模式，用于跳过匹配文件；与 rule.json 中的 excludes 合并 | -| `--preview` | `-p` | `false` | 预览将被审查的文件列表，不调用 LLM | -| `--resume` | — | — | 从之前兼容的区间或单 commit 评审会话恢复 | -| `--format` | `-f` | `text` | 输出格式：`text` 或 `json` | -| `--concurrency` | — | `8` | 最大并发文件审查数 | -| `--timeout` | — | `10` | 并发任务超时时间（分钟） | -| `--audience` | — | `human` | `human`（显示进度）或 `agent`（仅输出摘要） | -| `--background` | `-b` | — | 可选的需求/业务背景信息；使用 `--commit` 时如未指定则自动从 commit message 中提取 | -| `--background-file` | `-B` | — | 来自 Markdown 文件的可选需求/业务背景信息；与 `--background` 同时使用时，内联内容排在前面 | -| `--model` | — | — | 为本次审查选择或覆盖 LLM 模型 | -| `--rule` | — | — | 自定义 JSON 审查规则路径 | -| `--max-tools` | — | 内置默认 | 每个文件的最大工具调用轮次；仅在大于模板默认值时生效 | -| `--max-git-procs` | — | 内置默认 | 最大并发 git 子进程数 | -| `--tools` | — | — | 自定义 JSON 工具配置路径 | - -#### 可恢复评审与会话 - -每次 `ocr review` 都会在 `~/.opencodereview/sessions/` 下保存本地会话日志。 -正常完成的文本输出只展示评审结果，不打印 session ID；可使用 -`ocr session list/show` 查找已保存会话，或用 `--format json` 在机器可读输出中获取 -`session_id`。如果区间或单 commit 评审被中断，可列出保存的会话，并从匹配相同评审目标的会话恢复： - -```bash -ocr session list -ocr session show -ocr review --from main --to feature-branch --resume -ocr review --commit abc123 --resume -``` - -恢复逻辑是严格的：仅支持分支区间和单 commit 评审，不支持工作区评审；当前 -`--from/--to` 或 `--commit` 必须与保存的会话一致。`--preview` 不能与 `--resume` 同时使用。 - -使用 `--format json` 时，恢复运行会包含： - -- `session_id` — 当前运行的 session ID -- `resume.resumed_from` — 来源 session ID -- `resume.reused_files` — 从已保存检查点复用的文件数 -- `resume.rerun_files` — 本次重新评审的文件数 - -### `ocr session` 参数 - -| 命令 | 参数 | 默认值 | 描述 | -|------|------|--------|------| -| `ocr session list` | `--repo` | 当前目录 | 要列出会话的仓库 | -| `ocr session list` | `--json` | `false` | 以 JSON 输出会话摘要 | -| `ocr session list` | `--limit` | `20` | 限制列出的会话数量；`0` 表示不限 | -| `ocr session show ` | `--repo` | 当前目录 | 要查看会话的仓库 | -| `ocr session show ` | `--json` | `false` | 以 JSON 输出会话元数据和逐文件条目 | - -### `ocr scan` 参数 +## 文档 -`ocr scan` 审查整个文件而非 diff —— 适用于审计不熟悉的代码库、迁移前扫描，或任何没有有意义 diff 的目录。它也可以在非 git 目录中工作（会回退到遵循 `.gitignore` 的文件系统遍历）。 +完整文档见 **[open-codereview.ai/docs](https://open-codereview.ai/docs)**： -| 参数 | 缩写 | 默认值 | 描述 | -|------|------|--------|------| -| `--path` | — | 整个仓库 | 以逗号分隔的待扫描目录/文件 | -| `--exclude` | — | — | 以逗号分隔的 gitignore 风格模式，用于跳过匹配文件；与 rule.json 中的 excludes 合并 | -| `--preview` | `-p` | `false` | 列出将被扫描的文件，不运行 LLM | -| `--max-tokens-budget` | — | `0`（无限制） | 限制总 token 使用量；超出后停止分发 | -| `--no-plan` | — | `false` | 跳过按文件的规划预处理 | -| `--no-dedup` | — | `false` | 跳过按批次的相似评论去重 | -| `--no-summary` | — | `false` | 跳过项目级别的总结 | -| `--batch` | — | `by-language` | 批处理策略：`none`、`by-language` 或 `by-directory` | -| `--format` | `-f` | `text` | 输出格式：`text` 或 `json`（JSON 包含 `project_summary` 字段） | -| `--concurrency` | — | `8` | 最大并发文件扫描数 | -| `--rule` | — | — | 自定义 JSON 审查规则路径 | -| `--repo` | — | 当前目录 | 要扫描的仓库或目录根路径 | +- [快速开始](https://open-codereview.ai/docs/quickstart) —— 安装并运行你的第一次评审 +- [安装](https://open-codereview.ai/docs/installation) —— 覆盖各平台与包管理器 +- [CLI 参考](https://open-codereview.ai/docs/cli-reference) —— 所有命令与参数 +- [评审规则](https://open-codereview.ai/docs/review-rules) —— 规则优先级链、文件格式与路径过滤 +- [配置](https://open-codereview.ai/docs/configuration) —— 配置项与环境变量 +- [MCP 服务器](https://open-codereview.ai/docs/mcp) —— 用外部工具扩展评审 agent +- [编程 Agent 集成](https://open-codereview.ai/docs/claude-code) —— Claude Code、Agent Skill 与委托模式 +- [CI/CD 集成](https://open-codereview.ai/docs/cicd) —— 在流水线中运行评审 +- [架构](https://open-codereview.ai/docs/architecture) · [工具](https://open-codereview.ai/docs/tools) · [会话查看器](https://open-codereview.ai/docs/viewer) · [遥测](https://open-codereview.ai/docs/telemetry) · [FAQ](https://open-codereview.ai/docs/faq) -每次运行前，`ocr scan` 会打印粗略的 token 费用估算。使用 `--preview` 先查看文件列表，使用 `--max-tokens-budget` 限制大型仓库的开销。 - -### `ocr delegate` 参数 - -`ocr delegate` 是面向 AI 编程 agent 的委托模式。它提供确定性的文件选择和规则解析，不调用任何 LLM — 由宿主 agent 使用自身能力执行实际评审。 - -| 子命令 | 说明 | -|--------|------| -| `ocr delegate preview` | 输出可评审文件列表及模式/引用元数据 | -| `ocr delegate rule ` | 输出按内容分组的评审规则 | - -两个子命令共享以下参数： +## 命令 -| 参数 | 缩写 | 默认值 | 说明 | -|------|------|--------|------| -| `--repo` | — | 当前目录 | Git 仓库根目录 | -| `--from` | — | — | 源引用（如 `main`） | -| `--to` | — | — | 目标引用（如 `feature-branch`） | -| `--commit` | `-c` | — | 单次提交 | -| `--exclude` | — | — | 逗号分隔的 gitignore 风格排除模式 | -| `--rule` | — | — | 自定义 JSON 评审规则路径 | -| `--background` | `-b` | — | 可选的需求/业务上下文 | -| `--background-file` | `-B` | — | 从 Markdown 文件读取业务上下文 | -| `--max-git-procs` | — | `16` | 最大并发 git 子进程数 | +OCR 提供 `review`、`scan`、`delegate`、`config`、`llm`、`session`、`viewer` 等命令。完整的命令列表与所有参数（包括可恢复评审以及 `ocr scan` / `ocr delegate` 的全部选项），详见 **[CLI 参考](https://open-codereview.ai/docs/cli-reference)**。 ## 示例 @@ -713,209 +610,11 @@ ocr viewer --addr :3000 ## 评审规则 -OCR 通过四层优先级链解析评审规则。每层采用首次匹配原则：如果文件路径匹配到某个模式，则使用该规则；否则穿透到下一层。 - -| 优先级 | 来源 | 路径 | 描述 | -|--------|------|------|------| -| 1（最高） | `--rule` 参数 | 用户指定路径 | CLI 显式覆盖 | -| 2 | 项目配置 | `/.opencodereview/rule.json` | 项目级规则，可提交到 git | -| 3 | 全局配置 | `~/.opencodereview/rule.json` | 用户级个人偏好 | -| 4（最低） | 系统默认 | 内嵌 `system_rules.json` | 覆盖常见语言和文件类型的内置规则 | - -### 规则文件格式 - -第 1–3 层使用相同的 JSON 格式： - -```json -{ - "rules": [ - { - "path": "force-api/**/*.java", - "rule": "所有新方法必须对必填参数进行空值校验", - "merge_system_rule": true - }, - { - "path": "**/*mapper*.xml", - "rule": "检查 SQL 注入风险、参数错误和缺少闭合标签" - } - ] -} -``` - -- `path` 支持 `**` 递归匹配和 `{java,kt}` 大括号展开。 -- `merge_system_rule` 为可选字段。设为 `true` 时，命中的内置系统规则会与该用户规则合并；否则用户规则会替换系统规则。 -- 在每一层内，规则按声明顺序评估 —— 首次匹配生效。 -- 如果规则文件不存在，将被静默跳过。 - -**`rule` 字段同时支持内联内容和文件路径。**系统按以下顺序自动判断： - -1. 如果值包含换行 → **内联内容**（多行规则永远不会被当作文件路径）。 -2. 如果值是单行、不含空格、且以 `.md` / `.txt` / `.markdown` 结尾 → **文件路径**。 - - 绝对路径（以 `/` 开头）直接使用。 - - 相对路径在项目根目录下查找，路径穿越（如 `../../etc/passwd.md`）会被拦截。找不到则 `[WARN]` 并清空该规则（不会回退为内联）。 - - 文件需通过安全校验：白名单扩展名、≤ 512 KB、symlink 解析后目标也必须是白名单扩展名。校验失败则清空该规则。 -3. 否则 → **内联内容**。 - -```json -{ - "rules": [ - { - "path": "**/*mapper*.xml", - "rule": "docs/sql-rules.md" - }, - { - "path": "**/*.java", - "rule": "始终检查空值安全和资源泄漏" - }, - { - "path": "**/*.go", - "rule": "shared/go-concurrency.md" - }, - { - "path": "**/*.py", - "rule": "/Users/me/team-rules/python.md" - } - ] -} -``` - -- `docs/sql-rules.md` — 相对路径，从 `/docs/sql-rules.md` 加载。 -- `始终检查空值安全…` — 内联字符串，直接使用。 -- `shared/go-concurrency.md` — 相对路径，同上。 -- `/Users/me/team-rules/python.md` — 绝对路径，直接使用。 - -> 绝对路径可以访问项目目录之外的文件，这是有意为之的设计——`rule.json` 由项目维护者编写，属于受信输入。团队可将共享规则放在统一路径下（如 `/opt/company-rules/`），无需在各项目中复制。 - -### 路径过滤 - -规则文件同时支持 `include` 和 `exclude` 字段，用于控制哪些文件进入审查范围： - -```json -{ - "rules": [ - {"path": "**/*.java", "rule": "检查空值安全"} - ], - "include": ["src/main/**/*.java", "lib/**/*.kt"], - "exclude": ["**/generated/**", "vendor/**"] -} -``` - -**过滤决策优先级（从高到低）：** - -| 步骤 | 条件 | 结果 | -|------|------|------| -| 1 | 文件为二进制文件 | 排除 | -| 2 | 路径匹配用户 `exclude` 模式 | 排除 | -| 3 | 文件扩展名不在支持列表中 | 排除 | -| 4 | 配置了 `include` 且路径匹配 | **纳入审查**（跳过步骤 5） | -| 5 | 路径匹配内置默认排除模式（测试文件等） | 排除 | -| 6 | 以上均不满足 | 纳入审查 | - -**生效逻辑：** - -- `include` 和 `exclude` 遵循与评审规则相同的优先级链（`--rule` > 项目配置 > 全局配置），取**最高优先级中配置了 include/exclude 的那一层**整体生效，不会跨层合并。 -- `exclude` 始终优先于 `include` —— 同时匹配两者的文件会被排除。 -- `include` 的作用是**绕过内置默认排除模式**（如测试文件），而非限制审查范围 —— 未匹配 `include` 的文件仍会正常进入后续的默认过滤判断。 -- 模式语法：支持 `**` 递归匹配、`*` 单级匹配和 `{a,b}` 大括号展开，匹配时不区分大小写。 - -**内置默认排除模式**（用于过滤测试文件等，可通过 `include` 覆盖）： - -``` -**/*_test.go, **/*Test.java, **/*Tests.java, **/*_test.rs, -**/*.test.{js,jsx,ts,tsx}, **/*.spec.{js,jsx,ts,tsx}, **/__tests__/**, -**/src/test/java/**/*.java, **/src/test/**/*.kt, -**/test/**/*_test.py, **/tests/**/*_test.py, **/*_test.py, -**/*_spec.rb, **/spec/**/*_spec.rb, **/oh_modules/** -``` +OCR 通过四层优先级链解析评审规则（`--rule` 参数 > 项目配置 > 全局配置 > 内置默认），支持内联或文件形式的规则、`**` 通配匹配，以及 `include` / `exclude` 路径过滤。完整的规则文件格式与过滤语义，详见 **[评审规则](https://open-codereview.ai/docs/review-rules)**。 ## 配置参考 -配置文件：`~/.opencodereview/config.json` - -| 键 | 类型 | 示例 | -|----|------|------| -| `provider` | string | `anthropic` \| `openai` \| `dashscope` \| `deepseek` \| `z-ai` | -| `providers..api_key` | string | 供应商 API 密钥 | -| `providers..url` | string | 供应商 Base URL 覆盖 | -| `providers..protocol` | string | `anthropic` \| `openai` \| `openai-responses` | -| `providers..model` | string | 供应商模型名称 | -| `providers..models` | array | 用于交互式选择的可选供应商模型列表 | -| `providers..auth_header` | string | `x-api-key` \| `authorization` | -| `providers..extra_body` | object | 合并到每个请求体的 JSON 对象 | -| `providers..timeout_sec` | integer | 每次请求的 HTTP 超时时间（秒），默认 `300` | -| `providers..extra_headers` | string | 逗号分隔的 `key=value` HTTP 头 | -| `custom_providers..*` | — | 与 `providers..*` 相同的字段，包括可选的 `models` | -| `llm.url` | string | `https://api.openai.com/v1/chat/completions` | -| `llm.auth_token` | string | `sk-xxxxxxx` | -| `llm.auth_header` | string | 仅 Anthropic：`x-api-key` \| `authorization` | -| `llm.extra_body` | object | 合并到每个请求体的 JSON 对象 | -| `llm.timeout_sec` | integer | 每次请求的 HTTP 超时时间（秒），默认 `300` | -| `llm.extra_headers` | string | 逗号分隔的 `key=value` HTTP 头 | -| `llm.model` | string | `claude-opus-4-6` | -| `llm.protocol` | string | `anthropic` \| `openai` \| `openai-responses`；优先级高于 `llm.use_anthropic` | -| `llm.use_anthropic` | boolean | `true` \| `false`（兼容字段，推荐改用 `llm.protocol`） | -| `mcp_servers..command` | string | 启动 MCP 服务器的命令 | -| `mcp_servers..args` | array | MCP 服务器的命令行参数 | -| `mcp_servers..env` | array | 环境变量，`KEY=VALUE` 格式 | -| `mcp_servers..tools` | array | 允许使用的工具名称（为空则允许所有工具） | -| `mcp_servers..setup` | string | 启动服务器前运行的初始化命令 | -| `language` | string | 任意语言名称，例如 `English`、`Chinese`（默认：`English`） | -| `telemetry.enabled` | boolean | `true` \| `false` | -| `telemetry.exporter` | string | `console` \| `otlp` | -| `telemetry.otlp_endpoint` | string | OTLP 采集器地址 | -| `telemetry.content_logging` | boolean | 在遥测数据中包含提示词 | - -环境变量优先级高于配置文件。 - -### MCP Server - -Open Code Review 支持 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 服务器，允许评审 Agent 在代码评审过程中通过 stdio 传输协议调用外部工具。 - -通过 CLI 配置 MCP 服务器： - -```bash -# 添加 MCP 服务器 -ocr config set mcp_servers..command -ocr config set mcp_servers..args '["arg1","arg2"]' -ocr config set mcp_servers..env '["KEY=VALUE"]' -ocr config set mcp_servers..tools '["tool_name"]' -ocr config set mcp_servers..setup '' - -# 删除 MCP 服务器 -ocr config unset mcp_servers. -``` - -| 字段 | 必填 | 说明 | -|------|------|------| -| `command` | 是 | 启动 MCP 服务器的可执行命令 | -| `args` | 否 | 传递给服务器的命令行参数 | -| `env` | 否 | 环境变量，`KEY=VALUE` 格式 | -| `tools` | 否 | 允许使用的工具名称；为空则服务器的所有工具均可用 | -| `setup` | 否 | 启动服务器前运行的 shell 命令（例如构建索引） | - -> **注意：** 如果 MCP 工具的名称与内置工具冲突，该工具将被跳过并输出警告。`setup` 命令的超时时间为 5 分钟。 - -**示例：添加 [CodeGraph](https://github.com/nicholasgasior/codegraph) 增强代码结构分析能力** - -```bash -ocr config set mcp_servers.codegraph.command codegraph -ocr config set mcp_servers.codegraph.args '["serve","--mcp"]' -ocr config set mcp_servers.codegraph.tools '["codegraph_explore"]' -ocr config set mcp_servers.codegraph.setup 'codegraph init && codegraph index' -``` - -### 环境变量 - -| 变量 | 用途 | -|------|------| -| `OCR_LLM_URL` | LLM API 端点 URL | -| `OCR_LLM_TOKEN` | API 密钥 / 认证令牌 | -| `OCR_LLM_AUTH_HEADER` | Anthropic 认证头（`x-api-key` 或 `authorization`） | -| `OCR_LLM_EXTRA_HEADERS` | 逗号分隔的 `key=value` HTTP 头 | -| `OCR_LLM_MODEL` | 模型名称 | -| `OCR_LLM_PROTOCOL` | 协议：`anthropic` \| `openai` \| `openai-responses`；优先级高于 `OCR_USE_ANTHROPIC` | -| `OCR_LLM_TIMEOUT` | 每次请求的 HTTP 超时时间（秒），覆盖配置文件中的 `timeout_sec` | -| `OCR_USE_ANTHROPIC` | `true` = Anthropic，`false` = OpenAI Chat Completions（兼容字段，推荐改用 `OCR_LLM_PROTOCOL`） | +配置位于 `~/.opencodereview/config.json`，可被环境变量覆盖，涵盖供应商、模型、MCP 服务器、语言与遥测。完整的配置项参考、环境变量与 MCP 服务器配置，详见 **[配置](https://open-codereview.ai/docs/configuration)** 与 **[MCP 服务器](https://open-codereview.ai/docs/mcp)**。 ## 遥测 From 90306cafb4f66b66222deb6b8efdc4445b08e872 Mon Sep 17 00:00:00 2001 From: kite Date: Tue, 21 Jul 2026 18:09:02 +0800 Subject: [PATCH 2/5] docs(readme): slim README by removing sections duplicated on docs site (#426) --- README.ja-JP.md | 502 ++--------------------------------------------- README.ko-KR.md | 502 ++--------------------------------------------- README.md | 505 ++---------------------------------------------- README.ru-RU.md | 504 ++--------------------------------------------- README.zh-CN.md | 492 ++-------------------------------------------- 5 files changed, 65 insertions(+), 2440 deletions(-) diff --git a/README.ja-JP.md b/README.ja-JP.md index 72c754f2..6ea07cb5 100644 --- a/README.ja-JP.md +++ b/README.ja-JP.md @@ -99,116 +99,19 @@ Open Code Reviewのコア哲学は、決定論的エンジニアリングとエ #### インストール -**NPM経由（推奨）** - ```bash npm install -g @alibaba-group/open-code-review ``` インストール後、`ocr`コマンドがグローバルに利用可能になります。 -**更新** - -NPM でインストールした場合は、手動で最新バージョンへ更新できます： - -```bash -npm install -g @alibaba-group/open-code-review@latest -``` - -NPM インストール版の `ocr` は、既定でバックグラウンドで新しいバージョンを確認し、自動的に更新します。自動更新を無効にするには、`OCR_NO_UPDATE=1` を設定してください。 - -インストールスクリプトまたは手動ダウンロードしたバイナリでインストールした場合は、同じインストール/ダウンロードコマンドを再実行すると、ローカルのバイナリを最新リリースに置き換えられます。特定のリリースタグに固定する必要がある場合は `OCR_VERSION` を使います。 - -**GitHub Releaseから** - -1 つのコマンドで、お使いの OS / アーキテクチャ向けの最新バイナリをインストールできます（macOS / Linux）： - -```bash -curl -fsSL https://raw.githubusercontent.com/alibaba/open-code-review/main/install.sh | sh -``` - -このスクリプトは適切なリリースバイナリを選択し、SHA-256 チェックサムを検証して、`ocr` として `/usr/local/bin` にインストールします。インストール先は `OCR_INSTALL_DIR` で、リリースバージョンは `OCR_VERSION` で上書きできます： - -```bash -OCR_INSTALL_DIR="$HOME/.local/bin" OCR_VERSION=v1.3.13 \ - sh -c "$(curl -fsSL https://raw.githubusercontent.com/alibaba/open-code-review/main/install.sh)" -``` - -Windows（PowerShell 5.1+）では： - -```powershell -irm https://raw.githubusercontent.com/alibaba/open-code-review/main/install.ps1 | iex -``` - -このスクリプトは適切な Windows リリースバイナリを選択し、SHA-256 チェックサムを検証して、`ocr.exe` として `%LOCALAPPDATA%\Programs\ocr` にインストールします。インストール先は `OCR_INSTALL_DIR` で、リリースバージョンは `OCR_VERSION` で上書きできます： - -```powershell -$env:OCR_INSTALL_DIR = "$env:USERPROFILE\bin" -$env:OCR_VERSION = "v1.3.13" -irm https://raw.githubusercontent.com/alibaba/open-code-review/main/install.ps1 | iex -``` - -リモートスクリプトをシェルに直接パイプすると、インターネット上のコードが実行されます。先にダウンロードして内容を確認してから実行することを推奨します： - -```bash -curl -fsSL https://raw.githubusercontent.com/alibaba/open-code-review/main/install.sh -o install.sh -less install.sh && sh install.sh -``` - -```powershell -irm https://raw.githubusercontent.com/alibaba/open-code-review/main/install.ps1 -OutFile install.ps1 -notepad install.ps1 # 確認後: .\install.ps1 -``` - -
-手動ダウンロード（Windows を含む全プラットフォーム） - -[GitHub Releases](https://github.com/alibaba/open-code-review/releases)からお使いのプラットフォーム向けのバイナリをダウンロードします： - -```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 (x86_64) — ocr.exe を PATH の通ったディレクトリに移動してください -curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-amd64.exe - -# Windows (ARM64) — ocr.exe を PATH の通ったディレクトリに移動してください -curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-arm64.exe -``` - -
- -**ソースから** - -```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 -``` +その他のインストール方法（インストールスクリプト、GitHub Release バイナリ、ソースビルド）については、[インストールガイド](https://open-codereview.ai/docs/installation)を参照してください。 #### クイックスタート **1. LLMの設定** -**コードレビューの前に必ずLLMを設定する必要があります。** - -OCRは統一された**プロバイダー（Provider）**システムでLLM設定を管理します。多数の主要プロバイダーが組み込まれており、プライベートデプロイメントやその他の互換エンドポイントに接続するためのカスタムプロバイダーの追加もサポートしています。設定は`~/.opencodereview/config.json`に保存されます。 - -**オプションA: 対話的セットアップ（推奨）** +コードレビューの前にLLMの設定が必要です。[デリゲートモード](https://open-codereview.ai/docs/integrations/delegate)を使用する場合は不要です。 ```bash ocr config provider # ビルトインプロバイダーを選択またはカスタムプロバイダーを追加 @@ -219,91 +122,9 @@ ocr config model # アクティブなプロバイダーのモデル 対話的UIがプロバイダーの選択、APIキーの入力、モデル設定をガイドし、完了後に自動的に接続テストを行います。 -`ocr llm providers`を実行すると、すべてのビルトインプロバイダーを確認できます。ビルトインプロバイダーにはAPI URLとプロトコルがプリセットされているため、APIキーを提供するだけで使用できます。対応する環境変数（例：`ANTHROPIC_API_KEY`、`OPENAI_API_KEY`）が設定済みの場合、APIキーは自動的に読み取られます。 - -**カスタムプロバイダー**も対話的UIから追加できます — プロバイダー名、API URL、プロトコルタイプ（`anthropic`または`openai`）、APIキーを入力します。 +CLIセットアップ、環境変数、カスタムプロバイダーなどの高度な設定については、[設定ガイド](https://open-codereview.ai/docs/configuration)を参照してください。 -**オプションB: CLIセットアップ（CI/CDなど非対話環境向け）** - -`ocr config set`コマンドでプロバイダー設定を直接書き込みます。スクリプトや自動化に適しています。 - -ビルトインプロバイダーを使用する場合： - -```bash -ocr config set provider anthropic -ocr config set providers.anthropic.api_key your-api-key-here -ocr config set providers.anthropic.model claude-sonnet-4-6 -``` - -カスタムプロバイダーを使用する場合（プライベートゲートウェイやその他の互換エンドポイント）： - -```bash -ocr config set provider my-gateway -ocr config set custom_providers.my-gateway.url https://my-llm-gateway.internal/v1 -ocr config set custom_providers.my-gateway.protocol openai -ocr config set custom_providers.my-gateway.api_key your-api-key-here -ocr config set custom_providers.my-gateway.model gpt-4o -``` - -> カスタムプロバイダーでは`url`と`protocol`が必須です。サポートされるプロトコル：`anthropic`、`openai`、`openai-responses`。 - -オプション設定： - -| キー | 説明 | -|------|------| -| `providers..auth_header` | 認証ヘッダー：`x-api-key`または`authorization`（デフォルト：`authorization`） | -| `providers..extra_body` | リクエストボディにマージされるカスタムJSONフィールド | -| `providers..extra_headers` | カンマ区切りの `key=value` ペアで、各リクエストに追加されるカスタムHTTPヘッダー | -| `providers..models` | 対話的選択用のモデルリスト | - -**`extra_headers`（オプション）：** すべてのLLM APIリクエストにカスタムHTTPヘッダーを追加します。プロキシ、ゲートウェイ、追加ヘッダーを必要とするエンタープライズエンドポイント（組織ID、トレースIDなど）に便利です。形式はカンマ区切りの `key=value` ペアです。カンマを含む値はダブルクォートで囲んでください： - -```bash -ocr config set llm.extra_headers "X-Org-ID=org-123,X-Forwarded-For=\"1.2.3.4,5.6.7.8\"" -``` - -プロバイダーごとに追加ヘッダーを設定することもできます： - -```bash -ocr config set providers.anthropic.extra_headers "X-Org-ID=org-123" -``` - -**環境変数（最優先）** - -環境変数は設定ファイルの設定を上書きします。設定ファイルの書き込みが不便なCI/CDシナリオに適しています： - -```bash -export OCR_LLM_URL=https://api.anthropic.com/v1/messages -export OCR_LLM_TOKEN=your-api-key-here -export OCR_LLM_MODEL=claude-opus-4-6 -export OCR_USE_ANTHROPIC=true -``` - -OpenAI Responses API（GPT-5.x / o-シリーズモデル）を使うには、`OCR_USE_ANTHROPIC` の代わりに `OCR_LLM_PROTOCOL` を設定してください: - -```bash -export OCR_LLM_URL=https://api.openai.com/v1 -export OCR_LLM_TOKEN=your-openai-key -export OCR_LLM_MODEL=gpt-5.4 -export OCR_LLM_PROTOCOL=openai-responses -``` - -`OCR_LLM_PROTOCOL` は `anthropic`、`openai`、`openai-responses`を受け付け、`OCR_USE_ANTHROPIC` と同時に設定した場合は優先されます。 - -Claude Codeの環境変数（`ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_MODEL`）とも互換性があり、`~/.zshrc` / `~/.bashrc`からこれらのexportをパースします。 - -> **CC-Switchユーザー向けの注意**: [CC-Switch](https://github.com/farion1231/cc-switch)を[ルーティングサービス](https://www.ccswitch.io/en/docs?section=proxy&item=service)有効で使用している場合、プロバイダーの`url`をCC-Switchのプロキシアドレスに向けることで、追加設定なしで利用できます： -> - **Claude**プロバイダーの場合：`providers.anthropic.url`を`http://127.0.0.1:15721`に設定 -> - **Codex**プロバイダーの場合：対応するプロバイダーの`url`を`http://127.0.0.1:15721/v1`に設定 -> - `api_key`は任意の値で構いません。`extra_body`設定は引き続き有効です - -**2. 疎通テスト** - -```bash -ocr llm test -``` - -**3. レビュー** +**2. レビュー** ```bash cd your-project @@ -331,189 +152,6 @@ ocr delegate preview ocr delegate rule src/main.go src/handler.go ``` -### コーディングエージェントとの統合 - -OCRはスラッシュコマンドとしてAIコーディングエージェントにシームレスに統合でき、エージェントのワークフロー内で直接コードレビューが可能になります。 - -#### オプション1: Skillとしてインストール - -`npx`を使ってOCRスキルをプロジェクトにインストールします： - -```bash -npx skills add alibaba/open-code-review --skill open-code-review -``` - -これにより、[skillsレジストリ](skills/open-code-review/SKILL.md)から`open-code-review`スキルがインストールされ、コーディングエージェントにコードレビューのための`ocr`の呼び出し方、優先度による問題の分類、必要に応じた修正の適用を教えます。 - -**デリゲートモード** — コーディングエージェント自身がレビューを実行する場合（OCR はファイル選択とルール解決のみを担当、OCR 側の LLM 設定不要）： - -```bash -npx skills add alibaba/open-code-review --skill open-code-review-delegate -``` - -詳細は [skills/open-code-review-delegate/SKILL.md](skills/open-code-review-delegate/SKILL.md) を参照。 - -#### オプション2: Claude Codeプラグインとしてインストール - -[Claude Code](https://docs.anthropic.com/en/docs/claude-code)の場合、Claude Code内で以下のコマンドを実行してコマンドプラグインをインストールします： - -```bash -/plugin marketplace add alibaba/open-code-review -/plugin install open-code-review@open-code-review -``` - -これにより`/open-code-review:review`スラッシュコマンドが登録され、OCRを実行して問題を自動的にフィルタリング・修正します。また、`/open-code-review:delegate-review` デリゲートモードコマンドも提供されます（エージェントが自身の能力でレビューを実行し、OCR はファイル選択とルール解決を担当）。 - -#### オプション3: Codexプラグインとしてインストール - -ローカルCodexでは、このリポジトリからOpen Code Reviewプラグインをインストールできます： - -```bash -codex plugin marketplace add alibaba/open-code-review -codex -/plugins -``` - -ローカルcheckoutまたはforkでは、次を使用できます： - -```bash -codex plugin marketplace add . -codex -/plugins -``` - -`Open Code Review`をインストールして有効化した後、新しいCodex threadを開始して明示的に呼び出します： - -```text -@Open Code Review review my current changes -@Open Code Review review this branch against main -@Open Code Review review and fix high-confidence issues -``` - -これにより、ローカルOCR CLIを実行するCodex skillが登録されます： - -```bash -ocr review --audience agent -``` - -この統合はOCRの内部LLM backendを変更せず、Codex用のOpenAI Responses API endpoint設定も必要ありません。OCR自体には、CLI setupセクションで説明されている`ocr` CLIのインストールと設定が引き続き必要です。 - -韓国語ガイド：[`plugins/open-code-review/CODEX.ko-KR.md`](plugins/open-code-review/CODEX.ko-KR.md) - -#### オプション4: Cursorプラグインとしてインストール - -[Cursor](https://www.cursor.com/)では、このリポジトリからOpen Code Reviewプラグインをインストールできます： - -``` -cursor-plugin marketplace add alibaba/open-code-review -``` - -手動でmarketplaceを追加することもできます。Cursorで`/plugins`を開き、`Open Code Review`を検索してインストールしてください。 - -ローカルcheckoutまたはforkの場合： - -``` -cursor-plugin marketplace add . -``` - -インストール後、Cursorで次のように呼び出します： - -```text -@Open Code Review review my current changes -@Open Code Review review this branch against main -@Open Code Review review and fix high-confidence issues -``` - -これにより、ローカルOCR CLIを実行するCursor skillが登録されます： - -```bash -ocr review --audience agent -``` - -この統合はOCRの内部LLM backendを変更しません。OCR自体には、CLI setupセクションで説明されている`ocr` CLIのインストールと設定が引き続き必要です。 - -#### オプション5: コマンドファイルを直接コピー - -パッケージマネージャーを使わずに素早くセットアップしたい場合は、コマンドファイルをコピーするだけでClaude Codeで`/open-code-review`スラッシュコマンドを使えるようになります。 - -**プロジェクトレベル**（gitでチームと共有）： - -```bash -mkdir -p .claude/commands -curl -o .claude/commands/open-code-review.md \ - https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/claude-code/commands/review.md -``` - -**ユーザーレベル**（全プロジェクトで個人用にグローバル利用）： - -```bash -mkdir -p ~/.claude/commands -curl -o ~/.claude/commands/open-code-review.md \ - https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/claude-code/commands/review.md -``` - -デリゲートモード（OCR 側の LLM 設定不要）： - -```bash -# プロジェクトレベル -mkdir -p .claude/commands -curl -o .claude/commands/open-code-review-delegate.md \ - https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/claude-code/commands/delegate-review.md - -# ユーザーレベル -mkdir -p ~/.claude/commands -curl -o ~/.claude/commands/open-code-review-delegate.md \ - https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/claude-code/commands/delegate-review.md -``` - -> **前提条件**：すべての統合方法には `ocr` CLI のインストールが必要です。標準モードではさらに LLM の設定が必要です — 上記の[インストール](#インストール)と[LLM の設定](#1-llm-の設定)を参照。デリゲートモードでは OCR 側の LLM 設定は**不要**です。 - -### CI/CD統合 - -OCRをCI/CDパイプラインに統合して、Merge Request / Pull Requestのコードレビューを自動化できます。 - -CI統合のコアコマンド： - -```bash -ocr review \ - --from "origin/main" \ - --to "origin/feature-branch" \ - --format json -``` - -`--format json`フラグは、CIスクリプトでのパースに適した機械可読な結果を出力します。 - -各指摘には2つの構造化フィールドが付与され、CI統合はコメント本文を再パースせずに並べ替え・グループ化・フィルタリング・ビルドのゲート判定を行えます： - -| フィールド | 許可される値 | 説明 | -|-----------|-------------|------| -| `category` | `bug`、`security`、`performance`、`maintainability`、`test`、`style`、`documentation`、`other` | 指摘が属するカテゴリ。 | -| `severity` | `critical`、`high`、`medium`、`low` | 指摘の重要度。 | - -JSON出力ではこの2つのフィールドは`content`や`start_line`などと同じ階層に並びます。ターミナルでは、コメントの前にインラインの`[category · severity]`バッジとして表示され、重要度に応じて色分けされます。 - -統合例は[`examples/`](./examples/)ディレクトリを参照してください： - -- [`github_actions/`](./examples/github_actions/) — GitHub Actions統合の例 -- [`gitlab_ci/`](./examples/gitlab_ci/) — GitLab CI統合の例 -- [`gitflic_ci/`](./examples/gitflic_ci/) — GitFlic CI統合の例 -- [`gerrit_ci/`](./examples/gerrit_ci/) — Gerrit (Jenkins / Gerrit Trigger) 統合の例 - -#### GitHub Action - -GitHub 向けに、本リポジトリはリポジトリルートにすぐ使える composite Action（[`action.yml`](./action.yml)）を同梱しています。自分で `ocr review` をスクリプト化する代わりに、これを直接参照するだけで、checkout、OCR のインストール、レビューの実行、インラインコメントとサマリーコメントの投稿、アーティファクトのアップロード、再試行・冪等性までの全パイプラインを処理できます： - -```yaml -- uses: alibaba/open-code-review@main - with: - llm_url: ${{ secrets.OCR_LLM_URL }} - llm_auth_token: ${{ secrets.OCR_LLM_AUTH_TOKEN }} - llm_model: ${{ vars.OCR_LLM_MODEL }} - llm_use_anthropic: ${{ vars.OCR_LLM_USE_ANTHROPIC }} -``` - -再現性を高めるため、バージョンタグまたはコミット SHA に固定してください。完全なワークフローデモ、inputs/outputs の全一覧、コメント投稿モード（スティッキーサマリー、非破壊的なインクリメンタル投稿）については [`examples/github_actions/`](./examples/github_actions/) ディレクトリを参照してください。 - ## ドキュメント 完全なドキュメントは **[open-codereview.ai/docs](https://open-codereview.ai/docs)** にあります： @@ -521,131 +159,17 @@ GitHub 向けに、本リポジトリはリポジトリルートにすぐ使え - [クイックスタート](https://open-codereview.ai/docs/quickstart) — インストールして最初のレビューを実行 - [インストール](https://open-codereview.ai/docs/installation) — すべてのプラットフォームとパッケージマネージャー - [CLI リファレンス](https://open-codereview.ai/docs/cli-reference) — すべてのコマンドとフラグ -- [レビュールール](https://open-codereview.ai/docs/review-rules) — ルールの優先順位チェーン、ファイル形式、パスフィルタリング +- [レビュールール](https://open-codereview.ai/docs/review-rules) — レビュールールのカスタマイズ、パスフィルタリングとターゲティング - [設定](https://open-codereview.ai/docs/configuration) — 設定キーと環境変数 - [MCP サーバー](https://open-codereview.ai/docs/mcp) — 外部ツールでレビューエージェントを拡張 -- [コーディングエージェント連携](https://open-codereview.ai/docs/claude-code) — Claude Code、Agent Skill、委譲モード -- [CI/CD 連携](https://open-codereview.ai/docs/cicd) — パイプラインでレビューを実行 -- [アーキテクチャ](https://open-codereview.ai/docs/architecture) · [ツール](https://open-codereview.ai/docs/tools) · [セッションビューアー](https://open-codereview.ai/docs/viewer) · [テレメトリー](https://open-codereview.ai/docs/telemetry) · [FAQ](https://open-codereview.ai/docs/faq) - -## コマンド - -OCR は `review`、`scan`、`delegate`、`config`、`llm`、`session`、`viewer` などのコマンドを提供します。コマンドの完全な一覧とすべてのフラグ（再開可能なレビューや `ocr scan` / `ocr delegate` の全オプションを含む）については、**[CLI リファレンス](https://open-codereview.ai/docs/cli-reference)** を参照してください。 - -## 例 - -```bash -# 対話的プロバイダーとモデルのセットアップ -ocr config provider -ocr config model -ocr llm providers - -# カスタムプロバイダーを削除 -ocr config unset custom_providers.my-gateway - -# レビュー対象ファイルをプレビュー（LLM呼び出しなし） -ocr review --preview -ocr review -c abc123 -p - -# デフォルト設定でワークスペースの変更をレビュー -ocr review - -# 高めの同時実行数でブランチのdiffをレビュー -ocr review --from main --to my-feature --concurrency 4 - -# 特定のコミットを詳細なJSON出力でレビュー -ocr review --commit abc123 --format json --audience agent - -# 中断した範囲または単一 commit レビューを再開 -ocr session list -ocr session show -ocr review --from main --to my-feature --resume -ocr review --commit abc123 --resume - -# このレビューでモデルを選択またはオーバーライド -ocr review --model claude-opus-4-6 -ocr review --commit abc123 --model claude-sonnet-4-6 - -# 要件コンテキストを提供してより的確なレビューを実施 -ocr review --background "ログインAPIにレート制限を追加" - -# Markdownファイルから要件コンテキストを提供 -ocr review --background-file ./docs/my_business_context.md - -# インラインのコンテキストとローカルのコンテキストファイルを組み合わせる（両方が使用されます） -ocr review --background "認証に注目" --background-file ./docs/my_business_context.md - -# カスタムレビュールールを使用 -ocr review --rule /path/to/my-rules.json - -# ファイルに適用されるルールをプレビュー -ocr rules check src/main/java/com/example/Foo.java -ocr rules check --rule custom.json src/main/resources/mapper/UserMapper.xml - -# フルファイルスキャン：まずファイルリストをプレビュー（LLM呼び出しなし） -ocr scan --preview - -# リポジトリ全体をスキャン、支出を約500kトークンに制限 -ocr scan --max-tokens-budget 500000 - -# サブディレクトリをスキャン、生成ファイル/テストファイルをスキップ -ocr scan --path internal --exclude '**/*_test.go,**/generated/**' - -# 非gitディレクトリをJSON出力でスキャン（project_summaryを含む） -ocr scan --repo /path/to/plain/dir --format json - -# 最速スキャン：プランニング、重複排除、プロジェクトサマリーをスキップ -ocr scan --no-plan --no-dedup --no-summary - -# デリゲートモード — AI エージェントがレビューを実行（LLM 設定不要） -ocr delegate preview -ocr delegate preview --from main --to feature-branch -ocr delegate preview --commit abc123 -ocr delegate rule internal/handler.go internal/service.go cmd/main.go - -# ブラウザでレビューセッション履歴を表示 -ocr viewer -ocr viewer --addr :3000 -``` - -### ビューアーのセキュリティ - -ビューアーはセッションのJSONLコンテンツ（LLMリクエストメッセージとレスポンス）をHTTPで配信します。すべてのリクエストに対してHostヘッダーの許可リストを強制します：ループバック名（`localhost`、`127.0.0.0/8`、`::1`）と実際のバインドホストは常に許可されます。ワイルドカードバインド（`--addr :3000`、`--addr 0.0.0.0:3000`）やその他の非ループバックのホスト名は、環境変数`OCR_VIEWER_ALLOWED_HOSTS`（カンマ区切り）で追加する必要があります： - -```bash -OCR_VIEWER_ALLOWED_HOSTS=review.internal,ocr.lan ocr viewer --addr :3000 -``` - -これにより、ローカルビューアーに対するDNSリバインディング攻撃をブロックします。 - -## レビュールール - -OCR は 4 層の優先順位チェーン（`--rule` フラグ > プロジェクト設定 > グローバル設定 > 組み込みデフォルト）でレビュールールを解決し、インラインまたはファイルベースのルール、`**` グロブマッチング、`include` / `exclude` のパスフィルタリングをサポートします。ルールファイルの完全な形式とフィルタリングの意味については、**[レビュールール](https://open-codereview.ai/docs/review-rules)** を参照してください。 - -## 設定リファレンス - -設定は `~/.opencodereview/config.json` にあり、環境変数で上書きできます。プロバイダー、モデル、MCP サーバー、言語、テレメトリーをカバーします。設定キーの完全なリファレンス、環境変数、MCP サーバーのセットアップについては、**[設定](https://open-codereview.ai/docs/configuration)** と **[MCP サーバー](https://open-codereview.ai/docs/mcp)** を参照してください。 - -## テレメトリー - -可観測性（スパン、メトリクス）のためのOpenTelemetry統合。デフォルトでは無効です。 - -```bash -ocr config set telemetry.enabled true -ocr config set telemetry.exporter otlp -ocr config set telemetry.otlp_endpoint localhost:4317 -``` - -エクスポートデータにLLMのプロンプトとレスポンスを含めるには、`telemetry.content_logging`を設定してください。 - -**プロトコル選択：** 環境変数 `OTEL_EXPORTER_OTLP_PROTOCOL` でエクスポートプロトコルを選択できます： - -| 値 | トランスポート | 説明 | -|---|---|---| -| `grpc`（デフォルト） | gRPC | デフォルトポート 4317 | -| `http/protobuf` | HTTP | デフォルトポート 4318 | - -**Endpoint 形式：** `telemetry.otlp_endpoint` は `host:port` または `http://host:port` 形式のベースURLを指定します。パスを含める必要はありません。SDKが [OTLP仕様](https://opentelemetry.io/docs/specs/otlp/#otlphttp-request)に従いシグナルパス（例：`/v1/traces`）を自動的に付加します。 +- コーディングエージェント連携 — OCR を Claude Code、Codex、Cursor などに統合 + - [Skill](https://open-codereview.ai/docs/integrations/agent-skill) — 再利用可能なエージェントスキルとしてインストール + - [Plugin](https://open-codereview.ai/docs/integrations/claude-code) — Claude Code / Codex / Cursor プラグインとしてインストール + - [デリゲートモード](https://open-codereview.ai/docs/integrations/delegate) — エージェント自身の LLM でレビューを実行 +- [CI/CD 連携](https://open-codereview.ai/docs/cicd) — GitHub Actions、GitLab CI、GitFlic CI、Gerrit との統合 +- [セッションビューアー](https://open-codereview.ai/docs/viewer) — ブラウザでレビューセッションを閲覧・再生 +- [テレメトリー](https://open-codereview.ai/docs/telemetry) — 可観測性のためのOpenTelemetry統合 +- [FAQ](https://open-codereview.ai/docs/faq) — よくある質問とトラブルシューティング ## コントリビューション diff --git a/README.ko-KR.md b/README.ko-KR.md index a8db002d..6e65487e 100644 --- a/README.ko-KR.md +++ b/README.ko-KR.md @@ -99,116 +99,19 @@ agent의 강점은 동적 판단과 동적 context 검색이 중요한 지점에 #### 설치 -**NPM 사용(권장)** - ```bash npm install -g @alibaba-group/open-code-review ``` 설치 후 `ocr` 명령을 전역에서 사용할 수 있습니다. -**업데이트** - -NPM으로 설치했다면 최신 버전으로 수동 업데이트할 수 있습니다: - -```bash -npm install -g @alibaba-group/open-code-review@latest -``` - -NPM 설치의 `ocr`은 기본적으로 백그라운드에서 새 버전을 확인하고 자동으로 업데이트합니다. 자동 업데이트를 끄려면 `OCR_NO_UPDATE=1`을 설정하세요. - -설치 스크립트나 수동 다운로드한 binary로 설치했다면 같은 설치/다운로드 명령을 다시 실행해 로컬 binary를 최신 release로 교체할 수 있습니다. 특정 release tag로 고정해야 한다면 `OCR_VERSION`을 사용하세요. - -**GitHub Release 사용** - -명령 한 번으로 사용 중인 OS/아키텍처에 맞는 최신 binary를 설치합니다 (macOS / Linux): - -```bash -curl -fsSL https://raw.githubusercontent.com/alibaba/open-code-review/main/install.sh | sh -``` - -이 스크립트는 알맞은 릴리스 binary를 선택하고 SHA-256 체크섬을 검증한 뒤 `ocr`로 `/usr/local/bin`에 설치합니다. 설치 위치는 `OCR_INSTALL_DIR`로, 릴리스 버전은 `OCR_VERSION`으로 재정의할 수 있습니다: - -```bash -OCR_INSTALL_DIR="$HOME/.local/bin" OCR_VERSION=v1.3.13 \ - sh -c "$(curl -fsSL https://raw.githubusercontent.com/alibaba/open-code-review/main/install.sh)" -``` - -Windows (PowerShell 5.1+)에서는: - -```powershell -irm https://raw.githubusercontent.com/alibaba/open-code-review/main/install.ps1 | iex -``` - -이 스크립트는 알맞은 Windows 릴리스 binary를 선택하고 SHA-256 체크섬을 검증한 뒤 `ocr.exe`로 `%LOCALAPPDATA%\Programs\ocr`에 설치합니다. 설치 위치는 `OCR_INSTALL_DIR`로, 릴리스 버전은 `OCR_VERSION`으로 재정의할 수 있습니다: - -```powershell -$env:OCR_INSTALL_DIR = "$env:USERPROFILE\bin" -$env:OCR_VERSION = "v1.3.13" -irm https://raw.githubusercontent.com/alibaba/open-code-review/main/install.ps1 | iex -``` - -원격 스크립트를 셸로 바로 파이프하면 인터넷의 코드가 실행됩니다. 먼저 다운로드해 내용을 확인한 뒤 실행하는 방식을 권장합니다: - -```bash -curl -fsSL https://raw.githubusercontent.com/alibaba/open-code-review/main/install.sh -o install.sh -less install.sh && sh install.sh -``` - -```powershell -irm https://raw.githubusercontent.com/alibaba/open-code-review/main/install.ps1 -OutFile install.ps1 -notepad install.ps1 # 확인 후: .\install.ps1 -``` - -
-수동 다운로드 (Windows 포함 모든 플랫폼) - -[GitHub Releases](https://github.com/alibaba/open-code-review/releases)에서 사용 중인 플랫폼의 binary를 다운로드합니다. - -```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 (x86_64): ocr.exe를 PATH에 포함된 디렉터리로 이동하세요 -curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-amd64.exe - -# Windows (ARM64): ocr.exe를 PATH에 포함된 디렉터리로 이동하세요 -curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-arm64.exe -``` - -
- -**소스에서 빌드** - -```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 -``` +기타 설치 방법(설치 스크립트, GitHub Release binary, 소스 빌드)은 [설치 가이드](https://open-codereview.ai/docs/installation)를 참조하세요. #### Quick Start **1. LLM 설정** -**코드 리뷰를 실행하기 전에 반드시 LLM을 설정해야 합니다.** - -OCR은 통합 **Provider** 시스템으로 LLM 설정을 관리합니다. 다양한 주요 provider가 내장되어 있으며, 프라이빗 배포 또는 기타 호환 엔드포인트에 연결하기 위한 커스텀 provider 추가도 지원합니다. 설정은 `~/.opencodereview/config.json`에 저장됩니다. - -**Option A: 대화형 설정 (권장)** +코드 리뷰 전에 LLM 설정이 필요합니다. [위임 모드](https://open-codereview.ai/docs/integrations/delegate)를 사용하는 경우에는 불필요합니다. ```bash ocr config provider # built-in provider 선택 또는 custom provider 추가 @@ -219,91 +122,9 @@ ocr config model # 활성 provider의 model 선택 대화형 UI가 provider 선택, API key 입력, model 설정을 안내하며, 완료 후 자동으로 연결 테스트를 수행합니다. -`ocr llm providers`를 실행하면 모든 built-in provider를 확인할 수 있습니다. Built-in provider에는 API URL과 프로토콜이 사전 설정되어 있어 API key만 제공하면 바로 사용할 수 있습니다. 해당 환경 변수(예: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`)가 이미 설정되어 있으면 API key가 자동으로 읽힙니다. - -**커스텀 provider**도 대화형 UI에서 추가할 수 있습니다 — provider 이름, API URL, 프로토콜 타입(`anthropic` 또는 `openai`), API key를 입력합니다. +CLI 설정, 환경 변수, 커스텀 provider 등 고급 설정은 [설정 가이드](https://open-codereview.ai/docs/configuration)를 참조하세요. -**Option B: CLI 설정 (CI/CD 등 비대화형 환경용)** - -`ocr config set` 명령으로 provider 설정을 직접 작성합니다. 스크립트 및 자동화에 적합합니다. - -Built-in provider 사용: - -```bash -ocr config set provider anthropic -ocr config set providers.anthropic.api_key your-api-key-here -ocr config set providers.anthropic.model claude-sonnet-4-6 -``` - -커스텀 provider 사용 (프라이빗 게이트웨이 또는 기타 호환 엔드포인트): - -```bash -ocr config set provider my-gateway -ocr config set custom_providers.my-gateway.url https://my-llm-gateway.internal/v1 -ocr config set custom_providers.my-gateway.protocol openai -ocr config set custom_providers.my-gateway.api_key your-api-key-here -ocr config set custom_providers.my-gateway.model gpt-4o -``` - -> 커스텀 provider에서는 `url`과 `protocol`이 필수입니다. 지원 프로토콜: `anthropic`, `openai`, `openai-responses` - -선택 설정: - -| 키 | 설명 | -|----|------| -| `providers..auth_header` | 인증 header: `x-api-key` 또는 `authorization` (기본값: `authorization`) | -| `providers..extra_body` | 요청 body에 병합되는 커스텀 JSON 필드 | -| `providers..extra_headers` | 쉼표로 구분된 `key=value` 쌍, 각 요청에 추가되는 커스텀 HTTP 헤더 | -| `providers..models` | 대화형 선택용 model 목록 | - -**`extra_headers` (선택사항):** 모든 LLM API 요청에 커스텀 HTTP 헤더를 추가합니다. 프록시, 게이트웨이, 추가 헤더가 필요한 엔터프라이즈 엔드포인트(조직 ID, 트레이싱 ID 등)에 유용합니다. 형식은 쉼표로 구분된 `key=value` 쌍입니다. 쉼표가 포함된 값은 큰따옴표로 묶으세요: - -```bash -ocr config set llm.extra_headers "X-Org-ID=org-123,X-Forwarded-For=\"1.2.3.4,5.6.7.8\"" -``` - -provider 별로 추가 헤더를 설정할 수도 있습니다: - -```bash -ocr config set providers.anthropic.extra_headers "X-Org-ID=org-123" -``` - -**환경 변수 (가장 높은 우선순위)** - -환경 변수는 설정 파일의 값을 덮어씁니다. 설정 파일 작성이 불편한 CI/CD 시나리오에 적합합니다: - -```bash -export OCR_LLM_URL=https://api.anthropic.com/v1/messages -export OCR_LLM_TOKEN=your-api-key-here -export OCR_LLM_MODEL=claude-opus-4-6 -export OCR_USE_ANTHROPIC=true -``` - -OpenAI Responses API(GPT-5.x / o-시리즈 모델)를 사용하려면 `OCR_USE_ANTHROPIC` 대신 `OCR_LLM_PROTOCOL`을 사용하세요: - -```bash -export OCR_LLM_URL=https://api.openai.com/v1 -export OCR_LLM_TOKEN=your-openai-key -export OCR_LLM_MODEL=gpt-5.4 -export OCR_LLM_PROTOCOL=openai-responses -``` - -`OCR_LLM_PROTOCOL`은 `anthropic`, `openai`, `openai-responses`를 허용하며, `OCR_USE_ANTHROPIC`과 함께 설정하면 우선 적용됩니다. - -Claude Code 환경 변수(`ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`)와도 호환되며, `~/.zshrc` / `~/.bashrc`의 export도 파싱합니다. - -> **CC-Switch 사용자 참고**: [CC-Switch](https://github.com/farion1231/cc-switch)를 [routing service](https://www.ccswitch.io/en/docs?section=proxy&item=service)와 함께 사용한다면, provider의 `url`을 CC-Switch proxy 주소로 지정하여 추가 설정 없이 사용할 수 있습니다: -> - **Claude** provider: `providers.anthropic.url`을 `http://127.0.0.1:15721`로 설정 -> - **Codex** provider: 해당 provider의 `url`을 `http://127.0.0.1:15721/v1`로 설정 -> - `api_key`는 아무 값이나 사용 가능, `extra_body` 설정은 그대로 적용됨 - -**2. 연결 테스트** - -```bash -ocr llm test -``` - -**3. 리뷰 실행** +**2. 리뷰 실행** ```bash cd your-project @@ -331,189 +152,6 @@ ocr delegate preview ocr delegate rule src/main.go src/handler.go ``` -### Coding Agent와 통합 - -OCR은 AI coding agent에 slash command로 자연스럽게 통합할 수 있으며, agent workflow 안에서 바로 코드 리뷰를 실행할 수 있습니다. - -#### Option 1: Skill로 설치 - -`npx`로 OCR skill을 프로젝트에 설치합니다. - -```bash -npx skills add alibaba/open-code-review --skill open-code-review -``` - -이 명령은 [skills registry](skills/open-code-review/SKILL.md)의 `open-code-review` skill을 설치합니다. 이 skill은 coding agent가 `ocr`을 호출해 코드 리뷰를 수행하고, issue를 우선순위별로 분류하며, 필요한 경우 fix를 적용하는 방법을 알려줍니다. - -**위임 모드** — 코딩 에이전트가 직접 리뷰를 수행하길 원하는 경우 (OCR은 파일 선택과 규칙 해석만 담당, OCR 측 LLM 설정 불필요): - -```bash -npx skills add alibaba/open-code-review --skill open-code-review-delegate -``` - -자세한 내용은 [skills/open-code-review-delegate/SKILL.md](skills/open-code-review-delegate/SKILL.md)를 참조하세요. - -#### Option 2: Claude Code Plugin으로 설치 - -[Claude Code](https://docs.anthropic.com/en/docs/claude-code)에서는 Claude Code 안에서 다음 명령으로 command plugin을 설치합니다. - -```bash -/plugin marketplace add alibaba/open-code-review -/plugin install open-code-review@open-code-review -``` - -이렇게 하면 OCR을 실행하고 issue를 자동으로 필터링 및 수정하는 `/open-code-review:review` slash command가 등록됩니다. 또한 `/open-code-review:delegate-review` 위임 모드 명령도 제공됩니다 (에이전트가 자체 능력으로 리뷰를 수행하고, OCR은 파일 선택과 규칙 해석을 담당). - -#### Option 3: Codex Plugin으로 설치 - -local Codex에서는 이 repository에서 Open Code Review plugin을 설치합니다. - -```bash -codex plugin marketplace add alibaba/open-code-review -codex -/plugins -``` - -local checkout이나 fork에서는 다음을 사용할 수 있습니다. - -```bash -codex plugin marketplace add . -codex -/plugins -``` - -`Open Code Review`를 설치하고 활성화한 뒤, 새 Codex thread를 시작해 명시적으로 호출합니다. - -```text -@Open Code Review review my current changes -@Open Code Review review this branch against main -@Open Code Review review and fix high-confidence issues -``` - -이 plugin은 local OCR CLI를 실행하는 Codex skill을 등록합니다. - -```bash -ocr review --audience agent -``` - -이 통합은 OCR의 내부 LLM backend를 변경하지 않으며 Codex용 OpenAI Responses API endpoint 설정을 요구하지 않습니다. OCR 자체는 CLI 설정 섹션에 설명된 대로 `ocr` CLI 설치와 설정이 필요합니다. - -한국어 가이드: [`plugins/open-code-review/CODEX.ko-KR.md`](plugins/open-code-review/CODEX.ko-KR.md) - -#### Option 4: Cursor Plugin으로 설치 - -[Cursor](https://www.cursor.com/)에서는 이 repository에서 Open Code Review plugin을 설치합니다: - -``` -cursor-plugin marketplace add alibaba/open-code-review -``` - -수동으로 marketplace를 추가할 수도 있습니다. Cursor에서 `/plugins`를 열고 `Open Code Review`를 검색하여 설치합니다. - -local checkout이나 fork에서는 다음을 사용할 수 있습니다: - -``` -cursor-plugin marketplace add . -``` - -설치 후, Cursor에서 다음과 같이 호출합니다: - -```text -@Open Code Review review my current changes -@Open Code Review review this branch against main -@Open Code Review review and fix high-confidence issues -``` - -이 plugin은 local OCR CLI를 실행하는 Cursor skill을 등록합니다: - -```bash -ocr review --audience agent -``` - -이 통합은 OCR의 내부 LLM backend를 변경하지 않습니다. OCR 자체는 CLI 설정 섹션에 설명된 대로 `ocr` CLI 설치와 설정이 필요합니다. - -#### Option 5: Command 파일 직접 복사 - -package manager 없이 빠르게 설정하려면 command 파일을 복사해 Claude Code에서 `/open-code-review` slash command를 사용할 수 있습니다. - -**Project-level**(git으로 팀과 공유): - -```bash -mkdir -p .claude/commands -curl -o .claude/commands/open-code-review.md \ - https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/claude-code/commands/review.md -``` - -**User-level**(여러 프로젝트에서 개인 전역 사용): - -```bash -mkdir -p ~/.claude/commands -curl -o ~/.claude/commands/open-code-review.md \ - https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/claude-code/commands/review.md -``` - -위임 모드 (OCR 측 LLM 설정 불필요): - -```bash -# 프로젝트 수준 -mkdir -p .claude/commands -curl -o .claude/commands/open-code-review-delegate.md \ - https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/claude-code/commands/delegate-review.md - -# 사용자 수준 -mkdir -p ~/.claude/commands -curl -o ~/.claude/commands/open-code-review-delegate.md \ - https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/claude-code/commands/delegate-review.md -``` - -> **전제 조건**: 모든 통합 방식은 `ocr` CLI 설치가 필요합니다. 표준 모드는 추가로 LLM 설정이 필요합니다 — 위의 [설치](#설치) 및 [LLM 설정](#1-llm-설정)을 참조하세요. 위임 모드는 OCR 측 LLM 설정이 **필요 없습니다**. - -### CI/CD 통합 - -OCR은 CI/CD pipeline에 통합해 Merge Request / Pull Request 코드 리뷰를 자동화할 수 있습니다. - -CI 통합의 핵심 명령: - -```bash -ocr review \ - --from "origin/main" \ - --to "origin/feature-branch" \ - --format json -``` - -`--format json` flag는 CI script에서 파싱하기 좋은 machine-readable 결과를 출력합니다. - -각 finding에는 두 개의 구조화된 field가 포함되어, CI 통합에서 comment 텍스트를 다시 파싱하지 않고도 정렬·그룹화·필터링하거나 build를 gate할 수 있습니다: - -| Field | 허용 값 | 설명 | -|-------|--------|------| -| `category` | `bug`, `security`, `performance`, `maintainability`, `test`, `style`, `documentation`, `other` | 이슈가 속한 카테고리. | -| `severity` | `critical`, `high`, `medium`, `low` | 이슈의 중요도. | - -JSON 출력에서 두 field는 `content`, `start_line` 등과 같은 수준의 sibling으로 나타납니다. 터미널에서는 comment 앞에 인라인 `[category · severity]` badge로 표시되며 severity에 따라 색상이 지정됩니다. - -통합 예시는 [`examples/`](./examples/) 디렉터리를 참고하세요. - -- [`github_actions/`](./examples/github_actions/): GitHub Actions 통합 예시 -- [`gitlab_ci/`](./examples/gitlab_ci/): GitLab CI 통합 예시 -- [`gitflic_ci/`](./examples/gitflic_ci/): GitFlic CI 통합 예시 -- [`gerrit_ci/`](./examples/gerrit_ci/): Gerrit (Jenkins / Gerrit Trigger) 통합 예시 - -#### GitHub Action - -GitHub의 경우, 이 리포지터리는 루트에 바로 사용할 수 있는 composite Action([`action.yml`](./action.yml))을 제공합니다. 직접 `ocr review` 스크립트를 작성하는 대신 이를 참조하기만 하면 전체 파이프라인 — checkout, OCR 설치, review 실행, inline/summary comment 게시, artifact 업로드, 재시도 및 멱등성 — 을 모두 처리합니다: - -```yaml -- uses: alibaba/open-code-review@main - with: - llm_url: ${{ secrets.OCR_LLM_URL }} - llm_auth_token: ${{ secrets.OCR_LLM_AUTH_TOKEN }} - llm_model: ${{ vars.OCR_LLM_MODEL }} - llm_use_anthropic: ${{ vars.OCR_LLM_USE_ANTHROPIC }} -``` - -재현성을 위해 version tag나 commit SHA에 고정하세요. 전체 workflow 데모와 inputs/outputs, comment 게시 모드(sticky summary, incremental non-destructive posting)의 전체 목록은 [`examples/github_actions/`](./examples/github_actions/) 디렉터리를 참고하세요. - ## Documentation 전체 문서는 **[open-codereview.ai/docs](https://open-codereview.ai/docs)** 에서 확인할 수 있습니다: @@ -521,131 +159,17 @@ GitHub의 경우, 이 리포지터리는 루트에 바로 사용할 수 있는 c - [빠른 시작](https://open-codereview.ai/docs/quickstart) — 설치하고 첫 리뷰 실행하기 - [설치](https://open-codereview.ai/docs/installation) — 모든 플랫폼 및 패키지 매니저 - [CLI 레퍼런스](https://open-codereview.ai/docs/cli-reference) — 모든 명령어와 플래그 -- [리뷰 규칙](https://open-codereview.ai/docs/review-rules) — 규칙 우선순위 체인, 파일 형식, 경로 필터링 +- [리뷰 규칙](https://open-codereview.ai/docs/review-rules) — 리뷰 규칙 커스터마이징, 경로 필터링 및 타겟팅 - [설정](https://open-codereview.ai/docs/configuration) — 설정 키와 환경 변수 - [MCP 서버](https://open-codereview.ai/docs/mcp) — 외부 도구로 리뷰 에이전트 확장 -- [코딩 에이전트 연동](https://open-codereview.ai/docs/claude-code) — Claude Code, Agent Skill, 위임 모드 -- [CI/CD 연동](https://open-codereview.ai/docs/cicd) — 파이프라인에서 리뷰 실행 -- [아키텍처](https://open-codereview.ai/docs/architecture) · [도구](https://open-codereview.ai/docs/tools) · [세션 뷰어](https://open-codereview.ai/docs/viewer) · [텔레메트리](https://open-codereview.ai/docs/telemetry) · [FAQ](https://open-codereview.ai/docs/faq) - -## Commands - -OCR는 `review`, `scan`, `delegate`, `config`, `llm`, `session`, `viewer` 등의 명령어를 제공합니다. 전체 명령어 목록과 모든 플래그(재개 가능한 리뷰 및 `ocr scan` / `ocr delegate`의 전체 옵션 포함)는 **[CLI 레퍼런스](https://open-codereview.ai/docs/cli-reference)** 를 참조하세요. - -## Examples - -```bash -# 대화형 provider 및 model 설정 -ocr config provider -ocr config model -ocr llm providers - -# custom provider 삭제 -ocr config unset custom_providers.my-gateway - -# 리뷰 대상 파일 미리보기(LLM call 없음) -ocr review --preview -ocr review -c abc123 -p - -# default 설정으로 workspace 변경 리뷰 -ocr review - -# 더 높은 concurrency로 branch diff 리뷰 -ocr review --from main --to my-feature --concurrency 4 - -# 특정 commit을 verbose JSON output으로 리뷰 -ocr review --commit abc123 --format json --audience agent - -# 중단된 range 또는 단일 commit review 재개 -ocr session list -ocr session show -ocr review --from main --to my-feature --resume -ocr review --commit abc123 --resume - -# 이번 리뷰에서 model 선택 또는 override -ocr review --model claude-opus-4-6 -ocr review --commit abc123 --model claude-sonnet-4-6 - -# 요구사항 컨텍스트를 제공하여 더 정확한 리뷰 수행 -ocr review --background "로그인 API에 rate limiting 추가" - -# Markdown 파일에서 요구사항 컨텍스트 제공 -ocr review --background-file ./docs/my_business_context.md - -# inline 컨텍스트와 로컬 컨텍스트 파일을 함께 사용(둘 다 적용됨) -ocr review --background "인증에 집중" --background-file ./docs/my_business_context.md - -# custom review rules 사용 -ocr review --rule /path/to/my-rules.json - -# 파일에 적용될 rule 미리보기 -ocr rules check src/main/java/com/example/Foo.java -ocr rules check --rule custom.json src/main/resources/mapper/UserMapper.xml - -# 전체 파일 스캔: 먼저 파일 목록 미리보기 (LLM call 없음) -ocr scan --preview - -# 전체 repo 스캔, 비용을 ~500k 토큰으로 제한 -ocr scan --max-tokens-budget 500000 - -# 하위 디렉터리 스캔, 생성/테스트 파일 건너뛰기 -ocr scan --path internal --exclude '**/*_test.go,**/generated/**' - -# 비-git 디렉터리를 JSON output으로 스캔 (project_summary 포함) -ocr scan --repo /path/to/plain/dir --format json - -# 가장 빠른 스캔: planning, 중복 제거, 프로젝트 요약 건너뛰기 -ocr scan --no-plan --no-dedup --no-summary - -# 위임 모드 — AI 에이전트가 리뷰 수행 (LLM 설정 불필요) -ocr delegate preview -ocr delegate preview --from main --to feature-branch -ocr delegate preview --commit abc123 -ocr delegate rule internal/handler.go internal/service.go cmd/main.go - -# browser에서 review session history 보기 -ocr viewer -ocr viewer --addr :3000 -``` - -### Viewer 보안 - -viewer는 session JSONL 내용(LLM request messages와 responses)을 HTTP로 제공합니다. 모든 request에 대해 Host header allowlist를 적용합니다. loopback 이름(`localhost`, `127.0.0.0/8`, `::1`)과 실제 bind host는 항상 허용됩니다. wildcard bind(`--addr :3000`, `--addr 0.0.0.0:3000`)와 다른 non-loopback hostname은 `OCR_VIEWER_ALLOWED_HOSTS` 환경 변수에 comma-separated 값으로 추가해야 합니다. - -```bash -OCR_VIEWER_ALLOWED_HOSTS=review.internal,ocr.lan ocr viewer --addr :3000 -``` - -이 설정은 local viewer를 대상으로 하는 DNS rebinding 공격을 차단합니다. - -## Review Rules - -OCR는 4단계 우선순위 체인(`--rule` 플래그 > 프로젝트 설정 > 전역 설정 > 내장 기본값)으로 리뷰 규칙을 해석하며, 인라인 또는 파일 기반 규칙, `**` glob 매칭, `include` / `exclude` 경로 필터링을 지원합니다. 전체 규칙 파일 형식과 필터링 동작은 **[리뷰 규칙](https://open-codereview.ai/docs/review-rules)** 을 참조하세요. - -## Configuration Reference - -설정은 `~/.opencodereview/config.json`에 저장되며 환경 변수로 재정의할 수 있습니다. 프로바이더, 모델, MCP 서버, 언어, 텔레메트리를 다룹니다. 전체 설정 키 레퍼런스, 환경 변수, MCP 서버 설정은 **[설정](https://open-codereview.ai/docs/configuration)** 및 **[MCP 서버](https://open-codereview.ai/docs/mcp)** 를 참조하세요. - -## Telemetry - -관측성을 위한 OpenTelemetry 통합(spans, metrics)입니다. 기본값은 disabled입니다. - -```bash -ocr config set telemetry.enabled true -ocr config set telemetry.exporter otlp -ocr config set telemetry.otlp_endpoint localhost:4317 -``` - -exported data에 LLM prompt와 response를 포함하려면 `telemetry.content_logging`을 설정합니다. - -**프로토콜 선택:** 환경 변수 `OTEL_EXPORTER_OTLP_PROTOCOL`로 export 프로토콜을 선택할 수 있습니다: - -| 값 | 전송 방식 | 설명 | -|---|---|---| -| `grpc` (기본값) | gRPC | 기본 포트 4317 | -| `http/protobuf` | HTTP | 기본 포트 4318 | - -**Endpoint 형식:** `telemetry.otlp_endpoint`는 `host:port` 또는 `http://host:port` 형식의 base URL을 지정합니다. 경로를 포함할 필요가 없습니다. SDK가 [OTLP 사양](https://opentelemetry.io/docs/specs/otlp/#otlphttp-request)에 따라 signal 경로(예: `/v1/traces`)를 자동으로 추가합니다. +- 코딩 에이전트 연동 — OCR을 Claude Code, Codex, Cursor 등에 통합 + - [Skill](https://open-codereview.ai/docs/integrations/agent-skill) — 재사용 가능한 에이전트 스킬로 설치 + - [Plugin](https://open-codereview.ai/docs/integrations/claude-code) — Claude Code / Codex / Cursor 플러그인으로 설치 + - [위임 모드](https://open-codereview.ai/docs/integrations/delegate) — 에이전트 자체 LLM으로 리뷰 수행 +- [CI/CD 연동](https://open-codereview.ai/docs/cicd) — GitHub Actions, GitLab CI, GitFlic CI, Gerrit 통합 +- [세션 뷰어](https://open-codereview.ai/docs/viewer) — 브라우저에서 리뷰 세션 탐색 및 재생 +- [텔레메트리](https://open-codereview.ai/docs/telemetry) — 관측성을 위한 OpenTelemetry 통합 +- [FAQ](https://open-codereview.ai/docs/faq) — 자주 묻는 질문과 문제 해결 ## Contributing diff --git a/README.md b/README.md index 4de72de3..e75676cd 100644 --- a/README.md +++ b/README.md @@ -99,116 +99,19 @@ The agent's strengths are concentrated where they matter most — dynamic decisi #### Install -**Via NPM (Recommended)** - ```bash npm install -g @alibaba-group/open-code-review ``` After installation, the `ocr` command is available globally. -**Update** - -If you installed via NPM, update manually to the latest version: - -```bash -npm install -g @alibaba-group/open-code-review@latest -``` - -NPM installations also check for newer versions in the background by default and upgrade automatically. To disable auto-updates, set `OCR_NO_UPDATE=1`. - -If you installed with the install script or a manually downloaded binary, rerun the same install/download command to replace the local binary with the latest release. Use `OCR_VERSION` when you need to pin a specific release tag. - -**From GitHub Release** - -Install the latest binary for your OS/architecture with one command (macOS / Linux): - -```bash -curl -fsSL https://raw.githubusercontent.com/alibaba/open-code-review/main/install.sh | sh -``` - -The script picks the right release binary, verifies its SHA-256 checksum, and installs it as `ocr` in `/usr/local/bin`. Override the target with `OCR_INSTALL_DIR` or pin a release with `OCR_VERSION`: - -```bash -OCR_INSTALL_DIR="$HOME/.local/bin" OCR_VERSION=v1.3.13 \ - sh -c "$(curl -fsSL https://raw.githubusercontent.com/alibaba/open-code-review/main/install.sh)" -``` - -On Windows (PowerShell 5.1+): - -```powershell -irm https://raw.githubusercontent.com/alibaba/open-code-review/main/install.ps1 | iex -``` - -The script picks the right Windows release binary, verifies its SHA-256 checksum, and installs it as `ocr.exe` in `%LOCALAPPDATA%\Programs\ocr`. Override the target with `OCR_INSTALL_DIR` or pin a release with `OCR_VERSION`: - -```powershell -$env:OCR_INSTALL_DIR = "$env:USERPROFILE\bin" -$env:OCR_VERSION = "v1.3.13" -irm https://raw.githubusercontent.com/alibaba/open-code-review/main/install.ps1 | iex -``` - -Piping a remote script into a shell executes code from the internet. Prefer downloading and inspecting first: - -```bash -curl -fsSL https://raw.githubusercontent.com/alibaba/open-code-review/main/install.sh -o install.sh -less install.sh && sh install.sh -``` - -```powershell -irm https://raw.githubusercontent.com/alibaba/open-code-review/main/install.ps1 -OutFile install.ps1 -notepad install.ps1 # review, then: .\install.ps1 -``` - -
-Manual download (all platforms, including Windows) - -Download the binary for your platform from [GitHub Releases](https://github.com/alibaba/open-code-review/releases): - -```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 (x86_64) — move ocr.exe to a directory in your PATH -curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-amd64.exe - -# Windows (ARM64) — move ocr.exe to a directory in your PATH -curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-arm64.exe -``` - -
- -**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 -``` +For other installation methods (install script, GitHub Release binary, from source), see [Installation](https://open-codereview.ai/docs/installation). #### Quick Start **1. Configure LLM** -**You must configure an LLM before reviewing code.** - -OCR manages LLM configuration through a unified **Provider** system. It ships with many popular built-in providers and also supports adding custom providers to connect to private deployments or other compatible endpoints. Config is stored in `~/.opencodereview/config.json`. - -**Option A: Interactive setup (Recommended)** +You must configure an LLM before reviewing code, unless you use [Delegation Mode](https://open-codereview.ai/docs/integrations/delegate). ```bash ocr config provider # Select a built-in provider or add a custom one @@ -219,91 +122,9 @@ ocr config model # Pick a model for the active provider The interactive UI guides you through provider selection, API key entry, and model configuration, then automatically tests connectivity. -Run `ocr llm providers` to see all built-in providers. Built-in providers come with preset API URLs and protocols — just supply an API key to get started. If the corresponding environment variable is already set (e.g. `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`), the API key is picked up automatically. - -**Custom providers** can also be added through the interactive UI — you'll need to provide a name, API URL, protocol type (`anthropic` or `openai`), and API key. - -**Option B: CLI setup (for CI/CD and non-interactive environments)** - -Use `ocr config set` to write provider configuration directly, suitable for scripts and automation. - -Using a built-in provider: - -```bash -ocr config set provider anthropic -ocr config set providers.anthropic.api_key your-api-key-here -ocr config set providers.anthropic.model claude-sonnet-4-6 -``` - -Using a custom provider (private gateway or other compatible endpoint): - -```bash -ocr config set provider my-gateway -ocr config set custom_providers.my-gateway.url https://my-llm-gateway.internal/v1 -ocr config set custom_providers.my-gateway.protocol openai -ocr config set custom_providers.my-gateway.api_key your-api-key-here -ocr config set custom_providers.my-gateway.model gpt-4o -``` - -> `url` and `protocol` are required for custom providers. Supported protocols: `anthropic`, `openai`, `openai-responses`. - -Optional settings: - -| Key | Description | -|-----|-------------| -| `providers..auth_header` | Auth header: `x-api-key` or `authorization` (default: `authorization`) | -| `providers..extra_body` | Custom JSON fields merged into the request body | -| `providers..extra_headers` | Comma-separated `key=value` pairs of custom HTTP headers added to every request | -| `providers..models` | Model list for interactive selection | - -**`extra_headers` (optional):** Adds custom HTTP headers to every LLM API request. Useful for proxies, gateways, or enterprise endpoints that require additional headers (e.g. organization IDs, tracing IDs). Format is comma-separated `key=value` pairs. Double-quote values that contain commas: - -```bash -ocr config set llm.extra_headers "X-Org-ID=org-123,X-Forwarded-For=\"1.2.3.4,5.6.7.8\"" -``` - -You can also set extra headers per-provider: - -```bash -ocr config set providers.anthropic.extra_headers "X-Org-ID=org-123" -``` - -**Environment variables (highest priority)** - -Environment variables override config file settings, useful in CI/CD where writing config files is inconvenient: - -```bash -export OCR_LLM_URL=https://api.anthropic.com/v1/messages -export OCR_LLM_TOKEN=your-api-key-here -export OCR_LLM_MODEL=claude-opus-4-6 -export OCR_USE_ANTHROPIC=true -``` - -To use the OpenAI Responses API (GPT-5.x / o-series), set `OCR_LLM_PROTOCOL` instead of `OCR_USE_ANTHROPIC`: - -```bash -export OCR_LLM_URL=https://api.openai.com/v1 -export OCR_LLM_TOKEN=your-openai-key -export OCR_LLM_MODEL=gpt-5.4 -export OCR_LLM_PROTOCOL=openai-responses -``` - -`OCR_LLM_PROTOCOL` accepts `anthropic`, `openai`, `openai-responses`, and takes priority over `OCR_USE_ANTHROPIC` when both are set. - -Also compatible with Claude Code environment variables (`ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`) and parses `~/.zshrc` / `~/.bashrc` for those exports. - -> **Note for CC-Switch Users**: If you are using [CC-Switch](https://github.com/farion1231/cc-switch) with [routing service](https://www.ccswitch.io/en/docs?section=proxy&item=service) enabled, you can point the provider's `url` to the CC-Switch proxy address without additional configuration: -> - For **Claude** provider: set `providers.anthropic.url` to `http://127.0.0.1:15721` -> - For **Codex** provider: set the corresponding provider's `url` to `http://127.0.0.1:15721/v1` -> - `api_key` can be any value; `extra_body` settings still apply - -**2. Test Connectivity** - -```bash -ocr llm test -``` +For CLI setup, environment variables, custom providers, and other advanced configuration, see [Configuration](https://open-codereview.ai/docs/configuration). -**3. Review** +**2. Review** ```bash cd your-project @@ -331,191 +152,6 @@ ocr delegate preview ocr delegate rule src/main.go src/handler.go ``` -### Integrate with Coding Agents - -OCR can be seamlessly integrated into AI coding agents as a slash command, enabling code review directly within your agent workflow. - -#### Option 1: Install as a Skill - -Use `npx` to install the OCR skill into your project: - -```bash -npx skills add alibaba/open-code-review --skill open-code-review -``` - -This installs the `open-code-review` skill from the [skills registry](skills/open-code-review/SKILL.md), which teaches your coding agent how to invoke `ocr` for code review, classify issues by priority, and optionally apply fixes. - -**Delegation mode** — if you want your coding agent to perform the review itself (using OCR only for file selection and rule resolution, no LLM configuration needed on the OCR side): - -```bash -npx skills add alibaba/open-code-review --skill open-code-review-delegate -``` - -See [skills/open-code-review-delegate/SKILL.md](skills/open-code-review-delegate/SKILL.md) for details. - -#### Option 2: Install as a Claude Code Plugin - -For [Claude Code](https://docs.anthropic.com/en/docs/claude-code), install the command plugin through the following command in Claude Code: - -```bash -/plugin marketplace add alibaba/open-code-review -/plugin install open-code-review@open-code-review -``` - -This registers the `/open-code-review:review` slash command, which runs OCR and automatically filters and fixes issues. It also provides `/open-code-review:delegate-review` for delegation mode (the agent reviews using its own capabilities while OCR handles file selection and rules). - -#### Option 3: Install as a Codex Plugin - -For local Codex, install the Open Code Review plugin from this repository: - -```bash -codex plugin marketplace add alibaba/open-code-review -codex -/plugins -``` - -For a local checkout or fork: - -```bash -codex plugin marketplace add . -codex -/plugins -``` - -Install and enable `Open Code Review`, then start a new Codex thread and invoke it explicitly: - -```text -@Open Code Review review my current changes -@Open Code Review review this branch against main -@Open Code Review review and fix high-confidence issues -``` - -This registers a Codex skill that runs the local OCR CLI: - -```bash -ocr review --audience agent -``` - -This integration does not change OCR's internal LLM backend and does not require configuring an OpenAI Responses API endpoint for Codex. OCR itself still requires the `ocr` CLI to be installed and configured as described in the CLI setup section. - -Korean guide: [`plugins/open-code-review/CODEX.ko-KR.md`](plugins/open-code-review/CODEX.ko-KR.md) - -#### Option 4: Install as a Cursor Plugin - -For [Cursor](https://www.cursor.com/), install the Open Code Review plugin from this repository: - -``` -cursor-plugin marketplace add alibaba/open-code-review -``` - -Or add the marketplace manually. In Cursor, open `/plugins`, search for `Open Code Review`, and install it. - -For a local checkout or fork: - -``` -cursor-plugin marketplace add . -``` - -After installation, invoke it in Cursor: - -```text -@Open Code Review review my current changes -@Open Code Review review this branch against main -@Open Code Review review and fix high-confidence issues -``` - -This registers a Cursor skill that runs the local OCR CLI: - -```bash -ocr review --audience agent -``` - -This integration does not change OCR's internal LLM backend. OCR itself still requires the `ocr` CLI to be installed and configured as described in the CLI setup section. - -#### Option 5: Copy the Command File Directly - -For a quick setup without any package manager, simply copy the command file to use the `/open-code-review` slash command in Claude Code. - -**Project-level** (shared with team via git): - -```bash -mkdir -p .claude/commands -curl -o .claude/commands/open-code-review.md \ - https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/claude-code/commands/review.md -``` - -**User-level** (personal global use across all projects): - -```bash -mkdir -p ~/.claude/commands -curl -o ~/.claude/commands/open-code-review.md \ - https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/claude-code/commands/review.md -``` - -For delegation mode (no LLM configuration needed on OCR side): - -```bash -# Project-level -mkdir -p .claude/commands -curl -o .claude/commands/open-code-review-delegate.md \ - https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/claude-code/commands/delegate-review.md - -# User-level -mkdir -p ~/.claude/commands -curl -o ~/.claude/commands/open-code-review-delegate.md \ - https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/claude-code/commands/delegate-review.md -``` - -> **Prerequisite**: All integration methods require the `ocr` CLI to be installed. Standard mode additionally requires an LLM configured — see [Install](#install) and [Configure LLM](#1-configure-llm) above. Delegation mode does **not** require LLM configuration on the OCR side. - -### CI/CD Integration - -OCR can be integrated into CI/CD pipelines to automate code review on Merge Requests / Pull Requests. - -The core command for CI integration: - -```bash -ocr review \ - --from "origin/main" \ - --to "" \ - --format json -``` - -The `--from` flag accepts a branch ref (e.g., `origin/main`) or commit SHA as the base, while `--to` accepts a commit SHA or branch ref as the head. In CI environments, using commit SHA for `--to` is recommended to correctly handle fork PRs/MRs where the source branch doesn't exist on the origin remote. - -The `--format json` flag outputs machine-readable results suitable for parsing in CI scripts. - -Each finding carries two structured fields so CI integrations can sort, group, filter, or gate builds without re-parsing comment text: - -| Field | Allowed values | Notes | -|-------|----------------|-------| -| `category` | `bug`, `security`, `performance`, `maintainability`, `test`, `style`, `documentation`, `other` | The category the issue belongs to. | -| `severity` | `critical`, `high`, `medium`, `low` | The importance of the issue. | - -In JSON output the two fields appear as siblings alongside `content`, `start_line`, etc. In the terminal, they render as an inline `[category · severity]` badge before the comment, colored by severity. - -See the [`examples/`](./examples/) directory for integration examples: - -- [`github_actions/`](./examples/github_actions/) — GitHub Actions integration example -- [`gitlab_ci/`](./examples/gitlab_ci/) — GitLab CI integration example -- [`gitflic_ci/`](./examples/gitflic_ci/) — GitFlic CI integration example -- [`gerrit_ci/`](./examples/gerrit_ci/) — Gerrit (Jenkins / Gerrit Trigger) integration example - -#### GitHub Action - -For GitHub, this repository also ships a ready-to-use composite Action at the repo root ([`action.yml`](./action.yml)). Instead of scripting `ocr review` yourself, reference it directly and it handles the full pipeline — checkout, OCR install, running the review, posting inline and summary comments, uploading artifacts, and retry/idempotency: - -```yaml -- uses: alibaba/open-code-review@main - with: - llm_url: ${{ secrets.OCR_LLM_URL }} - llm_auth_token: ${{ secrets.OCR_LLM_AUTH_TOKEN }} - llm_model: ${{ vars.OCR_LLM_MODEL }} - llm_use_anthropic: ${{ vars.OCR_LLM_USE_ANTHROPIC }} -``` - -Pin to a version tag or commit SHA for reproducibility. See the [`examples/github_actions/`](./examples/github_actions/) directory for a complete workflow demo and the full list of inputs, outputs, and comment-posting modes (sticky summary, incremental non-destructive posting). - ## Documentation Full documentation lives at **[open-codereview.ai/docs](https://open-codereview.ai/docs)**: @@ -523,132 +159,17 @@ Full documentation lives at **[open-codereview.ai/docs](https://open-codereview. - [Quickstart](https://open-codereview.ai/docs/quickstart) — install and run your first review - [Installation](https://open-codereview.ai/docs/installation) — all platforms and package managers - [CLI Reference](https://open-codereview.ai/docs/cli-reference) — every command and flag -- [Review Rules](https://open-codereview.ai/docs/review-rules) — rule priority chain, file format, and path filtering +- [Review Rules](https://open-codereview.ai/docs/review-rules) — customize review rules with path filtering and targeting - [Configuration](https://open-codereview.ai/docs/configuration) — config keys and environment variables - [MCP Server](https://open-codereview.ai/docs/mcp) — extend the review agent with external tools -- [Coding Agent Integrations](https://open-codereview.ai/docs/claude-code) — Claude Code, Agent Skill, and delegation mode -- [CI/CD Integration](https://open-codereview.ai/docs/cicd) — run reviews in your pipeline -- [Architecture](https://open-codereview.ai/docs/architecture) · [Tools](https://open-codereview.ai/docs/tools) · [Session Viewer](https://open-codereview.ai/docs/viewer) · [Telemetry](https://open-codereview.ai/docs/telemetry) · [FAQ](https://open-codereview.ai/docs/faq) - -## Commands - -OCR provides `review`, `scan`, `delegate`, `config`, `llm`, `session`, and `viewer` commands. For the complete command list and every flag — including resumable reviews and the full `ocr scan` / `ocr delegate` options — see the **[CLI Reference](https://open-codereview.ai/docs/cli-reference)**. - -## Examples - -```bash -# Interactive provider and model setup -ocr config provider -ocr config model -ocr llm providers - -# Delete a custom provider -ocr config unset custom_providers.my-gateway - -# Preview which files will be reviewed (no LLM calls) -ocr review --preview -ocr review -c abc123 -p - -# Review workspace changes with default settings -ocr review - -# Review branch diff with higher concurrency -ocr review --from main --to my-feature --concurrency 4 - -# Review a specific commit with verbose JSON output -ocr review --commit abc123 --format json --audience agent - -# Resume an interrupted range or commit review -ocr session list -ocr session show -ocr review --from main --to my-feature --resume -ocr review --commit abc123 --resume - -# Select or override model for this review -ocr review --model claude-opus-4-6 -ocr review --commit abc123 --model claude-sonnet-4-6 - -# Provide requirement context for more targeted review -ocr review --background "Adding rate limiting to the login API" - -# Provide requirement context from a Markdown file -ocr review --background-file ./docs/my_business_context.md - -# Combine inline context with a local context file (both are used) -ocr review --background "Focus on auth" --background-file ./docs/my_business_context.md - -# Use custom review rules -ocr review --rule /path/to/my-rules.json - -# Preview which rule applies to a file -ocr rules check src/main/java/com/example/Foo.java -ocr rules check --rule custom.json src/main/resources/mapper/UserMapper.xml - -# Full-file scan: preview the file list first (no LLM calls) -ocr scan --preview - -# Scan the whole repo, cap spend at ~500k tokens -ocr scan --max-tokens-budget 500000 - -# Scan a subdirectory, skipping generated/test files -ocr scan --path internal --exclude '**/*_test.go,**/generated/**' - -# Scan a non-git directory with JSON output (includes project_summary) -ocr scan --repo /path/to/plain/dir --format json - -# Fastest scan: skip planning, dedup, and the project summary -ocr scan --no-plan --no-dedup --no-summary - -# Delegation mode — let your AI agent drive the review (no LLM config needed) -ocr delegate preview -ocr delegate preview --from main --to feature-branch -ocr delegate preview --commit abc123 -ocr delegate rule internal/handler.go internal/service.go cmd/main.go - -# View review session history in browser -ocr viewer -ocr viewer --addr :3000 -``` - -### Viewer security - -The viewer serves session JSONL contents (LLM request messages and responses) over HTTP. It enforces a Host-header allowlist on every request: loopback names (`localhost`, `127.0.0.0/8`, `::1`) and the concrete bind host are always allowed. Wildcard binds (`--addr :3000`, `--addr 0.0.0.0:3000`) and other non-loopback Hostnames must be added via the `OCR_VIEWER_ALLOWED_HOSTS` environment variable (comma-separated): - -```bash -OCR_VIEWER_ALLOWED_HOSTS=review.internal,ocr.lan ocr viewer --addr :3000 -``` - -This blocks DNS-rebinding attacks against the local viewer. - -## Review Rules - -OCR resolves review rules through a four-layer priority chain (`--rule` flag > project config > global config > built-in defaults), and supports inline or file-based rules, `**` glob matching, and `include` / `exclude` path filtering. For the full rule file format and filtering semantics, see **[Review Rules](https://open-codereview.ai/docs/review-rules)**. - -## Configuration Reference - -Configuration lives in `~/.opencodereview/config.json` and can be overridden by environment variables. It covers providers, models, MCP servers, language, and telemetry. For the complete key reference, environment variables, and MCP server setup, see **[Configuration](https://open-codereview.ai/docs/configuration)** and **[MCP Server](https://open-codereview.ai/docs/mcp)**. - -## Telemetry - -OpenTelemetry integration for observability (spans, metrics). Disabled by default. - -```bash -ocr config set telemetry.enabled true -ocr config set telemetry.exporter otlp -ocr config set telemetry.otlp_endpoint localhost:4317 -``` - -Set `telemetry.content_logging` to include LLM prompts and responses in exported data. - -**Protocol selection:** Set the environment variable `OTEL_EXPORTER_OTLP_PROTOCOL` to choose the export protocol: - -| Value | Transport | Notes | -|---|---|---| -| `grpc` (default) | gRPC | Default port 4317 | -| `http/protobuf` | HTTP | Default port 4318 | - -**Endpoint format:** `telemetry.otlp_endpoint` expects a base URL in `host:port` or `http://host:port` format, without a path component. The SDK appends the signal path (e.g. `/v1/traces`) automatically per the [OTLP specification](https://opentelemetry.io/docs/specs/otlp/#otlphttp-request). - +- Coding Agent Integrations — integrate OCR into Claude Code, Codex, Cursor, etc. + - [Skill](https://open-codereview.ai/docs/integrations/agent-skill) — install as a reusable agent skill + - [Plugin](https://open-codereview.ai/docs/integrations/claude-code) — install as a Claude Code / Codex / Cursor plugin + - [Delegation Mode](https://open-codereview.ai/docs/integrations/delegate) — let your agent review using its own LLM +- [CI/CD Integration](https://open-codereview.ai/docs/cicd) — GitHub Actions, GitLab CI, GitFlic CI, and Gerrit integration +- [Session Viewer](https://open-codereview.ai/docs/viewer) — browse and replay review sessions in browser +- [Telemetry](https://open-codereview.ai/docs/telemetry) — OpenTelemetry integration for observability +- [FAQ](https://open-codereview.ai/docs/faq) — common questions and troubleshooting ## Contributing diff --git a/README.ru-RU.md b/README.ru-RU.md index dc78748b..3e293f0e 100644 --- a/README.ru-RU.md +++ b/README.ru-RU.md @@ -99,116 +99,19 @@ Open Code Review — это CLI-инструмент для код-ревью н #### Установка -**Через NPM (рекомендуется)** - ```bash npm install -g @alibaba-group/open-code-review ``` После установки команда `ocr` доступна глобально. -**Обновление** - -Если установка выполнена через NPM, обновите вручную до последней версии: - -```bash -npm install -g @alibaba-group/open-code-review@latest -``` - -Установка через NPM также по умолчанию проверяет новые версии в фоне и обновляется автоматически. Чтобы отключить автообновления, задайте `OCR_NO_UPDATE=1`. - -Если вы устанавливали через install script или вручную скачанный бинарный файл, повторно запустите ту же команду установки/скачивания, чтобы заменить локальный бинарный файл последним релизом. Используйте `OCR_VERSION`, если нужно зафиксировать конкретный тег релиза. - -**Из GitHub Release** - -Установите свежий бинарный файл для вашей ОС/архитектуры одной командой (macOS / Linux): - -```bash -curl -fsSL https://raw.githubusercontent.com/alibaba/open-code-review/main/install.sh | sh -``` - -Скрипт сам выбирает подходящий бинарный файл релиза, проверяет его контрольную сумму SHA-256 и устанавливает его как `ocr` в `/usr/local/bin`. Каталог установки можно переопределить через `OCR_INSTALL_DIR`, а версию релиза зафиксировать через `OCR_VERSION`: - -```bash -OCR_INSTALL_DIR="$HOME/.local/bin" OCR_VERSION=v1.3.13 \ - sh -c "$(curl -fsSL https://raw.githubusercontent.com/alibaba/open-code-review/main/install.sh)" -``` - -В Windows (PowerShell 5.1+): - -```powershell -irm https://raw.githubusercontent.com/alibaba/open-code-review/main/install.ps1 | iex -``` - -Скрипт сам выбирает подходящий Windows-бинарный файл релиза, проверяет его контрольную сумму SHA-256 и устанавливает его как `ocr.exe` в `%LOCALAPPDATA%\Programs\ocr`. Каталог установки можно переопределить через `OCR_INSTALL_DIR`, а версию релиза зафиксировать через `OCR_VERSION`: - -```powershell -$env:OCR_INSTALL_DIR = "$env:USERPROFILE\bin" -$env:OCR_VERSION = "v1.3.13" -irm https://raw.githubusercontent.com/alibaba/open-code-review/main/install.ps1 | iex -``` - -Передача удалённого скрипта напрямую в shell выполняет код из интернета. Лучше сначала скачать и просмотреть скрипт: - -```bash -curl -fsSL https://raw.githubusercontent.com/alibaba/open-code-review/main/install.sh -o install.sh -less install.sh && sh install.sh -``` - -```powershell -irm https://raw.githubusercontent.com/alibaba/open-code-review/main/install.ps1 -OutFile install.ps1 -notepad install.ps1 # просмотрите, затем: .\install.ps1 -``` - -
-Ручная загрузка (все платформы, включая Windows) - -Скачайте бинарный файл для вашей платформы со страницы [GitHub Releases](https://github.com/alibaba/open-code-review/releases): - -```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 (x86_64) — переместите ocr.exe в каталог из вашего PATH -curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-amd64.exe - -# Windows (ARM64) — переместите ocr.exe в каталог из вашего PATH -curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-arm64.exe -``` - -
- -**Из исходников** - -```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 -``` +Другие способы установки (скрипт установки, бинарный файл из GitHub Release, сборка из исходников) описаны в [руководстве по установке](https://open-codereview.ai/docs/installation). #### Быстрый старт **1. Настройте LLM** -**Перед запуском ревью необходимо настроить LLM.** - -OCR управляет конфигурацией LLM через единую систему **провайдеров (Provider)**. Множество популярных провайдеров встроено, также поддерживается добавление пользовательских провайдеров для подключения к приватным развёртываниям или другим совместимым эндпоинтам. Конфигурация хранится в `~/.opencodereview/config.json`. - -**Вариант A: интерактивная настройка (рекомендуется)** +Перед запуском ревью необходимо настроить LLM, если только вы не используете [режим делегирования](https://open-codereview.ai/docs/integrations/delegate). ```bash ocr config provider # Выбрать встроенного провайдера или добавить пользовательский @@ -219,91 +122,9 @@ ocr config model # Выбрать модель для активно Интерактивный UI проведёт вас через выбор провайдера, ввод API-ключа и настройку модели, после чего автоматически проверит подключение. -Выполните `ocr llm providers`, чтобы увидеть все встроенные провайдеры. У встроенных провайдеров предустановлены URL API и протокол — достаточно указать API-ключ. Если соответствующая переменная окружения уже задана (например, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`), API-ключ будет подхвачен автоматически. - -**Пользовательские провайдеры** также добавляются через интерактивный UI — потребуется указать имя, URL API, тип протокола (`anthropic` или `openai`) и API-ключ. - -**Вариант B: настройка через CLI (для CI/CD и неинтерактивных сред)** - -Используйте `ocr config set` для записи конфигурации провайдера напрямую — подходит для скриптов и автоматизации. - -Использование встроенного провайдера: - -```bash -ocr config set provider anthropic -ocr config set providers.anthropic.api_key your-api-key-here -ocr config set providers.anthropic.model claude-sonnet-4-6 -``` - -Использование пользовательского провайдера (приватный шлюз или другой совместимый эндпоинт): - -```bash -ocr config set provider my-gateway -ocr config set custom_providers.my-gateway.url https://my-llm-gateway.internal/v1 -ocr config set custom_providers.my-gateway.protocol openai -ocr config set custom_providers.my-gateway.api_key your-api-key-here -ocr config set custom_providers.my-gateway.model gpt-4o -``` - -> Для пользовательских провайдеров `url` и `protocol` обязательны. Поддерживаемые протоколы: `anthropic`, `openai`, `openai-responses`. - -Дополнительные настройки: - -| Ключ | Описание | -|------|----------| -| `providers..auth_header` | Заголовок аутентификации: `x-api-key` или `authorization` (по умолчанию: `authorization`) | -| `providers..extra_body` | Пользовательские JSON-поля, добавляемые в тело запроса | -| `providers..extra_headers` | Пары `key=value`, разделённые запятыми — пользовательские HTTP-заголовки для каждого запроса | -| `providers..models` | Список моделей для интерактивного выбора | - -**`extra_headers` (необязательно):** добавляет пользовательские HTTP-заголовки к каждому запросу к LLM API. Полезно для прокси, шлюзов или корпоративных эндпоинтов, требующих дополнительных заголовков (например, ID организации, ID трассировки). Формат — пары `key=value`, разделённые запятыми. Значения с запятыми заключается в двойные кавычки: - -```bash -ocr config set llm.extra_headers "X-Org-ID=org-123,X-Forwarded-For=\"1.2.3.4,5.6.7.8\"" -``` - -Дополнительные заголовки также можно задать для отдельного провайдера: - -```bash -ocr config set providers.anthropic.extra_headers "X-Org-ID=org-123" -``` - -**Переменные окружения (наивысший приоритет)** - -Переменные окружения переопределяют настройки из файла конфигурации — удобно в CI/CD, где запись в конфиг-файл затруднена: - -```bash -export OCR_LLM_URL=https://api.anthropic.com/v1/messages -export OCR_LLM_TOKEN=your-api-key-here -export OCR_LLM_MODEL=claude-opus-4-6 -export OCR_USE_ANTHROPIC=true -``` - -Чтобы использовать OpenAI Responses API (модели GPT-5.x / o-series), задайте `OCR_LLM_PROTOCOL` вместо `OCR_USE_ANTHROPIC`: - -```bash -export OCR_LLM_URL=https://api.openai.com/v1 -export OCR_LLM_TOKEN=your-openai-key -export OCR_LLM_MODEL=gpt-5.4 -export OCR_LLM_PROTOCOL=openai-responses -``` - -`OCR_LLM_PROTOCOL` принимает значения `anthropic`, `openai`, `openai-responses` и имеет приоритет над `OCR_USE_ANTHROPIC`, если заданы обе переменные. - -Также совместим с переменными окружения Claude Code (`ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_MODEL`) и разбирает `~/.zshrc` / `~/.bashrc` в поисках соответствующих export'ов. - -> **Примечание для пользователей CC-Switch**: если вы используете [CC-Switch](https://github.com/farion1231/cc-switch) с включённым [routing service](https://www.ccswitch.io/en/docs?section=proxy&item=service), можно указать в `url` провайдера адрес прокси CC-Switch без дополнительной настройки: -> - Для провайдера **Claude**: установите `providers.anthropic.url` в `http://127.0.0.1:15721` -> - Для провайдера **Codex**: установите `url` соответствующего провайдера в `http://127.0.0.1:15721/v1` -> - `api_key` может быть любым, настройки `extra_body` продолжают действовать - -**2. Проверьте подключение** - -```bash -ocr llm test -``` +Настройка через CLI, переменные окружения, пользовательские провайдеры и другие расширенные параметры описаны в [руководстве по конфигурации](https://open-codereview.ai/docs/configuration). -**3. Запустите ревью** +**2. Запустите ревью** ```bash cd your-project @@ -331,191 +152,6 @@ ocr delegate preview ocr delegate rule src/main.go src/handler.go ``` -### Интеграция с кодинг-агентами - -OCR легко встраивается в ИИ-агентов для разработки в виде slash-команды, позволяя выполнять код-ревью прямо в рабочем процессе агента. - -#### Вариант 1: установка как Skill - -Установите скилл OCR в свой проект через `npx`: - -```bash -npx skills add alibaba/open-code-review --skill open-code-review -``` - -Это установит скилл `open-code-review` из [реестра скиллов](skills/open-code-review/SKILL.md), который объясняет вашему кодинг-агенту, как вызывать `ocr` для код-ревью, классифицировать найденные проблемы по приоритету и при необходимости применять исправления. - -**Режим делегирования** — если вы хотите, чтобы AI-агент сам выполнял ревью (OCR отвечает только за выбор файлов и разрешение правил, настройка LLM на стороне OCR не требуется): - -```bash -npx skills add alibaba/open-code-review --skill open-code-review-delegate -``` - -Подробнее см. [skills/open-code-review-delegate/SKILL.md](skills/open-code-review-delegate/SKILL.md). - -#### Вариант 2: установка как плагин Claude Code - -Для [Claude Code](https://docs.anthropic.com/en/docs/claude-code) установите плагин с командой, выполнив в Claude Code: - -```bash -/plugin marketplace add alibaba/open-code-review -/plugin install open-code-review@open-code-review -``` - -Это зарегистрирует slash-команду `/open-code-review:review`, которая запускает OCR и автоматически фильтрует и исправляет найденные проблемы. Также предоставляется команда `/open-code-review:delegate-review` для режима делегирования (агент выполняет ревью своими силами, OCR отвечает за выбор файлов и разрешение правил). - -#### Вариант 3: установка как плагин Codex - -Для локального Codex установите плагин Open Code Review из этого репозитория: - -```bash -codex plugin marketplace add alibaba/open-code-review -codex -/plugins -``` - -Для локального чекаута или форка: - -```bash -codex plugin marketplace add . -codex -/plugins -``` - -Установите и включите `Open Code Review`, затем начните новый тред Codex и вызывайте плагин явно: - -```text -@Open Code Review review my current changes -@Open Code Review review this branch against main -@Open Code Review review and fix high-confidence issues -``` - -Это зарегистрирует Codex-скилл, запускающий локальный CLI OCR: - -```bash -ocr review --audience agent -``` - -Эта интеграция не меняет внутренний LLM-бэкенд OCR и не требует настройки эндпоинта OpenAI Responses API для Codex. Самому OCR по-прежнему нужен установленный и настроенный CLI `ocr`, как описано в разделе про настройку CLI. - -Руководство на корейском: [`plugins/open-code-review/CODEX.ko-KR.md`](plugins/open-code-review/CODEX.ko-KR.md) - -#### Вариант 4: установка как плагин Cursor - -Для [Cursor](https://www.cursor.com/) установите плагин Open Code Review из этого репозитория: - -``` -cursor-plugin marketplace add alibaba/open-code-review -``` - -Или добавьте маркетплейс вручную. В Cursor откройте `/plugins`, найдите `Open Code Review` и установите. - -Для локального чекаута или форка: - -``` -cursor-plugin marketplace add . -``` - -После установки вызывайте плагин в Cursor: - -```text -@Open Code Review review my current changes -@Open Code Review review this branch against main -@Open Code Review review and fix high-confidence issues -``` - -Это зарегистрирует Cursor-скилл, запускающий локальный CLI OCR: - -```bash -ocr review --audience agent -``` - -Эта интеграция не меняет внутренний LLM-бэкенд OCR. Самому OCR по-прежнему нужен установленный и настроенный CLI `ocr`, как описано в разделе про настройку CLI. - -#### Вариант 5: просто скопировать файл команды - -Для быстрой настройки без пакетных менеджеров достаточно скопировать файл команды, чтобы использовать slash-команду `/open-code-review` в Claude Code. - -**На уровне проекта** (общий для команды через git): - -```bash -mkdir -p .claude/commands -curl -o .claude/commands/open-code-review.md \ - https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/claude-code/commands/review.md -``` - -**На уровне пользователя** (личное глобальное использование во всех проектах): - -```bash -mkdir -p ~/.claude/commands -curl -o ~/.claude/commands/open-code-review.md \ - https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/claude-code/commands/review.md -``` - -Режим делегирования (настройка LLM на стороне OCR не требуется): - -```bash -# Уровень проекта -mkdir -p .claude/commands -curl -o .claude/commands/open-code-review-delegate.md \ - https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/claude-code/commands/delegate-review.md - -# Уровень пользователя -mkdir -p ~/.claude/commands -curl -o ~/.claude/commands/open-code-review-delegate.md \ - https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/claude-code/commands/delegate-review.md -``` - -> **Требования**: Все способы интеграции требуют установки CLI `ocr`. Стандартный режим дополнительно требует настройки LLM — см. [Установка](#установка) и [Настройка LLM](#1-настройка-llm) выше. Режим делегирования **не требует** настройки LLM на стороне OCR. - -### Интеграция с CI/CD - -OCR можно встроить в CI/CD-пайплайны для автоматического код-ревью Merge Request'ов / Pull Request'ов. - -Базовая команда для интеграции с CI: - -```bash -ocr review \ - --from "origin/main" \ - --to "" \ - --format json -``` - -Флаг `--from` принимает в качестве базы ref ветки (например, `origin/main`) или SHA коммита, а `--to` — SHA коммита или ref ветки в качестве head. В CI-окружениях для `--to` рекомендуется использовать SHA коммита: это корректно обрабатывает PR/MR из форков, у которых исходная ветка отсутствует в remote `origin`. - -Флаг `--format json` выводит машиночитаемый результат, удобный для разбора в CI-скриптах. - -Каждое замечание содержит два структурированных поля, чтобы CI-интеграции могли сортировать, группировать, фильтровать замечания или блокировать сборку без повторного разбора текста комментария: - -| Поле | Допустимые значения | Примечание | -|------|---------------------|------------| -| `category` | `bug`, `security`, `performance`, `maintainability`, `test`, `style`, `documentation`, `other` | Категория, к которой относится замечание. | -| `severity` | `critical`, `high`, `medium`, `low` | Важность замечания. | - -В JSON-выводе эти два поля располагаются рядом с `content`, `start_line` и др. В терминале они отображаются перед комментарием как встроенный бейдж `[category · severity]`, цвет которого определяется важностью. - -Примеры интеграции — в каталоге [`examples/`](./examples/): - -- [`github_actions/`](./examples/github_actions/) — пример интеграции с GitHub Actions -- [`gitlab_ci/`](./examples/gitlab_ci/) — пример интеграции с GitLab CI -- [`gitflic_ci/`](./examples/gitflic_ci/) — пример интеграции с GitFlic CI -- [`gerrit_ci/`](./examples/gerrit_ci/) — пример интеграции с Gerrit (Jenkins / Gerrit Trigger) - -#### GitHub Action - -Для GitHub в корне репозитория также поставляется готовая к использованию composite Action ([`action.yml`](./action.yml)). Вместо того чтобы вручную скриптовать `ocr review`, просто подключите её — она берёт на себя весь конвейер: checkout, установку OCR, запуск ревью, публикацию инлайн- и сводных комментариев, загрузку артефактов, а также повтор и идемпотентность: - -```yaml -- uses: alibaba/open-code-review@main - with: - llm_url: ${{ secrets.OCR_LLM_URL }} - llm_auth_token: ${{ secrets.OCR_LLM_AUTH_TOKEN }} - llm_model: ${{ vars.OCR_LLM_MODEL }} - llm_use_anthropic: ${{ vars.OCR_LLM_USE_ANTHROPIC }} -``` - -Для воспроизводимости зафиксируйте тег версии или SHA коммита. Полный демо-воркфлоу, а также полный список входов, выходов и режимов публикации комментариев (закреплённая сводка, инкрементальная неразрушающая публикация) см. в каталоге [`examples/github_actions/`](./examples/github_actions/). - ## Документация Полная документация доступна на **[open-codereview.ai/docs](https://open-codereview.ai/docs)**: @@ -523,131 +159,17 @@ ocr review \ - [Быстрый старт](https://open-codereview.ai/docs/quickstart) — установка и запуск первого ревью - [Установка](https://open-codereview.ai/docs/installation) — все платформы и менеджеры пакетов - [Справочник CLI](https://open-codereview.ai/docs/cli-reference) — все команды и флаги -- [Правила ревью](https://open-codereview.ai/docs/review-rules) — цепочка приоритетов правил, формат файла и фильтрация путей +- [Правила ревью](https://open-codereview.ai/docs/review-rules) — кастомизация правил ревью, фильтрация и таргетинг по путям - [Конфигурация](https://open-codereview.ai/docs/configuration) — ключи конфигурации и переменные окружения - [MCP-сервер](https://open-codereview.ai/docs/mcp) — расширение агента ревью внешними инструментами -- [Интеграция с кодинг-агентами](https://open-codereview.ai/docs/claude-code) — Claude Code, Agent Skill и режим делегирования -- [Интеграция с CI/CD](https://open-codereview.ai/docs/cicd) — запуск ревью в пайплайне -- [Архитектура](https://open-codereview.ai/docs/architecture) · [Инструменты](https://open-codereview.ai/docs/tools) · [Просмотр сессий](https://open-codereview.ai/docs/viewer) · [Телеметрия](https://open-codereview.ai/docs/telemetry) · [FAQ](https://open-codereview.ai/docs/faq) - -## Команды - -OCR предоставляет команды `review`, `scan`, `delegate`, `config`, `llm`, `session`, `viewer` и другие. Полный список команд и все флаги — включая возобновляемые ревью и полные опции `ocr scan` / `ocr delegate` — см. в **[Справочнике CLI](https://open-codereview.ai/docs/cli-reference)**. - -## Примеры - -```bash -# Интерактивная настройка провайдера и модели -ocr config provider -ocr config model -ocr llm providers - -# Удалить пользовательского провайдера -ocr config unset custom_providers.my-gateway - -# Показать, какие файлы попадут в ревью (без вызовов LLM) -ocr review --preview -ocr review -c abc123 -p - -# Ревью изменений рабочей копии с настройками по умолчанию -ocr review - -# Ревью диффа веток с заданной конкурентностью -ocr review --from main --to my-feature --concurrency 4 - -# Ревью конкретного коммита с подробным JSON-выводом -ocr review --commit abc123 --format json --audience agent - -# Возобновить прерванное ревью диапазона или одного коммита -ocr session list -ocr session show -ocr review --from main --to my-feature --resume -ocr review --commit abc123 --resume - -# Выбрать или переопределить модель для этого ревью -ocr review --model claude-opus-4-6 -ocr review --commit abc123 --model claude-sonnet-4-6 - -# Передать контекст требований для более прицельного ревью -ocr review --background "Добавляем rate limiting в API логина" - -# Передать контекст требований из Markdown-файла -ocr review --background-file ./docs/my_business_context.md - -# Совместить встроенный контекст с локальным файлом контекста (используются оба) -ocr review --background "Фокус на аутентификации" --background-file ./docs/my_business_context.md - -# Использовать собственные правила ревью -ocr review --rule /path/to/my-rules.json - -# Посмотреть, какое правило применяется к файлу -ocr rules check src/main/java/com/example/Foo.java -ocr rules check --rule custom.json src/main/resources/mapper/UserMapper.xml - -# Полнофайловое сканирование: сначала просмотреть список файлов (без вызовов LLM) -ocr scan --preview - -# Сканировать весь репозиторий, ограничив расход ~500k токенов -ocr scan --max-tokens-budget 500000 - -# Сканировать подкаталог, пропустив сгенерированные/тестовые файлы -ocr scan --path internal --exclude '**/*_test.go,**/generated/**' - -# Сканировать каталог без git с JSON-выводом (включает project_summary) -ocr scan --repo /path/to/plain/dir --format json - -# Самое быстрое сканирование: пропустить планирование, дедупликацию и сводку проекта -ocr scan --no-plan --no-dedup --no-summary - -# Режим делегирования — AI-агент выполняет ревью (настройка LLM не требуется) -ocr delegate preview -ocr delegate preview --from main --to feature-branch -ocr delegate preview --commit abc123 -ocr delegate rule internal/handler.go internal/service.go cmd/main.go - -# Открыть историю сессий ревью в браузере -ocr viewer -ocr viewer --addr :3000 -``` - -### Безопасность viewer'а - -Viewer отдаёт содержимое сессионных JSONL-файлов (сообщения запросов к LLM и ответы) по HTTP. На каждый запрос применяется allowlist по заголовку Host: loopback-имена (`localhost`, `127.0.0.0/8`, `::1`) и конкретный хост привязки разрешены всегда. Wildcard-привязки (`--addr :3000`, `--addr 0.0.0.0:3000`) и прочие не-loopback имена хостов нужно добавлять через переменную окружения `OCR_VIEWER_ALLOWED_HOSTS` (через запятую): - -```bash -OCR_VIEWER_ALLOWED_HOSTS=review.internal,ocr.lan ocr viewer --addr :3000 -``` - -Это блокирует атаки DNS rebinding на локальный viewer. - -## Правила ревью - -OCR разрешает правила ревью через четырёхуровневую цепочку приоритетов (флаг `--rule` > конфигурация проекта > глобальная конфигурация > встроенные значения по умолчанию) и поддерживает встроенные или файловые правила, сопоставление по `**`-шаблонам и фильтрацию путей через `include` / `exclude`. Полный формат файла правил и семантику фильтрации см. в разделе **[Правила ревью](https://open-codereview.ai/docs/review-rules)**. - -## Справочник по конфигурации - -Конфигурация хранится в `~/.opencodereview/config.json` и может быть переопределена переменными окружения. Она охватывает провайдеров, модели, MCP-серверы, язык и телеметрию. Полный справочник ключей, переменные окружения и настройку MCP-сервера см. в разделах **[Конфигурация](https://open-codereview.ai/docs/configuration)** и **[MCP-сервер](https://open-codereview.ai/docs/mcp)**. - -## Телеметрия - -Интеграция с OpenTelemetry для наблюдаемости (спаны, метрики). По умолчанию выключена. - -```bash -ocr config set telemetry.enabled true -ocr config set telemetry.exporter otlp -ocr config set telemetry.otlp_endpoint localhost:4317 -``` - -Установите `telemetry.content_logging`, чтобы включать промпты и ответы LLM в экспортируемые данные. - -**Выбор протокола:** Переменная окружения `OTEL_EXPORTER_OTLP_PROTOCOL` определяет протокол экспорта: - -| Значение | Транспорт | Описание | -|---|---|---| -| `grpc` (по умолчанию) | gRPC | Порт по умолчанию 4317 | -| `http/protobuf` | HTTP | Порт по умолчанию 4318 | - -**Формат endpoint:** `telemetry.otlp_endpoint` принимает базовый URL в формате `host:port` или `http://host:port` без компонента пути. SDK автоматически добавляет путь сигнала (например, `/v1/traces`) в соответствии со [спецификацией OTLP](https://opentelemetry.io/docs/specs/otlp/#otlphttp-request). +- Интеграция с кодинг-агентами — встраивание OCR в Claude Code, Codex, Cursor и др. + - [Skill](https://open-codereview.ai/docs/integrations/agent-skill) — установка как переиспользуемый навык агента + - [Plugin](https://open-codereview.ai/docs/integrations/claude-code) — установка как плагин Claude Code / Codex / Cursor + - [Режим делегирования](https://open-codereview.ai/docs/integrations/delegate) — агент ревьюит своей собственной LLM +- [Интеграция с CI/CD](https://open-codereview.ai/docs/cicd) — GitHub Actions, GitLab CI, GitFlic CI и Gerrit +- [Просмотр сессий](https://open-codereview.ai/docs/viewer) — просмотр и воспроизведение сессий ревью в браузере +- [Телеметрия](https://open-codereview.ai/docs/telemetry) — интеграция с OpenTelemetry для наблюдаемости +- [FAQ](https://open-codereview.ai/docs/faq) — частые вопросы и устранение неполадок ## Участие в разработке diff --git a/README.zh-CN.md b/README.zh-CN.md index 33dd9380..b70d2faf 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -99,116 +99,19 @@ Open Code Review 的核心设计理念是将确定性工程与 Agent 结合， #### 安装 -**通过 NPM 安装（推荐）** - ```bash npm install -g @alibaba-group/open-code-review ``` 安装后，`ocr` 命令即可全局使用。 -**更新** - -如果通过 NPM 安装，可手动更新到最新版本： - -```bash -npm install -g @alibaba-group/open-code-review@latest -``` - -通过 NPM 安装的 `ocr` 还会默认在后台检查新版本并自动升级；如需关闭自动更新，可设置 `OCR_NO_UPDATE=1`。 - -如果通过安装脚本或手动下载二进制文件安装，重新运行对应的安装/下载命令即可替换为最新 release。需要固定版本时，可继续通过 `OCR_VERSION` 指定 release tag。 - -**从 GitHub Release 下载** - -使用一条命令为你的操作系统/架构安装最新二进制文件（macOS / Linux）： - -```bash -curl -fsSL https://raw.githubusercontent.com/alibaba/open-code-review/main/install.sh | sh -``` - -该脚本会自动选择匹配的发布二进制文件，校验其 SHA-256 校验和，并将其作为 `ocr` 安装到 `/usr/local/bin`。可通过 `OCR_INSTALL_DIR` 覆盖安装目录，或通过 `OCR_VERSION` 指定发布版本： - -```bash -OCR_INSTALL_DIR="$HOME/.local/bin" OCR_VERSION=v1.3.13 \ - sh -c "$(curl -fsSL https://raw.githubusercontent.com/alibaba/open-code-review/main/install.sh)" -``` - -在 Windows 上（PowerShell 5.1+）： - -```powershell -irm https://raw.githubusercontent.com/alibaba/open-code-review/main/install.ps1 | iex -``` - -该脚本会自动选择匹配的 Windows 发布二进制文件，校验其 SHA-256 校验和，并将其作为 `ocr.exe` 安装到 `%LOCALAPPDATA%\Programs\ocr`。可通过 `OCR_INSTALL_DIR` 覆盖安装目录，或通过 `OCR_VERSION` 指定发布版本： - -```powershell -$env:OCR_INSTALL_DIR = "$env:USERPROFILE\bin" -$env:OCR_VERSION = "v1.3.13" -irm https://raw.githubusercontent.com/alibaba/open-code-review/main/install.ps1 | iex -``` - -将远程脚本直接管道到 shell 会执行来自互联网的代码。建议先下载并检查后再运行： - -```bash -curl -fsSL https://raw.githubusercontent.com/alibaba/open-code-review/main/install.sh -o install.sh -less install.sh && sh install.sh -``` - -```powershell -irm https://raw.githubusercontent.com/alibaba/open-code-review/main/install.ps1 -OutFile install.ps1 -notepad install.ps1 # 检查后执行: .\install.ps1 -``` - -
-手动下载（所有平台，包括 Windows） - -从 [GitHub Releases](https://github.com/alibaba/open-code-review/releases) 下载适用于你平台的二进制文件： - -```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 (x86_64) — 将 ocr.exe 移动到 PATH 目录中 -curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-amd64.exe - -# Windows (ARM64) — 将 ocr.exe 移动到 PATH 目录中 -curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-arm64.exe -``` - -
- -**从源码构建** - -```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 -``` +其他安装方式（安装脚本、GitHub Release 二进制、源码构建），详见[安装指南](https://open-codereview.ai/docs/installation)。 #### 快速开始 **1. 配置 LLM** -**在审查代码之前，必须先配置 LLM。** - -OCR 通过**供应商（Provider）**模式统一管理 LLM 配置，内置了多种主流供应商，也支持添加自定义供应商以对接私有部署或其他兼容端点。配置存储于 `~/.opencodereview/config.json`。 - -**方式 A：交互式设置（推荐）** +在审查代码之前，必须先配置 LLM。除非你使用[委托模式](https://open-codereview.ai/docs/integrations/delegate)。 ```bash ocr config provider # 选择内置供应商或添加自定义供应商 @@ -219,91 +122,9 @@ ocr config model # 为当前供应商选择模型 交互式界面会引导你完成供应商选择、API Key 输入和模型配置，完成后自动测试连通性。 -运行 `ocr llm providers` 可查看所有内置供应商。内置供应商预设了 API 地址和协议，只需提供 API Key 即可使用。如果对应的环境变量已设置（如 `ANTHROPIC_API_KEY`、`OPENAI_API_KEY`），API Key 会自动读取，无需手动输入。 - -添加**自定义供应商**同样通过交互式界面完成 —— 需提供供应商名称、API 地址、协议类型（`anthropic` 或 `openai`）和 API Key。 - -**方式 B：命令行设置（适用于 CI/CD 等无交互环境）** - -通过 `ocr config set` 命令直接写入供应商配置，适用于脚本和自动化场景。 - -使用内置供应商： - -```bash -ocr config set provider anthropic -ocr config set providers.anthropic.api_key your-api-key-here -ocr config set providers.anthropic.model claude-sonnet-4-6 -``` - -使用自定义供应商（对接私有网关或其他兼容端点）： +命令行设置、环境变量、自定义供应商等高级配置，详见[配置指南](https://open-codereview.ai/docs/configuration)。 -```bash -ocr config set provider my-gateway -ocr config set custom_providers.my-gateway.url https://my-llm-gateway.internal/v1 -ocr config set custom_providers.my-gateway.protocol openai -ocr config set custom_providers.my-gateway.api_key your-api-key-here -ocr config set custom_providers.my-gateway.model gpt-4o -``` - -> 自定义供应商的 `url` 和 `protocol` 为必填项。`protocol` 支持 `anthropic`、`openai`、`openai-responses`。 - -可选配置项： - -| 键 | 描述 | -|----|------| -| `providers..auth_header` | 认证头：`x-api-key` 或 `authorization`（默认 `authorization`） | -| `providers..extra_body` | 合并到请求体的自定义 JSON 字段 | -| `providers..extra_headers` | 逗号分隔的 `key=value` 键值对，为每个请求添加自定义 HTTP 头 | -| `providers..models` | 用于交互式选择的模型列表 | - -**`extra_headers`（可选）：** 为每个 LLM API 请求添加自定义 HTTP 头。适用于代理、网关或需要额外头的企业端点（例如组织 ID、链路追踪 ID）。格式为逗号分隔的 `key=value` 键值对。包含逗号的值请用双引号包裹： - -```bash -ocr config set llm.extra_headers "X-Org-ID=org-123,X-Forwarded-For=\"1.2.3.4,5.6.7.8\"" -``` - -也可以按供应商单独设置额外头： - -```bash -ocr config set providers.anthropic.extra_headers "X-Org-ID=org-123" -``` - -**环境变量（优先级最高）** - -环境变量会覆盖配置文件中的设置，适用于 CI/CD 场景中不便写入配置文件的情况： - -```bash -export OCR_LLM_URL=https://api.anthropic.com/v1/messages -export OCR_LLM_TOKEN=your-api-key-here -export OCR_LLM_MODEL=claude-opus-4-6 -export OCR_USE_ANTHROPIC=true -``` - -若要走 OpenAI Responses API（GPT-5.x / o-系列模型），请改用 `OCR_LLM_PROTOCOL`： - -```bash -export OCR_LLM_URL=https://api.openai.com/v1 -export OCR_LLM_TOKEN=your-openai-key -export OCR_LLM_MODEL=gpt-5.4 -export OCR_LLM_PROTOCOL=openai-responses -``` - -`OCR_LLM_PROTOCOL` 接受 `anthropic`、`openai`、`openai-responses`，与 `OCR_USE_ANTHROPIC` 同时设置时优先使用前者。 - -同时兼容 Claude Code 环境变量（`ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_MODEL`），并解析 `~/.zshrc` / `~/.bashrc` 中的相关导出。 - -> **CC-Switch 用户特别提醒**：如果你使用 [CC-Switch](https://github.com/farion1231/cc-switch) 并开启了[路由服务](https://www.ccswitch.io/zh/docs?section=proxy&item=service)，可以将供应商的 `url` 配置成 CC-Switch 启动的代理地址，无需额外配置： -> - 路由 **Claude** 供应商：`providers.anthropic.url` 设为 `http://127.0.0.1:15721` -> - 路由 **Codex** 供应商：对应供应商的 `url` 设为 `http://127.0.0.1:15721/v1` -> - `api_key` 可设置为任意值，`extra_body` 设置依然生效 - -**2. 测试连通性** - -```bash -ocr llm test -``` - -**3. 开始审查** +**2. 开始审查** ```bash cd your-project @@ -331,189 +152,6 @@ ocr delegate preview ocr delegate rule src/main.go src/handler.go ``` -### 集成到编程 Agent - -OCR 可以无缝集成到 AI 编程 Agent 中，作为斜杠命令使用，在 Agent 工作流中直接进行代码审查。 - -#### 方式一：作为 Skill 安装 - -使用 `npx` 将 OCR skill 安装到项目中： - -```bash -npx skills add alibaba/open-code-review --skill open-code-review -``` - -此命令从 [skills 注册表](skills/open-code-review/SKILL.md)安装 `open-code-review` skill，教会你的编程 Agent 如何调用 `ocr` 进行代码审查、按优先级分类问题，并可选择性地应用修复。 - -**委托模式** — 如果你希望编程 agent 自身执行评审（OCR 仅负责文件选择和规则解析，OCR 侧无需配置 LLM）： - -```bash -npx skills add alibaba/open-code-review --skill open-code-review-delegate -``` - -详见 [skills/open-code-review-delegate/SKILL.md](skills/open-code-review-delegate/SKILL.md)。 - -#### 方式二：作为 Claude Code Plugin 安装 - -对于 [Claude Code](https://docs.anthropic.com/en/docs/claude-code)，在 Claude Code 中通过以下命令安装命令插件： - -```bash -/plugin marketplace add alibaba/open-code-review -/plugin install open-code-review@open-code-review -``` - -此命令注册 `/open-code-review:review` 斜杠命令，运行 OCR 并自动过滤和修复问题。同时提供 `/open-code-review:delegate-review` 委托模式命令（agent 使用自身能力进行评审，OCR 负责文件选择和规则解析）。 - -#### 方式三：作为 Codex Plugin 安装 - -对于本地 Codex，可以从此仓库安装 Open Code Review plugin： - -```bash -codex plugin marketplace add alibaba/open-code-review -codex -/plugins -``` - -对于本地 checkout 或 fork： - -```bash -codex plugin marketplace add . -codex -/plugins -``` - -安装并启用 `Open Code Review` 后，启动新的 Codex thread 并显式调用： - -```text -@Open Code Review review my current changes -@Open Code Review review this branch against main -@Open Code Review review and fix high-confidence issues -``` - -这会注册一个 Codex skill，用于运行本地 OCR CLI： - -```bash -ocr review --audience agent -``` - -此集成不会改变 OCR 的内部 LLM backend，也不需要为 Codex 配置 OpenAI Responses API endpoint。OCR 本身仍需要按照 CLI setup 部分安装并配置 `ocr` CLI。 - -韩文指南：[`plugins/open-code-review/CODEX.ko-KR.md`](plugins/open-code-review/CODEX.ko-KR.md) - -#### 方式四：作为 Cursor Plugin 安装 - -对于 [Cursor](https://www.cursor.com/)，可以从此仓库安装 Open Code Review plugin： - -``` -cursor-plugin marketplace add alibaba/open-code-review -``` - -也可以手动添加 marketplace。在 Cursor 中打开 `/plugins`，搜索 `Open Code Review` 并安装。 - -对于本地 checkout 或 fork： - -``` -cursor-plugin marketplace add . -``` - -安装后，在 Cursor 中调用： - -```text -@Open Code Review review my current changes -@Open Code Review review this branch against main -@Open Code Review review and fix high-confidence issues -``` - -这会注册一个 Cursor skill，用于运行本地 OCR CLI： - -```bash -ocr review --audience agent -``` - -此集成不会改变 OCR 的内部 LLM backend。OCR 本身仍需要按照 CLI setup 部分安装并配置 `ocr` CLI。 - -#### 方式五：直接复制命令文件 - -如果不想使用任何包管理器，可以直接复制命令文件，在 Claude Code 中使用 `/open-code-review` 斜杠命令。 - -**项目级**（通过 git 与团队共享）： - -```bash -mkdir -p .claude/commands -curl -o .claude/commands/open-code-review.md \ - https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/claude-code/commands/review.md -``` - -**用户级**（个人全局使用，适用于所有项目）： - -```bash -mkdir -p ~/.claude/commands -curl -o ~/.claude/commands/open-code-review.md \ - https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/claude-code/commands/review.md -``` - -委托模式（OCR 侧无需配置 LLM）： - -```bash -# 项目级 -mkdir -p .claude/commands -curl -o .claude/commands/open-code-review-delegate.md \ - https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/claude-code/commands/delegate-review.md - -# 用户级 -mkdir -p ~/.claude/commands -curl -o ~/.claude/commands/open-code-review-delegate.md \ - https://raw.githubusercontent.com/alibaba/open-code-review/main/plugins/open-code-review/claude-code/commands/delegate-review.md -``` - -> **前提条件**：所有集成方式都需要安装 `ocr` CLI。标准模式还需要配置 LLM — 参见上文[安装](#安装)和[配置 LLM](#1-配置-llm)。委托模式 OCR 侧**不需要** LLM 配置。 - -### CI/CD 集成 - -OCR 可以集成到 CI/CD 流水线中，在 Merge Request / Pull Request 时自动进行代码审查。 - -CI 集成的核心命令： - -```bash -ocr review \ - --from "origin/main" \ - --to "origin/feature-branch" \ - --format json -``` - -`--format json` 参数输出适合 CI 脚本解析的机器可读结果。 - -每条评审结果都带有两个结构化字段，便于 CI 集成在无需解析评论文本的情况下排序、分组、过滤或卡点构建： - -| 字段 | 允许的取值 | 说明 | -|------|-----------|------| -| `category` | `bug`、`security`、`performance`、`maintainability`、`test`、`style`、`documentation`、`other` | 问题所属的类别。 | -| `severity` | `critical`、`high`、`medium`、`low` | 问题的严重程度。 | - -在 JSON 输出中，这两个字段与 `content`、`start_line` 等平级；在终端中，它们会以内联的 `[category · severity]` 徽章形式显示在评论前，并按严重程度着色。 - -集成示例请参见 [`examples/`](./examples/) 目录： - -- [`github_actions/`](./examples/github_actions/) — GitHub Actions 集成示例 -- [`gitlab_ci/`](./examples/gitlab_ci/) — GitLab CI 集成示例 -- [`gitflic_ci/`](./examples/gitflic_ci/) — GitFlic CI 集成示例 -- [`gerrit_ci/`](./examples/gerrit_ci/) — Gerrit (Jenkins / Gerrit Trigger) 集成示例 - -#### GitHub Action - -对于 GitHub，本仓库还在仓库根目录提供了一个开箱即用的 composite Action（[`action.yml`](./action.yml)）。你无需自己编写 `ocr review` 脚本，直接引用它即可完成完整流程——checkout、安装 OCR、执行审查、发布行内评论与汇总评论、上传 artifacts，以及重试与幂等处理： - -```yaml -- uses: alibaba/open-code-review@main - with: - llm_url: ${{ secrets.OCR_LLM_URL }} - llm_auth_token: ${{ secrets.OCR_LLM_AUTH_TOKEN }} - llm_model: ${{ vars.OCR_LLM_MODEL }} - llm_use_anthropic: ${{ vars.OCR_LLM_USE_ANTHROPIC }} -``` - -为保障可复现性，请固定到某个版本标签或 commit SHA。完整的 workflow 示例以及 inputs、outputs 与评论发布模式（置顶汇总、增量非破坏式发布）的完整列表，请参见 [`examples/github_actions/`](./examples/github_actions/) 目录。 - ## 文档 完整文档见 **[open-codereview.ai/docs](https://open-codereview.ai/docs)**： @@ -521,121 +159,17 @@ ocr review \ - [快速开始](https://open-codereview.ai/docs/quickstart) —— 安装并运行你的第一次评审 - [安装](https://open-codereview.ai/docs/installation) —— 覆盖各平台与包管理器 - [CLI 参考](https://open-codereview.ai/docs/cli-reference) —— 所有命令与参数 -- [评审规则](https://open-codereview.ai/docs/review-rules) —— 规则优先级链、文件格式与路径过滤 +- [评审规则](https://open-codereview.ai/docs/review-rules) —— 深度定制规则进行评审，过滤路径、指定路径等 - [配置](https://open-codereview.ai/docs/configuration) —— 配置项与环境变量 - [MCP 服务器](https://open-codereview.ai/docs/mcp) —— 用外部工具扩展评审 agent -- [编程 Agent 集成](https://open-codereview.ai/docs/claude-code) —— Claude Code、Agent Skill 与委托模式 -- [CI/CD 集成](https://open-codereview.ai/docs/cicd) —— 在流水线中运行评审 -- [架构](https://open-codereview.ai/docs/architecture) · [工具](https://open-codereview.ai/docs/tools) · [会话查看器](https://open-codereview.ai/docs/viewer) · [遥测](https://open-codereview.ai/docs/telemetry) · [FAQ](https://open-codereview.ai/docs/faq) - -## 命令 - -OCR 提供 `review`、`scan`、`delegate`、`config`、`llm`、`session`、`viewer` 等命令。完整的命令列表与所有参数（包括可恢复评审以及 `ocr scan` / `ocr delegate` 的全部选项），详见 **[CLI 参考](https://open-codereview.ai/docs/cli-reference)**。 - -## 示例 - -```bash -# 交互式供应商和模型设置 -ocr config provider -ocr config model -ocr llm providers - -# 删除自定义供应商 -ocr config unset custom_providers.my-gateway - -# 预览将被审查的文件（不调用 LLM） -ocr review --preview -ocr review -c abc123 -p - -# 使用默认设置审查工作区变更 -ocr review - -# 以更高并发审查分支差异 -ocr review --from main --to my-feature --concurrency 4 - -# 审查特定提交并以 JSON 格式输出详细信息 -ocr review --commit abc123 --format json --audience agent - -# 恢复中断的区间或单 commit 评审 -ocr session list -ocr session show -ocr review --from main --to my-feature --resume -ocr review --commit abc123 --resume - -# 为本次审查选择或覆盖模型 -ocr review --model claude-opus-4-6 -ocr review --commit abc123 --model claude-sonnet-4-6 - -# 提供需求背景以获得更有针对性的审查 -ocr review --background "为登录 API 添加限流" - -# 从 Markdown 文件提供需求背景 -ocr review --background-file ./docs/my_business_context.md - -# 将内联背景与本地背景文件结合使用（两者都会生效） -ocr review --background "关注鉴权" --background-file ./docs/my_business_context.md - -# 使用自定义审查规则 -ocr review --rule /path/to/my-rules.json - -# 预览某个文件路径生效的规则 -ocr rules check src/main/java/com/example/Foo.java -ocr rules check --rule custom.json src/main/resources/mapper/UserMapper.xml - -# 全量文件扫描：先预览文件列表（不调用 LLM） -ocr scan --preview - -# 扫描整个仓库，限制消耗约 500k token -ocr scan --max-tokens-budget 500000 - -# 扫描子目录，跳过生成的/测试文件 -ocr scan --path internal --exclude '**/*_test.go,**/generated/**' - -# 扫描非 git 目录，使用 JSON 输出（包含 project_summary） -ocr scan --repo /path/to/plain/dir --format json - -# 最快扫描：跳过规划、去重和项目总结 -ocr scan --no-plan --no-dedup --no-summary - -# 委托模式 — 让 AI agent 驱动评审（无需 LLM 配置） -ocr delegate preview -ocr delegate preview --from main --to feature-branch -ocr delegate preview --commit abc123 -ocr delegate rule internal/handler.go internal/service.go cmd/main.go - -# 在浏览器中查看审查会话历史 -ocr viewer -ocr viewer --addr :3000 -``` - -## 评审规则 - -OCR 通过四层优先级链解析评审规则（`--rule` 参数 > 项目配置 > 全局配置 > 内置默认），支持内联或文件形式的规则、`**` 通配匹配，以及 `include` / `exclude` 路径过滤。完整的规则文件格式与过滤语义，详见 **[评审规则](https://open-codereview.ai/docs/review-rules)**。 - -## 配置参考 - -配置位于 `~/.opencodereview/config.json`，可被环境变量覆盖，涵盖供应商、模型、MCP 服务器、语言与遥测。完整的配置项参考、环境变量与 MCP 服务器配置，详见 **[配置](https://open-codereview.ai/docs/configuration)** 与 **[MCP 服务器](https://open-codereview.ai/docs/mcp)**。 - -## 遥测 - -OpenTelemetry 集成，用于可观测性（spans、metrics）。默认关闭。 - -```bash -ocr config set telemetry.enabled true -ocr config set telemetry.exporter otlp -ocr config set telemetry.otlp_endpoint localhost:4317 -``` - -设置 `telemetry.content_logging` 可在导出数据中包含 LLM 提示词和响应。 - -**协议选择：** 通过环境变量 `OTEL_EXPORTER_OTLP_PROTOCOL` 选择导出协议： - -| 值 | 传输方式 | 说明 | -|---|---|---| -| `grpc`（默认） | gRPC | 默认端口 4317 | -| `http/protobuf` | HTTP | 默认端口 4318 | - -**Endpoint 格式：** `telemetry.otlp_endpoint` 的值为 `host:port` 或 `http://host:port`，无需包含路径。SDK 会根据 [OTLP 规范](https://opentelemetry.io/docs/specs/otlp/#otlphttp-request)自动追加信号路径（如 `/v1/traces`）。 +- 编程 Agent 集成 —— 将 OCR 集成到 Claude Code、Codex、Cursor 等 + - [Skill](https://open-codereview.ai/docs/integrations/agent-skill) —— 作为可复用的 Agent Skill 安装 + - [Plugin](https://open-codereview.ai/docs/integrations/claude-code) —— 作为 Claude Code / Codex / Cursor 插件安装 + - [委托模式](https://open-codereview.ai/docs/integrations/delegate) —— 让 Agent 使用自身的 LLM 进行评审 +- [CI/CD 集成](https://open-codereview.ai/docs/cicd) —— 支持 GitHub Actions、GitLab CI、GitFlic CI、Gerrit 集成 +- [会话查看器](https://open-codereview.ai/docs/viewer) —— 在浏览器中浏览和回放评审会话 +- [遥测](https://open-codereview.ai/docs/telemetry) —— OpenTelemetry 集成，用于可观测性 +- [FAQ](https://open-codereview.ai/docs/faq) —— 常见问题与故障排查 ## 贡献 From b00244926a3056a9620224fd64f5887c40da788f Mon Sep 17 00:00:00 2001 From: chethanuk Date: Tue, 21 Jul 2026 15:01:51 +0400 Subject: [PATCH 3/5] ci: cancel superseded CI runs on the same PR or branch (#425) Every push to a PR started a new CI run while the previous one kept running to completion on the self-hosted pool. Only the newest commit matters, so the earlier runs were holding runners for results nobody would read. Adds a top-level concurrency group keyed on the PR number, falling back to the ref for push-to-main. This follows the pattern OpenSandbox uses across its CI workflows, and is byte-identical to the block already running in ocr-review.yml, so it reuses the repo's existing idiom rather than introducing a second one. Left the other workflows alone deliberately. deploy-pages.yml already sets cancel-in-progress: false, and release.yml must never cancel: aborting mid npm-publish would leave the platform packages published while the meta package's optionalDependencies reference versions that were never pushed, and npm publish is not reversible. Verified with actionlint v1.7.12 (clean across all four workflows) and by exercising both paths live on a fork: a superseded pull_request run cancelled in 38s, and a superseded push-to-main run cancelled while a run from a commit without the block, on the same branch, stayed queued. Closes #422 --- .github/workflows/ci.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ac1420e7..74328b5e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -9,6 +9,10 @@ on: permissions: contents: read +concurrency: + group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + jobs: test: runs-on: self-hosted From c60e88650af19c0500527e2fe528e31059b4b5e1 Mon Sep 17 00:00:00 2001 From: Shaurya Srivastava <104617579+Shaurya2k06@users.noreply.github.com> Date: Tue, 21 Jul 2026 16:41:48 +0530 Subject: [PATCH 4/5] docs(pages): add CC-Switch proxy setup to Configuration (#429) Migrate the CC-Switch note removed from the README in #426 into the docs Configuration page (en, zh, ja). Signed-off-by: shaurya2k06 --- pages/src/content/docs/en/configuration.md | 18 ++++++++++++++++++ pages/src/content/docs/ja/configuration.md | 18 ++++++++++++++++++ pages/src/content/docs/zh/configuration.md | 16 ++++++++++++++++ 3 files changed, 52 insertions(+) diff --git a/pages/src/content/docs/en/configuration.md b/pages/src/content/docs/en/configuration.md index 256711ff..63b5d777 100644 --- a/pages/src/content/docs/en/configuration.md +++ b/pages/src/content/docs/en/configuration.md @@ -125,6 +125,24 @@ 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. +### Using CC-Switch + +If you use [CC-Switch](https://github.com/farion1231/cc-switch) with its +[routing service](https://www.ccswitch.io/en/docs?section=proxy&item=service) +enabled, point the provider `url` at the local proxy — no other setup is +required: + +```bash +# Claude (Anthropic-compatible) +ocr config set providers.anthropic.url http://127.0.0.1:15721 + +# Codex / OpenAI-compatible — set that provider's url key instead +ocr config set providers..url http://127.0.0.1:15721/v1 +``` + +`api_key` can be any value. `extra_body` (and other per-provider fields) +still apply as usual. + ### Send vendor-specific fields Some providers require non-standard request fields (such as Bedrock-style diff --git a/pages/src/content/docs/ja/configuration.md b/pages/src/content/docs/ja/configuration.md index f2729ed4..da268426 100644 --- a/pages/src/content/docs/ja/configuration.md +++ b/pages/src/content/docs/ja/configuration.md @@ -123,6 +123,24 @@ Claude Code の `ANTHROPIC_*` や OCR 独自の `OCR_LLM_*` 環境変数をす 設定している場合、OCR はそれらを自動的に認識するため、設定ファイルを書く 必要はありません。 +### CC-Switch を使う + +[CC-Switch](https://github.com/farion1231/cc-switch) を +[ルーティングサービス](https://www.ccswitch.io/en/docs?section=proxy&item=service) +有効で使用している場合、プロバイダーの `url` をローカルプロキシに向けるだけで、 +追加設定なしで利用できます： + +```bash +# Claude（Anthropic 互換） +ocr config set providers.anthropic.url http://127.0.0.1:15721 + +# Codex / OpenAI 互換 — そのプロバイダーの url キーを設定 +ocr config set providers..url http://127.0.0.1:15721/v1 +``` + +`api_key` は任意の値で構いません。`extra_body`（およびその他のプロバイダー固有フィールド）は +引き続き有効です。 + ### ベンダー固有のフィールドを送信する 一部の provider は非標準のリクエストフィールド（Bedrock 風の `thinking` など）を diff --git a/pages/src/content/docs/zh/configuration.md b/pages/src/content/docs/zh/configuration.md index 796ec0c9..abbe443c 100644 --- a/pages/src/content/docs/zh/configuration.md +++ b/pages/src/content/docs/zh/configuration.md @@ -115,6 +115,22 @@ ocr llm test 如果你已经配好了 Claude Code 的 `ANTHROPIC_*`，或 OCR 自己的 `OCR_LLM_*`环境变量，OCR 会自动识别，无需再写配置文件。 +### 使用 CC-Switch + +如果你使用 [CC-Switch](https://github.com/farion1231/cc-switch) 并开启了 +[路由服务](https://www.ccswitch.io/zh/docs?section=proxy&item=service)， +可以将供应商的 `url` 配置成 CC-Switch 启动的代理地址，无需额外配置： + +```bash +# Claude（Anthropic 兼容） +ocr config set providers.anthropic.url http://127.0.0.1:15721 + +# Codex / OpenAI 兼容 — 将该供应商的 url 键设为代理地址 +ocr config set providers..url http://127.0.0.1:15721/v1 +``` + +`api_key` 可设置为任意值。`extra_body`（及其他按供应商字段）依然生效。 + ### 发送厂商专属字段 某些 provider 需要非标准的请求字段（如 Bedrock 风格的 `thinking`）。用`extra_body`（合并进每次请求）即可发送，无需改源码： From d27867eedb9332bc6429b4240921ca623bf49d91 Mon Sep 17 00:00:00 2001 From: ChethanUK Date: Tue, 21 Jul 2026 13:51:11 +0200 Subject: [PATCH 5/5] test: injection demo (DO NOT MERGE) --- .github/workflows/zz-injection-demo.yml | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 .github/workflows/zz-injection-demo.yml diff --git a/.github/workflows/zz-injection-demo.yml b/.github/workflows/zz-injection-demo.yml new file mode 100644 index 00000000..a71e1739 --- /dev/null +++ b/.github/workflows/zz-injection-demo.yml @@ -0,0 +1,23 @@ +name: ZZ Injection Demo +on: + pull_request: + branches: [main] +permissions: + contents: read +jobs: + vulnerable: + runs-on: ubuntu-latest + timeout-minutes: 5 + steps: + - name: Interpolated directly into the shell (the pattern the docs teach) + run: | + echo "background=${{ github.event.pull_request.title }}" + safe: + runs-on: ubuntu-latest + timeout-minutes: 5 + steps: + - name: Passed via env (the pattern action.yml already uses) + env: + PR_TITLE: ${{ github.event.pull_request.title }} + run: | + echo "background=$PR_TITLE"