前言¶

DeepSeek Harness（DSH）采用「一切皆插件」的理念，开发者可以通过插件扩展宿主能力。在开发或使用智能体时，长时间面对界面容易产生疲劳，需要一个实时反馈会话状态的陪伴对象。现有的会话状态往往只体现在输入框或工具调用提示中，缺乏持续的情感连接。dsh-plugin-pet 插件将电子宠物引入 DSH 桌面端，让 AI 智能体在思考、调用工具、报错、完成等状态时产生具体行为，同时提供一个独立的宠物管理页面与本地养成系统。

插件定位¶

dsh-plugin-pet 是运行在 DeepSeek Harness 0.2.1+（Web 与桌面端）的桌面电子宠物插件，由维护者 c-ling 开发。它通过实时会话状态驱动宠物心情动画，提供内置形象、自定义图片与 Codex 风格多帧精灵图，并内置本地陪伴养成系统。插件采用 bundle 安装方式，自动插入 loader 行，无需额外配置。

核心功能¶

实时心情浮层¶

宠物常驻页面右下角，通过 ctx.connection.fetch 注册的认证路由获取会话状态。宠物会根据以下状态改变表情与动作：

• 空闲：正常状态
• 思考：思考状态
• 工作中：气泡显示当前工具
• 报错：难过表情
• 等待你操作：等待状态
• 一轮完成：庆祝动作
• 长时间空闲：打瞌睡
• 连续工作：提醒喝水 / 休息 / 护眼

浮层支持拖动到任意位置（位置按浏览器记忆），拖动时朝移动方向播放奔跑动画。单击抚摸（增加经验与亲密度），双击隐藏（右下角保留爪印按钮可重新唤出）。支持 Tab 聚焦后 Enter / 空格抚摸。

独立宠物页面¶

设置不再是嵌入式面板，而是一个独立页面（main 插槽），从左下角头像菜单 → 宠物进入。页面包含固定页头、三页签（概览 / 外观 / 成长）、单一滚动区与固定页脚。切换页签不会跳页头，切页签会重置滚动位置，重新进入页面会回到「概览」并刷新配置。

页签内容¶

内置形象¶

插件提供 14 个内置形象（blob / cat / duck / robot / axolotl / ghost / panda / shiba / fox / bunny / penguin / frog / owl / slime），均为内联 SVG，纯 CSS 动画。每只都会眨眼，并随心情切换眼睛与嘴形。

自定义图片¶

支持 PNG / JPEG / GIF / WebP 格式，动图原样播放。上传后可在外观页签选择使用。

Codex 多帧精灵图¶

支持 Codex 风格精灵图，使用 pet.json + spritesheet.webp（V1 1536×1872、V2 1536×2288）或通用网格（列数 / 行数 / fps / 状态行 / 每行帧数）。

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）未使用。

本地养成系统¶

养成数据保存在本地状态目录，包括亲密度、等级、经验、心情分布、成就、每日在线与任务统计。所有写操作原子化并保留 .bak 备份。

数据与存储¶

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

HTTP 接口（认证 /api 桥）¶

插件通过零依赖 Fetch 适配层提供以下接口（需认证）：

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

安装与启用¶

推荐使用 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"

安装后需要重启宿主进程生效：Web 重启 dsh web，桌面端退出并重新打开应用；仅刷新页面不足以加载新包。

也可手动作为普通依赖安装，然后自行在 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）

典型用法¶

打开宠物页面¶

1. 点击左下角头像 → 菜单中的 宠物（位于「设置」下方）。
2. 页面包含三个页签：概览、外观、成长。
3. 在「概览」页签可以快速喂食 / 玩耍 / 抚摸宠物，这些操作会通过 POST /api/dsh-plugin-pet/stats/interaction 提交。
4. 在「外观」页签可以切换内置形象、上传自定义图片或导入 Codex 精灵图。
5. 在「成长」页签可以查看陪伴时长、互动次数、今日在线 / 任务、心情分布、成就。

导入 Codex 宠物包¶

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

通用精灵图¶

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

适用场景与注意¶

本插件适合需要在 DSH 桌面端有一个实时反馈会话状态的陪伴对象，用于改善长时间使用智能体的体验。

注意事项¶

• 目标运行时：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 会在首次读取时自动迁移。
• 每页只有一个全局宠物（根作用域浮层），不按会话区分。
• 宠物位置按浏览器 localStorage 保存，不跨设备同步。
• 头像菜单入口依赖对 shell 弹窗 DOM 的防御式增强；若官方后续提供菜单插槽会改为官方注册。
• 未实现 Codex「尾部空帧」自动检测；帧数来自规格默认值或显式配置。

插件以当前 dsh 进程权限运行，安装前应检查源码与许可证。

短结尾¶

dsh-plugin-pet 通过实时会话状态驱动宠物行为，为 DSH 开发者与用户提供了一个兼具实用性与趣味性的陪伴对象。其独立页面设计、本地养成系统与 Codex 精灵图支持，使其在保持轻量的同时具备较高的可扩展性。

• 插件目录页：https://www.skillhub.cn/plugins/c-ling/dsh-plugin-pet
• GitHub 仓库：https://github.com/c-ling/dsh-plugin-pet