convez.ai
Agente
whalesky-labs

AgentLight

whalesky-labs/AgentLight

Ver no GitHub
InicialPluginScore · de 0 a 100

AgentLight 是一个基于 ESP32-C3 的桌面 AI 状态灯项目。它通过 USB 串口、Bluetooth LE 和 Wi-Fi HTTP 接收状态命令,把 Codex、Claude Code、Cursor、Gemini、Qwen、opencode 等 AI Agent 工作流的执行状态显示到玩具红绿灯上。

Instalação

$npx convez-ai whalesky-labs/AgentLight

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
5
Forks
3
Acompanhando
0
Saúde
37%
Último commit
há 1 mês
Versão
v1.2026.288+52
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

简体中文 | English

AgentLight

AgentLight 是一个基于 ESP32-C3 的桌面 AI 状态灯项目。它通过 USB 串口、Bluetooth LE 和 Wi-Fi HTTP 接收状态命令,把 Codex、Claude Code、Cursor、Gemini、Qwen、opencode 等 AI Agent 工作流的执行状态显示到玩具红绿灯上。

当前仓库包含两部分:

  • ESP32-C3 固件:负责接收命令并控制红 / 黄 / 绿灯
  • 无客户端桥接层:通过 shell 脚本和 AI 工具 Hook 发送状态命令,不需要桌面 GUI App

完整使用说明见 docs/user-guide.md,包含硬件接线、固件烧录、设备验证、后台服务启动和 AI 工具接入。

硬件

  • ESP32-C3 SuperMini
  • 玩具红 / 黄 / 绿灯
  • 220R 限流电阻

默认接线:

ESP32-C3 引脚连接
GPIO4220R -> 红灯正极
GPIO5220R -> 黄灯正极
GPIO6220R -> 绿灯正极
GND三个灯共用负极

如果玩具灯是共阳接法,把 platformio.ini 里的 AGENTLIGHT_ACTIVE_LOW=1,并把共用正极接到 3V3。

命令

通过 USB 串口发送一行命令、向 BLE RX 特征写入同样文本,或者通过 Wi-Fi HTTP API 发送命令。

命令协议使用纯文本,一次发送一条命令:

  • USB 串口:以 \n 或 \r\n 结尾
  • BLE:向 RX 特征写入命令文本
  • Wi-Fi:访问 HTTP API
  • 命令不区分大小写,固件会统一转换为大写处理
  • 成功切换状态时返回 OK <STATE>
命令结果
GREEN绿灯亮,红灯 / 黄灯灭
GREEN_BREATHE绿灯呼吸
GREEN_BLINK绿灯闪烁
YELLOW黄灯常亮,红灯 / 绿灯灭
YELLOW_BREATHE黄灯呼吸
YELLOW_BLINK黄灯闪烁
RED红灯常亮,黄灯 / 绿灯灭
RED_BLINK红灯闪烁
RED_BREATHE红灯呼吸
OFF全部熄灭
PING返回 PONG
STATUS返回当前灯光状态
HELP返回支持的命令列表

响应示例:

GREEN_BREATHE -> OK GREEN_BREATHE
YELLOW_BLINK  -> OK YELLOW_BLINK
STATUS        -> STATUS YELLOW_BLINK
PING          -> PONG

BLE 设备名:WHALESKY-LABS-AGENTLIGHT

系统蓝牙列表展示名:AGENTLIGHT

BLE 默认启用配对 / 绑定,配对码:

521000

这是 ESP32-C3 的 BLE GATT 连接,不是经典蓝牙串口 SPP。固件默认启用标准 HID 配对外壳,主广播包使用 AGENTLIGHT 短名称、标准 Keyboard 外观和 HID 服务,让电脑和手机的系统蓝牙列表更容易展示并发起配对;扫描响应保留完整设备名 WHALESKY-LABS-AGENTLIGHT。HID 外壳只用于系统发现和配对,不会发送键盘按键;真正的灯光控制仍通过 AgentLight 自定义 RX / TX GATT 服务完成。首次读取 TX 特征、订阅通知或写入 RX 特征时会触发配对,配对成功后才能发送 PING、STATUS、YELLOW_BLINK 等命令。

BLE 服务与特征:

