vrr/open-code-review
2
0
Fork 0
mirror of https://github.com/alibaba/open-code-review.git synced 2026-07-09 17:28:58 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

docs(pages): add Japanese (ja) translation for docs content (#282)
Some checks are pending
CI / test (push) Waiting to run
Details
Deploy Pages / build (push) Waiting to run
Details
Deploy Pages / deploy (push) Blocked by required conditions
Details

Browse source 
Translate all 17 docs pages from zh to ja under content/docs/ja/,
translate frontmatter titles, and wire ja into content/docs/index.ts
(replacing the previous English fallback). Sidebar i18n keys already
existed in i18n/ja.ts, so navigation renders Japanese automatically.
This commit is contained in:
kite 2026-07-03 14:23:35 +08:00 • committed by GitHub
parent 64398465d4
commit db254dd9c8
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
18 changed files with 3698 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

41
pages/src/content/docs/index.ts
View file

@ -38,6 +38,25 @@ import zhCicd from './zh/integrations/ci.md';
import zhContributing from './zh/contributing.md';
import zhFaq from './zh/faq.md';
// Japanese docs
import jaOverview from './ja/overview.md';
import jaQuickstart from './ja/quickstart.md';
import jaInstallation from './ja/installation.md';
import jaConfiguration from './ja/configuration.md';
import jaCliReference from './ja/cli-reference.md';
import jaReviewRules from './ja/review-rules.md';
import jaArchitecture from './ja/architecture.md';
import jaTools from './ja/tools.md';
import jaViewer from './ja/viewer.md';
import jaTelemetry from './ja/telemetry.md';
import jaIntegrations from './ja/integrations.md';
import jaAgentSkill from './ja/integrations/agent-skill.md';
import jaClaudeCode from './ja/integrations/claude-code.md';
import jaSubprocess from './ja/integrations/subprocess.md';
import jaCicd from './ja/integrations/ci.md';
import jaContributing from './ja/contributing.md';
import jaFaq from './ja/faq.md';
export type DocSlug =
| 'overview'
| 'quickstart'
@ -97,10 +116,30 @@ const zhDocs: Record<DocSlug, string> = {
'faq': zhFaq,
};
const jaDocs: Record<DocSlug, string> = {
'overview': jaOverview,
'quickstart': jaQuickstart,
'installation': jaInstallation,
'configuration': jaConfiguration,
'cli-reference': jaCliReference,
'review-rules': jaReviewRules,
'architecture': jaArchitecture,
'tools': jaTools,
'viewer': jaViewer,
'telemetry': jaTelemetry,
'integrations': jaIntegrations,
'agent-skill': jaAgentSkill,
'claude-code': jaClaudeCode,
'subprocess': jaSubprocess,
'cicd': jaCicd,
'contributing': jaContributing,
'faq': jaFaq,
};
const docsMap: Record<string, Record<DocSlug, string>> = {
en: enDocs,
zh: zhDocs,
ja: enDocs, // fallback to English for Japanese
ja: jaDocs,
};
/**

258
pages/src/content/docs/ja/architecture.md Normal file
View file

@ -0,0 +1,258 @@
---
title: アーキテクチャ
sidebar:
order: 8
---
あなたが Enter キーを押してから JSON がターミナルに出力されるまで、`ocr review` が内部で実際にどう動くかのガイドです。挙動をデバッグし、引数をチューニングし、自信を持ってソースコードを読めるだけの十分なメンタルモデルを構築することを目的としています。
## 高レベルのパイプライン
```mermaid
flowchart TD
A["<b>ocr review</b>"]
B["<b>bootstrap</b><br/><span style='font-size:0.85em'>Resolve LLM endpoint (config → env → rc files)<br/>Load template, tool registry, system rules</span>"]
C["<b>diff provider</b><br/><span style='font-size:0.85em'>git diff / ls-files / show — produce []model.Diff<br/>Modes: Workspace · Commit · Range</span>"]
D["<b>filter & rules</b><br/><span style='font-size:0.85em'>5-gate filter (preview.go) — drop binaries,<br/>excluded paths, unsupported extensions. Pick rule per file.</span>"]
E["<b>subtask dispatch</b><br/><span style='font-size:0.85em'>For every diff in parallel (concurrency=N):<br/>Plan phase (optional) → Main loop → Comments</span>"]
F["<b>output writer</b><br/><span style='font-size:0.85em'>Synchronous line-resolution & review-filter; renders text<br/>or JSON depending on --format / --audience.</span>"]
A --> B --> C --> D --> E --> F
```
オーケストレーションのロジックは [`internal/agent/`](https://github.com/alibaba/open-code-review/blob/main/internal/agent/) パッケージにあり、4 つのファイルに分かれています: `agent.go`（メインループとディスパッチ）、`compression.go`（メモリ圧縮）、`preview.go`（ファイルフィルタリング）、`util.go`（ヘルパー）。注目すべきエントリポイントは 2 つです: `Agent.Run`（パイプラインの最上部）と `Agent.dispatchSubtasks`（ファイルごとのファンアウト）。
## diff provider
`internal/diff/git.go` は `Provider` 構造体を定義しており、その未エクスポートのフィールド `mode`（型は `Mode`、`int` 列挙体）が、CLI 引数に対応する 3 つのモードのいずれかを選択します:
| モード | トリガー方法 | 返す内容 |
|---|---|---|
| `Workspace` | 引数なし | staged + unstaged + untracked の変更 |
| `Commit` | `--commit <sha>` / `-c <sha>` | `<sha>` が導入した変更（`git show <sha>` 経由。`<sha>^..<sha>` の diff に相当） |
| `Range` | `--from <a> --to <b>` | `merge-base(a, b)..b` |
各 diff は次を保持します: old/new path、old/new hunk、挿入/削除カウント、バイナリフラグ、リネーム検出。`DiffContextLines` は **3** に固定されており、Git のデフォルトと一致します。
untracked ファイルはディスクから読み込まれ、ファイル全体の新規追加として扱われるため、commit 前にレビューできます。
## 5 段階ゲートのファイルフィルタリング
diff の読み込み後、各ファイルは [`whyExcluded`](https://github.com/alibaba/open-code-review/blob/main/internal/agent/preview.go) を通過します。この関数は次のいずれかを返します:
```
binary — file is binary
user_exclude — matched a pattern in your `exclude` list
unsupported_ext — extension is not in supported_file_types.json
default_path — matched a built-in test-file exclude pattern
```
……またはファイルが保持される場合は空を返します。`deleted` は `whyExcluded` からは**返されません**。これは `Preview()` の中でそのあと計算されます。保持されたファイルの diff が `IsDeleted` を報告したときです。各ゲートは以下の順序で実行されます:
1. `binary`: バイナリファイルが最初に破棄されます。
2. `user_exclude`: あなたのプロジェクトの `exclude` が常に優先されます。
3. `user_include`: include パターンが設定されており**かつ**ファイルがそのいずれかに一致する場合、即座に保持され（空を返す）、下記の `unsupported_ext` と `default_path` のゲートをバイパスします。
4. `unsupported_ext` は拡張子のホワイトリストでフィルタリングします。
5. `default_path` は最後のゲートです: 組み込みの**テストファイル**除外パターン（`**/*_test.go`、`**/*.test.{js,jsx,ts,tsx}`、`**/__tests__/**`、`**/*_test.py`、`**/*_spec.rb`、`**/*.test.ets`……）に一致します。各パターンはルートプレフィックスとして `**/` を付けます。
ノイズディレクトリのフィルタリング（`vendor/`、`node_modules/`、`target/`……）は、より早い段階、diff-provider 層で、`internal/diff/git.go` の `providerDirIgnoreDirs` リストを通じて発生します。これらのディレクトリの diff は解析されたあと `filterDiffs` によって除去され、ファイルごとのフィルターに到達することは決してありません。
`ocr review --preview` を実行すると、token を消費せずに完全なフィルタリング結果を確認できます。完全なアルゴリズムは[レビュールール](../review-rules/#how-files-are-filtered)を参照してください。
## ファイルごとのサブタスク: plan + main
フィルタリングを通過した各ファイルについて、OCR はサブエージェントを起動します。各サブエージェントは自身の goroutine 内で実行され、`--concurrency`（デフォルト **8**）によって制限され、独立した LLM メッセージバッファを持ちます。
1 つのサブタスクは最大**2 つの段階**を持ちます:
### 段階 1: Plan（任意）
```go
threshold := template.PlanModeLineThreshold // 50
changeLines := d.Insertions + d.Deletions
if changeLines < threshold { skip plan }
```
小さな diff に対しては、plan はレイテンシを増やすだけで価値がないため、静かにスキップされ、main ループが直接実行されます。より大きな diff に対しては、OCR は**1 回だけ** `PLAN_TASK` の LLM 呼び出しを行います。`Tools` フィールドを送らないため、plan の間モデルはツールを呼び出せません。読み取り専用ツールのサブセット（`code_search`、`file_read_diff`、`file_find`。`tools.json` で `plan_task` フラグが `true` の 3 つ）が、`{{plan_tools}}` プレースホルダー（`formatToolDefs` でレンダリング）を通じてプレーンテキストとして埋め込まれ、あとで何が使えるかをモデルに知らせます。モデルはチェックリストを返し、それが main prompt 内の `{{plan_guidance}}` になります。
### 段階 2: main ループ
main ループは `MAIN_TASK` prompt を組み立て、モデルとツール呼び出しの対話を展開します。完全なツールセットは、plan 段階のツールに **`task_done`**、**`code_comment`**、**`file_read`** を加えたものです。完全な一覧は[ツール](../tools/)を参照してください。
```
loop up to MAX_TOOL_REQUEST_TIMES (default 30):
response = llm.complete(messages, tools)
if response.toolCalls is empty:
nudge model with "You did not successfully call any tools.
Please try again or use task_done if finished."
continue
for each call: execute → collect result
if any call was task_done: break
addNextMessage(...) # may trigger compression
```
ループには 5 つの終了条件があります:
1. `task_done` が呼び出された。
2. `MAX_TOOL_REQUEST_TIMES` を使い切った。
3. 有効なツール結果が 3 ラウンド連続で生成されなかった（`maxConsecutiveEmptyRounds = 3`）。
4. context がキャンセルされた。
5. `addNextMessage` が false を返した。圧縮してもメッセージバッファを警告しきい値以下に戻せなかった場合です。
いずれの場合でも、収集済みの `code_comment` 呼び出しがレビューコメントになります。
## メモリ圧縮
長いツール呼び出しループは、最終的にコンテキストウィンドウをあふれさせます。OCR は**3 分割**戦略で管理し、`MAX_TOKENS = 58888` で定義される token 予算でトリガーされます:
| しきい値 | 定数 | 動作 |
|---|---|---|
| MAX_TOKENS の 60% | `tokenSoftThreshold` | **非同期**のバックグラウンド圧縮を起動します。現在のループは中断せず継続します。 |
| MAX_TOKENS の 80% | `tokenWarningThreshold` | 次のリクエストを送る前に**同期的**に圧縮を実行します。 |
### 3 つのゾーン
```mermaid
flowchart LR
subgraph messages["messages"]
direction LR
F["<b>frozen</b><br/>first 2 msgs<br/>(system +<br/>initial user)"]
C["<b>compress</b><br/>summarized<br/>into one<br/>user msg"]
A["<b>active</b><br/>K most recent<br/>complete<br/>rounds"]
end
F --- C --- A
```
1「ラウンド」とは、1 つの assistant メッセージと、それに続くツール結果メッセージのことです。`partitionMessages` は末尾から前へラウンドを辿り、`(0.80 × MAX_TOKENS) - reservedTokens` に収まる限り多くのラウンドを保持します。それより前の内容が **compress ゾーン**になります。
compress ゾーンは XML としてレンダリングされ、`MEMORY_COMPRESSION_TASK` prompt でモデルに渡されます。返されたサマリーは、`<previous_review_summary>` タグで包まれて元の user メッセージ内に追記されます。
圧縮後: `messages = frozen[2] + compressed_user_msg + active`。
```go
// compression.go
func (a *Agent) runCompression(ctx context.Context, msgs []llm.Message, filePath string) ([]llm.Message, error) {
part := partitionMessages(msgs, a.args.Template.MaxTokens, 0)
contextXML := buildMessageXML(msgs[part.frozenEnd:part.compressEnd])
// … MEMORY_COMPRESSION_TASK を呼び出す …
rebuilt[1] = llm.NewTextMessage(role, currentText+
"\n\n<previous_review_summary>\n"+rawSummary+"\n</previous_review_summary>")
for i := part.compressEnd; i < len(msgs); i++ {
rebuilt = append(rebuilt, msgs[i])
}
return rebuilt, nil
}
```
### 非同期 vs 同期
非同期パスでは、バックグラウンドで圧縮が実行されている間も main ループがツール呼び出しを生成し続けられます。次の token チェックが発生したとき、準備できたサマリーが `tryApplyPendingCompression` を通じて適用されます。非同期タスクが完了する前に比率が警告しきい値を越えた場合、ループは一時停止して `runCompression` を同期的に実行します。これにより次のリクエストが必ず収まることが保証されます。
## コメント処理パイプライン
各 `code_comment` ツール呼び出しは 1 つ以上の生のコメントを生成します。それらは**CommentWorkerPool**（固定サイズの goroutine プール）を通過し、メインのツール呼び出しループが後処理でブロックされることを防ぎます:
1. **行解決**（worker 内）: `existing_code` をスライディングウィンドウアルゴリズムで diff と照合し、正確な `start_line` / `end_line` を計算します。照合に失敗した場合は両方ともデフォルトで `0` になります。行範囲 `0` は「アンカーされていない」コメントの暗黙のシグナルであり、ユーザーが手動で位置を特定する必要があります（格納されるフラグはありません。下流のコンシューマーが `start_line == 0` をチェックします）。
2. **再配置タスク** *（任意のフォールバック）*: 行解決がより複雑な diff で失敗したとき、OCR は `RE_LOCATION_TASK` prompt を実行し、モデルにスニペットの再アンカーを依頼します。書き換えられた `existing_code` 文字列に有用です。
3. **レビューフィルター**: main ループの終了後（worker プールが空になったあと）、`REVIEW_FILTER_TASK` の LLM 呼び出しが、収集されたコメントを diff と照合してチェックし、明らかに誤りと証明できるコメントを削除します。ここでのエラーは記録されたうえで無視されます。
4. **2 回目の行解決**: `Agent.Run` が戻ったあと、トップレベルのコマンドが完全なコメントセットに対して `diff.ResolveLineNumbers` を再実行します（`cmd/opencodereview/review_cmd.go` を参照）。`existing_code` が複数ファイルにまたがる、あるいは再配置ステップで更新されたコメントを捕捉するためです。
5. **レンダリング**: `--format` に従って text または JSON にレンダリングします。
## token 予算ガード
LLM を呼び出す前に、OCR はまず fail-fast のチェックを行います:
```go
tokenLimit := MaxTokens * 4 / 5 // 80 %
if countMessagesTokens(messages) > tokenLimit {
record warning "token_threshold_exceeded"
return nil // skip this file
}
```
これにより、巨大な diff（自動生成された lock ファイル、数千行に触れるリファクタリング）がリクエストを消費する前にそれらを食い止めます。スキップされたファイルは致命的でない警告として stdout に報告され、JSON の `warnings` 配列に追加されます。
2 つ目のチェックは `filterLargeDiffs` の中で実行されます: diff が単独で `MAX_TOKENS` の 80% を超える場合、ファイルごとのディスパッチャーが起動する前にフィルタリングで除去されます。
## テンプレートとプレースホルダー
`internal/config/template/task_template.json` には**5 つの prompt** が含まれます:
| Key | 用途 |
|---|---|
| `PLAN_TASK` | plan 段階。チェックリストを生成します。 |
| `MAIN_TASK` | main レビューループ。`code_comment` 呼び出しを発行します。 |
| `MEMORY_COMPRESSION_TASK` | compress ゾーンを要約します。 |
| `REVIEW_FILTER_TASK` | ループ後に、明らかに誤りと証明できるコメントを削除する処理。 |
| `RE_LOCATION_TASK` | `existing_code` を照合できないコメントを再アンカーします。 |
各 prompt は `{role, prompt_file}` 参照のリストで、テンプレートディレクトリ内の `.md` ファイルを指します（例: `{"role": "system", "prompt_file": "main_task_system.md"}`）。読み込み時に `resolveConversation` がこれらのファイルをメモリ内の `{role, content}` メッセージに読み込み、その後テンプレートのプレースホルダーがファイルごとに解決されます:
| プレースホルダー | 置換される内容 |
|---|---|
| `{{system_rule}}` | 4 層チェーンから解決されたルール本文。 |
| `{{change_files}}` | PR 内の他の各変更ファイルの状態 + パス。 |
| `{{diff}}` | このファイルの diff（生の `git diff` 出力）。 |
| `{{current_file_path}}` | このファイルの新しいパス。 |
| `{{plan_guidance}}` | plan 段階の出力。plan がスキップされた場合は削除されます。 |
| `{{plan_tools}}` | plan 段階のツール定義のプレーンテキスト（`formatToolDefs` でレンダリング）。`PLAN_TASK` の system prompt に使用されます。 |
| `{{requirement_background}}` | `--background` 引数の内容。 |
| `{{current_system_date_time}}` | 実行時のローカルタイムスタンプ。形式は `YYYY-MM-DD HH:MM`（秒やタイムゾーンなし）。 |
| `{{context}}` | （圧縮時のみ）要約対象の XML レンダリング済みメッセージ。 |
| `{{path}}` | ファイルパス。`REVIEW_FILTER_TASK` に使用されます。 |
| `{{comments}}` | 蓄積されたコメント（JSON）。`REVIEW_FILTER_TASK` に使用されます。 |
プレースホルダーの置換は [`agent.go`](https://github.com/alibaba/open-code-review/blob/main/internal/agent/agent.go) にあります。テンプレート自体は CLI では上書きできません。prompt を変更するには、[`task_template.json`](https://github.com/alibaba/open-code-review/blob/main/internal/config/template/task_template.json) を編集して再ビルドする必要があります。`--tools` 引数は*ツールレジストリ*の上書きです（`internal/config/toolsconfig` が消費する JSON を置き換えます）。テンプレートの上書きではありません。[ツール](../tools/#customizing-tools)を参照してください。
> **プレースホルダー構文についての注意。** 上記のプレースホルダーはすべて二重波括弧 `{{…}}` 構文を使用します。*ただし* `RE_LOCATION_TASK` は例外で、単一波括弧の `{diff}`、`{existing_code}`、`{suggestion_content}` を置換します（`internal/diff/relocation.go` を参照）。
## 永続化
各レビューは JSONL としてディスクに書き込まれます:
```
~/.opencodereview/sessions/<encoded-repo-path>/<session-id>.jsonl
```
リポジトリパスは base64 エンコード**されません**。`encodeRepoPath`（`internal/session/persist.go` 内）が `/` と `\` を `-` に、`:` を `_` に置換し、パスをファイルシステムで安全にします。
各行は 1 つのイベントです: 送信された prompt、LLM レスポンス、ツール呼び出し、ツール結果、発行されたコメントなど。Web UI（`ocr viewer`）はこれらのファイルを直接読みます。データベースはなく、append-only のログだけです。UI ガイドとイベント schema は[セッションビューア](../viewer/)を参照してください。
## テレメトリ
テレメトリを有効にすると、agent は 3 つのパイプラインレベルの span を発行します（`review.run` はジョブ全体を包み、`diff.parse` は diff の読み込みを包み、レビューされた各ファイルにつき 1 つの `subtask.execute.<file>`）。加えて、各決定ポイントで短命な `event.<name>` span を発行します（`plan.skipped`、`token.threshold.exceeded`、`subtask.error`……）。LLM の往復とツール呼び出しは metrics としてのみ記録され、span としては記録されません。prompt とレスポンスの内容がテレメトリに添付されることは**決してありません**。`OCR_CONTENT_LOGGING` フラグは配線済みですが、現在はデッドコードです。完全な schema は[テレメトリ](../telemetry/)を参照してください。
## *自動化されない*もの
一部の決定は意図的に手動のままにされています:
- **エンドポイント発見にフォールバックはありません。** config + env + rc ファイルが完全な `(URL, token, model)` の三つ組を与えられない場合、OCR は推測するのではなく非ゼロコードで終了します。
- **サブエージェントの失敗は隔離され、リトライされません。** 1 つの失敗したファイルは 1 つの警告を生成し、残りは継続します。リトライは、それを包む CI パイプラインの責務であり、agent の責務ではありません。
- **クロスファイルの推論はありません。** 各ファイルはそれ自身の LLM 対話でレビューされます。ファイルをまたぐ問題は `file_read_diff` / `code_search` ツール呼び出しを通じて扱われ、共有コンテキストは使いません。それら*他の*ファイルで見つかった問題をコメント対象にすることも禁止されています。`main_task` prompt は、コンテキストツールを理解のためだけに使い、現在の diff の外にあるファイルで見つかった問題は無視するようモデルに指示します。
これらの選択により、実行は**ファイルごとに決定的**になり、コストが予測可能になります。
## ソースコードマップ
対照しながら読みたい場合:
| 関心事 | ファイル |
|---|---|
| トップレベルのコマンドディスパッチ | `cmd/opencodereview/main.go` |
| `review` の引数解析 | `cmd/opencodereview/flags.go` |
| agent のオーケストレーションと圧縮 | `internal/agent/`（agent.go、compression.go、util.go） |
| ファイルフィルタリング / プレビュー | `internal/agent/preview.go` |
| diff の読み込み（Git モード） | `internal/diff/git.go` |
| ルール解決チェーン | `internal/config/rules/system_rules.go` |
| ツールレジストリと実装 | `internal/tool/` |
| LLM エンドポイントリゾルバ | `internal/llm/resolver.go` |
| セッション JSONL ライター | `internal/session/persist.go` |
| Web ビューア | `internal/viewer/server.go` |
ビルドとテストの説明は[コントリビュート](../contributing/)を参照してください。
## 関連項目
- [ツール](../tools/): agent ループが呼び出す 6 種類のツール。
- [レビュールール](../review-rules/): ファイルごとのルールテキストがどう解決されるか。
- [セッションビューア](../viewer/): このパイプラインが書き出したトランスクリプトを確認します。

350
pages/src/content/docs/ja/cli-reference.md Normal file
View file

@ -0,0 +1,350 @@
---
title: CLI リファレンス
sidebar:
order: 6
---
各 `ocr` サブコマンド、引数、終了時の挙動に関する完全なリファレンスです。
## グローバルな使い方
```text
OpenCodeReview - AI-Powered Code Review CLI
Usage:
ocr [command]
Commands:
review, r Start a code review
rules Inspect and debug review rules
config Manage configuration settings
llm LLM utility commands
viewer Start the WebUI session viewer
version Show version information
Examples:
ocr review --from master --to dev Review diff range
ocr review --commit abc123 Review a single commit
ocr config provider Interactive provider setup
ocr config model Interactive model selection
ocr config set llm.model opus-4-6 Set a config value
ocr llm test Test LLM connectivity
ocr llm providers List built-in providers
ocr version Show version info
Use "ocr review -h" for more information about review.
Use "ocr rules -h" for more information about rules.
Use "ocr config" for more information about config.
Use "ocr llm" for more information about LLM utilities.
GitHub: https://github.com/alibaba/open-code-review
```
## コマンド一覧
| コマンド | エイリアス | 役割 |
|---|---|---|
| `ocr review` | `ocr r` | コードレビューを実行してコメントを出力します。 |
| `ocr rules check <file>` | — | あるファイルパスにどのルールが適用され、その出所はどこかを表示します。 |
| `ocr config set <key> <value>` | — | 設定値を `~/.opencodereview/config.json` に永続化します。 |
| `ocr config unset custom_providers.<name>` | — | カスタムプロバイダーを削除します（現在有効なものであれば、有効な `provider`/`model` もクリアされます）。 |
| `ocr config provider` | — | 対話的なプロバイダー設定 TUI。 |
| `ocr config model` | — | 対話的な model 選択 TUI。 |
| `ocr llm test` | — | 短い chat リクエストを送信し、設定されたエンドポイントを検証します。 |
| `ocr llm providers` | — | 組み込みの LLM プロバイダーをすべて一覧表示します。 |
| `ocr viewer` | — | 過去のレビューセッション用のローカル Web UI を起動します（`localhost:5483`）。 |
| `ocr version` | — | バージョン、commit、プラットフォーム、ビルド日、GitHub URL を出力します。 |
`ocr` および `ocr -h` はトップレベルの使い方を出力します。各サブコマンドも `-h` / `--help` を受け付けます。
## `ocr review`
メインコマンドです。Git diff を解析し、ファイルごとのサブエージェントをディスパッチし、レビューコメントを収集して出力します。
### 概要
```text
ocr review [flags]
ocr r [flags] (alias)
```
引数を何も渡さない場合、OCR は**ワークスペースモード**で動作します。カレントディレクトリのリポジトリ内にある staged + unstaged + untracked のすべての変更をレビューします。
### 引数
| 引数 | 短縮形 | デフォルト | 説明 |
|---|---|---|---|
| `--repo <path>` | — | カレントディレクトリ | Git リポジトリのルート。 |
| `--from <ref>` | — | — | diff の開始 ref（例: `main`）。 |
| `--to <ref>` | — | — | diff の終了 ref（例: `feature-branch`）。設定すると OCR は `merge-base(from, to)..to` を計算します。 |
| `--commit <sha>` | `-c` | — | 単一の commit をレビューします（その親との差分）。 |
| `--preview` | `-p` | `false` | フィルタリングのパイプラインを実行しますが LLM はスキップします。ファイル一覧と除外理由を出力します。 |
| `--format <fmt>` | `-f` | `text` | `text`（人間が読みやすい形式）または `json`（機械可読なコメント配列）。 |
| `--audience <who>` | — | `human` | `human` は進捗行をストリーム出力します。`agent` は stdout を静音化し、最終サマリー / JSON のみを出力します。 |
| `--background <text>` | `-b` | — | plan + main prompt に注入する、任意の要件 / 業務コンテキスト。 |
| `--concurrency <n>` | — | `8` | 並行してレビューするファイルの最大数。 |
| `--timeout <minutes>` | — | `10` | ファイルごとの締め切り時間。`0` でタイムアウトを無効化します。 |
| `--rule <path>` | — | — | カスタム JSON レビュールールファイルのパス。プロジェクトレベルおよびグローバルの `rule.json` を上書きします。 |
| `--max-tools <n>` | — | テンプレートのデフォルト | ファイルごとの最大ツール呼び出し回数。`0` はテンプレートのデフォルト（`30`）を使用します。1〜9 は `10` に引き上げられます。`≥ 10` の値はすべてテンプレートのデフォルトを上書きします（`30` より小さくても）。 |
| `--model <name>` | — | — | 今回のレビューについて、解決済みの LLM model を上書きします（例: `claude-opus-4-6`）。 |
| `--max-git-procs <n>` | — | `16` | 並行 git サブプロセスの最大数。 |
| `--tools <path>` | — | 埋め込み | カスタム JSON ツール設定ファイルのパス。埋め込みのツール定義を上書きします。 |
> モード引数は排他です: `--from`/`--to` を渡すか、`--commit` を渡すか、いずれも渡さない（ワークスペースモード）かのいずれかです。
> 混在させるとそのままエラーになります。
### モード
#### ワークスペースモード（デフォルト）
```bash
ocr review
```
OCR は 2 つの git コマンドからワークツリーの変更を組み立てます:
- `git diff HEAD` で追跡済みの変更を取得します（staged + unstaged をまとめて `HEAD` と比較。空の場合は `git diff --staged` にフォールバック）
- `git ls-files --others --exclude-standard` で untracked ファイルを取得し、ディスクから読み込んでファイル全体の新規追加として扱います
これは通常、commit 前に確認したい内容そのものです。より小さな範囲が必要なら、選択的に stage してください。
#### 範囲モード
```bash
ocr review --from main --to feature-branch
```
OCR は `merge-base(main, feature-branch)..feature-branch` を計算するため、feature ブランチが*導入した* diff だけが表示されます。ブランチを切ったあとに `main` へ入った無関係な変更は含まれません。
#### Commit モード
```bash
ocr review --commit abc123
ocr review -c abc123
```
`git show abc123` が生成する diff（すなわちその commit が導入した変更）をレビューします。
### 出力
#### Text（デフォルト、`--audience human`）
レビュー実行中は進捗行をストリーム出力し、続いてコメントごとに 1 ブロックを出力します（`path:start-end` を含む暗色の Unicode 区切りヘッダー、100 桁で折り返されたコメント本文、そして（存在する場合は）提案された置換のカラー化されたインライン diff）。実行終了時には stdout の末尾にサマリーを出力します:
```
[ocr] 17 file(s) changed, reviewing 9 in /path/to/repo
[ocr] Skipping image.png — filtered by path/extension rules
[ocr] ▶ file_read "src/foo.go"
[ocr] ✔ file_read (12ms)
[ocr] Plan completed for src/foo.go
…
─── src/foo.go:42-47 ───
Concurrent map access without a lock — wrap with sync.RWMutex.
- m[k] = v
+ mu.Lock(); defer mu.Unlock(); m[k] = v
…
[ocr] Summary: 9 file(s) reviewed, 14 comment(s), ~21344 token(s) used (input: ~18012, output: ~3332), 1m12s elapsed
```
#### Text（agent、`--audience agent`）
コメントの出力は同じですが、内部的に静音化可能な stdout ライターを通じて進捗行が抑制されます（[`internal/stdout`](https://github.com/alibaba/open-code-review/blob/main/internal/stdout/stdout.go)）。CI / パイプライン内で別の agent に引き渡す場合に使用します。
#### JSON
```bash
ocr review --format json --audience agent
```
```json
{
"status": "success",
"summary": {
"files_reviewed": 9,
"comments": 1,
"total_tokens": 21344,
"input_tokens": 18012,
"output_tokens": 3332,
"elapsed": "1m12s"
},
"comments": [
{
"path": "src/foo.go",
"content": "Concurrent map access without a lock — wrap with sync.RWMutex.",
"start_line": 42,
"end_line": 47,
"existing_code": "m[k] = v",
"suggestion_code": "mu.Lock(); defer mu.Unlock(); m[k] = v",
"thinking": "Looking at line 42, the map …"
}
]
}
```
トップレベルのフィールド:
| フィールド | 説明 |
|---|---|
| `status` | `success`、`completed_with_warnings`、`completed_with_errors`、または `skipped`。 |
| `message` | 任意。人間が読みやすいサマリー（例: `"No comments generated. Looks good to me."`）。 |
| `summary` | 任意。実行の集計: `files_reviewed`、`comments`、`total_tokens`、`input_tokens`、`output_tokens`、`cache_read_tokens`（omitempty）、`cache_write_tokens`（omitempty）、`elapsed`。`skipped` の実行時は省略されます。 |
| `comments` | 常に存在しますが、空の場合があります。各コメントのフィールドは上記の例のとおりです。 |
| `warnings` | 任意。1 つ以上のサブエージェントが失敗した場合に存在します。各項目は影響を受けたファイルとエラーを記述します。 |
レビュー対象のファイルがない場合、JSON モードは `skipped` の外殻を発行し、呼び出し側が「変更なし」と「発見なし」を区別できるようにします:
```json
{
"status": "skipped",
"message": "No supported files changed.",
"comments": []
}
```
### 終了コード
| コード | 意味 |
|---|---|
| `0` | レビューが完了しました（コメントがゼロの場合や、致命的でない警告がある場合もあります）。 |
| `1` | 致命的エラー。引数の誤り、LLM エンドポイントを解決できない、すべてのファイルごとのサブエージェントが失敗した、などです。エラーテキストは stderr に出力されます。 |
致命的でない警告（個々のサブエージェントの失敗、あるファイルが token しきい値を超過、など）はインラインで出力されます。JSON モードでは `warnings` 配列に追加されます。
## `ocr rules`
ルールの自己確認です。サブコマンドは 1 つだけです:
```text
ocr rules check [flags] <file-path>
Flags:
--repo <path> Git repository root (default: current dir)
--rule <path> Path to a custom rule JSON file
```
与えられたファイルパスに対して、OCR は次を行います:
1. 4 層のルールチェーン（custom → project → global → system）を辿ります。
2. 最初に一致したものを採用します。
3. **出所となる層**、一致した **glob パターン**、そして解決された**ルールテキスト**を出力します。
```bash
$ ocr rules check src/main/java/com/example/Foo.java
File: src/main/java/com/example/Foo.java
Source: System built-in
Pattern: **/*.java
Rule:
────────────────────────────────────────
<contents of internal/config/rules/rule_docs/java.md>
────────────────────────────────────────
```
「なぜ自分のカスタムルールが発火しないのか？」を調査するのに使えます。優先順位の完全な説明は[レビュールール](../review-rules/)を参照してください。
## `ocr config`
key を `~/.opencodereview/config.json` に永続化し、対話的な設定 TUI を提供します。4 つのサブコマンドがあります:
```text
ocr config set <key> <value>
ocr config unset custom_providers.<name> Delete a custom provider
ocr config provider Interactive provider setup
ocr config model Interactive model selection
```
- **`set`**: 非対話的に単一の設定値を書き込みます。
- **`unset`**: カスタムプロバイダーを削除します。サポートされるのは `custom_providers.<name>` のみです。削除するものが現在有効なプロバイダーの場合、`provider` と `model` がクリアされます（`ocr config provider` を実行して再選択してください）。
- **`provider`**: 対話的なプロバイダー設定 TUI を起動します（追加の引数なし。非対話的には `ocr config set provider <name>` を使用してください）。
- **`model`**: 対話的な model 選択 TUI を起動します（追加の引数なし。非対話的には `ocr config set model <name>` を使用してください）。
key の完全なリファレンス、schema、例は[設定](../configuration/)を参照してください。
## `ocr llm`
LLM ユーティリティコマンドです。2 つのサブコマンドがあります:
```text
ocr llm <sub-command>
Sub-commands:
test Send a test conversation to the configured LLM model
providers List all built-in LLM providers
```
### `ocr llm test`
```text
ocr llm test
```
`ocr review` とまったく同じ方法で LLM エンドポイントを解決し、[`internal/config/testconnection/task.json`](https://github.com/alibaba/open-code-review/blob/main/internal/config/testconnection/task.json) からあらかじめ用意された chat リクエストを送信して、以下を出力します:
```
Source: <which strategy was used>
URL: <endpoint URL>
Model: <effective model>
<the model's reply>
✓ Connection test successful
```
非ゼロで終了した場合は、エンドポイントが完全に設定されていないか、リクエストが失敗した（ネットワーク / 認証 / モデルのエラー）ことを意味します。エラーメッセージがどのケースかを示します。
### `ocr llm providers`
```text
ocr llm providers
```
各組み込み LLM プロバイダーを 3 列のテーブルで一覧表示します:
```
Built-in providers:
NAME PROTOCOL BASE URL
---- -------- --------
anthropic anthropic https://api.anthropic.com
…
```
続いて、`ocr config provider` で対話的に設定するか、`ocr config set provider <name>` で非対話的に設定できる旨のヒントが表示されます。
## `ocr viewer`
```text
ocr viewer [flags]
Flags:
--addr <address> listen address (default: localhost:5483)
Examples:
ocr viewer # start on default port
ocr viewer --addr :3000 # bind to all interfaces on port 3000
```
埋め込み HTTP サーバーを起動し、`~/.opencodereview/sessions/...` を読み込んで、過去のレビューセッションをブラウザで扱いやすい UI としてレンダリングします。[セッションビューア](../viewer/)を参照してください。
## `ocr version`
```text
ocr version
ocr --version
ocr -V
```
ビルド時に書き込まれたバージョン情報、短い Git commit（存在する場合）、プラットフォーム（`<GOOS>/<GOARCH>`）、ビルド日（存在する場合）、そして GitHub URL（`https://github.com/alibaba/open-code-review`）を出力します。
## ヒントと注意点
- `--audience agent` は `--format json` を**含意しません**。両者は異なることを制御します。UI の抑制 vs 構造化されたペイロードです。両方が必要な場合は組み合わせて使用してください。
- `--background` はレビュー品質を高めるのに最も効果的な引数の 1 つです。他の agent から呼び出す際は、常に要件 / PR の説明を渡してください。
- あるファイルの diff が単独で `MAX_TOKENS` の 80%（デフォルト `58888`）を超える場合、LLM を呼び出す前に破棄されます。これはログに記録されますが、実行を失敗にはしません。
- あるファイルの変更行数が `PLAN_MODE_LINE_THRESHOLD`（`50`）を下回る場合、plan 段階は**自動的にスキップ**されます。
## 関連項目
- [クイックスタート](../quickstart/): インストールして最初のレビューを完了します。
- [設定](../configuration/): 引数の背後にある環境変数と config key。
- [レビュールール](../review-rules/): `--rule` 引数とルールの解決。
- [連携](../integrations/): agent と CI から `ocr review` を呼び出します。

271
pages/src/content/docs/ja/configuration.md Normal file
View file

@ -0,0 +1,271 @@
---
title: 設定
sidebar:
order: 5
---
## エンドポイントの解決
`ocr review` または `ocr llm test` が実行されると、4 つの来源を順に試し、
完全な `(URL, token, model)` の三つ組を最初に返せた来源を使用します。
| 優先度 | 来源 | 読み取る内容 |
|---|---|---|
| 1 | `~/.opencodereview/config.json` | `provider` が設定されている場合は `providers`/`custom_providers` マッピングを通じて解決します（provider が優先。[組み込み provider](#built-in-providers) を参照）。provider が設定されていない場合にのみ、レガシーの `llm` セクションにフォールバックします。 |
| 2 | OCR 環境変数 | `OCR_LLM_URL`、`OCR_LLM_TOKEN`、`OCR_LLM_MODEL`、`OCR_USE_ANTHROPIC`、`OCR_LLM_AUTH_HEADER`。 |
| 3 | Claude Code 環境変数 | `ANTHROPIC_BASE_URL`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_MODEL`。 |
| 4 | シェルの rc ファイル | `~/.zshrc`、`~/.bashrc`、`~/.bash_profile`、`~/.profile` から解析された `export ANTHROPIC_*=…` 行。 |
Claude Code 風の来源については、`ANTHROPIC_BASE_URL` にバージョン付きのパス
（`/v1/...`）がない場合、OCR は自動的に `/v1/messages` を追加します。
いずれの戦略でも完全な三つ組が得られない場合、OCR は次のメッセージで終了します。
```
no valid LLM endpoint configured; one of OCR_LLM_URL/OCR_LLM_TOKEN/OCR_LLM_MODEL,
~/.opencodereview/config.json, or ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN/
ANTHROPIC_MODEL must be set
```
> 解決は、単に最初に空だった来源ではなく、最初に**エラーとなった**来源で停止します。特に注意してください。
> `config.json` に `provider` が設定されているのにその項目の設定が誤っている場合（不明な provider 名、
> 環境変数のフォールバックもなく `api_key` が欠落、`model` が欠落、カスタム provider の
> `url`/`protocol` が欠落）、OCR はそのエラーで終了し、OCR 環境変数、
> Claude Code、rc ファイルの来源にフォールバックすることは**ありません**。環境変数ベースの設定に切り替えるには、まず
> `provider` key を解除してください。
> 来源の優先順位により、設定ファイルが完全に埋まっている場合、**環境変数はいかなる値も上書きしません**。
> 環境変数を有効にするには、`~/.opencodereview/config.json` から該当する `llm.*` key を削除するか、
> `ocr config set` で新しい値に切り替えてください。
## `ocr config set` ——`~/.opencodereview/config.json` を管理する
```bash
ocr config set <key> <value>
```
`config set` は key/value ペアでファイルを変更し、schema を認識した解析を行います。インタラクティブな TUI
コマンド `ocr config provider` と `ocr config model` も同じファイルに書き込みます（
[インタラクティブ設定](#interactive-setup--ocr-config-provider--ocr-config-model) を参照）。認識される
key：
| Key | 型 | 説明 |
|---|---|---|
| `provider` | string | 現在の provider を設定します（組み込み名またはカスタム）。provider を切り替えると model がクリアされます。 |
| `model` | string | 現在の provider に model を設定します（provider 項目の下に保存。provider がない場合はトップレベルの `model` に保存）。 |
| `providers.<name>.<field>` | varies | 組み込み provider のフィールドごとの設定：`api_key`、`url`、`protocol`、`model`、`models`、`auth_header`、`extra_body`。 |
| `custom_providers.<name>.<field>` | varies | 同じフィールド。カスタム（非組み込み）provider 用。カスタム provider には少なくとも `url` と `protocol` を設定する必要があります。 |
| `llm.url` | string | エンドポイント URL。Anthropic では完全な Messages URL（例：`https://api.anthropic.com/v1/messages`）を使用します。OpenAI 互換では chat-completions URL を使用します。 |
| `llm.auth_token` | string | API key。`Authorization: Bearer …` として送信されます（OpenAI）。レガシーの Anthropic パスもデフォルトで `Authorization: Bearer …`（プリセットの `anthropic` provider ではデフォルトが `x-api-key` に変わります）。`llm.auth_header` を明示的に設定した場合にのみ `x-api-key` を使用します。 |
| `llm.auth_header` | string | Auth header 名（`x-api-key`、`authorization`、または `bearer`）。Anthropic のみで使用します。`x-api-key` を必要とする一部の Anthropic 設定で必須です。 |
| `llm.model` | string | モデル名。`[<数字>m]` サフィックスは自動的に除去されます。 |
| `llm.use_anthropic` | boolean | `true`（デフォルト）→ Anthropic Messages プロトコル。`false` → OpenAI Chat Completions。 |
| `llm.extra_body` | JSON object | ベンダー固有のリクエストフィールド。各 chat リクエストボディにマージされます。例：`'{"thinking":{"type":"disabled"}}'`。 |
| `language` | string | system prompt に追加される指示として転送されます。未設定の場合はデフォルトで `English`。[言語の選択](#choosing-a-language) を参照。 |
| `telemetry.enabled` | boolean | OpenTelemetry エクスポートのマスタースイッチ。デフォルトは無効。 |
| `telemetry.exporter` | string | `console` または `otlp`。 |
| `telemetry.otlp_endpoint` | string | OTLP collector のアドレス（例：`localhost:4317`）。 |
| `telemetry.content_logging` | boolean | エクスポートされるイベントデータに LLM の prompt / レスポンスを含めます。 |
例：
```bash
ocr config set llm.url https://api.anthropic.com/v1/messages
ocr config set llm.auth_token sk-ant-xxxxxxxxxx
ocr config set llm.model claude-opus-4-6
ocr config set llm.use_anthropic true
ocr config set llm.extra_body '{"thinking":{"type":"disabled"}}'
ocr config set language English
ocr config set telemetry.enabled true
ocr config set telemetry.exporter otlp
ocr config set telemetry.otlp_endpoint localhost:4317
# provider ベースの設定（推奨）
ocr config set provider anthropic
ocr config set model claude-opus-4-6
ocr config set providers.anthropic.api_key "$ANTHROPIC_API_KEY"
# カスタム（非組み込み）provider
ocr config set provider my-gateway
ocr config set custom_providers.my-gateway.url https://gateway.internal.com/v1
ocr config set custom_providers.my-gateway.protocol openai
ocr config set custom_providers.my-gateway.model llama-3-70b
ocr config set custom_providers.my-gateway.api_key "$MY_API_KEY"
```
boolean は Go の `strconv.ParseBool` が受け付ける任意の形式（`true`、`false`、`1`、`0`、
`t`、`f`……）を受け付けます。`llm.extra_body` は正しい JSON でなければなりません。
## ファイル schema リファレンス
上記のコマンドを実行すると、`~/.opencodereview/config.json` は次のようになります。
```json
{
"llm": {
"url": "https://api.anthropic.com/v1/messages",
"auth_token": "sk-ant-xxxxxxxxxx",
"auth_header": "x-api-key",
"model": "claude-opus-4-6",
"use_anthropic": true,
"extra_body": {
"thinking": { "type": "disabled" }
}
},
"language": "English",
"telemetry": {
"enabled": true,
"exporter": "otlp",
"otlp_endpoint": "localhost:4317"
}
}
```
provider ベースの形式では、レガシーの `llm` ブロックではなく `provider`、`model`、`providers`、
`custom_providers` を使用します。
```json
{
"provider": "anthropic",
"model": "claude-opus-4-6",
"providers": {
"anthropic": {
"api_key": "sk-ant-xxxxxxxxxx",
"model": "claude-opus-4-6"
}
},
"custom_providers": {
"my-gateway": {
"url": "https://gateway.internal.com/v1",
"protocol": "openai",
"model": "llama-3-70b",
"models": ["llama-3-70b", "llama-3-8b"],
"api_key": "gw-xxxxxxxxxx",
"auth_header": "authorization"
}
},
"language": "English"
}
```
`provider` が設定されている場合、解決は `providers`/`custom_providers` マッピングによって駆動されます。この設定では
レガシーの `llm` セクションは無視されます。
このファイルを手動で編集することもできますが、次回の書き込み時に `ocr config set` が `" "` インデントで
再シリアライズします。
## インタラクティブ設定——`ocr config provider` / `ocr config model`
provider と model を選択するために key を手動で入力する手間を省くため、OCR は 2 つのインタラクティブな Bubble Tea TUI を提供します。
どちらも同様に `~/.opencodereview/config.json` を変更します。
```bash
ocr config provider
ocr config model
```
- `ocr config provider`——組み込みまたはカスタムの provider を選択し、URL / protocol /
API key / model を入力するインタラクティブな TUI です。選択内容は config に保存され、自動的に `ocr llm test` を実行して
エンドポイントを検証します。組み込み provider の場合、直接入力しなければ API key はその provider の環境変数から
読み取れます（[組み込み provider](#built-in-providers) を参照）。手動設定を選んだ場合は、レガシーの
`llm.*` ブロックに代わりに書き込みます。
- `ocr config model`——現在の provider のプリセットリスト、および
`providers.<name>.models` / `custom_providers.<name>.models` の下でユーザーが追加した
model からモデルを選択するインタラクティブな TUI です。先に provider を設定しておく必要があります（`ocr config provider`）。
## 組み込み provider
以下の provider が OCR に同梱されています。それぞれにプリセットの `BaseURL`、`Protocol`、および
（該当する場合）`providers.<name>.api_key` が未設定のときにフォールバックとなる API key 環境変数があります。
| 名称 | Protocol | Base URL | API key 環境変数 |
|---|---|---|---|
| `anthropic` | anthropic | `https://api.anthropic.com` | `ANTHROPIC_API_KEY` |
| `openai` | openai | `https://api.openai.com/v1` | `OPENAI_API_KEY` |
| `dashscope` | openai | `https://dashscope.aliyuncs.com/compatible-mode/v1` | `DASHSCOPE_API_KEY` |
| `dashscope-tokenplan` | openai | `https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1` | `DASHSCOPE_TOKENPLAN_KEY` |
| `volcengine` | openai | `https://ark.cn-beijing.volces.com/api/v3` | `ARK_API_KEY` |
| `deepseek` | openai | `https://api.deepseek.com` | `DEEPSEEK_API_KEY` |
| `tencent-tokenhub` | openai | `https://tokenhub.tencentmaas.com/v1` | `TENCENT_TOKENHUB_API_KEY` |
| `hy-tokenplan` | openai | `https://api.lkeap.cloud.tencent.com/plan/v3` | `TENCENT_HUNYUAN_TOKENPLAN_KEY` |
| `kimi` | openai | `https://api.moonshot.cn/v1` | `MOONSHOT_API_KEY` |
| `z-ai` | openai | `https://open.bigmodel.cn/api/paas/v4` | `Z_AI_API_KEY` |
| `mimo` | openai | `https://api.xiaomimimo.com/v1` | `MIMO_API_KEY` |
| `minimax` | openai | `https://api.minimaxi.com/v1` | `MINIMAX_API_KEY` |
| `baidu-qianfan` | openai | `https://qianfan.baidubce.com/v2` | `QIANFAN_API_KEY` |
その他の provider 名はすべてカスタムとみなされ、`custom_providers` の下で設定する必要があり、少なくとも
`url` と `protocol` が必要です。
## 環境変数リファレンス
| 変数 | 用途 |
|---|---|
| `OCR_LLM_URL` | エンドポイント URL——`llm.url` と同形。 |
| `OCR_LLM_TOKEN` | API key——`llm.auth_token` と同じ。 |
| `OCR_LLM_MODEL` | モデル名。 |
| `OCR_LLM_AUTH_HEADER` | Auth header 名（`x-api-key`、`authorization`、または `bearer`）。Anthropic のみ。`llm.auth_header` と同じ。未設定の場合はデフォルトで `authorization`。 |
| `OCR_USE_ANTHROPIC` | 未設定 → Anthropic プロトコル（デフォルト）。`true` / `1` / `yes`（大文字小文字を区別しない）に設定 → Anthropic。その他の値（`false`、`0`、`no`、スペルミス……）に設定 → OpenAI。 |
| `ANTHROPIC_BASE_URL` | Claude Code 互換の base URL。 |
| `ANTHROPIC_AUTH_TOKEN` | Claude Code 互換の API key。 |
| `ANTHROPIC_MODEL` | Claude Code 互換の model。 |
| `OCR_ENABLE_TELEMETRY` | `1` で環境変数からテレメトリを有効化します。 |
| `OTEL_SERVICE_NAME` | span/metric の service name を上書きします。 |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP collector のアドレス——同時に exporter を `otlp` に強制します。 |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | OTLP のトランスポートプロトコル（`grpc`、`http/protobuf`、または `http/json`）。デフォルトは `grpc`。 |
| `OCR_CONTENT_LOGGING` | `1` でテレメトリイベントに prompt/レスポンスを含めます。 |
各 provider の API key（`ANTHROPIC_API_KEY`、`OPENAI_API_KEY`、
`DASHSCOPE_API_KEY`……）は、組み込み provider の `api_key` フィールドが未設定のときにフォールバックとなります。
各 provider の環境変数名は [組み込み provider](#built-in-providers) の表を参照してください。
## なぜ `extra_body` があるのか
一部のホスト型 provider は、リクエストボディに非標準のフィールドを追加します（例：Bedrock 風の `thinking`、
ベンダー固有の `temperature_strategy`、ストリーミングオプション）。`llm.extra_body` は発行される各リクエストに
マージされるため、ソースコードを変更せずにこれらのフィールドを送信できます。
```bash
ocr config set llm.extra_body '{"thinking":{"type":"enabled","budget_tokens":2048}}'
```
## 言語の選択
`language` key は 1 つのことだけを制御します。それは、レビューと `ocr llm test` の prompt 内の各
system-role メッセージに追加される 1 つの指示です。注入される正確な文字列は次のとおりです。
```
\n\nAlways respond in <language>.
```
- *未設定* または空——`English` として扱われます。
- `Chinese`、`English`、またはその他任意の文字列——そのまま透過されます。
組み込みの rule docs は言語の切り替えをサポートしません。`internal/config/rules/rule_docs/` の下に埋め込まれたファイルは
固定のファイル名で読み込まれ、ほとんどが中国語で書かれています（`default.md` は英語の例外）。`language`
の設定にかかわらず、それらはそのまま prompt に現れます。したがって `language` を `English` に設定した場合、prompt
には英語の指示と大量の中国語の rule テキストが重なります——強力なモデルは指示に従って英語のコメントを生成し、
弱いモデルは中国語と英語が混在した内容を出力する可能性があります。
`language` には環境変数、CLI 引数、プロジェクトレベルの上書きがありません——設定できる唯一の場所はグローバルな
`~/.opencodereview/config.json` で、
[`ocr config set`](#ocr-config-set--managing-opencodereviewconfigjson) を通じて設定します。
```bash
ocr config set language English
```
純粋な英語の rule テキストが必要な場合は、`--rule`、`<repo>/.opencodereview/rule.json`、
または `~/.opencodereview/rule.json` を通じて独自のルールを提供してください（
[レビュールール](../review-rules/#priority-chain) を参照）。
## プロジェクトレベル vs グローバル設定
CLI 自体はグローバルに設定されます（`~/.opencodereview/config.json`）——プロジェクトレベルの LLM 設定はありません。
ただし**レビュールール**はプロジェクトレベルです。[レビュールール](../review-rules/#priority-chain) を参照してください。
## 関連項目
- [クイックスタート](../quickstart/)——最小限のセットアップと初回のレビュー。
- [CLI リファレンス](../cli-reference/)——review コマンドが受け入れる各引数。
- [テレメトリ](../telemetry/)——OTLP / console exporter への接続方法。

205
pages/src/content/docs/ja/contributing.md Normal file
View file

@ -0,0 +1,205 @@
---
title: コントリビュート
sidebar:
order: 13
---
OCR は Apache-2.0 ライセンスのオープンソースプロジェクトです。バグ報告、ドキュメント修正、
コード貢献を歓迎します。本ページはクイックリファレンスです。正式版は
[`CONTRIBUTING.md`](https://github.com/alibaba/open-code-review/blob/main/CONTRIBUTING.md) にあります。
## 貢献の方法
Go を書かなくても貢献できます。
- **バグ報告**——再現手順を添えて
[GitHub issue](https://github.com/alibaba/open-code-review/issues/new/choose) を作成してください。
- **機能リクエスト**——
[Discussions](https://github.com/alibaba/open-code-review/discussions/categories/ideas)
に投稿するか、feature-request issue を作成してください。
- **ドキュメント**——誤字、不足している例、リンク切れ——これらの PR は通常、最も早くマージされます。
- **他の PR のレビュー**——メンテナー以外からのコメントは、レビュアーの負担軽減に役立ちます。
- **コード**——バグ修正、パフォーマンス改善、新機能。
## ローカル開発環境のセットアップ
### 前提条件
- [Go ≥ 1.25](https://go.dev/dl/)
- [Git](https://git-scm.com/)
- [Make](https://www.gnu.org/software/make/)
### ソースコードの取得
```bash
# GitHub で Fork し、次に:
git clone https://github.com/<your-username>/open-code-review.git
cd open-code-review
git remote add upstream https://github.com/alibaba/open-code-review.git
make build # dist/opencodereview を書き出す
make test # LC_ALL=C go test -v -race -count=1 ./...
```
> `upstream` remote は読み取り専用です。`origin`（あなたの fork）にプッシュし、そこから PR を出してください。
### ローカルビルドの実行
```bash
./dist/opencodereview review --preview
```
便宜のため、`dist/opencodereview` を指すシンボリックリンクを `~/bin/ocr-dev` に置いておくと、
任意のリポジトリで `ocr-dev` を呼び出せます。
### Make target
| Target | 作用 |
|---|---|
| `make build` | 現在のプラットフォーム向けにビルド → `dist/opencodereview`。 |
| `make build-darwin-amd64` | macOS Intel 向けのクロスコンパイル。 |
| `make build-darwin-arm64` | macOS Apple Silicon 向けのクロスコンパイル。 |
| `make build-linux-amd64` | Linux x86_64 向けのクロスコンパイル。 |
| `make build-linux-arm64` | Linux ARM64 向けのクロスコンパイル。 |
| `make build-windows-amd64` | Windows x86_64 向けのクロスコンパイル。 |
| `make build-windows-arm64` | Windows ARM64 向けのクロスコンパイル。 |
| `make build-all` | 6 つすべてのクロスコンパイルバイナリ（linux/darwin/windows × amd64/arm64）。 |
| `make sha256sum` | ビルド成果物の `sha256sum.txt` を生成。 |
| `make dist` | `clean → build-all → sha256sum`。CI が実行する内容。 |
| `make test` | race 検出を有効にしてテストを実行。 |
| `make clean` | `dist/` を削除。 |
## ブランチとコミットの規約
### ブランチのプレフィックス
| プレフィックス | 用途 |
|---|---|
| `feat/` | 新機能 |
| `fix/` | バグ修正 |
| `docs/` | ドキュメントのみ |
| `refactor/` | 挙動を変えないリファクタリング |
| `test/` | テストのみの変更 |
| `chore/` | ビルド / CI / ツール |
```bash
git checkout main
git pull upstream main
git checkout -b feat/anthropic-streaming
```
### コミットメッセージ
[Conventional Commits](https://www.conventionalcommits.org/) フォーマット:
```
<type>(<scope>): <short summary>
[optional body explaining the why]
```
例:
```
feat(agent): add support for custom tool definitions
fix(llm): handle timeout errors in Anthropic API calls
docs(readme): clarify endpoint resolution priority
refactor(viewer): extract task-card rendering into helper
```
**PR タイトル**も同じフォーマットを使うと、生成される changelog に整然と表示されます。
## プロジェクト構成
```
open-code-review/
├── cmd/opencodereview/ # CLI エントリーポイント——引数解析、ディスパッチ
├── internal/
│ ├── agent/ # レビューエージェントのロジック、サブエージェントのディスパッチ
│ ├── config/ # テンプレート、ルール、ホワイトリスト、埋め込み JSON
│ ├── diff/ # Git diff の解析、3 つのモード
│ ├── gitcmd/ # Git サブプロセスランナー
│ ├── llm/ # LLM client（Anthropic と OpenAI）、エンドポイント解決
│ ├── model/ # データ構造（LlmComment、Diff……）
│ ├── pathutil/ # パスユーティリティ
│ ├── release/ # Release notes の生成
│ ├── session/ # JSONL セッションライター
│ ├── stdout/ # ミュート可能な stdout writer
│ ├── suggestdiff/ # 提案 diff のレンダリング
│ ├── telemetry/ # OpenTelemetry の設定 + ヘルパー
│ ├── tool/ # ツールレジストリ + provider の実装
│ └── viewer/ # 埋め込み HTTP UI
├── pages/ # WebUI マーケティングページ（独立した React app）
├── plugins/ # Claude Code slash コマンド
├── extensions/ # エディタ拡張（VS Code）
├── examples/ # CI レシピ（GitHub Actions、GitLab CI）
├── skills/ # Agent SDK skill manifest
├── scripts/ # NPM postinstall + クロスプラットフォームビルドスクリプト
├── npm/ # 各プラットフォーム向け optional dependency パッケージ
└── bin/ # NPM wrapper（Node）
```
ほとんどの貢献は `internal/agent/`、`internal/tool/`、`internal/llm/` に触れます。
`cmd/opencodereview/` の CLI レイヤーは意図的に薄く保たれています——引数を解析してから
agent パッケージへディスパッチします。
## コード品質チェック
PR を出す前に:
```bash
go fmt ./...
go vet ./...
make test # race 有効、CI では push のたびに実行される
make build # バイナリがビルドできることのスモークテスト
```
CI は push のたびに同じ一式を実行するため、予期せぬ結果になることはありません。
## 新しいツールの追加
ツールは 2 つの部分から成ります。
1. [`internal/config/toolsconfig/tools.json`](https://github.com/alibaba/open-code-review/blob/main/internal/config/toolsconfig/tools.json)
内の **JSON 定義**: name、description、そして LLM が見る JSON-schema 引数。
2. `internal/tool/definitions.go` に登録される **Go provider**（実際の実装を含む）。
両方が揃って初めて、新しいツール名が機能します。既存の 6 つは[ツール](../tools/)にあり、
テンプレートとして使えます。
## 新しいルールパターンの追加
`internal/config/rules/system_rules.json` を編集して新しい glob をルールドキュメントにマッピングし、
`internal/config/rules/rule_docs/` 下に対応する markdown を追加します。ルールドキュメントは
パターンごとに 1 ファイルで保存されます（英語）。`language` 設定は system prompt に
「その言語で応答せよ」という指示を 1 行追加するだけです。rule-doc ファイルは切り替えません。
## PR のフロー
1. **大きな変更はまず issue を作成してください。** 事前に方向性を合わせておく方が、
コードレビューで初めて相違に気づくよりも良いです。
2. **1 つの PR につき 1 つの論理的変更。** 無関係な修正が 2 つあるなら、PR を 2 つ出してください。
3. **テストを更新してください。** 挙動の変更にはテストのカバレッジが必要です——`make test` は必ず通ること。
4. **ドキュメントを更新してください。** 変更が引数、config key、レビューパイプラインに影響する場合は、
本ドキュメントサイト（[`docs/`](https://github.com/alibaba/open-code-review) 内）と関連するインラインヘルプの
両方を更新してください。
5. **PR テンプレートを記入してください。** メンテナーがレビューします。通常は数営業日以内です。
## コントリビューターライセンス契約（CLA）
本プロジェクトは Alibaba Open Source CLA を必要とします。初めて PR を出すと bot がリンクを貼ります——
電子署名してください（1 分程度）。以降の PR では再署名は不要です。
## 初めての貢献ですか？
[`good first issue`](https://github.com/alibaba/open-code-review/labels/good%20first%20issue)
または [`help wanted`](https://github.com/alibaba/open-code-review/labels/help%20wanted)
のラベルが付いた issue を探してください。ほとんどは小規模で自己完結しており、issue の説明に
着手に十分なコンテキストがあります。
## 関連項目
- [アーキテクチャ](../architecture/)——`internal/agent/` を変更する前に必要なメンタルモデル。
- [ツール](../tools/)——既存のツールがどのようなものか。
- 完全な貢献ガイド:
[CONTRIBUTING.md](https://github.com/alibaba/open-code-review/blob/main/CONTRIBUTING.md)

304
pages/src/content/docs/ja/faq.md Normal file
View file

@ -0,0 +1,304 @@
---
title: FAQ
sidebar:
order: 14
---
よくあるエラー、想定外の挙動、そして「これは仕様ですか？」という疑問をまとめました。ここに
あなたの問題が見つからない場合は、実行手順と完全な出力を添えて
[GitHub issue](https://github.com/alibaba/open-code-review/issues) を作成してください。
## 設定と起動
### `no valid LLM endpoint configured`
```
no valid LLM endpoint configured; one of OCR_LLM_URL/OCR_LLM_TOKEN/OCR_LLM_MODEL,
~/.opencodereview/config.json, or ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN/
ANTHROPIC_MODEL must be set
```
OCR は 4 つのソースからなる解決チェーン（[設定](../configuration/#endpoint-resolution)）を
たどりましたが、完全な `(URL, token, model)` の三つ組を見つけられませんでした。次のいずれかを
行ってください。
- `ocr config set llm.url …` / `llm.auth_token …` / `llm.model …` を実行して
`~/.opencodereview/config.json` を埋める、**または**
- `OCR_LLM_URL` / `OCR_LLM_TOKEN` / `OCR_LLM_MODEL` をエクスポートする、**または**
- すでに Claude Code を使っている場合は、`ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN` /
`ANTHROPIC_MODEL` をエクスポートする。
その後 `ocr llm test` で接続性を検証してからレビューを再試行してください。
### `ocr llm test` が誤ったソースを表示する
OCR は**最後**ではなく**最初**の完全な三つ組を採用します。したがって、設定ファイルに
すでに 3 つの llm.* key がすべて揃っていると、環境変数は無視されます。環境変数を有効にするには、
設定 key を削除する（ファイルを削除するか手動で unset する）か、`ocr config set` で新しい値に
切り替えてください。
### `ocr llm test` が 401 / 403 を返す
token に scope が不足している、期限切れ、あるいはプロバイダーが一致していません。Anthropic と
OpenAI は異なる auth header と URL フォーマットを使います——`llm.use_anthropic` が指し先の URL と
一致していることを確認してください。
- Anthropic: URL は `/v1/messages` で終わり、`use_anthropic=true`。
- OpenAI / OpenAI 互換: URL は `/v1/chat/completions` で終わり、
`use_anthropic=false`。
### `not a git repository`
`ocr review` はカレントディレクトリに対して `git diff`（および untracked ファイルに対する
`git ls-files`）を実行します。Git ワークツリー内にいない場合は、早期に終了します。リポジトリに
`cd` するか、`--repo /path/to/repo` を渡してください。
## フィルタリングとルール
### ファイルがレビューされない
`ocr review --preview` を実行してください（LLM コストなし）。出力には各候補ファイルと、それが
保持されたか破棄されたかの**理由**が一覧されます。
```
src/foo.go modified
src/foo_test.go modified (excluded: user_exclude)
node_modules/lib.js added (excluded: default_path)
imgs/logo.png binary (excluded: unsupported_ext)
```
5 種類の除外理由は、[ファイルフィルタリング](../review-rules/#how-files-are-filtered)のゲートに対応します。
| 理由 | 修正方法 |
|---|---|
| `binary` | 対処不要——バイナリファイルにはレビュー可能なテキストがありません。 |
| `user_exclude` | あなたの `exclude` リストからそのパターンを削除してください。 |
| `unsupported_ext` | ホワイトリストゲートを回避するため、拡張子を `include` リストに追加してください。 |
| `default_path` | ファイルを `include` に追加してください——組み込みのテストファイル除外パターンを上書きします。 |
| `deleted` | 対処不要——レビュー対象の新しい内容がありません。 |
### カスタムルールが発火しない
`ocr rules check <file-path>` を実行してください。マッチした**レイヤー**と **glob パターン**を
すべて表示します。
```
File: src/api/UserHandler.go
Source: Project (.opencodereview/rule.json)
Pattern: src/api/**/*.go
Rule: …
```
レイヤーが正しくない場合（プロジェクトルールを期待していたのに "System built-in" と表示される等）、
多くは**宣言順序**の問題です——最初にマッチしたパターンが適用されます。より具体的なルールを
`rules` 配列内で前に移動するか、glob を修正してください。
### 波括弧展開が動作しない
`bmatcuk/doublestar/v4` は `{ts,tsx}` の波括弧をサポートします。マッチしない場合は、余分な空白を
確認してください——`{ts, tsx}` のように空白があると、`tsx` に静かにマッチしなくなります。
## レビュー
### あるファイルにコメントが 0 件——本当にレビューされたのか？
[セッションビューア](../viewer/)（`ocr viewer`）を開き、セッションを見つけ、そのファイルの
`main_task` レーンを確認してください。
- ツール呼び出しあり + `task_done` で終了 → クリーンなレビュー。
- ツール呼び出しあり + ループ途中で終了 → エラーカードを探してください。
- `main_task` カードが全くない → ファイルはレビュー前にフィルタされました。上記の[フィルタリングとルール](#filtering--rules)を参照してください。
### コメントの `start_line: 0` と `end_line: 0`
OCR はコメントを diff 内の正確な行にアンカーできませんでした。よくある原因は 2 つです。
- モデルが `existing_code` を diff からそのままコピーせず、書き換えてしまった。モデルには
そうしないよう指示されていますが、時々起きます。
- diff のフォーマットが異常（CRLF、tab/空白の混在）で、スライディングウィンドウのマッチングが
壊れた。
コメント自体は本物です——ただ自動的に配置されなかっただけです。ほとんどのエージェント統合
（SKILL、Claude Code plugin）は `existing_code` フィールドを読み、ファイル内で自ら位置を特定します。
### Token threshold exceeded
```
[ocr] WARNING: prompt tokens (94000) exceed 80% of max_tokens(58888) for src/big.sql
```
そのファイルの初期 prompt（ルール + diff + change-files リスト）が、モデルが応答できる前に
すでに `MAX_TOKENS = 58888` の 80 % を超えました。OCR はそのファイルをスキップして続行します——
JSON モードでは `warnings` にも表示されます。
緩和策:
- 自動生成されたものなら、ファイルを `exclude` リストに追加してください。
- 大きなリファクタリングをより小さな commit に分割してください。
- 一連の小さな commit に対しては、一括のワークスペースモードではなく `--commit` モードで
レビューしてください。
### ファイルが小さいのに plan フェーズに時間がかかる
まず `ocr review --preview` を実行してください。ファイルの `lines.changed` が
`PLAN_MODE_LINE_THRESHOLD`（デフォルト **50**）を超えると、plan フェーズが実行されます。これは
意図的なものです——大きな diff は plan の恩恵を受けます。単一のレビューでスキップするには、
より小さな diff で実行するか、埋め込みテンプレートを一時的に編集してください（上級者向け。
`--tools` の上書きが必要）。
### "Max tool requests reached"
```
[ocr] Max tool requests reached for src/foo.go.
```
モデルが 30（`MAX_TOOL_REQUEST_TIMES`）回のツール呼び出しを費やしたのに `task_done` を
呼びませんでした。その時点までに発せられたコメントは、依然として収集されレンダリングされます。
ほとんどのファイルでこうなる場合、原因は通常次のとおりです。
- モデルが「完了したら `task_done` を呼べ」という指示に従うのが苦手。より強力なモデル
（Claude Opus など）に切り替えてください。
- あるツールがエラーを出し続け、モデルがリトライし続けている。セッション JSONL を確認してください——
同じツール結果が繰り返されていれば、それが原因です。
- ファイルが本当に大きい、あるいはコンテキストが重く、30 回では足りない。`--max-tools <n>` で
上げるか下げるか調整してください（例: `--max-tools 40` でより多く、`--max-tools 15` でより少なく）。
1〜9 は 10 に引き上げられます。`0`（デフォルト）はテンプレートのデフォルト 30 を使います。
### 一部のサブエージェントが失敗しても、実行は 0 で終了する
意図的なものです。OCR はファイルごとの失敗を隔離し、1 つの問題のあるファイルが 20 ファイルの
レビュー全体を巻き込まないようにします。成功したものが*1 つでもあれば*、集計終了コードは `0` です。
完全に失敗した場合（成功したサブエージェントがゼロ）のみ非ゼロで終了します。どのファイルが
失敗したかは、JSON モードの `warnings` 配列またはテキストモードの stderr を確認してください。
### CI での実行がローカルよりずっと遅い
よくある原因は 2 つです。
- **モデルのレート制限**——制限がかかると、LLM client はバックオフしてリトライします。最初から
制限に触れないよう、`--concurrency` を下げてください（`4` など）。
- **コールドキャッシュ**——プロバイダーが prompt キャッシュをサポートしている場合、デプロイ後の
初回実行は恩恵を受けられません。同じウィンドウ内の後続実行はより高速になります。
## 出力と統合
### `--audience agent` でも進捗行が出る
見ているのが **stderr** でないことを確認してください。進捗メッセージは時々 stderr に出ます
（警告、エラー）。`--audience agent` が保証するクリーンな stdout は*パーサーに優しい*ものです——
すべてを遮断するにはリダイレクトしてください: `ocr review --audience agent 2>/dev/null`。
### JSON 出力が `{ "files_reviewed": 0, "comments": [] }`
ワークスペースに対象ファイルがありません。これは意図的なものです——明示的な形により、呼び出し側は
「レビュー対象がない」ことと「レビューしたファイルに指摘がない」ことを区別できます。コメントが
ゼロの正常なレビューは、通常の空配列 `[]` を返します。
### セッション JSONL はどこにある？
```
~/.opencodereview/sessions/<path-encoded-repo-path>/<session-id>.jsonl
```
リポジトリパスは、`/` と `\` を `-` に、`:` を `_` に置き換えてエンコードされます
（例: `/Users/foo/my-repo` → `Users-foo-my-repo`）。`ocr viewer` でセッションを閲覧できます。
このディレクトリを削除すると履歴が消えます。OCR は次回実行時にエンコード済みパスを再生成します。
## パフォーマンスとコスト
### どの token にどれだけ費やしたかを知るには？
テレメトリを有効にします。
```bash
ocr config set telemetry.enabled true
ocr config set telemetry.exporter console
ocr review
```
LLM 呼び出しには独自の span がありません——metric として記録されます。`ocr.llm.tokens_used`
（counter、`model` + `type` でラベル付け）、`ocr.llm.requests_total`（counter、`model`
+ `status` でラベル付け）、`ocr.llm.request_duration_seconds`（histogram、`model` でラベル付け）に
注目してください。console exporter はこれらの集計をインラインで出力します。ダッシュボードが必要な場合は、
OTLP exporter に切り替えて metrics 基盤に送ってください——[テレメトリ](../telemetry/)を参照。
### なぜ私のレビューはこんなに高価なのか？
よくある要因:
- ファイルが 50 行以上のとき plan フェーズが起動します。これはファイルごとに LLM 呼び出しを
1 回追加します。閾値を下げるとコストを削減でき、上げると小さな PR の速度を向上できます。
- `MAX_TOOL_REQUEST_TIMES = 30` はかなり緩やかです。ラウンドを使い切るモデルは、3 ラウンドで
終わるモデルより長い（トークンの多い）対話を生みます。より強力なモデルはより速く終える傾向が
あります。逆に、"max tool requests reached" に対処するため `--max-tools` を上げると、ファイルごとの
コストはおおむね線形に増加すると考えてください。
- メモリ圧縮それ自体が 1 回の LLM 呼び出しです。長いサブタスクは、レビューのラウンドに加えて、
圧縮のラウンド分も支払うことになります。
### LLM 呼び出しを減らすには？
- `include` リストを追加して、OCR が気にしないファイルをレビューしないようにします。
- アカウントに burst-mode の課金がある場合は、`--concurrency` を下げます。
- `--background` を渡します——十分な事前コンテキストがあれば、モデルが `file_read` /
`code_search` の往復なしに完了できることがあります。
## プライバシーとセキュリティ
### OCR は私のコードをどこかに送るのか？
OCR はあなたの **diff**（および任意の read-tool スニペット）を、設定した LLM エンドポイントに送ります。
それ以外のものは一切あなたのマシンから出ません——セッション JSONL とルールファイルはローカルにのみ
存在します。
テレメトリを有効にしている場合、`content_logging` フラグは設定レイヤーに接続されていますが、
現時点ではどのコードパスも**制御しません**——このフラグの値にかかわらず、prompt と応答の内容が
collector にエクスポートされることは決してありません。予約項目とみなしてください。本番環境では
`false` のままにしてください。詳細は[テレメトリ](../telemetry/#content-logging)を参照してください。
### LLM に送る前に secret をマスクできるか？
組み込み機能ではありません。推奨のワークフロー:
1. secret をリポジトリにコミットしない（一般的なルール）。
2. 機密情報を含むと分かっているファイルを `exclude` に追加する。
3. `git diff --no-textconv` フィルターまたは pre-commit でマスクし、secret が diff に入らないようにする。
「マスクルール」機能はロードマップにあります。
[issue トラッカー](https://github.com/alibaba/open-code-review/issues)をご覧ください。
## その他
### changelog はどこにある？
[GitHub Releases](https://github.com/alibaba/open-code-review/releases)
——各 release には Conventional Commits から生成された notes が付属しています。
### OCR は Git 以外の VCS をサポートするか？
しません。diff provider は shell 経由で `git` を呼び出します。SVN / Mercurial などには新しい
provider が必要です。Hg サポートの issue は[こちら](https://github.com/alibaba/open-code-review/issues)で
オープンになっています。
### なぜバイナリは `opencodereview` なのに CLI は `ocr` なのか？
release で配布される静的バイナリはプロジェクト名（`opencodereview`）を持ちます。NPM wrapper は
使いやすさのため `ocr` としてインストールされます。ソースからビルドすると `dist/opencodereview` が
得られます——`$PATH` 上の `ocr` としてコピーしてください。
### アンインストールするには？
```bash
npm uninstall -g @alibaba-group/open-code-review # NPM install
sudo rm /usr/local/bin/ocr # binary install
rm -rf ~/.opencodereview # all state
```
OCR は `~/.opencodereview` の外には書き込みません（NPM がダウンロードするバイナリを除く）。
したがってこのディレクトリを削除すれば、履歴、設定、ユーザーごとのルールが消去されます。
## 関連項目
- [設定](../configuration/)——LLM エンドポイント解決と config key。
- [レビュールール](../review-rules/)——ファイルフィルターとルール解決チェーン。
- [セッションビューア](../viewer/)——過去のレビューセッションを表示する。
- [テレメトリ](../telemetry/)——token 使用量と LLM メトリクス。

177
pages/src/content/docs/ja/installation.md Normal file
View file

@ -0,0 +1,177 @@
---
title: インストール
sidebar:
order: 4
---
`ocr` CLI をインストールするには、サポートされた 4 つの方法があります。いずれも生成されるのは同じバイナリなので、
環境に合わせて選んでください。
## NPM（推奨）
```bash
npm install -g @alibaba-group/open-code-review
```
NPM パッケージには、小さな wrapper スクリプト（`bin/ocr.js`）と
[postinstall hook](https://github.com/alibaba/open-code-review/blob/main/scripts/install.js)
が付属しており、以下を行います。
1. お使いのプラットフォームを検出します（`darwin-amd64`、`darwin-arm64`、`linux-amd64`、
`linux-arm64`、`windows-amd64`、`windows-arm64`）。
2. GitHub Releases から一致するバイナリをダウンロードします。
3. （チェックサムデータが存在する場合は）検証し、wrapper の隣に配置します。
プラットフォーム固有の npm パッケージ（例：`@alibaba-group/ocr-darwin-arm64`）が
optional dependency としてインストールされている場合は、そのバイナリを直接使用し、ダウンロードをスキップします。
`ocr` を実行すると、wrapper はダウンロード済みのバイナリを単に `exec` するだけなので、初回実行後の実際のオーバーヘッド
はゼロです。
### 更新
```bash
npm update -g @alibaba-group/open-code-review
# または特定のバージョンに固定：
npm install -g @alibaba-group/open-code-review@<version>
```
### アンインストール
```bash
npm uninstall -g @alibaba-group/open-code-review
```
## GitHub Release バイナリ
Node.js をインストールしたくない場合は、
[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 (AMD64)
curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-amd64.exe
# Windows (ARM64)
curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-arm64.exe
```
各 release では、バイナリの隣に `sha256sum.txt` も公開されており、完全性を検証できます。
```bash
curl -LO https://github.com/alibaba/open-code-review/releases/latest/download/sha256sum.txt
shasum -a 256 -c sha256sum.txt --ignore-missing
```
## インストールスクリプト（curl | sh）
GitHub Release バイナリのダウンロード（検証付き）をラップした便利なインストーラーです——CI のベース
イメージやヘッドレス環境に適しています。
```bash
curl -fsSL https://raw.githubusercontent.com/alibaba/open-code-review/main/install.sh | sh
```
2 つの環境変数を認識します。
| 変数 | デフォルト値 | 用途 |
|---|---|---|
| `OCR_INSTALL_DIR` | `/usr/local/bin` | `ocr` バイナリを配置する場所。 |
| `OCR_VERSION` | 最新 release | 特定の release tag に固定します（例：`v1.2.3`）。 |
このスクリプトは `darwin` と `linux` の `amd64` / `arm64` をサポートします。Windows では
[GitHub Release バイナリ](#github-release-binary) または [NPM](#npm-recommended)
の方法を使用してください。
## ソースからビルドする
OCR 自体を変更する場合、またはプリコンパイル済みバイナリのないプラットフォームで実行する場合にのみ、この方法が必要です。
### 前提条件
- [Go ≥ 1.25](https://go.dev/dl/)
- [Git](https://git-scm.com/)
- [Make](https://www.gnu.org/software/make/)
### ビルド
```bash
git clone https://github.com/alibaba/open-code-review.git
cd open-code-review
make build # dist/opencodereview を生成
sudo cp dist/opencodereview /usr/local/bin/ocr
```
### 他のプラットフォーム向けにビルドする
```bash
make build-linux-amd64
make build-linux-arm64
make build-darwin-amd64
make build-darwin-arm64
make build-windows-amd64 # Windows (x86_64)
make build-windows-arm64 # Windows (ARM64)
make build-all # 6 つすべてを一括ビルド
make sha256sum # sha256sum.txt も生成
```
`make dist` は `clean → build-all → sha256sum` を実行し、バイナリの隣に
`VERSION` ファイルを書き込みます——これはまさに release パイプラインが実行するステップです。
### テストの実行
```bash
make test # LC_ALL=C go test -v -race -count=1 ./...
```
## インストールの検証
バイナリがどこから来たものであっても：
```bash
ocr version # バージョン + git commit + ビルド日時を出力
ocr --help # トップレベルの使い方
ocr review --help # review コマンドの完全な引数リスト
```
"command not found" エラーが出る場合は、インストール先が `$PATH` 上にあることを確認してください。
```bash
which ocr
echo $PATH
```
## OCR が状態を保存する場所
| パス | 保存内容 |
|---|---|
| `~/.opencodereview/config.json` | LLM エンドポイント、言語、テレメトリ設定（`ocr config set` で管理）。 |
| `~/.opencodereview/rule.json` | オプションのグローバルレビュールール。 |
| `~/.opencodereview/sessions/<encoded-repo-path>/<session-id>.jsonl` | レビューセッションごとのストリーミング JSONL トランスクリプト。`ocr viewer` で使用します。 |
| `~/.opencodereview/{last-update-check,update.lock,update-available}` | NPM wrapper のバックグラウンド更新チェックの状態。wrapper はより新しい release があるかをポーリングし（デフォルトで約 18 分ごと）、アップグレードの案内を表示します。`OCR_NO_UPDATE=1` で無効化するか、`OCR_UPDATE_INTERVAL`（秒）で間隔を調整します。静的バイナリはこれらのファイルを書き込みません。 |
| `<repo>/.opencodereview/rule.json` | オプションのプロジェクトレベルのレビュールール——安全にコミットできます。 |
OCR は `~/.opencodereview/` の外に書き込むことは決してありません（NPM が一時的にバイナリをダウンロードする場合を除く）。
このディレクトリを削除すれば、クリーンなアンインストールが完了します。
## 関連項目
- [クイックスタート](../quickstart/)——LLM を設定して初回のレビューを完了します。
- [設定](../configuration/)——OCR が受け入れる各環境変数と config key。
- [コントリビュート](../contributing/)——ソースからビルドし、テストを実行して開発に参加します。

60
pages/src/content/docs/ja/integrations.md Normal file
View file

@ -0,0 +1,60 @@
---
title: 統合
sidebar:
order: 12
---
OCR は CLI であり、プロセスを派生できるあらゆる環境と組み合わせられます。本セクションでは、
エージェント型ワークフローや CI に組み込むための主要な方法を、統合方式ごとに 1 ページずつ扱います。
## なぜこれらの統合なのか？
OCR の `--audience agent` モードは、別のエージェントから駆動されることを前提に設計されています。
stdout には JSON / 最終サマリーのみが流れ、進捗 UI はありません。これにより、次の 3 つの組み合わせ方が
自然に成り立ちます。
1. **Agent skill**——呼び出し側のエージェントが呼べる skill として OCR を登録します（Anthropic
Agent SDK など）。
2. **Command（Claude Code plugin）**——パッケージ化されたコマンドをインストールし、
`/open-code-review:review` で `ocr review` をエンドツーエンドに実行します。Claude-Code スタイルの
コマンド規約をサポートする他のエージェントでも利用できます。
3. **Direct subprocess**——`subprocess.run` を呼べるあらゆるフレームワーク（LangChain ツール、
カスタムシェル、CI ステップ）から直接 shell 経由で呼び出します。
これらは組み合わせて使えます。skill も plugin も、最終的には同じバイナリを呼び出します。
## モードを選ぶ
| 方式 | 最適なケース | ページ |
|---|---|---|
| Agent skill | Anthropic Agent SDK、または `SKILL.md` を消費する他のフレームワーク上で構築している。 | [Agent Skill](agent-skill/) |
| Command（Claude Code plugin） | Claude Code（または Claude-Code スタイルのコマンド規約を持つ任意のエージェント）を使っていて、`/open-code-review:review` に正しい動作をさせたい。 | [Command（Claude Code Plugin）](claude-code/) |
| Direct subprocess | カスタムスクリプト、LangChain ツール、あるいは Anthropic 以外のエージェントから OCR を呼び出す必要がある。 | [Direct Subprocess](subprocess/) |
| CI/CD | すべての PR や pre-commit のたびに OCR を実行したい。 | [CI/CD](ci/) |
## MCP はどうなのか？
OCR は現在、Model Context Protocol server を公開していません。想定している統合方式は
「エージェントが CLI を呼び出す」というもので、よりシンプルであり、MCP server が持ち込む
長時間稼働プロセスの問題を避けられます。エージェントプラットフォームがどうしても MCP を
必要とする場合は、CLI を薄い shim でラップしてください。単一の `review` ツールを公開する
30 行程度の Node スクリプトで十分です。
## すべてのモードに共通するヒント
- **呼び出し側が人間でない場合は、常に `--audience agent` を渡してください。** そうしないと、
進捗行が解析対象の出力を汚染します。
- **PR / 要件のコンテキストがある場合は、常に `--background` を渡してください。** 品質が大きく
向上し、コストはツール引数 1 つ分にすぎません。
- **CI では `--concurrency` を低めに設定してください**（`--concurrency 4`）。プロバイダーの
レート制限に触れないようにするためです。デフォルトは 8 です。
- **CI では `--commit HEAD` よりも `--from origin/main --to HEAD` を優先してください。**
merge-base 計算により、ブランチを切った後に `main` に取り込まれた無関係な変更を除外できます。
- **`OCR_LLM_TOKEN` を stdout/logs から遠ざけてください。** OCR はこれを出力しませんが、
設定を誤った shell が漏らす可能性があります。CI の secret マスクを使ってください。
## 関連項目
- [CLI リファレンス](../cli-reference/)——review コマンドの各引数。
- [設定](../configuration/)——環境変数と config key。
- [クイックスタート](../quickstart/)——初回レビューのための最小構成。

85
pages/src/content/docs/ja/integrations/agent-skill.md Normal file
View file

@ -0,0 +1,85 @@
---
title: Agent Skill
sidebar:
order: 1
---
OCR を呼び出し可能な skill として登録することで、agent フレームワークが正しい引数、事前チェック、分類基準を用いて OCR を呼び出せるようになります。呼び出し側でこれらを改めて導き出す必要はありません。
## リポジトリに含まれるもの
リポジトリには
[`skills/open-code-review/SKILL.md`](https://github.com/alibaba/open-code-review/blob/main/skills/open-code-review/SKILL.md)
に SKILL マニフェストが用意されています。これは OCR を呼び出し可能な skill として宣言し、事前チェック、呼び出しワークフロー、コメントの分類基準（High/Medium/Low）を含みます。
## インストール
### 方法 1：`npx skills add`（推奨）
skill を使いたいプロジェクト内で実行します。
```bash
npx skills add alibaba/open-code-review --skill open-code-review
```
これは
[skills registry](https://github.com/alibaba/open-code-review/blob/main/skills/open-code-review/SKILL.md)
からマニフェストを取得してプロジェクトに配置し、skills の規約を尊重するコーディング agent が次回の呼び出し時にそれをロードするようにします。skill を最新版に更新するには、このコマンドを再実行してください。
> **前提条件：** 初回実行時、バイナリが `PATH` 上に存在しない場合、skill は
> （`npm install -g @alibaba-group/open-code-review` を通じて）`ocr` CLI を自動的にインストールします——[skill が行うこと](#what-the-skill-does)を参照してください。ただし、LLM は事前に設定しておく**必要があります**。skill が代わりに行うことはできず、処理を止めて尋ねます。[設定](../../configuration/)を参照してください。
### 方法 2：手動コピー（システムレベル）
プロジェクトごとではなくグローバルに skill をインストールしたい場合は、フォルダを skills ディレクトリにコピーします。
```bash
mkdir -p ~/.claude/skills
cp -R /path/to/open-code-review/skills/open-code-review ~/.claude/skills/
```
これにより、マシン上のすべてのプロジェクトで skill が利用可能になります。
## skill が行うこと
SKILL.md は一つの prompt です。呼び出し側の agent がそれをロードすると、agent 自身が手順を実行します。完全な `/open-code-review`（または同等）のリクエストは、次のように展開されます。
1. **事前チェック。** `which ocr` を実行して CLI が `PATH` 上にあることを確認し、続いて `ocr llm test` で LLM に到達可能であることを確認します。
2. **CLI が無ければ自動インストール。** `which ocr` が "NOT INSTALLED" を報告した場合、agent は `npm install -g @alibaba-group/open-code-review` を実行して続行します。ユーザーへの確認は行いません——これは通常のセットアップ手順とみなされます。
3. **LLM 設定が無ければ止めて尋ねる。** `ocr llm test` が失敗した場合、agent は認証情報を*でっち上げません*。サポートされている 2 つの方法（環境変数または `ocr config set …`）をユーザーに提示し、API key の提供を待ちます。
4. **業務コンテキストの抽出。** レビュー対象（commit、ブランチ、作業コピー）を確認し、短い `--background` 文字列を生成します。
5. **レビューの実行。**
`ocr review --audience agent --background "…" [--commit | --from/--to]`
を呼び出します。ユーザーが作業コピー、特定の commit、ブランチ区間のいずれをレビューしたいかに応じて引数を選択します。
6. **分類とレポート。** SKILL.md の基準を用いて JSON コメントを **High** /
**Medium** / **Low** に分類し（bug とセキュリティ問題は High、些細な指摘や誤検知と疑われるものは黙って破棄）、Markdown 形式のサマリーをレンダリングします。
7. **必要に応じて修正。** ユーザーが「レビュー**して**修正して」（または類似）と指示した場合、High/Medium 項目に対して安全な修正をインラインで適用します。そうでない場合はコードを変更する前に尋ねます。
完全な prompt——正確な分類基準、出力テンプレート、注意事項を含む——は
[`skills/open-code-review/SKILL.md`](https://github.com/alibaba/open-code-review/blob/main/skills/open-code-review/SKILL.md)
にあります。上記のいずれかを厳しくしたい場合（例えばデフォルトの動作を、修正前に常に尋ねるように変更するなど）は、ローカルのコピーを編集してください。
## Anthropic Agent SDK
SDK の init をインストール済みの skill パスに向けます。
```python
from anthropic_agent_sdk import Agent
agent = Agent(
skill_paths=["/path/to/open-code-review/skills/open-code-review"],
)
agent.run("Review my staged changes — focus on race conditions.")
```
SDK は SKILL.md prompt をロードし、agent が[skill が行うこと](#what-the-skill-does)で述べられているワークフローを実行します——`npm install` のフォールバックや、LLM 設定が無いときに認証情報の入力を促す手順を含みます。
## その他の agent フレームワーク
「外部 skill を登録する」インターフェースを持つフレームワークであれば、SKILL.md を取り込めます——それは frontmatter 付きの markdown に過ぎません。フレームワークが異なるスキーマを期待する場合でも、markdown 本文は prompt テンプレートとして利用できます。
## 関連項目
- [Command（Claude Code Plugin）](../claude-code/)——同じ skill の slash-command 版。
- [Direct Subprocess](../subprocess/)——マニフェストを介さず、自分で CLI を呼び出す方法。

366
pages/src/content/docs/ja/integrations/ci.md Normal file
View file

@ -0,0 +1,366 @@
---
title: CI/CD
sidebar:
order: 4
---
すべての Pull Request または Merge Request で OCR を実行します。上流リポジトリは、コピーして設定するだけのすぐ使える 2 つのパイプラインを提供しています——1 つは GitHub Actions、もう 1 つは GitLab CI です。どちらも
[Direct Subprocess](../subprocess/)にある中核コマンドの薄いラッパーです。
## CI/CD 統合の仕組み
本ページの各レシピは同じパターンに従います——以下の GitHub Actions と GitLab CI のセクションは、その具体的な実装に過ぎません。
1. **PR / MR イベントでトリガー。** 新しい pull request、更新された merge request、または手動の
`/open-code-review` コメントがジョブをトリガーします。
2. **runner に `ocr` をインストール**します。通常は
`npm install -g @alibaba-group/open-code-review` です。runner は一時的なため、これは実行のたびに発生します。
3. **CI secret から `ocr config set` 経由で LLM を設定**します（エンドポイント、token、model）。フォールバックできる永続的な `~/.opencodereview` はありません。
4. **区間モードでレビューを実行**し、機械可読な出力を得ることで、stdout がクリーンな JSON の外殻になるようにします。
```bash
ocr review \
--from "origin/<base-branch>" \
--to "origin/<head-branch>" \
--format json \
--audience agent
```
`--format json` は解析可能なペイロードを提供し、`--audience agent` は進捗行を抑制します。各レシピが消費する外殻は [JSON の構造](../subprocess/#json-shape)を参照してください。
5. **JSON を解析**し、`comments[]` を反復処理します。
6. **プロバイダーの review API を通じてコメントを PR / MR に貼り戻します。** 有効な行情報を持たない項目（ファイルレベルの発見）はインラインで貼り付けるのではなくサマリーの注記にまとめられます。インラインの一括 API がリクエストを拒否した場合、貼り付け手順も通常のサマリーコメントにフォールバックします。
常に 2 種類の認証情報が関わります。OCR が発見を生成するために使う **LLM 認証情報**と、貼り付け手順がコメントを貼り戻すために使う **PR/MR 書き込み token** です。GitHub のレシピは `GITHUB_TOKEN` を通じて後者を自動的に提供します。GitLab では `GITLAB_API_TOKEN` を明示的に設定することを推奨しますが、fork MR に対しては組み込みの `CI_JOB_TOKEN` にフォールバックします（これは `/discussions` を通じてディスカッションを開始できます）——信頼性のためには専用の token の使用を推奨します。
## GitHub Actions
上流のワークフローは
[`examples/github_actions/ocr-review.yml`](https://github.com/alibaba/open-code-review/blob/main/examples/github_actions/ocr-review.yml)
にあります。
### 何をするか
- `pull_request_target`（`opened`）**および** `issue_comment` イベント（本文が
`/open-code-review` または `@open-code-review` で始まるもの）でトリガーします。後者はレビュアーが PR にコメントすることで OCR をオンデマンドで再実行できるようにします。（`pull_request` ではなく `pull_request_target` を使うことで、fork から提出された PR でも secret を利用できます。OCR は diff を読むだけで、PR 内のコードは実行しません。）
- `npm install -g @alibaba-group/open-code-review` で OCR をインストールし、`ocr config set` で設定を書き込み、ブランチ区間モードで中核コマンドを実行します。
- JSON の外殻を解析し、GitHub Pull Request Review API を通じて各発見をインラインのレビューコメントとして貼り付けます。行情報を持たないコメントはサマリー本文にまとめられます。一括送信が失敗した場合は 1 件ずつの貼り付けにフォールバックし、統計をサマリーコメントに表示します。
### インストール
ワークフローをリポジトリに配置します。
```bash
mkdir -p .github/workflows
curl -o .github/workflows/ocr-review.yml \
https://raw.githubusercontent.com/alibaba/open-code-review/main/examples/github_actions/ocr-review.yml
```
### 必須の secret
**Settings → Secrets and variables → Actions** で設定します。
| Secret | 必須 | 説明 |
|---|---|---|
| `OCR_LLM_URL` | はい | LLM API エンドポイント（例：`https://api.openai.com/v1/chat/completions`）。 |
| `OCR_LLM_AUTH_TOKEN` | はい | LLM API の認証 token。この CI secret は `ocr config set llm.auth_token` に渡されます。（OCR の直接の環境変数は `OCR_LLM_TOKEN` であり、`OCR_LLM_AUTH_TOKEN` ではありません。） |
| `OCR_LLM_MODEL` | いいえ | モデル名。デフォルトはありません——明示的に設定する必要があります。 |
| `OCR_LLM_USE_ANTHROPIC` | いいえ | Anthropic Claude モデルの場合は `true` に設定します。 |
`GITHUB_TOKEN` は自動的に提供されます。ワークフローはレビューコメントを貼り付けるために `pull-requests: write` を宣言しています。
> ワークフロー起動時には
> `ocr config set llm.extra_body '{"thinking": {"type": "disabled"}}'`
> も実行され、このフィールドをサポートしない LLM プロバイダー向けに thinking-mode リクエストをオフにします。プロバイダーが thinking-mode を維持する必要がある場合は、その行を削除してください。
### カスタマイズ
以下はすべて、あなたがコピーしたばかりのワークフローファイル
（`.github/workflows/ocr-review.yml`）への編集です。
#### 背景コンテキスト
`--background` は最も効果の大きい単一の引数です——[すべてのモードに適用されるヒント](../#tips-that-apply-to-every-pattern)を参照してください。PR タイトルを渡します（タイトルが `feat(auth): add OAuth2 support` のようなセマンティックな規約に従っている場合、より効果的です）。
```yaml
- name: Run OCR review
run: |
ocr review \
--background "${{ github.event.pull_request.title }}" \
--from "origin/${{ github.base_ref }}" \
--to "origin/${{ github.head_ref }}" \
--format json --audience agent
```
#### カスタムルール
`--rule` でプロジェクト固有のルールファイルを渡します。
```yaml
- name: Run OCR review
run: |
ocr review --rule ./my-rules.json \
--from "origin/${{ github.base_ref }}" \
--to "origin/${{ github.head_ref }}"
```
スキーマは[レビュールール](../../review-rules/)を参照してください。
#### 並行数
デフォルトはファイルごとに 8 つの並行サブ agent です。大きな PR では、LLM プロバイダーのレート制限に抵触しないよう下げてください。
```yaml
- name: Run OCR review
run: |
ocr review --concurrency 5 \
--from "origin/${{ github.base_ref }}" \
--to "origin/${{ github.head_ref }}"
```
#### トリガーモード
デフォルトのワークフローは、PR が **opened** されたとき、および `/open-code-review` または
`@open-code-review` で始まる PR コメントのときにトリガーします。よくある 2 つの調整があります。
より多くの PR ライフサイクルイベントで実行する（例：新しい commit がプッシュされたときに再レビュー）：
```yaml
on:
pull_request:
types: [opened, synchronize, reopened, ready_for_review]
```
異なるコメントキーワードを使う：
```yaml
if: |
github.event_name == 'pull_request' ||
(github.event_name == 'issue_comment'
&& github.event.issue.pull_request
&& startsWith(github.event.comment.body, '/review'))
```
`github.event.issue.pull_request` のチェックは、コメントが通常の issue ではなく PR 上のものであることを保証します。
#### OCR のバージョン固定
デフォルトのワークフローは最新のリリース版をインストールします。固定するには：
```yaml
- name: Install OpenCodeReview
run: npm install -g @alibaba-group/open-code-review@1.0.0
```
#### GitHub App として投稿する
デフォルトではレビューコメントは `github-actions[bot]` から投稿されます。`OpenCodeReview Bot` のようなカスタムブランドの bot として投稿するには、`GITHUB_TOKEN` を GitHub App の installation token に置き換えます。
1. *Settings → Developer settings → GitHub Apps → New GitHub App* で **app を作成**します。webhook は無効にします（このユースケースでは不要）。*Repository permissions* で次を付与します。
- **Pull requests**：Read and write
- **Contents**：Read-only（diff の取得用）
- **Metadata**：Read-only（必須）
2. app 設定ページから**秘密鍵を生成**し、`.pem` ファイルをダウンロードします。同じページの **App ID** を控えておきます。
3. app を OCR にレビューさせたいリポジトリに**インストール**します。Installation ID はインストール後の URL に現れます。例：`https://github.com/settings/installations/12345` → ID は `12345`。
4. *Settings → Secrets and variables → Actions* で**3 つの secret を追加**します。
| Secret | 値 |
|---|---|
| `GITHUB_APP_ID` | App ID。 |
| `GITHUB_APP_PRIVATE_KEY` | `.pem` ファイルの全内容。`-----BEGIN RSA PRIVATE KEY-----` と `-----END RSA PRIVATE KEY-----` の行を含みます。 |
| `GITHUB_APP_INSTALLATION_ID` | Installation ID。 |
5. コメント貼り付け手順で **token を生成して使用**します。
```yaml
- name: Get GitHub App Token
id: app-token
uses: actions/create-github-app-token@v1
with:
app-id: ${{ secrets.GITHUB_APP_ID }}
private-key: ${{ secrets.GITHUB_APP_PRIVATE_KEY }}
- name: Post review comments to PR
uses: actions/github-script@v7
with:
github-token: ${{ steps.app-token.outputs.token }}
script: |
# ...existing post script...
```
レビューは `github-actions[bot]` ではなく、あなたの app の名前で投稿されるようになります。
### トラブルシューティング
| 症状 | 原因 / 修正 |
|---|---|
| `Cannot find merge-base` | checkout 手順が浅いクローンを使っていますが、区間モードのレビューには完全な履歴が必要です。上流のワークフローは `actions/checkout` に `fetch-depth: 0` を設定しています——ファイルを編集する際はこの設定を保持してください。 |
| `Failed to parse OCR output` | `OCR_LLM_URL` または `OCR_LLM_AUTH_TOKEN` が欠落しているか誤っています。*Settings → Secrets and variables → Actions* で値を再確認してください。 |
| レビューコメントが誤った行に付く | 通常、レビュー開始からコメント貼り付けの間に diff がずれたことを意味します。貼り付けスクリプトはこの場合、通常の issue コメントにフォールバックします——対処は不要です。 |
> **注意。** `OCR_DEBUG` 環境変数は現在 OCR で**未実装**です——`OCR_DEBUG: "1"` を設定しても効果はありません。将来の対応に備えてここに記載しています。現時点で詳細な出力が必要な場合は、ワークフローが `/tmp/ocr-result.json` と `/tmp/ocr-stderr.log` に書き込む生のレビュー JSON と stderr を確認するか（下記のトラブルシューティングを参照）、ローカルで `ocr review` を実行してください。
## GitLab CI
上流のパイプラインは
[`examples/gitlab_ci/.gitlab-ci.yml`](https://github.com/alibaba/open-code-review/blob/main/examples/gitlab_ci/.gitlab-ci.yml)
にあります。
### 何をするか
- `merge_requests` イベント（作成、更新、再オープンといったすべての MR イベント）でトリガーします。
- `node:20` イメージで実行し、OCR をインストールし、`ocr config set` で設定し、MR diff モードで中核コマンドを実行します。
- インラインの Python スクリプトで JSON の外殻を解析し、各発見を GitLab Discussion として（diff 上にインラインで）投稿します。MR の `versions` エンドポイントを使って正しい `base_sha` / `start_sha` /
`head_sha` を計算し、正確に位置決めします。インラインで投稿できないコメントは通常の MR note にフォールバックし、最後にサマリー note で締めくくります。
### インストール
パイプラインをリポジトリのルートに配置します。
```bash
curl -o .gitlab-ci.yml \
https://raw.githubusercontent.com/alibaba/open-code-review/main/examples/gitlab_ci/.gitlab-ci.yml
```
すでに `.gitlab-ci.yml` があり、それを保持したい場合は、レシピを別のパスに配置して `include:`
で取り込みます。
```yaml
include:
- local: 'ci/ocr-review.gitlab-ci.yml'
```
### 必須の CI/CD 変数
**Settings → CI/CD → Variables** で設定します。
| 変数 | 必須 | マスク | 説明 |
|---|---|---|---|
| `OCR_LLM_URL` | はい | いいえ | LLM API エンドポイント URL。 |
| `OCR_LLM_AUTH_TOKEN` | はい | はい | API 認証 token。この CI 変数は `ocr config set llm.auth_token` に渡されます。（OCR の直接の環境変数は `OCR_LLM_TOKEN` であり、`OCR_LLM_AUTH_TOKEN` ではありません。） |
| `OCR_LLM_MODEL` | いいえ | いいえ | モデル名。デフォルトはありません——明示的に設定する必要があります。 |
| `GITLAB_API_TOKEN` | いいえ | はい | `api` scope を持つ project / personal / group access token。オプションです——欠落時は組み込みの `CI_JOB_TOKEN` にフォールバックします（fork MR など）。信頼性のためには専用の `GITLAB_API_TOKEN` を推奨します。 |
> GitLab は 8 文字未満の変数を拒否するため、パイプライン内で `llm.use_anthropic` は
> `false` にハードコードされています。Anthropic Claude モデルを使うには、スクリプトを直接編集してください。
> パイプライン起動時には
> `ocr config set llm.extra_body '{"thinking": {"type": "disabled"}}'`
> も実行され、このフィールドをサポートしない LLM プロバイダー向けに thinking-mode リクエストをオフにします。プロバイダーが thinking-mode を維持する必要がある場合は、その行を削除してください。
> **手軽な bot 命名のヒント。** Project Access Token と Group Access Token では、
> token の**名前**が MR ディスカッションの横に表示されます。token を `OpenCodeReview Bot` と命名すれば、追加設定なしでレビューディスカッションにブランド名を付けられます——[サービスアカウント名義で投稿する](#post-under-a-service-account-identity)に記載のより永続的なサービスアカウント設定が不要なときに便利です。
### カスタマイズ
以下はすべて、あなたがコピーしたばかりの `.gitlab-ci.yml` への編集です。
#### 背景コンテキスト
MR タイトルを `--background` に渡します——タイトルが `feat(auth): add OAuth2 support`
のようなセマンティックな規約に従っている場合、より効果的です。
```yaml
script:
- |
ocr review \
--background "$CI_MERGE_REQUEST_TITLE" \
--from "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME" \
--to "${CI_COMMIT_SHA}" \
--format json --audience agent
```
#### カスタムルールと並行数
GitHub Actions のレシピと同じ引数です——`--rule` でプロジェクト固有のルールファイルを渡し、
`--concurrency` で並行サブ agent を制限します（デフォルトは 8）。
```yaml
script:
- |
ocr review --rule ./my-rules.json --concurrency 5 \
--from "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME" \
--to "${CI_COMMIT_SHA}"
```
ルールのスキーマは[レビュールール](../../review-rules/)を参照してください。
#### OCR のバージョン固定
```yaml
script:
- npm install -g @alibaba-group/open-code-review@1.0.0
```
#### プッシュのたびの再レビューを避ける
`only: [merge_requests]` は **MR の更新のたびに**トリガーするため、長期にわたる MR では大量の LLM token を消費します。GitLab にはネイティブの「作成時のみ」イベントがないため、推奨されるパターンは、レビューを実行する前に既存の OCR note を検出し、あればスキップすることです。`ocr review` の呼び出しを Python wrapper に置き換えます。
```python
import json, os, sys, urllib.request
GITLAB_URL = os.environ.get("CI_SERVER_URL", "https://gitlab.com")
PROJECT_ID = os.environ["CI_PROJECT_ID"]
MR_IID = os.environ["CI_MERGE_REQUEST_IID"]
API_TOKEN = os.environ["GITLAB_API_TOKEN"]
url = (
f"{GITLAB_URL}/api/v4/projects/{PROJECT_ID}"
f"/merge_requests/{MR_IID}/notes?per_page=100"
)
req = urllib.request.Request(url, headers={"PRIVATE-TOKEN": API_TOKEN})
with urllib.request.urlopen(req) as resp:
notes = json.loads(resp.read().decode())
if any("OpenCodeReview" in n.get("body", "") for n in notes):
print("OCR already reviewed this MR. Skipping to save tokens.")
sys.exit(0)
# ...otherwise call `ocr review ...` as usual and write the JSON to
# the file the posting step expects.
```
この後に再レビューを強制するには、MR から以前の OCR note を削除してください——次のパイプライン実行では OCR note が見当たらなくなり、処理を続行します。
#### セルフホスト GitLab
コードの変更は不要です。貼り付けスクリプトは `CI_SERVER_URL`（GitLab が各 runner で自動的に設定します）を読むため、そのままで自分のインスタンスと通信できます。`GITLAB_API_TOKEN` が `gitlab.com` ではなく、あなたのセルフホストインスタンスによって発行されていることだけ確認してください。
#### サービスアカウント名義で投稿する
デフォルトではレビューディスカッションは `GITLAB_API_TOKEN` が属するユーザー名で表示されます。プロジェクトレベルのサービスアカウントに切り替えると、`OpenCodeReview Bot` のようなカスタムブランドの bot 名義が得られます。
1. *Project → Settings → Service Accounts → New service account* で**サービスアカウントを作成**します。選んだ名前（例：`OpenCodeReview Bot`）が MR ディスカッションの横に表示されます。
2. *Settings → Members → Invite member* で**プロジェクトに招待**します。サービスアカウント名を検索し、`Developer` または `Maintainer` を割り当てます——どちらもディスカッションの投稿に必要な権限を持ちます。
3. *Settings → Service Accounts →（該当アカウント）→ Add new token* で **access token を発行**します。必要な scope は `api` です。token はすぐにコピーしてください——GitLab は一度しか表示しません。
4. *Settings → CI/CD → Variables* で **token の値を置き換え**ます——既存の `GITLAB_API_TOKEN` の値をサービスアカウントの token で置き換えます（変数名は変えません）。
ディスカッションは、最初に token を作成したユーザー名ではなく、サービスアカウント名で投稿されるようになります。
### トラブルシューティング
| 症状 | 原因 / 修正 |
|---|---|
| `Cannot find merge-base` | runner が浅いクローンを使っています。上流のパイプラインは `GIT_DEPTH: 0` を設定して完全なクローンを強制します——ファイルを編集する際はこの設定を保持してください。 |
| 投稿時の `API error 403` | `GITLAB_API_TOKEN` に `api` scope が無い、プロジェクトのメンバーでない、または——セルフホストの場合——別のインスタンスによって発行されています。`api` scope で再発行し、*Settings → CI/CD → Variables* で再登録してください。 |
| `Failed to parse OCR output` | `OCR_LLM_URL` または `OCR_LLM_AUTH_TOKEN` が誤っています。*Settings → CI/CD → Variables* で値を再確認してください。 |
| インラインコメントが誤った行に付く | GitLab のインラインディスカッションは正確な SHA の一致を要求します。貼り付けスクリプトは `versions` メタデータを取得して正しい `base_sha` / `start_sha` / `head_sha` を得ます。それでも発見をアンカーできない場合は、通常の MR note にフォールバックします。 |
パイプラインは生のレビュー JSON を `/tmp/ocr-result.json` に、stderr を
`/tmp/ocr-stderr.log` に書き込みます。debug 手順でそれらを cat して、OCR が何を返したか確認できます。
```yaml
script:
- cat /tmp/ocr-result.json
- cat /tmp/ocr-stderr.log
```
## 関連項目
- [Direct Subprocess](../subprocess/)——2 つのパイプラインが消費する JSON の構造。ゼロから CI スクリプトを書くときに役立ちます。
- [設定](../../configuration/)——OCR が受け付けるすべての環境変数と config key。

87
pages/src/content/docs/ja/integrations/claude-code.md Normal file
View file

@ -0,0 +1,87 @@
---
title: Command（Claude Code Plugin）
sidebar:
order: 2
---
パッケージ化されたコマンドをインストールすることで、OCR を [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
内でエンドツーエンドに実行できます——diff をレビューし、発見を分類し、採用すべき修正を自動的に適用します。
## リポジトリに含まれるもの
リポジトリには
[`plugins/open-code-review/`](https://github.com/alibaba/open-code-review/tree/main/plugins/open-code-review)
配下に Claude Code plugin が用意されています。コマンドの prompt 本体は
[`plugins/open-code-review/commands/review.md`](https://github.com/alibaba/open-code-review/blob/main/plugins/open-code-review/commands/review.md)
にあり、以下で述べるワークフローの正式な拠り所です。
## インストール
### 方法 1：plugin marketplace（推奨）
**Claude Code 内で**次の 2 つのコマンドを実行します。
```bash
/plugin marketplace add alibaba/open-code-review
/plugin install open-code-review@open-code-review
```
これにより `/open-code-review:review` slash コマンドが登録され、`/plugin` を通じて更新可能な状態が保たれます。
### 方法 2：コマンドファイルを直接コピー
plugin marketplace をスキップしたい場合は、コマンドファイルを直接 `.claude/commands/` に配置します。これは `/open-code-review`（`:review` サフィックス無し）として登録されます。
**プロジェクトレベル**（リポジトリにコミットし、チームで共有）：
```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/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/commands/review.md
```
### コマンドをサポートするその他の agent
コマンドファイルは単一の frontmatter フィールドを持つ純粋な markdown です——Claude Code 固有の内容は一切含まれていません。あなたの agent が同様の **command** 規約（ディレクトリから呼び出し可能なコマンドとしてロードされる markdown prompt）をサポートしている場合、上記のファイルコピー方法がインストール経路になります。`open-code-review.md` を agent がコマンドを読み込むディレクトリに配置し、agent のコマンド呼び出し方法に従って呼び出してください。prompt 本文は agent に依存しません——モデルに対して、どの `ocr` 引数を選び、出力をどのように分類するかを伝えるだけです。
> **前提条件：** 初回実行時、バイナリが `PATH` 上に存在しない場合、コマンドは
> （`npm install -g @alibaba-group/open-code-review` を通じて）`ocr` CLI を自動的にインストールします。ただし、LLM は事前に設定しておく**必要があります**——`ocr llm test` が接続できない場合、コマンドは失敗します。[設定](../../configuration/)を参照してください。
## 使い方
Claude Code でコマンドを名前で呼び出します。plugin marketplace 経由でインストールした場合は `/open-code-review:review` を、ファイルを直接コピーした場合は `/open-code-review` を使います。
```
/open-code-review:review
/open-code-review:review review this PR against main
/open-code-review:review focus on race conditions in commit abc123
```
prompt はあなたのリクエストを解析し、正しい `ocr review` 引数を選択します。引数なし → 作業領域モード（staged + unstaged + untracked）、commit の言及 → `--commit`、ブランチ区間の言及 →
`--from` / `--to`。OCR の引数を直接透過的に渡すこともできます
（例：`/open-code-review:review --commit abc123` や `--from main --to feature`）。
## コマンドが行うこと
コマンドの prompt はとても短く、3 ステップです。
1. **レビューの実行。** あなたのリクエストから推論した引数を用いて `ocr review --audience agent`
を呼び出します（要件コンテキストが記述されている場合はオプションの `--background` を追加）。`ocr` バイナリが `PATH` 上に無い場合、コマンドは `npm i -g @alibaba-group/open-code-review` を通じて自動インストールして続行します。出力は 5 分のタイムアウト内で取得されます。
2. **フィルタリングと評価。** 各コメントを **High** / **Medium** / **Low** に分類します。低信頼度（誤検知の疑い、些細な指摘、コンテキスト不足）のコメントは黙って破棄され、その他は表示されます。
3. **修正。** 採用すべき High/Medium 項目に対して修正を自動的に適用します。
[Agent Skill](../agent-skill/) と異なり、このコマンドは**デフォルトで自動修正します**——「レビューして片付ける」ワークフローには適した選択であり、「diff を見せてほしい」ワークフローには向きません。
コマンドがコードを変更する前に尋ねるようにしたい場合や、分類基準を厳しくしたい場合は、ローカルの prompt コピーを編集してください。Claude Code は呼び出しのたびにコマンドを読み直すため、再起動は不要です。
## 関連項目
- [Agent Skill](../agent-skill/)——SDK レベルの同等物。同じ底層の CLI で、デフォルト値が異なります（修正前に尋ねる）。
- [Direct Subprocess](../subprocess/)——slash コマンドを介さず、自分で CLI を呼び出す方法。

155
pages/src/content/docs/ja/integrations/subprocess.md Normal file
View file

@ -0,0 +1,155 @@
---
title: Direct Subprocess
sidebar:
order: 3
---
shell を通じて `ocr` を呼び出し、JSON を解析します。これは最も低レベルの統合経路です——本サイトの他の方法はすべて最終的にこれに帰着します。[Agent Skill](../agent-skill/) と [Command](../claude-code/) の方法は、呼び出し側の agent にこの作業を行わせるための prompt テンプレートです。[CI/CD](../ci/) のレシピは、スクリプトから同じことを行う GitHub Actions と GitLab CI のパイプラインです——agent のオーケストレーションは関与せず、サブプロセス呼び出し、JSON 解析、コメントの PR / MR への貼り戻しのみです。カスタムスクリプト、LangChain ツール、その他まだカバーされていないフレームワークから OCR を呼び出す場合は、このページを直接使ってください。
## Bash
```bash
result=$(ocr review --format json --audience agent)
status=$(echo "$result" | jq -r '.status')
total=$(echo "$result" | jq '.comments | length')
echo "Status: $status — $total comments"
echo "$result" | jq -r '.comments[] | "\(.path):\(.start_line) — \(.content)"'
```
## Python
```python
import json, subprocess
proc = subprocess.run(
["ocr", "review", "--format", "json", "--audience", "agent",
"--from", "origin/main", "--to", "HEAD",
"--background", pr_description],
capture_output=True, text=True, check=True,
)
data = json.loads(proc.stdout)
for c in data["comments"]:
if c["start_line"] > 0:
post_line_comment(c["path"], c["start_line"], c["content"])
```
## JSON の構造
OCR は単一のトップレベル**オブジェクト**を出力します（裸の配列ではありません）。以下は、1 件の発見を含む完全な `success` の外殻です。
```json
{
"status": "success",
"summary": {
"files_reviewed": 1,
"comments": 1,
"total_tokens": 12770,
"input_tokens": 12450,
"output_tokens": 320,
"elapsed": "9s"
},
"comments": [
{
"path": "internal/cache/store.go",
"content": "Concurrent map access without a lock — wrap reads and writes with `sync.RWMutex` to avoid a race on the shared cache.",
"start_line": 42,
"end_line": 47,
"existing_code": "func (s *Store) Get(k string) string {\n return s.m[k]\n}",
"suggestion_code": "func (s *Store) Get(k string) string {\n s.mu.RLock()\n defer s.mu.RUnlock()\n return s.m[k]\n}",
"thinking": "The struct exposes `m map[string]string` without a guarding mutex, and Get/Set are called from concurrent request handlers."
}
]
}
```
### トップレベルのフィールド
| フィールド | 型 | 常に存在 | 説明 |
|---|---|---|---|
| `status` | string | はい | `success`、`completed_with_warnings`、`completed_with_errors`、`skipped` のいずれか。 |
| `message` | string | いいえ | 短い人間可読のサマリー。空の実行やスキップ時に設定されます（例：`"No comments generated. Looks good to me."`）。 |
| `summary` | object | いいえ | 実行の集計。完了した実行時に存在し、`skipped` 時は省略されます。フィールドは下記を参照。 |
| `comments` | array | はい | 空の場合があります。各コメントのスキーマは下記を参照。 |
| `warnings` | array | いいえ | 1 つ以上のサブ agent が失敗またはスキップされた場合にのみ存在します。スキーマは下記を参照。 |
### summary の構造（`summary`）
| フィールド | 型 | 説明 |
|---|---|---|
| `files_reviewed` | int | すべてのフィルタを通過し、モデルに送られたファイル数。 |
| `comments` | int | すべてのファイルにわたって出力されたコメントの総数（`comments.length` と一致）。 |
| `total_tokens` | int | 実行中の各 LLM 呼び出しの prompt + completion token の合計。 |
| `input_tokens` | int | 各 LLM 呼び出しの prompt token（キャッシュ読み取り token を含む）。 |
| `output_tokens` | int | 各 LLM 呼び出しの completion token（キャッシュ書き込み token を含む）。 |
| `cache_read_tokens` | int | 各 LLM 呼び出しのキャッシュ読み取り token の総数。ゼロの場合は省略されます（`omitempty`）。 |
| `cache_write_tokens` | int | 各 LLM 呼び出しのキャッシュ書き込み token の総数。ゼロの場合は省略されます（`omitempty`）。 |
| `elapsed` | string | 経過時間（実時間）。秒単位に丸められ、Go の `time.Duration.String()` によってフォーマットされます（例：`"1m12s"`）。 |
### 各コメントのフィールド（`comments[]`）
| フィールド | 型 | 常に存在 | 説明 |
|---|---|---|---|
| `path` | string | はい | リポジトリ相対のファイルパス。 |
| `content` | string | はい | レビューコメント（Markdown）。 |
| `start_line` | int | はい | 影響範囲の先頭行。値が `< 1` の場合、コメントに行アンカーが無いこと（ファイルレベル）を意味します——これらはインラインで貼り付けようとせず、サマリーにまとめるべきです。 |
| `end_line` | int | はい | 影響範囲の末尾行。単一行コメントの場合は `start_line` と等しくなります。 |
| `existing_code` | string | いいえ | 置き換え対象の元のコード片。diff を伴わない提案的コメントの場合は省略されます。 |
| `suggestion_code` | string | いいえ | `existing_code` の提案された置き換え。存在する場合は常に `existing_code` とペアになります。 |
| `thinking` | string | いいえ | モデルの推論の軌跡。分類やデバッグに有用です。ユーザーに表示する前に安全に破棄できます。 |
### warnings の構造（`warnings[]`）
スキップまたは一部のファイルが失敗した実行は、次のような形になります。
```json
{
"status": "completed_with_errors",
"message": "Some files could not be reviewed due to errors.",
"comments": [],
"warnings": [
{
"file": "src/very_long_file.go",
"message": "diff size exceeds 80% of MAX_TOKENS; skipped",
"type": "token_threshold_exceeded"
},
{
"file": "src/broken.py",
"message": "sub-agent failed: context deadline exceeded",
"type": "subtask_error"
}
]
}
```
| フィールド | 型 | 説明 |
|---|---|---|
| `file` | string | 警告を引き起こしたファイルのリポジトリ相対パス。 |
| `message` | string | 短い人間可読の説明。 |
| `type` | string | フィルタリング用の安定した型。現在出力されるもの：`subtask_error`（サブ agent の実行失敗）と `token_threshold_exceeded`（diff がモデルにとって大きすぎる）。 |
`warnings` が少なくとも 1 つの `subtask_error` を含む場合、`status` は
`completed_with_errors` になります。そうでない場合は `completed_with_warnings` です。
### severity / priority フィールドは無い
OCR は `severity` や `priority` フィールドを**出力しません**。[Agent Skill](../agent-skill/)
と [Command](../claude-code/) のドキュメントで見られる High/Medium/Low の分類は、呼び出し側の agent が生のコメントを受け取った後に追加したものです——`jq '.comments[].severity'` を試みないでください。それは存在しません。
## 空の結果の扱い
**対象となるファイルが無い**作業領域は `status` で報告されるため、呼び出し側は「変更なし」と「発見なし」を区別できます。
```json
{
"status": "skipped",
"message": "No supported files changed.",
"comments": []
}
```
「すべてクリーン」と判断する前に、必ず `status == "skipped"` を確認してください。
## 関連項目
- [CI/CD](../ci/)——サブプロセス呼び出しの上に構築された、すぐ使える GitHub Actions と pre-commit のレシピ。
- [Agent Skill](../agent-skill/)——呼び出し側が通常のスクリプトではなく Anthropic SDK agent の場合。

126
pages/src/content/docs/ja/overview.md Normal file
View file

@ -0,0 +1,126 @@
---
title: 概要
sidebar:
order: 2
---
## Open Code Review とは？
Open Code Review（略称 **OCR**。光学式文字認識 Optical Character
Recognition とは異なります）は、AI 駆動のコードレビュー CLI であり、
[`@alibaba-group/open-code-review`](https://www.npmjs.com/package/@alibaba-group/open-code-review)
NPM パッケージおよびスタンドアロンの Go バイナリとして配布されています。CLI バイナリ名は `ocr` です。
たった 1 つのコマンド（`ocr review`）で、以下を実行します。
1. Git diff を解析します——ワークスペース、ブランチ区間、または単一の commit。
2. システムのデフォルトルールとユーザールールを組み合わせて変更ファイルをフィルタリングします。
3. 変更ファイルごとに **per-file サブ agent** を並行で起動します。
4. 各サブ agent は LLM のツール呼び出しループを実行します。大きな diff に対しては、オプションでまず
**plan フェーズ** を実行できます。
5. モデルは `code_comment` を呼び出して発見事項を記録し、オプションで `file_read`、
`code_search`、`file_find`、`file_read_diff` を呼び出してコンテキストを収集し、完了後に
`task_done` を呼び出します。
6. OCR は各コメントを正確な行番号に解決し、正確にマッチできなかったコメントに対しては
オプションの再配置フローを実行し、最終的なリストを出力（または JSON で出力）します。
## 汎用 agent の問題
汎用のコーディング agent（Claude Code の Skill、Cursor、Cline など）でコード
レビューを行ったことがあるなら、次のような経験をしたことがあるでしょう。
- **カバレッジ不足**——大きな変更セットでは、agent がひそかに手を抜き、一部のファイルしかレビューしません。
- **位置ずれ**——コメントが指し示すコードと一致しません。行番号やファイルパスが対象からずれます。
- **品質が不安定**——自然言語ベースの Skill はデバッグが難しく、prompt のわずかな変更で
出力品質が変動します。
根本的な原因は、純粋な言語駆動のアーキテクチャにはレビュープロセスに対する **ハードな制約** が欠けていることです。
## コア設計：決定論的エンジニアリング × agent
OCR のコアとなる考え方は、**決定論的エンジニアリング** と **agent** を組み合わせ、それぞれが最も得意とすることを担わせることです。
### 決定論的エンジニアリング——ハードな制約
*絶対に間違えてはならない* ステップについては、モデルではなくエンジニアリングロジックによって正しさを保証します。
- **正確なファイル選択**——[5 段階のフィルタゲート](../review-rules/#how-files-are-filtered)
がどのファイルをレビューするかを決定し、明示的な `include`/`exclude` 制御を提供します。
- **スマートなファイルのパッケージング**——関連するファイル（例：`message_en.properties` と
`message_zh.properties`）を 1 つのレビュー単位にまとめられます。各パッケージは独立したコンテキストとして
サブ agent に渡されて実行されます——分割統治により、超大規模な変更セットでも安定し、並行レビューを自然にサポートします。
- **きめ細かなルールマッチング**——レビュールールはファイルパスでマッチし、最初にマッチしたものが有効になります。これによりモデルの注意を
高度に集中させ、ノイズを排除します。テンプレートベースのマッチングは、純粋な言語駆動のルール誘導よりも安定しています。
- **外部の配置・リフレクションモジュール**——独立したコメント配置
（[`internal/diff/relocation.go`](https://github.com/alibaba/open-code-review/blob/main/internal/diff/relocation.go)）
と再配置フローにより、位置と内容の正確性を体系的に向上させます。
### Agent——動的な意思決定
agent の強みは、最も重要な部分に集約されます。
- **シーン特化でチューニングされた prompt**——コードレビューのシーンに向けて深くチューニングされた prompt
テンプレートにより、token 消費を抑えつつ効果を高めます（
[`internal/config/template/task_template.json`](https://github.com/alibaba/open-code-review/blob/main/internal/config/template/task_template.json)
を参照）。
- **シーン特化でチューニングされたツールセット**——大規模な本番データのツール呼び出し trace 分析から抽出されました
（呼び出し頻度の分布、単一ツールの繰り返し率、各ツールが呼び出しチェーン全体に与える影響）。最終的に得られた
専用の [6 ツール](../tools/) セットは、汎用 agent のツールキットよりも安定していて予測可能です。
## パイプラインの連携
```mermaid
flowchart TD
Start["<b>ocr review --from main --to feature</b>"]
S1["<b>1. Resolve LLM endpoint</b><br/>config / env / shell rc"]
S2["<b>2. Load diffs from git</b><br/>workspace / commit / range"]
S3["<b>3. Filter files</b><br/>binary → user_exclude → user_include<br/>→ ext allowlist → default path"]
S4["<b>4. Drop diffs > 80% of MAX_TOKENS</b>"]
S5["<b>5. Dispatch per-file sub-agents</b> (concurrent)<br/><br/>For each file:<br/>&nbsp;&nbsp;a. Plan phase (if changed lines ≥ 50)<br/>&nbsp;&nbsp;b. Main loop: LLM → tool calls → … → task_done<br/>&nbsp;&nbsp;c. code_comment results collected (async via worker pool)<br/><br/>Memory compression triggers when context<br/>exceeds 60 % (async) or 80 % (sync) of MAX_TOKENS."]
S6["<b>6. Resolve line numbers</b><br/>from <code>existing_code</code> against diffs.<br/>Re-locate via LLM if needed."]
S7["<b>7. Emit text or JSON output</b><br/>(and persist session to disk)"]
Start --> S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7
```
## プロジェクト構成
```
open-code-review/
├── cmd/opencodereview/ # CLI エントリ：ディスパッチ、引数、コマンド
├── internal/
│ ├── agent/ # ファイルごとのサブ agent ループ + メモリ圧縮
│ ├── config/
│ │ ├── allowlist/ # デフォルトのファイル拡張子ホワイトリストと除外項目
│ │ ├── rules/ # 階層型ルールパーサー、システムルールドキュメント
│ │ ├── template/ # plan / main / memory_compression prompt
│ │ ├── testconnection/ # 組み込みの `ocr llm test` タスク
│ │ └── toolsconfig/ # モデルに送信するツール定義
│ ├── diff/ # Git diff 解析、hunk 計算、再配置
│ ├── gitcmd/ # Git サブプロセスランナー
│ ├── llm/ # Anthropic + OpenAI プロトコル、リトライ、BPE token
│ ├── model/ # diff / コメント のデータ構造
│ ├── pathutil/ # パスユーティリティ
│ ├── release/ # Release notes 生成
│ ├── session/ # レビューセッションごとの JSONL 永続化
│ ├── stdout/ # `--audience agent` 下でミュート可能な stdout writer
│ ├── suggestdiff/ # "Apply suggestion" diff の構築
│ ├── telemetry/ # OpenTelemetry span、metrics、exporter
│ ├── tool/ # 6 つの組み込みツール + コメントコレクター
│ └── viewer/ # `ocr viewer`——過去のセッション用のローカル Web UI
├── pages/ # React ベースのマーケティング用ランディングページ（独立）
├── plugins/ # Claude Code プラグインマニフェスト + コマンド
├── extensions/ # エディタ拡張（VS Code）
├── examples/ # CI レシピ（GitHub Actions、GitLab CI）
├── skills/ # 汎用 agent Skill マニフェスト
├── scripts/ # NPM インストール/更新ヘルパー、リリーススクリプト
├── npm/ # 各プラットフォーム向け optional dependency パッケージ
└── bin/ # NPM wrapper、シェルからバイナリを呼び出す
```
## 関連項目
- [クイックスタート](../quickstart/)——インストールして初回のレビューを完了します。
- [アーキテクチャ](../architecture/)——agent ループ、plan フェーズ、メモリ圧縮。
- [CLI リファレンス](../cli-reference/)——各引数とサブコマンド。
- [インテグレーション](../integrations/)——Claude Code や任意の agent から OCR を呼び出します。

235
pages/src/content/docs/ja/quickstart.md Normal file
View file

@ -0,0 +1,235 @@
---
title: クイックスタート
sidebar:
order: 3
---
OCR をインストールし、Anthropic Messages API または OpenAI Chat Completions API
に対応した任意の LLM に接続して、初回のコードレビューを実行しましょう。
## 前提条件
- 動作する **Git** のインストール——OCR は Git をサブプロセスとして駆動し diff を読み取ります。
- Anthropic または OpenAI 互換の LLM の **API key**。
- 以下のいずれか：
- **Node.js ≥ 18**（推奨。最低サポートは Node 14——NPM 経由でインストール）。
- または `curl` + `chmod` だけで静的バイナリを `$PATH` に配置。
- またはソースからビルドしたい場合は **Go ≥ 1.25**。
## ステップ 1——CLI をインストールする
### 方法 A：NPM（推奨）
```bash
npm install -g @alibaba-group/open-code-review
```
NPM パッケージは小さな wrapper をインストールし、インストール時に（postinstall hook を通じて）お使いの
OS / アーキテクチャ向けの正しいバイナリをダウンロードします。実行時にバイナリが存在しない場合、wrapper はエラーを出し、
ダウンロードは行いません。インストール後、グローバルな `ocr` コマンドが利用できます。
```bash
ocr --version
```
### 方法 B：GitHub Release バイナリ
[releases ページ](https://github.com/alibaba/open-code-review/releases)
から対応プラットフォームのバイナリを選び、`$PATH` に配置します。
```bash
# macOS (Apple Silicon)
curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-darwin-arm64
chmod +x ocr && sudo mv ocr /usr/local/bin/ocr
# macOS (Intel)
curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-darwin-amd64
chmod +x ocr && sudo mv ocr /usr/local/bin/ocr
# Linux x86_64
curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-linux-amd64
chmod +x ocr && sudo mv ocr /usr/local/bin/ocr
# Linux ARM64
curl -Lo ocr https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-linux-arm64
chmod +x ocr && sudo mv ocr /usr/local/bin/ocr
# Windows (AMD64)
curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-amd64.exe
# Windows (ARM64)
curl -Lo ocr.exe https://github.com/alibaba/open-code-review/releases/latest/download/opencodereview-windows-arm64.exe
```
### 方法 C：ソースからビルドする
```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
```
> 各インストール方法の詳細は [インストール](../installation/) を参照してください。NPM wrapper が
> プラットフォームバイナリをどのように解決するかも含まれています。
## ステップ 2——LLM を設定する
完全な LLM エンドポイント（URL + token + model）を解決できるまで、OCR はレビューの実行を拒否します。
以下の優先順位で 4 つの来源を探索します。
1. `~/.opencodereview/config.json`
2. OCR 専用の環境変数（`OCR_LLM_*`）
3. Claude Code の環境変数（`ANTHROPIC_*`）
4. シェルの rc ファイル（`~/.zshrc`、`~/.bashrc`、`~/.bash_profile`、
`~/.profile`）から解析された `export ANTHROPIC_*` 行
### 最速の経路：`ocr config set`
```bash
ocr config set llm.url https://api.anthropic.com/v1/messages
ocr config set llm.auth_token sk-ant-xxxxxxxxxx
ocr config set llm.model claude-opus-4-6
ocr config set llm.use_anthropic true
```
これらの値は `~/.opencodereview/config.json` に永続化されます。
### 代替方法：環境変数
優先度が最も高く、ディスクに設定ファイルを残したくない CI / コンテナに適しています。
```bash
export OCR_LLM_URL=https://api.anthropic.com/v1/messages
export OCR_LLM_TOKEN=sk-ant-xxxxxxxxxx
export OCR_LLM_MODEL=claude-opus-4-6
export OCR_USE_ANTHROPIC=true # デフォルトは true。false にすると OpenAI プロトコルを使用
```
### すでに Claude Code を使っている場合
OCR は Claude Code が使用するのと同じ変数群を自動的に読み取るため、追加の設定は不要です。
```bash
export ANTHROPIC_BASE_URL=https://api.anthropic.com
export ANTHROPIC_AUTH_TOKEN=sk-ant-xxxxxxxxxx
export ANTHROPIC_MODEL=claude-opus-4-6
```
`ANTHROPIC_BASE_URL` にバージョン付きのパスがない場合、OCR は自動的に
`/v1/messages` を追加します。
### OpenAI 互換エンドポイントを使う場合
`llm.use_anthropic` を `false` に設定します（または `OCR_USE_ANTHROPIC=false`）。
```bash
ocr config set llm.url https://api.openai.com/v1/chat/completions
ocr config set llm.auth_token sk-xxxxxxxxxx
ocr config set llm.model gpt-4o
ocr config set llm.use_anthropic false
```
> 完全な key のリファレンスは [設定](../configuration/) を参照してください。ベンダー固有のリクエストフィールド
> 用の `llm.extra_body` や、レビューコメントの言語を切り替える `language` も含まれています。
## ステップ 3——接続性をテストする
```bash
ocr llm test
```
期待される出力（モデル名は異なります）：
```
Source: OCR config file
URL: https://api.anthropic.com/v1/messages
Model: claude-opus-4-6
Hello! …
```
代わりに `no valid LLM endpoint configured` のようなエラーが出た場合は、上記の
設定 key を再確認してください。401 / 403 は token が誤っているか期限切れであることを示します。
## ステップ 4——初回のレビューを実行する
任意の Git リポジトリに移動して実行します。
```bash
cd path/to/your-repo
# ワークスペースモード——staged + unstaged + untracked の変更をレビュー（デフォルト）
ocr review
# ブランチ区間——`main..feature-branch` をレビュー
ocr review --from main --to feature-branch
# 単一 commit——その commit が導入した diff をレビュー
ocr review --commit abc123
```
進捗情報が継続的に出力され、最後に各ファイルに 1 つ以上のレビューコメントが表示されます。
> ワークスペースモードには **untracked** ファイルが含まれます。すでにステージされた内容だけをレビューしたい場合は、まず
> `git add` で選択的にステージしてください。
> 上記の 3 つは基本的な使い方です。`ocr review` の完全な引数（並行数のチューニング、出力形式、
> audience モード、背景コンテキストなど）と、その他すべてのサブコマンド（`config`、`rules`、
> `llm test`、`viewer`）は [CLI リファレンス](../cli-reference/) を参照してください。
### 先に *何が* レビューされるか見てみたい場合
```bash
ocr review --preview # ワークスペース
ocr review -c abc123 -p # commit
```
`--preview` は各フィルタステップを実行しますが LLM は一切呼び出さないため、token を消費しません。ファイルリストと
各ファイルのステータス（`added` / `modified` / `deleted` / `renamed` / `binary`）を出力し、
除外されたファイルについてはその理由（`binary`、`unsupported_ext`、`default_path`、
`user_exclude`、`deleted`）も示します。
### ツール向けの JSON 出力
```bash
ocr review --format json --audience agent > review.json
```
- `--format json` は機械可読なコメント配列を出力します。各コメントには `path`、`content`、
`start_line`、`end_line`、`existing_code`、`suggestion_code`、およびオプションの
`thinking` が含まれます。
- `--audience agent` は人間向けの進捗 UI を抑制し、stdout を JSON / 最終
サマリーだけにします——上流の agent や CI スクリプトが必要とするものです。
## ステップ 5——結果を確認する
各コメントには以下が含まれます。
| フィールド | 意味 |
|---|---|
| `path` | そのコメントが対象とするファイル。 |
| `content` | レビューコメント本体。設定された `language` を使用します。 |
| `start_line` / `end_line` | ファイルの **新しい** バージョンにおける行範囲。両方が `0` の場合は OCR がコメントを正確に配置できなかったことを意味します——問題は本物ですが、正確な位置は自分で特定する必要があります。 |
| `existing_code` | コメントが指す diff の断片。内部的に行解決に使われます。`start_line` が `0` のときに役立ちます。 |
| `suggestion_code` | オプションの修正断片。 |
| `thinking` | オプションのモデルの推論。一部のモデルにのみ存在します。 |
## ステップ 6——過去のセッションを閲覧する
各レビューは JSONL トランスクリプトとして
`~/.opencodereview/sessions/...` に永続化されます。ローカルの Web UI でそれらを閲覧できます。
```bash
ocr viewer # http://localhost:5483
ocr viewer --addr :3000
```
> UI の完全な紹介は [セッションビューア](../viewer/) を参照してください。
## 関連項目
- [CLI リファレンス](../cli-reference/)——各サブコマンド、引数、出力モード。
- [レビュールール](../review-rules/)——レビュー内容をカスタマイズします。
- [インテグレーション](../integrations/)——OCR を Claude Code、Agent skill、CI に組み込みます。
- [テレメトリ](../telemetry/)——OTLP 経由で trace と metrics を送信します。
- [FAQ](../faq/)——既知のエラーと対策。

217
pages/src/content/docs/ja/review-rules.md Normal file
View file

@ -0,0 +1,217 @@
---
title: レビュールール
sidebar:
order: 7
---
ルールは、各ファイルをレビューする際に OCR が**何に注目すべきか**を伝えます。ルールは 3 層の JSON ファイルに格納され、加えてバイナリに同梱される埋め込みのシステムデフォルトルールがあります。
## 優先順位チェーン
OCR は**4 層の優先順位チェーン**でルールを解決します。各ファイルパスについて、層を順に試し、最初に一致したパターンが有効になります。
| 優先順位 | 出所 | パス | 説明 |
|---|---|---|---|
| 1（最高） | `--rule` 引数 | ユーザー指定 | CLI による上書き。指定されている限り常に有効になります。 |
| 2 | プロジェクト設定 | `<repoDir>/.opencodereview/rule.json` | プロジェクトレベルのルール。安全に commit できます。 |
| 3 | グローバル設定 | `~/.opencodereview/rule.json` | ユーザーレベルの好み。 |
| 4（最低） | システムデフォルト | 埋め込み `system_rules.json` | 一般的な言語をカバーする組み込みルール。 |
より高い優先順位の層のファイルが存在しない場合は静かにスキップされます。エラーではありません。したがって `.opencodereview/rule.json` を一度も追加していないプロジェクトは、そのままグローバル / システム層に落ちます。
システム層は**常に**存在するため（バイナリに同梱）、必ず*何らかの*ルールが解決されます。
## ルールファイル形式（層 1〜3）
```json
{
"include": ["src/**/*.{ts,tsx}", "src/**/*.go"],
"exclude": ["**/*.test.ts", "**/generated/**"],
"rules": [
{
"path": "src/api/**/*.go",
"rule": "All exported handlers must validate request bodies before use."
},
{
"path": "**/*mapper*.xml",
"rule": "Check SQL for injection risks, parameter errors, and missing closing tags."
}
]
}
```
3 つの独立したフィールドがあります:
- `include`: 任意。組み込みのデフォルト除外パターン（テストファイルの除外。下記参照）を*バイパス*するための glob パターンです。ホワイトリストではありません。どの `include` パターンにも一致しないファイルも、依然として `unsupported_ext` と `default_path` のチェックを通過し、レビューされる可能性があります。
- `exclude`: 任意。OCR がレビューしないファイルの glob パターンです。フィルタリングで最も優先されます。
- `rules`: `{path, rule}` エントリの配列で、**宣言順**に評価されます。そのファイルに最初に一致した `path` glob のエントリが、OCR がモデルに送る prompt を決定します。
### glob の機能
OCR は [`bmatcuk/doublestar/v4`](https://pkg.go.dev/github.com/bmatcuk/doublestar/v4) でマッチングを行います:
- `*`: `/` 以外の任意の文字に一致します。
- `**`: ディレクトリ境界をまたいで一致します（`src/**/*.go` は任意の深さをカバー）。
- `{a,b,c}`: 波括弧の展開。`*.{ts,tsx,js,jsx}` は 4 つのパターンに展開され、順に一致が試されます。
- `?`: 単一の文字に一致します。
- `[abc]`: 文字クラス。
> パターンマッチングは**大文字小文字を区別しません**（マッチング前にファイルパスは小文字化されます）。確信が持てないときは `ocr rules check <path>` で確認してください。
## ファイルがどのようにフィルタリングされるか
フィルタリングは 5 段階のゲートアルゴリズムで、[`internal/agent/preview.go`](https://github.com/alibaba/open-code-review/blob/main/internal/agent/preview.go) にあります。各 diff について、OCR は順に次を問います:
1. **`binary`**: ファイルはバイナリか？ 除外します。
2. **`user_exclude`**: パスがいずれかのユーザー `exclude` パターンに一致するか？ 除外します。
3. **`user_include`**: ユーザーが `include` を定義している場合、パスは一致するか？ 一致するなら**即座に保持**します（下記の `unsupported_ext` と `default_path` のゲートをバイパス）。
4. **`unsupported_ext`**: ファイルの拡張子は[ホワイトリスト](https://github.com/alibaba/open-code-review/blob/main/internal/config/allowlist/supported_file_types.json)にあるか？ なければ除外します。
5. **`default_path`**: パスがいずれかの組み込みテストファイル除外パターン（`**/*_test.go`、`**/*.test.{js,jsx,ts,tsx}`、`**/*_spec.rb`……）に一致するか？ 除外します。
5 つのゲートをすべて通過したファイルだけが LLM に送られます。`deleted` の理由（これはゲートではなく、`Preview()` の中で個別に計算されます）は、新しいパスが `/dev/null` であるファイルを示します。レビューすべき新しい内容がありません。`ocr review --preview` を使えば、token を消費せずにこのフィルタリング結果を出力できます。
### デフォルトパスの除外
組み込みの除外リスト（[`internal/config/allowlist/default_exclude_patterns.json`](https://github.com/alibaba/open-code-review/blob/main/internal/config/allowlist/default_exclude_patterns.json) を参照）は、テストファイルのパターンに一致します:
- `**/*_test.go`
- `**/src/test/java/**/*.java`
- `**/src/test/**/*.kt`
- `**/*.test.{js,jsx,ts,tsx}`
- `**/*.spec.{js,jsx,ts,tsx}`
- `**/__tests__/**`
- `**/test/**/*_test.py`
- `**/tests/**/*_test.py`
- `**/*_test.py`
- `**/*_spec.rb`
- `**/spec/**/*_spec.rb`
- `**/*Test.java`
- `**/*Tests.java`
- `**/*_test.rs`
- `**/oh_modules/**`
- `**/*.test.ets`
ノイズディレクトリのフィルタリング（`vendor/`、`node_modules/`、`target/`……）は、より早い段階、[`internal/diff/git.go`](https://github.com/alibaba/open-code-review/blob/main/internal/diff/git.go) の diff 層で発生し、ファイルごとのフィルタリングより先に実行されます。
これらのテストファイルパターンに一致するファイルを**レビューする**には、それをユーザー `include` リストに追加してください。それが default-path ゲートを上書きします。
## ファイルごとのルール解決
フィルタリングによってあるファイルが*レビューされる*と決まったあと、OCR は agent が従うべきルールテキストを選びます:
1. 宣言順に `--rule`（custom）層を試します。
2. 宣言順に `<repo>/.opencodereview/rule.json` を試します。
3. 宣言順に `~/.opencodereview/rule.json` を試します。
4. 埋め込みのシステムルール層にフォールバックします。
埋め込みの `system_rules.json` には次のパターンが同梱されています（順序どおり）:
| パターン | ルールドキュメント |
|---|---|
| `**/*.properties` | `properties.md`: i18n / 設定ファイル。 |
| `**/*{mapper,dao}*.xml` | `mapper_dao_xml.md`: MyBatis 形式の mapper SQL。 |
| `**/pom.xml` | `pom_xml.md`: Maven 依存関係。 |
| `**/build.gradle` | `build_gradle.md`: Gradle 依存関係。 |
| `**/package.json` | `package_json.md`: NPM 依存関係 / スクリプト。 |
| `**/Cargo.toml` | `cargo_toml.md`: Rust manifest。 |
| `**/*.{json,json5}` | `json.md`: 汎用 JSON（`.json5` にも一致）。 |
| `.github/workflows/**/*.{yaml,yml}` | `github_workflows.md`: GitHub Actions ワークフロー YAML。 |
| `.github/**/*.{yaml,yml}` | `github_config.md`: その他の `.github` 設定 YAML。 |
| `**/*.{yaml,yml}` | `yaml.md` |
| `**/*.java` | `java.md` |
| `**/*.ets` | `arkts.md`: ArkTS / HarmonyOS。 |
| `**/*.{ts,js,tsx,jsx}` | `ts_js_tsx_jsx.md` |
| `**/*.{kt}` | `kotlin.md` |
| `**/*.rs` | `rust.md` |
| `**/*.{cpp,cc,hpp}` | `cpp.md` |
| `**/*.c` | `c.md` |
| *(fallback)* | `default.md` |
解決されたルール本文は、plan および main task prompt 内の `{{system_rule}}` プレースホルダーの内容になります。
## どのルールが有効かを確認する: `ocr rules check`
```bash
$ ocr rules check src/main/java/com/example/UserService.java
File: src/main/java/com/example/UserService.java
Source: System built-in
Pattern: **/*.java
Rule:
────────────────────────────────────────
…contents of java.md…
────────────────────────────────────────
```
```bash
$ ocr rules check --rule custom.json src/main/resources/mapper/UserMapper.xml
File: src/main/resources/mapper/UserMapper.xml
Source: Custom (--rule)
Pattern: **/*mapper*.xml
Rule:
────────────────────────────────────────
…contents of your custom rule…
────────────────────────────────────────
```
あるルールが期待どおりに有効にならないときに使用してください。有効な**層**と**パターン**を表示します。
## レシピ
### プロジェクトレベル: コーディング規約を強制する
`<repo>/.opencodereview/rule.json` として保存し、commit します:
```json
{
"rules": [
{
"path": "src/api/**/*.go",
"rule": "Every public handler must `defer tx.Rollback()` immediately after starting a transaction."
},
{
"path": "**/*mapper*.xml",
"rule": "Check SQL for injection risks, missing parameter binding, and unclosed XML tags."
}
]
}
```
### プロジェクトレベル: 生成コードをスキップし、src に集中する
```json
{
"include": ["src/**/*.{ts,tsx,js,jsx}"],
"exclude": ["**/*.gen.ts", "**/generated/**"]
}
```
`include` を設定すると、`src/` 内のファイルは、本来は組み込みのデフォルト除外パターン（テストファイルなど）で除外されるものであっても保持されます。`src/` 以外のファイルは依然として通常の ext / default チェックを通ります。`include` はバイパスの仕組みであり、ホワイトリストではありません。
### PR ごとの上書き
```bash
ocr review --rule ./.review-rules-only-for-this-pr.json
```
プロジェクト層とグローバル層の両方を同時にバイパスします。単一の PR が完全に異なるレビューチェックリスト（例: セキュリティレビューのみ）を必要とするときに便利です。
### グローバルな個人設定
`~/.opencodereview/rule.json` に置くと、自分のマシン上のすべてのリポジトリが継承します:
```json
{
"rules": [
{
"path": "**/*.{ts,tsx,js,jsx}",
"rule": "Always check for unhandled promise rejections; warn on `// eslint-disable` without a reason comment."
}
]
}
```
## 関連項目
- [CLI リファレンス](../cli-reference/): `ocr review --rule`、`--preview`、`ocr rules check`。
- [設定](../configuration/): config ファイルの場所と階層的な解決チェーン。
- [アーキテクチャ](../architecture/): 解決されたルールがどのように agent prompt に供給されるか。

258
pages/src/content/docs/ja/telemetry.md Normal file
View file

@ -0,0 +1,258 @@
---
title: テレメトリ
sidebar:
order: 11
---
OCR には第一級の **OpenTelemetry** サポートが付属しています。各レビュー実行は、構造化された span、
metric、event を生成します。collector に接続すれば、これらのデータは「agent は時間をどこに費やしたか？」、
「各モデルのコストはどうか？」、「なぜこの実行は失敗したか？」に答えるのに十分です。
## 概要
テレメトリは**デフォルトで無効**です。有効にすると、OCR は以下をエクスポートします：
- **Span**——3 つのパイプラインレベルの span（`review.run`、`diff.parse`、
`subtask.execute.<file>`）に加え、各決定ポイントのイベントごとに短命な `event.*` span を 1 つ。
- **Metric**——レビュー所要時間、レビューされたファイル数、生成されたコメント数、LLM リクエスト / token / レイテンシ、
ツール呼び出し / レイテンシの集約カウントとヒストグラム。
- **Event**——span 内の離散的なイベント。`plan.skipped`、
`token.threshold.exceeded`、`review.started` など。
2 種類の exporter がサポートされています：
| Exporter | 使用する場面 |
|---|---|
| `console` | 個人利用 / デバッグ。span を整形して stdout に出力します。 |
| `otlp` | システム統合。任意の OTLP 互換 collector（Jaeger、Tempo、OTel Collector、Datadog Agent……）に送信します。 |
## テレメトリを有効にする
LLM エンドポイントと同様に、テレメトリは永続化された config または環境変数で設定できます——競合する場合は環境変数が優先されます。
### 設定ファイルによる方法
```bash
ocr config set telemetry.enabled true
ocr config set telemetry.exporter otlp
ocr config set telemetry.otlp_endpoint localhost:4317
ocr config set telemetry.content_logging false
```
`~/.opencodereview/config.json` での結果：
```json
{
"telemetry": {
"enabled": true,
"exporter": "otlp",
"otlp_endpoint": "localhost:4317",
"content_logging": false
}
}
```
### 環境変数による方法
```bash
export OCR_ENABLE_TELEMETRY=1
export OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4317 # implies exporter=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc # default. NOTE: only grpc is currently
# implemented; http/protobuf and http/json
# are accepted but not yet wired up.
export OTEL_SERVICE_NAME=open-code-review-prod # optional; default: open-code-review
export OCR_CONTENT_LOGGING=0 # reserved / currently a no-op (see Content logging)
```
`OTEL_EXPORTER_OTLP_ENDPOINT` を設定すると `exporter=otlp` も強制されます——一度きりの
`OTEL_EXPORTER_OTLP_ENDPOINT=… ocr review` 実行に適しています。
## 何がエクスポートされるか
### Span
1 回のレビューの完全な span ツリー：
```
review.run
├── diff.parse
├── event.review.started (decision-point event)
├── subtask.execute.<file1>
│ ├── event.plan.skipped (when changes are below threshold)
│ ├── event.plan.failed (when plan phase errored)
│ ├── event.token.threshold.exceeded (when prompt > 80% of max_tokens)
│ └── event.subtask.error (when the subtask errored)
├── subtask.execute.<file2>
└── …
```
LLM の往復とツールの実行は個別の span としては発行**されません**——metric（下記参照）にのみ現れます。
決定ポイントのイベントは、短命な `event.<name>` span として現在の context にアタッチされます。
各 span は有用な属性を保持します：
| Span | 主要な属性 |
|---|---|
| `review.run` | `error`（実行失敗時に設定） |
| `diff.parse` | `files.changed`、`lines.inserted`、`lines.deleted` |
| `subtask.execute.<file>` | `file.path`、`lines.changed`、`lines.inserted`、`lines.deleted` |
| `event.review.started` | `file.count`、`review.count`、`repo.dir` |
| `event.plan.skipped` | `file.path`、`lines.changed`、`threshold` |
| `event.plan.failed` | `file.path`、`message` |
| `event.token.threshold.exceeded` | `file.path`、`tokens`、`max_tokens` |
| `event.subtask.error` | `file.path`、`error` |
### Metric
OCR は OTel meter を通じて数値 metric を記録します——カウントとヒストグラムで、collector が下流で集約します：
| Metric | 種類 | 単位 | ラベル |
|---|---|---|---|
| `ocr.review.duration_seconds` | histogram | `s` | — |
| `ocr.files_reviewed_total` | counter | — | — |
| `ocr.comments_generated_total` | counter | — | — |
| `ocr.llm.requests_total` | counter | — | `model`、`status`（`ok` / `error`） |
| `ocr.llm.request_duration_seconds` | histogram | `s` | `model` |
| `ocr.llm.tokens_used` | counter | — | `model`、`type`（現在は常に `total`） |
| `ocr.tool.calls_total` | counter | — | `tool.name`、`status`（`ok` / `error`） |
| `ocr.tool.execution_duration_seconds` | histogram | `s` | `tool.name` |
### Event
イベントは決定ポイントで短命な `event.<name>` span としてトリガーされます。完全な一覧：
| イベント | 意味 |
|---|---|
| `review.started` | diff がロードされた。何ファイルをレビューするか判明している。 |
| `no.files.changed` | diff の解析で 0 ファイルとなった。 |
| `plan.skipped` | あるファイルが `PLAN_MODE_LINE_THRESHOLD` を下回った。 |
| `plan.failed` | plan フェーズでエラー。main ループは plan なしで実行される。 |
| `token.threshold.exceeded` | 初期 prompt token が `MAX_TOKENS` の 80 % を超えた。ファイルはスキップされる。 |
| `subtask.error` | あるファイルごとのサブタスクでエラー——`Error` span ステータスとして発行される。 |
これにより、ユーザーが気づく前に、レビュー品質の低下を早期に検出してアラートを出すことができます。
## コンテンツログ
テレメトリは LLM トラフィックの**形状**（カウント、所要時間、ステータス）をエクスポートしますが、実際の prompt や
レスポンスは**決して**エクスポートしません。OCR は LLM のメッセージ内容を span や event に付加しようとはしません——プロセスを離れるデータは上記に
記載された metric / event schema に限られ、それ以外は一切ありません。
`content_logging` の config key（および `OCR_CONTENT_LOGGING=1` の環境上書き）は設定レイヤーに接続されていますが、
現時点では prompt 内容を発出するいかなるコードパスも**制御しません**。このフラグは予約済みとみなしてください。
LLM に送信された、または LLM から返された内容を検査する必要がある場合は、[セッションビューア](../viewer/)が読み取るローカルの
JSONL トランスクリプトを使用してください。これらは完全に `~/.opencodereview/` 配下のディスク上に存在し、決して collector に送られません。
## レシピ
### ローカルデバッグ用の console exporter
```bash
ocr config set telemetry.enabled true
ocr config set telemetry.exporter console
ocr review --commit HEAD
```
span が人間可読な形式で stdout に出力されます。長い実行の出力を見るには `less` にパイプできます。
### OTel Collector + Tempo + Prometheus
```yaml
# otel-collector-config.yaml
receivers:
otlp:
protocols: { grpc: { endpoint: 0.0.0.0:4317 } }
exporters:
otlp/tempo:
endpoint: tempo:4317
tls: { insecure: true }
prometheus:
endpoint: 0.0.0.0:9464
service:
pipelines:
traces: { receivers: [otlp], exporters: [otlp/tempo] }
metrics: { receivers: [otlp], exporters: [prometheus] }
```
その後、shell で：
```bash
export OCR_ENABLE_TELEMETRY=1
export OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4317
ocr review --from main --to feature/branch
```
Tempo を開く → `service.name=open-code-review` で検索 → 任意の trace をクリックして完全な
span ツリーを表示。
### Datadog
Datadog Agent の OTLP receiver はデフォルトで OTLP/gRPC を使用します：
```bash
export OCR_ENABLE_TELEMETRY=1
export OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4317
export OTEL_SERVICE_NAME=open-code-review
```
span はその service name で APM 配下に現れます。LLM metric は上記のラベル付きで Metrics 配下に現れます。
### CI 実行、結果をダッシュボードへ
パイプラインステップで環境変数を注入します：
```yaml
- name: Code review
env:
OCR_LLM_URL: ${{ secrets.OCR_LLM_URL }}
OCR_LLM_TOKEN: ${{ secrets.OCR_LLM_TOKEN }}
OCR_LLM_MODEL: claude-opus-4-6
OCR_ENABLE_TELEMETRY: "1"
OTEL_EXPORTER_OTLP_ENDPOINT: ${{ vars.OTEL_COLLECTOR_URL }}
OTEL_SERVICE_NAME: open-code-review-ci
run: ocr review --from origin/main --to HEAD --audience agent
```
`OTEL_SERVICE_NAME` により、CI の trace を手動の開発実行の trace と区別できます。
## 解決の優先順位
OCR が最終的なテレメトリ設定を構築する際：
1. デフォルト（`enabled=false`、`exporter=console`、endpoint なし）。
2. `~/.opencodereview/config.json` の `telemetry.*` key。
3. 環境変数（最高優先度、ファイルを**上書き**）。
したがって、config では `telemetry.enabled=false` を保持したまま、実行ごとに
`OCR_ENABLE_TELEMETRY=1` で有効にできます。
## サンプリングとオーバーヘッド
OCR は**すべて**をエクスポートします。サンプリングの設定はありません。OTel のサンプリングは collector の責務です。典型的なレビュー
実行の場合：
- 1 つの `review.run` span + 1 つの `diff.parse` span + レビューされたファイルごとに 1 つの
`subtask.execute.<file>` span + 各決定ポイントのイベントごとに 1 つの短命な `event.*` span。
- 10 ファイルの PR で合計およそ 15〜25 個の span。LLM の往復とツール呼び出しは metric のカウントを増やしますが、
追加の span は作成しません。
エクスポートは**バッチ処理かつ非同期**です——テレメトリはレビューループをブロックしません。collector に到達できない場合、OCR は警告を記録して
続行します。レビューは引き続き通常の出力を生成します。
## トラブルシューティング
| 症状 | 考えられる原因 |
|---|---|
| 何もエクスポートされない | `OCR_ENABLE_TELEMETRY` / `telemetry.enabled` が未設定。デフォルトは**無効**。 |
| OTLP がローカルでは動くが本番で失敗する | OCR は現在 OTLP/gRPC のみを実装している——`OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`（または `http/json`）は受理されるが接続されておらず、切り替えても効果はない。endpoint と、collector が gRPC をリッスンしているかを確認すること。 |
| span は表示されるが metric がない | 一部の collector はデフォルトで traces pipeline のみを有効にする。設定に `metrics` pipeline を追加すること。 |
| span に prompt がない | OCR は prompt の内容をテレメトリに付加することは決してない——[コンテンツログ](#content-logging)を参照。代わりに[セッションビューア](../viewer/)を使ってトランスクリプトを検査すること。 |
## 関連項目
- [設定](../configuration/)——`telemetry.*` 名前空間の完全な key リファレンス。
- [アーキテクチャ](../architecture/)——各 span が実際に何を計測するか。
- [OpenTelemetry ドキュメント](https://opentelemetry.io/docs/)——collector のセットアップと exporter。

353
pages/src/content/docs/ja/tools.md Normal file
View file

@ -0,0 +1,353 @@
---
title: ツール
sidebar:
order: 9
---
OCR には、レビュー中に LLM が呼び出すための **6 つのツール**が組み込まれています。本ページでは、各ツールの用途、入力
schema、および入出力の例を記載します。完全な機械可読の定義は
[`internal/config/toolsconfig/tools.json`](https://github.com/alibaba/open-code-review/blob/main/internal/config/toolsconfig/tools.json)
にあります。
## 各フェーズでのツールの利用可否
各ツールは、**plan フェーズ**、**main task**、あるいはその両方のどこで利用できるかを宣言します：
| ツール | Plan | Main | 用途 |
|---|---|---|---|
| `task_done` | ✗ | ✓ | 「完了しました」を示す——ループを終了します。 |
| `code_comment` | ✗ | ✓ | 行範囲 + 提案を伴うレビューコメントを 1 件発行します。 |
| `file_read` | ✗ | ✓ | 変更後のスナップショット内のあるファイルの一部を読み取ります。 |
| `file_read_diff` | ✓ | ✓ | 別のファイルの diff を読み取り、ファイル横断の懸念を確認します。 |
| `file_find` | ✓ | ✓ | ファイル名のキーワードでファイルを特定します。 |
| `code_search` | ✓ | ✓ | リポジトリ全体の grep（リテラルまたは正規表現）。 |
`task_done` と `code_comment` は plan フェーズでは意図的に**利用できません**：plan は読み取り専用です。
> **コンテキストツールは読み取り専用のコンテキストであり、コメント対象ではありません。** `main_task` prompt は、
> *他の*ファイル内の発見についてコメントすることを明確に禁止しています。`file_read`、`file_read_diff`、`file_find`、
> `code_search` が存在するのは、モデルが現在のファイルの diff をよりよく理解するためであり——そのコンテキストを収集する際に
> 見つかったいかなる問題も、設計上無視されます。ファイル横断の懸念は、**現在のファイルの diff** で観測可能な場合にのみ
> コメントとして現れます。
ツールレジストリを上書きするには、組み込みの定義と同じ形式の JSON ファイルパスを `--tools <path>` で渡します。
これにより、ツールを無効化したり、説明を編集したり、既存の provider をベースに新しいツールを追加したりできます。
## `task_done`
main ループを終了します。
```json
{
"name": "task_done",
"input": { "state": "DONE" }
}
```
| フィールド | 必須 | 意味 |
|---|---|---|
| `state` | はい | `DONE`（デフォルト）または `FAILED`。`FAILED` は「利用可能なツールでは本当に完了できない」ことを示します——ほとんど常に正しい選択ではありません。 |
agent は `task_done` を受け取ると、LLM の呼び出しを停止し、累積した `code_comment`
呼び出しの処理を開始します。`task_done` は（結果がセッションログに記録される前に）即座に返されるため、`state` の値は受理されますが
**永続化されず**——終了コードにも影響しません。
## `code_comment`
1 件または複数のレビューコメントを発行します。各コメントはコードスニペット（`existing_code`）にアンカーされ、
OCR が行番号を自動計算できるようにします。
### Schema
```json
{
"name": "code_comment",
"input": {
"path": "string — optional, override the file path for this comment",
"comments": [
{
"content": "string — the comment in the configured language",
"existing_code": "string — snippet from the diff to anchor on",
"suggestion_code": "string — optional fix snippet",
"thinking": "string — optional, the model's reasoning for this comment"
}
]
}
}
```
`comments` は配列なので、モデルは 1 回のツール呼び出しで複数のコメントを発行できます。`content` と
`existing_code` は必須です。`suggestion_code` は任意ですが、提供が推奨されます。`path` はトップレベルの任意の上書きで——
省略すると、agent は現在レビュー中のファイルを注入します。モデルが省略しても agent が自動的に `path` を注入するため、
モデルが明示的に設定する必要はほとんどありません。`thinking`（コメントごと）はモデルの推論を捕捉し、コメントに保持されますが、
最終的なレビュー出力には表示されません。
> **`thinking` はランタイム専用フィールドです。** OCR はこれを解析して保存しますが、モデルに渡す
> `code_comment` schema には意図的に**含めていません**（`tools.json` には `content`、
> `existing_code`、`suggestion_code` のみがあります）。より高性能なモデルが依然として `thinking` ブロックを発行した場合も
> 永続化されます。ほとんどのモデルは発行しませんが、問題ありません。
### アンカーアルゴリズム
OCR は**動的なスライディングウィンドウ**を使って diff 内で `existing_code` テキストを検索します。マッチは順に試行されます：
1. **hunk の新側**——連続する **context + added** 行（deleted のみでも unchanged のみでもない）の一群で、
新ファイルの行番号を得ます。失敗した場合、OCR は **hunk の旧側**——context +
deleted 行——を再試行し、旧ファイルの行番号を得ます。
2. **ファイル全体の新規スキャン**——hunk マッチがない場合、OCR は変更後のファイル全体を 1 行ずつスキャンして連続マッチを探します
（`resolveFromFileContent`）。
3. **再位置特定タスク**——より複雑な diff でテキストマッチが依然として失敗した場合、OCR は
`RE_LOCATION_TASK` prompt を実行し、モデルにスニペットの再アンカーを依頼します。
マッチは**空白に対して非依存**です：比較前に行を trim し、diff の `+`/`-` マーカーを取り除くため、インデントが
正確に一致する必要はありません。最後の手段として、コメントは `start_line=0` で配信され、ユーザーに「問題は本物だが自分で位置を特定してほしい」と伝えます。
### 例
```json
{
"comments": [
{
"content": "`tx.Rollback()` is never deferred — early returns leak the transaction.",
"existing_code": "tx, err := db.Begin()\nif err != nil {\n return err\n}",
"suggestion_code": "tx, err := db.Begin()\nif err != nil {\n return err\n}\ndefer tx.Rollback()"
}
]
}
```
## `file_read`
ファイルの**変更後**の形式で一定範囲の行を読み取ります。
### Schema
```json
{
"name": "file_read",
"input": {
"file_path": "src/foo.go",
"start_line": 10,
"end_line": 80
}
}
```
| フィールド | 必須 | デフォルト | 説明 |
|---|---|---|---|
| `file_path` | はい | — | リポジトリルートからの相対パス。 |
| `start_line` | いいえ | `1` | 1 始まりのインデックス。 |
| `end_line` | いいえ | ファイル末尾 | 端点を含む。 |
### 出力
```
File: src/foo.go (Total lines: 220)
IS_TRUNCATED: false
LINE_RANGE: 10-80
10|package foo
11|
12|import (
13| "fmt"
…
```
各行の内容には、1 始まりの行番号と `|` 区切り文字が前置され、モデルが後続の `code_comment` 呼び出しで
行番号を正確に参照できるようにします。
### 制限
- **1 回の呼び出しで最大 500 行。** より大きな範囲は切り詰められ、`IS_TRUNCATED: true` が設定され、
`Note: Results truncated to 500 lines. Please narrow your line range.` が追記されます。
- ファイルの**変更後バージョン**のみを読み取ります。旧バージョンを見るには `file_read_diff` を使用します。
モデルが周辺のコンテキストを必要とする場合（diff 内でしか見えない関数についてコメントする際など）、diff の
hunk ヘッダー `@@ -x,y +m,n @@` から範囲を計算すべきです——通常は `m-50` から `m+n+50` まで。
## `file_read_diff`
同一の変更セット内の 1 つまたは複数の*他の*ファイルの diff を読み取ります——コメントが関連ファイルの
更新有無に依存する場合に有用です。
### Schema
```json
{
"name": "file_read_diff",
"input": {
"path_array": ["src/api/handler.go", "src/db/queries.go"]
}
}
```
### 出力
```
==== FILE: src/api/handler.go ====
--- a/src/api/handler.go
+++ b/src/api/handler.go
@@ -10,1 +10,2 @@
- old line
+ new line 1
+ new line 2
==== FILE: src/db/queries.go ====
@@ -5,1 +5,1 @@
- query := "SELECT *"
+ query := "SELECT id"
```
あるパスが変更セットに含まれていない場合、そのエントリは静かに省略されます。要求されたパスが**いずれも**変更セットに含まれていない場合、ツールは
`Error: diff not found for the requested paths` を返します。空の `path_array` は
`Error: no files found` を返します。
## `file_find`
ファイル名のキーワード（部分文字列マッチ）でリポジトリ内のファイルを検索します。
### Schema
```json
{
"name": "file_find",
"input": {
"query_name": "UserService",
"case_sensitive": false
}
}
```
| フィールド | 必須 | デフォルト | 説明 |
|---|---|---|---|
| `query_name` | はい | — | 各ファイルの **basename**（最後の `/` より後の部分）に対して部分文字列マッチを行い、フルパスには行いません。 |
| `case_sensitive` | いいえ | `false` | `true` に設定すると大文字小文字を厳密に区別してマッチします。 |
候補セットは、ワークスペースモードでは `git ls-files --cached --others --exclude-standard` から、
区間 / commit モードでは `git ls-tree -r --name-only <ref>` から得られます。拡張子のないファイルは
スキップされますが、`Makefile`、`Dockerfile`、`LICENSE`、`Vagrantfile`、
`Containerfile` は例外です。
### 出力
改行区切りのパスのリスト：
```
src/main/java/com/example/UserService.java
src/test/java/com/example/UserServiceTest.java
src/main/java/com/example/internal/UserServiceImpl.java
```
マッチするファイルがない場合（または `query_name` が空の場合）、ツールはリテラル文字列
`// The file was not found` を返します。
### 制限
最大 **100** 件のマッチを返します。超過分は静かに切り詰められます。モデルがより広範な検索を必要とする場合は、
`code_search` を使用すべきです。
## `code_search`
リポジトリ全体の全文検索。`git grep` によって駆動されるため、`pathspec` 構文を理解し、
`.gitignore` に従います。
### Schema
```json
{
"name": "code_search",
"input": {
"search_text": "TODO|FIXME",
"file_patterns": ["*.go", ":(exclude)vendor/"],
"case_sensitive": false,
"use_perl_regexp": true
}
}
```
| フィールド | 必須 | デフォルト | 説明 |
|---|---|---|---|
| `search_text` | はい | — | リテラル文字列または PCRE パターン（`use_perl_regexp` を参照）。 |
| `file_patterns` | いいえ | リポジトリ全体 | pathspec エントリの配列。除外には `:(exclude)pat` を使用します。 |
| `case_sensitive` | いいえ | `false` | — |
| `use_perl_regexp` | いいえ | `false` | `true` の場合、`search_text` は正規表現として扱われます。 |
### 出力
結果はファイルごとにグループ化されます。各グループは `File: <path>` と `Match lines: <n>` で始まり、続いて各ヒットが
`line|content` の 1 行で表されます：
```
File: path/to/example.java
Match lines: 2
433| String name = toolRequest.get().getName();
438| logToolRequest(newPath, tool, toolRequest.get());
File: path/to/other.java
Match lines: 1
22| var req = new ToolRequest();
```
マッチがない場合、ツールはリテラル文字列 `No matches found` を返します。
### pathspec クイックリファレンス
| 目的 | `file_patterns` |
|---|---|
| 単一ファイル | `["src/main.go"]` |
| すべての Go ファイル | `["*.go"]` |
| テストを除くすべての Go | `["*.go", ":(exclude)*_test.go"]` |
| 単一のディレクトリのみ | `["src/api/"]` |
| 複数の種類、vendor を除外 | `["*.go", "*.ts", ":(exclude)vendor/", ":(exclude)node_modules/"]` |
### 制限
- `git grep --max-count 100` によってファイルごとのヒット数上限を **100** に設定するため、複数ファイルにまたがる
合計出力は 100 を超える可能性があります。ファイルごとの上限に達した場合、出力の前に
`Note: The results have been truncated. Only showing first 100 results.` が付加されます。
- 空 / 空白のみの `search_text` は、各行に展開されるのではなく `Error: search_text is blank` を返します。
- ワークスペースモードは**現在のワークツリー**を検索し、区間 / commit モードは解決された対象の ref を検索します
（`FileReader.Ref` が位置引数として `git grep` に渡されます）。
## ツールの実行とエラー
ツールは agent ループ内で同期的に実行されますが、2 つの例外があります：
- `code_comment` は **CommentWorkerPool** にディスパッチされ、ループが行の解析 + リフレクションでブロックしないようにします。
- `task_done` はショートサーキットします——即座に返され、いかなる provider も呼び出しません。
ツールがエラーになった場合（ネットワーク障害、引数の形式エラー、ファイル未検出）、結果は通常のツール結果としてモデルに配信され、
テキストは `"Error: file not found: src/missing.go"` のような形になります。モデルはその後、再試行するか、ファイルを変更するか、
`task_done` を呼ぶかを決定します。
ツール名がレジストリに存在しない場合、OCR はクラッシュせず定数 `tool.NotAvailableMsg` を返します。これにより、
（`--tools` を通じて）ランタイムでツールを無効化することが安全になります。
## ツールのカスタマイズ
拡張方法は 2 つあります：
### 1. ツールを無効化する
`tools.json` をコピーし、不要なエントリを削除してから実行します：
```bash
ocr review --tools ./my-tools.json
```
たとえば、追加のコンテキストを一切読み取らない「コメントのみ」のレビューアが欲しい場合は、`code_comment` と
`task_done` のみを残します。
### 2. ツールの説明を書き換える
`name` は保持し（provider は内部で name で検索します）、`description` を変更してモデルを誘導します。これは
プロジェクト固有のガイダンスを注入する最も簡単な方法です——たとえば「`file_read` を使う際は、常に変更付近の少なくとも
30 行を読み取ること。」のように。
> **新しい**ツール*名*を追加するには Go 側での対応が必要です。`internal/tool/definitions.go` および
> `internal/tool/` 配下の provider を参照してください。JSON ファイルだけでは新しい動作を追加できません。
## 関連項目
- [アーキテクチャ](../architecture/)——agent ループがどのようにツールを駆動するか。
- [レビュールール](../review-rules/)——LLM に何に注目すべきかを伝えます。
- [セッションビューア](../viewer/)——過去のレビューで実際にどのツールがトリガーされたかを確認します。

151
pages/src/content/docs/ja/viewer.md Normal file
View file

@ -0,0 +1,151 @@
---
title: セッションビューア
sidebar:
order: 10
---
`ocr viewer` は小型の組み込み HTTP サーバーで、過去のレビューセッションをブラウザで扱いやすい UI でレンダリングします。
外部依存はありません——セッションは、OCR が各レビュー中にディスクに書き込む JSONL ファイルから直接読み取られます。
## 起動
```bash
ocr viewer # binds localhost:5483
ocr viewer --addr :3000 # bind to all interfaces on port 3000
ocr viewer --addr 0.0.0.0:8080 # bind on all interfaces
```
デフォルトのアドレスは `localhost:5483` です。サーバーはフォアグラウンドで実行されます——`Ctrl+C` で停止します。セッションは各リクエスト時に
`~/.opencodereview/sessions/` から遅延スキャンされるため、別のターミナルで実行中のレビューも、その
JSONL ファイルが現れ次第表示されます。
> **DNS リバインディング対策。** ビューアは `Host` ヘッダーをループバックのホワイトリスト
> （`localhost`、`127.0.0.1`、`::1`）と照合します。具体的なバインドホスト
> （`--addr 192.168.1.10:5483` など）は自動的に追加されますが、**ワイルドカード**バインド
> （`:3000`、`0.0.0.0`、`::`）は追加されません——この場合、LAN IP やホスト名から UI にアクセスすると
> `forbidden host` が返されます。ワイルドカードバインドをアクセス可能にするには、
> `OCR_VIEWER_ALLOWED_HOSTS` にカンマ区切りの許可ホスト名リストを設定します
> （例：`OCR_VIEWER_ALLOWED_HOSTS=box.local,192.168.1.10`）。
## 3 つのページ
ビューアには 3 つの URL があります：
| URL | 表示内容 |
|---|---|
| `/` | ディスク上にセッションを持つすべてのリポジトリの一覧。 |
| `/r/{repo}` | 単一リポジトリのセッション一覧。最新が先頭。 |
| `/r/{repo}/{sessionID}` | 単一セッションの完全な詳細。 |
`{repo}` はパスエンコードされた文字列です（区切り文字 `/` と `\` は `-` に、コロンは
`_` に置換されます——ディスク上のディレクトリ命名と同じエンコード）。通常は手動で入力することはなく——クリックして遷移します。
### `/`——リポジトリ一覧
少なくとも 1 件のセッションを持つ各リポジトリについて、リポジトリパス、総セッション数、最新のアクティビティのタイムスタンプを表示します。
### `/r/{repo}`——単一リポジトリのセッション一覧
各セッションについて：ID（UUID）、ブランチ名（OCR が検出できた場合）、レビューモード、モデル、ファイル数、
所要時間、開始タイムスタンプ。
### `/r/{repo}/{sessionID}`——セッション詳細
詳細ページが最も有用です。以下を表示します：
1. **ヘッダー**——diff 範囲、モデル、ブランチ、合計 token、実行時間。
2. **ファイルごとのグループ**——レビューされた各ファイルにつき 1 ブロック。各ファイル内には、5 つの「タスクタイプ」のスイムレーン：
| タスクタイプ | 出現条件 |
|---|---|
| `plan_task` | plan フェーズが実行された（ファイルが ≥ `PLAN_MODE_LINE_THRESHOLD`）。 |
| `main_task` | すべてのファイル。メインのレビューループ。 |
| `review_filter_task` | そのファイルに対してレビュー後のコメントフィルタリング処理が実行された。 |
| `memory_compression_task` | active+compress 領域が予算の 60 % / 80 % を超えた。 |
| `re_location_task` | ある `code_comment` がアンカーできず、フォールバックの再位置特定が実行された。 |
各スイムレーンは**タスクカード**の水平ストリップです——LLM の往復 1 回につき 1 枚。カードはタスクタイプごとに色分けされており、
どのフェーズが実行を支配したかを一目で把握できます。
## タスクカードの中身
タスクカードをクリックすると展開されます。各カードには以下があります：
- 1 行の**ヘッダー**——リクエスト番号、モデルバッジ、token バッジ（`P:` prompt / `C:` completion、
存在する場合は `CR:` / `CW:` キャッシュの読み書きも表示）、所要時間バッジ、そしてそのラウンドが失敗した場合はエラーバッジ。
- **Response**——生の assistant レスポンス。推論 / `thinking` ブロックも含む。
- **Tool calls**——各ツール呼び出しとその引数 + 返された結果（折りたたみ可能）。
モデルに送信された完全なメッセージリストとスコープ内のツール定義は、カード UI には**レンダリングされません**。必要な場合は、直接
JSONL トランスクリプト（各 `llm_request` レコードの `messages` フィールド）を検査してください。
## ユースケース
ビューアは 3 つのワークフローを想定して設計されています：
### 「なぜモデルはこう言ったのか？」
ターミナル出力であるコメントを開き、ビューアでそのファイルを見つけ、その `main_task` スイムレーンを下にたどります。
**ツール呼び出し**の中に、あなたが気にしている `code_comment` を含むカードこそが、それを生み出したラウンドです。カードの
Response にはモデルの推論が表示されます。モデルに送信された prompt + コンテキストを正確に知るには、JSONL トランスクリプトで
そのリクエスト番号の `llm_request` レコード（その `messages` フィールド）を開いてください。
### 「なぜこのファイルは沈黙しているのか？」
**コメントのない**ファイルは、モデルが*能動的に* `task_done` を呼び出した場合にのみ成功したレビューです。スイムレーンに
ツール呼び出しはあるが `code_comment` がない場合、それはモデルが能動的に下したクリーンなレビューです。スイムレーンがエラーカードで終わっている場合、それは
沈黙を装った失敗です——警告として扱うべきです。
### 「圧縮は何を保持 / 破棄したのか？」
`memory_compression_task` スイムレーンは各圧縮ラウンドを表示します。その中で、Response ペインには結果の要約があり、
圧縮された compress 領域からレンダリングされた XML は、そのラウンドの `llm_request` の `messages`（JSONL トランスクリプト内）にあります。
「モデルが以前のコンテキストを忘れた」というフィードバックの調査に有用です——圧縮が関連する詳細を破棄したかどうかを確認できます。
## ディスクのストレージレイアウト
ビューアは以下を読み取ります：
```
~/.opencodereview/sessions/
└── <path-encoded-repo-path>/
└── <session-id>.jsonl
```
JSONL ファイルの各行は 1 つのイベントです：
```json
{"type": "llm_request", "filePath": "src/foo.go", "taskType": "main_task", "request_no": 1, "messages": [{"role": "user", "content": "Review this diff…"}], "timestamp": "2026-06-02T10:15:23Z"}
{"type": "llm_response", "filePath": "src/foo.go", "taskType": "main_task", "model": "claude-sonnet-4-6", "content": "Found 2 issues…", "duration_ms": 8421, "usage": {"prompt_tokens": 12450, "completion_tokens": 320}}
{"type": "tool_call", "filePath": "src/foo.go", "tool_name": "file_read", "arguments": "{\"file_path\":\"src/foo.go\",\"start_line\":1,\"end_line\":50}", "result": "File: src/foo.go (Total lines: 220)\nIS_TRUNCATED: false\nLINE_RANGE: 1-50\n1|package foo…", "ok": true, "duration_ms": 14}
```
行は追記専用（append-only）です——不完全な JSONL は、セッションが実行中に中断されたことを意味し、ビューアは書き込み済みの
内容をレンダリングします。
ディスク容量を解放するには、セッションファイル全体を削除します。ビューアは次のリクエスト時にインデックスを再構築します。
## プライバシー
JSONL トランスクリプトには、LLM に送信され LLM から受信した**すべて**が含まれ、diff 内のあらゆるコードも含まれます。これらは
完全にあなたのマシンの `~/.opencodereview/` 内に存在します。OCR はそれらをどこにもアップロードしません。
レビューに長期保存したくないコードが含まれる場合は、以下が可能です：
- 定期的にセッションファイルを削除する、または
- CI で `--audience agent --format json` の出力を一時的なパイプにリダイレクトし、一時的な
`HOME` で実行して JSONL が永続化されないようにする。
OpenTelemetry exporter は別の話です——prompt の内容をエクスポートされる trace に含めない方法については
[テレメトリ](../telemetry/)を参照してください。
## ビューアが*適さない*場合
- プログラムによる後処理（CI、ダッシュボード）には `ocr review --format json --audience agent` を使用します。
ビューアは人間向けのレンダリングであり、機械向けではありません。
- 複数セッションにまたがる grep が必要な場合は、JSONL ファイルに対して直接 `jq` を使用します。UI にはまだ検索ボックスがありません。
## 関連項目
- [アーキテクチャ](../architecture/)——それら 5 つのタスクタイプが内部で実際に何をするか。
- [ツール](../tools/)——`main_task` カードで目にするツール呼び出し。