鲸鱼表情包 harmless0819-dev/dsh-whale-emote

dsh-whale-emote

让小鲸鱼挂件表演情绪：agent 通过一个本地 HTTP 调用，就能让表情包从挂件旁边弹出来。

为什么需要单独一层

dsh-whale-widget 本身没有任何接受外部文字/指令的接口。它的全部路由里，只有 /dsh-whale/last-turn.json 会被前端每秒轮询（内容由宿主按真实用量生成，只读）；size.json 只在页面初始化时读一次；图片和音效都是初始化或手势时加载。所以想让挂件「表达情绪」，只能另加一层。

这一层不修改第三方挂件的任何文件：它自己注册路由，并用挂件同款的 tapIndex 机制注入一小段脚本，操作挂件根节点 .dshwv-root 的坐标把表情弹在它旁边。

路由

| 方法 | 路径 | 作用 |
| GET | /dsh-emote/manifest.json | 可用情绪清单（key / 字幕 / 描述 / readable）+ 音效预设（sounds） |
| GET | /dsh-emote/state.json | 当前情绪，客户端每秒轮询（seq 递增表示新事件） |
| GET | /dsh-emote/sticker?key= | 表情图片本体 |
| GET | /dsh-emote/sound?key= | 音效本体（按扩展名给 audio/ 类型，支持 Range） |
| GET/POST | /dsh-emote/set?emotion=&text= | 触发情绪（POST 用 JSON body） |
| GET/POST | /dsh-emote/clear | 立刻收起 |
| GET | /dsh-emote/client.js | 注入用的客户端脚本 |
| GET | /dsh-emote/health.json | 探针：客户端是否在轮询、有没有真的显示出来 |
| POST | /dsh-emote/ack | 客户端显示成功后的回执（agent 靠它确认"真的弹了"） |
| POST | /dsh-emote/activity-ack | 状态条几何回执：客户端上报 left/top/w/h/display/inView/whaleRect |
| GET | /dsh-emote/activity.json | 当前活动状态（写文件=奋笔疾书 等），含诊断信息 + client 回传 |
| GET/POST | /dsh-emote/activity | 手动覆盖活动状态（POST JSON {label,emoji,detail,ttlMs}；?clear=1 立刻清空） |
| GET | /dsh-emote/state.json | 当前情绪 + activity 字段（客户端从这里读状态条，不用额外请求） |

emotion 支持模糊匹配：给 嚣张、最强 或者 key 的一部分都能命中；命中不了会返回 404 并附上全部可用 key。

诊断：用户说「没弹」时先查探针，别先猜代码

agent 看不到浏览器，所以「发了但没显示」和「根本没发」在它眼里长得一样。加了探针之后，一条查询就能定性：

curl.exe http://127.0.0.1:3080/dsh-emote/health.json

| 读出来 | 结论 |
| poll.connected: false | 客户端不在（页面关了 / 浏览器重启了）—— 最常见 |
| connected: true 但 ack.seq 落后 seq | 客户端在跑，是显示环节的问题，才值得查代码 |
| ack.seq 追上了 seq | 确实弹了，属于用户没看到（时机 / 位置），不是没发 |

- poll.count 每个 state.json 请求 +1，客户端每秒一次 → 4 秒涨约 4 才是正常。
- poll.ua 能看出是哪个浏览器在轮询。
- ack.lastAgoMs 是「上一次真正显示」距今多久。

踩过的坑：先怀疑过「SPA 把节点冲成游离节点」，还加了自愈补丁 —— 结果真凶只是页面关着 / 服务器没重启。教训：先看探针，再动代码。

用法

图形化一点 .\emote.ps1 -List # 列出全部情绪 .\emote.ps1 嚣张 # 弹图 .\emote.ps1 委屈 -Text "才、才不是呢" # 弹图 + 自定义气泡 .\emote.ps1 撒娇 -TtlMs 0 # 不自动收起 .\emote.ps1 -Decision 困惑 -Text "选哪个？" # 决策提醒：必弹 + 小鲸鱼唱歌音效 .\emote.ps1 -Clear # 收起

或者直接打接口 curl.exe "http://127.0.0.1:3080/dsh-emote/set?emotion=%E5%9A%A3%E5%BC%A0&text=hello"

