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 進行檢索

總體流程

理解使用者需求
- 讀使用者問題，提取：
  - 主題/領域關鍵詞（如「銷售報表」「系統架構」「介面文件」）
  - 時間或範圍限定（如「2023 年 Q1」「最近版本」）
  - 需要的輸出類型（解釋、摘要、具體欄位數值等）
- 確定知識庫根目錄：
  - 優先檢查使用者是否在問題中指定了知識庫路徑。
  - 否則使用預設根目錄 knowledge/。
  - 若預設根目錄不存在或目錄結構異常，應向使用者詢問確認，而不是自行假設。
分層查看目錄索引 data_structure.md
- 使用一個「當前工作目錄」的概念：
  - 預設從使用者指定的知識庫根目錄開始；如果使用者未指定，則使用當前目錄。
- 在當前工作目錄下，如果存在 data_structure.md：
  - 使用 Read 讀取該檔案的前若干行（例如 limit=300），必要時分段繼續讀取。
  - 目標：
    - 了解當前目錄下有哪些子目錄和檔案
    - 理解每個子目錄/檔案的用途說明
  - 基於使用者問題，挑選最相關的若干個子目錄或檔案，構成候選集合。
- 對於候選子目錄：
  - 遞迴進入該子目錄，將其作為新的「當前工作目錄」，繼續查找其中的 data_structure.md 並重複上述過程。
  - 在遞迴過程中，避免一次性深入所有分支，優先沿著與問題最相關的路徑向下鑽取。
- 對於候選業務檔案（md/文字、PDF、Excel 等）：
  - 在完成必要的目錄層級探索後，收集這些檔案為最終的檢索目標列表。
- 在優先級排序時：
  - 優先選擇用途說明與問題主題高度匹配的領域目錄和檔案
  - 其次考慮時間/版本等約束（如果索引中有體現）
  - 通用說明類文件（如 README.md、總體設計類文件）放在較後優先級
學習檔案處理方法（遇到 PDF/Excel 時強制執行）
- 在處理 PDF 檔案前：
  - 必須先讀取 references/pdf_reading.md（注意這個目錄位於 Skills 目錄下，而不是 Knowledge 目錄下）學習提取方法
  - 重點了解：pdftotext 命令、pdfplumber 用法、表格提取方法
- 在處理 Excel 檔案前：
  - 必須先讀取 references/excel_reading.md學習讀取方法
  - 必須先讀取 references/excel_analysis.md學習分析方法
  - 重點了解：pandas 讀取、欄位篩選、資料過濾
- 目的：確保使用正確的工具和方法，避免盲目檢索
按檔案類型執行處理和檢索
- 使用剛學到的方法處理檔案（提取、轉換、結構化）
- 對每類候選檔案，按照下面「Markdown/文字」「PDF」「Excel」策略執行
- 總原則：
  - 優先從最相關、最精確的檔案開始
  - 每個檔案內都漸進式地局部檢索，避免一次性載入全內容
  - 若當前檔案得不到滿意資訊，切換到下一個候選檔案
迭代檢索
- 所有檔案類型都使用統一的「多輪迭代檢索機制」（見上文公共檢索原則）
答案組織與溯源
- 彙總多輪檢索得到的上下文，綜合回答使用者問題。
- 盡量：
  - 給出清晰、直接的回答
  - 指出使用過的檔案名稱（必要時包含大致位置，如章節或大概行數/頁數）
- 如果答案基於推斷或資訊不完全：
  - 明確標註假設與不確定性
  - 提示使用者可以補充更具體的檔案範圍或關鍵詞

公共檢索原則

關鍵詞選擇策略

從使用者問題提取 3-8 個關鍵詞（含可能的英文縮寫、同義詞、上位/下位詞）
可組合詞組（如「銷售報表」、「API 介面逾時」）
必要時包含業務詞、技術術語、常見縮寫（如「uv」、「pv」、「GMV」）

grep 檢索基本原則

始終指定盡量精準的 include 和 path，避免搜尋整個目錄
pattern 優先嘗試問題中的核心名詞、術語，再嘗試同義詞
對於每個命中，只讀取匹配附近的局部區域（上下若干行）
保存「檔案名稱 + 位置資訊 + 文字片段」

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

所有檔案類型都採用統一的迭代策略：

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

注意事項

