以DSH小鲸鱼挂件为例学会开发DSH插件3个文件与23条路由的完整架构【免费下载链接】DeepSeek-Balance-Whale-WidgetDeepSeek HarnessDSH一只住在 DSH 界面右下角的小鲸鱼娘帮你盯着DeepSeek账户余额。QQ弹弹支持拖拽吸附、左吸附翻转、数字滚动动画随界面自动启用建议直接喊来你的dsh安装项目地址: https://gitcode.com/gh_mirrors/de/DeepSeek-Balance-Whale-Widget本文以 DeepSeek-Balance-Whale-Widget 项目DSH 小鲸鱼记账挂件插件dsh-whale-widget为例带你拆解一个 DeepSeek HarnessDSHWeb 插件的完整架构它只靠 3 个核心 JS 文件 1 个挂载声明就实现了余额监控、小鲸鱼记账、音效泡泡等全部功能宿主侧共注册 23 条/dsh-whale/*路由。读完这篇 DSH 插件开发指南你就能掌握「bundle 插件包 webServer 路由 页面注入脚本」这套标准架构。1. 先认识这个插件3 个文件撑起全部功能DSH 小鲸鱼挂件住在 DSH Web 界面右下角气泡里显示 DeepSeek API 余额、今日已用、每轮对话消耗支持拖拽吸附、Q 弹按压、音效与自定义泡泡。它的全部能力来自 3 个核心文件各司其职文件角色一句话说明package.json插件身份证声明包名dsh-whale-widget与dsh.bundle.patchDSH 据此识别它为 bundle 插件lib/index.js宿主侧本体约 3900 行注册全部路由、监听会话事件、记账与余额拉取lib/accounting.mjs记账内核仅 252 行定点金额运算 余额观测/校正账本独立成模块方便测试assets/whale-widget.js前端挂件本体约 1.7 万行原生 JS运行在浏览器页面里画鲸鱼、气泡、菜单这套「宿主Node 进程 前端浏览器」双半区结构是 DSH 插件的通用形态宿主负责取数、存盘、注册 HTTP 路由前端只负责渲染与交互两者通过路由通信。2. 插件是如何被 DSH 加载的2 个声明文件包元数据让 DSH 认出这是个插件package.json 里最关键的是dsh.bundle.patch字段它指向挂载声明文件main指向宿主入口main: lib/index.js, dsh: { bundle: { patch: ./cordis.patch.yml } }挂载声明一行 YAML 把自己插进配置树cordis.patch.yml 内容只有两行有效配置- insert: - id: dsh-whale-widget name: dsh-whale-widgetDSH 启动时会按 bundle 层栈叠加各插件的 patch把这个插件插入 Web profile 的配置树。装进 DSH 只需一条命令dsh plugin --profile web add dsh-whale-widget⚠️ 新手常见坑发布包里name必须写插件包名dsh-whale-widget不要写成name: ./xxx.mjs?vN那种相对路径——那是本机手动复制到 profile 时的热更写法发布给他人会因路径不存在而破坏启动。完整原因见 whale-widget-prompt.md 的「关键技术结论」一节。3. 宿主侧完整架构23 条路由怎么组织打开 lib/index.js你会发现所有路由都不是零散register的而是统一走一个包装入口 registerRoute它给每条路由自动套上「浏览器信任栅栏」拦截跨站请求、写操作仅限本机回环地址再调用ctx.webServer.register。这是插件安全设计的第一原则——统一入口默认拒绝。全部 23 条/dsh-whale/*路由按职责可分为 5 组源码位置见 lib/index.js数据类挂件内容的取数口路由方法职责/dsh-whale/balance.jsonGET余额 今日已用 峰谷状态永远返回 200 JSON/dsh-whale/last-turn.jsonGET最近一轮对话消耗seq递增前端据此判断新轮次/dsh-whale/wait.jsonGET当前挂起的「提问/授权」事件驱动提示音/dsh-whale/usage-records.jsonGET小鲸鱼记账的逐日/逐条明细/dsh-whale/balance-adjustments.jsonGET/POST余额校正充值等非调用扣减配置类用户设置的持久化回路路由方法职责/dsh-whale/size.jsonGET/PUT外观与开关缩放、音量、吸附等/dsh-whale/usage-settings.jsonGET/PUT提醒类设置预警、预算、每轮消耗提示内容/dsh-whale/api-models.jsonGET/POST/DELETE自定义 API 模型注册表密钥走 DSH 凭据不落配置媒体类图片、音效、前端代码路由职责/dsh-whale/image.png鲸鱼本体图读包内 assets/DSniang1.png/dsh-whale/rua.gif随机台词/撒娇动图/dsh-whale/widget.js下发前端挂件源码宿主按 mtime 热读取改前端不用重启/dsh-whale/sound/press.mp3/sound/release.mp3按压/松开音效按?setduck\|fx1切换/dsh-whale/audio.jsonaudio-fragment.wav音效库索引与片段试听/dsh-whale/role-image.png自定义角色图自定义资产类用户上传内容的管理路由职责/dsh-whale/roles.json/role-pin.json/role-delete.json自定义角色列表、置顶、删除/dsh-whale/bubble.json自定义泡泡点击序列 模块库/dsh-whale/bubble-imgs.json/bubble-img-upload.json/bubble-img.png泡泡图库的列表、上传、读取架构要点生命周期与可迁移路径disposer 收集模式每个registerRoute/tapIndex的返回物都 push 进disposers数组统一挂到ctx.effect上清理HMR 热重载不会留下重复路由见 lib/index.js。可迁移路径lib/index.js#L18-L22 用fileURLToPath(import.meta.url)推出包根目录PACKAGE_ROOT资源一律相对包内assets/取用户数据账本、角色、音频写到$DSH_HOME默认~/.dsh因为node_modules可能在更新时被清理。会话事件监听宿主用ctx.on(session/event, ...)捕获每轮assistant/message的真实 usageinput/cache/output/reasoning tokensturn/end时按峰谷定价表结算写入lastTurn——前端每秒轮询last-turn.json看到seq变大就弹出消耗泡泡。4. 记账内核252 行如何避免浮点数陷阱lib/accounting.mjs 是独立模块只导出纯函数preciseMoney/addMoney/sumMoney/observeBalance等。核心设计有两个定点金额金额先放大 1 亿倍SCALE 100000000转成整数运算8 位小数记账、2 位小数显示彻底绕开浮点误差accounting.mjs#L4-L20。观测 ≠ 交易余额下降记为消费debit余额上升充值/赠金单独记为 credit不会冲掉已有消费充值出现「待核对余额调整」提示由用户在界面上显式校正。把记账逻辑从 3900 行的宿主本体里拆出来是新手最容易忽略、却最值钱的架构习惯数据计算与 HTTP 处理分离前者可独立验证后者只做路由与校验。5. 前端挂件一个寄生在页面上的原生 JS 程序assets/whale-widget.js 由宿主通过tapIndex注入script defer src/dsh-whale/widget.js到 DSH 的 index.html幂等注入已存在则跳过。它有几个值得学习的手法幂等守卫首行if (window.__dshWhaleWidget) return防止热重载后重复初始化whale-widget.js#L1-L4。环境自检脚本会注入 DSH 的每个index 页面含插件市场等 SPA 视图所以开头先检测「当前是否主聊天界面」识别 composer 输入区不是就干脆不碰 DOM——避免干扰 React 渲染树。DOM 分层div.dshwv-root定位/翻转→div.dshwv-body按压 Q 弹缩放→ 鲸鱼图 SVG 气泡三层职责清晰动画互不干扰。浮层层级自检项目还配了零依赖脚本 tools/z-layer-audit.mjsnode tools/z-layer-audit.mjs即可校验所有 body 级浮层是否登记进 z-index 候选表防止「两个窗口互相盖住且谁都不报错」的静默失效——小项目也值得有这种自检工具。6. 本地开发工作流热重载怎么用最顺按 whale-widget-prompt.md 总结的踩坑结论DSH 插件联调的最快姿势安装在仓库根目录package.json所在层不要多套子目录执行dsh plugin --profile web add link:.然后重启dsh web。改前端assets/whale-widget.js宿主按文件 mtime 热读取浏览器CtrlF5 硬刷新即生效不用重启。改宿主lib/index.js/lib/accounting.mjs必须重启dsh web。验证路由存活带会话在浏览器里访问/dsh-whale/balance.json应返回 200 JSON含totalBalance裸curl返回 401/403 是信任栅栏在工作的预期行为不是接口坏了详见 README.md 的「验证」一节。卸载dsh plugin --profile web remove dsh-whale-widget。7. 总结从这个小挂件能学到的 DSH 插件架构清单 把这份清单存下来下一个插件直接套用标准 bundle 插件package.json含dsh.bundle.patchcordis.patch.yml挂载声明 ESM 宿主入口实现随界面自动启用。路由统一入口用一个registerRoute包装所有路由安全栅栏、错误兜底一次配齐balance.json这类高频接口永远返回 200 JSON绝不悬挂。disposer 生命周期所有注册物收集进数组、挂ctx.effect清理热重载零残留。数据与逻辑分层记账内核独立成纯函数模块定点数运算观测与校正分离。前端自守幂等守卫 环境自检注入脚本只在它该工作的页面工作。可迁移路径资源相对包根目录取用户数据落$DSH_HOME插件升级/迁移不掉数据。想深入完整规格DOM 结构、视觉几何参数、12 条踩坑结论、全部路由表直接读项目自带的「完整生成提示词」whale-widget-prompt.md——它本身就是面向二次开发的架构文档也是把 README 写成 AI 可复现规格的一个优秀范例。【免费下载链接】DeepSeek-Balance-Whale-WidgetDeepSeek HarnessDSH一只住在 DSH 界面右下角的小鲸鱼娘帮你盯着DeepSeek账户余额。QQ弹弹支持拖拽吸附、左吸附翻转、数字滚动动画随界面自动启用建议直接喊来你的dsh安装项目地址: https://gitcode.com/gh_mirrors/de/DeepSeek-Balance-Whale-Widget创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考