前言¶
在 DeepSeek Harness（DSH）里长时间跑智能体时，界面侧栏通常是固定的品牌标识，会话 token 与上下文占用则分散在 composer 自带的指示器里。若你希望在 Web GUI 上有一个可交互、能反映当前会话状态的视觉元素，又不改 profile 或手写挂载配置，社区插件 dsh-agent-whale-girl 提供了一种纯客户端方案：替换侧栏品牌 mark，并在页面内叠加可拖拽的浮动角色，台词与 token 卡片均来自 DSH 自身的会话投影，不额外请求网络或模型。
下面按定位、能力、安装与注意事项说明该插件；事实以 GitHub 仓库 README 为准。
这是什么¶
dsh-agent-whale-girl 是面向 DSH Web GUI 的非官方「鲸鱼娘」伴侣插件，由维护者 Turanbuturan 发布，在 SkillHub 目录中归类为客户端。插件通过 dsh.bundle patch 一次性挂载侧栏与 overlay 两半，无需手动编辑 profile。
一句话能力：侧栏用角色面部图替换默认 fish logo；页面上方浮动 220×298 的纸娃娃，可拖拽、可折叠，头部跟随指针，点击与长按有反馈，气泡与 token 卡片展示当前会话的真实 token 与上下文占用。
角色美术为社区同人创作，非 DeepSeek 官方资产；代码为 MIT 许可。
核心功能¶
侧栏品牌 mark¶
插件注册 sidebar.brand.mark，用 avatar-face.png 的特写替换默认 fish logo，并设置 priority: -1 以占据该单值槽位。
浮动伴侣（shell.overlay）¶
在 frame 上叠加纸娃娃，上方为 token 卡片，旁边为对话气泡。可在 frame 内任意拖拽，位置保存在 localStorage['whale-girl:position']；双击回到右下角并清除保存位置；窗口变窄时会自动收进可视区域。
视线与肢体¶
头部朝指针方向转动（约 ±7°），尾巴反向摆动（约 ±4.8°）；指针离开后约 0.22 s 回中。旋转枢轴按原画眼睛/睫毛测量，而非包围盒。
身体、头、尾为三层 puppet，静止时与插画像素一致，移动前视觉上无分层感。
交互：拍、点、连点¶
- 长按（≥ 350 ms）：一次性 squash 动画与专属台词；不会折叠角色。
- 短按（< 350 ms）：折叠或展开，并有一句回应。
- 快速连点：3–4 次有计数式抱怨；第 5 次触发一次性彩蛋动画。
动画仅在交互期间运行：三个一次性 @keyframes（wg-pat / wg-egg / wg-emote），无 infinite、无 alternate、无 will-change；空闲时 getAnimations() 为空。
情绪与台词¶
data-mood 随上下文占用变化：低于 50% 为 calm，≥50% 为 tense，≥85% 为 crit；每次跨档在角色角落显示 💦 约 2.6 s。
台词由状态触发，数字来自 DSH 会话投影（tokenUsage、contextPressure）：挂载问候、点击回应、输出进行中进度、80% 上下文警告、输出停止约 2.5 s 后的完成句。插件不调用网络或模型。
Token 卡片¶
展示上下文占用（进度条与 tokens / window）以及当前会话的 output / input / cache-read 计数，与 composer 指示器同源投影。无会话时隐藏；窗口宽度小于 900 px 时让位隐藏。
安装与启用¶
包声明了 dsh.bundle patch，安装即挂载，无需改 profile、无需手动拷贝文件。
桌面 DSH 应用使用 desktop profile；纯 Web profile 将 --profile desktop 改为 --profile web：
dsh plugin --profile desktop add github:Turanbuturan/dsh-agent-whale-girl
本地目录或 release tarball 同样可用：
dsh plugin --profile desktop add ./dsh-agent-whale-girl
安装后刷新页面即可。若改动了 host 侧代码需重启整个应用（Node ESM 缓存会固定模块路径）；该插件 host 半部 apply() 为空，一般刷新足够。
手动 drop-in（可选）¶
将插件目录拷到 <profile>/plugins/，在 profile 的 cordis.patch.yml 增加：
- insert:
- id: whale-girl
name: "./plugins/dsh-agent-whale-girl/index.js"
路径相对 profile 目录解析。删除 insert 行并刷新即可卸载；目录可保留。
卸载¶
dsh plugin --profile desktop remove dsh-agent-whale-girl
手动 drop-in 方式则删除上述 insert 行并刷新。
典型用法与构建（维护者）¶
日常使用：安装 → 刷新 → 在 Web GUI 内拖拽角色、单击折叠/展开、长按「拍」、观察 token 卡片与气泡随会话变化。
仓库已提交 lib/client.js 与 lib/client.css，安装无需构建。若修改原画或 skeleton，可在插件根目录执行：
node build.mjs
node verify-bundle.cjs lib/client.js
verify-bundle.cjs 对注册项、注入 CSS、层几何、视线数学、点击/拍/连点时机、 mood 值等做自检；请使用绝对路径或明确工作目录。
适用场景与注意¶
适合谁：在 DSH Web / desktop GUI 上开发或调试智能体、希望侧栏与 overlay 有统一角色标识，并直观看到当前会话 token 与上下文压力的用户。
权限与安全：插件以当前 DSH 进程权限在浏览器侧运行，读取的是 GUI 已有的会话投影。安装前建议浏览 源码 与 LICENSE；角色图遵循各上游仓库条款，详见 README 的 Source & attribution 与 NOTICE。
生态说明：DSH 采用「一切皆插件」的扩展方式；SkillHub 等社区目录为独立站点，与 DeepSeek、幻方无官方从属关系。本插件为社区非官方项目，「DeepSeek」与官方鲸鱼 logo 归各自权利人所有。
结尾¶
dsh-agent-whale-girl 把侧栏 mark 与可交互浮动伴侣收进一个可 dsh plugin add 的 bundle：不增网络面，台词与 token 与 composer 同源。若需要上述体验，可按 README 命令安装并刷新页面验证。
