手元の文書をキーワードと意味で探す検索CLIを作る

## ランタイムを1つに決め、コマンドごとの役割を分ける サポート対象のランタイムとパッケージマネージャーを1組選び、正規の開発経路とする。互換性がありそうというだけで、代替ランタイムやインストールコマンドを混在させない。 コマンドの責務を明確に保つ。 - コレクションコマンドは、インデックス対象のルートとその設定を管理する。 - コンテキストコマンドは、検索の手引きをパスへ付与する。 - 取得コマンドは、既知の文書を返す。 - 検索コマンドは、候補文書を順位付けする。 - メンテナンスコマンドは、インデックスを検査または更新する。 - サービスコマンドは、同じ機能を別のプロセスへ提供する。 インストール済みのコマンドラッパーがコンパイル済みアプリケーションコードを呼び出す構成なら、そのラッパーを維持する。文書化されたコンパイラーワークフローでソースをビルドし、ネイティブ拡張が既存の配置に依存する場合は、ラッパーを単一のコンパイル済み実行ファイルへ置き換えない。 ## コレクションごとの設定を持ち、除外と登録解除を分ける 各コレクションを、一意の名前、ソースルート、ファイルマスク、対象化状態、任意の更新前フックで表す。 コレクションの登録、一覧表示、検査、名称変更、対象化、除外、登録解除を支援する。登録解除と除外を区別する。登録解除はコレクション登録そのものを取り消し、除外はスコープ未指定のクエリから省くだけである。 コレクション全体またはパス接頭辞を対象に、ファイル一覧を取得できるようにする。インターフェースが対応している場合は、通常のコレクションパスとツールの仮想コレクションURIの両方を受け付ける。 登録、登録解除、名称変更、フック変更、対象化状態の変更、インデックス更新は、状態変更として扱う。利用者の承認が必要な場合は、実行前に正確なコマンドと想定される影響を示す。 ## 検索の手引き（コンテキスト）を、文書と分けてパスごとに付ける 人が記述したコンテキストは文書内容と分けて保存し、ソースファイルを書き換えずにランキングの手引きを更新できるようにする。 次の場所へコンテキストを設定できるようにする。 - コレクション内で検出された現在のディレクトリ。 - 特定のサブパス。 - 仮想コレクションパス。 - すべてのコレクションへ適用する手引きのためのグローバルルート。 コンテキストの一覧表示、コンテキストがないパスの検出、古くなったコンテキストの取り外しを行うコマンドを用意する。グローバルな手引きを維持しながら、関連する最も限定的なコンテキストを適用する。 コンテキストメタデータとインデックス対象の文書テキストを混同しない。ローカルな注記が無関係なコレクションへ暗黙に影響しないよう、スコープを可視化する。 ## 文書に短いIDを付け、取り出す量に上限を設ける 各文書へ、内容ハッシュの先頭6文字から導出した短い識別子を割り当てる。検索結果にその識別子を表示し、先頭マーカーの有無にかかわらず受け付ける。 パスまたは識別子による取得、任意の開始行と行数、globまたはカンマ区切りリストによる一括取得を支援する。 取得には明示的な上限を設ける。 - ファイルごとの最大行数を設定する。 - 最大バイト数を設定し、10 KBなどの既定値を文書化する。 - 大きすぎるファイルは、通知なしで内容の一部を返さず、対象から外す。 - 行番号は既定で付け、呼び出し側が無効にできるようにする。 - ディスク上の完全なパスは、要求された場合に限って返す。 ## 探し方に合う検索の種類を選び、ふだんはハイブリッド検索を使う 次の3つの異なる検索経路を提供する。 - 言語モデルを使わず、BM25などの全文ランキングを用いるキーワード検索。 - リランキングを行わず、ローカル埋め込みを用いるベクトル類似検索。 - 高品質な既定経路として、クエリ拡張とリランキングを用いる拡張ハイブリッドクエリ検索。 独立して順位付けされた結果集合は、Reciprocal Rank Fusionで統合する。想定外の順位を診断できるよう、元のスコアと検索方式を十分に可視化しておく。 通常用途ではハイブリッドクエリ経路を優先する。完全一致する用語が重要ならキーワード検索、意味的類似性が目的ならベクトル検索、最終的な順位品質より速度を重視するならリランキングなしの選択肢を使う。 ## 検索するコレクションと出力形式を選べるようにし、表示で結果を変えない 呼び出し側がコレクションフィルターを繰り返し指定し、名前を挙げた複数のコレクションだけを検索できるようにする。結果件数、全結果モード、最小スコア、全文モード、ランキングを明確にする目的記述を支援する。 表示とデータ転送を分離する。読みやすいコマンドライン形式に加え、構造化されたJSON、CSV、Markdown、XML、ファイル一覧の各形式を提供する。従来の形式フラグは、1つの正規形式オプションに対する別名としてのみ維持する。 一括取得では、行数上限、バイト数上限、行番号制御を検索ランキングとは独立して公開する。表示オプションによって、選択される文書を変えない。 ## 検索インデックスを作り、文書を決まった大きさのチャンクに分ける 全文インデックスには永続的なローカルデータベースを使い、意味的類似検索には互換性のあるベクトル拡張を使う。埋め込み、リランキング、クエリ拡張は、設定済みのローカルモデルで実行する。 文書を賢く分割し、1チャンクあたり900トークン、15%のオーバーラップを目標にする。可能な場合はMarkdown見出しを境界として優先する。 対応するコードファイルには抽象構文木を認識する方式を用意し、チャンクを関数、クラス、インポートの境界へ合わせる。明示的な自動戦略でこの方式を選択する。正規表現による分割を既定とし、Markdownと未知のファイル形式には一貫して適用する。 すべてを再構築しなくても障害を診断できるよう、インデックス作成、埋め込み生成、クエリ時ランキングを別々の段階として保つ。 ## 順位を調整する前に、インデックスとモデルの状態を確かめる 状態を変更せず、コレクションとインデックスの健全性を示す状態情報を提供する。設定、インデックス、モデル、デバイスの問題を調べる診断コマンドを追加する。 バージョン管理したフィクスチャファイルで検索品質を測定する。比較を再現できるよう、クエリ、正解として期待する関連文書、検索方式、ランキング指標、モデル設定、インデックスバージョンを記録する。 ランキングの重み、モデル、デバイス設定を変える前に診断を行う。モデルの欠損、古いインデックス、互換性のないベクトル拡張、利用できないデバイスは、それ自体ではランキングアルゴリズムが誤っている証拠にならない。 ## 頼まれた時だけ、ツールをローカルやHTTPのサービスとして動かす ローカルプロセス連携には標準入出力サービスを提供し、リモートクライアントには任意のHTTPサービスを提供する。明示的な上書きを許可しつつ、8181などの文書化された既定ポートを使う。 デバッグ用のフォアグラウンド動作と、長時間利用向けのバックグラウンドデーモンモードを支援する。管理対象のデーモンだけを停止する、対応する停止コマンドを用意する。 サービス転送方式と検索の意味を分離する。コマンドラインインターフェースとサービスインターフェースで、コレクション、コンテキスト、取得、ランキング、出力の規則を共有する。 バックグラウンドサービスを暗黙に起動しない。サービスを起動した時は、エンドポイント、プロセスモード、設定元、停止方法を報告する。 ## インデックスを変える操作は利用者に任せ、インストール済みのラッパーを壊さない コレクションの登録、埋め込みの生成、インデックス更新を自動で行わない。基盤となる検索データベースを直接変更しない。 依頼されたワークフローでこれらの変更が必要な場合は、利用者が実行する正確なコマンドを示し、想定されるファイル、所要時間、リソース使用量を説明する。許可範囲を広げず、読み取り専用の検索と取得を利用可能に保つ。 インストール済みのシェルラッパーを上書きしたり、ネイティブなベクトル拡張を壊したりするコンパイル方式を実行しない。配布ディレクトリからコンパイル済みJavaScriptを意図的に起動するラッパーを置き換えない。 更新前フックは実行可能な設定として扱う。検査時に表示し、明示的に依頼されたインデックス更新の一部としてのみ実行する。 ## 回帰テストを足し、変更履歴を付けてリリースする 自動テストは指定されたテストツリーに置き、サポート対象のランタイムで文書化された完全なテストスイートを実行する。コレクション状態、取得上限、ランキング方式、チャンク境界、サービスのライフサイクルについて、対象を絞った回帰テストを追加する。 リリースを手作業で組み立てず、正規のリリースワークフローを使う。 1. 変更を加えるたびに、未リリースセクションへ変更履歴の項目を追加する。 2. リリース時に、そのセクションを日付付きバージョンへ変換する。 3. プロジェクトで定められた参照形式を使い、外部からの貢献者を明記する。 4. 対象とするバージョン系列全体のリリースノートを集約する。 5. 配布前にリリースフックと検証を実行する。 変更した動作、インデックスまたはスキーマの互換性、実行したテスト、ベンチマークへの影響、移行の必要性、利用者に委ねた状態変更コマンドを報告する。