# dsh-pet-whale 功能全览

> 一只陪伴你处理 DeepSeek Harness（DSH）任务的像素蓝鲸。本文只讲**有什么功能、每个功能有哪些可调参数、每个操作会触发什么反应**；不涉及实现细节。
>
> 除非特别说明，所有功能在「页面内模式」和「桌面悬浮模式」下行为一致。

---

## 目录

1. [两种存在形态](#1-两种存在形态)
2. [任务感知与提醒](#2-任务感知与提醒)
3. [任务操作](#3-任务操作)
4. [互动动作与对应反应](#4-互动动作与对应反应)
5. [状态情绪反应](#5-状态情绪反应)
6. [空闲行为](#6-空闲行为)
7. [全屏漫游](#7-全屏漫游)
8. [参数总表](#8-参数总表)
9. [自定义宠物](#9-自定义宠物)
10. [脚本控制（Companion API）](#10-脚本控制companion-api)
11. [语言、主题与无障碍](#11-语言主题与无障碍)
12. [可靠性与生命周期](#12-可靠性与生命周期)

---

## 1. 两种存在形态

| 形态 | 说明 |
| --- | --- |
| **页面内模式** | 鲸鱼悬浮在 DSH 网页内部，随页面滚动停在角落，只能在浏览器窗口范围内活动。 |
| **桌面悬浮模式**（实验性） | 鲸鱼脱离 DSH，悬浮在**整个电脑**之上：任意应用、任意全屏 Space 都在其上。鲸鱼本体区域接收鼠标操作，**其余区域完全鼠标穿透**，不影响你使用任何软件。 |

- 两种形态**互斥显示**：开启悬浮模式后，页面内的鲸鱼自动隐藏；关闭后立刻回来。
- 悬浮模式由 DSH 自带的运行时驱动，宿主退出后悬浮鲸会自动退出，不留僵尸窗口。
- 悬浮模式不可用的环境（找不到运行时）会在设置页明确提示。

**相关参数**：`桌面悬浮模式` 开关（见参数总表）。

---

## 2. 任务感知与提醒

鲸鱼实时盯着你的 DSH 会话，任务有四种状态，各有专属表现：

| 状态 | 什么时候出现 | 鲸鱼的表现 | 提醒表现 |
| --- | --- | --- | --- |
| **运行中** (running) | 任务正在执行 | 划水姿态；若开启漫游则在整页/整屏游走 | 通知卡片（可停止） |
| **等待你处理** (waiting) | 工具需要审批、或向你提问/请求确认计划 | 上下蹦跳约 5 秒 + 「需要你处理：{任务名}」气泡 | 通知卡片，**可直接在卡片内处理** |
| **出错** (failed) | 任务报错 | 快速左右发抖约 4 秒 + 头顶火焰闪烁 | 通知卡片（保留 1 小时） |
| **完成** (review) | 任务跑完 | **胜利巡游**（见第 5 节），无任何气泡 | 无（巡游本身就是通知） |

**通知托盘**（页面内）：

- 多个任务时只显示最重要的一条，其余折叠为「还有 N 个会话」，点开全量列表；
- 支持两种排序切换：**待处理事项优先**（默认）/ **最新活动优先**；
- 每条提醒可以手动关闭（点 ×），关闭的提醒可随时**一键恢复**；
- 漫游时托盘**跟随鲸鱼移动**，不钉死在角落；
- 等待类提醒保留 24 小时、出错类 1 小时；完成类不再出现卡片（由胜利巡游代替）。

**相关参数**：无直接参数（行为固定），但受 `漫游`、`桌面悬浮模式` 影响。

---

## 3. 任务操作

不用切回对应会话，在鲸鱼的通知卡片上可以直接：

| 操作 | 说明 |
| --- | --- |
| **打开任务** | 点卡片正文，跳转到对应会话 |
| **停止当前轮次** | 运行中的任务卡片上有停止按钮 |
| **批准 / 拒绝工具** | 审批请求在卡片内展开，一键「允许一次」或「拒绝」 |
| **回答提问** | 单选题 / 多选题 / 自由文字回答都在卡片内完成，含完整校验（漏答、非法选项、超长、单选多投都会被拦下并提示） |
| **确认计划** | 计划确认与提问同一套交互 |

所有操作都有防呆：任务状态已变化、请求已被处理、重复点击都会得到明确报错而不是静默失败。

---

## 4. 互动动作与对应反应

| 你的动作 | 鲸鱼的反应 |
| --- | --- |
| **单击**（点住不拖） | **摸摸头**：开心地挥手 + 身体压扁再弹回（约 0.9 秒）+ 头顶冒出 3 颗上浮消散的爱心 |
| **双击** | **跳一跳**：专属跳跃动画 |
| **按住拖动** | 顺从地跟着手走（朝向随移动方向切换），松手后位置被记住；松手时若没拖动则视为摸头 |
| **抓住摇晃** | **喷水表演**：从头顶喷水孔喷出像素水柱，水珠自由落体、在屏幕底部堆积、摊平、渐隐消失。触发条件极宽松：拖动中方向翻转 2 次，或一次拖动累计 700px。连摇连喷，边拖边喷也不错位——喷点实时跟着鲸鱼走 |
| **右键** | 打开菜单（见下表） |
| **键盘 Enter** | 等效摸摸头；Escape 关闭菜单 |

**右键菜单**：

| 页面内模式 | 桌面悬浮模式 |
| --- | --- |
| 打个招呼 | 摸摸头 |
| 摸摸头 | 跳一跳 |
| 跳一跳 | 游回原位 |
| 恢复已关闭通知（有时） | 收起悬浮鲸（= 关闭悬浮模式） |
| 查看任务（有关联任务时） | |
| 宠物设置 | |
| 收起宠物 | |

菜单顶部始终有一行状态读数：`v1.1.0 · 漫游中/返回中/已就位 · 距原位 Npx`——既当版本标记，也让"游回家"这件事可见。

---

## 5. 状态情绪反应

任务状态变化时，鲸鱼会**主动表演**（边沿触发，不重复刷屏）：

| 事件 | 表演 |
| --- | --- |
| **任务出错** | 快速左右发抖约 4.2 秒，头顶右侧一团小火焰摇曳闪烁，与抖动同生同灭 |
| **需要你审批 / 回答** | 上下蹦跳约 5 秒 + 弹出「需要你处理：{任务名}」气泡（即使通知托盘在展示也强制弹） |
| **任务完成** | **胜利巡游**：鲸鱼缓缓游向页面顶端（顶端留有余量，水柱不会溢出屏幕）→ 从左上角出发横渡到右侧，**一路上持续喷水**，屏幕底部积出一条随行的水带 → 游完后自动返回原位恢复常态。全程约 15–20 秒 |
| **新任务开始** | 立即中止进行中的庆祝巡游，切换回工作状态 |

所有表演尊重系统「减少动态效果」偏好：开启后抖动/蹦跳/火焰/喷水/爱心全部自动关闭，只保留必要的文字提示。

---

## 6. 空闲行为

- **待机动画**：没有任务时播放专属的 Idle 动画（眨眼、摆尾）；
- **自娱自乐**：每隔约 18 秒，随机来一次挥手或跳跃（仅空闲态、页面可见、非拖动时）；
- **眼神跟随**：空闲时鲸鱼的眼珠会跟着你的鼠标转，**16 个方向**精确注视；页面内跟随页面内鼠标，悬浮模式下跟随全屏鼠标；
- **悬停打招呼**：鼠标划过鲸鱼时挥挥手。

---

## 7. 全屏漫游

- **触发条件**：有任务处于运行中，且漫游开关已开启；
- **自动巡航**（v1.2.0 新增）：即使没有任务，鲸鱼也会按「巡航频率」不定期离家巡游——沿平滑弧线游 20~40 秒、途中偶尔喷水，然后回家。频率可在设置中调节（0 关闭）；巡游期间拖拽或打开菜单会暂停；
- **彩蛋**（v1.2.1 新增）：3 秒内连点鲸鱼 7 次以上，它会**立刻自己出发巡游一次**——不受巡航频率设置限制，巡游完回家；
- **行为**：鲸鱼离开原地，以平滑的弧线在整页/整屏内自由游走（随机目标 + 有界转向，撞边反射，不会瞬移、不会抖动）；
- **结束行为**：任务结束（或出错/完成）后，鲸鱼以你设定的速度**游回初始位置**，到位后停下，不会停在半路；
- 漫游期间拖拽、打开菜单会暂停；漫游**不会改写**你保存的位置，回家即恢复；
- 漫游速度可调（见参数总表），速度同时用于"游回家"。

**相关参数**：`任务运行时全屏漫游` 开关、`漫游速度` 滑杆。

---

## 8. 参数总表

所有参数有三个调节渠道：**设置页**（设置 → 宠物 → 外观）、**右键菜单**（部分）、**脚本 API**（见第 10 节）。页面内修改后，悬浮窗约 1.5 秒内自动同步。

| 参数 | 范围 / 取值 | 默认 | 设置页控件 | 说明 |
| --- | --- | --- | --- | --- |
| `selected` 选择宠物 | 内置 + 自定义宠物 | 内置蓝鲸 | 宠物列表「选择」按钮 | 切换形象；所选宠物被删除时自动回退到可用宠物并提示 |
| `visible` 显示宠物 | 开 / 关 | 开 | 「收起宠物 / 显示宠物」按钮、右键菜单 | 隐藏时悬浮模式也会一并关闭 |
| `size` 宠物大小 | 64 – 224 px（步进 4） | 120 | 滑杆，右侧实时显示 `Npx` | 页面与悬浮窗共用 |
| `roam` 全屏漫游 | 开 / 关 | 关 | 开关 | 仅任务运行时生效 |
| `roamSpeed` 漫游速度 | 8 – 240 px/s（步进 4） | 48 | 滑杆，显示 `Npx/s`（漫游关闭时置灰） | 同时决定游回家的速度 |
| `overlay` 桌面悬浮模式 | 开 / 关 | 关 | 开关 | 悬浮鲸的右键菜单也可关闭它 |
| `spoutAmount` 喷水量 | 1 – 8 波 | 3 | 滑杆，显示 `N×` | 每次触发摇晃喷出的水柱波数；也影响胜利巡游的喷水节奏 |
| `spoutPower` 喷水高度 | 50 – 200 % | 100 | 滑杆，显示 `N%` | 水花喷射的高度与距离 |
| `patrolEvery` 巡航频率 | 0 – 30 分钟（步进 5） | 15 | 滑杆，显示 `N min` / `已关闭` | 鲸鱼不定期自动全屏巡游（约 20–40 秒，途中偶尔喷水）的间隔；0 为关闭 |
| 位置 | 0–1 归一化坐标 | 右下角 | 直接拖拽保存 | 页面内与悬浮窗**各自独立记忆**，互不干扰 |

非法值在服务端被拒绝（如大小越界、喷水量超范围），设置页会显示错误提示，配置不会被破坏。

---

## 9. 自定义宠物

- 把符合 **Codex 8 列动画协议** 的宠物目录（`spritesheet.png` + `pet.json`）放进宠物目录，设置页点「刷新」即可选用；
- 宠物目录可用设置页的「打开文件夹」按钮一键直达（默认 `~/.dsh/pet-whale/pets`）；
- 内置**生成 Skill**：设置页点「创建」，用自然语言描述想要的宠物，插件会在 DSH 新会话里按协议生成并安装（需要该会话具备图像生成工具）；
- 自定义宠物与内置蓝鲸可随时切换；所有宠物数据都在插件目录之外，升级重装不影响。

---

## 10. 脚本控制（Companion API）

页面加载后，`window.dshPetWhale` 暴露一套完整的脚本接口，可以：

- 读取宠物、配置和**全部任务通知的实时快照**（含审批/提问的完整内容）；
- 订阅状态变化；
- 执行第 3 节的全部任务操作（打开/停止/批准/拒绝/回答/关闭/恢复/排序）；
- 修改**第 8 节参数表中的所有参数**；
- 打开设置对话框；
- 接管屏幕显示权（自绘宠物外观）。

参数修改与设置页完全等效，悬浮窗同样自动同步。完整接口文档见 [companion-api.md](companion-api.md)。

**结论：第 2–8 节的一切能力和参数都是开放可编程的。**

---

## 11. 语言、主题与无障碍

- **双语**：界面跟随 DSH 语言设置（中文/英文），含所有菜单、按钮、气泡与错误提示；
- **主题**：颜色取自 DSH 主题变量，深色/浅色模式自动适配；
- **无障碍**：宠物按钮、菜单、托盘控件均有完整的 aria 标注与焦点环；键盘可完成摸头（Enter）、开菜单（Menu 键 / Shift+F10）、关菜单（Escape）；所有动画尊重系统「减少动态效果」设置。

---

## 12. 可靠性与生命周期

- **配置安全**：所有写入走原子替换 + 服务端校验，坏配置不会落盘；
- **悬浮窗守护**：宿主通过心跳看门狗管理悬浮窗——失联回收、意外退出自动重拉；宿主退出后悬浮窗 6 秒内自杀，不留僵尸鲸；
- **可观测**：悬浮窗输出记录在 `~/.dsh/pet-whale/overlay.log`；
- **数据隔离**：宠物与配置数据在 `~/.dsh/pet-whale/`，与插件本体、其他插件完全隔离，卸载不丢数据；
- **版本豁免提醒**：DSH 按 `插件名@版本` 记兼容豁免，升级版本后需重新授权一次（详见 FORK.md）。

---

*文档对应版本：dsh-pet-whale v1.1.0（2026-10-04）。功能变化请对照 CHANGELOG.md。*