本地证据检索 Cooberped/dsh-evidence

dsh-evidence

在 DeepSeek Harness 里传文件，让模型真的能读。

在 Web 输入框上传文件或整个文件夹。解析和索引都留在本机。模型先检索紧凑证据，再按需展开准确的页码、幻灯片、行区间或表格范围——而不是把全文塞进 prompt，也不用退回 Python 遍历。栅格图片继续走 Harness 原生视觉链路。

[!IMPORTANT]
npm Beta 已经可以安装。 公开的预发布版本是 @baseland/dsh-evidence@0.6.0-beta.4，包页面在 @baseland/dsh-evidence。请用 @beta 安装这一版。latest 仍指向第一个已发布版本 0.6.0-beta.1，因为这次预发布不会移动它。这不是稳定版承诺。

GitHub 仓库仍是 Cooberped/dsh-evidence。npm 包名是 @baseland/dsh-evidence，因为 npm 组织 @cooberped 无法认领。

它怎么工作

1. 只上传一次，文件落在当前会话工作区。
2. 在本地建索引——不把全文预先塞进模型上下文。
3. 围绕具体问题检索紧凑证据。
4. 只在需要时展开带版本的准确坐标。
5. 基于证据回答；没有证据就明确说明。

这样，文件就变成可以定位、按需回读的证据，而不是整篇塞进 prompt。

安装

需要带 web profile 的 DeepSeek Harness CLI，以及 Node.js >=22.13.0。从源码安装还需要 PATH 里有 pnpm。日常行为仍按 npm @deepseek-ai/dsh@0.1.7-rc.2 核对。包里同时声明了 engines.dsh：>=0.1.7-rc.2 <0.3.0，所以 0.3.0 以下的 0.2.x 宿主也可以安装。

下限是 Harness 0.1.7-rc.2。上传按钮仍使用 …Regular 图标名。@deepseek-ai/dsh-client-ui-primitives@0.2.1-rc.2 仍导出这些名字，conversation.input.left 和 conversation.input.dock 也仍在 0.2.0-rc.2 与 0.2.1-rc.2 的会话客户端里。0.1.6 及更早版本上，图标会对不上。仓库没有为旧版打过 release tag；若仍要跑 ≤ 0.1.6，请用图标改名之前的代码，或上游 taxueseek/dsh-files。

从 npm 安装

dsh plugin --profile web add @baseland/dsh-evidence@beta
dsh --profile web --dump-config # 确认组合配置中已有该 bundle layer
dsh web # 重启

请用 @beta。它指向这次预发布 0.6.0-beta.4。只写包名会跟着 latest 走，而 latest 仍是 0.6.0-beta.1。那是 npm 上的第一个版本，注册表会保留 latest；用 beta 标签发布这一版不会移动它。以后发出稳定版时，latest 应该改到那个版本。@beta 继续表示预发布。

说明见 v0.6.0-beta.4。@beta 装到的就是这一版。这一版更新了运行时依赖：read-excel-file 9.3.10 → 9.3.12，修好了工作表 XML 里 <sheetData/> 出现得比较靠后时会崩溃的问题；pdfjs-dist 6.3.289 → 6.4.299；pdfjs-dist 带进来的可选依赖 @napi-rs/canvas 1.0.8 → 1.0.10。仍带有 0.6.0-beta.1 里还没有的三处上传修正：同一批里第二个及之后的文件会把卡片插到正确位置；较长的中文文本在开头一段正好切在半个字上时仍会被认出；已确认是文本的卡片会显示自己的短扩展名（.md 显示为 MD），而不是一律 TXT。开发依赖 @types/node 在 lockfile 里也从 26.6.3 升到了 26.6.5。

dsh plugin add 会把后面的参数交给 profile 里的 pnpm，这也是 Harness bundle 发布指南里的安装方式。如果你的 npm 客户端走了国内镜像（例如 npmmirror），而镜像上还没有这个包，就给这一条命令指定官方注册表：

dsh plugin --profile web add @baseland/dsh-evidence@beta --registry https://registry.npmjs.org/

卸载用 dsh plugin --profile web remove @baseland/dsh-evidence。

profile 和插件的用法遵循官方 Harness 插件参考和同一份发布指南。

从源码安装

git clone https://github.com/Cooberped/dsh-evidence.git
cd dsh-evidence
pnpm install --frozen-lockfile
pnpm build

dsh plugin --profile web add . # 把当前 checkout 链接到 web profile
dsh --profile web --dump-config # 确认组合配置中已有该 bundle layer
dsh web # 重启

