@sundusk/dsh-waterball
适用于 dsh Web GUI 的水球宠物插件：一个带白色眼睛、漂浮的天蓝色水球，会根据代理活动状态（空闲 / 思考 / 工具）做出反应，并在设置的插件部分提供启用开关和大小选项。适配 dsh 0.1.2-alpha.1（已移除 dsh-client-runtime）。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:sundusk/dsh-waterball-pet#5fb3ce282e10fcb109b41bf5ea27c13f04dffe29Waterball 以 @sundusk/dsh-waterball 发布，当前版本为 0.2.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
一个适用于 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.
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 模块。0.1.0-rc.7，其构建产物 require
@deepseek-ai/dsh-client-runtime/client，在新版浏览器端会因模块表无法解析而加载失败。以下为不同状态下的水球样式：
| 状态 | 黑色眼睛 | 白色眼睛 | 隐藏眼睛 |
|---|---|---|---|
空闲 · idle | 空闲，蓝色水球，黑色眼睛 | 空闲，蓝色水球，白色眼睛 | 空闲，蓝色水球，无眼睛 |
思考 / 工作 · waiting | 思考，绿色水球，黑色眼睛 | 思考，绿色水球，白色眼睛 | 思考，绿色水球，无眼睛 |
工具调用 · jumping | 工具调用，紫色水球，黑色眼睛 | 工具调用，紫色水球，白色眼睛 | 工具调用，紫色水球，无眼睛 |
授权等待 · authorizing | 授权等待，黄色水球，黑色眼睛 | 授权等待，黄色水球，白色眼睛 | 授权等待，黄色水球，无眼睛 |
做出你的抉择 · questioning | 做出你的抉择，粉色水球，黑色眼睛 | 做出你的抉择，粉色水球，白色眼睛 | 做出你的抉择，粉色水球，无眼睛 |
完成 · done | 完成，青色水球，黑色眼睛 | 完成，青色水球，白色眼睛 | 完成，青色水球，无眼睛 |
出错 · failed | 出错，红色水球，黑色眼睛 | 出错，红色水球，白色眼睛 | 出错，红色水球，无眼睛 |
停止 / 中断 · stopped | 停止，深灰色水球，黑色眼睛 | 停止，深灰色水球，白色眼睛 | 停止，深灰色水球，无眼睛 |
点击挥手 · waving | 点击挥手，橙色水球，黑色眼睛 | 点击挥手，橙色水球，白色眼睛 | 点击挥手，橙色水球，无眼睛 |
水球内部颜色随状态变化，外层白色渐变始终不变。眼睛颜色与显隐可在设置中调整。
| 状态 | 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 事件。
需要已安装 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 安装无需执行构建脚本。Water ball styles for each state:
| State | Black eyes | White eyes | Hidden eyes |
|---|---|---|---|
Idle · idle | Idle blue water ball, black eyes | Idle blue water ball, white eyes | Idle blue water ball, no eyes |
Thinking / working · waiting | Thinking green water ball, black eyes | Thinking green water ball, white eyes | Thinking green water ball, no eyes |
Tool call · jumping | Tool call purple water ball, black eyes | Tool call purple water ball, white eyes | Tool call purple water ball, no eyes |
Awaiting approval · authorizing |
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.
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
waterballsettings namespace. The Harness@deepseek-ai/dsh-host-apiproxypackage maintains an allowlist for Web UI settings. If your Harness version does not includewaterball, 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
waterballin the host allowlist, restartdsh 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.
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.
| Awaiting approval yellow water ball, black eyes |
| Awaiting approval yellow water ball, white eyes |
| Awaiting approval yellow water ball, no eyes |
Awaiting your choice · questioning | Question pink water ball, black eyes | Question pink water ball, white eyes | Question pink water ball, no eyes |
Completed · done | Completed cyan water ball, black eyes | Completed cyan water ball, white eyes | Completed cyan water ball, no eyes |
Error · failed | Error red water ball, black eyes | Error red water ball, white eyes | Error red water ball, no eyes |
Stopped / interrupted · stopped | Stopped charcoal water ball, black eyes | Stopped charcoal water ball, white eyes | Stopped charcoal water ball, no eyes |
Click reaction · waving | Click reaction orange water ball, black eyes | Click reaction orange water ball, white eyes | Click reaction orange water ball, no eyes |
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 |