🎁 福利专区全网大模型免费应用 + 新用户福利 + 注册活动入口,低成本玩转 AI
市场 / 管理·1 次阅读·鲸鱼娘桌宠 插件页

一个桌宠插件如何读到宿主的工作状态

桌宠类插件常被当成装饰,但「知道 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 自动整理,数据来源于插件详情页。

60 秒视频版 · AI 辅助生成并人工校对
这篇内容有帮助吗
赞赏随意,不解锁任何内容,也不必留个人信息。
扫码用
查看 鲸鱼娘桌宠 插件详情
安装命令 · 中文 README · 兼容性报告
前往插件页 →
回到顶部