参数：ttlMs（自动收起毫秒，0 = 不自动收）、text（挂在图下方的气泡文字）、sizePx（覆写尺寸）、sound（是否放音效，默认关）、soundKey（用哪段音效，默认 press）。

状态条：反映「当前在干嘛」（2026-09-21 新增）

用户要求：右下角挂件要有一条反映当前对话状态的表达 —— 例如「写入 → 奋笔疾书」。
现在这条状态条是全自动的：宿主监听会话事件（session/event），把正在跑的工具翻成动作，常驻在鲸鱼头顶（与挂件同层，z-index:9999）。agent 不用每次手写。

- 常驻：闲置时显示 🐟 摸鱼中，干活时显示具体动作，不会自动消失。
- 可拖动：按住拖到任意位置，松手吸附到最近的视口边缘；位置记在 localStorage。
- 单击还原：没拖动就松手 = 回到「自动跟随鲸鱼头顶」。
- 跟着鲸鱼走：拖鲸鱼 / 挂件吸附 / 改挂件大小时，药丸一起动。
手动摆过之后仍然保持相对关系一起位移（挂件缩放则退回头顶重新锚定）。

| 触发 | 显示 | detail |
| write / edit | ✍️ 奋笔疾书 | 文件名 |
| read / read_image | 📖 翻书中 | 文件名 |
| grep / glob | 🔍 翻箱倒柜 | pattern |
| pwsh / bash / job_ | ⌨️ 敲命令 | 命令首词 |
| web_search / web_fetch | 🌐 上网查 | query |
| browser_ | 🖱️ 逛网页 | — |
| subagent / workflow / ralph | 🐣 摇人帮忙 | — |
| ask_user_question | 🙋 等你拍板 | — |
| todo_write / goal 系 | 📋 列计划 | — |
| hindsight_ | 🧠 翻记忆 | — |
| present / skill | 📦 交东西 | — |
| 未知工具 | 🔧 干活中 | 工具名（兜底，绝不静默变空） |
| turn 开着但没在跑工具 | 💭 思考中 | — |
| turn/end | ✅ 收工（定格 3s 后淡出） | — |

几个关键设计（都有 harness 锁着）：

- 粘滞期（默认 4s）：工具常常只跑几十毫秒，不粘一会儿的话状态条永远只会闪「思考中」。
所以 tool/result 在粘滞期内不覆盖当前动作。
- 多会话判收工：subagent / 另一个标签页也会开 turn，只有最后一个 turn/end 才喊收工。
- 丢事件的兜底：turn 一直挂着但 90s 没有任何会话事件（崩溃/强杀）→ 自动按 idle 处理。
- 与表情是两条独立通道：情绪是 agent 主动表演的一次性事件（有 ttl、会收起），活动是宿主推出来的持续状态。状态条复用同一次 state.json 轮询（不额外发请求），服务端没给 activity 字段时客户端不炸（新旧混装安全）。
- Live2D 联动：dsh-whale-live2d 读同一个 activity，把活动映射到模型表情（writing→画笔、thinking→放空脸……共 14 张）。活动脸是底噪层：情绪脸盖在上面，情绪到点回到活动脸，活动没了才回默认脸；闲置随机小动作不抢活动脸。

配置项（profile patch 的 config 段）：

| 键 | 默认 | 作用 |
| autoActivity | true | 是否启用自动状态条 |
| activityHoldMs | 4000 | 动作粘滞期（防闪） |
| activityDoneMs | 3000 | 「收工」定格时长 |
| activityIdleMs | 90000 | 丢 turn/end 的兜底超时 |

探针与手动通道：

curl.exe http://127.0.0.1:3080/dsh-emote/activity.json # 现在挂的是什么 + 诊断 .\emote.ps1 -ActivityStatus # 同上（CLI 版） .\emote.ps1 -Activity "正在读图纸" -ActivityEmoji "📐" # 强制覆盖（演示/排查用） .\emote.ps1 -ActivityClear # 立刻收起

视觉旋钮在 lib/client.js（改完只要 F5）：ACTIVITY_FADE_MS（淡出延迟）、ACTIVITY_GAP（与鲸鱼间距）、ACT_SNAP_MARGIN（吸附留边）。

