# 🐳 dsh-ventus-whale
> 🧩 **一键整合安装：[dsh-ventus-plugins](https://github.com/mmzm0808/dsh-ventus-plugins)** —— 本插件已并入整合包，也可按本仓库方式单独安装。



**蓝色大肥鱼 · DeepSeek 3D 桌宠** —— 一只由 DeepSeek 虎鲸 logo 轮廓构建的可交互 3D 桌宠，悬浮在你的 Web GUI 角落，陪你聊天、跟头庆祝、冒爱心。

<p align="center">
  <img src="docs/preview-light.gif" alt="亮色主题预览：游动 · 悬停工具栏 · 360° 转圈 · 爱心喷发" width="420">
  <img src="docs/preview-dark.gif" alt="暗色主题预览：游动 · 悬停工具栏 · 360° 转圈 · 爱心喷发" width="420">
</p>

<p align="center">
  <img alt="license" src="https://img.shields.io/badge/license-MIT-blue">
  <img alt="version" src="https://img.shields.io/badge/version-v0.1.0-blueviolet">
  <img alt="runtime" src="https://img.shields.io/badge/runtime-dsh%20web-4d6bfe">
</p>

## ✨ 特性

| 分类 | 说明 |
|---|---|
| 🖼️ 3D 模型 | DeepSeek 虎鲸 logo 轮廓 swept 重建，尾鳍 / 背鳍 / 胸鳍 / 眨眼动画，透明背景 |
| 🎮 交互 | 左键拖拽旋转（arcball + 惯性）、右键或「拖动」模式自由定位、单击爱心、双击弹跳 |
| 🌀 转圈 | 发送消息自动翻 360° 前空翻（可关），或悬停工具栏「转圈」按钮手动触发 |
| 🧰 悬停工具栏 | 两行布局：改名 / 重置 / 拖动 / 爱心开关 / 转圈；触屏点按唤出 |
| ⚙️ 设置 | 大小（窗口随缩放，鲸鱼始终完整可见）、灵敏度、显示文字；草稿式「保存 / 取消」 |
| 🚀 轻量 | three.js 内联进 client bundle（gzip ≈124KB）；空闲降帧渲染，隐藏时零渲染 |

## 🚀 安装

```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 插件 → 大肥鱼桌宠 → 调大小 / 灵敏度 / 文字后点「**保存**」生效

## ⚙️ 设置项

| 设置 | 说明 |
|---|---|
| 启用开关 | 开 / 关虎鲸（修改后点保存生效） |
| 发送时翻跟头 | 发送消息时虎鲸翻一个 360° 跟头庆祝 |
| 大小 | 虎鲸窗口随大小缩放（0.2×–3×，鲸鱼始终完整可见） |
| 灵敏度 | 拖动旋转灵敏度（0.2×–5×） |
| 显示文字 | 虎鲸下方的自定义文字，留空隐藏 |

## 🗂️ 数据与安全

- 配置持久化在 `~/.dsh/dsh-ventus-whale/config.json`（原子写入 + fsync）
- API：`/api/ventus-whale/state | update | reset`（**loopback-only**，仅本机可访问）

## 🛠️ 开发

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

## 🐋 Ventus 系列插件

| 插件 | 说明 | 仓库 |
|---|---|---|
| 🐳 dsh-ventus-whale | 蓝色大肥鱼 · DeepSeek 虎鲸 3D 桌宠 | [GitHub](https://github.com/mmzm0808/dsh-ventus-whale) |
| 📊 dsh-deepseek-usage | DeepSeek API 用量监测（悬浮球 + 面板） | [GitHub](https://github.com/mmzm0808/dsh-deepseek-usage) |
| 🔍 dsh-ventus-search | 多引擎搜索与正文抓取（Bing / 360 / Bilibili） | [GitHub](https://github.com/mmzm0808/dsh-ventus-search) |

## 📄 许可证

MIT License · Copyright (c) 2026 Ventus

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

## ⭐ Star History

<p align="center">
  <img alt="Star History" src="https://api.star-history.com/svg?repos=mmzm0808/dsh-ventus-whale&type=Date">
</p>