爱弥斯像素桌宠zouyuanqing/dsh-aemeath-pet

Aemeath Mini 桌宠 · DSH 插件

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

Version
License
DSH
Codex V1

✨ 特性

- 🎨 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 社区

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