行空板 M10 变成 AI Agent 状态终端
一个 2.8 寸小屏,实时显示 AI 正在思考什么、改哪个文件、跑什么命令;任务卡住时,按下板载 A 键就能批准,B 键拒绝。整机不需要额外电路,一块行空板 M10 加一根 Type-C 线就够了。
难度:入门偏进阶(会复制粘贴命令即可,不需要焊接)
耗时:约 1 小时
硬件:行空板 M10 ×1、Type-C 数据线 ×1、2.4G WiFi
软件:行空板自带 Python 3.7 + unihiker / pinpong;电脑端 Python 3.7+(Bridge 纯标准库,部署脚本需 paramiko)


一、起因
前段时间刷到 B 站一个视频《我把旧手机变成了 AI Agent 状态终端》,作者把淘汰的旧手机挂在显示器边上,实时显示 Codex / Claude Code 在干什么:在思考、在读文件、在跑测试,甚至能直接在手机上点「批准」。
这个点子很戳人。写代码的时候,AI 在后台跑长任务,人只能盯着终端刷屏,或者切窗口看它卡在哪。有一块常亮的副屏,抬眼就能看到进度,确实舒服。
但旧手机方案有几个问题:要常插电、电池长期满电鼓包、屏幕常亮烧屏、还得装个 App。手边正好有一块行空板 M10——2.8 寸触摸屏、WiFi、蜂鸣器、A/B 两个实体按键,天生就是干这个的。
于是动手把整套东西搬到了行空板上,顺手多做了两件旧手机做不到的事:实体按键审批和 8-bit 音效。
二、成品是什么样
行空板竖着放在显示器下方,屏幕从上到下是这样几块:
┌──────────────────────────┐
│ AGENT PAGER 在线 │
├──────────────────────────┤
│ 运行中 · 执行 02:14 │ ← 状态 + 右上角运行时间
│ [1] 行空板M10副屏 │ ← 项目名
│ 任务: 把界面文字改成三行 │ ← 用户的原始请求
│ 过程: 执行: 部署新版状态 │ ← Agent 当前动作(人话)
│ 终端到行空板 │
├──────────────────────────┤
│ 子代理 无 │
├──────────────────────────┤
│ 待批准: 执行 git push │ ← 有审批时变红
├──────────────────────────┤
│ A 批准 B 拒绝 │
└──────────────────────────┘

状态会随 Agent 的动作实时变化:
空闲 → 启动中 → 运行中 · 思考 → 运行中 · 读/写/执行 → 已完成- 需要授权时,状态变红并显示「等待批准」,底部红条给出待批准的操作摘要
- 按 A 批准,按 B 拒绝;55 秒不操作自动放行(可配置)
- 状态切换时蜂鸣器会响一小段 8-bit 音阶,开机、完成、告警、批准、拒绝的音阶都不一样
音效这件事看似花哨,实际很有用:戴着耳机写代码,AI 任务跑完了「叮咚」一下,不用回头看屏幕。
三、材料清单
| 名称 | 数量 | 说明 |
|---|---|---|
| 行空板 M10 | 1 | 主控 + 2.8 寸 240×320 触摸屏 + 蜂鸣器 + A/B 键 |
| Type-C 数据线 | 1 | 首次配置用,之后走 WiFi |
| 电脑 | 1 | Windows / macOS / Linux 均可,需要 Python 3.7+ |
| 2.4G WiFi | - | 电脑和行空板必须在同一网段 |
不需要面包板、不需要杜邦线、不需要外接屏幕。所有外设行空板都板载了。
软件侧全部是 Python 标准库 + 行空板自带的 unihiker、pinpong 库,电脑端不装任何第三方依赖。
四、整体思路
先说我用的开发工具:WorkBuddy,一个带 Hook 机制的 AI 编程 Agent。它的 Hook 规范和 Claude Code 基本一致,会在会话开始、提交提问、调用工具前后、结束等时机回调外部脚本。这就给了我们一个天然的「状态采集口」。
整套系统分三层:

WorkBuddy Hook → 电脑 Bridge(Python) → HTTP 推送 → 行空板 M10
(7 个事件) (聚合/签名/审批) (电脑→板) (屏幕/音效/按键)
为什么是电脑主动推,而不是行空板主动连?
这是整个项目最大的一个架构决策,也是被现实逼出来的。
最初我按 AgentPager 原版的思路,让行空板作为 WebSocket 客户端去连电脑的 49362 端口。代码写得没问题,但行空板永远连不上——Windows 防火墙默认拦截入站连接,行空板发起的 TCP 握手直接被丢包。
而反方向是通的:我能用 SSH 从电脑连上行空板。也就是说,「电脑 → 行空板」这条路畅通,「行空板 → 电脑」这条路被墙挡住。
于是把方向反过来:Bridge 每次状态变化,主动 POST 到行空板的 8766 端口;行空板上的接收端把数据交给界面渲染,按键结果写进一个队列,Bridge 再定时轮询取回。
不用改防火墙,不用管理员权限,插上就能跑。Bridge 里同时保留了对 AgentPager 原生 WebSocket 协议的兼容,方便以后接官方 App。
五、动手
5.1 电脑端:启动 Bridge
Bridge 是一个纯标准库的 Python 服务,负责三件事:接收 Hook 事件、把事件聚合成「任务快照」、把快照推给行空板。
cd bridge
python bridge.py
启动后会打印:
AgentPager Bridge for WorkBuddy
Hook 接口: http://192.168.1.100:8765
WebSocket : 49362
配对信息 : http://192.168.1.100:8765/pairing
5.2 安装 Hook
python install_hooks.py install
安装器会往 ~/.workbuddy/settings.json 写入 7 个事件的 Hook:
SessionStart、SessionEnd、UserPromptSubmit、PreToolUse、PostToolUse、Stop、PreCompact
每个 Hook 都调用同一个转发脚本 hook_client.py:从 stdin 读事件 JSON,转发给 Bridge,再把 Bridge 的决策写回 stdout。审批就是靠这条链路实现的——Hook 阻塞等结果,Agent 才能停下来等你按键。
WorkBuddy 会热加载 Hook 配置,改完通常不用重启。
5.3 行空板端:部署
行空板出厂系统已经内置 SSH 和 Python 环境,不用额外装东西。先让它连上 WiFi(用 USB 连电脑,浏览器打开 Jupyter 页面配置即可),记下它的局域网 IP。然后在电脑上一条命令推过去:
python tools/deploy.py --host 192.168.1.106 --password ****** install
--password填行空板的 SSH 密码,默认密码见 DFRobot 官方文档。部署脚本依赖paramiko,这是电脑端唯一需要pip install的包。
脚本用 SSH/SFTP 把 unihiker/ 传到 /root/agentpager/,写入配置,用 setsid 拉起接收端,再配一条 @reboot 的 cron 实现开机自启。
行空板侧的配置只有一项要改——电脑的 IP:
{
"bridge_host": "192.168.1.100",
"push_mode": "reverse",
"sound": true
}
5.4 跑起来
在 WorkBuddy 里随便提一个需求,行空板立刻从「等待任务」切到「运行中」,项目名、你的原始提问、Agent 当前动作依次出现。工具一调用,右上角计时开始跳,蜂鸣器「哔」一声。
六、界面是怎么画出来的
行空板 M10 的屏幕是 240×320 的 framebuffer,unihiker 库提供了一套类似 Canvas 的绘图接口:fill_rect、fill_round_rect、draw_text、draw_circle。所以界面不是我一张张图贴上去的,而是用代码画的,改布局就是改几个坐标。
布局分五块:顶栏、状态卡、子代理条、提示条、按键说明。状态卡最高(180px),因为要给「任务」和「过程」各留三行。
# 状态区
self._rect("card", 8, 38, 224, 180, COLORS["panel"], r=6)
self._text("state", 18, 48, "连接中...", 17, COLORS["sub"])
# 运行时间固定在右上角,独立控件,不会被长文本盖住
self._text("elapsed", 228, 49, "", 10, COLORS["yellow"], origin="top_right")
self._text("project", 18, 72, "", 10, COLORS["sub"])
self._text("task", 18, 92, "", 9, COLORS["blue"], w=206)
self._text("step", 18, 156, "", 9, COLORS["text"], w=206)
这里有两个细节值得说。
第一,右上角的时间必须独立成控件。 一开始我把「状态 · 耗时 · token」拼成一行显示,结果状态文字一长(「运行中 · 执行」),就把右边的耗时挤掉、甚至盖住。改成独立的右对齐控件后,不管左边多长,时间都稳稳在角上。
第二,小屏幕上「显示什么」比「显示多少」重要。 最初我直接把工具调用原样打上去,屏幕经常出现:
过程: Bash: cd /root/agentpager && python /very/long/path/deploy.py...
一屏幕全是路径和参数,人根本读不出来它在干嘛。后来在 Bridge 里加了一层「翻译」,把工具输入压成一句人话:
def tool_summary(name, inp):
"""把工具输入压成一行"人话",优先自然语言描述。
Bash 工具自带 description(中文),必须优先于 command;
文件类工具只取文件名;搜索类展示 pattern。"""
verb = TOOL_VERB.get(name, name)
# 1. 自然语言字段(Bash 的 description 最重要)
for k in ("description", "summary", "prompt", "query", "message"):
if inp.get(k):
return "{}: {}".format(verb, _flat(inp[k], 140))
# 2. 搜索模式
if inp.get("pattern"):
return "{}: {}".format(verb, _flat(inp["pattern"], 100))
# 3. 文件类:只显示文件名
for k in ("file_path", "path", "filepath"):
if inp.get(k):
return "{} {}".format(verb, _basename(inp[k]))
# 4. 命令兜底:只给短预览,不铺满整屏
if inp.get("command"):
return "{}: {}".format(verb, _flat(inp["command"], 90))
return name
改完之后的显示效果:
过程: 执行: 部署新版状态终端到行空板并验证屏幕显示
同一件事,读者一眼就懂。这是整个项目里我觉得最值钱的一次改动——状态屏的价值不是「转播终端」,而是「翻译终端」。
七、实体按键审批
这是行空板比旧手机更好用的地方。
Agent 请求权限时,Bridge 生成一个带 requestID 的待审批请求,通过快照推给行空板。状态文字变红,底部弹出红色提示条,同时 on_a_click / on_b_click 挂上回调:

def on_a(self):
with STATE_LOCK:
pending = STATE["snapshot"].get("pendingRequests", [])
if pending:
send_control("approve") # 有待审批 → 批准
else:
# 没有待审批 → A 键当作「切换任务」
...
def on_b(self):
with STATE_LOCK:
pending = STATE["snapshot"].get("pendingRequests", [])
if pending:
send_control("deny") # 拒绝
按键结果不会直接回传给 Hook,而是先写进行空板上的结果队列,Bridge 每 0.5 秒轮询 /results 取走,再唤醒阻塞中的 Hook,返回:
{"permissionDecision": "allow"}
这条链路是双向的,所以安全上做了一点小设计:所有控制命令用 HMAC-SHA256 签名,密钥在 Bridge 首次启动时随机生成,行空板通过 /pairing 拉取。这样即使局域网里有人抓到了请求,也没法伪造一次「批准」。
实测:按 A → Hook 返回 allow → Agent 继续执行 → 两端 pending 清零,全程不到 1 秒。
八、8-bit 音效
行空板板载一个蜂鸣器,用 pinpong 的 buzzer.pitch(freq) 驱动。我按场景写了几组音阶:
NOTE = {
"boot": [523, 659, 784], # 开机
"start": [392, 523], # 任务开始
"done": [659, 784, 1047], # 任务完成
"alert": [880, 660, 880], # 需要批准
"error": [330, 247], # 出错
"approve": [523, 784], # 按 A
"deny": [392, 294], # 按 B
}
听起来简单,但这里踩了两个坑,都是实测才发现的:
坑一:pitch() 的第二个参数不是秒。 我一开始写 buzzer.pitch(freq, 0.09),想让它响 90 毫秒,结果直接报位运算错误——第二个参数是「拍数」,整数,不是时长。
坑二:pitch() 默认是持续音。 改对参数后音是响了,但响起来就不停,整个房间一直在「嗡——」。查了固件才发现默认 beat=0x04 表示持续发声,必须显式停止。最终每个音符都要配一次 stop:
def beep(freq, dur=0.08):
if not HARDWARE or not CFG.get("sound", True) or buzzer is None:
return
buzzer.pitch(int(freq))
time.sleep(dur)
_buzz_stop() # 关键:不 stop 就一直响
def _buzz_stop():
bd = get_globalvar_value("UNIHIKER")["UNIHIKER"].board
bd.GD32V_buzz_stop()
九、踩过的坑(这部分可能比代码更有用)
1. Hook 装对了文件,却没生效
WorkBuddy 读的是 ~/.workbuddy/settings.json,我一开始按 Codex 的习惯写进了 ~/.codebuddy/settings.json。文件格式完全正确,就是不触发。
排查方法:让 Hook 往日志里写一行,看有没有写。没有,就是压根没被调用。
2. 中文路径把 Python 干掉了
项目目录叫 行空板M10副屏。Hook 命令里带中文路径,WorkBuddy 传递时编码被破坏,日志里出现:
can't open file '...\xd6\xc1...'
解法:安装器把 hook_client.py 复制到纯英文路径 ~/.workbuddy/agentpager/,Hook 只指向这份副本;命令里全部用正斜杠,每段路径加双引号。
3. surrogates not allowed
Hook 收到的 JSON 里偶尔混进 \udcaf 这类孤立代理字符(来自被截断的 emoji 或系统路径),json.dumps 时直接抛 UnicodeEncodeError,Hook 静默失败。
解法:递归清洗一遍再序列化。
def _sanitize(o):
if isinstance(o, str):
return o.encode("utf-8", "ignore").decode("utf-8", "ignore")
if isinstance(o, dict):
return {k: _sanitize(v) for k, v in o.items()}
if isinstance(o, list):
return [_sanitize(v) for v in o]
return o
4. 屏幕全黑,但进程活着
这个卡了最久。现象是程序正常跑、日志正常打,屏幕一片黑。
根因很意外:HARDWARE 这个标志被 pinpong 的 Board().begin() 拖累了。原来的代码把「屏幕初始化」和「蜂鸣器初始化」放在同一个 try 里,Board().begin() 在串口被占用时会超时,异常一抛,HARDWARE=False,于是连屏幕都不画了。
解法:屏幕和蜂鸣器彻底解耦。HARDWARE 只由 from unihiker import GUI 决定;蜂鸣器单独初始化,失败就静音,绝不影响显示。
顺带修了第二个问题:Board().begin() 会注册信号处理器,只能在主线程调用,放后台线程会报 signal only works in main thread。移到主线程后又加了 signal.alarm(15) 超时保护,防止串口异常时整个程序卡死。
5. 文字行与行重叠、还有「鬼影」
这个问题最像玄学。现象是:长文本变短之后,屏幕上还残留着上一段文字的下半截,看起来就像两行叠在一起。
根因是 framebuffer 的绘制模型:canvas.delete() 只是把控件从画布移除,不会重画它占过的像素。背景色一直留在那儿,旧文字就永远留在屏幕上。
解法:更新文字时,先按旧控件的 bbox 用背景色抹一块,再删控件、重建新文字,最后把抹除用的矩形也删掉。
def set_text(self, key, text, color=None):
...
old = self.obj.get(key)
if old:
bbox = self.gui.canvas.bbox(old.ids[0])
if bbox:
x0, y0, x1, y1 = bbox
eraser = self.gui.fill_rect(
x=x0 - 1, y=y0 - 1, w=x1 - x0 + 2, h=y1 - y0 + 2,
color=spec["bg"]) # 用背景色擦掉旧像素
self.gui.remove(old)
...
if eraser:
self.gui.remove(eraser)
配合按字号算好的行高(9 号字实际行距约 18px),任务区固定在 92–146,过程区从 156 开始,中间留出干净的间隙。
6. 同一句话显示了两遍
「状态实时同步中」同时出现在信息行和底部提示条的兜底文案里。删掉信息行,提示条没有临时消息时直接留空并融进背景,问题解决。
底部原本还有额度、品牌两行,也一起砍了——小屏幕上,留白比信息更贵。
十、还能怎么玩
这套东西的骨架是「事件采集 → 状态聚合 → 小屏渲染」,把中间那层换掉,能接的东西很多:
- 接别的 Agent:WorkBuddy Hook 与 Claude Code 规范兼容,改一下事件映射就能接 Claude Code;Codex 也有自己的 hook/notify 机制。
- 接 CI:把 GitHub Actions 的 webhook 转成同样格式的快照,行空板就变成流水线状态灯,红绿一眼可见。
- 接智能家居:状态变化时顺手 MQTT 推一条,Agent 一完成任务,书房灯变绿。
- 加传感器:行空板还有光线传感器和加速度计,可以做人来自动亮屏、翻转自动换布局。
我个人最想要的是「远程审批」——现在必须在板子旁边才能按键,如果做成手机网页也能批,就真的可以离开工位去泡咖啡了。
十一、文件说明
bridge/
bridge.py 电脑端桥接服务(Hook 接收 + 状态聚合 + 反向推送 + 审批)
hook_client.py Hook 转发脚本(stdin → Bridge → stdout)
install_hooks.py 一键安装/卸载 7 个 Hook
unihiker/
agent_pager.py 行空板终端(界面/音效/按键/WebSocket 兼容)
receiver.py 反向推送接收端(HTTP :8766)
tools/
deploy.py SSH 一键部署 + 开机自启
mock_events.py 无硬件模拟事件
代码约 2100 行:Bridge 与 Hook 纯标准库,只有部署脚本用到 paramiko;行空板端只用板载库。
项目思路来自开源项目 AgentPager(GPL-3.0),本实现复用了它的 state.snapshot 协议格式,因此行空板端可以直接对接官方 Bridge。
写在最后
做这个小东西最大的收获,不是学会了怎么在 framebuffer 上画字,而是意识到:AI 编程工具缺的不是能力,是「可观测性」。
它跑得快、干得多,但你不知道它在干什么。一块 2.8 寸的屏幕,把黑盒变成了透明的:你能看见它在读哪个文件、跑哪条命令、卡在哪一步。看见之后,信任感才建立得起来。
如果你也有一块吃灰的行空板,不妨试试。它可能不会让你写代码更快,但会让你在等 AI 跑任务的时候,少切几次窗口。
项目开源
云天 365/unihiker-agent-pager: 行空板 M10 AI Agent 状态终端:WorkBuddy Hook 实时状态、实体按键审批、8-bit 音效