本地安装是对当前 checkout 的链接：拉取更新后重新执行 pnpm install --frozen-lockfile && pnpm build 并重启。卸载用 dsh plugin --profile web remove @baseland/dsh-evidence。

怎么用

1. 打开 Harness Web 输入框。
2. 添加文件：回形针多选、文件夹按钮选整个目录，或者直接把东西拖到页面上。
3. 确认每个预期文件都有独立卡片，并显示 AI 可读取。
4. 提一个具体问题——模型会自己调用工具。

好用的提示词：

先索引这三个文件，不要立即总结。

在这些材料中查找 Q3 留任指标的定义和公式。
每个判断都给出来源文件与准确页码、幻灯片、行区间或 Sheet!Range。

比较会议决定与工作簿目标。
如果材料不足，请说明缺少什么，不要猜测。

两个工具

| | search_documents | read_document |
| 用来 | 找答案在哪 | 读某个位置是什么 |
| 主要入参 | file_paths，可选短 query | file_path 加 coordinate/version，或 offset/limit，或 sheet/cell_range/list_sheets |
| 不带 query | 索引发生变化的内容并返回紧凑清单，适合"先把这几个文件读一下" | — |
| 返回 | 排序后的证据块，每条带 path、format、text、coordinate 和 version | 一个分页窗口，或精确展开的单个坐标 |

两条规则撑起整个循环：

- 坐标绑定版本（源文件哈希 + 解析/切块 Schema）。只要给了 coordinate，version 就是必填，并在返回任何内容前校验。文件改过之后旧坐标会明确报错，而不是悄悄读到错行。
- 零召回不等于可以猜。 工具会引导模型换词重试、在合理时顺序读取，或者明确报告文件中没有证据。

支持格式与诚实边界

| 输入 | 本地转成的文本 | 稳定坐标 | 当前边界 |
| Text | UTF-8、UTF-16 BOM、高置信度无 BOM UTF-16、GB18030 | line:S-E，可附 chars:S-E | 其他编码和二进制文件会被拒绝 |
| PDF | 文本层提取，保留页边界 | page:N，可附页内行/字符范围 | 扫描件和纯图片页没有 OCR |
| DOCX | 正文、段落、表格、页眉、页脚、脚注、尾注 | line:S-E，可附 chars:S-E | 不做图片 OCR，也不是 Word 像素级渲染器 |
| XLSX | Sheet 清单、单元格值、范围、行列坐标 | 带引号规则的 Sheet!A1:F40 | 不计算公式、不解释图表/形状、不执行宏 |
| PPTX | 按页序提取 DrawingML 文本与 speaker notes | slide:N，可附页内行/字符范围 | 不做幻灯片图片 OCR，不解析图表数据、SmartArt、动画和嵌入对象 |
| JPEG/PNG/WebP/GIF | Harness 原生图片附件 | Harness 附件身份 | 需要支持视觉的模型；不由 read_document 解析 |

格式一律由字节判定，不看扩展名——可执行文件改名成 .pdf 会被拒绝。长输出按行分页并受字符预算约束，任何截断都会显式标记。

能力细节——输入框、检索、精确读取、视觉转交

输入框与上传

- 回形针多选文件、整文件夹选择，以及页面级拖放。
- Finder 多选会合并 DataTransfer.items 与 DataTransfer.files，混合批次不会悄悄只剩第一个可识别文件。
- 文档在 Harness 图片专用 drop handler 之前被接管；纯 JPEG/PNG/WebP/GIF 仍走原生图片链路。
- 有界并发上传（默认 4）；单个文件失败不会取消整批。
- 按字节嗅探真实格式的文件卡，展示 上传中 / AI 可读取 / 失败 状态。
- @ 候选同时包含上传文件和工作区文件，对模型只给出工作区相对路径，不暴露宿主机绝对路径。
- 每会话配额、SHA-256 去重、TTL 清理、安全文件名归一化、文件夹递归清理。

本地检索

- 中文连续段按重叠 bigram 建索引并以短语查询，因此 流程绩效 不会命中只含 绩效流程 的块。单汉字走有界子串回退；Q3 这类字母数字保持整词。
- 只有启动能力探针成功才启用 SQLite FTS5；否则明确选择 JS 内存后端，并在工具结果里说明。
- 默认不持久化模型检索词。

精确文档读取

