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 包。