DeepSeek Harness 插件系统入门:从＂会用＂到＂会写＂,10 分钟搞懂＂一切皆＂

上一篇我们成功把 DeepSeek Harness（dsh）跑了起来。今天来聊一个绕不开的话题——插件系统。

dsh 最核心的设计哲学只有一句话：

一切皆插件（Everything is a Plugin）

什么意思？你用的 Web 界面、命令行模式、文件操作、模型适配、权限审批……全是插件拼出来的。想加新能力？装个插件就行，甚至自己写一个。

这篇文章带你把插件系统从"会用"到"会写"完整过一遍，全程 10 分钟。

01 先搞懂三个关键概念

插件系统看起来复杂，其实只有三个核心概念：

① 插件（Plugin）—— 能力的积木

一个插件就是一段 TypeScript 代码，向外导出一个函数。框架加载插件时调用它，插件通过传入的上下文对象向框架注册能力（工具、服务、事件监听……）。applyctx

② 组合包（Bundle）—— 打包好的插件集

单个插件能力太小，所以官方把一组插件打包成 npm 包，这就是 bundle。bundle 的 npm manifest 里会声明自己的补丁文件（），安装后自动贡献一组配置。dsh.bundle.patch

③ 配置档（Profile）—— 你"这台机器"的装配图

Profile 是下的一个目录（默认是）。它回答一个问题：**"我这套配置由哪些 bundle、按什么顺序组成？"**$DSH_HOME/profiles/<名字>$DSH_HOME~/.dsh

每个 profile 包含：

package.json —— 记录了（有序的 bundle 清单）和额外插件依赖dsh.profile.bundles
cordis.patch.yml —— 你自己写的补丁层，可以改配置、加插件

💡 补丁层的叠加顺序是：bundle 自带补丁 → 该 profile 的补丁 → $DSH_HOME/cordis.patch.yml（机器级偏好）→ 启动时 --patch 参数。后写的层覆盖先写的层。

02 你其实早就在用插件

别觉得插件是"高级功能"——你上一篇装好的 dsh 本身就是插件拼出来的：

你运行的命令	实际是
`dsh web`	`base`（基础能力）+ （Web 界面）两个官方 bundle`web-app`
`dsh --profile headless "任务"`	`base` + `headless`（一次性任务）两个官方 bundle

官方内置了三个 bundle：、、。和两个 profile 首次使用时会自动从模板初始化。@deepseek-ai/dsh-base@deepseek-ai/dsh-web-app@deepseek-ai/dsh-headlesswebheadless

03 装一个第三方插件（实战）

现在来点真的：给 dsh 装一个社区插件。dsh 提供了专门的插件管理命令：

# 本质是把命令转发给 pnpm，在 profile 目录里操作
dsh plugin --profile tui add 插件包名

比如安装一个 Claude Code 风格的终端界面插件：

dsh plugin --profile tui add @dsh-tui/dsh-tui

然后直接启动这个 profile：

dsh --profile tui

卸载、查看依赖、更新也都很直观：

dsh plugin --profile tui remove @dsh-tui/dsh-tui
dsh plugin --profile tui why @dsh-tui/dsh-tui
dsh plugin --profile tui update

⚠️ 一个常见的坑：从 Git 地址安装的插件（）在安装时会自动构建源码，pnpm 10+ 默认会拦截。第一次会失败并提示一个密钥——把提示的密钥写进该 profile 的 pnpm-workspace.yaml，再重新执行 add 即可。安装官方打包好的 npm 包则没有这个问题。add github:xxx/yyyaddallowBuilds

想先本地试玩，不装进 profile？也可以把插件直接用挂载到现有 Web UI 上（见下节）。--patch

04 插件市场：把 1700+ 社区插件变成一键安装

插件生态火不火？看数量就知道——GitHub 上带话题的仓库已经 1700+ 个，还在每天增长。插件一多，新问题来了：怎么找到好用的？dsh-plugin

