JohnXu22786/docindex

dsh-doc-index

npm version
License: MIT
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
（按路径分隔符拆分）。

模型工具

| 工具 | 用途 |
| --- | --- |
| doc_scan | 增量扫描/刷新/清理工作区（可选 path 限定子树，force 忽略变更检测）。 |
| doc_query | 检索。query（必填）、topK、mode（auto/lexical/semantic）、highlight、snippetChars。每条命中返回 路径＋行号＋片段＋分数。 |
| doc_reindex | 重建。full 先清空索引；path 限定范围重建。 |
| doc_stats | 索引统计（文档数、片段数、嵌入数、体积、根目录）。 |

配置参考

| 键 | 默认值 | 含义 |
| --- | --- | --- |
| roots | [] → process.cwd() | 扫描的工作区根目录。 |
| dbPath | '' → $DSH_HOME/doc-index/index.db | SQLite 路径（可用 :memory:）。 |
| openAt | startup | 打开库的时机：startup / first-use / never。 |
| update | watch | watch（fs.watch＋防抖）或 manual。 |
| watchDebounceMs | 1500 | 监听重扫的防抖毫秒。 |
| excludes | [] | 额外的 gitignore 风格排除规则（见下）。 |
| includeHidden | false | 是否索引点号开头的文件/目录。 |
| followSymlinks | false | 是否跟随目录符号链接（自动断环）。 |
| maxDocs | 20000 | 最大文档数。 |
| maxSegments | 300000 | 最大文本片段数。 |
| maxEmbeddedSegments | 50000 | 最多获得向量的片段数。 |
| maxFileBytes | 5 MB | 大于此字节数的文件跳过。 |
| maxDepth | 64 | 根目录下最大目录深度（0 表示不限制）。 |
| maxWalkedFiles | 200000 | 单次扫描最多收集的候选文件数（内部检查文件预算为其 4 倍）。若因此被截断，则本次扫描不做删除。 |
| tokenizer.cjkN | 2 | CJK n-gram 深度：1（一元）/2（＋二元）/3（＋三元）。 |
| segmentChars | 400 | 单个索引片段约最大字符数。 |
| snippetChars | 240 | 每条命中的最大片段长度。 |
| textExtensions | [] | 额外按纯文本处理的扩展名（如 .csv）。 |
| search.topK | 10 | 每次查询默认命中数（1–50）。 |
| search.minScore | 0 | 过滤低于此归一化分数的结果。 |
| search.mode | auto | auto / lexical / semantic。 |
| search.highlight | true | 是否对命中词加 … 标记。 |
| search.matchOp | and | 查询各「组」之间用 and 还是 or。 |
| search.rrfK | 60 | RRF 常数。 |
| search.semanticWeight | 0.5 | 语义列表在 RRF 中的权重（词法为 1 - w）。 |
| embedding.provider | ngram | none / ngram / transformers。 |
| embedding.dim | 256 | ngram 嵌入器维度。 |
| embedding.model | '' | transformers 模型 id（默认多语言 MiniLM）。 |
| embedding.device / cacheDir / quantized | auto / HF 缓存 / true | transformers 相关选项。 |
| journalMode | wal | SQLite 日志模式。 |

语义嵌入（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

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