# RedGreenSign 小白使用指南

这是一套 AI 工作状态灯。你拿到的硬件已经烧录好程序，不需要自己写代码，也不需要安装 Node.js。

## 你会收到什么

- 一个 ESP32-C3 状态灯硬件
- 一个 Mac 安装包：`RedGreenSign-macos.dmg`

## 灯光含义

- 绿灯常亮：空闲，或 AI 任务已经完成
- 黄灯闪烁：AI 正在执行任务
- 红灯常亮：AI 正在等待你授权
- 灯全灭：你手动停止了状态灯服务

## 第一步：连接硬件

### 推荐方式：蓝牙模式

1. 把状态灯插到电脑 USB 口，或者插到 USB 充电器。
2. 只要灯上电即可，蓝牙数据不走 USB 线。
3. 如果上电后红、黄、绿依次闪一下，说明硬件启动正常。

### 备用方式：USB 模式

1. 用 USB-C 数据线把状态灯插到 Mac。
2. 注意必须是支持数据传输的线，不能是只能充电的线。
3. 如果 App 里显示 `串口：/dev/cu.usbmodem...`，说明 USB 连接正常。

## 第二步：安装 App

1. 打开 `RedGreenSign-macos.dmg`。
2. 把 `RedGreenSign.app` 拖到 `Applications`。
3. 打开 `Applications` 里的 `RedGreenSign.app`。

如果 macOS 提示“无法验证开发者”：

1. 在 `Applications` 里找到 `RedGreenSign.app`。
2. 右键点击它。
3. 选择 `Open`。
4. 再确认打开。

打开后，Mac 右上角菜单栏会出现 `RGS`。

## 第三步：连接蓝牙

1. 点击右上角菜单栏里的 `RGS`。
2. 点击 `连接蓝牙`。
3. 等到界面显示 `蓝牙：已连接`。

如果第一次使用时 macOS 弹出蓝牙权限，请选择允许。

如果一直搜不到：

- 确认状态灯已经插电。
- 拔掉状态灯重新插上。
- 打开 macOS 系统设置里的蓝牙页面，看是否能看到 `RedGreenSign`。
- 如果系统蓝牙页面也看不到，联系硬件提供者检查固件。

## 第四步：选择要监听的 AI 工具

在 `监听来源` 区域勾选你要监听的工具：

- Codex
- Cursor
- Trae
- opencode
- Claude Code

不使用的工具可以不勾选。

## 第五步：启动

1. 蓝牙已连接后，点击 `启动`。
2. 看到 `服务：运行中`，说明状态灯服务已启动。
3. 之后你使用 Codex、Cursor、Trae、opencode 或 Claude Code 时，灯会自动变化。

如果你改了监听来源，点击 `重启` 让新设置生效。

## 测试灯是否可用

可以用这几个按钮测试：

- `绿灯`
- `黄灯`
- `红灯`
- `熄灭`

蓝牙已连接时，测试命令会走蓝牙。没有连接蓝牙时，会尝试走 USB。

## 停止使用

点击 `停止`：

- 后台服务会停止
- 状态灯会熄灭

点击 `退出 App`：

- 只退出右上角菜单栏 App
- 如果服务还在运行，状态监听可能仍然继续

建议不用时先点 `停止`，再点 `退出 App`。

## 查看日志

界面底部的 `最近日志` 会显示运行日志。

如果需要完整日志，点击 `打开日志`。

## 常见问题

### 1. 蓝牙连接不上

先确认状态灯是否上电。重新插拔硬件后再点 `连接蓝牙`。

### 2. 点了启动，但灯没反应

先点击 `绿灯`、`黄灯`、`红灯` 测试。

如果测试按钮也没反应：

- 蓝牙模式：确认显示 `蓝牙：已连接`
- USB 模式：确认显示 `串口：/dev/cu.usbmodem...`

### 3. 黄灯一直闪

说明 App 认为某个 AI 工具还在执行任务。

可以先点击 `停止`，灯会熄灭；再点击 `启动` 重新开始监听。

### 4. 红灯一直亮

红灯表示 AI 工具正在等待授权。

回到对应 AI 工具里，看看是否有确认、授权、Allow、Approve 之类的按钮或提示。

### 5. 没有用某个 AI 工具，要不要取消勾选

建议取消。只勾选自己实际使用的工具即可。

## 最短使用流程

```text
插上状态灯
打开 RedGreenSign.app
点击右上角 RGS
点击 连接蓝牙
勾选要监听的 AI 工具
点击 启动
```