At-Pet开发实录
文章目录
起因
起因是术无之前搞Github-Copilot-Pet时候突发奇想,如果把这个项目成熟的的技术组合成一个独立项目
随后呢术无一拍脑袋,整合了一些朋友和我对象进行一系列开发和兼容
SHUWU其实起名有一些小巧思,把All Agent Pet中的All Agent简写为At再加上Pet就有了At-Pet
怎么实现
先说结论:At-Pet 没有去读任何 Agent 的内部会话数据,而是自己开了一个本地 HTTP 服务,Agent 那边通过 Hook、插件或者随便什么可信的本地程序把事件 POST 进来,桌宠根据事件切换动画。
Agent(Claude Code / OpenCode / 其他) │ Hook / 插件 / HTTP POST ▼127.0.0.1:8765 ── 多会话状态管理 │ ├──▶ GET /events(SSE 推送状态) └──▶ 桌宠窗口(透明、无边框、置顶)一、桌面窗口:Qt 6 + C++17
技术栈是 C++17 加 Qt 6(Widgets 和 Network 模块),用 CMake 构建,目前只支持 Windows 10/11(amd64 和 ARM64)。
桌宠本体是透明、无边框、始终置顶的窗口:
- 拖动可以移动,单击冒一句台词,双击输入文字让它说话,右键打开控制菜单;
- 可以在屏幕上自由游走,也可以开启重力:拖拽后松手会下坠,甩出去时带着拖拽的动量,碰到屏幕边缘会反弹;
- 拖拽、甩动、重力都会保证桌宠始终完全在屏幕内。
系统托盘负责显示/隐藏、导入宠物、一键召唤全部宠物,以及切换简体中文和英语,默认跟随系统语言并记住选择。
二、宠物格式:pet.json + 精灵图
每只宠物就是一份 pet.json 加一张精灵图(sprite sheet),每一行是一个动画,每一行里的帧从左到右排列:
{ "name": "Sample Cat", "sprite": "spritesheet.png", "cell": [128, 128], "scale": 1.5, "fps": 8, "defaultAnimation": "idle", "animations": { "idle": { "row": 0, "frames": 4 }, "walk": { "row": 1, "frames": 4 }, "thinking": { "row": 2, "frames": 4 }, "tool": { "row": 3, "frames": 4 }, "sleep": { "row": 4, "frames": 4 }, "work": { "row": 5, "frames": 4 }, "review": { "row": 6, "frames": 4 }, "done": { "row": 7, "frames": 4 }, "cancelled": { "row": 8, "frames": 4 }, "error": { "row": 9, "frames": 4 } }}几个值得注意的点:
- 每个动画可以单独设置
fps(1–30),不写就用全局的; - 向左、向右走可以分别配
walkLeft/walkRight,没有就回退到walk; - 还兼容
row_counts写法、起止帧区间和显式帧索引; - 在设置窗口里可以逐个动画调速,这些偏好存在应用设置里,不会改你导入的
pet.json; pet.json、精灵图和宠物文件夹都会被监听,改完即时生效,不用重启。
宠物库保存在 %APPDATA%\Ni-ShuWu\At-Pet\pets 下。内置的默认宠物直接打包在程序里,不需要导入;如果内置资源不可用,会退回到程序自带的矢量宠物。
三、事件驱动:怎么决定桌宠做什么
Agent 发来的 event 会被映射成统一的状态:
| 上报的 event | 桌宠状态 |
|---|---|
thinking / model_thinking | thinking |
tool_start / tool_running | tool |
tool_end | thinking |
| 权限或审批请求 | permission |
work | work |
review / reflection | review |
completed / done | done |
cancelled / aborted | cancelled |
error / failed | error |
多个 sessionId 会被独立追踪,最近更新的非子代理会话驱动主宠物。设置了 isSubagent 或 parentSessionId 的子会话,在打开相应选项后会各自拥有一只独立的宠物。完成、取消、报错这类终态动画会先短暂显示,然后再交给下一个活跃会话或者待机状态。发送 idle 或 session_end 就会把会话移除。
这里有个容易被忽略的设计:At-Pet 不扫描 Agent 进程,也不读取机器相关的日志路径。所以没有接入的 Agent 不会自动出现动画,必须有一个集成主动把事件发过来。
四、权限请求:让桌宠替你按下确认
Agent 要执行危险操作时,可以请求弹出权限对话框:
POST /permission发起请求,返回一个requestId;- 用户在弹窗里选择 Allow once 或 Deny,关闭弹窗也等同于拒绝;
- 通用集成通过
GET /permission/{requestId}轮询结果,结果只能被消费一次。
对于可能危险的操作,弹窗会根据启发式规则给出视觉警告,但警告只是提示,不会改变可选的两个按钮。请求不会超时,也不会自动拒绝。At-Pet 本身从不执行任何工具,它只负责弹窗和把决定传回去。
五、原生集成
Claude Code:在 Claude Code 的设置里为 UserPromptSubmit、PreToolUse、PostToolUse、PermissionRequest、Stop、SubagentStart 等事件配置 HTTP Hook,地址都指向 http://127.0.0.1:8765/agent-event/claudecode。PermissionRequest 这个 Hook 会一直挂起,直到用户点击允许或拒绝,然后把结果原样返回给 Claude Code。
OpenCode V2:把仓库里的 integrations/opencode-v2/at-pet.ts 放进项目的 .opencode/plugins/ 目录,或者全局的 %USERPROFILE%\.config\opencode\plugins\,重启 OpenCode 即可。插件会转发会话和工具事件,并把 ask 类型的权限决定交给 At-Pet 处理。如果 At-Pet 没有运行,OpenCode 保持原有的 ask 行为。
其他 Agent:走通用的 HTTP API 就行,比如 PowerShell 一行就能发一个事件:
Invoke-RestMethod http://127.0.0.1:8765/event -Method Post ` -ContentType 'application/json' ` -Body '{"sessionId":"session-1","event":"tool_start","message":"Running tests"}'此外还有一个可选的 MCP stdio 桥接,但它只会在被显式调用时上报事件,不像 Hook 和插件那样自动观察生命周期或者也可以选择给Agent装插件
六、局限
- 只支持 Windows:Linux 和 macOS 不在项目范围内;后续可以集成开发环境编译
- 需要主动接入:At-Pet 不会自己感知 Agent 在干什么,每个 Agent 都得有一个集成去发事件;
- 本地 API 没有鉴权:端口默认绑定在
127.0.0.1:8765,只适合同机的可信程序使用,千万不要暴露到网络上;喜欢玩内网穿透的小伙伴你们好啊
- GitHub Copilot 需要外部发送器:窗口标题包含“Copilot”的窗口只能让桌宠朝它看,并不能同步 Copilot 的会话状态。