| name | card-onboard |
| description | Onboard a user setting up AI Desk Card for the first time, or after moving
to a new machine, plugging the device into a new network, or after a
firmware update. Detects daemon state, USB / BLE / Wi-Fi connection,
firmware version, and mDNS visibility — then walks the user through
whatever's missing (install firmware, plug USB, pair BLE, provision
Wi-Fi). Use whenever the user says "first-time setup" / "刚拿到设备" /
"卡片没反应" / "刷固件" / "怎么连卡片" / "ai-desk-card 连不上".
|
| trigger_keywords | ["card onboard","入职","第一次用","first-time setup","刷固件","怎么连卡片","ai-desk-card 连不上","配对","配 wifi"] |
| allowed-tools | ["Bash","Read"] |
card-onboard — AI Desk Card 首次接入流程
把用户从"刚拿到设备/啥都没装"带到"四个 widget 在屏上、Wi-Fi 在线、推帧
0.2 秒到位"。
一次性原则
- 永远先跑 probe，不要凭空问"你 daemon 启动了吗"。
scripts/probe.sh 一
次拿全所有状态。
- 每一步告诉用户当前进度："我看到 daemon 跑着了，但还没设备连接，
现在去查串口..."。不要静默操作。
- 失败别循环重试。卡住就停，把诊断结果给用户、让他决定。
- 优先推 Wi-Fi，不要默认走 USB-serial 或 BLE。Wi-Fi 单帧 0.2 秒，USB
1-32 秒，BLE 命令通但 frame 不通（已知问题）。
探针入口
bash $CLAUDE_PLUGIN_ROOT/skills/card-onboard/scripts/probe.sh
输出结构（JSON）：
{
"daemon": { "running": bool, "pid": int|null },
"transport": { "connected": bool,
"type": "SerialTransport|BLETransport|WiFiTransport|null" },
"firmware": { "our": bool, "note": str, "banner": str|null },
"serial_ports": [ "/dev/cu.usbserial-..." ],
"mdns_peer": { "ip": "192.168.x.y", "port": 9880,
"txt": { "fw": "0.8.0", "proto": "1" } } | null
}
firmware.our=true = 设备上跑的是我们的固件（daemon 发了 cmd:owner
2.5 秒内收到 ack:owner）。
mdns_peer != null = 设备已经在 LAN 上播 Wi-Fi，这是最理想的状态。
决策树（按顺序处理；命中分支就先修，再回到 probe 验证）
G — mdns_peer != null 且 transport.type != "WiFiTransport"
最理想状态被错过了。设备已在 Wi-Fi，但 daemon 没用 Wi-Fi。告诉用户：
设备在 Wi-Fi <ip> 已上线。你 daemon 没用它，估计是之前没重启过 daemon。
跑：
/card-stop && /card-start
回到 probe，应该看到 transport.type == "WiFiTransport"。
A — daemon.running == false
Daemon 没跑。跑 /card-start（自动选 Wi-Fi > USB > BLE）。等 1-2 秒重新
probe。
B — daemon.running == true && serial_ports == [] && mdns_peer == null
设备完全离线 — 没插 USB、Wi-Fi 也没起来。可能场景：
- 设备根本没启动：电池死了，或者没开机。让用户按一下电源键。
- 设备启动了但没配过 Wi-Fi：第一次开机或者 NVS 凭据被清了。需要先用
USB 把 daemon 连起来，再走 BLE pair →
/card-wifi-setup 喂凭据。让
用户插一条 USB-C 数据线（注意不是充电线）。
- 设备在 Wi-Fi 但不同网段：daemon 跑这台 Mac 跟设备不在同一个局域
网。让用户检查 Wi-Fi 是不是手机热点或公司客网。
C — transport.connected == false 但 serial_ports != []
USB 端口在但 daemon 没接上。最常见原因：上次 daemon 没释放干净，或者
M5Paper 那一头 USB 还在 boot。跑：
/card-stop && /card-start
还不行 → 给我看 probe + tail -20 "${TMPDIR:-/tmp}/ai_desk_card_daemon.log"。
D — transport.connected == true && firmware.our == false
USB 通了但固件不是我们的（裸板 / M5 出厂 demo / 旧 buddy 固件）。问：
设备已连接，但运行的不是 AI Desk Card 固件。要现在刷上吗？
（刷固件会清掉设备上的其他程序，30 秒内完成）
用户同意 → /card-install flash，等 5 秒重新 probe。
E — transport.connected == true && firmware.our == true 但 mdns_peer == null
固件就位但 Wi-Fi 没配过。强烈推荐配 Wi-Fi（之后单 widget 0.2 秒）。让
用户给出 SSID + 密码：
设备就绪。要不要现在配 Wi-Fi？这样以后推 widget 0.2 秒一帧，比 USB 快 100 倍。
告诉我 SSID 和密码，我帮你写到设备 NVS（凭据只存设备本地，不进 git）。
收到凭据 → 跑：
/card-wifi-setup "<SSID>" "<密码>"
等 15 秒重新 probe，看到 mdns_peer.ip → 成功。
如果用户不想配 Wi-Fi（"只是想看看效果"），直接进 分支 F。
F — 全绿，要不要推默认 widget
✅ 一切就位。问用户：
推一组默认 widget 上去看看？默认布局：
top-left = weather, top-right = ai-status,
middle = focus, bottom = todo
同意 → 切到 card-widget skill。
Z — 用户明确要用 BLE only（不推荐）
USB / Wi-Fi 都不想用的场景。注意：BLE 推 widget 数据不稳（已知问题，
小命令通、大块数据 device 端 onWrite 不触发）。提醒用户后：
- 拔 USB，daemon 自动 fallback 到 BLE
/card-stop && /card-start- daemon 自动扫描
Card-* 设备 → 1-2 分钟连上
- 重 probe →
transport.type == "BLETransport"
- 推 widget 失败时回到此分支建议配 Wi-Fi
安抚话术
- "为什么 e-ink 显示这么慢" → USB serial 32s/帧是 115200 baud 的物理上
限。Wi-Fi 是 0.2 秒。强烈建议配 Wi-Fi。
- "为什么屏幕一直显示之前内容" → e-ink 0 功耗保留最后一帧，特性不是 bug。
- "电量怎么不准" → 通过电池电压 > 4150 mV 判定"USB 在充"。刚拔 USB 电
池满电时也会显示 USB 模式，几分钟后会回归正常。
- "我想换显示的人名/二维码" → 编
ai-desk-card/assets/profile.yaml，
跑 /card-sleep 推送名片帧。
不要做的事
- ❌ 不要自动
/card-install flash — 总是先问用户
- ❌ 不要主动重启 daemon 或 device，除非用户同意（或走 /card-stop+start）
- ❌ 不要试图自己解析串口协议 — 走
/firmware-probe HTTP endpoint
- ❌ 不要跳过 mDNS 分支直接推 USB / BLE — Wi-Fi 是首选路径
- ❌ 不要把 SSID/密码记到 daemon log 或写进 git — 只通过
/card-wifi-setup 一次性写到设备 NVS
排错信息收集
如果用户卡某一步：
bash $CLAUDE_PLUGIN_ROOT/skills/card-onboard/scripts/probe.sh
tail -30 "${TMPDIR:-/tmp}/ai_desk_card_daemon.log"
ioreg -p IOUSB | grep -i 'usb\|m5\|silab\|ftdi' | head -10
把这些汇集给用户、问要不要发 issue 到 https://github.com/op7418/m5-paper-buddy
