🐳 DSWhale Copilot — dsh-whale-copilot

一条由 DSH 事件驱动的 DeepSeek 蓝白小鲸鱼宠物，运行在 DSH Web 界面底部。 它会随 agent 会话状态游泳、起伏、跳跃、间歇喷水：思考（reasoning-delta）时间歇喷水、 回复时摇尾、执行工具时冒泡，游动模式下还会时不时探出水面，露出的背部连喷几次水再潜回去、 需要审批时暂停移动并喷水抖动（头顶亮灯 + 红色角标，且回到最左侧，不遮挡审批按钮）、 agent 向你提问（ask_user_question 工具）时同样暂停移动并抖动提醒（琥珀色喷水 + 橙色角标）， 任务完成时跃出水面。 点击鲸鱼本体可展开/收起会话状态面板（面板出现位置跟随鲸鱼当前位置，自动考虑左右与上下安全区； 实时会话列表 + 最近动态 + 大小/上下位置/气泡距鲸鱼顶部距离/透明度/主题（深/浅色）/ 游动 / 静态（拖拽摆放）模式/海洋背景开关/提醒方式设置； 海洋背景高度随鲸鱼大小与气泡位置自适应；面板头部带 ⟳ 检测更新按钮，可随时手动检查新版本）。 审批、提问、任务完成发生时，可开启全浏览器醒目提醒：页缘闪屏 + 系统级原生通知 + 浏览器标签栏闪烁。

这是什么

一个正式安装的 DSH 插件包（npm 包，双面插件）：

