AgentCore-Light macOS 测试版说明

版本：v1.1.2

一、首次运行

1. 双击打开 AgentCore-Light-mac.dmg。
2. 将 AgentCore-Light.app 拖到 Applications。
3. 第一次运行请右键点击 Applications 里的 AgentCore-Light.app，选择“打开”。
4. 如果 macOS 提示无法验证开发者，请进入“系统设置 -> 隐私与安全性”，允许打开此 App。

二、测试状态灯

1. 插上 AgentCore-Light 状态灯。
2. 双击 AgentCore-Light.app。
3. 浏览器会自动打开 http://127.0.0.1:18793。
4. 等待设备区域显示已连接，端口通常类似 /dev/cu.usbmodem1101。
5. 点击 IDLE / THINKING / BUSY / SUCCESS / ERROR / WAIT_CONFIRM / OFF 测试灯效。
6. 拖动亮度滑块测试亮度。

三、AI 接入

1. 点击顶部“AI 接入”。
2. 安装 Claude Code 或 Codex Hook。
3. 请先确认 AgentCore-Light.app 已经拖入 Applications，再安装 Hook。
4. Hook 会调用 /Applications/AgentCore-Light.app/Contents/MacOS/AgentCore-Light 的 send 模式。
5. 重启对应 AI 工具后再验证状态灯变化。

四、登录后自启动

1. 打开控制台右上角“设置”。
2. 开启“开机自启动”。
3. macOS 会创建 LaunchAgent：
   ~/Library/LaunchAgents/com.buildfpga.agentcorelight.plist
4. LaunchAgent 会指向 /Applications/AgentCore-Light.app/Contents/MacOS/AgentCore-Light service。
5. 下次登录后会自动启动后台串口服务。

五、测试版安全提示

当前测试版没有 Apple Developer ID 签名和 notarization 公证。
macOS 第一次运行出现安全提示是正常现象。
正式发布版后续需要做 Apple Developer ID 签名和 notarization 公证。

六、排查

如果设备未连接，请更换 USB 数据线，或重新插拔 AgentCore-Light 状态灯。
客户不需要运行 build_macos.sh，不需要安装 Python，也不需要打开终端。

七、在线更新

控制台中的“检查更新”会读取：

https://light.buildfpga.com/v1-exe-json/latest.json

macOS 更新包是一个包含 `AgentCore-Light.app` 的 zip 文件。下载后程序会
自动校验 SHA-256，退出旧程序，替换 `/Applications/AgentCore-Light.app`，
再启动新版本。首次测试建议先把 App 放入 `/Applications`，否则 macOS
可能因应用目录没有写权限而无法自动替换。

八、在 Mac 上编译

在项目根目录执行：

```bash
python3 -m pip install -r requirements.txt
bash build/build_macos.sh
```

产物：

```text
dist/AgentCore-Light.app
release/AgentCore-Light-mac.dmg
release/AgentCore-Light-mac.zip
```

脚本会按照当前 Mac 的 CPU 架构构建。Intel 和 Apple Silicon 如果需要
同时发布，建议分别构建并确认依赖与签名策略。
