ローカルナレッジベース検索スキル（kb-retriever）

ナレッジベースディレクトリの説明

• ナレッジベースはルートディレクトリ下に保存され、複数のファイルタイプ（.md/.txt、.pdf、.xlsx など）を含み、通常は種類またはビジネス目的で複数レベルのサブディレクトリに分割されます。
• 階層的ディレクトリインデックスファイルを採用：
  • ルートディレクトリには data_structure.md ファイルがあり、主な「ドメインディレクトリ」とその用途を説明します。
  • 各ドメインディレクトリ下には独自の data_structure.md があり、該当ディレクトリ下のサブディレクトリ/ファイルと各自の用途を説明します。
  • さらに深いサブディレクトリもやはり data_structure.md を持つことができ、複数レベルのインデックスツリーを形成します。
• ナレッジベースルートディレクトリの約定：
  • デフォルトでは、ナレッジベースは現在のプロジェクトルートディレクトリ下の knowledge/ ディレクトリにあると見なされます。
  • ユーザーが対話で明確に他のパス（例：「私のナレッジベースは /data/kb にあります」または「./docs ディレクトリをナレッジベースとして使用してください」）を指定した場合は、ユーザーが指定したパスをルートディレクトリとします。
  • デフォルトパス knowledge/ が存在しないか、アクセスに失敗した場合は、実際のナレッジベースルートディレクトリの位置をユーザーに確認し、勝手に推測しないようにします。
• 個別のビジネスファイルは非常に大きい可能性があります：
  • Read を使用して直接ファイル全体を読み取らないでください
  • PDF、Excel に対応する Skill を使用して構造化処理を行った後、grep/局所読取と組み合わせて細かい検索を行います

knowledge ルートディレクトリの特定

• ルートディレクトリはユーザーを優先：ユーザーが（./docs、./knowledge-personal など）パスを指定した場合、ユーザーが提供したパスを直接使用してください。
• デフォルトルートディレクトリ：その他の場合、ルートディレクトリは現在のプロジェクト下の knowledge/ であるという約定があります。
  • Shell を使用してディレクトリが存在するかを明示的に確認：test -d knowledge を優先使用し、次点として ls -d knowledge を使用します。
  • 注意：Glob "knowledge" in . などのパターンを使用してディレクトリの存在を判定することは禁止されています。Glob はファイルパスのみを返し、ディレクトリ自体を返さず、空の結果は「ディレクトリが存在しない」と「ディレクトリが存在するが空である」を区別できません。
• ルートディレクトリが test -d などの方法で確認された場合にのみ、Glob を使用して該当ディレクトリ下のコンテンツを検索し、ディレクトリを path として使用します。例えば：
  • インデックスファイル：pattern="**/data_structure.md", path="knowledge"
  • すべての Markdown：pattern="**/*.md", path="knowledge"
• デフォルト knowledge/ が存在しない場合（test -d が失敗）：他のディレクトリを推測せず、デフォルトルートディレクトリが見つからないことをユーザーに明確に伝え、ユーザーに実際のナレッジベースパスを指定してもらいます。

重要な原則：学習してから処理

PDF または Excel ファイルに遭遇した場合の強制チェックリスト：

• ✅ 対応する references ドキュメントを読んで処理方法を学習しました
• ✅ 推奨されるツールとコマンドを理解しました
• ✅ ファイル処理（抽出/変換）を完了しました
• ⏭️ これで検索を始められます

禁止事項：

• ❌ pdf_reading.md を読まずに直接 PDF を処理しようとする
• ❌ excel_reading.md を読まずに直接 Excel を処理しようとする
• ❌ ファイル処理ステップをスキップして、元の PDF/Excel を直接検索する

全体的なフロー

1. ユーザーのニーズを理解する

   • ユーザーの質問を読み、以下を抽出します：
     • 主題/ドメインキーワード（例：「販売レポート」「システムアーキテクチャ」「インターフェースドキュメント」）
     • 時間または範囲制限（例：「2023年Q1」「最新バージョン」）
     • 必要な出力タイプ（説明、要約、具体的なフィールド値など）
   • ナレッジベースルートディレクトリを決定：
     • ユーザーが質問で指定したかどうかをまず確認してください。
     • そうでない場合は、デフォルトルートディレクトリ knowledge/ を使用します。
     • デフォルトルートディレクトリが存在しないか、ディレクトリ構造が異常な場合は、ユーザーに確認を求め、勝手に推測しないようにします。