项目UUID
服务8f16d7a0-6c6d-4d68-8d64-6b4d2a86b601
RX 写入8f16d7a1-6c6d-4d68-8d64-6b4d2a86b601
TX 通知 / 读取8f16d7a2-6c6d-4d68-8d64-6b4d2a86b601

Wi-Fi HTTP

固件默认启动一个 Wi-Fi AP:

配置默认值
SSIDWHALESKY-LABS-AGENTLIGHT
密码agentlight
网关地址192.168.4.1

HTTP API:

方法路径说明
GET/查看可用接口
GET/status查询当前状态
GET/command?cmd=GREEN发送命令
POST/command通过 plain text body 发送命令

测试示例:

curl "http://192.168.4.1/status"
curl "http://192.168.4.1/command?cmd=YELLOW_BLINK"
curl -X POST "http://192.168.4.1/command" --data "GREEN_BREATHE"

SSID 和密码可以在 platformio.ini 中通过 AGENTLIGHT_WIFI_AP_SSID 和 AGENTLIGHT_WIFI_AP_PASSWORD 修改。

脚本桥接

第二阶段不做桌面客户端 App,而是通过 scripts/agentlight 直接向设备发送命令。默认使用 Wi-Fi HTTP。

scripts/agentlight status
scripts/agentlight yellow-blink
scripts/agentlight green
scripts/agentlight red-blink

脚本支持别名:

输入实际命令
busy / running / toolYELLOW_BLINK
thinking / generatingYELLOW_BREATHE
idle / ready / done / successGREEN
waiting / confirm / blockedRED_BLINK
error / failedRED

可配置环境变量:

变量默认值说明
AGENTLIGHT_HOST192.168.4.1设备 HTTP 地址
AGENTLIGHT_BASE_URL空完整基础 URL,优先级高于 host
AGENTLIGHT_TIMEOUT2curl 超时时间,单位秒

后台 Agent 服务

电脑端推荐做成后台 Agent 服务,而不是桌面 App:

系统形态
WindowsWindows Service Agent
macOSLaunchAgent
Linuxsystemd user service

统一服务入口是 scripts/agentlight-agent,安装脚本位于 service/windows 和 service/macos。启动和排查步骤见 docs/user-guide.md。

事件 Gate

scripts/agentlight-gate 用来承接 AI 工具生命周期事件,将事件映射为灯光状态,并在短时间窗口内抑制完全重复的事件,避免同一状态被连续重复发送。

scripts/agentlight-gate start
scripts/agentlight-gate tool
scripts/agentlight-gate thinking
scripts/agentlight-gate done
scripts/agentlight-gate waiting
scripts/agentlight-gate error
事件灯效
startYELLOW_BLINK
toolYELLOW_BLINK
thinkingYELLOW_BREATHE
doneGREEN_BLINK
waitingRED_BLINK
errorRED

AI Hook 集成

第三阶段不做 GUI 客户端,优先通过 Hook 接入:

Claude Code、Gemini CLI、Qwen Code、opencode、Copilot CLI、Kimi、CodeBuddy、Kiro、Antigravity、OpenClaw、Hermes、Pi 等平台统一走多 Agent 入口或通用 wrapper,不再为每个平台维护重复模板文档。

完整平台兼容矩阵见 docs/agent-platform-compatibility.md。矩阵会区分“已实现监听器 / Hook 模板 / 通用 wrapper 接入”,避免把通用入口写成已经完成的原生集成。

所有平台最终都调用同一个归一化入口:

scripts/agentlight-event --agent <agent> --event <event> --send

当前统一入口支持这些 Agent 名称:

平台支持方式
Codex CLI / Desktopsession 文件监听 + 统一事件入口 + wrapper 文档
Claude Code统一事件入口 + hook/wrapper 文档
Cursor AgentCursor Hook 模板
Gemini CLI / Qwen Code / GitHub Copilot CLI / opencode通用 wrapper 入口
Kimi / CodeBuddy / Kiro / Antigravity / OpenClaw / Hermes / Pi通用事件入口 + wrapper 文档,等待具体工具 hook 接入
ChatGPT Desktop / Claude Desktop暂无稳定公开 hook;可通过外部自动化或未来适配接入统一事件入口