禁止第一次就直接呼叫：Glob "knowledge" in . 或任何試圖用 Glob 判定目錄存在性的呼叫，目錄存在性應透過 shell 命令（如 test -d）檢查。
使用本 Skill 查詢知識庫時，禁止使用網路搜尋等其他工具取得知識

針對不同檔案類型的具體策略

1. Markdown / 文字類檔案（.md, .txt, .log 等）

候選檔案選擇
- 根據 data_structure.md 和檔案名稱、路徑判斷相關度
- 優先檢索標題和目錄類檔案（如彙總文件、設計總覽）
grep 定位與局部讀取
- 使用 Grep 工具對指定候選檔案，include 限定具體副檔名（如 "*.md"）
- 對於有匹配的檔案，使用 Read 僅讀取匹配附近的局部區域：
  - 透過行號偏移和 limit 控制讀取（例如從匹配行附近往前後各讀取幾十行）
  - 避免整檔案讀取
特殊處理
- 如內容僅是目錄/標題，根據連結或小節名稱繼續定位深入內容
- 應用「多輪迭代檢索機制」（見上文公共檢索原則）

2. PDF 檔案檢索策略

工作流：

首先：讀取處理方法指南
- 在處理任何 PDF 之前，必須先讀取 references/pdf_reading.md（注意這個目錄位於 Skills 目錄下，而不是 Knowledge 目錄下）
- 重點了解：pdftotext 命令、pdfplumber 用法、表格提取方法、快速決策表
選擇候選 PDF
- 根據 data_structure.md 中的描述，選擇最相關的 1-3 個檔案
- 如果使用者指明具體 PDF 檔案，則優先使用該檔案
應用學到的方法提取文字
- 使用 pdf_reading.md 中推薦的工具（優先 pdftotext 或 pdfplumber）
- 重要：使用 pdftotext input.pdf output.txt 將文字提取到檔案，不要直接輸出到 stdout（避免佔用大量 token）
- 如需提取表格，使用 pdfplumber 的表格提取功能
對提取結果執行檢索
- 使用 grep 對提取的文字進行關鍵詞搜尋
- 對於每個命中，提取命中附近範圍的上下文（上下數十行或相鄰幾頁）
- 保存「檔案名稱 + 頁碼/大致位置 + 文字片段」
- 應用「多輪迭代檢索機制」（見上文公共檢索原則）

3. Excel 檔案檢索策略

工作流：

首先：讀取處理方法指南
- 在處理任何 Excel 之前，必須先讀取：
  - references/excel_reading.md - 學習如何讀取工作表（注意這個目錄位於 Skills 目錄下，而不是 Knowledge 目錄下）
  - references/excel_analysis.md - 學習如何分析資料（注意這個目錄位於 Skills 目錄下，而不是 Knowledge 目錄下）
- 重點了解：pandas 讀取方法、欄位篩選、資料過濾、聚合操作
選擇候選 Excel
- 根據 data_structure.md 和檔案/工作表命名，選擇最相關的表
- 優先選擇包含「報表」「統計」「日誌」「設定」「對應」等關鍵詞的工作簿/工作表
- 若使用者指明具體 Excel 檔案，優先使用該檔案
應用學到的方法探索結構
- 使用 pandas 讀取前 10-50 行（使用 nrows 參數限制）
- 重點掌握：欄位名稱/欄位名、資料類型（數值、日期、文字）、關鍵欄位
- 將欄位名稱與使用者問題比對，識別潛在關鍵欄位（如「收入」「銷售額」「error_code」等）
執行資料檢索和分析
- 使用學到的 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 工作表
資訊缺失或不確定時
- 明確說明在當前知識庫中沒有找到完全匹配的資訊或只能部分回答。
- 不臆造事實。
- 提示使用者可以如何幫助縮小範圍：
  - 指定更具體的目錄/檔案
  - 提供更精確的關鍵詞或欄位名稱
  - 指定時間/版本範圍

您可能也喜歡

agent-architecture-audit

237Kresearch-knowledge

Full-stack diagnostic for agent and LLM applications. Audits the 12-layer agent stack for wrapper regression, memory pollution, tool discipline failures, hidden repair loops, and rendering corruption. Produces severity-ranked findings with code-first fixes. Essential for developers building agent applications, autonomous loops, or any LLM-powered feature.