Agent Halo

同时开很多个 AI 编程智能体时，用一个光环看清它们各自在做什么。

把 HALOFLUX 的节拍光环改造成 AI 智能体的实时监控画面：本机每个正在运行的智能体会话占光环的一段，思考、输出、调用工具、等待、出错，各有不同的动态效果。

状态：预览版。采集程序和 Wallpaper Engine 壁纸都已可用，正在作者本机日常使用。

写在前面：一个有点矛盾的项目

说实话，这个项目本身是矛盾的。

我想要的其实是一个监控工具：同时开着好几个 AI 编程智能体、跑着好几个项目的时候，能一眼看清每个对话在干什么、走到哪一步、有没有跑偏。但我一直没想到合适的界面形式，最后借了 HALOFLUX 的光环，把它做成了一张壁纸。

所以你现在看到的，是一个"长得像壁纸的监控工具"。它好看，但未必是监控多个对话的最佳形态。如果你有更好的想法，比如更清楚的布局、完全不同的交互，甚至推翻壁纸这个形式，非常欢迎一起来改。

顺带一提：这个项目本身就是用多个智能体协作做出来的（前端由 Factory Droid 编写，采集程序由 Codex 编写），开发过程中它一直在监控自己的开发过程。

它能做什么

1. 多个智能体、多个对话、多个项目，同屏实时可视化

• 每打开一个智能体会话，光环上就多一段，左侧同时多一张状态卡片。开了几个，就显示几个。
• 每个会话都能实时看到：
  • 哪个智能体、用的什么模型、在做哪个项目；
  • 现在是在思考、输出、跑工具还是等你确认，已经持续了多久；
  • 正在运行的工具和目标，比如 Execute · npm test、Edit · store.js；
  • token 用量、上下文占用和输出速度（输出速度取决于智能体是否记录，见下方支持列表）。
• 资源占用：采集程序空闲时 CPU 约 0.1%，内存约 66MB；壁纸在没有智能体运行时进入休眠，CPU 接近 0，被全屏程序遮挡时完全暂停。监控只读取本机会话记录；用户提交回答后，可通过已连接的 Codex 会话送达，或在后台任务退出后续接。
• 黄色问题行和对应外环可点击回答，支持多个问题、选项和自由输入；本机浏览器预览与 Windows 通知提供备用入口。详见 问题回答与设置。
• 内环或外环报错（工具失败的红 ×、本轮出错）会一直标红，直到你点开处理：快捷回复"重试 / 解释原因 / 换个方法 / 跳过继续 / 停下等我"或自由输入，能续接的会话直接送达，其余提供复制。详见 报错回复。

2. 比较炫的画面，但它是不是必要的，我们还没有答案

• 画面基于 HALOFLUX 的节拍光环。智能体调用工具、完成一个步骤时，光环会有对应的闪光。
• 三个场景可选：照片城市（默认）、赛博城市沙盘和原版光环。照片城市用六座真实建筑呈现会话状态，包含窗格光雕、进场光涌、塔冠光束、水面碎光和 3D 导播运镜；点击卡片或胶囊可查看会话与回复面板。运镜强度可选关闭、轻柔、标准和电影高能。详见 前端设计。
• 背景主题可选"星云深空"（默认，星云随节拍呼吸、偶尔划过流星）或原版深灰。
• 壁纸设置面板里可以选视觉预设、调节拍速度、柔光和光束辉光；preview/ 预览版还保留了原作者的完整调参控制台（按 C 打开）。
• 这样的画面到底让监控更直观，还是只是好看，我们现在还不确定。欢迎来 Issues 讨论：保留多少视觉效果合适，哪些信息最值得放在第一眼能看到的位置。

3. 实时复核每个对话的方向，是否符合你的预期

• 内环显示智能体走到了规划的第几步，比如 PLAN 3/6，以及当前步骤。
• 外环显示下一步打算做什么，以及整个规划的步骤列表。每个已完成的步骤都带反馈：耗时、工具调用次数、失败次数、改了哪些文件。
• 打开完整模式后，每一步还会附上智能体自己写的一句小结。
• 不用逐个切进对话窗口，扫一眼就能发现某个智能体是不是跑偏了、卡住了，或者在某一步反复失败，可以及时介入。

