Skip to content

Commit 8ab0467

Browse files
westngwestng
committed
docs: add open source user guide
Summary: - Add a complete Chinese user guide for first-time AgentLight setup. - Link the guide from README and service documentation. Details: - Document hardware preparation, wiring, firmware flashing, USB/BLE/Wi-Fi validation, background service startup, platform switching, AI tool integration, and troubleshooting. - Update README.md and README.en.md to point users to docs/user-guide.md. - Reference the guide from docs/agent-service.md for service setup order. - Extend bridge verification to require the user guide and key setup sections.
1 parent 7246478 commit 8ab0467

5 files changed

Lines changed: 350 additions & 4 deletions

File tree

‎README.en.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,8 @@ This repository contains two parts:
3636
- **ESP32-C3 firmware**: receives commands and controls the red/yellow/green lights
3737
- **No-GUI bridge layer**: sends state commands through shell scripts and AI tool hooks
3838

39+
The complete user guide is available in Chinese at [docs/user-guide.md](./docs/user-guide.md).
40+
3941
## Hardware
4042

4143
- ESP32-C3 SuperMini
@@ -338,9 +340,9 @@ AgentLight/
338340
│ ├── agentlight-agent.example.json Example background agent service config
339341
│ └── agent-platforms.json Compatible AI Agent platform registry
340342
├── tests/ Desktop agent layering and config behavior tests
341-
├── docs/ Service and compatibility documents
343+
├── docs/ Chinese user guide, service, and compatibility documents
342344
├── platformio.ini ESP32-C3 SuperMini firmware build config
343-
└── CHANGELOG.md Bilingual release notes
345+
└── CHANGELOG.md Chinese release notes
344346
```
345347

346348
Project code standards are documented in [docs/code-standards.md](./docs/code-standards.md), and repository-level rules are defined in [AGENTS.md](./AGENTS.md).

‎README.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,8 @@ AgentLight 是一个基于 ESP32-C3 的桌面 AI 状态灯项目。它通过 USB
3333
- **ESP32-C3 固件**：负责接收命令并控制红 / 黄 / 绿灯
3434
- **无客户端桥接层**：通过 shell 脚本和 AI 工具 Hook 发送状态命令，不需要桌面 GUI App
3535

36+
完整使用说明见 [docs/user-guide.md](./docs/user-guide.md)，包含硬件接线、固件烧录、设备验证、后台服务启动和 AI 工具接入。
37+
3638
## 硬件
3739

3840
- ESP32-C3 SuperMini
@@ -316,9 +318,9 @@ AgentLight/
316318
│ ├── agentlight-agent.example.json 后台 Agent 服务示例配置
317319
│ └── agent-platforms.json AI Agent 兼容平台清单
318320
├── tests/ 桌面 Agent 分层与配置行为测试
319-
├── docs/ 服务与兼容性文档
321+
├── docs/ 使用说明、服务与兼容性文档
320322
├── platformio.ini ESP32-C3 SuperMini 固件构建配置
321-
└── CHANGELOG.md 中英双语版本发布说明
323+
└── CHANGELOG.md 中文版本发布说明
322324
```
323325

324326
项目代码规范见 [docs/code-standards.md](./docs/code-standards.md)，仓库级执行规则见 [AGENTS.md](./AGENTS.md)。

‎docs/agent-service.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
AgentLight 的电脑端形态不是桌面 App，而是后台 Agent 服务。服务负责监听本机 AI Agent 状态，并通过现有桥接链路把状态发送到 ESP32-C3。
44

5+
如果你是第一次使用项目，请先阅读 [AgentLight 使用说明](./user-guide.md)，按硬件接线、固件烧录、设备验证、后台服务启动的顺序完成基础链路。
6+
57
## 服务形态
68

79
| 系统 | 形态 | 运行身份 |

‎docs/user-guide.md‎

