Agent Status Light

Docs

Desktop app and agent hooks

The desktop app connects the local device, receives agent hooks, updates the status light, and handles account activation and device binding.

文档

桌面 app 和 agent hooks

桌面 app 连接本地设备、接收 agent hooks、更新状态灯，并处理账号激活和设备绑定。

Install the desktop app

Download the app through the public Worker release proxy. Stable desktop installers are public release assets, including the macOS direct download through the website release proxy.

agent-status-light_darwin-arm64.dmg
  • Use the website download buttons for desktop installers; do not add new firmware download URLs.
  • Connect the ESP32-WROOM-32 light after installing the app.
macOS
安装桌面 app

通过 public Worker release proxy 下载 app。稳定桌面安装包是公开 release assets，包括官网 release proxy 提供的 macOS 直接下载。

agent-status-light_darwin-arm64.dmg
  • 桌面安装包使用官网下载按钮；不要新增固件下载 URL。
  • 安装 app 后连接 ESP32-WROOM-32 信号灯。
macOS
Local runtime

The desktop app owns local state, agent hooks, device setup, firmware flashing, and the local runtime path from software state to the physical signal light. It is not a cloud console.

  • Connect the ESP32-WROOM-32 light and run Devices Test before relying on automation.
  • Use Status buttons to verify red, yellow, and green output.

Media to prepare

Screenshot · Devices panel after verification Verified local device in the desktop app

Show the selected device after Devices Test succeeds, using safe demo names and no complete device fingerprint.

Use it for: Place near local runtime and install guidance so users know what a successful device check looks like.

suggested file: docs-desktop-devices-verified
本地 runtime

桌面 app 负责本地状态、agent hooks、设备设置、固件刷写，以及从软件状态到物理信号灯的本地 runtime 路径。它不是云端控制台。

  • 连接 ESP32-WROOM-32 信号灯，并先运行 Devices Test。
  • 使用 Status 按钮验证红、黄、绿输出。

待准备素材

截图 · Devices 面板验证完成状态 桌面 app 中已验证的本地设备

展示 Devices Test 成功后的选中设备，使用安全演示名称，不展示完整 device fingerprint。

用途： 放在本地 runtime 和安装说明附近，让用户知道设备检查成功后应该看到什么。

建议文件名： docs-desktop-devices-verified
Agent hooks

Agent hooks turn local agent workflow events into status updates for the desktop runtime. Configure the agent hook after the app is installed and the device is verified; hooks should not talk to Bluetooth or cloud services directly.

  • Configure the agent hook from the desktop app where supported, or use the documented local command surface.
  • Hook commands are local and fail open so an unavailable app does not block the agent workflow.

Media to prepare

Video · agent hook status changes Hook events changing the local status light

Use a local demo project to show running, waiting, needs attention, done, offline, and unknown without showing private project content.

Use it for: Place beside agent hook setup so users understand hooks translate local workflow events, not a cloud console.

suggested file: docs-desktop-agent-hook-status-demo
Agent hooks

Agent hooks 把本地 agent 工作流事件转换为桌面 runtime 的状态更新。请在 app 安装且设备验证后再配置 hook；hook 不应该直接控制蓝牙或云服务。

  • 支持时可从桌面 app 配置 agent hook，也可以使用文档中的本地命令入口。
  • Hook 命令保持本地、fail-open，app 不可用时不阻塞 agent 工作流。

待准备素材

视频 · agent hook 状态变化 Hook 事件驱动本地状态灯变化

使用本地 demo 项目展示 running、waiting、needs attention、done、offline 和 unknown，不展示私有项目内容。

用途： 放在 agent hook 设置旁边，说明 hook 转换的是本地工作流事件，不是云端控制台。

建议文件名： docs-desktop-agent-hook-status-demo
Status semantics

Use running/yellow for active work, waiting or needs attention/red when the user must act, done/green when work is complete, and offline or unknown/gray when the app cannot verify the local path.

running

Agent work or tool execution is active.

Yellow physical light, usually blinking or otherwise active.

Let the agent continue unless it asks for confirmation.

waiting

The workflow is paused for user confirmation or input.

Red physical light.

Check the desktop app or agent terminal and respond.

needs attention

The app or agent needs intervention, usually because work cannot continue automatically.

Red physical light.

Review the prompt, error, or device state before continuing.

done

The current task completed or returned to an idle-like ready state.

Green physical light.

Read the result, start the next task, or leave the device idle.

offline

The desktop app cannot verify the local device path.

Gray UI state and no trusted physical-light update.

Check USB, power, permissions, and Devices Test.

unknown

The app has not received enough local state to classify the workflow.

Gray UI state until a verified status arrives.

Wait for the next hook event or verify the selected device.

状态语义

工作进行中使用 running/黄色；需要用户处理时使用 waiting 或 needs attention/红色；完成或空闲使用 done/绿色；app 无法验证本地路径时使用 offline 或 unknown/灰色。

running

Agent 正在工作，或工具调用正在执行。

物理灯显示黄色，通常是闪烁或活跃状态。

通常继续等待，除非 agent 明确请求确认。

waiting

工作流暂停，等待用户确认或输入。

物理灯显示红色。

查看桌面 app 或 agent 终端并处理提示。

needs attention

app 或 agent 需要人工介入，通常表示无法自动继续。

物理灯显示红色。

先查看提示、错误或设备状态，再继续操作。

done

当前任务已完成，或回到类似空闲的就绪状态。

物理灯显示绿色。

阅读结果、开始下一个任务，或让设备保持空闲。

offline

桌面 app 无法验证本地设备路径。

UI 显示灰色状态，且没有可信的物理灯更新。

检查 USB、供电、权限和 Devices Test。

unknown

app 暂时没有足够的本地状态来判断工作流。

UI 保持灰色，直到收到已验证状态。

等待下一次 hook 事件，或确认当前选择的设备。

Local-first privacy boundary

Local-first status display does not imply uploading your source code or full work content. Official service rights use account login, activation code redemption, and device binding; public UI should show only safe summaries such as provider, display name, and short fingerprint.

本地优先隐私边界

本地优先状态显示不代表上传你的源码或完整工作内容。官方服务权益使用账号登录、激活码兑换和设备绑定；公开 UI 只应显示 provider、display name、短指纹等安全摘要。

Typical workflow

The ordinary path is install, connect, verify, configure hooks, then watch the physical light.

  • Download the app, open it, and connect the ESP32-WROOM-32 light over USB.
  • Run Devices Test until the app reports a verified local device.
  • Configure the agent hook and observe red / yellow / green state changes during real work.
典型流程

普通路径是安装、连接、验证、配置 hooks，然后观察物理灯。

  • 下载 app，打开后通过 USB 连接 ESP32-WROOM-32 信号灯。
  • 运行 Devices Test，直到 app 报告本地设备已验证。
  • 配置 agent hook，并在真实工作中观察红 / 黄 / 绿状态变化。