luxonis-build-poc

Luxonis 构建概念验证

通过改造最接近且已验证可用的 Luxonis 示例，在真实 OAK 设备上构建一个最精简的可运行切片，展示需求的核心价值，而不是从头发明一套流水线。一个端到端运行的垂直切片，胜过一个范围很广但只接了一半线的应用。

最终状态必须且只能是以下一种：

• running-demo——切片能够运行并展示需求中核心的成功现象，且已通过重新运行你报告的确切命令／代码片段验证。
• blocked——无法在本地运行演示；请报告唯一的阻塞环节、证据和下一步操作（例如，使用 luxonis-device-setup 验证设备）。

核心原则

- **改造已验证可用的示例；切勿凭记忆臆造 DepthAI API。** 每个 API 调用都必须对应到你克隆的示例或阅读过的文档页面。 - **编写流水线代码前，确认 `depthai` 版本。** 始终使用 DepthAI v3，而非 v2——两者差异显著；应与已安装的主版本匹配，绝不可在 v3 代码中混用 v2 API。在 DepthAI v3 中，所有平台（RVC2 和 RVC4 均包括在内）上的 `ColorCamera`／`MonoCamera` 都已弃用——请使用 `Camera` 节点。 - **先完成一个垂直切片。** 在添加第二种行为、选项或润色前，先让单一路径端到端运行。 - **绝不可从源码编译 DepthAI。** 如果这似乎是必要的 -> **blocked**。

1. 预检

查看工作目录和用户输入。如果存在，请阅读 PROJECT_BRIEF.md（要构建什么）和 DEVICE.md（之前验证过的设备的缓存记录）。请自行完成准备工作：不要假定已安装其他任何 Luxonis 技能。先确认需求，再确认设备。

需求。 如果没有 PROJECT_BRIEF.md，则在用户具备该工具时使用专用工具 /luxonis-project-interview；否则，在对话中用一段话记录目标（行为、目标对象、成功现象）并继续。此处不要进行完整访谈。

设备。 运行中的演示必须在真实硬件上执行：DepthAI 无法在没有已连接 OAK 的情况下运行（RVC2 和 RVC4 均如此——不存在纯主机或模拟模式），回放是设备上的输入源，不能替代设备。DEVICE.md 是提示，不能证明设备已连接，而且记录可能已过时。应通过实时可达性确认设备，而不是依据文件是否存在：

• 存在 DEVICE.md -> 通过快速实时检查核对其内容。如果记录的设备仍能打开，就使用该设备。如果发现的是另一台设备，则以实时发现结果为准，使用该设备，并提出更新 DEVICE.md。
• 不存在 DEVICE.md -> 不要假定“没有设备”。运行最小可达性探测（已验证可用的 DepthAI 代码片段能否打开设备并传输一帧）。此处只进行这项探测；如果探测失败且需要实际配置工作（USB／udev、PoE、接管），则转到 /luxonis-device-setup。
• 设备可达 -> 构建切片并运行（通常可达到 running-demo）。
• 没有设备可达 -> 构建切片并准备确切的运行命令，然后以 blocked 结束：切片代码已完成并准备就绪，但需要经过验证的设备才能证明其可运行——运行 /luxonis-device-setup，然后重新执行此技能。

2. 知识来源

对于任何 Luxonis 特定事实（设备功能、API/SDK、命令、版本要求）， 请从 `https://docs.luxonis.com/llms.txt` 开始查阅实时文档，并打开其中链接的 `.md` 页面；只有文档未涵盖时，才进行网络搜索。绝不要根据模型 记忆回答此类事实。

将克隆的示例代码用作实现参考——且只能使用精选的 oak-examples 仓库的 main 分支，该分支跟踪 DepthAI v3。仅在准备好改编示例时才 克隆，避免过早克隆：

• 如果目录 ~/.luxonis/agent-context（用户主目录中的 .luxonis/agent-context 文件夹） 不存在，请创建该目录。
• 通过 HTTPS 克隆 https://github.com/luxonis/oak-examples（绝不使用 SSH），采用浅克隆 并固定到 main，同时启用 git 的低速保护（http.lowSpeedLimit=1000、 http.lowSpeedTime=60），以便网络停滞时中止，而不是一直挂起。克隆到临时的同级路径 （例如 oak-examples.tmp），仅在成功后才将其重命名到位；使用适合主机 shell 的命令， 确保克隆失败不会留下不完整的检出。如果检出已存在，则改用仅快进的拉取来更新。
• 检出仅在包含 INDEX.md 时才可用。如果克隆失败或目录不完整，请将示例视为不可用 并回退到实时文档。绝不要读取不完整的检出，也绝不要替换为网络搜索找到的、较旧的 或基于 v2 的示例：始终使用 DepthAI v3，绝不使用 v2。

