# dsh-ui-web

> A whale-girl pet on the bottom-right corner of the DSH Web interface. Animations switch based on chat activity. Pat and feed to increase intimacy and level up. Features include naming, dragging, hiding, and summoning.

## Metadata

- Author: [@CAPTAIN1275](https://github.com/CAPTAIN1275)
- Repo: <https://github.com/CAPTAIN1275/dsh-ui-web.git>
- GitHub: [CAPTAIN1275/dsh-ui-web](https://github.com/CAPTAIN1275/dsh-ui-web)
- Stars: 34
- Language: TypeScript
- License: [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)
- Topics: `dsh-plugin`, `dsh-plugin-market`, `dsh-plugins`
- Forks: 2
- Open Issues: 0
- Last push: 2026-08-16T18:08:27.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:CAPTAIN1275/dsh-ui-web/packages/dsh-pet
```

## Wiki

## 一句话定位
在 DeepSeek Harness Web 界面的右下角养一只鲸鱼娘养成系宠物：模型在思考、等待、调工具、完成时她会自动切换动画，你可以摸头、喂食、改名、拖动她，亲密度会从幼鲸一路涨到「深海羁绊」。

## 核心能力
- 跟随模型会话状态切换动画：思考 / 调用工具时她"工作"、等待时她待机、完成时她跳跃庆祝、空闲时她呼吸
- 摸头（10 秒冷却，+1 好感）与喂食（30 秒冷却，+5 好感、-1 小鱼干）两种互动，进度实时气泡反馈
- 亲密度 4 级养成：幼鲸 → 伙伴 → 挚友 → 深海羁绊（100 点封顶），跨级时弹出"升级啦！"提示
- 小鱼干经济：每完成 3 个模型回合 +1 条，每过 30 分钟自然 +1 条，库存上限 20 条
- 自定义命名（1–20 字符）、悬浮面板喂食/改名/隐藏、按住拖动重定位（位置持久化）、隐藏后输入框出现"召唤{名字}"按钮
- 全局浮层：会话生命周期外（新建会话空屏）也始终挂在右下角，不依赖某个会话或 UI 槽位

## 技术实现
- **语言**: TypeScript（带 JSX）+ Node.js（host 半区）+ React 18（browser 半区）
- **关键依赖**: `@deepseek-ai/cordis`（插件框架）、`@deepseek-ai/dsh-host-webserver`（挂 `/api/pet/*` 与 `/pet/whale/*` 路由）、`@deepseek-ai/dsh-client-runtime` + `@deepseek-ai/dsh-client-ui-settings`（浏览器半区 + 设置卡）、`schemastery`（DSH 设置 schema 校验）、React 18（由 DSH 外壳注入）
- **架构模式**: 双半区 cordis bundle。`src/index.ts` 是 host 半区，导出 `name='pet'` 与 cordis `apply`：构造 `PetService` 监听 `session/event`（turn/start、step/start、tool/call、turn/end 派发到 idle/waiting/thinking/tool/done 五个相位），通过 `installSettingsSection` 注册名为 `pet` 的设置分区，按 enabled 状态挂载路由。`src/client/index.ts` 是 browser 半区，`createRoot → document.body` 全局挂载浮层，每 800ms 轮询 `/api/pet/state`，配合 `visibilitychange` 在标签页回到前台时立即拉取，注册中英字典并把设置卡挂到 `web-ui.plugin.item` 槽位
- **入口文件**: host 半区 `packages/dsh-pet/src/index.ts`，browser 半区 `packages/dsh-pet/src/client/index.ts`，bundle 声明在 `packages/dsh-pet/cordis.patch.yml:8-10`（插入 `id: pet`），浏览器依赖注入在 `packages/dsh-pet/package.json:37-49`

## 适用场景
长时间盯着 DSH Web 跑模型任务、想要一点陪伴感的用户：模型思考时鲸鱼娘在脚下工作，完成时跳一下庆祝，亲密度随使用时长和工作回合自然增长。也适合想给 DSH 界面增加一点"养成感"、又不需要复杂配置的人——安装即用，关闭、隐藏、改名都能在设置里直接搞定。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH 宿主 | `0.1.0-rc.6+` | peerDependencies 锁到 `@deepseek-ai/dsh-* ^0.1.0-rc.6`；运行时只依赖 4 个浏览器端 `@deepseek-ai/dsh-client-*` 包 |
| Node.js | `^22.19.0` 或 `>=24.0.0` | `engines.node` 字段明确要求 |
| 平台 | web（DSH 浏览器端） | 包内 `dsh.client.platform: "web"`，无桌面/终端适配 |
| 原生模块 | 无 | 运行时只引入 `clsx` + `schemastery`（纯 JS）；CSS Modules 由 lightningcss 内联为 `<style data-plugin>` |
| React | `^18.2.0` | peerDependency，由 DSH 外壳注入 |

## 安装方式
```bash
dsh plugin --profile web add github:CAPTAIN1275/dsh-ui-web/packages/dsh-pet
```

## 配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| 启用宠物（enabled） | 开关 | 插件总开关：关闭后浮层、轮询、API 路由一起停用 | 开 |
| 显示宠物（visible） | 开关 | 是否在屏幕上显示浮层；关闭后聊天输入区出现"召唤{名字}"按钮 | 开 |
| 大小（size） | 数字（32–512，px） | 宠物显示尺寸，等于图集单格高度 | 160 |
| 距右侧（right） | 数字（0–10000，px） | 距视口右边界的水平偏移（拖动时实时同步） | 24 |
| 距底部（bottom） | 数字（0–10000，px） | 距视口底边的垂直偏移（拖动时实时同步） | 20 |
| 名字（name） | 字符串（1–20 字符） | 宠物的显示名，会出现在悬浮面板和"召唤{名字}"按钮上 | "鲸鱼娘" |
| 摸头冷却 | 内部常量（affinity.petCooldownMs） | 两次摸头之间的最小间隔，源码可调 | 10000 ms |
| 喂食冷却 | 内部常量（affinity.feedCooldownMs） | 两次喂食之间的最小间隔，源码可调 | 30000 ms |
| 小鱼干上限 | 内部常量（treats.maxTreats） | 库存硬上限 | 20 |
| 亲密度上限 | 内部常量（affinity.AFFINITY_MAX） | 累计好感点的封顶 | 100 |

> 说明：冷却时间、小鱼干经济参数、亲密度上限是源码内置在 `affinity.ts` / `treats.ts` 里的常量，普通用户用默认即可；如需调整可由 host 在 `PetConfig` 中传入 `affinity` / `treats` 字段覆盖。

## 常见问题

**Q: 安装之后右下角没看到宠物怎么办？**

A: 先确认已经重启了 `dsh web`——cordis bundle 的注入只在 host 启动时生效。如果还是不显示，打开浏览器控制台看有没有 `pet.state transport error`，再到设置 → 插件配置 → 宠物把"启用宠物"打开。

**Q: 摸头 / 喂食没反应，是不是坏了？**

A: 大概率是冷却中。摸头 10 秒内重复点击、喂食 30 秒内重复点击，鲸鱼娘会发气泡提示"今天摸够啦"或"吃饱饱啦"，冷却结束前都不会再生效。喂食还可能因为小鱼干库存为零被拒绝。

**Q: 小鱼干用完了怎么补？**

A: 不能直接充值。两条补给路径：每完成 3 个模型回合自动 +1 条，每过 30 分钟自然 +1 条。存满 20 条后不再涨，但亲密度仍会随时间缓慢增长（每 30 分钟 +1 点）。

**Q: 卸载插件会丢掉亲密度和小鱼干吗？**

A: 不会。所有状态（命名、亲密度、库存、位置、自定义）都写在 `$DSH_HOME/pet.json`（默认 `~/.dsh/pet.json`），卸载插件不会删这个文件，重新安装后进度自动恢复。

**Q: 能换成自己的角色或加多只宠物吗？**

A: 当前版本不支持。本插件只内置了鲸鱼娘这一只，没有多宠物注册表或自定义图集投放机制；想换角色需要直接改源码中的 `spritesheet.ts` 几何定义与图集资源。

**Q: 设置里看不到宠物配置卡怎么办？**

A: 说明当前 DSH 版本没有把 `pet` 这个设置命名空间暴露到设置页（少数部署会限定 `WEB_SETTINGS_NAMESPACES` 白名单）。遇到这种情况可以直接编辑 `$DSH_HOME/settings.yaml`，或在 dsh-host-apiproxy 的白名单里加上 `pet` 后重启。

**Q: 宠物的命名能改吗？有长度限制吗？**

A: 能在悬浮面板的"改名"入口里直接改，1–20 字符，不能全是空白。改名后召唤按钮、悬浮面板都会同步显示新名字。

## 上手难度
入门 — 安装即用，零配置启动；可选的高级设置（尺寸、位置、命名）都在设置卡片里点几下就能改，不需要接触代码或配置文件。

## 已知问题与限制
- `failed` 动画已经在 9 状态图集契约里占了一行（row 5），但当前 rc.6 还没有任何 DSH 事件源能点亮它，模型失败时表现等同于 idle
- 插件依赖 rc.6 的 `session/event`（turn/start、step/start、tool/call、turn/end）派生动画相位；如果宿主版本低于 rc.6 或会话事件缺失，宠物会一直停在 idle
- `pet.json` 文件损坏时，插件会静默回退到默认值继续运行；用户的亲密度、命名、库存、位置会丢失但不会报错提示
- `packages/dsh-pet/package.json` 声明 `"license": "Apache-2.0"`，但子包内的 `LICENSE` 文件是 BSD-3-Clause——许可证元数据不一致，使用前以仓库根 `LICENSE` 为准
- 浏览器半区在 apply 与 mount 时会向控制台输出 `console.log` 和 `console.warn` 调试日志，正式使用场景里会留下噪声

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dsh-ui-web](https://deepseek-plugin.org/plugins/CAPTAIN1275/dsh-ui-web/packages/dsh-pet)
Wiki generated by AI (model: `MiniMax-M3`)