card-onboard 用于把用户从刚拿到设备或未安装任何环境的状态,带到四个 widget 上屏、Wi-Fi 在线、推帧约 0.2 秒的就绪状态。它适用于首次设置,以及换新机器、设备接入新网络或固件更新后的重新接入。
用途与原则:每次先运行探针,不凭空询问 daemon 是否启动;每步向用户报告进度;卡住时停止并把诊断结果交给用户决定,不循环重试;连接方式优先 Wi-Fi,其次 USB-serial,BLE 仅作最后手段。
探针入口:bash $CLAUDE_PLUGIN_ROOT/skills/card-onboard/scripts/probe.sh,输出为 JSON,包含 daemon.running 与 pid、transport.connected 与 type、firmware.our 与 banner、serial_ports、mdns_peer(ip、port 9880、txt 中 fw 与 proto)。firmware.our=true 表示设备运行自家固件;mdns_peer 非空表示设备已在局域网广播 Wi-Fi,为最理想状态。
主要分支:mdns_peer 存在但 transport 非 WiFiTransport 时执行 /card-stop && /card-start;daemon 未运行时执行 /card-start;设备完全离线时检查供电、USB 数据线与网络网段;USB 有端口但未连接时重启 daemon 并查看日志;固件非自家时先征得用户同意再执行 /card-install flash;固件就位但未配 Wi-Fi 时用 /card-wifi-setup "<SSID>" "<密码>" 写入设备 NVS,凭据只存设备本地,不进入 git;全部就绪后可切到 card-widget 推送默认布局(top-left weather、top-right ai-status、middle focus、bottom todo)。
限制与注意:不要自动执行刷固件;不要未经同意重启 daemon 或设备;不要自行解析串口协议;不要跳过 mDNS 分支;不要记录 SSID 或密码到日志或仓库。BLE 下推 widget 数据不稳定,已知大块数据在设备端 onWrite 不触发。排查时可收集探针输出、tail -30 "${TMPDIR:-/tmp}/ai_desk_card_daemon.log" 和 ioreg -p IOUSB | grep -i 'usb|m5|silab|ftdi' | head -10。e-ink 保留最后一帧、USB 推帧 1-32 秒、电量显示延迟均为已知特性。具体价格、平台与完整安装步骤暂未提供。