• Host 半区（lib/index.js）：监听 session/event（含提问事件：ask_user_question 工具调用即视为提问，等待用户回答）、agent/*、approval/request、 subagent/*、workflow/*、goal/changed 等事件，聚合会话状态与有界事件日志， 并监听 session/title 事件实时刷新会话标题（标题是异步生成的）， 通过 webServer 注册 /whale/pull、/whale/hello HTTP 路由供浏览器轮询。
• Client 半区（lib/client.js）：浏览器 bundle（window.__ModuleLoader__.load 格式，与官方 dsh-client-* 包一致），通过 dsh.client: { platform: 'web' } 声明， 由 @deepseek-ai/dsh-client-modules 自动注入 window.__DSH_BOOT__ 并服务 /plugins/<包名>/client.js。

安装

装完即激活——一条命令（需 pnpm）：

dsh plugin --profile web add dsh-whale-copilot
dsh web

dsh plugin add 把包装进 ~/.dsh/profiles/web/，并因包声明了 dsh.bundle.patch 而自动写入 dsh.profile.bundles；dsh web 启动时自动挂载 host 半区并注入浏览器半区， 无需手动改任何文件。

无 pnpm 的手动安装（本机开发）

# 1) 把包放入 web profile 的 node_modules（hoisted 存储）
Copy-Item -Recurse dsh-whale-copilot "$env:USERPROFILE\.dsh\profiles\web\node_modules\"

# 2) 在 ~/.dsh/profiles/web/package.json 里声明依赖 + bundle 层：
#    "dependencies": { "dsh-whale-copilot": "^1.1.0" },
#    "dsh": { "profile": { "bundles": [..., "dsh-whale-copilot"] } }

# 3) 重启
dsh web

Windows 本机开发也可运行 install-local.ps1（等价的手动安装，直接 insert 行方式）。

疑难排查

add 装到了旧版本（如 1.0.1 而非 1.1.0）

npm 上 latest 已是新版本，但 dsh plugin add 仍装旧版——通常是 profile 目录里 已有的 pnpm-lock.yaml / dependencies 锁定了旧版本所致（此前装过旧版）。

解决：显式指定版本重装。

dsh plugin --profile web add dsh-whale-copilot@<版本>
# 例如：dsh plugin --profile web add [email protected]

若仍报 No matching version（pnpm 元数据缓存未刷新），加 --prefer-online，或先 remove 再 add：

dsh plugin --profile web add [email protected] --prefer-online
# 或
dsh plugin --profile web remove dsh-whale-copilot
dsh plugin --profile web add [email protected]

验证实际装到的版本：

node -p "require(process.env.HOME + '/.dsh/profiles/web/node_modules/dsh-whale-copilot/package.json').version"

并确认 ~/.dsh/profiles/web/package.json 的 dsh.profile.bundles 已包含 dsh-whale-copilot（装完即激活的关键）。

随时开关

编辑 ~/.dsh/profiles/web/cordis.patch.yml，重启 dsh：

- id: whale
  disabled: true        # 关闭
# disabled: false       # 重新开启（或删除该条目）

彻底卸载：dsh plugin --profile web remove dsh-whale-copilot（或手动删除 dsh-whale-copilot 依赖、dsh.profile.bundles 里的条目与 node_modules 目录）。

面板设置

点击鲸鱼打开面板 → 右上角 ⚙ 进入设置：

设置	范围	默认	说明
主题	深色 / 浅色	深色	状态面板配色（浅色模式下文字/边框自动切换为深色系）
模式	游动 / 静态	游动	游动：底部左右循环巡游；静态：停在原地，鼠标拖拽摆放到页面任意位置（位置自动记忆）
大小	50% – 130%	85%	鲸鱼整体缩放（气泡与海洋高度随之自适应）
上下位置	上浮 20px – 下沉 22px	下沉 8px	距底部距离（仅游动模式显示；静态模式下位置由拖拽决定）
气泡距离	顶部+0 – 160px	顶部+18px	气泡距鲸鱼顶部（背部最高点）的相对间距——调整鲸鱼大小时气泡始终贴着头顶走，不会脱节
透明度	0% – 100%	100%	鲸鱼本体透明度（气泡与审批角标不受影响，角标始终醒目）
海洋背景	显示 / 隐藏	显示	是否渲染底部海洋背景（水面波浪 + 气泡）；隐藏后鲸鱼悬浮在页面上
提醒	闪屏 / 系统通知 / 标签闪烁	全开	审批、提问、任务完成时的全浏览器醒目提醒开关

海洋背景高度是动态的：按「鲸鱼可视高度 + 气泡相对间距 + 气泡盒体与水面波浪带的安全余量」 实时计算，放大鲸鱼或调高气泡后海洋会跟着变高，保证气泡始终完整呈现在水面之内。

点击区域：只响应鲸鱼本体轮廓（SVG 实际绘制的部分），周围的透明区域不会触发点击； 点击鲸鱼本体即可在「展开面板 / 收起面板」之间切换。静态模式下轻微拖动（<5px）仍视为点击， 拖过阈值才判定为摆放。

面板位置跟随鲸鱼：面板在展开瞬间位于鲸鱼当前位置附近并水平居中，靠近屏幕左右边缘时自动夹紧， 不会超出视口；窗口尺寸变化时也会重新夹紧。静态模式下按鲸鱼所在高度自动选择展开方向： 鲸鱼在上半屏（或上方空间不足）时面板改到鲸鱼下方，否则放在鲸鱼上方； 展开时为视口上下各留安全边距、并按剩余空间动态限制面板最大高度—— 贴近顶部/底部时面板依然完整可见（放不下会自动换边，仍放不下则压缩高度靠内部滚动），不会遮挡鲸鱼。

静态模式拖拽边界：按鲸鱼「可视轮廓」计算——左右各留约一半于旧版的安全距离（小尺寸也能贴边摆放）， 下方留 20px 安全区，保证起伏/庆祝动画时鲸鱼始终完整显示。

设置保存在浏览器 localStorage（键 dsh-whale-copilot:settings，兼容旧键 dsh-whale:settings）， 带 schema 版本标记（v: 2）：旧版本的「气泡距离」（距容器底部的固定像素）与新语义不可换算， 升级后该项一次性重置为新默认值，其余设置全部保留。刷新页面 / 下次启动自动按上次的值初始化； 点「恢复默认」可回到默认值。

游动 / 静态模式

• 游动模式（默认）：鲸鱼沿底部左右循环巡游，并保留全部动态行为（起伏、跳跃、间歇喷水、探出水面等）。
• 静态模式：鲸鱼不再自动移动，用鼠标按住鲸鱼本体即可拖到页面任意位置松手放置； 位置持久化保存，刷新后原地出现。审批/提问的抖动与喷水提醒照常播放（只是不再回到最左侧—— 你摆哪儿它就在哪儿提醒）。切回游动模式时，鲸鱼从当前停留处继续巡游。

探出水面喷水（游动模式专属彩蛋）

游动时每隔 24–50 秒随机触发一次：鲸鱼缓缓上浮、把背部露出水面（眼睛和喷水口在水线之上， 尾巴仍在水下），连喷 3 次水后再潜回去，整个过程约 8.6 秒。调度上做了全局避让： 正在思考/回复的常规动作、审批/提问冻结期间都不会触发；喷水过程中收到审批/提问会立即取消上浮， 优先保证提醒动画正确，不会出现姿态叠加异常。静态模式下不触发（都离开水面了还探什么）。

版本与在线升级

面板头部提供 ⟳ 检测更新按钮（检查期间旋转、防重复点击），点击即向 Host 手动发起一次版本检查， 结果通过鲸鱼气泡即时反馈（「已是最新～」/「发现新版本 vX.Y.Z！可在设置里升级」）， 同时刷新设置页顶部的版本状态徽标。

设置面板顶部第一行显示当前版本号与更新状态：

• 除手动检测外，Host 半区也会自动向 npm 官方仓库（registry.npmjs.org）检查最新版本 （启动时 + 每 6 小时各一次；离线/未发布时静默降级，不影响任何功能；手动与自动检查共享并发去重）；
• 发现新版本时显示 发现新版本 vX.Y.Z + 「立即升级」按钮，点击后 Host 在插件的安装目录（web profile，自动定位）内执行 pnpm add dsh-whale-copilot@<最新版>（pnpm 不可用时退化为 npm）原地升级；
• 升级完成后提示「重启 dsh web 后生效」——重启后新版本自动生效，无需手动改任何文件；
• 自动升级失败时给出原因；此时可手动执行：

dsh plugin --profile web add dsh-whale-copilot@latest

说明：升级只是替换已安装的 npm 包内容，不会卸载本插件，因此升级过程中当前运行的宿主不会中断；版本检查与升级接口都只挂在本地回环 Web 面（/whale/*），不参与审批等敏感流程。

审批提示

Host 半区通过 approval/request 瀑布事件观察权限审批：先记录状态、把事件投递给浏览器， 再 await next() 继续真实审批链（观察式，不劫持审批）。

当收到审批请求时，鲸鱼会：回到最左侧停住（避免遮挡页面中部/右侧的审批操作按钮）→ 持续喷水 + 左右抖动 → 头顶红色角标显示待审批数量， 气泡显示「需要审批！」；批准后跃起庆祝，拒绝后垂眼懊恼。审批期间，会话状态面板中该会话显示「待审批」。

游动与朝向由同一状态驱动（JS 统一控制位移 + 头部朝向，不再使用两条独立 CSS 动画）。 审批时位移与朝向一并完全冻结，审批结束后从左侧重新开始巡航， 不会再出现「身体掉头了、头部方向没跟上」的失步问题。

提问提示

Host 半区通过 session/event 监听 ask_user_question 工具调用即视为提问事件 （按 callId 与 tool/result 配对，等待用户回答期间保持提问状态；回合结束也会兜底解除）。 与审批同理，提问时鲸鱼回到最左侧停住 → 持续喷水（琥珀色）+ 左右抖动 → 头顶橙色角标显示待提问数量， 气泡显示问题文本（来自工具参数的第一条问题）；用户回答后恢复游动。 会话状态面板中该会话显示「提问中」。

全浏览器醒目提醒（审批 / 提问 / 任务完成）

设置面板 →「提醒」勾选三种方式，任一打开时，审批/提问/任务完成事件到达即触发： （默认全开；「系统通知」需浏览器授权，首次点击鲸鱼时会以用户手势自动请求权限，拒绝后静默降级）

1. 页缘闪屏：整个页面四边红色（审批）/ 琥珀色（提问）/**绿色（任务完成）**脉冲闪烁 + 顶部居中 toast（无需权限，最可靠）；
2. 系统通知：Notification API 发出系统级弹窗（带鲸鱼 logo，标签去重）；
3. 标签闪烁：临时把浏览器标签标题改为 ⚠️ 需要审批！ / ❓ 有提问待回答！ / 🎉 任务完成！，几秒后自动还原。

会话标题

面板会话列表的标题来自 DSH 的 sessionTitle 服务（session/title 事件）。标题是异步生成的 （首个用户消息后先出 fallback 标题，随后可能由 LLM provider 优化），因此刚建立的会话往往先显示 session-xxxx…。本插件 Host 半区监听 session/title 事件，标题一旦生成就自动刷新， 不再像旧版那样只在会话创建时读一次、之后永远显示 session id。

插件 Logo

面板头部与系统通知图标使用随包携带的鲸鱼剪影（assets/whale.svg，源自 dsh-dock）， 以 base64 内嵌于客户端 bundle，无需额外请求。

发布到插件市场 / npm

当前 DSH rc.6 没有独立的市场 UI——官方分发通道是 npm 包，通过 dsh plugin --profile web add <包名> 安装（需 pnpm）。包已按官方 dsh.client / dsh.bundle 约定打包，未来若有市场，可直接被市场目录消费。

包名采用裸名 dsh-whale-copilot（无作用域）。发布前请先确认该裸名在 npm 上未被占用： npm view dsh-whale-copilot。裸名包默认公开可见，无需 --access public。

cd dsh-whale-copilot
npm login                 # 用你的 npmjs 账号（spartaattack）登录
npm publish   # 裸名包默认公开，无需 --access public

发布后任何装有 pnpm 的机器都能：

dsh plugin --profile web add dsh-whale-copilot
dsh web   # 装完即激活，无需手动改任何文件

技术要点

• 客户端 bundle 是手写的官方 __ModuleLoader__.load CJS 格式（无需完整仓库构建）； React 通过 require("react") 获取（浏览器 shell 的 seed 模块）。
• Host 半区不依赖 harness 动态运行器——事件监听、webServer 路由都是标准 Cordis 能力， 因此重启后依然存在，任何会话共享同一实例。
• /whale/* 是只读状态接口，仅回环/本机 Web 面可见，不参与审批等敏感流程。

许可证

MIT