dsh-plugin-corpus

dsh plugin --profile web add dsh-plugin-corpus

dsh-plugin-corpus（插件使用与开发说明）

dsh-plugin-corpus 是 DeepSeek Harness (DSH) 的文件语料库插件。

它的核心思想很简单：

• 内容是普通文件：语料根目录可以整体搬走、备份；
• 索引只是缓存：每个集合一份 SQLite，可以随时重建；
• 模型只读 processed/：插件不再保存源文件；
• 一切访问先过 ACL：按工作区/会话/路径授权，默认拒绝。

当前版本：1.5.0。

---

1. 安装与启用

从 Release 安装

1. 下载 dsh-plugin-corpus-v<version>-plugin.zip；

2. 解压到 %USERPROFILE%\.dsh\plugins\，得到：

   %USERPROFILE%\.dsh\plugins\dsh-plugin-corpus\

3. 确认 DSH profile 的 dependencies 和 dsh.profile.bundles 都包含

dsh-plugin-corpus（通过插件管理器安装时通常会自动完成）；

4. 完全重启 DSH。宿主半部（工具、提示词、面板路由、提取器）和客户端

bundle 都只在进程启动时加载，刷新浏览器不够。

默认语料根：

%USERPROFILE%\.dsh\corpus

可以在面板的 语料库根目录 设置中修改或迁移。

从 npm / 插件市场安装

dsh plugin add dsh-plugin-corpus

安装后完全重启 DSH。npm 包：<https://www.npmjs.com/package/dsh-plugin-corpus>。

从源码部署

git clone https://github.com/czdcm/dsh-plugin-corpus.git
cd dsh-plugin-corpus
powershell -NoProfile -ExecutionPolicy Bypass -File tools\deploy.ps1
# 完全重启 DSH

tools\deploy.ps1 会把 plugin/ 复制到 DSH 插件目录。GitHub 源码 clone 不含 vendor 二进制；完整安装请用 Release 包，源码开发前先把 vendor 文件放回 plugin/vendor/，否则脚本会提示降级。

---

2. 界面与日常使用

左侧栏「语料库」

• 导入语料：浏览器文件可多选；本机路径可多行输入（每行一个文件/目录），同一批全部导入同一个集合；集合留空会自动创建 import-日期-时间；集合名支持中文、空格和常用符号（≤64 字符，不能含 / \ : * ? " < > |）；
• 公式与图形：HTML MathML、Word/PowerPoint OMML、Unicode 数学符号和已有 LaTeX 会统一整理为 $...$ / $$...$$；Office/PPT 会读取对象树、连接线、图表并渲染版式缩略图，提示词要求解释图形逻辑，不再以“图示略”跳过；
• 检索：按关键词搜索已索引的 processed/ 内容；结果只用于定位，不直接打开预览；
• 查看：文件列表每行的「用外部软件打开」主按钮优先读取 Windows 默认关联直接打开；没有关联时打开系统软件选择器，由 Windows 记录本次选择；▾ 可再次打开系统软件选择器；文件列表的图标/名称/类型跟随处理后语料类型，按钮只显示默认应用图标，右侧箭头保留系统选择器；不再内置右侧栏预览；
• 语料文件：按集合分组的资源管理器式列表；
• 集合组默认折叠，点集合标题 ▸/▾ 展开或折叠；
• 顶部有「全部展开 / 全部折叠」；
• 每行显示图标、名称、类型、大小、导入时间、操作；
• 行尾「删除」是两击确认的软删除；
• 重建：增量/全量重建索引；
• 根目录设置：查看、复制、打开、迁移语料根。

右侧栏「语料权限」

• 查看当前会话/工作区实际能访问哪些集合；
• 编辑策略：默认拒绝，按 workspace/session 授权，可设置过期时间；
• 保存前自动备份原策略。

主会话工具

模型可以通过 13 个工具使用语料库：

工具 · 用途

corpus_search · 在可访问集合中检索

corpus_read · 按路径和行范围读取 processed 文档

corpus_list · 列出集合与文档

corpus_catalog · 返回集合/文档卡片、行数、章节目录摘要

corpus_outline · 返回章节/小节标题、起止行号、摘要；缺失目录时按需生成

corpus_reindex · 启动增量/全量重建

corpus_status · 查看重建/导入任务、索引状态、访问范围

corpus_import · 导入本机文件或已上传文件

corpus_ingest · 后台提取并导入文档

corpus_structure · 把仓库/目录/文件/文本总结为结构化语料

corpus_summarize_session · 把会话总结成语料

corpus_delete · 软删除单篇或整个集合

corpus_access · 解释当前工作区/会话的权限范围

---

3. 数据布局

<CORPUS_ROOT>/
├─ <collection>/
│  ├─ <subfolder>/      可选，可继续嵌套，形成树状目录
│  └─ <import-folder>/
│     ├─ processed/     模型使用的 Markdown
│     └─ .meta.json
└─ .corpus/
   ├─ index/<collection>.sqlite
   ├─ config.json
   ├─ outlines/<hash>.json  文档结构目录（不进入检索分块）
   ├─ import-tmp/
   └─ trash/<时间>/     软删除内容，可手动恢复