说明:AgentLight 不做桌面宠物、托盘面板、Dashboard、权限气泡或终端聚焦;这些仍由原 AI 工具或其他桌面客户端处理。本项目只负责把可观察到的 Agent 状态同步到硬件红黄绿灯。

Codex 也支持通过本地 session 文件进行只读监听。这个方式适合先验证“Codex 工作状态能不能被观察到”,不直接控制硬件:

scripts/codex-session-monitor --thread-id "$CODEX_THREAD_ID" --from-start
scripts/codex-session-monitor --once --limit 20

监听器会把 Codex session JSONL 记录归一化为:

输出状态来源示例
promptuser_message
thinkingtask_started / reasoning
workingfunction_call / web_search_call
typingagent_message / message
successtask_complete
errorturn_aborted

如果要把多个平台的日志/命令输出接入统一事件流,可以使用配置化监听器:

scripts/multi-agent-monitor --config config/agent-monitors.example.json
scripts/multi-agent-monitor --config config/agent-monitors.example.json --send

配置文件支持:

  • file 类型:tail 文本日志或 JSONL 日志
  • command 类型:运行一个命令并读取 stdout
  • rules:用 contains / equals / json_path 把平台输出映射到统一事件

状态约定

状态灯效含义
OFF全灭未连接 / 关闭
GREEN绿灯常亮空闲,可开始新任务
GREEN_BREATHE绿灯呼吸已连接,待命中
GREEN_BLINK绿灯闪烁任务完成提示 / 心跳测试
YELLOW黄灯常亮AI 正在执行普通任务
YELLOW_BREATHE黄灯呼吸AI 正在长时间思考 / 生成
YELLOW_BLINK黄灯闪烁工具调用 / 命令执行中
RED红灯常亮错误
RED_BLINK红灯闪烁需要人工确认 / 阻塞
RED_BREATHE红灯呼吸低优先级提醒 / 等待查看

灯效时序

灯效固件行为
常亮目标颜色持续点亮,其他颜色熄灭
闪烁800ms 周期,亮 400ms / 灭 400ms
呼吸2000ms 周期,亮度从低到高再回落

当前呼吸效果使用软件 PWM 实现,不需要额外硬件。对于玩具灯或普通 LED,220R 电阻仍然需要串联在 GPIO 与 LED 之间。

架构

AgentLight/
├── src/
│   ├── domain/                 命令、颜色、灯效与状态模式模型
│   ├── application/            状态灯业务用例,负责命令处理与当前状态维护
│   ├── infrastructure/         GPIO / USB 串口 / BLE / Wi-Fi HTTP 通道实现
│   └── main.cpp                固件装配入口,连接业务层与硬件通道
├── agentlight_agent/
│   ├── domain/                 桌面 Agent 领域模型:监听器、规则、运行模式
│   ├── application/            平台选择、监听编排、服务运行用例
│   ├── infrastructure/         JSON 配置、路径解析、事件发送、监听执行器
│   └── interfaces/             CLI 适配层,承接 scripts 入口
├── scripts/
│   ├── agentlight              无客户端命令桥接入口
│   ├── agentlight-gate         AI 事件到灯光状态的映射与重复事件抑制
│   ├── agentlight-event        多 Agent 事件归一化入口
│   ├── agentlight-agent        后台 Agent 服务兼容入口
│   ├── codex-session-monitor   Codex session 文件状态监听器
│   └── multi-agent-monitor     多 Agent 配置化监听兼容入口
├── hooks/                      AI 工具 Hook 模板与接入说明
├── service/
│   ├── windows/                Windows Service Agent 安装脚本
│   └── macos/                  macOS LaunchAgent 安装脚本
├── config/
│   ├── agent-monitors.example.json      监听器示例配置
│   ├── agentlight-agent.example.json    后台 Agent 服务示例配置
│   └── agent-platforms.json             AI Agent 兼容平台清单
├── tests/                      桌面 Agent 分层与配置行为测试
├── docs/                       使用说明、兼容性、代码规范与协议说明
├── platformio.ini              ESP32-C3 SuperMini 固件构建配置
└── CHANGELOG.md                中文版本发布说明

项目代码规范见 docs/code-standards.md。