拖动与吸附

胶囊可以直接拖：按住拖到想放的地方，松手自动吸附到最近的视口边缘（左右二选一，竖直自由但不出屏）。位置记在 localStorage，F5 后还在。
单击（没拖动）= 还原成自动跟随鲸鱼，不用去翻设置。

⚠️ 实现上的一个坑：挂件自己在 document 捕获阶段 监听 pointerdown 并用
isWhaleHit()（PNG alpha 采样）判断「有没有戳到鲸鱼」。捕获阶段先于 target，
所以我们在胶囊上的 stopPropagation 拦不住它 —— 拖胶囊会把鲸鱼一起拖走。
解法是拖动开始时给 document 补发一个 pointercancel：挂件监听了 pointercancel 并会因此放弃它那次拖拽。改这块代码前请先看 onActDown() 的注释。

决策提醒音效（-Decision）

用户要求：每次我弹表情提醒他做决策（问问题、等确认、等选方案），就放「小鲸鱼唱歌」。
所以有 -Decision 这个组合开关，它等于 -Force（绕过概率必弹）+ -Sound sing：

.\emote.ps1 -Decision 困惑 -Text "这两个方案选哪个？"

音效走每次事件单独指定这条路：set 时带上 soundKey，服务端把它翻成 soundUrl 塞进 state.json，客户端 show() 时优先用 s.soundUrl，没有才回落到挂件自带的 duck。
所以普通情绪照旧是「咔哒」一声，只有决策提醒才唱歌，互不干扰。

自动联动（2026-09-17 起）

决策提醒的唱歌音效已改成自动触发：agent 每次调 ask_user_question（要向用户拍板），插件在 tools/pre-execute 钩子里自动弹一个 decisionEmotion 情绪 + sing 音效，不用再靠 agent 每次手动记着补 .\emote.ps1 -Decision。问一次拍板 → 唱一次歌。

配置项（profile patch 的 config 段，默认值如下）：

| 键 | 默认 | 作用 |
| autoDecision | true | 是否启用自动联动 |
| decisionEmotion | 困惑 | 拍板时自动弹哪个情绪 |
| decisionText | '' | 气泡文案；留空则自动取问题标题（header），再退到问题正文（截 40 字） |
| decisionTtlMs | 25000 | 自动弹出的停留时间（毫秒） |

/dsh-emote/health.json 的 autoDecision 字段实时报告 enabled / emotion / count / lastAt，可以用来验证联动有没有真的触发。改这些配置 / 或改 lib/index.js 里的联动逻辑 → 要重启 dsh web。

-Decision 组合开关仍然可用（手动强制 + 唱歌），只是从「唯一通道」降级成「手动通道」。

预设表在 lib/index.js 的 DEFAULT_SOUNDS（也可用 profile 配置的 sounds 覆盖）：

| key | 是什么 | 怎么来的 |
| press（默认） | 挂件自带 duck press | 直接指向 /dsh-whale/sound/press.mp3?set=duck |
| release | 挂件自带 duck release | 同上，换 release |
| sing | 小鲸鱼唱歌 | file: 小鲸鱼唱歌.wav，走插件自己的 /dsh-emote/sound 路由 |

带 file 的预设从 mediaDir（默认就是表情目录 D:\deepseek\表情）取文件。为什么不用挂件那条 /dsh-whale/sound/…：它只认四个写死的候选文件，而且不管什么文件都回 audio/mpeg；自定义 wav 从那里出去类型就是错的（能响只是浏览器嗅探的运气）。所以自己开一条路由，按扩展名给 audio/wav，并老实实现 206 / Range —— 浏览器拿媒体时会带 Range: bytes=0-。

加一段新音效：把文件丢进 D:\deepseek\表情，在 DEFAULT_SOUNDS 里加一条 { key: 'xxx', label: '…', file: 'xxx.wav' }，改的是 lib/index.js → 要重启 dsh web。
（只想换掉 sing 对应的文件则不用动代码：清单按 mtime 重读，路由每次从磁盘读文件。）

情绪清单（以 .\emote.ps1 -List 为准）

