dsh-plugin-pet

dsh-plugin-pet

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

English

宠物常驻页面右下角，实时响应会话状态（思考 / 调用工具 / 报错 / 完成 / 等待你操作）；设置不再是嵌入式面板，而是一个独立页面（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 / 状态行 / 每行帧数）。
• 本地养成：亲密度、等级、经验、心情分布、成就、每日在线与任务统计，全部保存在本机。

结构

本包是双面插件：宿主半边是普通 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，桌面端退出并重新打开应用；仅刷新页面不足以加载新包。

使用

打开宠物页面

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

页面包含四个页签：

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

浮层

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

数据与存储

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

• 修订号：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 桥）

所有写路径都在服务端校验：魔数嗅探（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 且不加值。

浏览器 <img> 直接访问这些 /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