AgentCore-Light v1

让实体状态灯跟随 Claude Code、Codex 等 AI 工具的工作状态。支持 Windows、Mac 和 Linux；首次使用只需选择你的电脑系统并按下面操作。

开始前

1. 用支持数据传输的 Type-C 线连接状态灯和电脑。
2. 先不要粘贴双面胶；确认灯效和 AI 联动正常后再粘贴。

Windows / Linux：让 AI 帮你安装（推荐）

在 Claude Code、Codex、Cursor 等支持 Hook 的 AI 工具中，直接发送：

请根据 light.buildfpga.com/ai.txt 安装 AgentCore-Light。

AI 会按 安装指南 下载并校验程序、安装后台服务和对应 Hook。需要下载、安装或授权时，请根据提示确认操作。Linux 当前仅支持 x86_64 的 Ubuntu 20.04 及以上版本。

安装完成后，新建一个 AI 对话并发送一条普通消息；看到状态灯跟随变化，就可以粘贴双面胶了。

Mac：安装测试版

1. 下载 Mac 测试版。
2. 完整解压，将 AgentCore-Light.app 拖到“应用程序”。
3. 测试版第一次使用前，需要在“系统设置 → 隐私与安全性”中授权信任，详见 Mac 安装说明。
4. 打开 App，在本地控制台启动服务并测试灯效；再在“AI 接入”中安装你正在使用的 Hook。

详细步骤请看 Mac 安装说明。

Windows：不使用 AI 时手动安装

1. 下载 Windows 安装包并完整解压。
2. 双击 AgentCore-Light.exe，在打开的页面点击“启动服务”。
3. 确认设备已连接后，在“AI 接入”中安装你正在使用的 AI 工具 Hook；重启该 AI 工具并新建对话测试。

详细步骤请看 快速安装。

Linux：不使用 AI 时手动安装

1. 下载 Linux 安装包并完整解压（x86_64 的 Ubuntu 20.04 及以上，或其他带桌面环境的主流发行版）。
2. 终端进入解压目录，执行 chmod +x AgentCore-Light 和 ./AgentCore-Light，浏览器打开 http://127.0.0.1:18793。
3. 提示串口权限不足时，执行 sudo usermod -aG dialout $USER，注销并重新登录后再试。
4. 需要开机后台运行时，在解压目录执行 ./AgentCore-Light install。

详细步骤见安装包内 README.md 和 快速安装。

遇到问题

先确认 Type-C 线支持数据传输，再查看 常见问题。设备正常时不要随意刷固件。

二次开发

需要把 AgentCore-Light 集成到自己的软件、自动化脚本、监控系统或 AI Agent？查看 二次开发 API，包含本机 HTTP 接口、命令行工具和 Python / JavaScript 示例代码。