2. 階層的にディレクトリインデックス data_structure.md を表示

   • 「現在の作業ディレクトリ」の概念を使用：
     • デフォルトはユーザーが指定したナレッジベースルートディレクトリから開始；ユーザーが指定しない場合は、現在のディレクトリを使用します。
   • 現在の作業ディレクトリに data_structure.md が存在する場合：
     • Read を使用してファイルの最初の数行（例：limit=300）を読み取り、必要に応じて段階的に続きを読み取ります。
     • 目的：
       • 現在のディレクトリにどのようなサブディレクトリとファイルがあるかを理解する
       • 各サブディレクトリ/ファイルの用途説明を理解する
     • ユーザーの質問に基づいて、最も関連する複数のサブディレクトリまたはファイルを選択して、候補セットを構成します。
   • 候補サブディレクトリの場合：
     • 該当サブディレクトリに再帰的に入り、それを新しい「現在の作業ディレクトリ」として、その中の data_structure.md を探して上記のプロセスを繰り返します。
     • 再帰プロセス中は、すべてのブランチに一度に深く入ることは避け、問題に最も関連するパスに沿って優先的にドリルダウンします。
   • 候補ビジネスファイル（md/テキスト、PDF、Excel など）の場合：
     • 必要なディレクトリレベルの探索を完了した後、これらのファイルを最終的な検索対象リストとして収集します。
   • 優先順位のソート時：
     • 用途説明が問題のテーマと高度に一致するドメインディレクトリとファイルを優先選択してください
     • 次に時間/バージョンなどの制約を検討してください（インデックスに表示されている場合）
     • 一般的な説明ドキュメント（README.md、全体設計ドキュメントなど）は優先度の後の位置に置きます

3. ファイル処理方法を学習する（PDF/Excel に遭遇した場合は強制実行）

   • PDF ファイルを処理する前に：
     • 必ず先に読む references/pdf_reading.md（このディレクトリは Skills ディレクトリ下にあり、Knowledge ディレクトリ下ではないことに注意）抽出方法を学びます
     • 重点：pdftotext コマンド、pdfplumber の使用方法、テーブル抽出方法
   • Excel ファイルを処理する前に：
     • 必ず先に読む references/excel_reading.md読取方法を学びます
     • 必ず先に読む references/excel_analysis.md分析方法を学びます
     • 重点：pandas による読取、列フィルタリング、データフィルタリング
   • 目的：正しいツールと方法を使用して、盲目的な検索を避けます

4. ファイルタイプに応じた処理と検索を実行

   • 学んだ方法を使用してファイルを処理します（抽出、変換、構造化）
   • 各候補ファイルタイプについて、以下の「Markdown/テキスト」「PDF」「Excel」戦略を実行します
   • 全般的な原則：
     • 最も関連性が高く、最も正確なファイルから優先的に開始してください
     • 各ファイル内でも段階的に局所検索を行い、全コンテンツの一括読取を避けます
     • 現在のファイルで満足できる情報が得られない場合は、次の候補ファイルに切り替えます

5. 反復検索

   • すべてのファイルタイプは統一的な「複数ラウンド反復検索メカニズム」を使用します（上記の一般的な検索原則を参照）

6. 回答の組織化と情報源の確認

   • 複数ラウンドの検索で得られたコンテキストを集約し、ユーザーの質問に統合的に回答します。
   • 以下のようにします：
     • 明確で直接的な回答を提供する
     • 使用したファイル名を指摘します（必要に応じてセクションまたは大まかな行数/ページ数を含める）
   • 回答が推論または不完全な情報に基づいている場合：
     • 仮定と不確実性を明示的にマークしてください
     • ユーザーがより具体的なファイル範囲またはキーワードで補足できることを示唆します

共通検索原則

キーワード選択戦略

