加载dsh第三方插件

DSH 第三方插件加载

DeepSeek Harness（DSH）的设计哲学可以用一句话概括：Everything is a Plugin。模型适配器、工具注册表、会话日志，甚至 Agent 循环本身，全都是通过插件机制组装起来的。这意味着，理解如何加载第三方插件，就相当于掌握了扩展 DSH 能力的核心入口。

一、理解插件加载的本质

在动手之前，先厘清几个概念，这对后续排障至关重要。

Plugin 是装配单元 ：一个导出 apply(ctx) 函数的 TypeScript 模块。DSH 启动时加载它，执行 apply，插件再通过 ctx 注册具体能力。
Tool / Service / Event 是具体能力 ：插件可以注册工具（供模型调用）、服务（供其他插件依赖）或事件监听器。终端出现 plugin loaded 只证明 DSH 找到了插件并执行了 apply()；出现具体的 Tool call 才证明能力注册成功。验收插件时，一定要根据插件类型检查对应的效果，不能只看加载日志。

DSH 基于 Cordis 插件架构 ，一个核心规则是：loader id 必须在三处保持一致 ------cordis.patch.yml 中的 id、dsh.plugin.json 中的 id、以及宿主半边导出的 name。一旦错位，轻则插件管理功能静默失效，重则出现 duplicate loader entry id 启动崩溃循环。

二、安装第三方插件的三种方式

方式一：通过 DSH 官方插件命令（推荐）

这是社区插件最通用的安装方式，适用于已通过 npm 全局安装 DSH 的环境。

bash 复制代码

# 从 GitHub 仓库安装
dsh plugin --profile web add github:用户名/仓库名

# 从 npm 安装
dsh plugin --profile web add 插件包名

dsh plugin 命令会处理依赖安装和基本的目录结构，安装后插件处于"已安装·未启用"状态。建议优先采用此方式，因为它与 DSH 的 profile 管理机制配合最好。

方式二：通过插件市场（图形界面）

对于不熟悉命令行的用户，DSH 内置了插件市场入口：

进入 设置 → 插件 → 插件市场。
支持分类浏览 （Agent、MCP、开发工具等）、关键词搜索 和 AI 语义搜索（用自然语言描述需求）。
点击插件右侧的「安装」按钮。

市场会校验插件的 package.json 中是否声明了可直接启用的 DSH bundle，不完整的仓库不会被展示，也不会被安装入口放行。

方式三：源码本地安装（开发调试用）

如果正在开发插件或调试本地版本，可以采用 link 方式挂载：

bash 复制代码

git clone 插件仓库
cd 插件目录
npm install
# 以 link: 方式挂载进 profile，需手动在 cordis.patch.yml 中添加挂载行

纯数据类插件（如知识库插件）常采用这种方式，装完后需手动在 profile 的 cordis.patch.yml 末尾加一行挂载声明，重启会话后生效。

三、启用与生效：状态流转详解

安装只是把代码下载到当前 profile，不会自动启用。插件有四种状态：

状态	含义	下一步操作
已安装·未启用	代码已下载，未加入启用列表	点击「启用」
已启用·重启后生效	配置已修改，等待重启	重启 DSH
已启用	当前运行中已加载	正常使用
不兼容·不建议启用	与当前环境冲突	市场会阻止启用，避免启动失败

启用后如需重启，页面会明确提示并提供「立即重启生效」按钮。所有会改配置的操作都会先确认、写入前备份配置、写入后重新校验，失败则自动回滚。

停用 vs 卸载：停用只是把插件移出有序加载列表，本地依赖保留，可随时恢复；只有显式卸载才会删除代码文件。建议先停用观察，确认不再需要后再卸载。

四、加载顺序的调整

插件的加载顺序会影响依赖关系和功能优先级。DSH 官方 Profile 支持通过调整 cordis.patch.yml 中的列表顺序来控制 Bundle 加载顺序。

命令行方式 ：直接编辑 profile 目录下的 cordis.patch.yml，调整 - id: xxx 条目的先后位置。
图形界面方式：部分桌面启动器（如 dsh-melody-launcher）支持拖动列表直接调整加载顺序。

需要注意 ：@deepseek-ai/dsh-base、dsh-web-app、dsh-headless 三个核心组合层在主进程层面被禁止停用，界面上也不提供卸载入口，以确保核心功能稳定。

五、典型插件的加载实践

案例：加载一个 Tool 类型插件

以 text_stats 插件为例，它注册了一个统计字符数的 Tool。

安装：dsh plugin --profile web add github:用户名/dsh-text-stats
启用：在插件管理中点击「启用」，重启 DSH。
验收：
- 检查后端日志，应出现 plugin loaded 字样，证明 apply(ctx) 已执行。
- 在对话中问模型："请帮我统计这句话有多少个字符"，观察模型是否调用了 text_stats Tool。只有出现 Tool call 记录，才证明 Tool 注册成功。

案例：加载一个 UI 增强插件

以 dsh-enhance-tool 为例，它为 Web 界面增加润色、提示词库等功能。

安装：dsh plugin --profile web add github:dcrzsy/dsh-enhance-tool。
特殊依赖处理：部分插件可能需要手动链接宿主模块依赖（参考插件文档说明）。
重启：fuser -k 3080/tcp && nohup dsh web &，浏览器 Ctrl+Shift+R 硬刷新。
验收：composer 工具栏应出现新增按钮，侧边栏出现新入口。后端日志可 grep patched prepareCall 确认加载。

六、常见加载问题与排障

1. 启动时崩溃，报 `duplicate loader entry id`

原因：cordis.patch.yml 的 id、dsh.plugin.json 的 id、插件导出的 name 三者不一致。

解决：检查三处的标识符是否完全一致（包括大小写和 scope）。这是 DSH Desktop 已知的常见启动崩溃原因。

2. 安装后看不到插件功能

排查思路：

是否已点击「启用」？默认安装后是"已安装·未启用"状态。
是否已重启 DSH？部分插件修改需要重启生效。
浏览器是否硬刷新（Ctrl+Shift+R）？UI 类插件常因缓存不显示。

3. 插件市场不显示某个插件

市场会校验仓库的 package.json 中是否包含可直接启用的 DSH bundle 声明。纯界面包、不完整仓库、不可解析仓库不会被展示，也不会被安装入口放行。

4. 插件加载成功但模型不调用 Tool

终端出现 plugin loaded 只能证明 apply() 执行了，不等于 Tool 注册成功。需检查：

插件是否在 apply 中调用了 ctx.tool.register() 等注册方法。
检查模型是否配置了对应的 Tool 权限（部分模型需显式开启 Tool Call）。

七、开发环境与加载调试

如果需要深入调试插件加载过程，建议从源码运行 DSH，这样加载本地 TypeScript 文件更方便。官方文档站提供了完整的开发参考，推荐安装 dsh-plugin-dev-kb 知识库插件，它把官方 168 页文档整理为 agent 可自动加载的形态，写插件时无需反复翻网页。

固定一个稳定的 DSH 提交版本进行开发，可以避免主分支快速变化带来的干扰。目前 DSH 仍处于 Developer Preview 阶段，固定提交是减少环境差异的有效策略。