zouyuanqing / dsh-aemeath-pet

Aemeath Mini 桌宠 · DSH 插件

在 DSH 右下角养一只随 Agent 状态变换动作的 Q 版像素爱弥斯电子幽灵

✨ 特性

• 🎨 9 种状态动画 - idle / running / review / waiting / failed / celebrating / waving / jumping
• 🔄 实时状态同步 - 400ms 轮询 Agent 工作状态
• 🖱️ 完整交互 - 拖动移动 + 点击挥手
• 🎮 Codex V1 兼容 - 严格遵循 8×9 网格，192×208 像素规范
• 🔧 调试工具 - aemeath_pet_debug 查看内部状态
• 🌐 HTTP 资源服务 - 通过 webServer 提供精灵图
• 📡 RPC 通信 - pet-state 接口同步状态

📦 安装

方法一：通过 DSH 插件管理器安装（推荐）

1. 打开 DeepSeek Harness Web GUI
2. 进入 设置 → 插件管理
3. 点击 安装本地插件
4. 选择 dsh-aemeath-pet 目录
5. 启用插件并刷新页面

方法二：手动安装

# 克隆或复制本插件到 DSH 插件目录
cp -r dsh-aemeath-pet ~/.dsh/plugins/

# 重启 DSH
dsh web

方法三：通过 cordis.patch.yml 配置

在 ~/.dsh/cordis.patch.yml 中添加：

- id: dsh-aemeath-pet
  name: 'dsh-aemeath-pet'  # 使用包名，让 DSH 通过 package.json 解析

🎮 使用

状态说明

Agent 状态	桌宠动画	气泡文字
空闲	idle（待机呼吸）	休息中~ 有事叫我
执行工具中	running（墨镜工作）	努力工作中…
等待响应	review（思考）	思考中…
等待用户输入	waiting（屏幕幽灵）	在等你回复哦~
请求错误	failed（问号幽灵）	呜…出错了 (._.)
任务完成	celebrating（跳跃）	完成啦！✧。٩(ˊᗜˋ)و✧*。
点击互动	waving（挥手）	诶嘿~
拖动中	running-left/right	呜哇~ 别拽我！

交互操作

• 拖动：按住桌宠可拖动到任意位置
• 点击：单击桌宠触发挥手动画
• 自动：根据 Agent 状态自动切换动画

🏗️ 架构

本插件采用 DSH 标准的 Client/Host 分离架构：

dsh-aemeath-pet/
├── package.json          # DSH 插件元数据
├── lib/
│   ├── index.js          # Host 半：状态机 + 资源服务
│   └── client.js         # Client 半：React 渲染 + 动画 + 交互
└── assets/
    ├── spritesheet.png   # 精灵图（1536×1872，8×9 网格）
    ├── spritesheet.webp  # 精灵图 WebP 版本
    └── pet.json          # Codex 宠物元数据

Host 半（lib/index.js）

• 资源服务：通过 webServer 注册 HTTP 路由，向浏览器提供精灵图
• 状态机：轮询 agents 服务，推导桌宠状态
• 事件钩子：监听 tools/execute、approval/request、agent/request-error
• RPC 接口：提供 pet-state RPC 供 Client 同步状态

Client 半（lib/client.js）

• React 组件：注入 shell.overlay 插槽
• 精灵图动画：使用 background-position 切换帧
• 状态同步：400ms 轮询 host.call('pet-state')
• 交互处理：Pointer Events 实现拖动与点击

📐 精灵图契约

严格遵循 Codex V1 宠物规范：

• 网格尺寸：8 列 × 9 行
• 单元格尺寸：192×208 像素
• 总图尺寸：1536×1872 像素
• 行映射：
  • Row 0: idle（6 帧）
  • Row 1: running-right（8 帧）
  • Row 2: running-left（8 帧）
  • Row 3: waving（4 帧）
  • Row 4: jumping（5 帧）
  • Row 5: failed（8 帧）
  • Row 6: waiting（6 帧）
  • Row 7: running（6 帧）
  • Row 8: review（6 帧）

🔧 开发

调试工具

启用插件后，可在对话中使用：

aemeath_pet_debug

返回状态机内部信息：

{
  "mode": "idle",
  "seq": 42,
  "celebrating": false,
  "celebrateCount": 5,
  "workMarks": 128,
  "errorMarks": 2,
  "transitionsSeen": 15,
  "waitingCount": 0,
  "toolsInFlight": 0,
  "recentTool": false,
  "pollCount": 1024,
  "agentCount": 1
}

修改配置

编辑 lib/index.js 顶部的 CONFIG 对象：

const CONFIG = {
  spriteFile: 'spritesheet.png',
  routePath: '/aemeath-pet/spritesheet.png',
  pollMs: 400,           // 状态轮询间隔（ms）
  celebrateMs: 4800,     // 庆祝动画持续（ms）
  failedMs: 2600,        // 失败动画持续（ms）
};

🐛 故障排查

桌宠不显示

1. 确认插件已启用（设置 → 插件管理）
2. 检查浏览器控制台是否有错误
3. 确认 DSH Web GUI 已刷新

精灵图加载失败

1. 检查 assets/spritesheet.png 是否存在
2. 查看 DSH 启动日志：[aemeath-pet] spritesheet loaded: XXX bytes
3. 确认 HTTP 路由可访问：http://127.0.0.1:3080/aemeath-pet/spritesheet.png

状态不更新

1. 使用 aemeath_pet_debug 工具查看 pollCount 是否递增
2. 检查 agents 服务是否可用
3. 查看浏览器控制台网络请求是否成功

📚 参考资料

• OpenAI Codex Pets 规范
• DSH 插件开发指南
• liyupi/dsh-kun-like-pet - 标准 Client/Host 分离范式
• minybear/DeepSeek-Harness-Pet - 完整 Codex 契约实现
• cuNuo/aemeath-mini-codex-pet - 原始精灵图素材

📄 许可证

MIT License

🙏 致谢

• Aemeath Mini 精灵图：来自 cuNuo/aemeath-mini-codex-pet
• DSH 插件架构：DeepSeek Harness 团队
• Codex Pets 规范：OpenAI 社区

---

享受与爱弥斯一起工作的时光吧！ ✨👻