• ユーザーの質問から 3～8 個のキーワードを抽出します（英文の略語や同義語、上位/下位語を含む）
• キーワードを組み合わせることができます（例：「販売 レポート」、「API インターフェース タイムアウト」）
• 必要に応じてビジネス用語、技術用語、一般的な略語を含めます（例：「uv」、「pv」、「GMV」）

grep 検索の基本原則

• 常にできるだけ正確な include と path を指定し、ディレクトリ全体の検索を避けます
• パターンは問題の中核的な名詞や用語を優先的に試し、その後同義語を試します
• 各ヒットについては、マッチの近くの局所範囲のみを読み取ります（前後数行）
• 「ファイル名 + 位置情報 + テキスト断片」を保存します

複数ラウンド反復検索メカニズム（最大 5 回）

すべてのファイルタイプは統一的な反復戦略を使用します：

1. 反復制御
   • 「試みられた検索回数」カウンタを保持し、最大 5 回です
   • 各検索後にカウンタをインクリメントします
2. 各ラウンド反復フロー
   1. 質問に基づいて検索キーワードを生成/更新します（同義語や拡張語を含む）
   2. まだ十分に検索されていないファイルまたはファイルの一部を選択します
   3. 検索を実行します（grep/局所読取/専用 Skill 呼び出し）
   4. 取得したコンテキスト断片を分析します
   5. 質問に回答するのに十分かを判定します
3. 終了条件
   • 回答をサポートするのに十分なコンテキストを見つけた；または
   • 5 回の試みに達しても適切な情報が見つからなかった
4. 情報不足の場合の処理
   • ユーザーに情報が不足しているか、現在のナレッジベースにない可能性があることを明確に伝えます
   • 見つかった最も近い情報を提供し、不確実性を説明してください
   • ユーザーが範囲を縮小できる方法を提示します（より具体的なファイル名、キーワード、時間範囲など）

注意事項

• 禁止：最初から直接 Glob "knowledge" in . を呼び出すか、Glob を使用してディレクトリの存在を判定しようとするいかなる呼び出し。ディレクトリの存在は Shell コマンド（test -d など）で確認する必要があります。
• このスキルを使用してナレッジベースをクエリする場合、ネット検索などの他のツールを使用してナレッジベースを取得することは禁止されています

異なるファイルタイプに対する具体的な戦略

1. Markdown / テキストファイル（.md, .txt, .log など）

1. 候補ファイルの選択

   • data_structure.md とファイル名、パスから関連度を判定します
   • タイトルと目次タイプのファイルを優先的に検索します（要約ドキュメント、設計概要など）

2. grep によるロケーション及び局所読取

   • Grep ツールを指定された候補ファイルに使用し、include を特定のサフィックスに制限します（例：「*.md」）
   • マッチするファイルについては、Read を使用してマッチの近くの局所範囲のみを読み取ります：
     • 行番号のオフセットと limit を使用して読取を制御します（例えば、マッチ行の近くから前後それぞれ数十行を読み取ります）
     • ファイル全体の読取を避けます

3. 特殊処理

   • コンテンツが単なる目次/タイトルのみの場合、リンクまたはセクション名に基づいて深い内容のロケーションを続けます
   • 「複数ラウンド反復検索メカニズム」を適用します（上記の一般的な検索原則を参照）

2. PDF ファイル検索戦略

ワークフロー：

1. まず：処理方法ガイドを読む

   • PDF を処理する前に、必ず先に読む references/pdf_reading.md（このディレクトリは Skills ディレクトリ下にあり、Knowledge ディレクトリ下ではないことに注意）
   • 重点：pdftotext コマンド、pdfplumber の使用方法、テーブル抽出方法、高速決定表

2. 候補 PDF を選択

   • data_structure.md の説明に基づいて、最も関連する 1～3 個のファイルを選択してください
   • ユーザーが特定の PDF ファイルを指定した場合は、そのファイルを優先してください

3. 学んだ方法を適用してテキストを抽出

   • pdf_reading.md で推奨されるツールを使用します（pdftotext または pdfplumber を優先）
   • 重要：pdftotext input.pdf output.txt を使用してテキストをファイルに抽出し、stdout に直接出力しないでください（大量のトークンを占有するのを避けるため）
   • テーブルを抽出する必要がある場合は、pdfplumber のテーブル抽出機能を使用します

