Z-Buddy 🐾

ZCode 桌宠 —— 悬浮在桌面上的 AI 编程伙伴：状态可视化 · 电脑操作协同 · GLM 对话气泡

🌐 官网（下载 / 文档 / 宠物画廊）：https://learnercodez.github.io/Z-Buddy/（站点源码在本仓库 website/ 目录）

🚧 项目状态：立项与调研完成，开发尚未启动（Phase 0 技术验证待跑）。欢迎 Star 围观，Issue 区畅聊想法。

---

这是什么

一只挂在桌面角落的像素小宠物。你用 ZCode 干活时，它实时反映 Agent 的状态：干活时打字、出错时沮丧、完成时庆祝、深夜冒 Zzz 气泡睡觉——对标 OpenAI Codex 的 Pet Mode，但为 ZCode 而生。

它不只是状态动画。Z-Buddy 的野心是成为 Agent 在物理世界的化身：

• 🔍 看得见：ZCode 操控你的电脑时（无障碍后台操作），桌宠用点击动画 + 目标元素高亮框 + 气泡旁白把"隐形操作"演出来；
• 🤝 能协作：你随时可以接管——帮它点两步，停手后它自动接上（人机接力协议：让位 → 交接 → 复位）；
• 💬 会聊天：点一下宠物，直接和 GLM 对话。它知道你刚跑了个失败的任务，说话像活的，不像挂皮聊天机器人；
• 📋 可查询：鼠标悬停展开后台任务面板——有哪些任务、进行到第几步、等不等你审批，一目了然。

为什么做

缺口	现状
生态缺口	Codex 有桌宠且有 4600+ 社区宠物包的生态；ZCode 官方没有桌宠功能
信任缺口	ZCode 的电脑操作多为无障碍后台执行，屏幕上什么都看不到
协调缺口	人机同时操作电脑时，没有任何"用户优先"的门控机制

功能规划

功能	状态	说明
状态动画（idle/running/failed/完成/深夜睡觉）	🔜 P1	对齐 Codex Pet Mode
悬浮窗（置顶/拖动/多显示器）	🔜 P1	Electron / Tauri（待选型实验）
宠物包格式兼容 Codex hatch-pet	🔜 P1	直接接入 4600+ 存量宠物生态
/zpet 斜杠命令	🔜 P2	唤醒/切换宠物
hatch 技能：GLM 生成宠物包	🔜 P2	对标 hatch-pet，无需 Pro 订阅
电脑操作可视化（高亮框 + 旁白）	🔜 P2	隐形操作显形
GLM 对话气泡（点击聊天）	🔜 P2	直连 GLM-Flash，本地零落盘
后台任务气泡（悬停展开）	🔜 P2	任务列表 / 状态 / 审批入口
权限审批桌面卡片	🔜 P3	对标 clawd 的 Ctrl+Shift+Y/N
人机接力（帮点两步，接得上）	🔬 P3	依赖暂停机制验证
子代理多宠物可视化	🔬 P3	一个子代理一只小宠物

架构（规划）

┌──────────────────────────┐         ┌──────────────────────────────┐
│  ZCode 插件 (z-buddy)     │         │  Z-Buddy 桌宠应用（独立进程）  │
│                          │         │                              │
│  hooks ── 生命周期事件     │──HTTP──▶│  悬浮窗（置顶/无边框/可拖动）   │
│  skill ── 宠物包生成      │  /文件   │  精灵图播放器（状态→动画行）    │
│  MCP ──── 操作权证(设想)  │         │  聊天气泡（直连 GLM API）      │
│                          │         │  后台任务面板                  │
└──────────────────────────┘         └──────────────────────────────┘

📐 插件侧目录结构完全遵循 ZCode 官方模板插件 Example Plugin 的推荐布局（.zcode-plugin/plugin.json manifest + hooks/hooks.json + Skills + MCP 预留位），与官方插件市场规范保持一致，为上架做好准备。

路线图

• Phase 0 · 技术验证（当前阶段）：hooks 事件流实测、打断行为实验、暂停机制原型、Electron/Tauri 选型对拼
• Phase 1 · MVP：对齐 Codex 桌宠体验，插件 + 应用可一键安装
• Phase 2 · 生态与可视化：hatch 技能、宠物包导入、操作可视化、任务气泡
• Phase 3 · 护城河：人机接力、审批卡片、子代理多宠物、养成系统

原则

1. 无侵入：桌宠挂了绝不能影响 ZCode 正常工作（Hook 静默降级）；
2. 隐私：聊天历史只存内存不落盘；数据只在用户主目录，永不进项目文件夹；
3. 版权：自带宠物全部原创；宠物包格式兼容开放格式，但分发渠道拒绝 IP 侵权内容；
4. 透明：AI 在干什么，用户永远看得见。

相关生态

• Petdex —— Codex 宠物分发平台（4600+ 宠物）
• clawd-on-desk —— 通用 Agent 桌宠（本项目的架构参考与敬意来源）
• ZCode / GLM —— 本项目依托的编程工具与模型

⚠️ Z-Buddy 是独立的个人开源项目，与 Z.ai / 智谱无隶属关系。

License

代码计划采用 MIT（发布前确定）；自带宠物美术资产版权归项目所有、禁止再分发为 IP 衍生物。