s17179XTY/dsh-BigfishPet

dsh-BigfishPet — DeepSeek Harness 桌宠插件（鲸鱼娘 🐳）

这是针对 DeepSeek Harness 的通用桌宠插件，不是 Bigfish 应用或 DSH Desktop 的专属功能——Bigfish、DSH Desktop 都只是它运行于其中的壳。任何 DeepSeek Harness 环境只要执行一行 dsh plugin 命令即可安装：插件内置状态机 + 桌面 Helper（架构借鉴 dsh-dafeiyu），监听真实任务事件归约为 思考/工作/等待/完成/出错，通过 JSONL 协议驱动 PySide6 透明宠物窗口（runtime/helper.py）——窗口由插件自带并 spawn，与壳无关，装完即用。

桌宠原型来自 Bigfish（DeepSeek Harness 的第三方桌面壳），本插件把它插件化，成为 DSH 的一等公民：在 DSH 设置里直接调整，状态持久化、任务状态走真实信号。

这是什么

DeepSeek Harness 本身是 Web 后端 + 浏览器界面，没有创建桌面窗口的能力。本插件的 Host 跑在 DSH 后端里，监听标准 session/event 归约出真实状态，再 spawn 一个 PySide6 桌面 Helper（透明窗口）来显示鲸鱼娘：

| 部分 | 位置 | 职责 |
| --- | --- | --- |
| DSH 插件（通用，必装） | 仓库根目录（lib/、package.json） | DSH 设置里的「桌宠」页（显示/大小/气泡/活跃程度/走动冷却/减少动态/响应子 Agent/名字 等，即时保存）；状态存 ~/.dsh/pet.json。内置状态机（lib/companion-reducer.js）：session/event → 思考/工作/等待/完成/出错 + 阶段/待办/进度，输出 STATE/PULSE/TASK/TASKS 协议消息 |
| 桌面 Helper（自带，无需壳侧整合） | runtime/（PySide6）+ assets/（动画帧） | 透明置顶宠物窗口：大圆角状态卡、浅底深图形状态图标、程序化动作、拖动、右键 toggle 宿主、点击互动、空闲自动入睡。由插件 Host spawn，任何 DSH 环境都出现 |

功能

- 透明置顶窗口（WA_TranslucentBackground，Qt 合成透明，本机已验证），鲸鱼娘悬浮桌面，Bigfish 隐藏/最小化也不消失；
- 真实状态驱动：思考/工作/等待/完成/出错五态 + 阶段（查找/实现/验证/执行）+ 当前待办 + 真实进度（已完成 3/5 步，无待办数据不编造）；多任务时按 等待>出错>工作>思考 优先显示，≥2 个活跃会话时状态卡同时列出各任务；
- 动画随状态：THINKING/WORKING（跑任务）→ eat 吃东西动画（持续循环）；WAITING → sleep 打盹；SUCCESS → eat 庆祝；IDLE → idle 站立呼吸（待状态动作帧美术资源就位后可升级为每状态专属帧）；
- 空闲自动入睡：IDLE 持续 3 分钟无任务 → 自动切 sleep 睡觉动画（与走动互斥，入睡后不再响应走动；任务消息到来或点击宠物立即唤醒切回 idle）；可用环境变量 DSH_DAFEIYU_IDLE_SLEEP_MS 调整（毫秒）；
- 鲸鱼公主台词库（旧版恢复）：左键点击（摸头/尾巴/戳/双击）随机冒一句台词气泡；空闲时每 45–90 秒自言自语一句；
- 右键 = 打开/最小化宿主（无菜单）：自动检测宿主进程（Bigfish.exe / DSH Desktop.exe）——找到则最小化/还原其主窗口；找不到（纯 WebUI 模式）则打开 WebUI（http://127.0.0.1:3080/）；
- 状态卡气泡：常驻显示主文案 + detail 行（项目 · 已完成 x/y 步 · 当前待办），dsh-dafeiyu 同款大卡片（30px 圆角白卡 + 浅灰细边框 + 右侧状态图标 + 原版阴影）；显示规则由 bubbleMode 控制（常驻/隐藏/自定义状态）；
- 气泡贴住宠物：气泡底部按当前帧实际高度动态贴合宠物顶部（各状态帧高不同，不会离宠物过远）；
- 拖动换位置（回写 ~/.dsh/pet.json，设置页同步）；
- 设置页 dsh-dafeiyu 同款卡片式：每次改动即时保存，无「保存」按钮；底部只读展示当前状态机输出。

安装（一行命令）

插件是标准 DSH 插件，用 dsh plugin 命令安装（bundle 挂载）：

