# dsh-web-ui

> Registry-driven desktop pet companion for dsh web GUI. Model session activity drives animation switching. Pet and feed to increase intimacy. Supports custom pets and messages.

## Metadata

- Author: [@zhu1090093659](https://github.com/zhu1090093659)
- Repo: <https://github.com/zhu1090093659/dsh-web-ui.git>
- GitHub: [zhu1090093659/dsh-web-ui](https://github.com/zhu1090093659/dsh-web-ui)
- Stars: 5,125
- Language: TypeScript
- License: [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)
- Homepage: <https://gallery.dsh-market.com>
- Topics: `deepseek-harness`, `dsh`, `dsh-plugin`, `web-ui`
- Forks: 310
- Open Issues: 49
- Last push: 2026-08-20T14:37:38.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

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

## Wiki

## 一句话定位
为 dsh web GUI 增加一只常驻右下角的桌面宠物伴侣：模型会话活动驱动它切换动画，你可以摸头喂食攒亲密度，并能通过投放 `pet.json` 目录的方式无改代码接入任何自定义精灵或 Live2D 宠物。

## 核心能力
- 在右下角挂一个浮窗精灵，模型处于等待 / 思考 / 调工具 / 整理 / 完成 / 失败六个相位时切换为不同动画；完成会跳一下，失败静一静后回到待机
- 摸头（10 秒冷却，+1 好感）和喂小鱼干（30 秒冷却，+5 好感，-1 库存）两种互动；亲密度从「幼鲸」到「鲸生共渡」共 9 级，攒到顶也不会卡住
- 小鱼干是稀缺经济：每完成 30 轮会话 +1 条，每过 5 小时 +1 条，库存上限 20，比原版 Codex 节奏慢 10 倍
- 内置两只鲸鱼娘（原版 + 精致版），并通过「注册表」扫描 `$DSH_HOME/pets/` 用户目录、`~/.codex/pets/` legacy 目录、以及嵌入应用传入的额外条目，同 id 自动覆盖
- 支持 sprite2d 精灵图集（9 行 × 8 列默认契约）与 Live2D 模型（v2 manifest）；Live2D 走 PixiJS 按需加载的 MIT vendor bundle
- 悬浮面板提供改名、投喂、隐藏+召唤、按住拖动改位置；状态气泡按场景轮换词库，支持 `voice.json` 替换全部文案与按钮文字

## 技术实现
- **语言**: TypeScript（带 JSX）+ Node.js（host 半区）+ React 18（browser 半区）
- **关键依赖**: `react` / `react-dom` ^18.2.0（peer，宿主运行时注入）、`clsx`（类名合并）、`schemastery`（DSH 配置 schema 校验）、Live2D 路径按需加载的 `pixi.js` + `untitled-pixi-live2d-engine` MIT vendor bundle
- **架构模式**: 双半区 cordis bundle：`src/index.ts` 是 host 半区（`export const name='pet'`、cordis Service `pet.*`、注册设置分区、挂载 `/api/pet/*` 与 `/pet/<id>/*` 路由），`src/client/index.ts` 是 browser 半区（`createRoot → document.body` 全局挂载、每 2 秒轮询 host、`visibilitychange` 唤醒后立即拉取、`ctx.locale.register` 注册中英字典、`ctx.slots.inject('settings.section', …)` 注册顶级设置卡）
- **入口文件**: `packages/dsh-pet/src/index.ts`（host 入口）、`packages/dsh-pet/src/client/index.ts`（browser 入口）；cordis bundle 声明在 `packages/dsh-pet/cordis.patch.yml:1-10`（插入 id `pet`），浏览器依赖在 `packages/dsh-pet/package.json:45-58`（注入 4 个官方 `@deepseek-ai/dsh-client-*` 模块 + `platform: web`）

## 适用场景
- 想要让 DSH Web GUI 在长时间跑模型任务时不那么单调、同时还有「养一只小宠物」陪伴感的用户：模型思考时它在脚下游动，完成时它跳一下庆祝；
- 想为自己作品或社区主题做一只「招牌精灵 / 看板娘」放进 DSH 的用户：把 `pet.json` + 图集丢进 `$DSH_HOME/pets/` 就能上线，免改插件代码；
- 想给宠物换一套「人设台词」（比如让某只猫喊别的口号）的用户：在宠物目录里放一份 `voice.json` 即可逐槽覆盖。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH 宿主 | `0.1.0-rc.6+` 推荐 | 包未在 dsh.engines 声明最低版本；devDependencies 统一锁到 `@deepseek-ai/dsh-* ^0.1.0-rc.8`，已知宿主 CLI 为 0.1.0-rc.7/rc.8 |
| Node.js | `^22.19.0` 或 `>=24.0.0` | package.json `engines.node` |
| 平台 | 跨平台 | host 半区是 Node.js，client 半区是浏览器，无 OS 限制 |
| 原生模块 | 无 | 运行时依赖只有 clsx / schemastery；Live2D 用的 PixiJS 与 Live2D 引擎是 MIT vendor bundle，Cubism Core 由用户自备 |
| React | `^18.2.0` | peerDependency，由宿主注入 |

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

## 配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| visible | 开关 | 是否在屏幕上显示宠物 | true |
| size | 数字（32–512，px） | 宠物显示尺寸（精灵单格高度） | 160 |
| right | 数字（0–10000，px） | 距视口右边界的水平偏移 | 24 |
| bottom | 数字（0–10000，px） | 距视口底边的垂直偏移 | 120 |
| petId | 字符串 | 当前选中的宠物 id（在注册表里选） | 内置默认鲸鱼娘 |
| enabled | 开关 | 插件总开关：关闭时宠物和 API 一起停用 | true |
| decorationEnabled | 开关 | 是否在状态气泡前显示小鲸鱼装饰 | true |
| 互动冷却（摸头） | 内部常量（affinity.petCooldownMs） | 两次摸头之间的最小间隔，源码可调 | 10000 ms |
| 互动冷却（喂食） | 内部常量（affinity.feedCooldownMs） | 两次喂食之间的最小间隔，源码可调 | 30000 ms |
| 小鱼干上限（treats.maxTreats） | 数字 | 库存上限 | 20 |
| 好感上限（affinity.AFFINITY_MAX） | 数字 | 好感点累计上限 | 999999999 |

> 说明：「互动冷却 / 小鱼干上限 / 好感上限」默认在源码 `affinity.ts` / `treats.ts` 内，如要调整需通过 host 配置传入 `affinity` / `treats` 参数；普通用户用默认即可。

## 常见问题

**Q: 安装之后宠物不显示怎么办？**

A: 安装后必须重启 `dsh web`，注册表只在 host 启动时构建一次；浏览器半区会通过 `/api/pet/pets` 拿列表，确认你看到两个内置选项。如果只是空白，先看浏览器控制台是否有 `pet.state transport error`，多出现于浏览器半区被禁用时——到设置 → 宠物把「enabled」打开即可。`packages/dsh-pet/src/client/index.ts:114-119、165-184` / `packages/dsh-pet/README.zh.md:271-272`。

**Q: 我换了一台电脑，好感度和小鱼干会带过去吗？**

A: 数据写在 `$DSH_HOME/pet.json`（默认 `~/.dsh/pet.json`），不在云端。手动复制这个文件到新机器的相同路径即可恢复所有进度（亲密度、命名、库存、位置、自选宠物 id）。`packages/dsh-pet/src/persist.ts:77-167`。

**Q: 自定义的 Live2D 模型为什么不显示？**

A: 大概率是缺 Cubism Core。Live2D 专有许可禁止再分发，本插件无法替你下载它；从 Live2D 官方拿到 `live2dcubismcore.min.js` 放到 `$DSH_HOME/pets/.runtime/` 下，然后重启 dsh web 即可。如果路径正确仍然空白，再看图集路径与 `live2d.model` 是否一致，以及模型目录是否在 `$DSH_HOME/pets/` 下。`packages/dsh-pet/README.zh.md:127-134`。

**Q: 多会话同时跑，宠物会不会卡或者气泡一长串？**

A: 不会。精灵动画跟最近一次有意义的活动走；多个顶层会话每个各自一个气泡，最多同屏 12 个，多出的合并到主气泡右上角的 +N 角标，悬停展开；子代理不占独立气泡，避免 N 个对话叠出 N+ 子代理数 的气泡堆。`packages/dsh-pet/src/service.ts:439-458、559-571`。

**Q: 我不喜欢它说话的语气，怎么改？**

A: 两种粒度。最简的是把鼠标停到悬浮面板按「改名」，只是给当前宠物换个称呼；想要整套「换话术」，在宠物目录下放一份 `voice.json`（或在 `$DSH_HOME/pets/.voice.json` 写全局覆盖），按 `voicePackVersion: 1` 的格式覆盖 status / tools / whispers / panel 四个区段；合并优先级 宠物自带 > 全局 > 内置，坏包只警告不拒载。`packages/dsh-pet/README.zh.md:91-123`。

**Q: 怎么彻底关掉它，不卸载插件？**

A: 进设置 → 宠物，关闭「enabled」即可，host 端 API 与浏览器端都会同步卸载（隐藏后右下角会出现一个「召唤 名字」按钮再次启用）。想从设置中彻底拿掉，包括插件自身，使用 `dsh plugin --profile web remove github:zhu1090093659/dsh-web-ui/packages/dsh-pet`，`$DSH_HOME/pets/` 与 `pet.json` 不会被删，下次重装可接上。`packages/dsh-pet/src/index.ts:177-191` / `packages/dsh-pet/src/client/index.ts:312-315`。

**Q: 局域网里别人能拿到我的宠物图集或状态吗？**

A: 默认不能。所有 `/api/pet/*` 与 `/pet/<id>/*` 都套 loopback 围栏（127.0.0.1 + Host 头 + sec-fetch-site），LAN 邻居直接 403。同时安装了 `dsh-remote-web-ui` 的情况下，已配对设备的 cookie 才可作为额外放行。资产路由还做 realpath 越界检测（symlink 逃跑 403）与大小上限（图片 20 MB、Live2D 模型 32 MB、manifest 64 KB，超限 413）。`packages/dsh-pet/README.zh.md:289-295` / `packages/dsh-pet/src/routes.ts:42-49、72-82`。

## 上手难度
入门 — 一行命令安装、零额外配置即可见到内置鲸鱼娘；想自带的玩家只需按 README 给的 `pet.json` 模板在 `$DSH_HOME/pets/` 下放图集与描述文件，不涉及任何 TS/JS 代码。

## 已知问题与限制
- Live2D Cubism Core 由 Live2D 专有许可限制，本插件不内置也不下载；缺文件时 Live2D 宠物位置显示安装指引卡，sprite2d 宠物不受影响（`packages/dsh-pet/README.zh.md:127-134` / `packages/dsh-pet/src/routes.ts:328-345`）
- 资产路由硬上限：图集与 PNG/WebP/GIF 图像 20 MB、Live2D 模型闭包文件 32 MB、manifest 64 KB；超出返回 413（`packages/dsh-pet/src/routes.ts:42-49`）
- 用户编写的 `voice.json` / `decoration.json` / `.voice.json` 扫描时按 64 KB 限额与「必须是普通文件」过滤；超限或设备/FIFO 静默跳过（`packages/dsh-pet/src/registry.ts:629-661`）
- `pet.json` 损坏或不存在时静默回退到默认值，不会报错（`packages/dsh-pet/src/persist.ts:156-158`）
- 注册表完全扫描不到任何可用条目时插件启动直接抛错 `[dsh-pet] no valid pet manifests found`（`packages/dsh-pet/src/service.ts:246-248`）
- Live2D 模型必须放在宠物目录下且其引用闭包（moc、贴图、动作、物理、姿态、表情）需齐全；模型 `.model3.json` 引用了穿越/绝对/URL 形态的文件会直接拒载并给诊断（`packages/dsh-pet/src/registry.ts:500-535`）
- 仅依赖旧 `${CODEX_HOME:-~/.codex}/pets/` 的 hatch-pet legacy 来源仍可识别但已是历史兼容，新宠物请直接进 `$DSH_HOME/pets/`（`packages/dsh-pet/src/registry.ts:813-820`）
- 第三方装饰（喷水鲸鱼）素材派生自 DeepSeek wordmark（MIT），详见 `packages/dsh-pet/THIRD_PARTY_NOTICES.md`

---

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