Lines changed: 332 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,332 @@
1+
# AgentLight 使用说明
2+
3+
本文档面向第一次使用 AgentLight 的用户，按实际落地顺序说明硬件接线、固件烧录、设备验证、后台服务启动和 AI 工具接入。
4+
5+
## 使用流程
6+
7+
```text
8+
准备硬件
9+
-> 接线
10+
-> 构建并烧录固件
11+
-> 验证 USB / BLE / Wi-Fi 控制
12+
-> 配置电脑端 Agent 服务
13+
-> 启动后台服务
14+
-> 接入 Codex 或其他 AI 工具
15+
-> 查看日志和排查问题
16+
```
17+
18+
## 准备硬件
19+
20+
需要准备：
21+
22+
| 物料 | 说明 |
23+
| --- | --- |
24+
| ESP32-C3 SuperMini | 当前固件目标开发板 |
25+
| 玩具红 / 黄 / 绿灯 | 也可以先用普通红黄绿 LED 验证 |
26+
| 220R 电阻 | 每一路灯都需要串联限流 |
27+
| USB 数据线 | 必须支持数据传输，不能只支持充电 |
28+
29+
默认 GPIO：
30+
31+
| 灯 | ESP32-C3 GPIO | 连接方式 |
32+
| --- | --- | --- |
33+
| 红灯 | GPIO4 | GPIO4 -> 220R -> 红灯正极 |
34+
| 黄灯 | GPIO5 | GPIO5 -> 220R -> 黄灯正极 |
35+
| 绿灯 | GPIO6 | GPIO6 -> 220R -> 绿灯正极 |
36+
| 共用负极 | GND | 三路灯负极接 GND |
37+
38+
如果玩具灯是共阳接法，需要把共用正极接到 `3V3`，并在 [platformio.ini](../platformio.ini) 中把 `AGENTLIGHT_ACTIVE_LOW=1`。
39+
40+
## 构建并烧录固件
41+
42+
安装 PlatformIO 后，在仓库根目录执行：
43+
44+
```bash
45+
pio run -e esp32-c3-supermini
46+
pio run -e esp32-c3-supermini -t upload
47+
pio device monitor
48+
```
49+
50+
烧录成功后，固件会同时开启：
51+
52+
| 通道 | 用途 |
53+
| --- | --- |
54+
| USB Serial | 通过串口发送文本命令 |
55+
| Bluetooth LE | 通过 BLE RX 特征写入文本命令 |
56+
| Wi-Fi HTTP | 电脑连接设备 AP 后通过 HTTP API 发送命令 |
57+
58+
默认固件配置：
59+
60+
| 配置 | 默认值 |
61+
| --- | --- |
62+
| BLE 设备名 | `WHALESKY-LABS-AGENTLIGHT` |
63+
| Wi-Fi AP | `WHALESKY-LABS-AGENTLIGHT` |
64+
| Wi-Fi 密码 | `agentlight` |
65+
| HTTP 地址 | `http://192.168.4.1` |
66+
67+
## 验证硬件
68+
69+
### 使用 Wi-Fi HTTP 验证
70+
71+
1. 电脑连接 Wi-Fi：`WHALESKY-LABS-AGENTLIGHT`
72+
2. 密码输入：`agentlight`
73+
3. 执行命令：
74+
75+
```bash
76+
curl "http://192.168.4.1/status"
77+
curl "http://192.168.4.1/command?cmd=GREEN"
78+
curl "http://192.168.4.1/command?cmd=YELLOW_BLINK"
79+
curl "http://192.168.4.1/command?cmd=RED_BLINK"
80+
```
81+
82+
如果灯能按命令切换，说明硬件、固件和 Wi-Fi 控制通道已经可用。
83+
84+
### 使用 USB Serial 验证
85+
86+
打开串口监视器：
87+
88+
```bash
89+
pio device monitor
90+
```
91+
92+
在串口中输入：
93+
94+
```text
95+
GREEN
96+
YELLOW_BLINK
97+
RED_BLINK
98+
STATUS
99+
```
100+
101+
每条命令以换行结尾。成功时固件会返回 `OK <STATE>` 或 `STATUS <STATE>`。
102+
103+
### 使用桥接脚本验证
104+
105+
桥接脚本默认使用 Wi-Fi HTTP：
106+
107+
```bash
108+
scripts/agentlight status
109+
scripts/agentlight green
110+
scripts/agentlight yellow-blink
111+
scripts/agentlight red-blink
112+
```
113+
114+
如果设备地址不是默认值，可以设置：
115+
116+
```bash
117+
export AGENTLIGHT_BASE_URL="http://192.168.4.1"
118+
```
119+
120+
## 启动电脑端后台服务
121+
122+
电脑端后台服务负责监听 AI 工具状态，并把状态事件发送到硬件。
123+
124+
默认配置文件是 [config/agentlight-agent.example.json](../config/agentlight-agent.example.json)：
125+
126+
```json
127+
{
128+
"activePlatform": "codex",
129+
"multiSessionMode": "latest-event-wins",
130+
"sendToHardware": true,
131+
"environment": {
132+
"AGENTLIGHT_HOST": "192.168.4.1",
133+
"AGENTLIGHT_TIMEOUT": "2"
134+
}
135+
}
136+
```
137+
138+
关键规则：
139+
140+
- 服务启动时只监听一个 `activePlatform`。
141+
- 多会话策略固定为 `latest-event-wins`。
142+
- 同一平台内哪个会话最后产生状态事件，硬件灯就显示哪个会话的状态。
143+
- `sendToHardware=true` 时，事件会继续发送到硬件；测试监听时可以先改成 `false`。
144+
145+
### 前台试运行
146+
147+
先用前台模式确认配置没问题：
148+
149+
```bash
150+
scripts/agentlight-agent check-config --config config/agentlight-agent.example.json
151+
scripts/agentlight-agent print-runtime --config config/agentlight-agent.example.json
152+
scripts/agentlight-agent run --config config/agentlight-agent.example.json --once
153+
```
154+
155+
如果只想看 Codex 状态能否被监听，不控制硬件，可以直接运行：
156+
157+
```bash
158+
scripts/codex-session-monitor --once --limit 20
159+
```
160+
161+
### macOS 后台服务
162+
163+
安装 LaunchAgent：
164+
165+
```bash
166+
service/macos/install-launch-agent.sh
167+
```
168+
169+
默认配置位置：
170+
171+
```text
172+
~/.whalesky-labs-AgentLight/agentlight-agent.json
173+
```
174+
175+
默认日志位置：
176+
177+
```text
178+
~/Library/Logs/whalesky-labs-AgentLight/
179+
```
180+
181+
查看服务：
182+
183+
```bash
184+
launchctl list | grep whalesky-labs
185+
tail -f ~/Library/Logs/whalesky-labs-AgentLight/agentlight-agent.log
186+
tail -f ~/Library/Logs/whalesky-labs-AgentLight/launchagent.err.log
187+
```
188+
189+
卸载：
190+
191+
```bash
192+
service/macos/uninstall-launch-agent.sh
193+
```
194+
195+
### Windows 后台服务
196+
197+
以管理员身份打开 PowerShell：
198+
199+
```powershell
200+
Set-ExecutionPolicy -Scope Process Bypass
201+
.\service\windows\install-service.ps1
202+
```
203+
204+
默认服务名：
205+
206+
```text
207+
whalesky-labs-AgentLight
208+
```
209+
210+
默认配置位置：
211+
212+
```text
213+
%ProgramData%\whalesky-labs-AgentLight\agentlight-agent.json
214+
```
215+
216+
默认日志目录：
217+
218+
```text
219+
%ProgramData%\whalesky-labs-AgentLight\logs\
220+
```
221+
222+
常用命令：
223+
224+
```powershell
225+
Get-Service whalesky-labs-AgentLight
226+
Start-Service whalesky-labs-AgentLight
227+
Stop-Service whalesky-labs-AgentLight
228+
.\service\windows\uninstall-service.ps1
229+
```
230+
231+
## 切换 AI 平台
232+
233+
查看当前平台：
234+
235+
```bash
236+
scripts/agentlight-agent platform get --config config/agentlight-agent.example.json
237+
```
238+
239+
查看可用平台：
240+
241+
```bash
242+
scripts/agentlight-agent platform list --config config/agentlight-agent.example.json
243+
```
244+
245+
切换到 Codex：
246+
247+
```bash
248+
scripts/agentlight-agent platform set codex --config config/agentlight-agent.example.json
249+
```
250+
251+
切换平台后，需要重启后台服务，让新平台配置生效。
252+
253+
## 接入 AI 工具
254+
255+
统一事件入口：
256+
257+
```bash
258+
scripts/agentlight-event --agent <agent> --event <event> --send
259+
```
260+
261+
常用事件：
262+
263+
| 事件 | 灯光状态 |
264+
| --- | --- |
265+
| `start` | `YELLOW_BLINK` |
266+
| `tool` | `YELLOW_BLINK` |
267+
| `thinking` | `YELLOW_BREATHE` |
268+
| `done` | `GREEN_BLINK` |
269+
| `waiting` | `RED_BLINK` |
270+
| `error` | `RED` |
271+
| `idle` | `GREEN` |
272+
273+
Codex 推荐先使用本地 session 监听：
274+
275+
```bash
276+
scripts/codex-session-monitor --thread-id "$CODEX_THREAD_ID" --from-start
277+
scripts/codex-session-monitor --thread-id "$CODEX_THREAD_ID" --event-command scripts/agentlight-event
278+
```
279+
280+
其他平台可以先使用通用 wrapper：
281+
282+
```bash
283+
/absolute/path/to/AgentLight/hooks/agents/generic-wrapper.sh <agent> <command> "$@"
284+
```
285+
286+
不同平台的具体接入说明见：
287+
288+
- [hooks/agents/README.md](../hooks/agents/README.md)
289+
- [hooks/codex/README.md](../hooks/codex/README.md)
290+
- [hooks/cursor/README.md](../hooks/cursor/README.md)
291+
- [docs/agent-platform-compatibility.md](./agent-platform-compatibility.md)
292+
293+
## 常见问题
294+
295+
### Wi-Fi 连接后没有响应
296+
297+
- 确认电脑连接的是 `WHALESKY-LABS-AGENTLIGHT`。
298+
- 确认请求地址是 `http://192.168.4.1`。
299+
- 确认固件已经烧录成功，并且开发板已重新上电。
300+
301+
### 灯不亮
302+
303+
- 检查每一路灯是否串联 220R 电阻。
304+
- 检查 GPIO 是否对应 `GPIO4`、`GPIO5`、`GPIO6`。
305+
- 检查玩具灯是共阴还是共阳；共阳需要设置 `AGENTLIGHT_ACTIVE_LOW=1`。
306+
- 用 `GREEN`、`YELLOW_BLINK`、`RED_BLINK` 分别测试三路。
307+
308+
### 服务启动了但灯没有变化
309+
310+
- 先运行 `scripts/agentlight yellow-blink`，确认硬件通道可用。
311+
- 查看服务配置中的 `sendToHardware` 是否为 `true`。
312+
- 查看 `AGENTLIGHT_HOST` 或 `AGENTLIGHT_BASE_URL` 是否指向正确设备。
313+
- 查看后台服务日志，确认监听器是否有事件输出。
314+
315+
### Codex 状态没有被监听到
316+
317+
- 确认 Codex 已经产生本地 session JSONL。
318+
- 先运行 `scripts/codex-session-monitor --once --limit 20` 看是否有输出。
319+
- 如果要限制到某个会话，确认 `CODEX_THREAD_ID` 是否正确。
320+
321+
## 项目边界
322+
323+
AgentLight 只负责把可观察到的 AI Agent 状态同步到硬件红黄绿灯。
324+
325+
当前不提供：
326+
327+
- 桌面 GUI 客户端
328+
- 托盘面板
329+
- Dashboard
330+
- 权限气泡
331+
- 终端聚焦
332+
- 自动改写第三方 AI 工具配置

0 commit comments

Comments
 (0)