dsh-doc-index

  English

一个 dsh bundle：将工作区变为可检索的本地知识库。它会对本地的 Markdown / 纯文本 / PDF / DOCX / PPTX / XLSX 文档建立语义索引，并支持用自然 语言或关键词查询——返回命中文档、带精确行号的片段与相关度分数。

• 词法检索：SQLite FTS5（node:sqlite，无原生依赖）＋自研 CJK 分词器，

让中文搜索开箱即用。

• 语义检索：provider 插槽——默认自带宽容零依赖的本地嵌入器，也支持按需

接入神经网络的 transformers provider。

• 结果以 RRF（倒数排名融合） 融合。
• 增量更新：仅对变更文件重索引（可选文件监听），并保留全量重建兜底。
• 容量与排除规则可控，索引规模有界、目标明确。
• 提供 dsh 服务（ctx.docIndex）＋四个模型可调用工具（doc_scan、

doc_query、doc_reindex、doc_stats），同时提供独立 CLI（docindex）。

该 bundle 遵循 dsh 标准分发格式：package.json 声明 dsh.bundle.patch 指向 cordis.patch.yml，入口模块是带 static inject / static Config 的 Cordis Service——与 @deepseek-ai/dsh-session-query-sqlite 同形态，但为工作区文档 重新实现，并通过自有工具提供检索能力。

---

环境要求

• Node.js >= 22.5（使用内置 node:sqlite）。
• 要运行在 dsh 中，需要一个可提供 @deepseek-ai/cordis、

@deepseek-ai/dsh-tools 与 @deepseek-ai/schemastery 的 DeepSeek Harness 环境（这些被声明为 peer 依赖）。

> 说明： Node 将 node:sqlite 标记为实验特性，启动时会有提示（不影响功能）。 > 可用 --disable-warning=ExperimentalWarning 关闭。

---

安装接入 dsh

在 profile 目录（或 Harness 任意位置）添加 bundle 并通过补丁层挂载：

dsh plugin add <本包路径>

本包也已发布到 npm，可独立使用 CLI：

npm install -g dsh-doc-index   # 提供 `docindex` CLI
npm install dsh-doc-index      # 或作为项目依赖加入

自带的 cordis.patch.yml 只插入一行插件：

- insert:
    - id: doc-index
      name: dsh-doc-index

不额外配置时，它会把当前工作目录索引到 $DSH_HOME/doc-index/index.db （DSH_HOME 默认 ~/.dsh），并开始监听变更。

如需自定义，在 profile 的 cordis.patch.yml 里覆盖（后层补丁会整体替换 该行的 config，请把关心的键全部写上）：

- id: doc-index
  config:
    roots:
      - /path/to/your/workspace
      - /another/vault
    dbPath: /path/to/index.db
    update: watch
    embedding:
      provider: transformers   # 需要 `npm i @huggingface/transformers`
    excludes:
      - vendor/
      - '*.tmp'

加载后，四个工具即可被模型调用，其他插件也可使用 ctx.docIndex 服务：

const hits = await ctx.docIndex.query({ query: 'RLHF and llama.cpp' })
// hits[0].path, hits[0].line, hits[0].snippet, hits[0].score

---

独立 CLI

同一套引擎也可以在命令行使用：

# 索引当前目录（可用 --root 多次；--db 指定库）
docindex scan
docindex scan --root ./docs --root ./specs

# 检索
docindex query "flux pipeline timeout" --top 5
docindex query "向量数据库" --mode semantic --json

# 重建
docindex reindex --full

# 查看统计
docindex stats

docindex --help 查看全部参数。环境变量：DOCINDEX_DB、DOCINDEX_ROOTS （按路径分隔符拆分）。

---

模型工具

---

配置参考

---

语义嵌入（provider 插槽）

DeepSeek 未提供官方 embedding API，因此本插件内置可插拔的 EmbeddingProvider 插槽：

• ngram（默认，零依赖）：基于 CJK n-gram ＋拉丁词的确定性特征哈希嵌入器，

完全离线、无需下载模型，提供一个「共享 token 越近」的向量空间，作用相当于 重排序器：语义候选被限定为与查询有 token 重合的片段，因此无匹配的查询 会返回空结果而非“噪声命中”。需要真正学到语义（含跨语言召回）时切换 provider。

• transformers（可选）：通过 @huggingface/transformers 加载小型 ONNX

编码器。安装后设置 embedding.provider: 'transformers'；默认模型为多语言， 中文可直接使用。

• none：关闭语义路径（仅词法）。
• 宿主应用也可自实现并注入自定义 provider（例如远程 HTTP embedding 接口）。

若请求的 provider 无法构建（例如缺少可选的 @huggingface/transformers）， 引擎会优雅降级：记警告并以纯词法继续。doc_query 会在「需要语义但不可用」 时把结果标记为 degraded。

---

检索原理

1. 片段：每篇文档按约 segmentChars 切分为若干片段，每个片段记录起始的 1 基行号，因此每条命中都可定位到行。 2. 分词：拉丁词统一小写；CJK 连续段展开为 n-gram（深度 2 时 你好世界 → 你 好 世 界 你好 好世 世界）。索引侧与查询侧使用同一套 分词，中文关键词检索开箱即用。查询时，一个表意字串内部用 OR 匹配其 n-gram（于是“苹果手机”也能命中只含“苹果”或“手机”的文档），字串/词之间用 AND（或 OR）组合。 3. 词法：FTS5 bm25() 排序命中。 4. 语义：查询向量与库内片段向量做余弦相似度（受 maxEmbeddedSegments 约束；向量存于 SQLite）。 5. 融合：两份排序结果用 RRF 合并，并归一化到 [0, 1]。

---

排除规则、二进制与容量

• 默认排除表：node_modules/、.git/、.svn/、.hg/、.cache/、

.next/、.nuxt/、.output/、dist/、build/、coverage/、 .DS_Store、*.pyc/pyo、*.exe/dll/so/dylib/o/obj、Thumbs.db、 .docindex/。excludes 追加 gitignore 风格规则（支持 **、*、?、 [...]、! 取反前缀、目录尾 /、锚定前缀 /）。

• 未知扩展名按内容嗅探，疑似二进制则跳过（binary）。无文本层的 PDF 以

no-text-layer 跳过（需 OCR）。空文件以 empty 跳过。

• 达到 maxDocs/maxSegments 后新文档会以 max-docs/max-segments 跳过，

并在 doc_scan 输出中报告。

---

开发

npm install          # 仅安装 TypeScript 与 dsh 类型包（dev）
npm run build        # tsc -> dist/
npm test             # 构建并运行完整测试（node:test，无额外依赖）

核心（src/engine.ts、src/db.ts、src/embedding.ts 等）零运行时依赖， 并有完整单元测试覆盖：分词、忽略规则、抽取（文本/PDF/OOXML）、发现、增量 更新、中文检索、RRF 排序、片段高亮、容量限制，以及「无嵌入模型时优雅降级」。

示例工作区见 example/。

许可证

[MIT](LICENSE)

遇到问题或希望支持新的文档类型？欢迎在 github.com/JohnXu22786/docindex 提交 issue。