dsh-live2d-roselia

Readme

# dsh-live2d-roselia

Roselia Live2D 桌宠插件 —— 为 DeepSeek Harness Web GUI 添加可拖拽的 Live2D 看板娘。

收录 Roselia 五位成员的 Live2D 桌宠：湊友希那（主唱）、氷川紗夜（吉他）、
今井リサ（贝斯）、宇田川亜子（鼓手）、白金燐子（键盘），合计 436 套换装
（常服 / 校服 / 演出 / 活动 / 生日 / 联动等，取自 BANDORI 独立版全量数据）；
模型本地存储、同源加载，零网络请求。

## 功能

- 右下角 Live2D 看板娘（5 角色：友希那 / 紗夜 / リサ / 亜子 / 燐子）
- 拖拽自由移动（位置持久化到 localStorage）
- 角色切换 + 换装面板（436 套换装，中文名显示：常服2023 / 活动41 SR / 泳装2023 / 生日2022 等；角色选择面板显示角色头像）
- 视线跟随鼠标、空闲随机动作/台词气泡、点击互动
- 拍照（下载 PNG 截图）
- 隐藏（右下角 Live2D 悬浮钮恢复）
- 纯 DOM 注入，无 React 依赖；卸载时完整清理（监听/定时器/渲染器/DOM）

## 安装

```bash
dsh plugin --profile web add D:\dsh\dsh-live2d-roselia
```

然后重启 dsh web（或热加载 client bundle），硬刷新页面。

## 结构

```
package.json            dsh.bundle.patch / dsh.client(platform: web) / exports["./client"]
cordis.patch.yml        补丁层：insert 一行 host 插件
build/
  tsdown.client.ts      client bundle 构建预设（镜像官方 tsdown.client.ts 协议）
  web-platform.ts       平台模块表（与 shell seed 一致）
src/
  index.ts              host 半区：导出 name/apply，注册 /ro-assets/* 同源静态路由
  routes.ts             静态路由（vendor / waifu.css / 角色图标 / 模型），路径防越界
  client/
    index.ts            浏览器半区：ctx.effect 持有启动/清理，注入样式 + 按序加载运行时
    waifu/              widget 源码（改造：vendor 全局惰性解析、生命周期可清理）
assets/
  vendor/               pixi.min.js (PIXI 6.5.2) / live2d.min.js (Cubism 2.1 框架) /
                        live2d-display.cubism2.min.js (pixi-live2d-display 0.4.0 cubism2 版)
  waifu.css             桌宠样式（注入时叠加高 z-index 覆盖）
  assets/               角色头像（chara_icon_47/36/16/1/32.png = 友希那/紗夜/リサ/亜子/燐子）
  model/                模型资源（5 角色 × 436 套，Cubism 2，约 660MB）
```

## 开发

```bash
pnpm install
pnpm build        # tsdown 双产物：lib/index.js (host) + lib/client.js (browser)
```

改代码后：`pnpm build` → 重启 dsh web → 硬刷新页面。
（若 bundle 内容无变化仍未生效，完全重启 dsh web。）

## 规范说明

- host 半区为函数插件四要素的子集：导出 `name` 与 `apply`（无用户可配置项，故省略
  `Config`）；`webServer` 为必需服务，经 `ctx.inject(['webServer'], cb)` 声明后使用，
  路由注册的 disposer 包进 `ctx.effect`，卸载/HMR 自动清理。
- client 半区全部副作用（DOM、监听、定时器、PIXI 渲染器）随 fiber dispose：
  `apply` 内整体注册为 `ctx.effect`，返回 disposer 全量回收。
- 浏览器半区只 import 自身模块与类型（`@deepseek-ai/cordis` 仅 type-only），
  不越过平台模块表，无跨插件值导入。
- 静态路由前缀使用 `/ro-assets`（与 dsh-live2d-mygo 的 `/pet-assets` 区分，
  两插件可同时安装互不冲突）。
- 分发采用「lib 产物提交进 Git」策略（与 dsh-gbc-ui 一致）：无 prepare 脚本，
  `dsh plugin add github:...` 免 allowBuilds 直装。

## 说明

- 模型为邦邦（BanG Dream!）手游解包资源（源自 D:\za\GitHub\Live2D 自包含版
  model-data，编号 001/016/032/036/047），仅供个人学习研究使用。
- 台词包按 5 角色人设撰写（友希那 冷艳高音 · 舞台女王 / 紗夜 认真严谨 · 反差萌 /
  リサ 温柔大姐姐 · 队内粘合剂 / 亜子 中二病 · 自称魔女 / 燐子 胆小害羞 · 绝对音感）。
- 渲染栈：pixi-live2d-display（Cubism 2）× PIXI 6.5.2，与自研 widget 一致。
  Cubism 2.1 链只需 live2d.min.js（框架）+ cubism2 版 display，无需 Cubism Core。