本地文件夹检索模式（实验）
给 DSH 新建会话增加一个「本地文件夹检索模式」：在本地 Word / PDF / PPT / Excel 文件夹里按关键词找内容，回答哪些文件、哪些位置有命中；也可以把库里的题组一套新卷。
- 包名：
dsh-folder-search
- 版本：
0.5.36
- 作者：七七（Voyager77Twt）
- 许可：MIT
- 兼容：DSH
>= 0.2.0-rc.2，Node >= 22.19
.doc / .ppt / .rtf 转换需要 Windows + 本机 Office
解析和检索都在插件内部完成，只把命中片段和位置送进模型上下文，不把整份文件塞给模型。
快速开始
- 打开 设置 → 本地搜索设置；
- 在「数据库与索引库位置」填写题库文件夹的绝对路径；
- 保存后插件自动开始建索引，可在「索引库状态」查看进度；
- 新建会话，模式选「本地文件夹检索模式」；
- 直接提问，例如：
搜索“侯氏制碱法”相关的题目，给文件和位置。
设置页只在第一次需要填路径。之后新会话会直接从设置读取题库位置，不再先问。
搜索模式
「搜索步骤」最上面有四个预设：
| 模式 | 行为 |
|---|
| 原词搜索 | 只做原词检索；强关联、自动词表、一般关联、零命中兜底全部关闭。 |
| 默认搜索 | 按当前已保存的本机数值执行；自定义词表自动生效，不修改逐项设置。 |
| 全面搜索 | 原词 + 强关联（最多 4 个）+ 自动词表（最多 8 个词，含自定义词表）+ 一般关联（最多 8 个词）全部开启；放开关联文件上限和最终输出上限，一般关联词也可以带入文件。输出可能很大。 |
| 自定义搜索 | 展开下面的逐项设置；默认使用本机已保存数值，可手动调整。 |
只有切到「自定义搜索」才会展开详细步骤；其他模式只显示预设说明。
模式本身也会保存到设置，新会话沿用。
数据库与索引库位置
| 设置 | 默认 | 说明 |
|---|
| 题库位置 | 空 | 题库文件夹绝对路径。填好后新会话直接使用；为空时才会在对话里询问。 |
| 索引库位置 | 空 | 索引缓存目录；留空使用 %LOCALAPPDATA%\dsh-library-search。保存时会把旧索引复制到新位置，成功后删除旧目录。 |
| 建库并发数 | 3 | .docx / .pdf / .xlsx 等并行抽取的数量，1–8。.doc / .ppt / .rtf 仍走 Word/PowerPoint，串行，避免 Office 冲突。 |
| 单文件上限（MB） | 200 | 超过此大小的文件直接跳过。大型图片汇编 docx 可调到 200–500，内存峰值也会增加。 |
保存路径后：
- 修改题库位置：重新建库；
- 修改索引库位置：自动迁移索引；
- 修改单文件上限：也会触发一次建库，重新尝试之前因大小被跳过的文件。
索引状态接口：/api/dsh-folder-search/index（GET 查进度，POST action=build 开始/继续）。
四类结果与兜底
检索结果可能来自四条路径，分开统计和输出：
| 类型 | 含义 | 使用哪组输出上限 |
|---|
| 直接命中（原词） | 用户原词在文件中出现 | 原词检索·输出上限 |
| 自动扩展命中 | 内置词表或自定义词表把关键词扩成关联词后命中 | 自动扩展输出 |
| 强关联命中 | 只命中了模型给的强关联词 | 强关联输出 |
| 一般关联命中 | 模型补充的一般关联词；默认只补段落，开启设置后才可带文件 | 与自动扩展共用文件数；位置/片段用关联词输出 |
零命中兜底
如果：
直接命中 = 0 且 强关联命中 = 0
那么即使「允许一般关联词带入文件」是关闭的，也会自动启用兜底：
- 自动扩展和一般关联都可以带入文件；
- 文件上限 =
强关联输出·最多文件数 + 自动扩展输出·最多文件数；
all 按 5000 处理；- 先输出自动词表文件，再输出一般关联文件；
- 最终仍受「最终输出文件数」限制。
输出会显示：
兜底关联命中：自动词表 N + 一般关联 M 个文件
兜底命中·自动词表
兜底命中·一般关联
这解决的是“空气除硫”这类原词没有、但标准词是“脱硫”的问题，避免模型为了换词连续搜索。
搜索结果的分段顺序
最终输出顺序固定为：
直接命中 → 自动扩展 → 强关联 → 一般关联
兜底时：
自动扩展 → 一般关联
最终输出文件数 在各类别自身上限之后统一截断，所以直接命中会优先占用名额。
设置项逐项说明
1. 原词输出
| 设置 | 默认 | 详细作用与建议 |
|---|
| 原词检索·输出文件数 | 全部 | 直接命中的文件最多列多少个。“全部”最全也最贵；想压费用先改这一项。 |
| 原词检索·每文件位置数 | 4 | 每个直接命中文件最多列几处命中；总数仍会显示“另有 N 处”。想看得全可调到 10–50，想省 token 调到 2。 |
| 原词检索·片段长度 | 90 | 每处命中截取多少字符。45–60 更省，但可能看不全题干。 |
2. 自动词表与自定义词表
自定义词表现在是独立的「自定义词表」卡片，位于搜索模式按钮下方：默认搜索、全面搜索、自定义搜索都会显示并使用；原词搜索隐藏且不使用。
| 设置 | 默认 | 详细作用与建议 |
|---|
| 自动关联词扩展 | 开 | 是否使用内置词表扩词。自定义词表不受这个开关影响：默认/全面/自定义始终使用，只有原词搜索不使用。 |
| 关联词数量上限 | 4 | 自动词表每个关键词最多几个扩展词（不含原词）。只控制自动词表；一般关联词数量在下一步单独设置。 |
| 自定义词表 | 空 | 每行 关键词=关联词1,关联词2。同一个关键词：自定义词优先。默认/全面/自定义模式都会使用；原词搜索不使用。 |
| 自动扩展输出·最多文件数 | 全部 | 仅自动扩展命中的文件上限。注意：普通输出文件数为“全部”时，这里也建议设数字，否则容易一次列很多。 |
| 自动扩展输出·每文件位置数 | 2 | 自动扩展文件每文件最多几处。 |
| 自动扩展输出·片段长度 | 45 | 自动扩展文件每处片段字符数。 |
自定义词表示例：
空气除硫=脱硫
沉淀溶解平衡=Ksp,溶度积
3. 强关联词
强关联词由模型在第一次检索前自检后给出。允许：
- 人物、旧称、别名、英文缩写、简称；
- 近义词、标准术语（例如把“脱硫”作为“空气除硫”的强关联词）。
不允许父类/领域词。工具仍会做广度闸门。
| 设置 | 默认 | 详细作用与建议 |
|---|
| 强关联词 | 开 | 是否接受模型给出的 strongTerms。关闭后完全忽略。 |
| 强关联词上限 | 2 | 每次最多使用几个强关联词。默认 2；全面模式固定至少 4。人名、旧称、别名、缩写、近义词、标准术语优先放这里。 |
| 强关联降级判定 | all | 可选：factor（直接命中倍数）、files（固定文件数）、ratio（全库占比）、domain（领域词）、all（任一，默认）。 |
| 强关联倍数阈值 | 2 | 直接命中文件数 >5 时，强关联词单独命中超过“直接命中数 × 倍数”就降级。 |
| 强关联固定文件数 | 50 | 仅在 files 模式下生效：超过这个文件数降级。 |
| 强关联占比阈值（%） | 20 | 直接命中文件数 >5 时，强关联词命中文件占全库比例超过该值就降级。 |
| 强关联输出·最多文件数 | 全部 | 仅强关联命中的文件上限。兜底时也参与“强关联上限 + 自动扩展上限”的计算。 |
| 强关联输出·每文件位置数 | 2 | 强关联文件每文件最多几处。 |
| 强关联输出·片段长度 | 45 | 强关联文件每处片段字符数。 |
| 降级后重复搜索 | 关 | 强关联词被降级时，是否用剩余强关联词再搜一次；仍在本工具调用内。 |
| 最多重复次数 | 1 | 重复搜索最多几遍，0–5。 |
闸门规则：
- 直接命中文件数 ≤ 5：2 倍规则和 20% 规则不启用；
- 领域词结尾规则仍生效；
- 只保留最窄的 1 个强关联词；
- 被降级的词不再带入新文件，已命中原词的文件保留；
- 结果顶部会注明降级词。
领域词后缀：
工业 / 产业 / 行业 / 领域 / 技术 / 方法 / 工艺 / 生产 / 应用 / 研究 /
化学 / 反应 / 原理 / 实验 / 流程 / 装置 / 设备 / 材料 / 物质 / 题目 / 试题
4. 一般关联词
| 设置 | 默认 | 详细作用与建议 |
|---|
| 一般关联词 | 开 | 是否接受模型给出的 generalTerms。关闭后模型补充的一般关联词不参与检索。 |
| 一般关联词数量上限 | 4 | 一般关联词最多取几个，0–8。0 等于不接收一般关联词；与自动词表数量上限独立。 |
| 允许一般关联词带入文件 | 关 | 开启后：自动词表文件名额未满时，一般关联词可以补文件，和自动扩展共用文件上限，优先自动词表。零命中兜底时即使关闭也自动带入。 |
一般关联词默认是“段落补充器”，不是“文件发现器”，所以“纯碱”这类泛词不会单独带出大量无关文件。只有开启或零命中兜底时才会带文件。
5. 搜索步骤与其他
| 设置 | 默认 | 详细作用与建议 |
|---|
| 自动补索引 | 开 | 检索前检查题库更新并补缓存；关闭后只用旧缓存，新文件不会出现。 |
| 匹配范围 | 同文件 | 同文件=关键词在同一个文件里出现即可；同段/页=必须同一段、同一页、同一幻灯片或同一单元格。越严越省，但可能漏掉分散在不同页的关键词。 |
| 显示命中片段 | 开 | 关闭后只给文件和位置，不回传片段，最省 token。 |
| 显示题号 | 开 | 在位置后标“题号 N（文中编号）”。汇编卷题号可能重排，以文件和片段为准。 |
| 合并重复文件 | 关 | 合并命中内容完全相同的文件；会少列文件，但跨格式副本（doc/pdf）通常不会被合并。 |
| 搜索模式 | 默认搜索 | 原词/默认/全面/自定义四选一；只有自定义展开逐项设置。 |
| 最终输出文件数 | 全部 | 所有类别合计最多输出多少个文件；有上限时按直接→自动→强关联→一般关联顺序保留。 |
| 目录默认文件数 | 60 | library_outline 一次列多少文件，只影响目录输出。 |
6. 搜索步骤执行顺序
一次工具调用内按顺序执行：
| 步骤 | 执行次数 | 作用 |
|---|
| 1. 自动补索引 | 1 次（可关） | 检查题库更新并补缓存 |
| 2. 原词检索 | 1 次（必开） | 用用户原词搜索 |
| 3. 强关联词 | 1 次，与第 2 步合并 | 模型自检后填专名/近义词/标准术语；默认最多 2 个 |
| 4. 自动关联词扩展 | 1 次，与第 2 步合并 | 内置词表 + 自定义词表；自定义优先 |
| 5. 一般关联词 | 1 次，与第 2 步合并 | 默认只补段落；开启/兜底时可补文件 |
| 6. 匹配范围 | 1 次 | 同文件 / 同段页 |
| 7. 显示片段 | 1 次 | 关闭后只给位置 |
| 8. 显示题号 | 1 次 | 标“题号 N（文中编号）” |
| 9. 合并重复文件 | 1 次 | 合并相同内容文件 |
| 10. 降级后重复搜索 | 0–5 次 | 强关联被降级时用剩余强关联词再搜 |
每个启用的步骤只执行 1 次（第 10 步按设置次数），不会自动无限重搜。
文本缓存与索引库
缓存位置：
%LOCALAPPDATA%\dsh-library-search\lib-<hash>\
├── manifest.json
└── docs\ ← 每个文档一个 .txt
- 每个题库根目录生成一个
lib-<hash>；
- 目录名保留旧名
dsh-library-search，避免已有索引失效；
- 文本缓存约为原题库的 0.4%（本机 4.5 GB → 约 20 MB）；
- 缓存上限 250 MB 只统计 docs + manifest；
- 建库中的
legacy-pdf-* 临时 PDF 不计入 250 MB，建库结束会删除；它们会占磁盘，但不是索引正文；
- 删除
lib-* 只会让下次重新抽，不会动原文件。
建库流程
- 扫描文件；
.doc/.rtf 先批量转 PDF（每批 20 个），批量失败后逐文件单独转换；- 转换出的文本按段/页/幻灯片/单元格写入
docs；
- 建库
sync 会重试之前失败的条目，转换成功的旧版文档会从 failed 变成 ready。
当前题库的已知失败
本机题库 1767 个文件中 1760 个已索引，剩余 7 个：
| 文件 | 原因 |
|---|
模拟试题/2022/一模/朝阳/朝阳区第二学期高三化学质量检测一试卷.docx | docx 损坏（invalid zip） |
期末考试/2020期中期末/2020选择.docx | docx 损坏 |
期末考试/2019期末/东城期末/18题.pptx | pptx 损坏 |
期末考试/2013期末/成绩/王莹.xlsx | 文件有密码 |
模拟试题/2020/西城一模05/2020.5西城高三化学诊断性测试试卷.doc | Word 转换失败 |
模拟试题/2013/2013房山高三一模化学试题.doc | Word 转换失败 |
模拟试题/2010一模/通州区高三年级模拟考试（一）.doc | Word 转换失败 |
损坏 zip 和加密 Excel 只能修原文件；3 个 .doc 已尝试单文件 Word 转换，仍失败，通常是本机 Word 打不开。
支持范围
| 类型 | 支持 |
|---|
.docx | 全文（段落 + 标题路径） |
.pdf | 全文（页码；扫描件无文本会标注） |
.doc / .rtf | 本机 Word 转 PDF 后全文 |
.pptx | 全文（第 N 张） |
.ppt | 本机 PowerPoint 转 PDF 后全文 |
.xlsx / .xls | 单元格文本（Sheet!B12） |
.txt / .md / .csv | 逐行 |
.rar / .zip / 图片 / 视频 | 仅文件名 |
工具
| 工具 | 用途 |
|---|
library_search | 关键词检索；返回文件、位置、片段、四类统计 |
library_outline | 目录、大题/题号位置 |
library_read | 读完整题目（可用 question 限定） |
library_export | 组卷并导出 .docx |
library_status | 检查索引状态 |
library_index | 批量建索引 |
library_index_export | 导出索引包 zip |
library_index_import | 导入索引包，按大小/时间校验 |
缓存会不会导致搜索不全？
缓存本身不会丢命中：它是抽取文本的完整副本，检索时逐行扫描，没有采样、摘要或截断。
| 对照 | 样本 | 结果 |
|---|
| 缓存检索 vs 每次直接解析原文件 | 2019年 70 个文件，3 个关键词 | 命中文件集合完全一致，missing=0 |
| 缓存检索 vs Word 自身文本 | 20 个 .docx，3 个关键词 | missing=0，extra=0 |
仍可能搜不全的情况：
- 索引还没建完；
- Word 页眉/页脚/脚注/公式、PPT 备注、Excel 公式与批注、扫描 PDF 的图片文字；
- 压缩包/图片/视频只索引文件名；
- 缓存上限到了；
- 文件改动但 mtime 与大小都没变（可用
refresh: "force" 重建）。
限制
- 扫描 PDF、图片文字不索引；
.doc / .ppt 转换依赖本机 Office，可能较慢；- 去重只比较已显示的前几条 block，Word/PDF 跨格式副本通常不会互相合并；
- 强关联词闸门和兜底是启发式规则，不能保证模型一定想到正确专名；
- 组卷是实验功能，导出前要自己核对题目和答案；
- 一般关联词兜底可能一次带出较多文件，建议同时给「强关联输出·最多文件数」和「最终输出文件数」设数字。
开发
node tests/_static-audit.mjs # 语法、清单、设置键、路由、分类/上限/兜底
pnpm pack # 生成 dsh-folder-search-<version>.tgz
目录：
lib/index.js 工具注册、配置
lib/search.js 检索、分类、强关联闸门、兜底、渲染
lib/indexer.js 增量索引、缓存、并发
lib/extract.js docx/pdf/pptx/xlsx/文本抽取
lib/legacy-batch.js 旧版 Office 批量/单文件转换
lib/outline.js 目录
lib/docx-writer.js 组卷导出
lib/client.js 设置页
lib/settings-store.js 设置默认值与持久化
lib/settings-host.js 设置接口、建库任务、迁移
cordis.patch.yml 模式预设