支持的智能体

规划步骤只对会写任务清单的智能体有效。不写规划的会话显示 NO PLAN，仍可以看到状态、工具和 token。

为什么还没支持另外一些客户端

能支持到什么程度，取决于这个客户端有没有把会话记录以可读的格式存在本机。目前的情况：

总结一句：不是不想支持，而是作者只能验证自己在用的工具。

一起来做

这个项目很需要你的帮助，包括但不限于：

• 验证适配器：如果你在用 Claude Code、Gemini CLI、Qwen Code、Kimi CLI 或 Copilot CLI，跑一下采集程序，告诉我们哪里不对。
• 新增客户端：给你常用的智能体写一个适配器。先看 事件协议，再参考 collector/src/adapters/ 里现有的实现，现有的适配器大多只有几十到一百多行。
• 改界面：现在的光环只是一种尝试。更清楚的信息布局、更适合监控的视图，甚至完全不同的形态，都欢迎提 Issue 或直接发 PR。
• 讨论：哪些信息最值得第一眼看到？视觉效果保留多少合适？欢迎到 Issues 里聊。

快速开始

Windows 安装版适用于通过 Steam 创意工坊使用 Agent Halo 的 Windows 10/11 x64 用户。在 GitHub Releases 下载 Collector 安装包，安装后从开始菜单打开 Agent Halo Collector 并启动。安装版附带运行时，登录自启动可选。详见 Windows 安装指南。

从源码运行

需要 Node.js 22.15 或更高版本（开发环境为 Windows 11 + Node 24），无需安装任何依赖。

仓库的视频资源使用 Git LFS。克隆前安装 Git LFS 并运行 git lfs install；已有克隆运行 git lfs pull 下载媒体。照片城市的完整页面和资源位于 wallpaper/photo/，主壁纸入口为 wallpaper/index.html。

1. 启动采集程序

# 推荐：开机自动在后台启动，不弹窗（只对当前用户生效，不需要管理员）
collector\autostart.cmd install     # 安装并立即在后台启动
collector\autostart.cmd status      # 查看状态
collector\autostart.cmd uninstall   # 取消自启并停止后台进程

# 或者手动启动
cd collector
node src/index.js            # 默认模式
node src/index.js --detail full   # 完整模式：显示每一步的小结文字

开机自启用的是配置文件里的设置。想让后台进程也用完整模式，在 %APPDATA%\haloflux-monitor\config.json 里写 { "detail": "full" }。

2. 安装壁纸（Wallpaper Engine）

把 wallpaper/ 整个目录复制到 Wallpaper Engine 的 projects\myprojects\ 下，例如：

$we = 'D:\SteamLibrary\steamapps\common\wallpaper_engine'   # 改成你的安装目录
Copy-Item -Recurse wallpaper "$we\projects\myprojects\agent-halo"

然后在 Wallpaper Engine 的"已安装"列表里选 Agent Halo。布局（侧弧 / 全环）、面板、帧率、清晰度、端口等都在壁纸的设置面板里调。更新时重新复制一次即可。

不装 Wallpaper Engine 也能看：浏览器打开 wallpaper/index.html，按 F11 全屏。加 ?demo=1 用内置模拟数据，加 ?debug=1 显示帧率。

preview/ 是早期的浏览器预览版，保留了原作者的调参控制台（按 C 打开）：双击 preview\start-preview.cmd 即可。

采集程序只监听 127.0.0.1:47821，不对外开放。更多参数和配置项见 collector/README.md。

隐私

看起来像密钥的字符串会被替换为 [redacted]。

项目结构

想给新的智能体写适配器，见上方 一起来做。

致谢与许可

• 画面和渲染引擎来自 HALOFLUX，作者 Ryder191（RYDER CODE / Ms MAIKEBAIs CAT）。
• 本项目是 HALOFLUX 的衍生作品，沿用 PolyForm Noncommercial License 1.0.0：可以自由使用、修改、分享，但不能用于任何商业用途。详见 LICENSE 和 NOTICE。