适合得意/炫耀：嚣张(最强)　挑衅(闭源模型在哪)　暴富　傲娇　嘴硬

适合卖萌/亲近：撒娇　卖萌　开心　糊弄　自嘲　无辜

适合认错/崩坏：委屈(我不是大肥鱼)　耍赖　崩溃　慌乱　大哭　阵亡　害怕

适合吐槽/阴阳：腹黑(四个橙子五个小孩)　嘲讽(真坐得住啊你)　不耐烦　装懂　生气

其他：发疯　讲课　教学　困惑　整活　涨价　庆祝　小心翼翼

完整字幕见 emote-manifest.json 或 .\emote.ps1 -List。

改表情 / 加表情

- 图片目录：D:\deepseek\表情（插件里是 DEFAULT_IMAGES_DIR）
- 清单：emote-manifest.json，改动后无需重启（插件按 mtime 自动重读）

加新图：把 png 丢进图片目录，然后在 emote-manifest.json 里加一条：

{ "file": "新文件名.png", "key": "得意", "caption": "字幕原文", "desc": "画面描述", "readable": true }

readable: false 表示字幕小、缩小后看不清 —— 这类会自动放大 1.4 倍显示。

安装

从 GitHub（推荐）
dsh plugin --profile web add github:harmless0819-dev/dsh-whale-emote

或从本地克隆
dsh plugin --profile web add link:

装完重启 dsh web，然后浏览器 F5。

卸载

dsh plugin --profile web remove dsh-whale-emote

然后重启 dsh web。第三方挂件不受影响。

可调旋钮（都在 lib/client.js，改完只要 F5，不用重启）

| 常量 | 当前值 | 作用 |
| SIZE_SCALE | 0.5 | 最终像素 = 服务端 sizePx × 这个值（默认 340 × 0.5 = 170px） |
| EDGE | 'random' | 'random' 左右随机 / 'left' / 'right' / 'whale' 跟随鲸鱼所在侧 |
| V_MIN V_MAX | 0.35 0.65 | 竖直位置的随机区间（占视口高度比例），即「中间 30%」 |
| SOUND_ALWAYS | true | 每次弹出都放音效 |
| SOUND_URL | press.mp3?set=duck | 兜底音效：服务端没给 soundUrl 时才用它 |
| SOUND_VOLUME | 0.6 | 音量；唱歌那段 20 秒，嫌吵就调小 |
| POLL_MS | 1000 | 轮询间隔，决定「触发 → 出现」的延迟上限 |

两个容易踩的实现细节

- 随机位置必须在 show() 里掷骰子，不能写在 place() 里。place() 一次弹出会被调用 3 次（立即 / 图片 onload / requestAnimationFrame），写在那里表情弹出时会左右横跳。现在用 curSide / curAnchor 缓存一次结果，连窗口 resize 都不会跳。
- 浏览器自动播放策略：页面还没有过用户手势时 audio.play() 会被拒（NotAllowedError，且是静默失败）。现在被拒时记 soundPending，并在首次 pointerdown / keydown 时补放一声（仅当表情还挂着，避免空响）。

架构要点（维护必读）

为什么客户端脚本是单独一个文件

lib/client.js 是独立文件，/dsh-emote/client.js 路由每次请求都从磁盘读。原因：改插件模块（lib/index.js）必须重启 dsh web 才生效 —— 实测 HMR 不会重载它（改完代码后服务器仍在吐旧字节）。把客户端逻辑拆出去之后：

| 你要改的东西 | 改哪个文件 | 怎么生效 |
| 视觉：位置、动效、尺寸、CSS | lib/client.js | 浏览器 F5 即可，不用重启 |
| 宿主：路由、状态机、清单逻辑 | lib/index.js | 必须重启 dsh web |

重启 dsh web（restart-web.ps1）

改完 lib/index.js 之后，用配套脚本重启 —— 请在用户自己的终端里跑：

& 'D:\deepseek\dsh-whale-emote\restart-web.ps1' # 停掉 + 拉起 + 自检 & 'D:\deepseek\dsh-whale-emote\restart-web.ps1' -DryRun # 只看会杀谁、会怎么拉

