DeepSeek Harness 插件教程：安装、更新、卸载与恢复

如果你还没看 Profile 教程（/deepseek-harness/profile/），建议先补一遍再回来——插件安装里最常出现的两个概念都围绕它展开。

profile

profile 回答的问题是：这个插件要安装进哪一套 DSH 组合？例如日常使用 Web UI 时，目标 profile 通常是 web。

组合包

官方中文把这类包称为「组合包」。如果一个 npm 包声明了如下字段，它就是一个 DSH 组合包：

{
  "dsh": {
    "bundle": {
      "patch": "./cordis.patch.yml"
    }
  }
}

安装后，CLI 会把它加入对应 profile 的组合层列表。

插件包和组合包是不是一回事？

不完全是。dsh plugin 可以安装普通依赖，也可以安装带 dsh.bundle 声明的组合包。如果安装的包没有 dsh.bundle 声明，当前 CLI 仍然会把它保留为普通依赖，但会提示它不是 profile 配置层。

这是插件管理和前面的普通 npx 启动路线不同的地方。当前 dsh plugin --profile <name> ... 会把后面的参数转发给 pnpm，并在 profile 目录中执行。所以动手前先确认 pnpm 可用：

$ pnpm -v

第二步：先记录你要安装什么

安装任何第三方插件前，建议记录以下信息：

• 包名
• 来源
• 版本
• Git 仓库
• 如果来自 Git：Commit SHA
• 安装日期
• 当前 DSH 版本

例如这样一条安装记录：

• DSH：0.1.1-rc.2
• 插件：example-plugin
• 来源：GitHub
• Commit：abcdef123456...
• 日期：2026-08-23

这一步看起来很简单，但以后排错非常重要。因为插件项目会更新——如果只记录「我昨天装了最新版」，几天后就很难知道当时真正运行的代码是哪一版。

如果你日常使用 Web UI，通常目标 profile 是 web。普通 npx 用户的命令是：

$ npx @deepseek-ai/dsh plugin --profile web add <package>

例如概念上：

$ npx @deepseek-ai/dsh plugin --profile web add some-plugin

这里不是全局安装。它的意思是把这个依赖安装到 web profile。

dsh plugin 实际做了什么？

当前实现大致分成三步：

1. 如果 profile 不存在，先初始化
2. 在 profile 目录里执行对应的 pnpm 命令
3. 命令成功后重新检查已安装依赖

如果依赖声明了 dsh.bundle，CLI 会把它加入 dsh.profile.bundles。如果以后更新的版本新增了 dsh.bundle，当前 CLI 在 update 后也会重新识别并激活它。

安装成功后，第一件事不要急着启动

先检查 profile 组合：

$ npx @deepseek-ai/dsh --profile web --dump-config

或者：

$ npx @deepseek-ai/dsh web --dump-config

最低标准是 pnpm 操作成功、且依赖出现在 profile 中。但到这里仍然只能说「安装步骤成功」，不能直接写「插件已验证可用」。

第二层验证：已经进入组合

对于声明 dsh.bundle 的插件，运行：

$ npx @deepseek-ai/dsh --profile web --dump-config

确认三件事：能看到对应组合包层；相关配置行存在；没有明显 patch 目标错误。

如果包安装成功但 dump 里没有它，先检查它是否真的声明了 dsh.bundle。如果没有，当前 CLI 会把它当普通依赖，而不是 profile 层。

第三层验证：重启 profile

这是非常重要的一步。当前官方 CLI 明确：安装、移除或更新 Bundle 后，只会改变磁盘上的 profile manifest 和 Bundle 列表；正在运行的 profile 会继续保持本次启动时的 Bundle 集合。所以安装或更新以后，需要停止当前 DSH，再重新启动：

$ npx @deepseek-ai/dsh web

这一步验证的是新的组合能不能真的启动。

为什么 cordis.patch.yml 可以热更新，Bundle 却要重启？

当前 profile / home 的普通 cordis.patch.yml 支持运行时重新组合，但 Bundle 成员列表是在 profile 启动时确定的：

这两个生命周期不要混淆。

第四层验证：能力有没有真正出现？

profile 能启动还不够，你还需要检查插件声称提供的能力是否真的出现在 DSH 中。不同插件验证方式不同，例如可能是：新工具、新 Provider、新 UI、新服务、新 Agent 预设能力、新设置项。

