前言¶
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 仓库。
