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.
兼容性
- v0.2.0 适配 DeepSeek Harness
dsh-v0.1.2-alpha.1：该版本删除了
@deepseek-ai/dsh-client-runtime 包，快照 store 引擎迁移为平台模块
@deepseek-ai/dsh-client-store。本插件客户端改为自包含实现
（src/client/snapshot-store.ts），bundle 只 require react 系平台模块，
不再 require 任何 @deepseek-ai 模块。
- v0.1.x（≤0.1.3）面向
0.1.0-rc.7，其构建产物 require
@deepseek-ai/dsh-client-runtime/client，在新版浏览器端会因模块表无法解析而加载失败。
状态外观
以下为不同状态下的水球样式：
状态、内部颜色与操作
水球内部颜色随状态变化，外层白色渐变始终不变。眼睛颜色与显隐可在设置中调整。
| 状态 | 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, 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 |
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-pet
The 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.
