sundusk/dsh-waterball-pet

dsh-waterball-pet

一个适用于 DeepSeek Harness Web UI 的漂浮水球宠物插件。水球使用纯 SVG 绘制，
内部颜色会随 Agent 的会话状态变化（外层白色渐变保持不变），球体带柔和投影与
底部接触阴影，便于在浅色页面上看清边界。眼睛可在设置中切换白色/黑色或隐藏。
支持在 Web UI 中开关、调整大小和拖动位置。

这是一个适用于 DeepSeek Harness Web UI 的漂浮水球宠物插件。它使用 SVG
绘制，并响应 Agent 会话事件：水球内部颜色随状态变化，而渐变的外层白色边缘
保持不变。柔和的投影和静态的底部接触阴影使水球在浅色页面背景下依然可见。
眼睛可在插件设置中切换为白色或黑色，或隐藏。Web UI 设置卡片控制可见性、
大小和位置。

兼容性

- 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，在新版浏览器端会因模块表无法解析而加载失败。

状态外观

以下为不同状态下的水球样式：

| 状态 | 黑色眼睛 | 白色眼睛 | 隐藏眼睛 |
| --- | --- | --- | --- |
| 空闲 · 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 事件。

安装

从 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

状态外观

各状态的水球样式：

| 状态 | 黑色眼睛 | 白色眼睛 | 隐藏眼睛 |
| --- | --- | --- | --- |
| 空闲 · 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 | ask_user_question 的 tool/call | 左右摇摆，直到 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

该仓库包含预构建的宿主和浏览器产物，因此安装时无需运行第三方构建脚本。重启 dsh web，然后在 设置 → 插件 → Web UI 插件 下启用 Water Ball
Pet。

兼容性说明：宿主允许列表

GitHub 安装成功并不保证已安装的 DeepSeek Harness
宿主支持 waterball 设置命名空间。Harness
@deepseek-ai/dsh-host-apiproxy 包为 Web UI 设置维护了一个允许列表。
如果你的 Harness 版本不包含 waterball，插件可能可以安装，但其
设置卡片可能不可用或为只读，enabled/size/position 等设置
可能无法持久化，并且某些宿主版本可能无法渲染水球悬浮层。

如果出现这种情况，请将 DeepSeek Harness 升级到在
宿主允许列表中包含 waterball 的版本，重启 dsh web，然后再次检查。编辑本地 npx 缓存只是
临时的开发变通方法；它无法修复其他用户的安装，并且可能在重新安装时被
覆盖。这是 Harness 宿主的兼容性问题，不是 GitHub
或 npm 分发问题。

本地开发

dsh plugin --profile web add link:

更改源代码后运行 pnpm build，并提交更新后的 lib/ 产物。

桌面悬浮球（推荐）

水球不只可以活在网页里。如果你希望它出现在整个电脑桌面上——即使不看 DeepSeek
Harness 的 Web UI，也能随时知道任务进度——可以试试
dsh-macDesktop-pet：一款 macOS 原生
悬浮球应用，在桌面上显示一颗置顶的发光小球，颜色随 Agent 状态呼吸变化（思考=绿、
调工具=紫、完成=青、出错=红），瞄一眼桌面即可掌握运行状态。

桌面伴侣：一款原生 macOS 应用，显示一个始终置顶的发光小球，随 Agent 的状态呼吸变化，
因此你无需打开 Web UI 即可一眼掌握进度。