信号宠物 dingchenhui0618-arch/dsh-signal-pet

dsh-signal-pet

一只住在界面角落的小宠物，它读你真实的会话事件：思考时动得更快，有工具在跑时拉出连线，出错时变红发抖，长任务做完时庆祝一下。

A status pet for DeepSeek Harness. It reacts to the live event stream — thinking, tool calls, errors, long-job completion — and doubles as the busy/error indicator you can actually see at a glance.

它解决什么

「宠物」这个形式的问题从来不是不好玩，而是看完不知道该看什么。所以这只宠物有两个身份，而且是同一个东西：

- 好玩的那面：它会动，会庆祝，点一下会收起来。
- 有用的那面：它同时是一眼可见的忙碌/出错指示器。你不用去翻日志、也不用盯着转圈——出错了它就是红的，在抖；在跑工具它就是紫的，有几条线就有几个工具在跑。

它不做内容识别、不做装饰、不挡你打字。位置会主动避开输入框——一只趴在你正在打字的框上的宠物是障碍物，不是装饰。

状态

宠物的状态不是客户端猜的。宿主半区监听真实的 harness 事件，折叠成一个小快照，客户端只负责画：

| 状态 | 触发 | 表现 |
| idle | 没有活跃会话 | 慢慢上下飘 |
| thinking | agent/status 变 running | 同样的动作，速度快 3 倍多 |
| working | 有工具正在执行 | 紫色环 + 每个运行中的工具拉一条流动的连线 |
| error | tools/result 报错，或 agent/error | 红环 + 抖 5 下 + 显示错误摘要 |
| celebrate | 一个跑了 10 秒以上的回合结束 | 跳 4 下 + 三颗火花 |

优先级是产品决定，不是巧合：错误压过一切。哪怕同时在跑工具，只要刚出过错，宠物就是红的——它的职责就是「出事的时候你一定会注意到」。

装

npm 版 CLI 管理的 profile
dsh plugin --profile <name> add <插件目录>

桌面版：desktop profile 由 Electron app 独占，npm 版 CLI 会被拒绝—— error: profile "desktop" is managed exclusively by the Electron application 用它自带的那个 CLI 才行（在 app 的 resources/runtime/cli/bin/dsh 下）： "<app>/resources/runtime/cli/bin/dsh" plugin --profile desktop add <插件目录>

装完重启一次 app（host 半区必须重启进程才会加载）。

用

- 点一下宠物 —— 收成一个小圆点，只留状态环颜色；再点一下展开。选择记在 localStorage。
- data-pet-state —— 宠物根元素和图层上都带这个属性，值就是当前状态（idle/thinking/working/error/celebrate），所以截图验收、自动化断言、CSS 钩子都有稳定的抓手。
- data-pet-mode —— 图层上是 animated / static / collapsed。

避让 UI

宠物的位置在五个候选角里挑第一个完全不重叠的；都不行就挑重叠最小的，并把 clear: false 落成一个类名（vp-blocked），这样界面能说明它没能让开，而不是假装让开了。

障碍物是按行为识别的，不是按 DSH 的类名：

textarea, input, [contenteditable="true"], [role="textbox"], [data-pet-avoid]

外加当前获得焦点的元素（哪怕它不是上面任何一类）。data-pet-avoid 是留给其他插件和你自己的逃生口——任何你想要宠物避开的东西，加上这个属性就行。

匹配行为而不匹配类名，是因为 DSH 的界面样式下一次重构时，类名会变，而「这是一个输入框」不会变。

无障碍

prefers-reduced-motion: reduce 时，宠物退化成静态角标：所有 keyframe 关闭，身体缩成 22px 圆点，但状态环的颜色和文字标签保留。

这是刻意的取舍——减弱动效不等于减弱信息。指针仍然必须能传达「现在在忙」和「刚才出错了」，只是不再靠运动传达。

和原版的关系

灵感来自 9livewolf/dsh-think-bounce-pet（17 stars）。

原版没有任何 LICENSE 文件，也就是默认「保留所有权利」。所以本插件没有复用它的任何一行代码，也没有 clone 它——只读了它的 README 来弄清它做了什么、缺什么，实现是从零写的。这一点值得写清楚，不是客套。

原版实际做了什么（据它的 README）：两只大肥鱼在界面里弹跳，作者自己写的是「无实意」；有常驻球和思考球（推理开始时飞入、结束时缩小消失）；支持鼠标碰撞、重力、初速度、摩擦、大小等实时参数；有设置页；参数存在 localStorage；挂在 shell.overlay，全屏 pointer-events:none 图层。

