前言¶
給智能體接一份項目規範、產品手冊或者標準條文，最常見的做法是把文檔塞進向量庫，再靠語義檢索往上下文裏灌。這條路在問答場景裏好用，但有一類需求它並不擅長：你要的不是“看起來相關”，而是能指出原文在哪一節、同一句話每次檢索結果都一樣，並且整份知識包可以離線帶走、事後覈對。
DeepSeek Harness（dsh）把模型、工具、技能、會話都做成插件，社區裏也因此出現了不少記憶類擴展。其中一部分走圖譜或會話沉澱，另一部分則更接近傳統全文檢索。dsh-kb-sieve 屬於後者：它不把文檔交給外部向量服務，而是在本地抽出原文、建成 SQLite FTS5 索引，再讓模型按“先檢索、後精讀、再引用章節”的流程作答。
本文依據插件目錄頁、GitHub 倉庫 README 與源碼交叉覈對後整理，介紹它解決什麼問題、三個工具怎麼配合，以及安裝時需要注意的邊界。文中提到的社區插件目錄是獨立站點，與 DeepSeek / 幻方沒有官方從屬關係，不宜把它理解成官方應用商店。
這是什麼¶
dsh-kb-sieve 是一款面向 DeepSeek Harness 的記憶插件，由 omdsh-dev 維護，npm 包名爲 @dsh-external/dsh-kb-sieve。倉庫當前版本爲 0.1.0，主要語言是 TypeScript，許可證爲 Apache-2.0。目錄頁與 GitHub 均顯示 2 顆星。
它做的事情可以收成一句話：把 .md / .txt / .docx / .pdf 做成可審計的知識包——一邊留下 references/ 裏的原文，一邊用 SQLite FTS5 做本地檢索。構建過程不調用大模型，同樣的輸入會得到同樣的產物。
倉庫把自己定位成“DSH 版 kb-sieve”。原版生成的 skill 會附帶 Python kbtool 腳本、包裝器，以及可選的 PyInstaller 二進制；本插件把檢索和精讀搬進 TypeScript 工具，生成出來的 skill 只剩數據：SKILL.md 指令、references/ 原文和 kb.sqlite，不再依賴 Python 運行時。
三個工具分別幹什麼¶
插件只註冊三個工具，不改 agent 循環、TUI 或系統提示詞。源碼裏的 inject 只有 tools，也就是等工具註冊服務就緒後掛上能力。
1、kb_build：文檔變成知識包
必填參數是知識庫名 name（小寫字母、數字、連字符）和輸入路徑數組 inputs。可選參數包括輸出父目錄 out、顯示標題 title、是否全量重建 force，以及抽取併發 workers（默認 4，範圍 1–8）。
默認輸出位置不是用戶主目錄下的全局 skill 目錄，而是當前項目根（向上找到最近的 .git，找不到就用當前工作目錄）裏的 .dsh/skills/<name>/。這正是 DSH 會監聽的 skill 根目錄：構建完成後，下一輪對話裏模型就能在 skill 目錄中看到這份知識庫。
force 缺省爲 false。倉庫 README 後半部分和 src/index.ts 都寫明：已有 build_state.json 時按源文件字節指紋和抽取文本指紋做增量，文檔會落入 unchanged / changed / new / removed 四種狀態。需要整包重做時再把 force 設爲 true。README 裏有一張“與原版差異”對照表仍寫着 v1 不做增量，這和同一份 README 的增量說明、以及當前源碼不一致；以源碼和更具體的增量段落爲準。
抽取側有幾條實現細節值得單獨記下：
.md按原文讀入；.txt會做標題推斷（下劃線標題、章節號、短行啓發式）。.docx用fflate解 OOXML，讀取w:p/w:t，並識別 Heading1–6 或“標題 N”樣式。.pdf不內置解析器，而是調用系統裏的pdftotext -layout（poppler-utils）。PATH 上沒有這個命令時，構建會失敗，需要先安裝 poppler，或把 PDF 轉成 TXT/MD 再導入。
構建按文檔流水線進行：抽完一份就落庫釋放。README 給出的量級是：32MB 文檔構建峯值大約 0.6–2GB；內存緊張時把 workers 調小。SQLite 寫入按 5 萬行分批提交。
2、kb_query：確定性檢索
必填參數是知識包路徑 pack 和查詢詞 query。可選 limit（默認 10，最大 100）和 doc_ids（逗號分隔，用來限定文檔範圍）。
檢索鏈路是詞法的，沒有向量、也沒有隨機性：FTS5 BM25（標題權重 10、正文權重 1）→ 標準號 / 章節號 / 型號一類精確標識符匹配 → 文檔類型加權 → 窗口密度重排 → 返回 doc_id、行號、匹配行、score。結果帶 status：high_confidence、needs_verification 或 no_hits。查詢詞明顯越出語料域（例如庫裏不存在的標準號，或絕大多數詞都不在文檔裏）時，會給出 no_hits 和 oos_reason。
行號只給後續 kb_read 定位用。生成的 SKILL.md 明確要求模型回答時引用章節名（例如「第 D21.3 節」），不要把內部行號報給讀者。
3、kb_read：按章節精讀原文
必填是 pack 和 doc_id。常見模式包括：
around：讀某行所在的完整章節，可用expand擴到相鄰章節；sections：輸出文檔地圖（標題 + 行號區間）；find/after：從指定行向後搜關鍵詞；jump：跳讀多段，例如"210-230,450-460"；start/count：按範圍讀取。
tokens 用來在輸出裏標記命中詞。kb_read 會拒絕路徑穿越；kb_build 的輸入、輸出路徑都相對當前工作目錄解析。
知識包裏有什麼¶
一次成功的構建會得到大致如下的目錄：
<pack>/
├── SKILL.md
├── manifest.json
├── kb.sqlite
└── references/<doc_id>/
├── doc.md
├── metadata.md
└── structure_report.json
SKILL.md 是給模型看的說明書：先 kb_query，再拿 doc_id 和行號去 kb_read，結論必須落到 references/ 原文的章節標題上；連續兩輪 no_hits 就應停止，不要編造。manifest.json 列出全部文檔的 doc_id、標題、路徑和哈希。kb.sqlite 裏是文檔表、external-content FTS5，以及行級二級索引（line_text / line_rowmap / line_fts）。當前源碼裏的索引布局版本是 3（INDEX_VERSION），舊包在查詢時可能帶 warning，下次構建會按 build_state.index_version 觸發一次全量重建。
kb_query / kb_read 讀的是 kb.sqlite 加 references/。倉庫說明 schema 與原版 Python kb-sieve 產物一致，因此原版已經構建好的知識包可以直接拿來查，不必先用本插件重做一遍。沒有行級索引的舊包會回退到全文掃描路徑。
安裝與啓用¶
目錄頁給出的安裝命令如下，在 DeepSeek Harness 終端裏運行即可：
dsh plugin add github:omdsh-dev/dsh-kb-sieve
需要可復現安裝時，按目錄頁的寫法固定 commit 哈希：
dsh plugin add github:omdsh-dev/dsh-kb-sieve#<commit>
把 <commit> 換成倉庫裏的具體提交。dsh CLI 會從 GitHub 解析插件並裝進當前配置。
倉庫 README 還補充了按 profile 安裝的方式：把插件裝進 tui / headless / web 或自建 profile，然後用對應 profile 重啓，使 kb_build / kb_query / kb_read 注入生效。卸載時使用包名 @dsh-external/dsh-kb-sieve。需要本機 dsh 版本已經提供 dsh plugin 子命令。package.json 聲明的 Node 引擎是 ^22.19.0 || >=24.0.0；peer 依賴 @deepseek-ai/dsh-tools 和 cordis 由 dsh 組合提供，運行時額外依賴 fflate（用於 docx 抽取），會隨插件安裝流程一起裝上。
目錄頁和 README 裏的 git 來源寫法並不完全相同。目錄頁使用 github:omdsh-dev/dsh-kb-sieve，與當前公開倉庫一致；README 示例裏曾出現 git+https://github.com/dsh-external/dsh-kb-sieve.git。安裝時以目錄頁這條命令爲準，不要按包名裏的 @dsh-external 去猜另一個 GitHub 組織。
典型用法¶
倉庫推薦的用法是構建加動態加載。對模型直接說人話，例如「把這些文檔做成知識庫」，並給出文檔路徑。kb_build 默認寫到項目下的 .dsh/skills/，DSH 會動態發現新 skill；模型加載後按 SKILL.md 調用 kb_query / kb_read。skill 內容按需讀取，沒有額外的緩存失效步驟。
也可以把 out 指到任意父目錄，之後查詢時顯式傳入 pack 路徑。第三種情況是隻查舊包：只要目錄裏有兼容的 kb.sqlite 和 references/，不必重新構建。
生成的 skill 把默認流程寫得很死：
- 用
kb_query拿 compact 摘要（doc_id、行號、匹配行、status）。 - 用
kb_read的around精讀命中章節；定位困難時先sections: true看章節地圖。 - 回答時引用章節名，不輸出內部行號；沒有證據就明確說未找到。
多跳問題不要把所有關鍵詞一次塞進查詢。SKILL.md 要求每輪只查 1–2 個環節，從命中行提取新實體再查下一跳。
這些都是工具參數，不是單獨的 CLI 子命令。插件裝好後，由當前會話裏的模型按 skill 指令去調工具；不要指望在 shell 裏直接敲 kb_query。
適用場景與注意事項¶
比較適合把規範、手冊、接口說明、制度條文這類需要“對着原文說話”的材料交給智能體。檢索是 BM25 加密度窗口，對標準號、章節號、型號這類標識符更友好；它不是語義向量記憶，也不從對話裏自動抽取三元組。社區目錄裏同屬「記憶」分類的 graph-memory、mnemon 走的是另一條路，和 dsh-kb-sieve 不是替代關係。
使用前建議先看這幾條邊界：
- 輸入格式目前只有 md / txt / docx / pdf。PDF 依賴系統
pdftotext，容器或精簡環境裏經常缺這一步。 - 別名、圖邊、LLM 查詢變體、TSV 索引等原版能力，倉庫對照表仍標爲 v1 未做。
- 行號是
doc.md的物理行，給工具定位用，不是印刷頁碼。 - 大文檔會佔內存。README 寫 32MB 文檔構建峯值約 0.6–2GB，內存緊張時減小
workers。 - 知識包落在項目內的
.dsh/skills/，隨項目走，不默認寫到~/.dsh/skills。
插件以當前 dsh 進程的權限運行，安裝時可能執行代碼。裝之前應檢查源代碼倉庫和許可證；生產或共享環境裏建議固定 commit。DeepSeek Harness 本身仍處於 developer preview，官方倉庫也提醒會有破壞性變更，插件 API 同樣可能跟着動。
小結¶
dsh-kb-sieve 把“可引用的原文”和“可重複的本地檢索”捆成一個知識包：構建不經過 LLM，查詢走 SQLite FTS5，精讀回到 references/ 章節。它解決的不是把記憶做得更像人，而是讓智能體在規範、手冊這類材料上少憑印象說話。
目錄頁：https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-kb-sieve/
GitHub：https://github.com/omdsh-dev/dsh-kb-sieve
