1475 字
7 分钟

At-Pet开发实录

文章目录

起因#

起因是术无之前搞Github-Copilot-Pet时候突发奇想,如果把这个项目成熟的的技术组合成一个独立项目

随后呢术无一拍脑袋,整合了一些朋友和我对象进行一系列开发和兼容

SHUWU

其实起名有一些小巧思,把All Agent Pet中的All Agent简写为At再加上Pet就有了At-Pet

怎么实现#

先说结论:At-Pet 没有去读任何 Agent 的内部会话数据,而是自己开了一个本地 HTTP 服务,Agent 那边通过 Hook、插件或者随便什么可信的本地程序把事件 POST 进来,桌宠根据事件切换动画。

Ni-ShuWu
/
At-Pet
Waiting for api.github.com...
00K
0K
0K
Waiting...
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_thinkingthinking
tool_start / tool_runningtool
tool_endthinking
权限或审批请求permission
workwork
review / reflectionreview
completed / donedone
cancelled / abortedcancelled
error / failederror

多个 sessionId 会被独立追踪,最近更新的非子代理会话驱动主宠物。设置了 isSubagent 或 parentSessionId 的子会话,在打开相应选项后会各自拥有一只独立的宠物。完成、取消、报错这类终态动画会先短暂显示,然后再交给下一个活跃会话或者待机状态。发送 idle 或 session_end 就会把会话移除。

这里有个容易被忽略的设计:At-Pet 不扫描 Agent 进程,也不读取机器相关的日志路径。所以没有接入的 Agent 不会自动出现动画,必须有一个集成主动把事件发过来。

四、权限请求:让桌宠替你按下确认#

Agent 要执行危险操作时,可以请求弹出权限对话框:

  1. POST /permission 发起请求,返回一个 requestId;
  2. 用户在弹窗里选择 Allow once 或 Deny,关闭弹窗也等同于拒绝;
  3. 通用集成通过 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 一行就能发一个事件:

Terminal window
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装插件

Ni-ShuWu
/
At-Pet_Agent-plugin
Waiting for api.github.com...
00K
0K
0K
Waiting...

六、局限#

  • 只支持 Windows:Linux 和 macOS 不在项目范围内;后续可以集成开发环境编译
  • 需要主动接入:At-Pet 不会自己感知 Agent 在干什么,每个 Agent 都得有一个集成去发事件;
  • 本地 API 没有鉴权:端口默认绑定在 127.0.0.1:8765,只适合同机的可信程序使用,千万不要暴露到网络上;
    • 喜欢玩内网穿透的小伙伴你们好啊
  • GitHub Copilot 需要外部发送器:窗口标题包含“Copilot”的窗口只能让桌宠朝它看,并不能同步 Copilot 的会话状态。