如何安装 DeepSeek Harness 插件

DeepSeek Harness 会把插件安装到指定的 profile（配置档） 中。这个边界非常重要：安装到 web 会改变 Web 组合，其他 profile 则维护自己的依赖和 patch 层。

本教程依据当前 developer preview 的官方 CLI 参考编写。实际操作前，请同时核对插件仓库说明和你所运行 Harness revision 对应的官方文档。

还没有候选插件？先浏览 DeepSeek Harness 插件目录。想理解整体原理？阅读 DeepSeek Harness 指南。

安装前准备

你需要：

Node.js，用于运行官方 @deepseek-ai/dsh 包。
系统 PATH 中可用的 pnpm；Harness 插件命令会在目标 profile 内把包操作转发给 pnpm。
一个 profile 名称。官方 Web UI 使用 web，一次性终端任务使用 headless，测试陌生插件时可以使用独立自定义 profile。
已经审查过的包名或 Git 规格，并且它来自插件的权威仓库。

先启动一次官方 Web UI，确认基础安装可以工作：

npx @deepseek-ai/dsh web

下文按照官方参考使用 dsh 作为 CLI 名称。如果系统 PATH 中没有该命令，可以把相同参数交给 npx @deepseek-ai/dsh 执行。

第一步：检查插件仓库

复制安装命令前，至少确认：

来源记录指向预期的作者与仓库。
README 说明支持的 Harness 版本或 revision。
包清单中的包名与准备安装的对象一致。
安装和 prepare 脚本用途清晰且确有必要。
所需凭据、文件系统访问、命令和网络目标符合预期能力。
仓库说明了配置与卸载方法。

公开或近期更新的仓库并不等于安全。Star 数和目录标签只能作为发现信号。

第二步：选择目标 profile

如果能力明确属于现有界面，可以使用对应 profile。例如，Web 客户端扩展通常安装到 web：

dsh --profile web --dump-default-config

评估陌生插件时，建议使用单独 profile。缺失的官方 profile 会从内置模板初始化；其他新 profile 由插件命令初始化时会从 base bundle 开始。

dsh plugin --profile plugin-test add github:owner/repository

隔离可以减少配置相互影响，但不会自动让不可信代码变安全。插件安装和运行仍可能使用当前进程拥有的权限执行代码。

第三步：安装 DeepSeek Harness 插件

安装维护者公开的 GitHub 仓库：

dsh plugin --profile web add github:owner/repository

安装已经发布的包：

dsh plugin --profile web add package-name

如果没有全局可用的 dsh 命令，可以通过 npm 执行等价操作：

npx @deepseek-ai/dsh plugin --profile web add github:owner/repository

不要根据仓库名称猜测包名，必须使用维护者文档中的精确包名或 Git 规格。

包操作成功后，Harness 会重新核对 profile 的 bundle 列表。清单中声明 dsh.bundle patch 的依赖会加入 bundle 栈；没有这项声明的依赖会作为普通依赖保留并显示警告，可能还需要按文档手动添加 patch 才会产生效果。

第四步：安全处理 pnpm `allowBuilds`

部分 Git 插件会通过 prepare 脚本在安装时构建源码。pnpm 10 及更高版本可能在第一次尝试时阻止构建，并输出 allowBuilds 提示。

应把这次失败当作审查节点：

阅读包的 prepare 脚本及其调用代码。
确认被阻止的包 key 确实属于目标仓库。
按 CLI 输出指引，只把已经审查的 key 加入该 profile 的 pnpm-workspace.yaml。
重新执行相同的 add 命令。

不要为了通过安装而广泛允许所有构建脚本。预构建 tarball 或本地 checkout 可能不需要该授权，但仍然需要代码审查。

第五步：验证安装结果

先让 pnpm 说明目标 profile 为什么包含这个包：

dsh plugin --profile web why package-name

再在不启动应用的情况下检查完整组合配置：

dsh --profile web --dump-config

确认预期的 bundle 或配置行已经出现，同时检查是否意外改变了其他提供方、权限或网络服务。然后启动 profile：

dsh --profile web

先验证最小目标流程，并关注终端与浏览器控制台中的启动失败、缺失服务、权限提示和意外外部请求。

更新或卸载插件

阅读发布说明和兼容变更后再更新：

dsh plugin --profile web update package-name

从同一个 profile 中删除依赖：

dsh plugin --profile web remove package-name

完成任一操作后再次运行 --dump-config。Harness 会在成功的包操作后重新核对 bundle 成员，但用户自行添加的 patch 行或插件数据可能仍需按照仓库说明单独清理。

DeepSeek Harness 插件安装故障排除

找不到 `pnpm`

安装 pnpm，并确认 pnpm 可执行文件位于 PATH 中。即使通过 npm 启动 Harness，插件子命令仍会在 profile 目录内使用 pnpm。

第一次 add 出现 `allowBuilds` 错误

这是 pnpm 对源码构建执行的保护。检查提示中的包和脚本，仅在指定位置添加已批准 key，然后重新运行相同命令。

包已安装但界面没有变化

检查安装输出与包清单。未声明 dsh.bundle patch 的依赖不会自动加入配置，只会作为普通依赖保留。请按维护者与当前版本匹配的说明添加 patch。

Profile 无法启动

使用 dsh --profile web --dump-config 检查组合配置，再比较插件兼容说明与当前 Harness revision。如果无法确认安全且受支持的配置，应从受影响 profile 中移除插件。

改动了错误的 profile

每条管理命令都应明确带上目标 --profile <name>。分别对预期和误操作的 profile 运行 why 与 --dump-config，然后从错误 profile 中删除该包。

安装安全检查清单

核对作者、仓库、包名和当前 revision。
阅读安装、prepare、postinstall 与运行时脚本。
检查依赖和锁文件变化。
检查文件系统、命令、凭据、浏览器与网络访问。
使用测试 profile 和最小权限。
需要可复现时固定已审查版本或 commit。
启动前检查组合后的配置。
保存准确卸载命令和数据清理步骤。