命令行工具

和设备对话的 andon-light 命令：怎么安装、有哪些命令、怎么找到设备。

andon-light 是运行在你电脑上、通过 USB 和设备对话的一个小程序。它是用 Python 写的，Claude Code 和 Codex CLI 的 hook 在背后自动切换灯光颜色时，调用的正是它。不过你随时也可以自己手动运行它。

安装

日常使用建议直接装已发布的版本，而不是自己从源码构建。参见 Linux 或 Windows 的安装说明。macOS 目前还没有测试和支持。

如果你在开发这个工具本身的源码，在项目的 host/ 目录下用"可编辑"模式安装：

cd host
pipx install --editable .

这样会直接链接回源码文件，改了代码马上生效，不用重新安装。

如果你想放在一个独立的隔离环境里，不加进系统 PATH：

cd host
python3 -m venv .venv
.venv/bin/pip install -e .

使用方法

andon-light doctor                              # 检查能不能找到你的设备
andon-light set working                         # 常亮绿色
andon-light set waiting                         # 常亮黄色
andon-light set idle                             # 常亮红色
andon-light set compacting                       # 依次点亮模式（整理中）
andon-light heartbeat                            # 只重置看门狗，不改变颜色
andon-light --port /dev/ttyACM0 set working      # 如果自动识别选错了端口，手动指定
andon-light install-hooks                        # 设置和 Claude Code 的集成（默认）
andon-light install-hooks --agent codex          # 改成设置和 Codex CLI 的集成
andon-light install-hooks --yes --scope global   # 同上，跳过确认直接执行

install-hooks 在做任何改动之前，都会先完整展示即将写入的内容，并等你确认。你可以选择应用范围是全局还是单个项目。如果某个 hook 你已经自定义过，即将被覆盖，它会提前警告你。--agent 用来选择设置哪一个集成：

两个 agent 用的是同一套固件、同一套通信协议。区别只在电脑这一端跑的软件，设备那一端没有任何不同。

怎么找到你的设备

这个工具会寻找匹配特定 USB 厂商 ID（0x2E8A）的设备，这正是这块板子所用芯片系列使用的 ID，所以通常不需要你手动指定端口，它就能自动找到设备。

如果它找错了设备，或者什么都没找到，可以用 --port 参数或者 ANDON_LIGHT_PORT 环境变量手动指定。

如果看到"设备或资源被占用"的报错，通常是因为别的程序已经占着这个连接，最常见的情况是后台还开着的 Arduino IDE 串口监视器。同一时间只能有一个程序使用这个连接。这个工具会自动重试大约半秒钟，如果还是不行，会给出简短的一行提示和非零的退出码，而不是甩出一大段原始报错。