使用面向 Agent 的目录浏览检出内容：阅读 INDEX.md（根据 Tags/Shape/Mode 匹配 需求简介）和 ESSENTIAL_KNOWLEDGE.md 以了解通用术语，然后阅读所选示例的 AGENTS.md，最后阅读其 README.md。如果有 oakctl，也可以使用 oakctl app examples list 浏览。

3. 根据需求简介选择运行路径

需求简介中的预期运行位置和设备系列共同决定方案：

• 摄像头连接到笔记本电脑/计算机 → 主机端脚本（Shape: script、 Mode: host）。使用纯 Python 和 depthai，在主机上运行。
• 在摄像头上运行，不连接计算机 → 独立 OAK 应用（Mode: standalone）， 使用 oakapp.toml 打包，并通过 oakctl app run 运行。需要 RVC4/OAK4。

如果目标不明确，提一个问题即可；不要两种方案都做。选择 Shape/Mode 已符合所选路径的示例， 以便改编，而不是转换。

4. 构建一个垂直切片

从最接近的示例开始，尽可能少做改动，以实现需求简介中的主要行为。主机依赖项只能安装在 隔离的 venv 中——绝不使用全局 pip，未经批准绝不修改项目依赖项。对于独立应用， 保留示例的 oakapp.toml 结构，仅调整此切片所需的内容。

5. 验证，然后停止

需求简介中的成功标准定义了“可用”。运行切片，并记录能够证明其成功的具体观察结果。

• 主机脚本： python3 main.py（在 venv 中运行）——观察预期输出/叠加层。

• 独立应用：

  oakctl app run <app-dir>                 # uses oakapp.toml; add -d <id> to pin the device
  oakctl app run <app-dir> --detach        # then: oakctl app list / app logs / app stop <id>
  

运行失败时，一次只验证一个假设并重新运行相同的命令——按顺序进行更改，绝不堆叠修改或运行 相互竞争的设备命令。只有在重新运行成功后才能声明为运行中的演示；如果无法运行（没有设备/处于离线状态）， 请如实说明并标记为受阻——不要声称演示已运行，除非它确实运行过。

切片运行成功后就停止。在聊天中记录假设、确切的运行命令和明显的后续步骤 （如果用户需要，也可以写入简短的 POC_NOTES.md）。不要擅自扩大范围。

安全护栏

• 对高权限或持久性操作设置确认门槛。 更改全局 pip/项目依赖、更新操作系统、刷写固件、恢复出厂设置、采用 Hub、发布应用 -> 需先确认。在本地构建并运行开发应用没有问题。
• 使用模型，而非训练模型。 复用 DepthAI Model Zoo / 示例模型。如果目标需要自定义模型，请说明需要数据集/训练——不要声称能在这里训练模型。
• 如实说明 WSL 的 USB 限制。 不要假装 WSL 可以访问 USB；在用户接入设备，或改为在可直接访问 USB 的主机上运行之前，应停止操作。
• 硬件故障（橙色 LED、启动失败、疑似校准问题）-> 阻止操作，联系 [email protected]。
• 如果是已有程序出现故障、运行缓慢或令人困惑，而非新构建的程序，则应由 luxonis-troubleshoot 处理。

文档

• 软件中心 / 入门指南 -- https://docs.luxonis.com/software-v3.md
• 文档源索引 -- https://docs.luxonis.com/llms.txt
• oakctl CLI（运行/构建/管理应用）-- https://docs.luxonis.com/software-v3/oak-apps/oakctl.md
• oakapp.toml 配置 -- https://docs.luxonis.com/software-v3/oak-apps/configuration.md
• V2 与 V3 迁移 -- https://docs.luxonis.com/software-v3/depthai/tutorials/v2-vs-v3.md
• 示例（目录见 INDEX.md）-- https://github.com/luxonis/oak-examples