桌面电子宠物 c-ling/dsh-plugin-pet

dsh-plugin-pet

DeepSeek Harness 0.2.1+（Web 与桌面端）的桌面电子宠物插件：由实时会话状态驱动心情动画，支持内置形象、自定义图片与 Codex 风格多帧精灵图，并带本地陪伴养成系统。

宠物常驻页面右下角，实时响应会话状态（思考 / 调用工具 / 报错 / 完成 / 等待你操作）；设置不再是嵌入式面板，而是一个独立页面（main 插槽），从左下角头像菜单 → 宠物进入，布局与「黄金看板 / 快讯看板」一致。

- 双端一致：同一份客户端 bundle 运行在 Web 与桌面端（Electron），只依赖 /api 认证桥与 --dsw-alias- 主题 token。
- 独立页面：固定页头、三页签（概览 / 外观 / 成长）、页签行内的保存动作、单一滚动区与固定页脚；切页签不会跳页头。
- 头像菜单入口：在左下角账号弹窗里注入「宠物」项（0.2.1 没有菜单扩展插槽，插件以防御式 DOM 增强实现，并用 data-signed-out 与中英文 aria-label 双重识别账号菜单）。
- 14 个内置形象（blob / cat / duck / robot / axolotl / ghost / panda / shiba / fox / bunny / penguin / frog / owl / slime，内联 SVG，纯 CSS 动画），每只都会眨眼，并随心情切换眼睛与嘴形。
- 自定义图片（PNG / JPEG / GIF / WebP；动图原样播放）。
- Codex 多帧精灵图：pet.json + spritesheet.webp（V1 1536×1872、V2 1536×2288，见 Codex pet package spec），或通用网格（列数 / 行数 / fps / 状态行 / 每行帧数）。
- 本地养成：亲密度、等级、经验、心情分布、成就、每日在线与任务统计，全部保存在本机。

结构

| 文件 | 作用 |
| lib/index.js | 宿主插件：配置 / 成长持久化 + 通过 ctx.connection.fetch 注册的认证路由 |
| lib/connection-routes.js | 零依赖 Fetch 适配层：405、请求体上限、错误信封与 Request / Response 转换 |
| lib/client.js | 浏览器 bundle（手写 factory-CJS，无构建步骤）：浮层、独立页面、头像菜单入口 |
| cordis.patch.yml | bundle 层的 loader 行 |
| test/ | node --test：宿主 Fetch 路由、配置迁移、并发修订号、客户端槽位 / 页面渲染 / 菜单增强 |

本包是双面插件：宿主半边是普通 Cordis 插件；客户端半边由
"dsh": { "client": { "platform": "web", "inject": [], "immediately": true } } 加
"./client" 导出声明，由 client-modules 在启动时立即加载。

兼容性

- 目标运行时：DeepSeek Harness 0.2.1+（engines.dsh: >=0.2.1-rc.2 <0.3.0-0），桌面端与 Web profile 同一套代码。
- 1.x（DSH 1.0.7）的 settingsScope / currentProvideInfo / webServer 裸路由已全部移除；旧的扁平 config.json 会在首次读取时自动迁移。

安装

推荐按 bundle 安装（dsh.bundle + cordis.patch.yml 会插入 loader 行）：

Web（推荐 bundle 模式；自动插入 loader 行）
npx @deepseek-ai/dsh plugin --profile web add "github:c-ling/dsh-plugin-pet#v2.0.0"
dsh plugin --profile web add "github:c-ling/dsh-plugin-pet#v2.0.0"

桌面端（由 Desktop 自带的 CLI 或「插件」页面管理）
dsh plugin --profile desktop add "github:c-ling/dsh-plugin-pet#v2.0.0"

本包带 dsh.bundle + cordis.patch.yml，dsh plugin add 会把它作为 bundle 层安装并自动插入 loader 行，不需要再手写；重启宿主后生效。

