luxonis-troubleshoot

Luxonis 故障排查

恢复现有 OAK 路径。每次只更改一个原因，重新运行相同的观测，并在第一个失败层级处停止。

完成条件

原始失败观测通过，且下一个依赖检查仍能正常工作；或者标记为受阻，并指出明确的下一步操作。硬件故障（橙色 LED、启动失败、疑似校准问题）请联系 [email protected]。

切勿凭记忆臆造 DepthAI API。仅使用 DepthAI v3；不要混用 v2 API。

优先使用最可靠的来源：Luxonis MCP 工具（不同主机上显示的名称可能不同），然后是它们返回的确切示例或文档来源，再然后是 https://docs.luxonis.com/llms.txt，最后是实际观察到的行为；记忆仅用于一般推理。对于 oakctl 命令和标志，以已安装的 oakctl --help 为准，其优先级高于文档和 MCP：本地版本（可能较旧或为 beta）决定了此处能做什么，因此如果缺少当前文档中描述的功能，请基于本地版本进行处理，并建议更新 oakctl。如果观察到的主机或设备行为与文档或 MCP 矛盾，请以观察结果为准并注明冲突。如果离线，请依据 oakctl --help 和本地示例开展工作，并指出哪些事实尚未验证。

如果缺少 AGENTS.md，或者此任务需要主机工具链但缺少 oakctl，请指出 luxonis-workspace 并遵循其中的说明，然后继续。不要复制其中的操作流程。

如果存在，请阅读 docs/brief.md、docs/device.md、源代码、日志和证据。也请阅读可能存在的旧版根目录文件 PROJECT_BRIEF.md 和 DEVICE.md。这些文件都不是必需的。将 docs/device.md 视为设置说明；以实时状态为准。不要从头开始访谈。如果产品有误，请提及 luxonis-app。

1. 固定一个故障

说明一个预期观测，以及与之矛盾的最小实际结果。保留确切的运行和观测命令、本次复现所用的设备、拓扑、代表性输入、相关版本，以及可获取的完整 stderr、帧或使用方输出。

如果安全且范围明确，请先复现一次再编辑。对于间歇性故障，请收集多次有界观测并记录发生频率。

2. 定位第一个失败层级

按以下顺序检查，并在第一个失败处停止：

1. 主机工具链和导入。
2. 设备发现、传输、电源和独占访问。
3. 主机进程或 OAK App 生命周期。
4. 流水线构建、连接、注册和主题。
5. 传感器或回放输入。
6. 模型／归档输入、预处理、解析器和推理。
7. 同步、裁剪、跟踪、几何处理和应用状态。
8. 请求的文件、MQTT、API、UI、终端或其他最终输出。

如果设备路径未经验证，请使用 luxonis-device-setup。如需采集或回放整体录制内容，请使用 luxonis-record。如需验证有关实时帧、检测结果、深度、裁剪、轨迹或结构化流水线消息的说法，请使用 luxonis-inspect。请将外部输出与流水线证据分开验证。

一种快捷的判断方法：最小化的已知可用 DepthAI 代码片段能否打开设备并流式传输一帧？如果不能，问题位于设备／连接层。如果可以，则根据最接近的当前示例对应用进行二分排查。

崩溃／错误：在 DEPTHAI_LEVEL=debug 下重新运行。深度或输出异常：采集一帧。FPS 低：测量并记录数值。

3. 测试一个假设

解释为什么当前证据更支持某个原因，以及什么结果会证伪该假设。只更改一个原因。保持复现和观测命令不变。对同一未更改操作的重试不得超过两次；第三次尝试需要新假设或人工决策。

优先选择范围明确的修复：使环境与所选示例一致；修正一个地址、端点、队列、主题、连接或阻塞读取；恢复归档输入、解析器或标签顺序；让依赖跟踪和裁剪路径使用相同的已过滤检测结果。

不要一开始就进行大范围重写、更换模型、更新设备或更改拓扑。

4. 验证修复

重新运行最初失败的观察。如果通过，再运行下一个依赖检查，确保局部修复不会掩盖下游回归。报告根本原因、证据、已更改的文件、修改前后的确切命令、通过的检查，以及仍未验证的说法。

防护措施

• 执行 sudo/管理员操作、固件/操作系统更新、刷写、恢复出厂设置、Hub 采用、持久网络配置、全局 pip 操作或替换客户的制品前，先征求同意。
• 绝不从源代码编译 DepthAI。
• 不要假装 WSL 支持 USB。
• 绝不让多个相互竞争的进程同时访问同一设备。
• 对于训练、专有 SLAM 或完整的 ROS 系统：说明情况并停止。不要说 OAK 用例不可能实现。说明哪些事项仍由人工负责，并给出一个下一步。