dsh-doc-index：本地知識庫索引

前言¶

在 DeepSeek Harness (DSH) 的開發與使用場景中，智能體經常需要訪問本地積累的文檔（如 Markdown、PDF、Office 文件等）。這些文檔散落在工作區各處，且包含大量中文內容，傳統的基於關鍵詞的搜索難以滿足語義理解的需求，而通用的遠程嵌入 API 又依賴網絡且成本較高。

dsh-doc-index 作爲一個 DSH Bundle，旨在解決這一問題。它將本地文件轉化爲可檢索的語義索引，提供混合檢索能力（BM25 + 嵌入向量），並支持增量更新與精確行號引用。

名稱：dsh-doc-index
維護者：JohnXu22786
類別：記憶
核心價值：把一個普通的工作區目錄變成一個具備語義搜索能力的本地知識庫。它索引 Markdown、純文本、PDF、DOCX、PPTX、XLSX 等文件，支持中文分詞，並能返回帶有精確行號和相關性得分的片段。

安裝前請確保環境滿足以下要求：

通過命令行安裝插件：

dsh plugin add <path-to-this-package>

安裝後，插件會在 cordis.patch.yml 中插入一行 doc-index，默認將當前工作區索引到 $DSH_HOME/doc-index/index.db，並自動啓動文件監聽以進行增量更新。

該插件提供了混合檢索能力，結合了精確匹配與語義匹配，並通過互逆排名融合（RRF）合併結果。

混合檢索：
- BM25 檢索：使用 SQLite FTS5 實現，內置 CJK n-gram tokenizer，無需額外依賴即可支持中文分詞。
- 語義檢索：支持本地嵌入，默認使用零依賴的 ngram 算法（確定性特徵哈希），也可切換到 transformers 加載本地 ONNX 模型。
增量更新：
- 默認開啓文件監聽（update: watch），文件變更後自動重新索引。
- 提供命令行工具 doc_scan，支持指定路徑或強制刷新。
結果引用：
- 搜索結果包含文檔路徑、行號（line）、片段（snippet）和相關性得分（score）。

插件通過 embedding.provider 控制語義檢索的底層實現：

ngram（默認）：零依賴，基於字符 n-gram 的特徵哈希。適合離線環境，無需下載模型，對中文支持良好。
transformers（可選）：通過 @huggingface/transformers 加載 ONNX 模型（默認爲多語言 MiniLM），提供更豐富的語義理解能力。
none：僅啓用 BM25 詞法檢索。

檢索結果融合採用互逆排名融合（RRF）策略，通過 search.rrfK 調整融合權重。

插件暴露了 CLI 工具和 DSH 工具集，供模型或開發者調用。

# 掃描並建立索引
docindex scan

# 搜索，top 5 結果
docindex query "flux pipeline timeout" --top 5

# 重建索引
docindex reindex --full

# 查看統計信息
docindex stats

在 DSH 上下文中，模型可使用以下工具，其他插件可調用 ctx.docIndex 服務：

doc_query：執行搜索，參數包括 query、topK、mode（auto/lexical/semantic）、highlight。
doc_scan：增量索引，可選參數 path 範圍和 force 強制刷新。
doc_reindex：重建索引，參數 full 清空數據庫後重建。
doc_stats：查看索引統計（文檔數、段落數、大小等）。

實驗性警告：由於使用了 Node.js 的 node:sqlite，啓動時可能會看到關於 ExperimentalWarning 的提示，這屬於正常現象，不影響功能。
性能限制：插件內置了容量限制，包括 maxDocs（默認 20000）、maxSegments（默認 300000）和 maxFileBytes（默認 5MB），超出限制的文件或目錄會被自動跳過或排除。
排除規則：默認支持類似 .gitignore 的排除模式，可通過 excludes 配置項擴展。
生態說明：該插件屬於 DSH 生態的一部分，通過 cordis.patch.yml 注入，安裝路徑需指向本地包或 npm 包。