whale-on-desk

dsh plugin --profile web add whale-on-desk

whale-on-desk 🐳 鲸桌

中文 | [English](docs/README.en.md) | 🏠 官网

给 DeepSeek Harness 的像素鲸鱼桌宠。

Agent 干活时它游泳,调工具时吐泡泡,请求批准时贴着屏幕敲玻璃。

它会做什么

鲸鱼住在 DeepSeek Harness 网页界面的一角,实时反映 Agent 的状态:

Agent 在干嘛 · 鲸鱼在干嘛

任务运行中 · 快速游泳 🏊

模型输出中 · 陪它思考,头顶思考泡泡 💭

调用工具 · 吐一个带友好标签的泡泡(敲命令 / 读文件 / …)

请求批准 · 贴住屏幕边缘敲玻璃 + 琥珀色脉冲,浏览器标签标题闪 🔔

任务完成 · 空翻庆祝 + 开口汇报:"搞定! 3 分 12 秒,跑了 8 个工具,改了 5 个文件" 🎉

任务失败 · 下沉,眼睛变横线 😢

上下文约 62% / 82% · 喂鱼时间——"还能吃一点 / 吃饱了" 🍤

闲置 5 分钟 · 主动讨活:"我闲着呢,有活吗?"

闲置 10 分钟 · 睡着 💤

本地 00:00–06:00 · 戴睡帽 🌙

悬停鲸鱼 · 显示当前任务统计牌(耗时 / 工具数)

点击鲸鱼 · 惊吓反应 + 随机台词("别戳啦")

单击 / 双击它 · 吱吱叫 / 惊醒炸毛(带音效)

可以拖到任何位置,位置自动记住。音效为实时合成,零音频文件。

安装

dsh plugin --profile web add whale-on-desk

打开(或重启)DSH 网页界面即可。无需 API Key,无需配置。

DSH Desktop(社区 Electron 桌面版)同样支持——它跑的就是官方 Web 客户端,插件体系和 DSH home 与网页版一致。在应用托盘打开 Open DSH Terminal,执行 dsh plugin add whale-on-desk,重启 DSH Desktop 即可。

卸载 / 配置

dsh plugin --profile web remove whale-on-desk

睡眠超时可在 cordis.patch.yml 配置(sleepAfterMinutes,默认 10)。右键点鲸鱼有小菜单(静音 / 回到默认位置 / 换桌宠 / 隐藏——隐藏后双击右下角 🐳 恢复)。配置 allowPreview: true 会额外开启 POST /whale/preview {"state":"glass-tap"}(传 {"state":null} 恢复)——方便录演示和截图,默认关闭。

成长系统与 Agent 语音

鲸鱼会陪你长大——完成任务获得经验,开启会话获得经验,陪伴时长持续累积。8 个称号等你解锁。升级和解锁称号时鲸鱼开口庆祝。悬停可见等级、称号和经验进度。零负反馈:永不扣分,永不惩罚。

whale_say 工具——你的 Agent 可以让鲸鱼说话和表演。鲸鱼成了 Agent 的通知通道。

水族馆模式

右键鲸鱼 → 🐠 水族馆,进入全屏水族箱:手绘水体背景(自动适配明暗主题)、海草摇曳、随工具调用生长的进度珊瑚、计数本回合工具数的小鱼群——大鲸鱼本体就是 Agent:等批准时冲向缸边敲玻璃(警示浮标闪烁)。水层保持半透明且点击穿透,可以边写代码边养鱼。按 Esc(或 ✕ 按钮)回到桌面伙伴模式。

AI 宠物工坊

插件向 harness 注册了 pet-forge 技能:直接对 Agent 说"给我做一只粉色章鱼桌宠"——它会设计精灵图、跑和内置鲸鱼同款的像素审计、切出 GIF、装成宠物包并当场热切换,全程无需重启。(需要 PATH 里有 ffmpeg。)

自定义桌宠

把一套精灵放进 ~/.dsh/whale-on-desk/pets/<名字>/——一个把状态映射到 GIF 文件的 manifest.json,加上 GIF 本体:

{ "idle": "idle.gif", "glass-tap": "tap.gif" }

没提供的状态回退到你的 idle,没带的文件回退到内置小鲸鱼。右键桌宠即可切换,立即生效,无需刷新。相关配置:pet(启动时激活的桌宠名)、petsDir、enabled: false(彻底卸载桌宠)。

工作原理

• 宿主端(lib/index.js):Cordis 插件,监听 session/event(回合、流式块、工具调用、审批——全部是持久会话事件),折叠进一个小状态机(lib/pet-machine.mjs);在 DSH web 服务器上暴露 /whale/state、/whale/poke、/whale/assets/*。只读:不碰你的会话和文件。
• 浏览器端(lib/client.js):经 DSH shell 模块加载器注册,挂载到 shell.overlay 槽位,渲染当前状态的精灵图(500ms 轮询),播放合成音效,记忆位置。
• 美术流水线(tools/process-sprites.mjs):AI 精灵图进,干净循环 GIF 出——切片、精确 8 色吸附(纯最近色计算)、洋红抠像、装饰剔除。

自己做新状态

见 [docs/GPT_PROMPT_PLAYBOOK.md](docs/GPT_PROMPT_PLAYBOOK.md)——用 AI 出图工具生成新鲸鱼动画的完整工作流,以及把一张图变成上线状态的一条命令。

目录结构

art/     AI 工作流的源精灵图(仅仓库)
assets/  发布运行时:状态 GIF + manifest.json
docs/    美术规格、提示词手册、权威角色参考图
lib/     插件宿主端 + 浏览器端 + 状态机
test/    状态机单元测试
tools/   精灵图处理流水线 + 测试网格生成器

致谢与声明

动画语法与像素规范致敬 clawd-on-desk(仅风格参考——未共享任何素材或代码;clawd 美术归 Anthropic 所有)。鲸鱼美术由 AI 辅助生成。与 DeepSeek 无官方关联。MIT 许可。