下面两张截图来自一个安装了第三方插件的扩展环境（用户日常环境，浅色主题为环境原状），可以看到「能力出现在 Web UI 里」的实际样子。注意：这些第三方插件是自己安装之后才有的，默认安装并不自带。

EXTENDED点击放大

EXTENDED点击放大

第五层验证：做一次最小功能测试

真正的插件验证必须落到核心功能。例如一个插件声称提供某个工具，就让智能体执行一个最简单、低风险的调用，并验证三点：

1. 工具真的能被发现
2. 工具调用能执行
3. 返回结果符合预期

最终只有做到「安装 → 进入组合 → 能启动 → 能力出现 → 核心功能成功」这条链，DSHOPC 才适合把它标记成「当前版本实测可用」，而且还必须记录测试环境。

如果插件已经发布为可直接安装的 npm 包：

$ npx @deepseek-ai/dsh plugin --profile web add <package>

例如：

$ npx @deepseek-ai/dsh plugin --profile web add @scope/package

这通常是用户侧最简单的分发方式，但仍然要继续做 dump-config → 重启 → 功能验证。不要因为来自 npm 就跳过验证。

从本地插件目录安装

当前 CLI 会处理相对路径，使它们相对于你运行命令时所在的目录解析，而不是错误地指向 profile 自己的目录。例如在某个插件 checkout 中：

$ npx @deepseek-ai/dsh plugin --profile web add .

可以把当前 checkout 加入目标 profile。这种方式更适合本地开发、插件调试、修改源码以后验证。

从 GitHub 安装

当前 DSH 支持通过 pnpm 的 Git / GitHub spec 安装：

$ npx @deepseek-ai/dsh plugin --profile web add github:owner/repo#<commit-sha>

Git 安装拿到的通常是源码，而不是 npm 发布包里已经准备好的构建产物。如果插件是 TypeScript，可能需要在安装阶段运行 prepare，生成真正可加载的代码。当前官方文档明确：pnpm ≥10 默认会阻止 Git 依赖的构建脚本，直到用户显式授权。这时第一次 add 可能失败，并提示 allowBuilds。

allowBuilds 到底是什么意思？

以下面这种写法为例：

allowBuilds:
  some-plugin: true

什么情况下才应该加 allowBuilds？

1. 确认包来源
2. 阅读或审查过仓库
3. 确认确实需要安装阶段构建
4. 接受该代码在本机执行

以上都确认以后，再按 pnpm 实际输出，把准确的包键加入该 profile 的 pnpm-workspace.yaml，然后重新运行安装命令。

为什么固定 Commit 很重要？

即使你已经审查了 GitHub 仓库，也要确认「你审查的代码」和「你安装的代码」是同一份。更稳妥的方式是仓库、Commit SHA、安装记录三者齐备：

$ npx @deepseek-ai/dsh plugin --profile web add github:owner/repo#abc123...

这样后续仓库 main 分支变化，不会自动把你锁定的 Commit 变成另一份代码。

npm / tarball 为什么通常不需要这道 Git 构建授权？

如果包发布时已经构建好了可运行产物，用户安装时就不需要通过 Git prepare 再现场构建。官方文档给出的两种思路包括：

• 发布预构建 npm 包
• 提供 pnpm pack 生成的 tarball

因为 dsh plugin 把参数转发给 pnpm，所以可以使用 update 子命令：

$ npx @deepseek-ai/dsh plugin --profile web update <package>

更新以后不要直接结束。继续检查组合：

$ npx @deepseek-ai/dsh --profile web --dump-config

然后重启 web profile，最后重新执行最小功能验证。

为什么更新比第一次安装更需要记录版本？

因为插件升级后可能发生：

• manifest 变化
• Bundle 层变化
• 配置 schema 变化
• DSH API 兼容变化
• 功能行为变化

所以 DSHOPC Lab 如果以后写「这个插件可用」，应该明确记录插件版本 / Commit、DSH 版本、Node.js、系统、测试日期，而不是只写「最新版可用」。

怎么查看插件为什么被安装？

因为 pnpm 子命令会被转发，可以使用：

$ npx @deepseek-ai/dsh plugin --profile web why <package>

这类命令适合排查它是直接依赖，还是被其他包带进来的。

