一个桌宠插件如何读到宿主的工作状态
桌宠类插件常被当成装饰,但「知道 agent 正在干什么」这件事并不装饰。dsh-whale-musume(鲸鱼娘)在站内的分类是「市场 / 管理」,它是靠读宿主 DOM 的契约标记来判断忙闲的:工具调用在跑,她抱起笔记本;工具结束,她放下。这套判断没有任何模型参与,全是选择器。
桌宠类插件常被当成装饰,但「知道 agent 正在干什么」这件事并不装饰。dsh-whale-musume(鲸鱼娘)在站内的分类是「市场 / 管理」,它是靠读宿主 DOM 的契约标记来判断忙闲的:工具调用在跑,她抱起笔记本;工具结束,她放下。这套判断没有任何模型参与,全是选择器。
先把已知事实摆齐
| 项目 | 数值 |
|---|---|
| GitHub 星标 | 201(2026-11-05 现查,与站内快照一致) |
| 站内综合分 | 63.4 |
| npm 周下载 | 4,712(npm 全网,含 CI 与镜像,不是本站安装数) |
| 版本 / 许可 | 2.5.0 / MIT |
| 运行时依赖 | 0 个 dependencies、0 个 peerDependencies |
| 站点实装档位 | 已验证 · L5 运行时冒烟(数据截至 2026-10-29) |
零依赖这一点决定了它的安装形态:产物随仓库提交,没有 prepare,安装期不需要构建,因此安装失败几乎只可能是外部条件(到 GitHub 的链路、registry 镜像同步)而不是插件代码。
它读的是 DOM 契约,不是模型状态
宿主的界面标记一变,桌宠就瞎。作者在 v2.2.0 适配桌面端时逐条核对了 0.2.0-rc.2 的真实契约,并把差异写成文档,其中几条对写插件的人有普遍参考价值:
| 契约点 | 旧写法为什么失效 | 现在的判据 |
|---|---|---|
| 工具卡 | [data-role="tool"] 在 0.2.0-rc.2 上零命中 | [data-tool](值即工具名)+ 同元素 data-state |
| 忙态 | 工具卡完成后仍留在 DOM | 只认 running / preparing |
| 会话运行 | 没有可靠信号 | [data-chat-running],仅运行时挂载 |
| 终端 | [data-slot="terminal"] 不存在 | [data-terminal] |
| 输入框 | 变成 contenteditable | [data-composer-input] |
| 主题 | 明暗写在 body[data-ds-dark-theme],空串表示暗 | 补齐空串识别,旧 class 只作回落 |
| 设置面板 | 常驻引导弹窗也是 role="dialog" | 收敛到 [data-shortcut-modal="settings"] |
最后一条值得单独说:判据不收窄,刷新后常驻的引导弹窗会被误判成设置页,桌宠就会按「设置页不显示装饰」的规则把自己藏起来——用户看到的现象是「装完就没了」。
状态机与表现层分开,是为了可测
仓库把核心状态机(assets/whale-moe-core.js)和表现层(assets/dsh-whale-moe.js)拆开,状态机可以直接 node --test 跑,不需要浏览器或服务器。好处有两个:一是桌面端契约再变,改的是选择器映射而不是整套逻辑;二是养成数值(心情、好感、饱食、等级、签到、成就)可以脱离界面做单元断言。
另一条容易被忽略的约束写在 README 里:客户端模块是惰性 CJS,副作用必须放在 factory 物化期,boot() 因此从 apply() 挪进了 factory。这条直接对应下面第一个坑。
数据落在哪儿
养成数据存在宿主 origin 的 localStorage 里,键名以 whale-moe: 开头。桌面端主窗口的 origin 是 dsh-app://app,旧版 Web 是 http://127.0.0.1:<端口>——两个 origin 不同源,数据天然隔离。v2.5.0 才补了跨端迁移(导出 JSON、迁移码 WM1--、导入覆盖同名),并且明确不迁移悬浮位置、天气城市与经纬度,因为这些属于设备相关数据。
三个必须知道的坑
坑一 · 桌面端装完只刷新页面
现象:命令返回成功,页面刷新后右下角什么都没有,控制台也没有报错。
原因:boot() 在 client 模块的 factory 里执行,桌面端不会因为刷新页面就重新物化插件模块。
解决:完全退出桌面端应用再启动。要确认是否起来,看 window.__dshWhaleMusumeBooted === true、document.querySelectorAll('[data-dsh-whale-root]').length === 1。
坑二 · 还按 19387 找她
现象:按旧文档写的 127.0.0.1:19387 打不开任何东西,以为插件没装上。
原因:0.2.0-rc.2 的桌面端 GUI 确实默认 19387,但从 0.2.1 起端口改为系统分配(--port 0)。
解决:不要写死端口。需要定位时从宿主进程实际监听端口取,或直接看 package.json 里 dependencies 与 dsh.profile.bundles 是否各出现一次。
坑三 · 以为换端能带走好感度
现象:同一台机器上从旧版 Web 换到桌面端,等级、好感、成就全归零。
原因:两个 origin 的 localStorage 不互通,也不自动搬迁。
解决:设置 → 看板娘 → 跨端迁移,导出 JSON 或复制迁移码再导入。注意它只搬核心进度,悬浮位置与天气城市需要在新端重设。
边界
她只对 Windows 10 / 11 的桌面端与 DSH 0.1.x 的旧版 Web 做过实测;0.2.1-rc.1 / 0.2.1-rc.2 只有静态契约核对加单元测试,没有在真实 Electron 里复跑。headless 与 acp 这类没有界面的 profile 不显示,这是设计而非故障。默认零外部请求,天气要你填城市才会请求 Open-Meteo,余额显示默认关闭且只访问本机代理。
总结
这类插件的技术含量不在「可爱」,而在把宿主的不稳定界面契约收敛成一张可测的映射表,并且把副作用放在正确的生命周期里;想对照更多同类插件的分类与安装形态,可以看 DeepSeek Harness Hub 插件清单 里的分类聚合。
适合与不适合
适合:想给 DSH 桌面端加一个常驻状态指示的人;愿意按 README 的契约文档排查界面差异的插件作者;需要一套可单测的状态机样例的前端工程师。
不适合:用 macOS 或 Linux 桌面端的人,当前支持范围只有 Windows 10/11;跑 headless / acp profile 的人,没有界面就没有落点;要求「装完零配置就有效果」的人,桌面端必须先重启应用。
标签:鲸鱼娘桌宠、DeepSeek Harness、DOM 契约、插件生命周期
本文由 DeepSeek Harness Hub 自动整理,数据来源于插件详情页。