dsh-waterball-pet
一个适用于 DeepSeek Harness Web UI 的漂浮水球宠物插件。水球使用纯 SVG 绘制， 内部颜色会随 Agent 的会话状态变化（外层白色渐变保持不变），球体带柔和投影与 底部接触阴影，便于在浅色页面上看清边界。眼睛可在设置中切换白色/黑色或隐藏。 支持在 Web UI 中开关、调整大小和拖动位置。
> This is a floating water-ball pet plugin for the DeepSeek Harness Web UI. It is > drawn with SVG and reacts to Agent session events: the ball's inner color > changes with the state while the white outer edge of the gradient stays > constant. A soft drop shadow and a static ground contact shadow keep the ball > visible against light page backgrounds. Eyes can be switched to white or black, > or hidden, from the plugin settings. The Web UI settings card controls > visibility, size, and position.
状态外观
以下为不同状态下的水球样式：
| 状态 | 黑色眼睛 | 白色眼睛 | 隐藏眼睛 |
|---|---|---|---|
空闲 · idle | <img src="./docs/assets/waterball-idle-blue-black-eyes.png" width="96" alt="空闲，蓝色水球，黑色眼睛"> | <img src="./docs/assets/waterball-idle-blue-white-eyes.png" width="96" alt="空闲，蓝色水球，白色眼睛"> | <img src="./docs/assets/waterball-idle-blue-no-eyes.png" width="96" alt="空闲，蓝色水球，无眼睛"> |
思考 / 工作 · waiting | <img src="./docs/assets/waterball-waiting-green-black-eyes.png" width="96" alt="思考，绿色水球，黑色眼睛"> | <img src="./docs/assets/waterball-waiting-green-white-eyes.png" width="96" alt="思考，绿色水球，白色眼睛"> | <img src="./docs/assets/waterball-waiting-green-no-eyes.png" width="96" alt="思考，绿色水球，无眼睛"> |
工具调用 · jumping | <img src="./docs/assets/waterball-jumping-purple-black-eyes.png" width="96" alt="工具调用，紫色水球，黑色眼睛"> | <img src="./docs/assets/waterball-jumping-purple-white-eyes.png" width="96" alt="工具调用，紫色水球，白色眼睛"> | <img src="./docs/assets/waterball-jumping-purple-no-eyes.png" width="96" alt="工具调用，紫色水球，无眼睛"> |
授权等待 · authorizing | <img src="./docs/assets/waterball-authorizing-yellow-black-eyes.png" width="96" alt="授权等待，黄色水球，黑色眼睛"> | <img src="./docs/assets/waterball-authorizing-yellow-white-eyes.png" width="96" alt="授权等待，黄色水球，白色眼睛"> | <img src="./docs/assets/waterball-authorizing-yellow-no-eyes.png" width="96" alt="授权等待，黄色水球，无眼睛"> |
做出你的抉择 · questioning | <img src="./docs/assets/waterball-questioning-pink-black-eyes.png" width="96" alt="做出你的抉择，粉色水球，黑色眼睛"> | <img src="./docs/assets/waterball-questioning-pink-white-eyes.png" width="96" alt="做出你的抉择，粉色水球，白色眼睛"> | <img src="./docs/assets/waterball-questioning-pink-no-eyes.png" width="96" alt="做出你的抉择，粉色水球，无眼睛"> |
完成 · done | <img src="./docs/assets/waterball-done-cyan-black-eyes.png" width="96" alt="完成，青色水球，黑色眼睛"> | <img src="./docs/assets/waterball-done-cyan-white-eyes.png" width="96" alt="完成，青色水球，白色眼睛"> | <img src="./docs/assets/waterball-done-cyan-no-eyes.png" width="96" alt="完成，青色水球，无眼睛"> |
出错 · failed | <img src="./docs/assets/waterball-failed-red-black-eyes.png" width="96" alt="出错，红色水球，黑色眼睛"> | <img src="./docs/assets/waterball-failed-red-white-eyes.png" width="96" alt="出错，红色水球，白色眼睛"> | <img src="./docs/assets/waterball-failed-red-no-eyes.png" width="96" alt="出错，红色水球，无眼睛"> |
停止 / 中断 · stopped | <img src="./docs/assets/waterball-stopped-charcoal-black-eyes.png" width="96" alt="停止，深灰色水球，黑色眼睛"> | <img src="./docs/assets/waterball-stopped-charcoal-white-eyes.png" width="96" alt="停止，深灰色水球，白色眼睛"> | <img src="./docs/assets/waterball-stopped-charcoal-no-eyes.png" width="96" alt="停止，深灰色水球，无眼睛"> |
点击挥手 · waving | <img src="./docs/assets/waterball-waving-orange-black-eyes.png" width="96" alt="点击挥手，橙色水球，黑色眼睛"> | <img src="./docs/assets/waterball-waving-orange-white-eyes.png" width="96" alt="点击挥手，橙色水球，白色眼睛"> | <img src="./docs/assets/waterball-waving-orange-no-eyes.png" width="96" alt="点击挥手，橙色水球，无眼睛"> |
状态、内部颜色与操作
水球内部颜色随状态变化，外层白色渐变始终不变。眼睛颜色与显隐可在设置中调整。
| 状态 | mood | 内部颜色 | 触发事件 / 操作 | 动画与持续时间 |
|---|---|---|---|---|
| 空闲 | idle | 蓝色 #4fb3f7 | 没有活动；activity/status 的 idle | 上下浮动 |
| 思考 / 工作 | waiting | 绿色 #34d399 | turn/start、step/start、assistant/chunk；或 activity/status 的 waiting / thinking | 左右张望，持续到下一状态 |
| 工具调用 | jumping | 紫色 #a855f7 | tool/call；或 activity/status 的 tool | 跳跃，持续到工具结果 |
| 授权等待 | authorizing | 黄色 #facc15 | approval/asked | 柔和呼吸，直到 approval/decided（批准→继续，拒绝/取消→出错） |
| 做出你的抉择 | questioning | 粉色 #ec4899 | tool/call 的 ask_user_question | 左右摆动，直到 tool/result（回答→继续思考；取消/关闭→停止） |
| 工具结果后继续思考 | waiting | 绿色 #34d399 | tool/result | 回到思考动画 |
| 完成 | done | 青色 #22d3ee | activity/status 的 done；或 turn/end 的 reason=completed | 欢快跳动约 2.5 秒 |
| 出错 | failed | 红色 #f87171 | turn/end 的 reason=error | 低头沮丧约 3 秒 |
| 中断 / 停止 | stopped | 深灰 #111827 | turn/end 的 reason=aborted、blocked、max-tokens 或其他停止原因 | 静止下沉约 3 秒 |
| 点击挥手 | waving | 橙色 #fb923c | 单击水球 | 左右摇摆约 1.6 秒 |
标准 DSH 会话事件始终作为状态来源；如果额外安装了活动状态插件，也兼容 activity/status 事件。
安装
从 GitHub 安装（推荐）
需要已安装 Node.js、pnpm 和 DeepSeek Harness：
dsh plugin --profile web add github:sundusk/dsh-waterball-pet仓库已包含构建后的 host/browser 两个插件部分，安装时不需要执行第三方构建脚本， 可以直接使用。安装完成后重启 dsh web，然后打开 Web UI，在「设置 → 插件」的 插件配置列表中启用「水球宠物」（卡片与内置的 Shell / Agent loop / Web search 卡片平级，位于「Web UI 插件」分组之外）。
> 兼容性注意：白名单问题 > > 插件能够从 GitHub 安装成功，不代表当前 DeepSeek Harness 宿主版本已经允许 > waterball 设置命名空间。Harness 的 @deepseek-ai/dsh-host-apiproxy 会维护一份 > Web UI 设置白名单；如果你的版本还没有包含 waterball，可能出现以下情况： > > - 插件已经安装，但设置卡片显示不可用或只读； > - 启用、大小、位置等设置无法保存； > - 某些宿主版本中水球覆盖层也可能不会显示。 > > 遇到这些情况，请先升级 DeepSeek Harness 到包含 waterball 白名单的版本，重启 > dsh web 后再检查。修改本机 npx 缓存中的宿主文件只能作为临时开发排查手段， > 不会替其他用户解决这个问题，也可能在重新安装后被覆盖。这个兼容性问题属于 > Harness 宿主，不是 npm/GitHub 分发方式本身造成的。
本地开发安装
dsh plugin --profile web add link:<本仓库绝对路径>重启 dsh web 后生效。插件代码修改后运行 pnpm build，并将更新后的 lib/ 一并提交。
结构
src/index.ts— host 半区：监听标准 session 事件与可选的activity/status相位，
提供 GET /api/waterball/status，注册 waterball 设置命名空间。
src/client/index.ts— browser 半区：渲染水球、轮询状态、注册插件配置卡片。cordis.patch.yml— bundle patch 插件行，插件 ID 为ui-waterball。shared/— 独立仓库使用的客户端构建预设。lib/— 已提交的 host/browser 构建产物，保证 GitHub 安装无需执行构建脚本。
English
State appearance
Water ball styles for each state:
| State | Black eyes | White eyes | Hidden eyes |
|---|---|---|---|
Idle · idle | <img src="./docs/assets/waterball-idle-blue-black-eyes.png" width="96" alt="Idle blue water ball, black eyes"> | <img src="./docs/assets/waterball-idle-blue-white-eyes.png" width="96" alt="Idle blue water ball, white eyes"> | <img src="./docs/assets/waterball-idle-blue-no-eyes.png" width="96" alt="Idle blue water ball, no eyes"> |
Thinking / working · waiting | <img src="./docs/assets/waterball-waiting-green-black-eyes.png" width="96" alt="Thinking green water ball, black eyes"> | <img src="./docs/assets/waterball-waiting-green-white-eyes.png" width="96" alt="Thinking green water ball, white eyes"> | <img src="./docs/assets/waterball-waiting-green-no-eyes.png" width="96" alt="Thinking green water ball, no eyes"> |
Tool call · jumping | <img src="./docs/assets/waterball-jumping-purple-black-eyes.png" width="96" alt="Tool call purple water ball, black eyes"> | <img src="./docs/assets/waterball-jumping-purple-white-eyes.png" width="96" alt="Tool call purple water ball, white eyes"> | <img src="./docs/assets/waterball-jumping-purple-no-eyes.png" width="96" alt="Tool call purple water ball, no eyes"> |
Awaiting approval · authorizing | <img src="./docs/assets/waterball-authorizing-yellow-black-eyes.png" width="96" alt="Awaiting approval yellow water ball, black eyes"> | <img src="./docs/assets/waterball-authorizing-yellow-white-eyes.png" width="96" alt="Awaiting approval yellow water ball, white eyes"> | <img src="./docs/assets/waterball-authorizing-yellow-no-eyes.png" width="96" alt="Awaiting approval yellow water ball, no eyes"> |
Awaiting your choice · questioning | <img src="./docs/assets/waterball-questioning-pink-black-eyes.png" width="96" alt="Question pink water ball, black eyes"> | <img src="./docs/assets/waterball-questioning-pink-white-eyes.png" width="96" alt="Question pink water ball, white eyes"> | <img src="./docs/assets/waterball-questioning-pink-no-eyes.png" width="96" alt="Question pink water ball, no eyes"> |
Completed · done | <img src="./docs/assets/waterball-done-cyan-black-eyes.png" width="96" alt="Completed cyan water ball, black eyes"> | <img src="./docs/assets/waterball-done-cyan-white-eyes.png" width="96" alt="Completed cyan water ball, white eyes"> | <img src="./docs/assets/waterball-done-cyan-no-eyes.png" width="96" alt="Completed cyan water ball, no eyes"> |
Error · failed | <img src="./docs/assets/waterball-failed-red-black-eyes.png" width="96" alt="Error red water ball, black eyes"> | <img src="./docs/assets/waterball-failed-red-white-eyes.png" width="96" alt="Error red water ball, white eyes"> | <img src="./docs/assets/waterball-failed-red-no-eyes.png" width="96" alt="Error red water ball, no eyes"> |
Stopped / interrupted · stopped | <img src="./docs/assets/waterball-stopped-charcoal-black-eyes.png" width="96" alt="Stopped charcoal water ball, black eyes"> | <img src="./docs/assets/waterball-stopped-charcoal-white-eyes.png" width="96" alt="Stopped charcoal water ball, white eyes"> | <img src="./docs/assets/waterball-stopped-charcoal-no-eyes.png" width="96" alt="Stopped charcoal water ball, no eyes"> |
Click reaction · waving | <img src="./docs/assets/waterball-waving-orange-black-eyes.png" width="96" alt="Click reaction orange water ball, black eyes"> | <img src="./docs/assets/waterball-waving-orange-white-eyes.png" width="96" alt="Click reaction orange water ball, white eyes"> | <img src="./docs/assets/waterball-waving-orange-no-eyes.png" width="96" alt="Click reaction orange water ball, no eyes"> |
State, ball colors, and interactions
The water-ball's inner color follows the current state; the white outer edge of the gradient never changes. Eye color and visibility are adjustable in settings.
| State | mood | Ball color | Trigger / operation | Animation and duration |
|---|---|---|---|---|
| Idle | idle | Blue #4fb3f7 | No active work; activity/status phase idle | Gentle bobbing |
| Thinking / working | waiting | Green #34d399 | turn/start, step/start, assistant/chunk; or activity/status phase waiting / thinking | Side-to-side tilt until the next state |
| Tool call | jumping | Purple #a855f7 | tool/call; or activity/status phase tool | Hopping until the tool result |
| Awaiting approval | authorizing | Yellow #facc15 | approval/asked | Soft breathing until approval/decided (allowed → continue; rejected/cancelled → error) |
| Awaiting your choice | questioning | Pink #ec4899 | tool/call of ask_user_question | Side-to-side tilt until tool/result (answered → continue thinking; cancelled/dismissed → stopped) |
| Thinking after a tool result | waiting | Green #34d399 | tool/result | Returns to the thinking animation |
| Completed | done | Cyan #22d3ee | activity/status phase done; or turn/end with reason=completed | Cheerful jump for about 2.5 seconds |
| Error | failed | Red #f87171 | turn/end with reason=error | Drooping animation for about 3 seconds |
| Stopped / interrupted | stopped | Dark gray #111827 | turn/end with reason=aborted, blocked, max-tokens, or another stop reason | Sinking animation for about 3 seconds |
| Click reaction | waving | Orange #fb923c | Click the water ball | Side-to-side wave for about 1.6 seconds |
The plugin always supports standard DSH session events. It also accepts the optional activity/status events when an activity-tracking plugin is installed.
Install from GitHub
Requirements: Node.js, pnpm, and DeepSeek Harness.
dsh plugin --profile web add github:sundusk/dsh-waterball-petThe repository includes the prebuilt host and browser artifacts, so installation does not need to run a third-party build script. Restart dsh web, then enable Water Ball Pet under Settings → Plugins → Web UI Plugins.
> Compatibility note: host allowlist > > A successful GitHub installation does not guarantee that the installed DeepSeek Harness > host supports the waterball settings namespace. The Harness > @deepseek-ai/dsh-host-apiproxy package maintains an allowlist for Web UI settings. > If your Harness version does not include waterball, the plugin may install but its > settings card can be unavailable or read-only, settings such as enabled/size/position > may not persist, and some host versions may not render the water-ball overlay. > > If this happens, upgrade DeepSeek Harness to a release that includes waterball in the > host allowlist, restart dsh web, and check again. Editing the local npx cache is only a > temporary development workaround; it does not fix other users' installations and may be > overwritten during reinstall. This is a Harness host compatibility issue, not a GitHub > or npm distribution issue.
Local development
dsh plugin --profile web add link:<absolute-path-to-this-repository>Run pnpm build after changing the source and commit the updated lib/ artifacts.
桌面悬浮球（推荐）
水球不只可以活在网页里。如果你希望它出现在整个电脑桌面上——即使不看 DeepSeek Harness 的 Web UI，也能随时知道任务进度——可以试试 dsh-macDesktop-pet：一款 macOS 原生 悬浮球应用，在桌面上显示一颗置顶的发光小球，颜色随 Agent 状态呼吸变化（思考=绿、 调工具=紫、完成=青、出错=红），瞄一眼桌面即可掌握运行状态。
> Desktop companion: a native macOS app that shows an always-on-top glowing ball breathing > with the Agent's state, so you can track progress at a glance without opening the Web UI.