怎么卸载插件？

$ npx @deepseek-ai/dsh plugin --profile web remove <package>

当前 CLI 成功后会重新检查安装状态。如果这个依赖原来还是一个 Bundle，它也会从 dsh.profile.bundles 中移除。

卸载以后怎样确认真的移除了？

同样不要只看 remove 成功，建议做三步。第 1 步，查看组合：

$ npx @deepseek-ai/dsh --profile web --dump-config

确认对应 Bundle 层已经消失。第 2 步，重启 profile：

$ npx @deepseek-ai/dsh web

第 3 步，检查能力：确认原来的插件能力已经不再出现。这样才算完成一次完整卸载验证。

先回忆：最后一个发生变化的 Bundle 是什么？如果故障发生在刚安装一个插件以后，可以按这个思路缩小范围：

1. 安装前正常
2. 安装某插件
3. --dump-config 能看到新层
4. 重启失败

走到这里，已经把故障范围缩小到「新 Bundle 或它与当前组合的兼容问题」。优先顺序是：

1. 记录错误
2. 确认插件版本 / Commit
3. 检查 --dump-config
4. 移除刚安装的插件
5. 再次 dump
6. 重启验证基线是否恢复

一个最小恢复流程

假设 some-plugin 导致 web profile 无法正常启动。可以先移除它：

$ npx @deepseek-ai/dsh plugin --profile web remove some-plugin

然后：

$ npx @deepseek-ai/dsh --profile web --dump-config

确认插件层消失。再：

$ npx @deepseek-ai/dsh web

如果原来的 Web UI 基线恢复，说明故障和该插件变化高度相关。但还不能自动得出「插件代码一定有 Bug」的结论——也可能是下面这些原因：

• DSH 版本不兼容
• 配置冲突
• 插件依赖缺失
• 当前操作系统差异
• 使用方式错误

这种兼容性结论应该进入 Lab。

DSHOPC 对插件建议统一使用下面这些状态：

其中「DSHOPC 已验证」还必须增加这些记录：

• 测试日期
• DSH 版本
• Node.js
• 系统
• 插件版本 / Commit
• 测试步骤
• 实际结果
• 已知问题

一个建议的插件验证卡

以后 DSHOPC Lab 可以统一按下面的卡片记录。这样「插件可用」就不再是一句模糊判断：

插件：
来源：
版本 / Commit：

DSH：
Node.js：
系统：
测试日期：

[ ] 安装成功
[ ] dump-config 出现 Bundle
[ ] profile 重启成功
[ ] 插件能力出现
[ ] 最小功能成功
[ ] 卸载成功
[ ] 基线恢复

已知问题：

• dsh plugin 是针对 profile 管理依赖
• 当前插件管理依赖 pnpm
• 安装成功不等于成为 Bundle
• dsh.bundle 决定一个依赖是否进入 profile 组合层
• 安装后应该先 --dump-config
• Bundle 安装 / 更新 / 删除后要重启 profile
• allowBuilds 允许安装阶段本机代码执行
• 第三方 Git 插件更适合固定 Commit
• 最终必须做最小功能验证
• 卸载后也要 dump + 重启 + 检查能力消失

如果这些已经清楚，你已经具备 DSH 插件的基础安装与验证能力。

如果你准备创建「做事方法」，继续看技能教程（/deepseek-harness/skills/）——技能路线和第三方插件安装不是同一件事。

如果你准备接外部 MCP Server，继续看 MCP 教程（/deepseek-harness/mcp/）——你已经具备理解 MCP Client 插件和 profile 配置所需要的基础。

如果插件出现故障，直接进入故障排除（/deepseek-harness/troubleshooting/），它是随时可进的恢复入口。

以后如果 DSHOPC 对某个具体插件完成真实安装、启动和功能验证，详细结果应该放到 Lab，而不是把单次经验塞回这篇通用教程。

• 用五层标准判断插件：安装 → 组合 → 启动 → 能力 → 核心功能
• 第三方 Git 插件固定 Commit
• 插件第一次验证使用测试环境和低风险任务
• 不把 npm / GitHub 来源当作安全认证
• 不把 allowBuilds 当成普通功能开关
• 插件故障优先恢复最后变化，而不是先删除整个 Harness home
• 「当前可用」「已验证」等结论应进入 Lab 并附完整测试环境