- XLSX 支持工作簿结构盘点、1-based Sheet 选择、坐标保真的 A1 范围、合并表头、隐藏/稀疏 Sheet，以及明确的检测值计数。
- PPTX 按演示文稿关系声明的页序读取，而不是 ZIP 文件名顺序。
- system prompt 要求模型优先使用本插件工具；只有收到明确错误或"不支持能力"提示后，才可回退 Python/shell。

原生视觉转交

- JPEG/PNG/WebP/GIF 使用 Harness 原生输入框附件 rail 和供应商中立的 base64 image_url 路径。
- 所选模型仍必须声明支持图片输入；插件不会把纯文本模型变成视觉模型。

配置

bundle 在 cordis.patch.yml 中提供保守默认值。Harness 会在 bundle layer 之后应用用户 profile overlay，启动前先查看最终组合结果：

dsh --profile web --dump-config

| 配置项 | 默认值 | 含义 |
| maxFileBytes | 24 MiB | 单次文档读取字节上限 |
| uploadMaxBytes | 24 MiB | 单次上传请求体字节上限 |
| maxUploadBytesPerSession | 512 MiB | 会话上传配额；0 表示显式关闭 |
| readLimit | bundle patch 为 2,000；Schema 回退值 800 | 单次 read_document 返回的最大行数 |
| maxOutputChars | 24,000 | 基础字符窗口；叙述型格式使用更小的分格式窗口 |
| maxConcurrentUploads | 4 | 同时受理的上传请求体数量 |
| uploadTtlMs | 7 天 | 上传文件保留时长 |
| retrievalEnabled | true | 启用 search_documents；关闭后仍保留 read_document |
| retrievalMaxFiles / retrievalMaxResults | 12 / 12 | 单次检索文件数 / 返回证据块数 |
| retrievalQueryLogEnabled | false | 是否持久化归一化后的模型检索词 |
| trustedHosts | [] | 额外的反向代理 authority；为空表示仅回环 |

其余不常用配置项及其权威默认值见 src/index.ts。显式配置的 retrievalIndexDir 必须是绝对私有路径，且不展开 ~。

运行时后端。 包要求 Node.js >=22.13.0，这是 pdfjs-dist 的最低版本，且 Node 20 已于 2026-04-30 结束支持。持久检索索引还需要运行时提供 node:sqlite，并且编译了 FTS5。启动探针发现缺其中任意一项时，改用功能完整但仅限进程内的 JS 后端。回退是支持的，并写在工具输出里。

安全与隐私

- 按文件字节判断格式，不看扩展名。 扩展名只是提示。PDF 头与 OOXML ZIP 成员决定解析器；已知异类二进制和伪装文件会被拒绝。
- 有界 OOXML。 在解析器分配内存前限制 ZIP 成员数量与名称长度、声明 XML 大小、XML 总展开量、工作簿行列以及稀疏 Sheet 维度。
- 工作区包含性。 读取走 ctx.fs；存在 session cwd 时，目标必须留在当前会话工作区内。
- 安全上传落盘。 拒绝预先存在的符号链接与特殊文件；平台支持时使用 exclusive/no-follow 创建；配额与删除保持 fail closed。
- 默认仅回环。 上传与工作区端点要求回环 Host 并做同源校验。trustedHosts 只用于部署方控制的反向代理。

trustedHosts 不是身份认证。 当前 Harness WebServer 的插件约定不能证明某个 session ID 一定属于调用者。不要把本插件直接暴露成未经认证的公网多租户上传服务；应使用仅回环的自托管方式，或由同时约束 session 访问的认证代理承载。

数据存在哪里，什么会离开本机

| 存储 | 默认位置 | 内容 | 生命周期 |
| 上传文件 | <会话工作区>/.dsh-filess/<storageKey>/ | 上传的原始字节 | 每会话配额、SHA-256 去重、默认 7 天 TTL 清扫 |
| 检索索引 | $DSH_HOME/dsh-files/index | 供检索的索引内容、坐标、版本；只有显式开启时才存 query | 私有权限、文档/query TTL；无法持久化时回退 JS 内存 |

- 解析与索引都发生在 Harness 主机本地；插件自身不会调用任何外部解析服务。
- 但工具返回的证据确实会进入对话，并可能发送给你配置的模型供应商；原生图片附件同样会发送给所选视觉模型供应商。
- 不要把检索目录同步到云盘，也不要提交到 Git。

已知边界——本项目刻意不做的事

