# dsh-ventus-whale

**Ventus 虎鲸桌宠**：一个可交互的 DeepSeek 虎鲸 3D 模型浮窗（透明背景），悬浮在 Web GUI 角落。基于 DeepSeek 虎鲸 logo 轮廓构建的 swept 3D 模型，带尾鳍/背鳍/胸鳍/眨眼动画。

## 功能

- **透明 3D 虎鲸**：three.js 实时渲染，**默认关闭**，召唤后出现在视口右侧中部（默认位置，可拖拽自由定位）
- **拖动旋转**：按住虎鲸拖动旋转视角（arcball，松手带惯性）；悬停时游动加快、微微转头看向光标
- **右键拖动**：把虎鲸拖到任意位置（自由定位持久化，设置改动不会丢失）
- **单击爱心**：头顶冒出一簇 3–5 颗爱心，跟随虎鲸旋转、上浮渐隐
- **双击弹跳**：虎鲸原地跳一下
- **悬停工具栏**：两行布局——改名（内联编辑，Enter 保存 / Esc 取消）、重置、**拖动**（进入拖动模式，鼠标/触屏按住即可移动）、爱心开关、**转圈**（随时让虎鲸翻一个 360° 跟头）；触屏设备点按虎鲸即可唤出工具栏
- **空闲动画**：温和游动 + 尾鳍摆动 + 胸鳍划水 + 自动眨眼
- **设置页「Ventus 插件」分组**（描述为「Ventus 系列的插件设置」）：与「Web UI 插件」同级，内含「大肥鱼桌宠」设置卡
  - **启用开关**：开/关虎鲸（修改后点「保存」生效）
  - **大小滑块**：虎鲸窗口随大小缩放（0.2×–3×，鲸鱼始终完整可见）
  - **灵敏度滑块**：拖动旋转灵敏度（0.2×–5×）
  - **显示文字**：虎鲸下方可自定义文字（默认隐藏，留空即隐藏）
  - **保存/取消**：设置修改不再自动保存，草稿攒好后点「保存」一次性生效，「取消」丢弃未保存修改

## 安装（GitHub 分发）

```sh
dsh plugin --profile web add github:mmzm0808/dsh-ventus-whale#v0.1.0
```

仓库已提交完整 `lib/` 构建产物，安装**无需执行构建脚本**（pnpm ≥10 的 allowBuilds 门禁不影响本插件）。安装后**重启 dsh**（新 bundle 层在启动时加载）。

> 本地开发安装：`dsh plugin --profile web add "<本仓库本地绝对路径>"`

## 使用

1. **默认关闭**：启动后虎鲸不出现；点侧边栏底部（设置旁）的 🐋 按钮召唤（再点隐藏），召唤后出现在视口右侧中部
2. 左键拖动旋转、右键或工具栏「拖动」按钮定位（鼠标/触屏均可，松手保存位置）、单击爱心、双击弹跳、悬停工具栏改名/重置/拖动/爱心开关
3. 设置 → Ventus 插件 → 大肥鱼桌宠：调大小/灵敏度/文字后点「保存」生效

## 数据

- 配置持久化在 `~/.dsh/dsh-ventus-whale/config.json`（原子写入）
- API：`/api/ventus-whale/state|update|reset`（loopback-only）

## 开发

```sh
pnpm install
pnpm build      # tsc types + tsdown (host lib + client bundle)
pnpm verify     # typecheck + 冒烟测试
```

## 说明

- three.js（0.147）内联进 client bundle（约 470KB，gzip 后 123KB），第三方声明见 [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md)
- 模型几何体来自 DeepSeek 虎鲸 logo 轮廓的 swept 重建，着色器实现 logo 眼斑图案
- 许可证：MIT