qiqibabyy/dsh-pet-desktop

DeepSeek Harness 桌面宠物插件 — 把 Codex 桌宠完整移植到 DSH 桌面上。

一个自包含的 DSH（DeepSeek Harness）插件：harness 启动时自动在你的桌面上养一只帧动画桌宠。它不依赖网页端桌宠，自带状态机、文案引擎与宠物注册表，直接订阅 harness 会话事件。

功能

• 🖥️ 桌面常驻：无边框、置顶、透明智能穿透可切换（开启后拖不动、摸不到、滚轮无效，唯独右键仍能唤出菜单关掉它，永不自锁）；右键菜单（收起/召唤、缩放、鼠标穿透、退出）；互动栏（名字/亲密度/喂食/改名）只在轻点她时出现，路过或悬停不打扰
• 📌 贴边拖拽：光标 1:1 跟手 + 触边吸附——撞上屏幕边的那刻钉住，回拉鼠标不会把她带离（重新按住才走）。气泡与设置卡随边自动翻向：左右贴边时向内生长，顶贴边时降到脚下，任何位置都不会被屏幕裁掉
• 🎬 Codex 宠物格式原生支持：宠物文件夹直接拷进 ~/.codex/pets 即用，自动发现 ~/.dsh/pets 与包内 assets/pets（pet.json + spritesheet.webp），9 条标准轨道（idle / running-right / running-left / waving / jumping / failed / waiting / running / review）+ 每宠物 tracks/sequences 覆盖
• 💬 活动气泡：直接监听 harness 会话事件，投影为 waiting / thinking / tool / review / done / failed 六相位；389 条内置中文文案按 4s 轮转，工具碎碎念（「」小气泡）带 9s/5s 冷却与 8s 上屏时限；多会话气泡栈 + +N 角标
• 💕 亲密度系统：摸头 +1（10s 冷却）、喂食 +5（消耗 1 小鱼干，30s 冷却）、完成对话 +1（按会话轮次幂等）；小鱼干每 30 轮 +1、每 5 小时 +1、上限 20；亲密度永不衰减
• 🐋 装扮：内置小鲸鱼陪伴装饰层（随相位播放帧段），设置页可换/可关
• 📈 今日 token 用量：轻点卡片与设置页实时显示当天 tokens（输入/输出/缓存分桶 + 调用次数，本地零点归零，重启不丢）；已安装 dsh-usage 时自动改用其当日台账——与用量面板同源同口径
• 📊 用量公告回显：若同时安装了网页端 dsh-pet/dsh-usage，余额/套餐公告会镜像到桌宠（纯回显，无依赖）
• ⚙️ 设置页集成：harness Web 设置 →「桌面宠物」：自动启动、状态与立即启动/停止、窗口控制（置顶/鼠标穿透/收起召唤/大小滑杆）、带精灵缩略图的宠物选择卡、装扮选择、electron 路径。鼠标穿透随时可在本页关回来——不存在救不回来的锁死

安装

需要 DSH Desktop（或任何带 web server 的 harness 宿主）。

dsh plugin --profile web add @qiqibabyy/dsh-pet-desktop
# 本地开发：
dsh plugin --profile web add link:../dsh-pet-desktop

Electron 运行时按以下顺序查找（任一命中即可）：

1. 设置页「electron 路径」字段
2. 环境变量 DSH_PET_ELECTRON
3. 本包 node_modules/electron/dist/electron.exe（在包目录 npm i electron 过）
4. 全局 npm：%APPDATA%/npm/node_modules/electron（Windows）

找不到 Electron 时，设置页会红字提示；装一个 npm i -g electron 即全部解决。

宠物与装扮

宠物文件夹格式见 assets/pets/README.md。同名 id 后者覆盖前者，发现顺序：

1. 本包 assets/pets/
2. ${CODEX_HOME:-~/.codex}/pets/ — Codex 原生目录
3. ${DSH_HOME:-~/.dsh}/pets/ — 用户目录（装扮也扫这里的 decorations/）
4. 插件配置 petDirs 列出的额外目录

renderer: live2d / frames2d 的宠物按设计跳过（本插件渲染 sprite2d 图集）。

从 Codex 移植宠物

零转换直接拷：把 Codex 的宠物文件夹（pet.json + 图集）整个放进 ~/.codex/pets/<id>/ 即被自动发现（CODEX_HOME 环境变量同样生效）。宠物定义兼容 Codex 两代 manifest——旧版扁平格式（hatch-pet）与 v2 sprite2d 块。换宠物不用碰命令行：harness 设置 →「桌面宠物」→ 形象分组，缩略图卡片点选，桌宠即时换装。

段位（亲密度点数）

点数 ≥	段位	星迹
0	幼鲸	*
25	伙伴	**
50	挚友	***
80	深海羁绊	****
200	心有灵犀	*****
500	传说羁绊	******
2000	神话羁绊	*******
10000	永恒之契	********
100000	鲸生共渡	*********

开发

npm install            # 只有 schemastery 一个运行时依赖
node scripts/smoke.mjs # 无宿主烟测：注册表 / 账本 / 文案引擎 / 事件投影

目录结构：

路径	作用
index.js	插件装配（cordis host 半边）
src/service.js	状态机 + 亲密度账本 + 事件投影（~/.dsh/desktop-pet.json 原子持久化）
src/chatter.js	文案引擎（389 条，逐条移植自 dsh-pet，Apache-2.0）
src/registry.js	宠物与装扮发现（Codex v1/v2 manifest 兼容）
src/routes.js	/api/desktop-pet/* loopback 路由（含图集/装扮静态资产）
src/supervisor.js	Electron 伴生窗口的查径、启动、接管、守护
client.js	设置页卡片（模块宿主 CJS 工厂格式，免构建）
companion/	Electron 伴生窗口（主进程 + 渲染层，零 npm 依赖）
assets/decorations/	内置装扮（whale，MIT，见其 LICENSE.txt）

许可

• 代码：Apache-2.0（见 LICENSE）
• src/chatter.js 文案池与 assets/decorations/whale 装扮衍生自 dsh-web @linxin666/dsh-pet （代码 Apache-2.0；whale 装扮按其清单声明为 MIT）
• 桌宠交互概念与宠物格式向 Codex Desktop Pet 致敬