每次导入都有自己的文件夹，方便整体删除或迁移；集合内部也可以建子目录并继续嵌套，文件列表按目录分组。

索引表很轻：

• docs：文档路径、标题、大小、mtime、hash、块数；
• chunks：块文本、标题、行号范围；
• meta：indexed_at 等元数据。

删除索引不会丢语料；重新 corpus_reindex 即可重建。

---

4. 支持的文件格式

格式 · 提取方式

.md .markdown .txt .text · 直接读取文本

.html .htm · 去标签，保留标题/段落/列表

.csv · 文本化表格

.pdf · 随包 pdftotext 抽文字层；缺文字层/乱码的页逐页用 Windows OCR，最后按页序合并

.docx .xlsx .pptx · 优先 OfficeCLI；失败/缺失时回退纯 JS ZIP+XML 解析

.png .jpg .jpeg .webp .gif .bmp .tif .tiff · 有可用视觉模型时结构化；否则使用 Windows OCR/占位 Markdown

PDF 文本在进入 AI 前会做质量闸门：空格比例过低、符号/控制字符异常或夹带 PDF/JPEG 二进制标记的输出会被丢弃。逐页判断：可读的页保留文字层，缺文字层/乱码的页单独 OCR，合并后仍不可读时导入失败，不会把乱码写进 processed/。.meta.json 的 pdfPages 记录总页数、文字层页数、OCR 页数与不可读页数。

面板里的 Vision 不可用时会显示具体原因，通常是当前默认模型不支持图片输入。可以在 DSH profile 的插件配置中设置 ingestVisionProvider / ingestVisionModel 指向可接收图片的模型；未配置视觉模型时图片退回内置 Windows OCR。

完整包随附 PDF/Office 工具。没有 officecli 时 Office 回退纯 JS；没有 pdftotext 时 PDF 文字层不可提取，只能整本走 Windows OCR（非 Windows 则无法导入 PDF）。官方 Release 只发布完整包。

OfficeCLI 是 Apache-2.0；Poppler pdftotext 是 GPL-2.0-or-later，详见仓库根目录的

THIRD_PARTY_NOTICES.md。

---

5. 访问控制（ACL）

策略文件默认位置：

%USERPROFILE%\.dsh\corpus-access.json

结构示例：

{
  "version": 1,
  "default": "deny",
  "grants": [
    {
      "workspace": "C:/Users/<you>/work/project-a",
      "paths": ["collection-a"]
    },
    {
      "session": "session-id",
      "paths": ["collection-b/guides", "collection-b/reference.md"],
      "expiresAt": "2027-01-01T00:00:00.000Z"
    }
  ],
  "deny": []
}

规则：

• 默认拒绝；grants 按 workspace/session + 路径匹配；
• 显式 deny 优先于 grants；
• 过期的 grant 自动忽略；
• 集合名、路径前缀、glob 都可以作为 paths；
• 工具调用、提示词列表、面板 /access 使用同一套判断。

右栏「语料权限 → 全局」的「全局访问」用于默认拒绝时给指定合集放行：填写合集名后点击添加，保存为 workspace: "*" 的 grant，对所有工作区/会话生效；其他合集仍按默认拒绝。

仓库中的 config/corpus-access.example.json 是脱敏模板；本机 ACL 文件不要提交。

---

6. 配置项

插件配置（DSH profile 中）：

配置 · 默认 · 说明

corpusRoot · 空 · 覆盖语料根；空 = ~/.dsh/corpus

promptOrder · 9000 · 语料提示词段在 system prompt 中的顺序

maxPromptFiles · 12 · 提示词里最多列多少个文件标题

maxPromptChars · 8000 · 提示词目录文本的最大字符数

ingestProvider / ingestModel · 空 · 内置小代理使用的模型覆盖

ingestVisionProvider / ingestVisionModel · 空 · 图片识别使用的视觉模型；留空跟随默认模型

ingestMaxChars · 24000 · 单次 ingest 的材料上限

ingestTimeoutMs · 120000 · ingest LLM 超时

structureMaxChars · 48000 · 仓库/会话结构化的材料上限

maxToolOutputChars · 24000 · 工具返回值的硬上限；超限时逐级压缩长字符串/长数组并标记 _truncated，避免把超大文本写进会话历史

perfLogMs · 250 · 单次 corpus_import 超过该毫秒数时写 warn 日志，便于定位慢导入

性能说明（v1.5.0）：插件跑在 DSH 宿主进程里，任何同步长任务都会连带卡住 GUI。

现在导入按文件异步执行、每 32 个文件或 8ms 让出一次事件循环；单次导入只预热前 40 份目录，

其余按需生成。提示词目录缓存 60 秒、面板轮询缓存 1.5 秒，导入/重建/删除后主动失效。

---

7. 面板 HTTP API

面板使用同源路由，前缀：

/api/dsh-plugin-corpus

路由列表：

GET  /overview          GET  /files             POST /search
POST /read              POST /reindex           GET  /status
GET  /access            GET  /import/targets    POST /import
GET  /import/status     POST /delete            GET  /gallery
GET  /settings          POST /settings/root     POS

…(truncated)