分层原则:

  • domain 不直接访问硬件,只定义状态与命令协议
  • application 不关心 USB、BLE、Wi-Fi 或 GPIO 细节,只处理业务语义
  • infrastructure 承担硬件 IO、串口、BLE 和 Wi-Fi HTTP 适配
  • main.cpp 只负责对象装配和主循环调度
  • agentlight_agent/domain 定义桌面端监听模型,不读取文件或启动进程
  • agentlight_agent/application 负责平台选择、多会话策略和服务编排
  • agentlight_agent/infrastructure 负责配置文件、文件监听、子进程和事件发送
  • agentlight_agent/interfaces 只处理 CLI 参数和输出,scripts 保持向后兼容

服务运行策略:

  • 服务启动时只监听一个 activePlatform
  • 支持通过 scripts/agentlight-agent platform set <platform> 切换平台
  • 同一平台内支持多项目、多会话
  • 多会话不聚合、不轮播,采用 latest-event-wins
  • 哪个会话最后产生状态事件,灯光就显示哪个会话的状态

构建与烧录

本项目使用 PlatformIO + Arduino framework。

pio run
pio run -t upload
pio device monitor

如果看不到 USB 串口,请确认:

  • 已安装 PlatformIO 的 ESP32 平台
  • USB 线支持数据传输,不只是充电线
  • platformio.ini 中已开启 ARDUINO_USB_CDC_ON_BOOT=1

CI 固件构建

GitHub Actions 会在 main 分支推送、Pull Request、v* 标签和手动触发时构建固件包。

固件版本号规则:

场景版本号来源
推送 v* tag使用 tag 名称,例如 v1.2026.051+1775834670
手动触发并填写 version使用填写的版本号
普通 push / PR自动生成 v1.<Year>.<DayOfYear>+<GITHUB_RUN_NUMBER>,末尾构建号由 CI 自动递增

发布版本使用 CalVer:

字段规则示例
展示版本<Major>.<Year>.<DayOfYear> (<BuildNumber>)1.2026.051 (1775834670)
Git tagv<Major>.<Year>.<DayOfYear>+<BuildNumber>v1.2026.051+1775834670
短版本<Major>.<Year>.<DayOfYear>1.2026.051
构建号<BuildNumber>1775834670

构建通道:

通道说明
stable正式构建,Release 不标记为预发布;推送 v* tag 时默认使用
preview预览构建,Release 标记为预发布;普通 push / PR / 手动触发默认使用

CI 会生成并发布这些独立资产,不再额外打包 zip:

  • firmware.bin
  • bootloader.bin
  • partitions.bin
  • manifest.json
  • firmware-assets.sha256

固件使用 Arduino ESP32 内置的 huge_app.csv 分区方案,面向 4MB Flash 的 ESP32-C3 SuperMini,单个 App 分区大小为 3MB,用于容纳 USB、BLE、Wi-Fi 三通道一体固件。

manifest.json 包含版本、构建通道、Git 提交、SHA256 和烧录 offset。版本发布说明维护在 CHANGELOG.md,CI 会读取当前版本号对应的中文章节;如果没有对应章节,则读取 Unreleased 章节,并自动追加构建通道、构建环境、Git 提交、构建时间和资产清单。推送 v* tag 或手动触发时勾选发布,会自动创建 GitHub Release 并把生成后的发布说明写入 Release body。

预览构建不会默认创建 GitHub Release,但 CI 会把从 CHANGELOG.md 读取并生成的 Release body 输出到构建日志和 GitHub Actions Summary,便于直接查看本次版本更新说明;该 Release body 只作为 CI 临时内容,不作为固件资产发布。

桥接层验证

多 Agent 桥接层可以用内置脚本验证:

scripts/verify-agent-bridge

它会检查:

  • shell 脚本语法
  • Codex session monitor Python 语法
  • 多 Agent 名称归一化
  • 生命周期事件归一化
  • hooks 文档目录是否完整
  • 多 Agent monitor 示例配置是否可加载

开源协议

AgentLight 使用 MIT License 开源,SPDX 标识为 MIT。

中文优先的协议说明见 docs/license.md。协议原文以根目录 LICENSE 为准。

Ver o original no GitHub

Bom para

Relacionados