wct-lab/dsh-docchain：DSH 文档检索与转换插件

前言¶

DSH（DeepSeek Harness）采用「一切皆插件」的架构，扩展能力通过插件实现。在构建基于文档的知识库或研究工作流时，开发者需要处理文件检索、内容搜索、元数据查询、批量上传、格式转换等重复性工作。手工编写这些功能耗时且容易出错。wct-lab/dsh-docchain 是一个面向 DSH 的文档检索与转换插件，它将常见的文档操作封装为可复用的技能（skill），开发者安装一次即可在任意机器上使用，无需手动复制文件到 ~/.agents/skills。

插件定位¶

这是一个基于 docchain 构建的 DSH 知识库和文档转换插件，提供文件名/内容/元数据搜索、主题列表、批量上传、文档转 Markdown、图像相似性搜索以及多子智能体深度研究工作流。插件通过插件配置页面管理多个 docchain 环境，每个环境拥有独立的地址和凭证，支持按环境预选主题。

核心功能¶

插件提供以下技能（skill），每个技能由 SKILL.md 说明和对应的 Node.js 脚本组成：

docchain-filename-search：按关键词在主题范围内搜索文件名
docchain-content-search：按关键词搜索文档内容，返回行号和内容，支持 or/and 操作符
docchain-meta-search：通过自定义元数据字段查询文档（字符串/数字/时间类型，支持精确匹配和范围查询）
docchain-topic-info：列出 docchain 主题，支持分页和按名称或 ID 过滤
docchain-upload：将本地文件或整个文件夹批量上传到指定主题
doc2markdown：将 docx/doc/pdf/pptx/xlsx/images 等多种格式转换为 Markdown，结果与源文件并排
docchain-image-search：通过示例图片查找相似图片，返回匹配图片及其主题、文档和相似度分数
deep-research-advanced：多子智能体深度研究工作流编排器（纯指令，无脚本）

安装与启用¶

插件需要根据运行 DSH 的方式选择对应的安装命令：

运行方式	命令
桌面应用	`dsh plugin --profile desktop add github:wct-lab/dsh-docchain`
`dsh web`	`dsh plugin --profile web add github:wct-lab/dsh-docchain`

安装完成后需重启 DSH，使宿主和客户端重新加载。

配置（必需）¶

插件不包含预置凭证。除 doc2markdown 外，所有脚本在运行前都需要配置 docchain 服务端点和 API 密钥；doc2markdown 可使用内置默认端点匿名上传。配置字段包括：

| 字段 | 说明 | 是否必需 |
|—|—|
| docchain_url | docchain 服务地址，例如 http://<host>:7100/llmdoc | 是 |
| docchain_api_key | API 认证密钥 | 是 |

配置提供方式按优先级排序：

环境变量 DOCCHAIN_URL 和 DOCCHAIN_API_KEY
单个技能的配置文件 <skill>/scripts/config.json
插件状态文件 ~/.dsh/storages/docchain-config.json（由插件配置页面写入）
包级 skills/docchain_config.json（文件分发时的回退，插件仅提供 docchain_config.example.json 模板）

配置文件格式示例：

{
  "docchain_url": "http://<host>:7100/llmdoc",
  "docchain_api_key": "your-api-key-here"
}

所有脚本依赖 Node.js，调用方式为在技能基础目录执行 node scripts/<script>.js …，具体参数见各 SKILL.md。

插件配置（推荐）¶

插件在 DSH web 客户端提供配置页面：在 dsh web 左侧栏打开「Plugins」，找到 dsh-docchain 插件，点击行上的配置按钮。该页面管理一组已保存的环境，每个环境包含地址和凭证引用，并预选主题。当前生效的环境显示在单行中，点击可查看列表、添加/编辑/删除条目。切换环境立即生效，无需保存或重启。

配置页面遵循官方凭证模式，配置模式声明以下字段：

字段	说明
`docchain_url`	未激活环境时使用的服务端点，与当前环境同步
`docchain_api_key_ref`	凭证引用名称，默认为 `DOCCHAIN_API_KEY`
`docchain_api_key`	回退明文密钥（不推荐，存储优先）
`docchain_environments`	已保存环境列表（JSON），每条包含名称、URL、凭证引用和预选主题

密钥值存储在凭证存储 ~/.dsh/.credentials.yaml 的 refs 部分（仅所有者权限）。通过配置页面保存或直接编辑该文件即可生效，修改会热重载。激活时，每次存储凭证变更或行设置保存后，解析后的值会写入 ~/.dsh/storages/docchain-config.json（权限 0600），该文件是当前解析的纯投影。密钥解析顺序为：凭证存储（启动环境 > 存储文件）> 行中的 docchain_api_key。

引用名称本身即配置：不配置 docchain_api_key_ref 是有效状态，此时页面报告无密钥，脚本会以配置错误退出，而不是回退到其他引用。保留但错误的密钥会静默查询错误的账户，比失败更难察觉。

切换环境¶

配置页面维护一组已保存环境，切换不同 docchain 服务时无需重复输入 URL 和密钥：

页面显示当前生效的环境行，点击可展开列表
选择条目立即生效，无需保存或重启
每个环境存储独立的 URL 和凭证引用，切换回时不再请求密钥
凭证引用保留在凭证存储中，仅写入不读取
页面仅管理环境，地址和密钥是环境的属性，编辑在行内完成
无保存条目时，行显示「no environment selected」，docchain_url 和 docchain_api_key_ref 作为回退值（可在 cordis.patch.yml 中编辑）
删除条目会删除其凭证，除非另一环境仍使用该引用或该引用是回退引用；生效条目不能删除，需先切换

数据位置¶

内容	位置
环境列表（名称、URL、凭证引用、预选主题）	插件配置页面
密钥值	`~/.dsh/.credentials.yaml`（`refs` 部分）
解析后的配置投影	`~/.dsh/storages/docchain-config.json`

典型用法¶

以下示例展示常见操作：

在 dsh web 中安装插件并重启
打开 Plugins 页面，配置 dsh-docchain，添加一个环境，输入地址和密钥，预选主题
在技能列表中调用 docchain-filename-search，按关键词搜索文件名
使用 docchain-content-search 搜索文档内容，关键词用 or/and 组合
通过 docchain-upload 批量上传本地文件到指定主题
使用 doc2markdown 将文档转换为 Markdown，结果与源文件并排

适用场景与注意事项¶

适合需要与 docchain 服务交互的 DSH 用户，包括知识库管理、文档检索、批量上传、格式转换和基于文档的研究工作流。

使用时需注意：插件以当前 dsh 进程的权限运行；安装前应检查源码与许可证；配置密钥时注意解析顺序和引用名称配置；doc2markdown 不依赖配置，其他脚本必需配置；凭证引用未配置时脚本会报错而非回退。

小结¶

wct-lab/dsh-docchain 将文档检索与转换能力标准化为 DSH 技能，通过配置页面管理多环境切换，支持批量操作和深度研究工作流。开发者安装一次即可在任意机器复用这些能力，避免重复实现。更多详情见插件目录页与 GitHub 仓库。