它会：找到监听 3080 的进程 → 停掉 → 等在 -WorkDir（默认 D:\deepseek）用 dsh web 拉起 → 轮询首页 → 查 /dsh-emote/health.json 和 /dsh-emote/sound?key=sing（206 表示 Range 那条路通） → 提醒你回浏览器 F5。日志写在 D:\deepseek\dsh-web.log。

为什么必须由用户在终端跑，不能让 agent 代跑：agent 的 shell 跑在文件沙箱里，写不了 %DSH_HOME%\...，dsh web 连 profile 都启不开 ——实测直接死在 EPERM: open '%DSH_HOME%\profiles\web\cordis.yml'。
就算硬拉起来，也可能是个残的服务。（顺带一提：重启会掐断正在进行的那一轮会话，所以别在 agent 干到一半时重启。）

鲸鱼的真实几何（定位的坑）

挂件根节点是个正方形大方块，而鲸鱼本体只占它右下角的 59.45%：

.dshwv-root { position:fixed; width:var(--dshw-base); height:var(--dshw-base); }
.dshwv-img { position:absolute; right:0; bottom:0; width:59.45%; height:59.45%; }

所以定位必须量 .dshwv-img。量 .dshwv-root 会得到一个含大片空白的矩形，表情会被推到离鲸鱼很远的地方（V1 的「位置很怪」就是这个 bug）。挂件左吸附时会加 transform:scaleX(-1)，但 getBoundingClientRect() 已经把变换算进去了，直接量 img 就是对的。

⚠️ Windows PowerShell 5.1 的两个坑

这套环境跑的是 Windows PowerShell 5.1（Desktop），不是 PowerShell 7。写脚本会连踩两次：

1. .ps1 里有中文 → 必须存成 UTF-8 with BOM。5.1 读无 BOM 的 .ps1 会按 ANSI(GBK) 解码，中文变乱码；乱码字节里可能含引号，直接把脚本解析搞崩（报 Unexpected token / Missing closing ')'）。
用 write 类工具改完 emote.ps1 后 BOM 会丢，要补回来： $p='D:\deepseek\dsh-whale-emote\emote.ps1'
$c=[System.IO.File]::ReadAllText($p,[System.Text.UTF8Encoding]::new($false))
[System.IO.File]::WriteAllText($p,$c,[System.Text.UTF8Encoding]::new($true))

2. Invoke-RestMethod -Body 按 Latin-1 编码，而且 5.1 的 ConvertTo-Json 不会把中文转义成 \uXXXX —— 两者相叠，中文 JSON 到服务端就是乱码（表现为 unknown emotion 的 404）。必须自己转字节：
$bytes = [System.Text.Encoding]::UTF8.GetBytes(($payload | ConvertTo-Json -Compress))
Invoke-RestMethod -Method Post -Uri $uri -ContentType 'application/json; charset=utf-8' -Body $bytes

emote.ps1 里的 Send-Json 已经这么做了。

3. ConvertTo-Json 会把 .NET 数组序列化成 { "value": [...], "Count": n } —— 不是 JSON 数组！而且 @($json | ConvertFrom-Json) 的行为也不符合直觉，可能把整个数组包成单元素。
- 我踩的坑：用 PowerShell 合并清单（32 + 17）时，输出变成了 [{value:[32],Count:32},{value:[17],Count:17}]，插件解析不出任何 key，emote.ps1 求饶 直接 404。
- 结论：碰 JSON 就用 node。JSON.parse / JSON.stringify 没有这些歧义。修复脚本见 repair-manifest.mjs（它会递归钻进 {value} 里把条目捞出来，校验 49 条 + key 唯一后才写回）。

（命令行参数里的中文是没问题的，会烂的是「文件编码」「请求体编码」和「用 PowerShell 拼 JSON」这三处。）

已知限制

- 客户端每秒轮询一次，所以从触发到出现最多约 1 秒延迟。
- 表情包是整幅梗图（1254×1254，字烧在图里），不能替换挂件本体的抠图 DSniang1.png，所以是「弹在旁边」而不是「换脸」。
- 挂件拖动/吸附时表情不会跟着走（只在弹出瞬间按当时位置定位）；窗口 resize 会重新定位。
- 首次安装、或改 lib/index.js 时需要重启 dsh web；改 lib/client.js 不需要。