也可手动作为普通依赖安装，然后自行在 profile 的 cordis.patch.yml 中添加同一行（不要同时使用 bundle 与手写行）：

cd ~/.dsh/profiles/web
corepack pnpm add "github:c-ling/dsh-plugin-pet#v2.0.0"

- insert:
- id: dsh-plugin-pet
name: 'dsh-plugin-pet'
config:
maxImageBytes: 5242880 # 可选：单张图片上限（默认 5 MB） maxSheetBytes: 10485760 # 可选：精灵图上限（默认 10 MB） interactionCooldownMs: 1500 # 可选：互动冷却毫秒（默认 1500，0 关闭） maxDailyInteractions: 500 # 可选：每日互动计次上限（默认 500） directory: "" # 可选：自定义状态目录（默认 storages/dsh-plugin-pet）安装后重启宿主进程（client-modules 按进程缓存包裁决）：Web 端重启 dsh web，桌面端退出并重新打开应用；只刷新页面不足以加载新包。

使用

打开宠物页面

- 点击左下角头像 → 菜单中的 宠物（位于「设置」下方）。

页面包含四个页签：

| 页签 | 内容 | 保存 |
| 概览 | 当前形象与心情、等级 / 亲密度、名字 / 大小 / 显示开关、快速喂食 / 玩耍 / 抚摸 | 页签行内「保存」，只提交本页字段 |
| 外观 | 内置形象、自定义图片、Codex / 通用精灵图、心情预览 | 页签行内「保存」，只提交外观 |
| 成长 | 陪伴时长、互动次数、今日在线 / 任务、心情分布、成就 | 只读，无保存动作（页签行高度保持不变） |

页头、页签行与页脚固定，只有中间内容滚动；切换页签会重置滚动位置，重新进入页面会回到「概览」并刷新配置。

浮层

- 拖动宠物到任意位置（位置按浏览器记忆）；拖动时朝移动方向播放奔跑动画。
- 单击抚摸（爱心 + 经验）；双击隐藏，右下角保留爪印按钮可重新唤出；支持 Tab 聚焦后 Enter / 空格抚摸。
- 心情由实时状态推导：空闲、思考、工作中（气泡显示当前工具）、难过（出错）、等待（等你确认）、一轮完成时的庆祝；长时间空闲会打瞌睡，连续工作会提醒喝水 / 休息 / 护眼。
- 成就解锁与升级会在浮层上方弹出提示。

数据与存储

状态目录：$DSH_HOME/storages/dsh-plugin-pet/（可用 config.directory 覆盖）。

| 文件 | 内容 |
| config.json | { version: 1, revision, config: { name, size, visible, sprite } }；目录 0700、文件 0600 |
| config.json.bak | 每次成功写入的同步备份 |
| stats.json / stats.json.bak | 陪伴成长统计；主文件损坏时从 .bak 恢复 |
| image.<ext> / sheet.<ext> | 上传的图片 / 精灵图原始字节 |

- 修订号：GET /api/dsh-plugin-pet/config 返回 revision；POST 可带 expectedRevision，不匹配时返回 409 { code: "stale-config", config, revision }，客户端会采纳最新配置并提示重试，避免多标签页互相覆盖。
- 1.x 迁移：旧的扁平 config.json（顶层 name/size/visible/sprite）在首次读取时保留精灵图描述并改写成 2.x 信封；image. / sheet. 与 stats.json 原样继续使用。

HTTP 接口（认证 /api 桥）

