🐳 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 dsh-whale-copilot@1.1.0
若仍报 No matching version（pnpm 元数据缓存未刷新），加 --prefer-online，或先
remove 再 add：
dsh plugin --profile web add dsh-whale-copilot@1.1.0 --prefer-online
# 或
dsh plugin --profile web remove dsh-whale-copilot
dsh plugin --profile web add dsh-whale-copilot@1.1.0
验证实际装到的版本：
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 配对，等待用户回答期间保持提问状态；回合结束也会兜底解除）。
与审批同理，提问时鲸鱼回到最左侧停住 → 持续喷水（琥珀色）+ 左右抖动 → 头顶橙色角标显示待提问数量，
气泡显示问题文本（来自工具参数的第一条问题）；用户回答后恢复游动。
会话状态面板中该会话显示「提问中」。
全浏览器醒目提醒（审批 / 提问 / 任务完成）
设置面板 →「提醒」勾选三种方式，任一打开时，审批/提问/任务完成事件到达即触发：
（默认全开；「系统通知」需浏览器授权，首次点击鲸鱼时会以用户手势自动请求权限，拒绝后静默降级）
- 页缘闪屏：整个页面四边红色（审批）/ 琥珀色（提问）/**绿色（任务完成）**脉冲闪烁 + 顶部居中 toast（无需权限，最可靠）；
- 系统通知：
Notification API 发出系统级弹窗（带鲸鱼 logo，标签去重）；
- 标签闪烁：临时把浏览器标签标题改为
⚠️ 需要审批！ / ❓ 有提问待回答！ / 🎉 任务完成！，几秒后自动还原。
会话标题
面板会话列表的标题来自 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
