# CLI の挙動
[English](cli_behavior.en.md)
この文書は、`asrch` の外部挙動を簡潔に固定する。プロジェクト全体の目標と非目標は `goals_and_condition.md` を正とする。
## 検索プロトコル
エージェントは、複数語を OR 正規表現へ結合して本文を読むのではなく、次の順序で探索する。
1. `survey` で複数の候補語を比較する。
2. 有効な単一語を選び、`scout` で分布を確認する。
3. パスを狭め、`sample` で代表的な近接一致クラスタを見る。
4. ファイルを特定し、`show` で少数の一致だけを詳しく見る。
## コマンド
| `survey` | 複数の固定検索語と候補パス | 語ごとの一致行数、ファイル数、有望なパスを比較する | 20 行 / 4,000 バイト |
| `scout` | 単一クエリ | 一致行数、ファイル数、上位ディレクトリ、上位ファイルを要約する | 15 行 / 4,000 バイト |
| `sample` | 単一クエリ | 近接一致をクラスタ化し、代表的な短い文脈を表示する | 20 行 / 6,000 バイト |
| `show` | 単一クエリと明示ファイル | 少数の一致を短い文脈付きで表示する | 30 行 / 8,000 バイト |
`count` と `terms` は提供しない。`count` は `scout` と役割が重複し、単純頻度集計の `terms` は広い検索でノイズを次の検索語として推奨しやすいためである。
全コマンドのハード上限は 40 行、8,000 バイトである。`show` の文脈は最大 5 行である。
## 複数語と OR
`survey` は `--term` を最大 12 回、候補パスを最大 8 個受け取り、各語と各パスの組み合わせを独立に検索する。一致本文は表示しない。
出力は TOON に寄せた形式で、`overall[term,matches,files,dominant_path]` と `by_path` の両方を含める。`overall` は語ごとの合計一致行数、合計ファイル数、最も一致が多いパスを示す。`by_path` はパスごとの語の分布を示すが、一致ゼロの語行は省略する。これにより、エージェントが reasoning で再集計しなくても、次に使う検索語とパスを同時に選べる。
`scout` も TOON に寄せ、メタ情報を `scout:` 以下に、分布を `top_directories[path,matches]` と `top_files[path,matches]` に出す。`sample` と `show` は本文 snippet の読みやすさを優先し、従来の形式を維持する。
一語が全候補語の一致行数合計の 80% 以上を占める場合、その語が比較を支配していることを警告する。固定文字列モードで 3 文字以下の語を受け取った場合は、意図外の部分一致を避けるため境界付き検索を提案する。
`scout`、`sample`、`show` は、`--regex` 指定時にエスケープされていない `|` を含むクエリを拒否する。任意の正規表現を完全に解析して OR を分解することは目的としない。
## 検索モード
検索語は既定で固定文字列として扱う。
- オプションなし: 固定文字列の部分一致
- `--identifier`: ASCII 識別子境界付き固定文字列
- `--word`: 単語境界付き固定文字列
- `--regex`: 明示的な正規表現。`survey` では使用不可
短い語や一般語を探す場合は、意図外の部分一致を避けるため `--identifier` または `--word` を優先する。
空の検索語は拒否する。
## `sample` の選択方法
`sample` は確率的なサンプリングを行わない。同じコマンドが同じ結果を返す決定性を優先する。
1. 一致をファイルごとにまとめる。
2. 2 行以内に近接する一致を同じクラスタとして扱う。
3. 各クラスタの先頭一致を代表とする。
4. クラスタが多いファイルでは、先頭・中央・末尾を優先する。
5. ファイル間をラウンドロビンし、各代表一致の前後 1 行を表示する。
`sample` は `--context` を受け付けない。文脈量を増やしたい場合は、ファイルを絞った後に `show <query> <file> --context N` を使う。
## `show` の制約
`show` は明示したファイルだけを受け付ける。ディレクトリは拒否する。一致行が 20 件を超える場合、または内部走査上限へ到達した場合は、本文を表示せず検索語を絞るよう要求する。
`show` は snippet 単位で出力する。次の snippet を開始する前に出力予算が残っていない場合は停止するが、開始した snippet は `--context` によって既定上限を少し超えても最後まで表示する。
## 広すぎる検索
一致行が 1,000 件を超える、または一致ファイルが 100 件を超える場合、検索が広いことを表示する。内部走査上限へ到達した場合は検索を停止し、件数を `at least` として表示する。
エージェントは、この表示を受けたら出力上限を増やすのではなく、検索語またはパスを絞る。
## 既定の除外
次のようなノイズの多い対象は、`rg` の glob と ignore 規則によって既定で除外する。
- `.git`、`target`、`node_modules`、`vendor`
- `dist`、`build`、`coverage`、`generated`
- `scratch`、`tmp`
- `*.log`、`*.jsonl`、`*.xml`、`*.min.js`、`*.map`
既定除外を解除する CLI オプションは提供しない。明示的なノイズ探索を簡単にすることより、通常のエージェント探索を安全にすることを優先する。