kb-retriever

本地知識庫檢索 Skill（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，避免搜索整個目錄
• pattern 優先嘗試問題中的核心名詞、術語，再嘗試同義詞
• 對於每個命中，只讀取匹配附近的局部區域（上下若干行）
• 保存「文件名 + 位置信息 + 文本片段」

多輪迭代檢索機制（最多 5 次）

所有文件類型都採用統一的迭代策略：

1. 迭代控制
   • 維護「已嘗試檢索次數」計數，最多 5 次
   • 每次檢索後累加計數
2. 每輪迭代流程
   1. 基於問題生成/更新檢索關鍵詞（可包括同義詞、擴展詞）
   2. 選擇尚未充分檢索的文件或文件部分
   3. 執行檢索（grep/局部讀取/專用 Skill 調用）
   4. 分析獲取的上下文片段
   5. 判斷是否足夠回答問題
3. 終止條件
   • 找到足夠支撐回答的上下文；或
   • 已達到 5 次嘗試仍未找到合適信息
4. 信息不足時的處理
   • 明確告知用戶信息缺失或可能不在當前知識庫中
   • 提供已找到的最接近信息，並說明不確定性
   • 提示用戶可以如何縮小範圍（更具體的文件名、關鍵詞、時間範圍等）

注意事項

• 禁止第一次就直接調用：Glob "knowledge" in . 或任何試圖用 Glob 判定目錄存在性的調用，目錄存在性應通過 shell 命令（如 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（注意這個目錄位於 Skills 目錄下，而不是 Knowledge 目錄下）
   • 重點了解：pdftotext 命令、pdfplumber 用法、表格提取方法、快速決策表

2. 選擇候選 PDF

   • 根據 data_structure.md 中的描述，選擇最相關的 1-3 個文件
   • 如果用戶指明具體 PDF 文件，則優先使用該文件

3. 應用學到的方法提取文本

   • 使用 pdf_reading.md 中推薦的工具（優先 pdftotext 或 pdfplumber）
   • 重要：使用 pdftotext input.pdf output.txt 將文本提取到文件，不要直接輸出到 stdout（避免佔用大量 token）
   • 如需提取表格，使用 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 工作表
• 信息缺失或不確定時
  • 明確說明在當前知識庫中沒有找到完全匹配的信息或只能部分回答。
  • 不臆造事實。
  • 提示用戶可以如何幫助縮小範圍：
    • 指定更具體的目錄/文件
    • 提供更精確的關鍵詞或字段名
    • 指定時間/版本範圍