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

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

• ナレッジベースは1つのルートディレクトリ下に格納されており、さまざまなファイル形式（例： .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/。
  • シェルを使用してディレクトリの存在を明示的に確認する：優先的に 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年第1四半期」「最新バージョン」）
     • 必要な出力形式（解説、要約、具体的なフィールド値など）
   • ナレッジベースのルートディレクトリを特定する：
     • まず、ユーザーが質問の中でナレッジベースのパスを指定しているかどうかを確認する。
     • 指定されていない場合は、デフォルトのルートディレクトリを使用する 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 を読むこと（このディレクトリは Knowledge ディレクトリではなく、Skills ディレクトリ下にあることに注意）抽出方法を習得する
     • 重点的に理解すべき点：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 を指定し、ディレクトリ全体の検索は避ける
• pattern では、まず問題文中の核心となる名詞や用語を試み、次に同義語を試す
• 各ヒットについては、一致した箇所周辺の局所的な領域（上下数行）のみを読み取る
• 「ファイル名 + 位置情報 + テキスト断片」を保存する

複数回の反復検索メカニズム（最大5回）

すべてのファイルタイプに対して統一された反復戦略を採用する：

1. 反復制御
   • 「検索試行回数」をカウントし、最大5回までとする
   • 検索のたびにカウントを累積
2. 各反復のプロセス
   1. 問題に基づいて検索キーワードを生成／更新する（同義語や拡張語を含む場合あり）
   2. まだ十分に検索されていないファイルまたはファイルの一部を選択する
   3. 検索を実行（grep／部分読み取り／専用Skillの呼び出し）
   4. 取得した文脈の断片を分析
   5. 質問への回答として十分かどうかを判断する
3. 終了条件
   • 回答を裏付けるのに十分なコンテキストが見つかった場合、または
   • 5回の試行を経ても適切な情報が見つからない
4. 情報が不足している場合の処理
   • ユーザーに対し、情報が不足していること、または現在のナレッジベースには存在しない可能性があることを明確に伝える
   • 見つかった中で最も近い情報を提供し、不確実性について説明する
   • ユーザーが検索範囲を絞り込む方法（より具体的なファイル名、キーワード、期間など）を提示する

注意事項

• 初回から直接以下の呼び出しを行うことは禁止する：Glob "knowledge" in . またはGlobを使用してディレクトリの存在を確認しようとする呼び出しは一切禁止する。ディレクトリの存在確認は、シェルコマンド（例： test -d）を介して確認してください。
• 本Skillを使用してナレッジベースを検索する際、ウェブ検索などの他のツールを使用して情報を取得することは禁止されています

ファイルタイプごとの具体的な方針

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 を読むこと（このディレクトリは Knowledge ディレクトリではなく、Skills ディレクトリ内にあることに注意）
   • 重点的に理解すべき点：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 - ワークシートの読み取り方法を学ぶ（このディレクトリは Knowledge ディレクトリではなく、Skills ディレクトリ内にあることに注意）
     • references/excel_analysis.md - データの分析方法を学ぶ（このディレクトリは Knowledge ディレクトリではなく、Skills ディレクトリ内にあることに注意）
   • 重点的に理解すべき点：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」シート
• 情報が不足している、または不確かな場合
  • 現在のナレッジベースに完全に一致する情報が見つからないこと、または部分的な回答しかできないことを明確に説明します。
  • 事実をでっち上げないでください。
  • ユーザーに、検索範囲を絞り込むためのヒントを提供する：
    • より具体的なディレクトリやファイルを指定する
    • より正確なキーワードやフィールド名を提供する
    • 期間やバージョンの範囲を指定する