本文首发于 栏轩·阁欢迎访问阅读原文获取更好的阅读体验。引言为什么插件是 dsh 的灵魂上一篇文章介绍了 DeepSeek Harness 的安装与上手。如果说 dsh 是一台可组装的机器那么插件就是它的每一个零件——界面、模型接入、工具调用乃至官方 UI 本身全都是插件。这篇文章将带你完整走一遍插件开发的实战路径从理解设计理念和架构组成到安装别人的插件、自己动手写两个 demo最后发布到 npm 让全世界都能安装。本文是实战向教程代码会尽量精简重点讲清为什么这么做以及我踩过的坑。一、设计理念一切皆插件dsh 的整个架构建立在一条简单的信念上Everything is a Plugin一切皆插件。这意味着框架本身只提供组装能力由 Cordis 驱动具体功能全部由插件以模块化的方式提供。对开发者来说这个理念带来三个直接好处可插拔想要什么功能装一个插件不想要了卸掉即可可替换同一个能力有多个实现换一个插件就行互不干扰可学习官方功能也是插件实现的——源码就摆在仓库里是最好的教材理解这一点是进入插件开发的第一把钥匙。二、插件的架构组成一个 dsh 插件本质上是一个npm 包通过package.json里的声明激活成插件。它由两大部分组成1. 声明让 dsh 认识这个包在package.json中声明两件事dsh.bundle.patch声明本包是 bundle并指向cordis.patch.yml——安装后该 patch 会自动挂进配置层栈dsh.client声明浏览器半侧的注入依赖与平台web2. 两个半侧插件实际运行的代码半侧位置职责形态宿主半侧服务端lib/index.js注册路由、服务、权限等标准 Cordis 插件{ name, inject, apply(ctx, config) }浏览器半侧前端lib/client.js渲染界面、交互逻辑window.__ModuleLoader__.load({ id, factory })浏览器半侧有几个硬性规则是新手最容易踩的坑不能自己打包 Reactfactory 接收同步requireReact 等运行时依赖必须从 DSH 外壳的平台模块表获取CSS 内联注入以字符串形式插入style标签而不是引外部样式文件插件 ID 唯一id必须与 package.json 声明一致三、插件是什么一个生活化的类比如果还是觉得抽象可以把插件想象成App Store 里的应用dsh 是操作系统提供运行环境和接口插件是应用各自提供一项能力dsh plugin命令就是应用商店/包管理器装一个插件 往商店里加一个应用写一个插件 开发一个新应用上架。四、安装别人的插件安装插件非常简单本质上是pnpm add到$DSH_HOME/profiles/web/node_modules# 安装dsh plugin--profilewebadd包名# 卸载dsh plugin--profileweb remove包名# 更新dsh plugin--profileweb update# 查看已安装dsh plugin--profileweb list前置条件需要pnpm环境--profile web指定安装到 Web profile。实战踩坑提醒如果你用本地路径file:安装自己正在开发的插件要特别注意——pnpm 的file:依赖是复制而不是链接。也就是说你改了源码已安装的那份不会自动更新必须remove再add一次或重启服务否则跑的还是旧代码。这个坑在开发期会反复遇到。五、自己写插件整体流程自己写一个插件大致分四步建包初始化 npm 包写好package.json的声明bundle patch client写宿主半侧用 Cordis 三件套注册插件主体写浏览器半侧如果要界面或前端逻辑按__ModuleLoader__形态注册客户端本地验证dsh plugin --profile web add .装上重启看效果从 hello world 开始我的第一个插件是dsh-hello——一个工具类插件它注册了一个打招呼工具你在聊天里和 AI 说你好AI 识别到这个意图后就会自动调用插件提供的问候工具。这个 demo 虽然简单但它的意义不小验证整条链路是通的声明能被 dsh 识别、安装后能挂进配置层栈、宿主半侧能正常激活、工具能被 AI 自动调用跑通AI 调用工具的核心机制模型判断意图 → 触发工具 → 拿到结果 → 继续对话这整个闭环在 hello 里就完整走了一遍工具描述怎么写直接影响 AI 会不会正确调用hello 阶段就开始体会给模型写说明书这件事不要小看这一步。插件开发的绝大多数挫败感都来自链路没通——装上了但没生效、激活了但看不到、改了代码但跑的还是旧的。先用 hello world 把链路跑通后面所有功能都是在这条已验证的链路上叠加。而且dsh-hello就是下面 Demo 01AI 可调用工具的最初原型——工具类插件从 hello 一路演化成了更复杂的能力。下面用两个 demo 展示最常见的两种插件能力。六、Demo 01AI 可以调用的工具目标让模型在对话时能自动调用插件提供的工具类似其他 Agent 软件的 Skill。这正是dsh-hello走过的路——只是把打招呼换成真正的能力。思路插件向运行时注册一个工具——定义一个名字、一段描述让模型知道何时用、和一个执行函数。模型在对话中判断这个任务需要调用工具时会自动触发它并拿到结果继续推理。关键点工具的描述要写清楚模型靠它决定是否调用执行函数要返回结构化结果模型靠它继续推理工具可以是任何能力读文件、查网页、执行命令、访问你的私有 API……这个 demo 的价值在于它把让 AI 干活从对话扩展到了真实世界——模型不再是只聊天而是能真正动手。七、Demo 02自定义 Web UI目标往 dsh 界面里注入自己的 UI 组件比如一个桌面宠物、一个侧边栏、一个浮窗。思路dsh 的界面是槽位 注入的架构。官方定义了一些插槽如shell.overlay浮动层插件可以把自己的组件注入到这些槽位里与官方 UI 共存而不互相覆盖。关键点找到合适的槽位如浮动层、侧边栏、状态栏组件在浏览器半侧渲染用 DSH 提供的 React注意竞态与生命周期界面组件经常异步加载要做好防重入、防过期回调我实战做的桌面宠物就是挂在浮动层上的自定义 UI动画链式播放、屏幕漫游、点击/拖拽交互、窗口缩放跟随——整个就是一个通过槽位注入的独立应用。八、发布插件让全世界都能安装开发完成后发布到 npm 即可让任何人dsh plugin --profile web add 包名安装。1. 登录 npm官方源npmlogin--registryhttps://registry.npmjs.org/注意用官方源而不是镜像源。如果账号开了两步验证2FA登录/发布时可能需要 OTP 验证码或使用 npm tokens 页面 创建的访问令牌。2. 发布前自查健康检查脚本在package.json里配置prepack发布前自动校验必需文件、bundle 形态、包体积收窄files只发布运行时需要的文件代码 播放资源文档/预览图等不需要进包版本号语义化版本发新版记得npm version patch/minor/major3. 发布npmpublish--registryhttps://registry.npmjs.org/发布成功后任何人都可以一条命令安装你的插件了。九、总结从一切皆插件的理念到写出第一个能跑的插件、再到发布到 npm这条路径比想象中顺滑理念插件 npm 包 声明宿主半侧管能力、浏览器半侧管界面安装dsh plugin一条命令开发hello world 跑通链路 → 工具 demo 让 AI 动手 → UI demo 让界面长出自己的样子发布npm login publish全球可装插件开发最迷人的地方在于官方功能也是插件。遇到任何不懂的实现直接读官方插件源码就是最好的学习路径。如果你也在写 dsh 插件欢迎分享你的作品——记得在 GitHub 仓库打上dsh-plugin话题让更多人发现它。