| 方法 | 路径 | 用途 |
| GET | /api/dsh-plugin-pet/config | 当前配置 + revision |
| POST | /api/dsh-plugin-pet/config | 局部更新名字 / 大小 / 可见性 / 内置形象 / 精灵图 fps、状态行、帧数；支持 expectedRevision |
| GET/POST/DELETE | /api/dsh-plugin-pet/image | 读取 / 上传原始字节 / 删除自定义图片 |
| GET/POST/DELETE | /api/dsh-plugin-pet/sheet | 读取 / 上传（?source=codex&version=1\|2\|auto 或 ?source=custom&cols=&rows=&fps=）/ 删除精灵图 |
| POST | /api/dsh-plugin-pet/petjson | 导入 Codex pet.json（要求已有尺寸匹配的精灵图） |
| GET | /api/dsh-plugin-pet/stats | 陪伴成长统计 |
| POST | /api/dsh-plugin-pet/stats/heartbeat | 页面在线心跳（陪伴时长、在线时长、心情采样） |
| POST | /api/dsh-plugin-pet/stats/interaction | 喂食 / 玩耍 / 抚摸，返回经验与亲密度增益 |
| POST | /api/dsh-plugin-pet/stats/task | 完成任务成长 |
| POST | /api/dsh-plugin-pet/stats/event | 客户端检测到的成就事件（连续工作 / 修复错误） |

所有写路径都在服务端校验：魔数嗅探（PNG / JPEG / GIF / WebP）、大小上限、Codex 精确尺寸、通用网格整格切分；配置与统计写入原子化并保留 .bak。

错误响应带稳定机器码（{ ok: false, code, error, params? }，如 bad_json / too_large / codex_size / grid_uneven / stale-config），由客户端按当前语言翻译。成长类响应额外携带 unlockedKeys 与 levelUp；interaction 超出冷却或每日上限时返回 throttled: true 且不加值。

浏览器 直接访问这些 /api 资源也带签名会话 Cookie，因此 Web 与桌面端表现一致。

Codex 精灵图导入

1. 宠物页面 → 外观 → 精灵图 → 导入 Codex 宠物包。
2. 先上传 spritesheet.webp / spritesheet.png：必须是 1536×1872（V1，9 行） 或 1536×2288（V2，11 行），8 列网格、每格 192×208；版本自动检测。
3. 可选导入 pet.json，应用 displayName 并校验 spriteVersionNumber 与已上传精灵图一致。

Codex 行 → DSH 心情：idle→0、run_right→1、run_left→2、pet→3（waving）、happy→4（jumping）、sad→5（failed）、waiting→6、working→7（running）、thinking→8（review）、sleeping→0（复用 idle）。V1 九行动作全部启用；仅 V2 的朝向行（9/10）未使用。

通用精灵图

外观 → 精灵图 → 通用精灵图：任何宽高能被网格整除的 PNG / WebP 都可用。设置列数、行数、fps，上传后为每个心情分配行号与帧数；页面内提供实时预览。

开发与验证

node --check lib/index.js lib/client.js lib/connection-routes.js
node --test # Node >= 24：直接 node --test
python3 -m json.tool package.json
git diff --check

- 客户端 bundle 是 shell 的 factory-CJS 格式（window.__ModuleLoader__.load({ id, factory })）；require("react") / require("react-dom") 由 shell 静态模块表提供，ui-primitives 缺失时自动降级为原生元素。
- 页面 UI 使用 --dsw-alias- token 与官方密度（20/28 标题、14/22 正文、12/18 提示、32px 输入、36px 按钮、44px 页签行）；macOS 桌面端页头让出 --dsh-frame-top-clearance。
- 服务端测试用 new Request(...) 直接调用注册的 Fetch 处理器，断言注册键必须是 /api/...；客户端测试在 new Function 沙箱中加载 bundle，断言 factory id、inject、槽位、三页签、每页动作栏、live 状态投影与头像菜单注入。

已知限制

- 每页只有一个全局宠物（根作用域浮层），不按会话区分。
- 未实现 Codex「尾部空帧」自动检测；帧数来自规格默认值或显式配置。
- V2 精灵图的朝向行（9/10）未使用。
- 宠物位置按浏览器 localStorage 保存，不跨设备同步。
- 头像菜单入口依赖对 shell 弹窗 DOM 的防御式增强；若官方后续提供菜单插槽会改为官方注册。

License

MIT