在任意目录执行；profile 用你要装的目标环境（如 web）
dsh plugin --profile web add github:s17179XTY/dsh-BigfishPet

装完后重启对应的 Harness 客户端：设置里出现「桌宠」卡片，桌面上出现鲸鱼娘（Helper 随插件启动，无需任何壳侧整合）。

⚠️ 不要再往 profile 的 cordis.patch.yml 里手动追加 - insert: id: bigfish-pet（前提是插件已通过 bundle 挂载）：bundle 挂载 + profile 级手动 insert 并存时，同一 entry 被应用两次，DSH 启动崩溃（duplicate loader entry id: bigfish-pet）。用 dsh plugin add（bundle 挂载）时，包内 cordis.patch.yml 自带 - insert 就是插件的 loader entry，profile 级不需要再写。

也可以手动复制 + 挂载（仅当目标环境不支持 dsh plugin 命令时）：

1) 克隆/下载本仓库，把插件部分复制进 profile 的 node_modules
$profile = "$HOME\.dsh\profiles\web"
git clone https://github.com/s17179XTY/dsh-BigfishPet.git
Copy-Item -Recurse dsh-BigfishPet "$profile\node_modules\bigfish-pet"
2) 若 profile 的 package.json 的 dsh.profile.bundles 没有 "bigfish-pet"，
在 profile 级 cordis.patch.yml 末尾追加（不是包内文件），并把包内
cordis.patch.yml 改为空 []（避免重复 insert）：
- insert:
- id: bigfish-pet
name: 'bigfish-pet'

插件会创建/读取 ~/.dsh/pet.json（宠物状态 + 配置）与 ~/.dsh/bigfish-completions.jsonl（完成标记，兼容旧壳）。

为什么安装后看不到宠物？（FAQ）

| 场景 | 结果 |
| --- | --- |
| 装了插件（dsh plugin 命令）+ 重启 DSH | ✅ 设置卡片 + 透明宠物窗口都出现（Helper 随插件启动） |
| 装了插件但没重启 | ⚠️ 重启前 Helper 未启动，没有宠物 |
| 目标环境缺 Python/PySide6 | ⚠️ 宠物窗口不出现（Helper 起不来）；设置页正常。可用 scripts/build-helper.ps1 打包 exe 随插件分发（不再依赖 Python） |

排查顺序：① 重启 DSH → ② ~/.dsh/pet.json 的 display.visible 是否为 true → ③ py -3 -c "import PySide6" 是否可用 → ④ 手动冒烟：在插件目录跑 py -3 runtime/helper.py（应出现宠物窗口）。改过动画/状态后 Helper 只在启动时读取 manifest，改动后需重启 Helper 才生效（可杀掉 Helper 进程，插件会自动重启）。

目录结构

├── AGENTS.md           # 给 AI 代理的项目说明（关键约定/验证方式/待办）
├── README.md
├── LICENSE             # MIT
├── package.json        # 插件包声明（dsh.bundle.patch + dsh.client）
├── cordis.patch.yml    # bundle insert（- insert: id: bigfish-pet）——插件的 loader entry
├── lib/
│   ├── index.js              # Host：/bigfish-pet/* 路由、pet.json、session/event → Helper、完成标记
│   ├── companion-reducer.js  # 状态机归约器（事件 → STATE/PULSE/TASK/TASKS 消息）
│   ├── status-copy.js        # 鲸鱼娘人设文案库（statusCopy/activityCopy/activityStage/taskCopy）
│   ├── protocol.js           # Helper JSONL 协议（hello/state/pulse/task/tasks/config/ping/shutdown）
│   ├── helper-process.js     # Helper 进程管理（spawn/心跳/崩溃重启/快照重放）
│   └── client.js             # Client：「桌宠」设置卡片（即时保存、当前状态只读区）
├── runtime/            # PySide6 桌面 Helper（helper.py + animation_model.py + layout_store.py）
├── assets/
│   ├── pet-manifest.json     # 动画清单（状态 → clip 映射；动作帧就位后升级）
│   └── pet/*.png             # 鲸鱼娘动画帧（idle/eat/sleep/walk）
├── scripts/
│   ├── build-helper.ps1      # PyInstaller 打包 Helper 为单文件 exe
│   └── gen-shapes.ps1        # （旧壳用）轮廓数据生成
└── bigfish/            # 旧 Electron 壳侧桌宠（已停用：main.js 的 DISABLE_ELECTRON_PET=true；保留作参考/回退）

致谢

- 桌宠原型来自 Bigfish（DeepSeek Harness 第三方桌面壳）；
- 状态机设计与状态展示借鉴 dsh-dafeiyu（MIT，QCYTSN）。

License

MIT