有人直接做了个插件市场：zat-dsh-engine——类似 Steam 创意工坊风格的可视化市场，装进 dsh 后，浏览、搜索、一键安装社区插件全在界面里完成，不用再记命令行。

安装（一行命令）

# 推荐（GitHub 直装）
dsh plugin --profile web add github:mishibeikejie/zat-dsh-engine

# 国内直连 GitHub 慢的话，用官方镜像源
dsh plugin --profile web add https://gh-proxy.com/https://github.com/mishibeikejie/zat-dsh-engine.git

⚠️ 两个重要提醒：
务必用 dsh plugin add 安装，不要手改 patch 文件——市场插件自带挂载配置，手动往里再写一遍会造成重复挂载，dsh 直接启动失败（作者在 README 里专门警告过）。cordis.patch.yml
从 Git 安装首次可能被 pnpm 的拦下：把提示的密钥写进该 profile 的再重跑即可。addallowBuildspnpm-workspace.yaml

装完重启 dsh，打开 设置 → 插件，就能看到新的「插件市场」标签页。

它有多好用

🛒 全量目录：实时同步 GitHub 上全部仓库（1700+），中文简介自动翻译dsh-plugin
🤖 AI 找插件：直接在对话里说需求——“找个能让模型看图识图的插件”——AI 自动搜索、推荐，还附安装前体检 + 安全扫描（✅/⚠️/❌，有问题如实说，绝不盲目推荐）
⚡ 一键装/卸/更：带实时进度条，失败自动回滚；已装的插件显示版本对比和更新角标
🩺 一键体检修复：网络/pnpm/入口/OS 问题一键检测，能修的自动修
🌐 网络自适应：自动走你的代理;GitHub 不通时自动切镜像
🎨 12 大分类：主题、工具、浏览器、技能、视觉、网络、Agent、数据......

实际效果

本文作者已经装好并验证过（v0.6.1）：重启 dsh → 设置 → 插件 → 插件市场，1700+ 插件卡片排成列表，点一下就安装。

而且装好市场之后，之前聊到的主题皮肤直接在市场里搜就能一键装（Catppuccin、dsh-skin 等都在）——命令行都省了。

进阶提示：想自己写插件？官方文档有完整教程（工具、配置、发布一步步带你写）——从"会用"到"会写"，这篇先到"会用"，下一篇我们继续。docs/user/develop/basic/

05 调试神器：查看装配图

装了一堆插件后，怎么知道最终生效的配置长什么样？两个命令直接打印组合配置树，不用启动服务：

dsh --profile web --dump-default-config   # 只看官方 bundle 拼出来的
dsh --profile web --patch ./xxx.yml --dump-config   # 加上你自己的补丁层

输出会标注每一行配置来自哪个文件、被哪些补丁修改过，排查"插件没生效"特别好用。

06 常见问题速查

问题	解决
`add`报提示`allowBuilds`	把提示的密钥写进该 profile 的，重新`pnpm-workspace.yamladd`
插件加载了但没效果	检查补丁文件里的插件名拼写;本地插件路径必须是绝对路径（Windows 上还要加前缀）`file:///`
提示找不到某个包	bundle 会先从 dsh 安装目录解析，再查 profile 的 node_modules;确认包名正确
想让插件对所有人可用	发布到 npm，manifest 里声明，并给仓库打上话题便于被发现`dsh.bundle.patchdsh-plugin`

写在最后

一句话总结今天的内容：

✅ 插件 = 能力积木，bundle = 打包好的积木组，profile = 你的装配图。装插件一行命令，逛插件市场——1700+ 社区插件一键装。

dsh 的插件生态才刚刚起步，现在动手写插件，就是最早吃到红利的一批人。感兴趣的话，官方文档的目录有完整的插件开发教程，从工具、配置到发布一步步带你写。docs/user/develop/basic/