如何给 DSH 写一个插件（并安装 / 卸载它）

如何给 DSH 写一个插件并安装 / 卸载它本文基于真实环境deepseek-ai/dsh0.2.1-rc.5Windows的实操复盘。DSH 各版本插件 API 名字可能略有差异本文以已验证可加载的写法为准——下文所有结论都来自实际安装、加载、卸载的验证而非照抄社区教程。0. 先说清 DSH 的插件模型DSH 的口号是万物皆是插件。一个插件本质是一个包通过package.json里的dsh清单声明自己然后在它的客户端半边里往 DSH 的 UI 贡献样式、组件、页面、服务。本文带你从零写一个把界面染成红色的插件my-red-theme并走完安装、验证、卸载全流程。1. 动手前先核对你的运行时很多人栽在这网上教程常写放进dsh-runtime/node_modules 改cordis.patch.yml但你的真实环境是这样的全局 CLInpm i -g deepseek-ai/dsh本机版本0.2.1-rc.5。家目录home没设DSH_HOME时用默认~/.dshWindows 即C:\Users\你\.dsh。插件按 profile 隔离~/.dsh/profiles/name/各自有node_modules/和cordis.patch.yml。你实际在用的 profile 叫web路径C:\Users\你\.dsh\profiles\web\node_modules\ ← 插件都装这里 C:\Users\你\.dsh\profiles\web\cordis.patch.yml已装的dsh-better-sidebar就在这个web/node_modules里——它是你最好的真实样本比任何博客都准。关键认知没有全局插件这种事插件是跟着 profile 走的。“把插件装进全局 dsh的真实含义是装到某个 profile 的node_modules并让 loader 挂载”。2. 一个最小可加载插件的真实结构照官方自带的cordis-plugin-development技能模板里面有一个decoration装饰模板来写一个纯 UI 插件只需要 4 个文件my-red-theme/ ├── package.json # ESM dsh 清单 ├── index.js # host 半边空壳 ├── client.js # client 半边真正干活的注入样式 └── cordis.patch.yml # bundle patch让 loader 挂载package.json{name:local/my-red-theme,version:1.0.0,private:true,type:module,exports:{.:./index.js,./client:./client.js},files:[index.js,client.js,cordis.patch.yml],dsh:{bundle:{patch:./cordis.patch.yml},client:{platform:web,immediately:true,inject:[]}}}注意三点和社区版 Cordis 教程不同用dsh字段声明插件不是cordis: true。必须是ESMtype: module。用 CommonJS 会直接加载失败。local/是本地开发插件的约定作用域。index.jshost 半边// 纯 UI 装饰不需要 host 逻辑exportfunctionapply(){}client.jsclient 半边——重点// 运行在浏览器里document 可用window.__ModuleLoader__.load({id:local/my-red-theme,factory(require){constCSS_IDmy-red-theme-css;constRED_CSS:root, body, #app { --dsh-bg: #2b0000 !important; --dsh-fg: #ffd9d9 !important; --dsh-primary: #ff2f2f !important; background: var(--dsh-bg) !important; color: var(--dsh-fg) !important; } button, .btn { background: #ff2f2f !important; color: #fff !important; };functioninject(){if(typeofdocumentundefined)return;if(document.getElementById(CSS_ID))return;// 幂等热重载不重复插consteldocument.createElement(style);el.idCSS_ID;el.textContentRED_CSS;document.head.appendChild(el);}inject();if(typeofdocument!undefined)document.addEventListener(DOMContentLoaded,inject);return{inject:[],apply(){}};},});cordis.patch.yml-insert:-id:my-red-themename:local/my-red-theme# 必须与 package.json 的 name 完全一致3. 最关键的坑host 半边 ≠ client 半边这是 90% 新手写出来了但界面没反应的原因host 半边index.js跑在Node里document/window不存在。client 半边client.js经window.__ModuleLoader__.load注册才跑在浏览器里。所以让界面变红这种 DOM 操作只能写在 client 半边。很多教程让你在入口ctx.inject([style], ...)直接碰 DOM在你的版本里会因为没有document而静默失败。想加侧边栏 Tab也是同理在client.js的apply(ctx)里用ctx.slots.register(...)官方decoration模板就是这么注册 UI 的并把inject改成[slots]。4. 安装与卸载命令清单dsh plugin子命令的本质是把后续参数原样转发给该 profile 目录里的 pnpm。安装本地路径 / npm 包 / tgz 都支持dsh plugin--profile web add D:\path\to\my-red-theme它会把包装进~/.dsh/profiles/web/node_modules并写入dsh.profile.bundles让 loader 挂载。装本地路径时它创建的是link:软链实测看到link:D:/.../my-red-theme意味着你改工作区源码、重启 web 就能见效不用重装。也可以是 npm 包名dsh plugin --profile web add dsh-better-sidebar0.28.2或本地打的包add ./xxx.tgz。卸载dsh plugin--profile web remove local/my-red-theme包名用package.json里的name含local/。实测执行后node_modules/local/my-red-theme目录消失profile 的package.json依赖与 bundle 列表均无残留。验证是否真的加载了肉眼最直观重启 web 界面看变化红主题装上去界面立刻全红。看启动日志里有没有插件相关报错。浏览器开发者工具 → Elements检查head里有没有你的style idmy-red-theme-css。改完插件后必须重启 web 界面——client 半边的增删没有热更新刷新页面才会重新加载。5. 你可能没注意到的 7 件事插件是 per-profile 的没有全局插件。装到web只在web生效。host / client 半边之分DOM 操作只能放 client 半边否则document为undefined。cordis: true是社区版 Cordis 的写法你的deepseek-ai/dsh用的是package.json的dsh字段。照搬社区教程会装不上。必须是 ESM。CommonJS 入口加载即失败。cordis.patch.yml的name必须和包名完全一致否则 loader 按名字匹配不到挂载不上。dsh plugin add走的是 pnpm本地路径会建link:软链——这是最舒服的开发方式改源码即生效重启即可。CSS 全用!important只是最快见效要做可切换主题更优雅的做法是把样式包在[data-themered]选择器里再让插件动态给html加属性。DSH 自身的颜色 token如--dsh-bg最好去开发者工具里抄它的真实变量名再覆盖比盲写!important更不容易破版。6. 小结写 DSH 插件 一个 ESM 包 dsh清单 client.js里用window.__ModuleLoader__.load注入逻辑安装/卸载统一走dsh plugin --profile name add/remove。最大的两个坑是host/client 半边之分与ESM/清单格式——避开这两点你就能在十分钟内让界面全红再往上逐步加服务、加 Tab。附本次实操时间线复盘在d:/zhonglin/dsh/packages/my-red-theme按社区教程初版写了插件cordisjs/corecordis: true CommonJS ctx.inject。实地核对真实运行时发现全局是deepseek-ai/dsh0.2.1-rc.5家目录~/.dsh插件在profiles/web/node_modules。读官方cordis-plugin-development的decoration模板和已装的dsh-better-sidebar确认真实格式ESM dsh清单 window.__ModuleLoader__.load的 client 半边。按真实格式重写插件4 个文件node --check语法校验通过。dsh plugin --profile web add 本地路径安装 → 界面实测全红验证加载成功。dsh plugin --profile web remove local/my-red-theme卸载 → 验证node_modules、依赖、bundle 列表均清理干净。