4. 抽出結果に対して検索を実行

   • grep を使用して抽出されたテキストに対してキーワード検索を実行します
   • 各ヒットについて、ヒット周辺の範囲のコンテキストを抽出します（前後数十行または隣接する数ページ）
   • 「ファイル名 + ページ番号/大まかな位置 + テキスト断片」を保存します
   • 「複数ラウンド反復検索メカニズム」を適用します（上記の一般的な検索原則を参照）

3. Excel ファイル検索戦略

ワークフロー：

1. まず：処理方法ガイドを読む

   • Excel を処理する前に、必ず先に読む：
     • references/excel_reading.md - ワークシートの読み方を学びます（このディレクトリは Skills ディレクトリ下にあり、Knowledge ディレクトリ下ではないことに注意）
     • references/excel_analysis.md - データの分析方法を学びます（このディレクトリは Skills ディレクトリ下にあり、Knowledge ディレクトリ下ではないことに注意）
   • 重点：pandas 読取方法、列フィルタリング、データフィルタリング、集約操作

2. 候補 Excel を選択

   • data_structure.md とファイル/ワークシート名に基づいて、最も関連するテーブルを選択してください
   • 「レポート」「統計」「ログ」「設定」「マッピング」などのキーワードを含むワークブック/ワークシートを優先してください
   • ユーザーが特定の Excel ファイルを指定した場合は、そのファイルを優先してください

3. 学んだ方法を適用して構造を探索

   • pandas を使用して最初の 10～50 行を読み取ります（nrows パラメータで制限）
   • 重点：列名/フィールド名、データタイプ（数値、日付、テキスト）、重要フィールド
   • 列名をユーザーの質問と比較し、潜在的な重要フィールドを特定します（例：「収入」「販売額」「error_code」など）

4. データ検索と分析を実行

   • 学んだ pandas メソッドを使用してフィルタリングと集約を実行します（例：df[df['column'] == value]）
   • 毎回マッチ行の近くのデータのみを読み取り、テーブル全体の一括読取を避けます
   • 質問に時間範囲が含まれている場合は、検索に時間フィルタリングを追加してください
   • 「複数ラウンド反復検索メカニズム」を適用します（上記の一般的な検索原則を参照）

他のツールとの協力

PDF 処理

• PDF を処理する前に必ず先に読む references/pdf_reading.md 処理方法を学びます
• pdfplumber/pypdf を使用してテキスト抽出、テーブル抽出、メタデータ読取を実行します
• pdftotext コマンドラインツールを優先的に使用して高速テキスト抽出を行います

Excel 処理

• Excel を処理する前に必ず先に読む：
  • references/excel_reading.md - 読取方法を学びます
  • references/excel_analysis.md - 分析方法を学びます
• pandas を使用してデータ探索、プレビュー、フィルタリング、分析を実行します

ツール使用の原則

• Grep：指定されたファイルでキーワードで行番号とマッチ断片を検索するために使用します。常に正確な include と path を指定します
• Read：ファイルの局所読取にのみ使用します。常に合理的な limit（例：200～500 行）と適切なオフセットを設定します
• 非常に大きい可能性のあるファイルについて：
  • 最初から最後まで直接読み取ることは禁止されています
  • インデックス、目次、キーワードなどを使用して範囲を縮小した後に読み取ります

回答スタイルとエラー処理

• 回答スタイル
  • ユーザーの質問言語（中国語/英語）を使用して回答するようにしてください。
  • まず結論を示し、次に簡潔な根拠を示します。
  • 必要に応じて、引用されたファイルと大まかな位置をリストに示すことができます。例えば：
    • ソース：design/api_gateway.md 行 100 の付近
    • ソース：reports/2023_Q1_sales.xlsx Summary ワークシート
• 情報不足または不確実の場合
  • 現在のナレッジベースで完全に一致する情報が見つからないか、部分的にのみ回答できることを明確に述べます。
  • 事実を作り出さないでください。
  • ユーザーが範囲を縮小できる方法をヒントで示します：
    • より具体的なディレクトリ/ファイルを指定してください
    • より正確なキーワードまたはフィールド名を提供します
    • 時間/バージョン範囲を指定してください