拍板使用说明
这份说明覆盖拍板的全部功能：板板（设备）、拍板 Hub（电脑端）、拍板小程序和云端中转。第一次用建议按顺序读 1–4 节，之后按需查。
- 1. 拍板是什么
- 2. 准备
- 3. 安装
- 4. 第一次设置
- 5. 接入 agent
- 6. 板板怎么用
- 7. 电脑端 Hub
- 8. 小程序
- 9. 不在同一个 Wi-Fi：云端中转
- 10. 升级、重置和迁移
- 11. 常见问题
- 12. 数据和隐私
1. 拍板是什么
Claude Code、Codex 这些 AI agent 在电脑上干活时，常常停下来问「可以执行这条命令吗？」「可以改这个文件吗？」。拍板把这些问题送到桌上的板板：它亮起来、一脸期待地看着你，你点一下就批准，歪一下就拒绝；活干完了，它换个开心的表情告诉你。你不用一直盯着终端。
| 部分 | 是什么 | 在哪儿 |
|---|---|---|
| 板板 | 桌上的小设备：1.47 寸屏幕、一个按键、姿态传感器、一颗灯 | 微雪 ESP32-S3-LCD-1.47B + 3D 打印外壳 |
| 拍板 Hub | 电脑上的程序：接收各家 agent 的事件，转给板板，再把你的决定送回去 | Windows（免安装 zip） |
| 拍板小程序 | 微信小程序：账号、给板板配网、提醒、问一句、绑定电脑 | 微信 |
| 云端中转 | 电脑和板板不在一个网络时帮忙转发 | Azure 香港 |
Claude Code / Codex / Qwen / Kimi / Gemini
│ hooks（本机）
▼
拍板 Hub（电脑）── 局域网 / 云端中转 ──▶ 板板
▲ 蓝牙
拍板小程序
2. 准备
- 硬件：微雪 ESP32-S3-LCD-1.47B，一根能传数据的 USB-C 线；可选 3D 打印外壳（hardware/proto-147）和 602025 锂电池。
- 电脑：Windows 10/11 x64。agent 装在这台电脑上。
- 手机：微信。
- 网络：2.4 GHz Wi-Fi（板板不支持 5 GHz），没有网页认证（酒店、公司的「登录页」Wi-Fi 板板过不去）。
3. 安装
最新版本都在项目主页和 Releases 上。
3.1 刷固件
第一次用整包 paiban-firmware-v*-merged.bin（16 MB，含分区表）：
pip install esptool
esptool.py --chip esp32s3 --baud 921600 write_flash 0x0 paiban-firmware-v0.5.1-merged.bin
以后升级用 -app.bin，刷到 0x10000，Wi-Fi、提醒、设置、账号绑定都保留：
esptool.py --chip esp32s3 --baud 921600 write_flash 0x10000 paiban-firmware-v0.5.1-app.bin
电脑认不出板子时：按住 BOOT 键再插 USB，进入下载模式。刷完按一下 RST 或重新插拔。
3.2 装电脑端
- 下载
paiban-hub-v*-win-x64.zip，解压到一个固定位置（比如D:\paiban-apps\PaibanHub）。 - 双击
PaibanHub.exe。Windows 提示「已保护你的电脑」时点「更多信息 → 仍要运行」（程序还没有数字签名）。 - 第一次运行会在开始菜单建快捷方式，并默认开机自启（可在设置里关）。
升级：退出 Hub（托盘图标右键 → 退出），用新版覆盖整个文件夹，再打开。设置和登录信息存在 %APPDATA%\拍板 Hub，不受影响。
3.3 小程序
小程序正式上线前，用微信开发者工具导入仓库里的 miniapp/，点「预览」用手机扫码。用到账号和云端中转时，需要开通微信云开发（见 miniapp/README.md）。
4. 第一次设置
- 板板上电：屏幕显示配网二维码，灯慢慢呼吸白光。
- 小程序配网：「我的 → 添加设备」，扫板板屏幕上的码（或在列表里选
BANBAN-xxxx）。连上后填 Wi-Fi 名称和密码，建议先点「测试连接」：板板会真的连一次，告诉你是密码不对、找不到这个 Wi-Fi，还是信号太弱。 - 自动找到电脑：板板和电脑在同一个 Wi-Fi 下，Hub 每 2 秒在局域网广播一次，板板听到就连上，屏幕左上角的点变绿。
- 找不到？可能路由器隔离了设备之间的广播（访客网络常这样）。在小程序「配网 → 电脑地址」选手动，填 Hub 概览页显示的地址（如
192.168.1.20:8765）。 - 接入 agent：Hub 左侧「接入 agent」，点 Claude Code（或别的）的「接入」。
- 试一下：Hub 概览页底部「测试审批」，板板会弹出一条审批，单击就批准。
5. 接入 agent
在 Hub「接入 agent」页点一下即可。Hub 会把 hooks 写进各家的配置文件，改之前自动备份，「撤销」只删拍板自己写的那几行，你原有的配置不动。
| 客户端 | 配置文件 | 审批能力 | 注意 |
|---|---|---|---|
| Claude Code | ~/.claude/settings.json |
完整：板板上批准 / 拒绝直接生效；「交回电脑」就照常在终端确认 | 后台任务 claude -p 没有确认框：启动前设环境变量 PAIBAN_HEADLESS_APPROVE=1，改文件和执行命令就会送板板审批 |
| Codex | ~/.codex/hooks.json |
完整 | 第一次接入后在 Codex 里输入 /hooks，把拍板的 hooks 标为信任 |
| Qwen Code | ~/.qwen/settings.json |
完整 | |
| Kimi Code | ~/.kimi-code/config.toml |
只能拦截：板板上拒绝会挡住；批准后 Kimi 自己的确认框可能还会出现 | 配合 --yolo 最顺手。只读命令不打扰你 |
| Gemini CLI | ~/.gemini/settings.json |
只能拦截 | 同上 |
- 会送审批的：执行命令、改文件、写文件这些有副作用的操作；读文件、搜索等只读操作不打扰你。
- 会发通知的：任务完成（显示 agent 最后一句话）、需要你看一下（比如它在问你问题）、出错。
- Hub 没开时：hook 连不上，agent 照常在终端里问你，不会卡住。
- 改了 Hub 端口：已接入的客户端要点一次「重新写入」。
其他程序也能用：
# 发通知
curl -X POST http://127.0.0.1:8765/notify -d '{"title":"备份完成","body":"共 12 GB","agent":"nightly"}'
# 发审批并等结果：allow / deny / defer（defer = 交回电脑或超时）
curl -X POST http://127.0.0.1:8765/approve -d '{"agent":"deploy","summary":"发布到生产","detail":"v2.3.1","timeout":120}'
6. 板板怎么用
6.1 一个键 + 姿态
屏幕横着用，USB 口在右手边。BOOT 键是唯一的按键。
| 屏幕 | 单击 | 双击 | 长按 | 手势 |
|---|---|---|---|---|
| 表盘 / Agent / 设备 | 下一页 | 上一页 | 勿扰（设备页：显示配网码） | 扣过来 = 勿扰；拍一拍、摇一摇、拿起来板板都有反应（见 6.7） |
| 等你批准 | 批准 | 拒绝 | 交回电脑 | 先放平，向右歪约 20° 并稳住 1 秒批准，向左拒绝 |
| 确认绑定账号 | 同意 | 拒绝 | — | 向右同意，向左拒绝 |
| 提醒 | 完成 | — | 10 分钟后再提醒 | 摇一摇 = 10 分钟后 |
| 通知 | 收起 / 下一条 | 全部清掉 | — | — |
| 问一句的回答 | 下一页 | 关闭 | — | — |
| 互动模式 | 换个把戏 | 回表盘 | 回表盘 | 倾斜滚动、摇晕、连拍三下变心心眼 |
60 秒没操作屏幕会调暗（板板变困）；有审批或提醒时自动亮起来。用电池时更省电：30 秒调暗、3 分钟熄屏，按键、拿起来、拍一下或有审批都会马上亮（见 6.8）。
倾斜批准怎么防误触：审批弹出后，要先把板板放平、放稳一下，倾斜才生效；歪过去（默认约 20°）以后要稳稳地保持 1 秒（中途晃动、刚被摇过或拍过都会重新计时）；只认左右歪，前后俯仰（比如拿起来看）不算；批准一次后要回到水平才能再用。小程序「设置 → 倾斜灵敏度」可以选灵敏（15°、0.8 秒）/ 适中（20°、1 秒）/ 迟钝（28°、1.3 秒）；也可以关掉倾斜，只用按键。
6.2 四个页面
- 表盘：时间、日期、板板的脸，以及 agent 的整体状态（待命 / 在做 / 等你 / 完成）。
- Agent：最近 6 个 agent 会话，每个显示项目名、正在做什么、状态和持续时间。
- 设备：名称、Wi-Fi、IP、电池、蓝牙、云端中转状态、Hub 地址、固件版本。长按显示配网二维码。
- 互动：和板板玩，倾斜它会滚来滚去。
6.3 表情和灯
| 表情 | 意思 | 灯 |
|---|---|---|
| 发呆、偶尔眨眼 | 待命 | 青色微光 |
| 眯眼点头 | agent 在干活 | 蓝色呼吸 |
| 眼巴巴看着你 | 等你批准 | 琥珀色快闪 |
| 着急冒汗 | 审批快超时 | 琥珀色快闪 |
| 开心 | 任务完成 | 绿色 |
| 掉眼泪 | 出错 | 红色呼吸 |
| 委屈 | 被你拒绝 | — |
| 睡着 | 勿扰 / 屏幕调暗 | 灭 |
| 灰色眼睛 + 问号 | 找不到电脑 | — |
| 紫色呼吸 | 提醒在响 | 紫色 |
6.4 审批
- 屏幕上：哪个 agent、做什么（比如「运行 npm test」「修改文件 report.md」）、具体内容、剩余时间。
- 超时（默认 90 秒，Hub 设置里可改）就交回电脑，agent 照常在终端里问你。
- 同时有电脑、小程序在线时，哪边先决定都算，其他地方的同一条自动收起。
6.5 通知、提醒、问一句
- 通知：任务完成 / 需要你看 / 出错时弹出，20 秒后自动收起；最近 6 条在小程序「设备」页也能看到。
- 提醒：在小程序「提醒」页添加（时间、每天 / 工作日 / 周末 / 自定义星期 / 只响一次、内容），最多 12 条。提醒存在板板上，断网也会响。单击完成，长按或摇一摇 10 分钟后再提醒。
- 问一句：在小程序「问一句」页选好由谁回答（电脑上装了的 Claude Code / Codex / Gemini / Qwen / Kimi 才会列出来），打字发送。问题经板板送到电脑，由那家 agent 回答；板板顶上显示「Codex 的回答」这样的标题，小程序的当前回答和历史记录也标着是哪家答的。需要 Hub 0.3、固件 0.6、小程序 0.6 以上。
6.6 勿扰
长按表盘页的 BOOT 键、把板板扣过来（屏幕朝下）、或在小程序里打开勿扰。勿扰时灯灭、通知不弹出；审批照常显示（不然 agent 会卡住）。
6.7 板板的心情
板板有自己的心情，闲着的时候表情不再一成不变：
- 作息：早上精神好、午后犯困、深夜很困；早上、中午、傍晚、深夜会各打一次招呼（「早上好！」「该吃午饭啦」「很晚了，早点睡」）。
- 天气：电脑端每半小时把当地天气发给板板（Hub 设置 → 板板的心情，可以关掉或指定城市）。表盘底栏显示「18° 小雨 · 一切安静」；下雨会听雨声、下雪会开心、太热会冒汗、冷了会撅嘴。
- 你怎么对它：拍一拍会开心，连拍三下变心心眼；摇一摇会晕，一直摇它会生气；剧烈地摇会害怕（「救命——」），然后委屈；放了很久被拿起来会好奇「要带我去哪？」；被歪着放时眼睛会往低的那边看。很久没人理它会有点失落。
- 工作：任务完成心情变好，出错会难过；电量很低时没精神。
- 小动作：闲着时每隔十几秒到半分钟会随机做个小动作：东张西望、哼歌、打哈欠、发呆、想好吃的、伸懒腰、打瞌睡……心情好、精神好时更活泼。
小程序首页会显示板板现在的心情（比如「一切安静 · 板板有点困」）。需要固件 0.7、电脑端 0.4 以上。
6.8 省电（电池供电）
小程序「设置 → 省电」有三档：用电池时省电（默认）、一直省电、不省电。
| 插着电脑 | 省电时 | |
|---|---|---|
| 调暗 | 60 秒没操作 | 30 秒没操作，CPU 降到 80 MHz，刷新率降到 10 帧 |
| 熄屏 | 不熄 | 3 分钟没操作：背光关、屏幕休眠、灯灭、Wi-Fi 进深度省电（消息晚到几百毫秒） |
| 亮起来 | 按键、拍一下、摇、拿起来；有审批、提醒、通知、回答时自动亮 | 同左 |
电量低于 3% 且持续 2 分钟，板板会进入深度睡眠保护电池；充上电后按 BOOT 键唤醒。
7. 电脑端 Hub
关窗口会缩到右下角托盘（可在设置里改成直接退出）。托盘图标会随状态变化：没运行、等设备连接、设备在线、有审批等你；鼠标悬停能看到详情，右键可以发测试通知或退出。
7.1 概览
- 板板的在线状态、地址、固件、型号、连接方式（局域网 / 云端中转）、连接时长。
- 等你批准的审批：电脑上也能直接点批准 / 拒绝 / 交回电脑。
- Agent 会话列表、最近的通知和审批结果、统计（批准 / 拒绝 / 交回 / 通知数）。
- 测试按钮：测试审批、测试通知、测试 agent 列表，不需要 agent 也能看板板的反应。
7.2 接入 agent
见第 5 节。每张卡片显示：是否找到这个命令、配置文件位置、审批能力、注意事项；「打开位置」直接在资源管理器里定位配置文件。
7.3 账号
登录 / 登出云端中转，查看和管理账号里的板板，见第 9 节。
7.4 动态
最近 500 条事件：agent 事件、审批、设备上下线、错误，可按「审批 / 设备 / 问题」筛选。
7.5 设置
| 设置 | 默认 | 说明 |
|---|---|---|
| 云端中转 | 开 | 登录后才有效；关掉就只走局域网 |
| 中转服务器 | 官方地址 | 一般不用改；改了要重新登录 |
| 端口 | 8765 | agent 的 hooks 和板板都连这个；改了要「重新写入」各客户端 |
| 等你批准的时间 | 90 秒 | 15–570 秒；超时交回电脑 |
| Kimi / Gemini 先送设备审批 | 开 | 关掉就只发通知 |
| 没有设备时在电脑上审批 | 关 | 打开：板板不在线时 Hub 窗口里弹审批 |
| 系统通知 | 开 | 窗口不在前台时，有审批就弹 Windows 通知 |
| 默认由谁回答 | Claude Code | 小程序里没选的时候用这家；它没装就用第一家装了的 |
| 各家的命令 | claude -p、codex exec --skip-git-repo-check -、gemini、qwen、kimi --print |
「问一句」用的命令，问题从标准输入传进去，答案取标准输出 |
| 外观 | 跟随系统 | 亮色 / 暗色 |
| 开机自动启动 | 开 | 启动后缩在托盘 |
| 关闭窗口时缩到托盘 | 开 |
8. 小程序
| 页面 | 功能 |
|---|---|
| 设备 | 当前板板的状态、正在等你批准的审批（手机上也能批）、agent 列表、最新通知；演示按钮（不用电脑也能看板板的反应）；互动模式开关；多台设备时可切换 |
| 提醒 | 添加 / 编辑 / 删除提醒，写进板板 |
| 问一句 | 打字问 agent，历史记录 |
| 我的 | 微信登录、头像昵称、设备列表（重命名、切换、移除）、电脑与云端中转、使用统计 |
| 设置（我的 → 设备设置） | 亮度、屏幕转 180°、时区、互动模式、左右倾斜审批、倾斜方向反转、扣过来勿扰、勿扰、校准「正放」、Wi-Fi、云端中转、重新识别引脚、重启、恢复出厂 |
小程序和板板之间是蓝牙，手机要在板板附近（约 10 米内）。
9. 不在同一个 Wi-Fi：云端中转
公司电脑 + 家里的板板、电脑连手机热点、以后的 4G 版，都靠云端中转。完整步骤和安全说明见 云端中转使用指南，简要流程：
- 电脑登录（每台电脑一次）：Hub「账号 → 登录」显示二维码，小程序「我的 → 电脑与云端中转 → 扫码绑定电脑」。
- 板板绑定（每台一次）：在 Hub 账号页点「绑定到账号」，或小程序配网后绑定；板板上要按确认。
- 之后自动选择：同一个 Wi-Fi 走局域网，不在就走中转；审批不会重复弹。
- 登出 / 解绑：Hub「账号 → 登出」；手机上可以远程解绑电脑和板板。
中转服务器是多副本部署的：服务器升级时连接会在一两秒内自动切换，板板上不会显示掉线，期间的审批也会补发。
10. 升级、重置和迁移
- 板板固件：刷
-app.bin到0x10000（3.1 节），设置都保留。设备页能看到版本号。 - Hub：覆盖整个文件夹（3.2 节）。
- 恢复出厂：小程序「设置 → 恢复出厂设置」。清掉 Wi-Fi、提醒、设置和中转令牌；绑定用的 claim key 保留，所以把板板送人后，新主人在板板上按确认就能绑到自己的账号。
- 重新识别引脚：姿态传感器或电池没识别出来时用，设备会重启。
- 从「灵犀」时期的旧版升级：设置会自动迁移，旧版 hooks 会被替换，见 docs/rename.md。
11. 常见问题
板板一直显示「正在找拍板 Hub」 - 电脑上 Hub 开着吗？（托盘里有图标） - 板板和电脑在同一个 Wi-Fi 吗？访客网络、AP 隔离会挡住广播 → 手动填 Hub 地址。 - Windows 防火墙第一次会问是否允许 PaibanHub 访问网络，要勾「专用网络」。
agent 要我确认，但板板没反应
- Hub「接入 agent」里这个客户端显示「已接入」吗？Codex 要在 /hooks 里信任一次。
- 板板在勿扰？（审批照常显示，但灯不亮）
- Hub「动态」页有没有收到事件？没有 → 「重新写入」一次。
Wi-Fi 测试提示「找不到这个 Wi-Fi」：板板只支持 2.4 GHz。双频路由器请把 2.4G 单独起个名字。
倾斜方向反了：小程序「设置 → 倾斜方向反过来」，或「校准正放」。
「问一句」提示命令运行失败：Hub 设置里那家 agent 的命令在终端里能直接运行吗？比如 echo 你好 | claude -p。
「问一句」一直「思考中」或提示没登录：命令行版的 Claude Code / Codex 要在终端里单独登录一次，桌面版的登录不通用。
电池显示「未检测到」：没接电池时正常；接了电池还这样，点「重新识别引脚」。
云端中转相关：见 云端中转使用指南 · 常见问题。
12. 数据和隐私
- 局域网模式：所有消息只在你的电脑和板板之间，不出局域网。Hub 的 hooks 只接受本机请求。
- 小程序：账号资料（昵称、头像）、设备列表、使用统计存在微信云开发；不开云开发时只存在手机上。
- 云端中转：只存账号的 HMAC（不存微信 openid）、电脑名、设备 ID 和令牌的哈希；审批内容只转发不保存。数据库每天备份，保留 30 天。服务器能看到转发中的消息内容，端到端加密是下一步。
- 注销：小程序「我的 → 退出登录」，云端账号资料可删除；电脑和板板在中转上的记录可在「电脑与云端中转」里逐个解绑。