所以差异不在「接不接会话状态」——原版确实接了思考状态。差异在接得有多细、以及有没有把它当指示器用：

| | 原版 | 本插件 |
| 会话状态 | 只有推理开始/结束 | agent/status、tools/pre-execute、tools/result、agent/error、agent/turn-stopping 五种事件 |
| 工具调用 | 不反映 | 每个运行中的工具一条流动连线，data 里带次数与最近一次的名称/耗时/是否失败 |
| 错误 | 不反映 | 红环 + 抖动 + 错误摘要，且优先级最高 |
| 完成 | 不反映 | 跑满 10 秒的回合结束时庆祝一次 |
| 避让 UI | 不避让 | 五候选角落 + getBoundingClientRect 避开输入框与焦点元素 |
| 无障碍 | 不响应 | prefers-reduced-motion 退化成静态角标（保留状态颜色与文字） |
| 可验收 | 无稳定抓手 | data-pet-state / data-pet-mode |
| 物理 | 重力、抛出、鼠标碰撞、实时参数面板 | 没有 |
| 设置页 | 有 | 没有（只有一个点击收起） |

最后两行是原版比我强的地方，直说。我没有实现物理引擎，因为那部分不服务于「一眼可见的指示器」这个目标，而重写一个物理系统也不是这次改进要解决的问题。

HTTP 面

GET /dsh-signal-pet 当前快照（phase、计数、最近工具、错误、忙碌时长） GET /dsh-signal-pet/state 同上（别名） POST /dsh-signal-pet/reset 清空状态 POST /dsh-signal-pet/pulse 强制触发一次庆祝（用来验收动画，不用真的等一个长任务）

它绝不干扰工作

这一条是硬约束。tools/pre-execute 是决定一个工具会不会被执行的 waterfall，所以宿主的监听器在任何路径上都会到达 next()——包括它自己内部出错的时候。一个能挡住它所报告的工作的状态指示器，比没有指示器更糟。

其余同理：状态折叠、事件记录、路由注册全部包在 try/catch 里，任何一处失败都只是宠物不灵，不会让回合失败。

容错姿态

- webServer.register 失败只是没有 HTTP 面（宠物不显示），事件监听照常工作。
- 宿主侧 enabled: false 时接口照常应答，只是不再记录事件。
- shell.overlay 注册失败只让这一层降级并打日志，不会让整个客户端启动失败。
- localStorage 被禁用只影响「收起」这个偏好，不影响宠物本身。
- 窗口尺寸为 0 时位置计算返回有限数值，不产生 NaN。
- 每次注册都可撤销（ctx.effect），因为 dsh 能在运行期卸载插件。

配置

apply(ctx, config) 的 config 全部可覆盖：

| key | 默认 | 说明 |
| errorTtlMs | 12000 | 错误在宠物上停留多久，之后回落到「现在正在发生什么」 |
| celebrateMs | 2600 | 一次庆祝持续多久 |
| celebrateAfterMs | 10000 | 回合至少跑这么久才值得庆祝。低于它就只是普通结束，每次都庆祝等于噪声 |
| maxTethers | 6 | 最多画几条连线（同时跑 20 个工具时不该糊满屏幕） |
| enabled | true | 关掉后事件不再记录 |

开发

node --test # 67 个测试
node scripts/build.mjs

状态机是纯的（src/signal.js：无定时器、无 I/O、不改输入），所以「什么时候该庆祝」「错误什么时候该消」这类判断全部由单测钉死，不需要跑起来看。

阶段是每次读取时推导出来的，不是存下来的。 错误会过期、庆祝有窗口，如果把 phase 当状态存，就需要一个定时器去清除它——而依赖定时器的状态机，总会有一次定时器没响然后永久卡在 error。

避让定位和动效降级也是纯函数，通过 __test 暴露。这两块最典型的坏法都是「看起来没问题」：宠物悄悄不再避让输入框，或者对要求减少动效的人继续动。它们不需要 DOM 就能验，所以就被验了。

渲染层也被真的渲染过一遍（test/client.test.mjs：结构化 stub 掉 React 与浏览器全局，然后调用注册进去的组件，像 React 一样执行函数组件再走整棵树）。这不是为了覆盖率好看——data-pet-state 和 reduced-motion 降级这两个承诺只存在于渲染结果里，而「看着没问题」正是一个坏掉的指示器最常见的存活方式。

License

MIT