给编码 Agent 一块状态面板：AgentPad13 的 Raw HID 协议、固件边界与自制路线
当 Claude Code、Codex 或其他编码 Agent 在终端里长时间运行时，开发者通常只能盯着滚动日志：它究竟在思考、调用工具、等待输入，还是已经结束？把状态塞进通知栏并不总是理想解法——窗口可能被遮挡，声音会打断工作，而远距离观察又需要更直接的信号。
AgentPad13 是一个为这类场景设计的开源自制宏键盘：以 RP2040 为核心，提供 13 个按键、旋钮、摇杆、触摸键和 24 颗 RGB LED。它有趣的部分不只是硬件，而是用 Raw HID 协议让宿主机把 Agent 状态映射到每个按键的灯光。对于想给本地 Agent 工作台加入实体反馈的开发者，它提供了一条从电路板、QMK/Vial 固件到协议测试都可检查的路线。
先厘清边界：它不是“控制 AI 的键盘”
AgentPad13 的 README 把定位说得很明确：这是面向 agentic work 的 13 键 macropad。它并不会理解代码、替你调度模型，也没有替代终端或 IDE；它接收的是外部程序写入的状态，再通过 RGB 灯呈现。这样反而是一个合理的架构边界：Agent 的业务逻辑留在宿主机，USB 设备只负责输入和低延迟、可见的输出。
项目当前硬件说明包括 RP2040、USB-C、12 个 1U 热插拔键和 1 个 2U 键、可按压 EC11 编码器、模拟倾斜摇杆、触摸键，以及逐键与边缘灯光共 24 颗 RGB LED。仓库的硬件 CAD 与 PCB 采用 CERN-OHL-W-2.0；常规固件及发布固件是 GPL-2.0-or-later 的 QMK/vial-qmk 派生部分。两者协议不同，不能因为仓库没有一个统一的顶层 LICENSE 就笼统声称“全项目 MIT”。
这种分层也解释了它的适用场景：适合本地运行多个 Agent、想用物理信号减少注意力切换的人；不适合期待设备自己判断任务是否安全、自动批准危险命令，或把它当成生产权限系统的人。LED 显示的是宿主机愿意上报的状态，不是独立的审计证据。
为什么选 Raw HID，而不是把一切伪装成按键
键盘的标准 HID 报告适合发送按键和修饰键，但不适合让上位机稳定地下发一组“第 N 个任务正在运行”的结构化状态。Raw HID 允许固件和本地桥接程序约定自己的报文格式：宿主机通过 USB 把状态写入设备，固件解析后更新 LED；设备仍可保留普通键盘、Vial 配置等既有输入能力。
这带来三个工程收益。
- 状态与快捷键解耦。 某个键可以继续触发常用命令，灯光则表示另一个 Agent 的进度；不必把“按了什么”和“发生了什么”绑成一件事。
- 状态是离散协议而非屏幕抓取。 宿主侧直接发出 thinking、running、waiting、done 这样的枚举，比 OCR 终端或根据窗口颜色猜测更可测。
- 可做离线验证。 项目提供了协议文档、模拟与一致性测试。自制硬件里，这比“插上去亮了”更重要：后者无法证明主机程序、报告 ID 和灯光映射一致。
但 Raw HID 并不自动安全。任何能打开相同 USB 接口的本地进程都可能写入状态；如果桥接程序把网络消息直接转成 HID 报文，还要验证来源、限制长度和频率，并在断连时让灯光回到明确的未知或空闲状态。不要把一个蓝灯当作远端任务真的已经完成。
一个可复现实操：先跑固件的主机侧测试
项目没有要求每位读者立刻焊板。README 为实验性的 Direct OAI keymap 提供了主机侧测试入口；它从仓库根目录运行，测试目录和文件匹配模式均由项目明确给出：
python3 -m unittest discover -s firmware/tests/codex_oai -p 'test_*.py'
这条命令适合放在自制流程的前面，而不是最后。先克隆仓库、运行测试、阅读 firmware/BUILD.md 与 keymap contract，再决定是否订 PCB、打印外壳或刷写 UF2。README 还提供 python3 manifest_selfverify.py，用于核对发布包列出的文件与校验信息；对需要交给板厂、切片器或刷写工具的文件，这种先验检查比从聊天记录复制一个文件名可靠得多。
正常工作流中的推荐固件仍是发布目录里的 agentpad13.uf2。所谓 Direct OAI 是隔离的实验替代 keymap：README 明确说它不是 Vial 固件，也不替代常规推荐路径；物理验证仍标为 pending。因而文章、采购清单或团队内部文档都不该把“通过了离线 USB/协议/LED 检查”写成“已经在真实设备上完成长期验证”。
把 Agent 事件变成可维护的状态模型
真正需要你自己实现的是宿主侧适配器。不要一开始就为每个模型和每种工具调用设计不同颜色；先定义一个小而稳定的状态机，再让各 Agent 的日志或 hook 转换为该状态机。例如：
idle -> 没有活动任务 thinking -> 正在规划或等待模型响应 running -> 正在执行命令、工具或子任务 waiting -> 需要人工输入、权限确认或外部资源 success -> 任务成功结束 failed -> 任务失败，需要查看终端详情
接着为每个并行任务分配一个 LED 槽位，并规定优先级：failed 与 waiting 应覆盖普通 running，success 只短暂显示后回到 idle。这样能避免“所有灯都在闪”却无法判断应先处理什么。桥接器还应记录状态转换的时间、任务标识和来源事件；LED 只是提示，真正的诊断依据仍是终端日志、运行记录和版本控制历史。
如果你的 Agent 支持工具前确认，最安全的映射是把确认请求显示为 waiting，然后回到原来的终端或审批界面作决定。不要让一个实体按键直接获得“批准 shell、合并 PR、读取密钥”的隐式权限。物理交互提升的是可见性，不是授权强度。
还要避免把状态协议设计成“最后一条日志的镜像”。日志可以很长、格式会变，也可能包含路径、分支名甚至敏感参数；面板协议应只传有限枚举、任务槽位和时间戳。这样即使未来把 Claude Code 换成别的 Agent，或将终端 hook 改为队列事件，硬件层仍然只依赖稳定的契约。把协议版本和未知状态的降级行为写下来，后续调试会轻松得多。
制作与运维时容易忽略的三件事
第一，发布包和开发分支不是同一个概念。项目把 release/ 作为订购、打印、刷写所需文件的集合，而 firmware/ 是源码、模拟和构建材料。优先使用 README 指向的发布路径，并在变更前保存版本、校验信息与构建日志；不要从任意开发中的 CAD 或固件文件夹挑一个文件就投入制造。
第二，USB 设备也需要故障策略。为宿主桥接进程添加重连、写入限速和心跳；设备重新插拔后应重新同步全量状态，而不是只发送“最后一个变化”。否则常见结果是任务已经结束，灯却永远停在运行色。对于长任务，定期刷新状态与超时熄灭通常比无限保留最后一次颜色更可解释。
第三，硬件状态可能泄露工作节奏。办公室或共享空间里，旁人可以从颜色、闪烁频率和亮灯数量推测是否有高优先级任务、审批等待或故障。若任务名称、客户名或密钥风险较高，就只上报抽象状态，不把敏感文本编码到键位、宏名称或屏幕叠加层中。
适合怎样开始
AgentPad13 的价值不在于承诺“硬件让 Agent 更聪明”，而在于把一个常被忽略的人机接口问题拆开：宿主侧如何定义状态、USB 如何传输、固件如何显示、发生故障时人如何回到可信的终端证据。对于已经有本地 Agent 工作流、愿意维护 RP2040/QMK 工具链的开发者，这是一个可研究、可验证的实体状态面板项目。
建议先完成离线测试和发布包校验，再在一条非关键任务上只显示 running、waiting、failed 三种状态。确认断连、重试和人工确认都符合预期后，再扩展到多 Agent、多键位与更复杂的灯效。把硬件当成提示层，而不是控制面，才能让它在提高可见性的同时不扩大自动化风险。