The user-visible product is the physical light beside your computer, the desktop app that owns local state, agent hooks that report workflow events, and optional official service rights for activation and firmware service.

• Local hardware + desktop app + ESP32-WROOM-32 signal light + agent hooks + official service rights.
• Local basic status-light features do not require sign-in.

用户实际使用的是桌面旁边的物理灯、负责本地状态的桌面 app、上报工作流事件的 agent hooks，以及可选的激活与官方服务权益。

• 本地硬件 + 桌面 app + ESP32-WROOM-32 信号灯 + agent hooks + 官方服务权益。
• 本地基础状态灯功能不需要登录。

The currently documented official target is ESP32-WROOM-32 with red / yellow / green status lamps, a USB data connection for power, serial verification, and flashing, plus a case or enclosure only as basic physical protection.

• ESP32-WROOM-32 board running the Agent Status Light firmware.
• Red, yellow, and green status lamps driven by the firmware protocol.
• USB data connection for power, device discovery, firmware verification, and desktop app communication.
• Case or enclosure details remain within the current official support range; no production SKU or purchase promise is made here.

当前官方文档目标是 ESP32-WROOM-32，配红 / 黄 / 绿状态灯，通过 USB 数据线供电、串口验证和刷写；外壳只作为基础物理保护说明，不承诺具体量产 SKU。

• 运行 Agent Status Light 固件的 ESP32-WROOM-32 开发板。
• 由固件协议驱动的红、黄、绿状态灯。
• USB 数据连接用于供电、设备发现、固件验证和桌面 app 通信。
• 外壳或 enclosure 仍以当前官方支持范围为准；这里不伪造购买或量产承诺。

Connect the USB cable, open the desktop app, select or auto-detect the device, then run Devices Test before trusting the light.

• Connect the USB cable to the ESP32-WROOM-32 and your computer; use a data-capable cable, not a charge-only cable.
• Open the desktop app and use Devices to select or auto-detect the device.
• Run Devices Test. The app should verify firmware version, capabilities, ack, and status before saving the device.
• Use the Status buttons to test running, waiting, and done-like idle output on the physical light.

连接 USB 线，打开桌面 app，选择或自动识别设备，然后运行 Devices Test，再相信灯光状态。

• 连接 USB 线到 ESP32-WROOM-32 和电脑；请使用可传数据的线，不要用仅充电线。
• 打开桌面 app，在 Devices 中选择或自动识别设备。
• 运行 Devices Test。app 应在保存设备前验证固件版本、capabilities、ack 和 status。
• 使用 Status 按钮测试 running、waiting 和类似 done 的 idle 输出。

The app and docs use user-facing states beyond the firmware's four internal states. The physical ESP32 path maps active work to yellow, attention to red, done/idle to green, and unavailable states to gray or no verified light.

app 和文档会使用比固件四个内部状态更贴近用户的说法。物理 ESP32 路径把活跃工作映射为黄色，需要处理映射为红色，done/idle 映射为绿色，不可用或未知状态用灰色或未验证表示。

Start with the connection and power path before changing firmware or wiring.

• No reaction: check USB permission, data cable, power, and whether the ESP32 startup self-test shows red, yellow, and green.
• Serial port is not visible: reconnect the USB cable, try another port, close other serial monitors, and check operating-system permission prompts.
• Lights do not turn on: confirm power, the red / yellow / green module, and current official wiring guidance before assuming the desktop app is wrong.
• State does not update: run Devices Test again, verify the selected path, and check that agent hooks are configured only after the local device works.

先检查连接和供电，再考虑固件或接线问题。

• 无反应：检查 USB 权限、数据线、供电，以及 ESP32 启动自检是否依次显示红、黄、绿。
• 串口不可见：重新插拔 USB、换端口、关闭其它串口监视器，并检查系统权限提示。
• 灯不亮：先确认供电、红黄绿灯模块和当前官方接线说明，不要直接假设桌面 app 错误。
• 状态不更新：重新运行 Devices Test，确认选中的设备路径；本地设备可用后再配置 agent hooks。

Local basic status-light features do not require sign-in. Official service rights, firmware updates, and one-click flashing require an account, activation code, and device binding. The final-user path does not require Arduino IDE, arduino-cli, PlatformIO, ESP-IDF, or esptool.

本地基础状态灯功能不需要登录。官方服务权益、固件更新和一键刷写需要账号、激活码和设备绑定。最终用户不需要 Arduino IDE、arduino-cli、PlatformIO、ESP-IDF 或 esptool。