排错 / 11建议耗时 按需
第 11 步｜故障排查地图
目标
遇到问题时从可观察事实出发，找到优先排查位置；不要随便换零件，也不要让 AI 推测代替测量和记录。
故障树
| 现象 | 先检查什么 | 不要先做什么 |
|---|---|---|
| 电脑没有串口 | USB 数据线、USB 口、开发板指示灯、Mac 设备树 | 反复刷未知固件 |
| 插 USB 后异常发热 | 立即断电，检查排母错位、焊锡桥连、屏排线方向 | 继续带电测试 |
| 固件提示芯片不匹配 | 商家芯片修订号、v1/v3 完整包 | 强制跳过版本检查 |
| 程序运行但黑屏 | DSI（非 CSI）、FFC Pin/方向、屏幕型号、固件对应版本 | 猜测驱动通用就换屏 |
| 花屏 / 方向不对 | 屏幕初始化、应用逻辑方向、屏模组批次 | 直接交换排线触点 |
| 某个按钮不工作 | 焊点、轴体引脚、外壳卡阻、设置映射 | 先改客户端源码 |
| 摇杆方向错误 | 摇杆型号与焊接方向、PCB 引脚定义 | 硬掰摇杆 |
| 有画面但不跟随 Codex | Mac 管理端是否在线、目标 Agent 是否运行、适配器支持范围 | 假定设备已能监控远程所有工作流 |
| 语音不可用 | 系统权限、服务 Key、输入框状态、麦克风 | 把 Key 发到 GitHub Issue |
| 盒子装不上 | STEP 版本、公差、螺母、排线和轴帽干涉 | 硬压或打胶封死 |
每次失败怎么记录
以“现象 → 条件 → 测量 → 假设 → 最小测试 → 结论”的格式写进 制作日志。示例：
现象：右键无反应。条件：裸机正常，装壳后不正常。测量：键帽与开孔边缘接触。最小测试：拆掉上壳重新按键。结果：恢复。结论：可能是结构公差，而不是 PCB 故障。此例仅示范写法，并非已发生的真实测试。
验收
- 有可复现的故障现象和实际版本信息。
- 已区分结构、供电、固件、屏幕、客户端、Agent 六类问题。
- 修复后重新跑受影响的验收项。
出问题怎么办
仍无法定位时，用 上游 GitHub Issues 或 立创项目评论区 查相同版号的案例。提问附非隐私的最小证据，明确标注“未验证”的推测；不要上传 API Key 或完整日志。
下一关：拍摄与剪辑模板