- 扫描版 PDF 和 Office 文件中的内嵌图片不做 OCR。
- Office 版式会转成文本和坐标，不做像素级还原。
- XLSX 公式不计算，宏永不执行。
- PPTX 图表、SmartArt、动画和嵌入对象不做解释。
- 上传配额锁是进程内的，不是跨进程事务。
- 纯 Node 没有完整可移植的 dirfd/openat 链，同 UID 恶意进程抢占祖先目录仍属于 OS 隔离边界。
- 清单允许 0.3.0 以下的 Harness 0.2.x 安装。端到端用过的仍是 0.1.7-rc.2 的 web profile；换更新的宿主之前，请先在本机冒烟。

项目状态

| 项目 | 公开源码 Beta，由 Cooberped 独立维护 |
| 目前测过 | npm @deepseek-ai/dsh@0.1.7-rc.2 的 web profile |
| 最低版本 | 0.1.7-rc.2 或更高，且低于 0.3.0。 在 0.1.6 及更早版本上，上传图标会对不上。若仍要跑更旧的 Harness，请用那次改动之前的代码，或上游 taxueseek/dsh-files；仓库没有为旧版打过 release tag |
| 实测目标模型 | OpenCode Go — DeepSeek V4 Flash |
| npm | 公开 Beta @baseland/dsh-evidence@0.6.0-beta.4（GitHub pre-release v0.6.0-beta.4）。请用 @beta 安装。latest 仍留在第一个已发布版本 0.6.0-beta.1；这次预发布不会移动它，这也不是稳定版。GitHub 仍是 Cooberped。包在维护者的 npm 账号 baseland 下，因为组织 @cooberped 无法认领 |
| 兼容性 | engines.dsh 为 >=0.1.7-rc.2 <0.3.0。@deepseek-ai/dsh-* 的 peer 使用同一范围，只有 @deepseek-ai/dsh-client-runtime 是 >=0.1.1-rc.2 <0.3.0，因为 npm 上没有更新的那一包。Harness 0.2.1 读 engines.dsh，忽略这些 peer。0.1.7-rc.2 和 0.2.0-rc.2 仍按 peer 判断。这是安装声明；这里还没有把完整的 0.2 会话重新跑一遍 |

本项目不是 DeepSeek 官方插件，与 DeepSeek 不存在隶属或官方背书关系。

和 dsh-files 的关系

本仓库保留 taxueseek/dsh-files 的 MIT 许可 Git 历史（含署名与 MIT 声明），并由 Cooberped 独立维护（已离开 GitHub fork 网络）。它不是 clean-room 重写。

不要在同一个 profile 里同时安装 dsh-files 和 @baseland/dsh-evidence。两者注册的 cordis 行 id 都是 files-toolkit。

在上游的上传与 read_document 之上，本仓库增加了本地私有检索（search_documents）、带版本校验的坐标、更严的上传/路径/OOXML 边界、PPTX 文本与演讲者备注、面向中文语序的检索，以及社区发布与治理。

开发

pnpm install --frozen-lockfile
pnpm typecheck
pnpm test
pnpm benchmark:retrieval
pnpm license:check
pnpm package:check

pnpm release:check # 以上全部，用于最终候选

release:check 覆盖类型检查、两个 bundle、聚焦回归测试、双后端检索正确性、许可策略，以及打包与发布要求。benchmark 使用确定性的合成 PDF/DOCX/XLSX/PPTX 素材——真实业务文档、答案集与模型输出一律留在仓库之外，详见 benchmark/README.md。

参与贡献

欢迎提交 Issue 和 Pull Request。所有贡献都由维护者在必需检查通过后人工评审合并，GitHub 不会自动合并社区代码。

Harness 界面、peer 或上游 API 断裂的修复尤其欢迎——0.1.7 将图标改名为 …Regular 即是一例。详见 CONTRIBUTING.md。

提 PR 之前：阅读 CONTRIBUTING.md 并为提交签署 DCO；为行为变更补充聚焦测试；在本地跑最小相关检查；不要把真实文档、凭据、私有路径和模型输出提交到 Git；每一项新增视觉素材都要登记到 assets/README.md。

安全问题按 SECURITY.md 处理。发布归属与来源检查见 RELEASING.md。

许可、传承与标识

项目代码与仓库原创 SVG 文档图形采用 MIT License。上游历史与版权声明完整保留。依赖与附带数据的许可见 THIRD_PARTY_NOTICES.md。

DeepSeek、DeepSeek Harness、OpenCode Go 及其他第三方名称或标识归各自权利人所有，此处仅用于说明兼容性或测试目标。素材来源登记见 assets/README.md。