luxonis-guide

Luxonis 指南

将用户引导至一个适合其当前情况的 Luxonis 技能。推荐下一条命令，然后停止。不要在这里执行该技能的工作。

最终只能处于以下一种状态：

• 已引导——指定一条下一步命令，并说明它在流程中的位置。
• 超出范围——当前情况不在第一阶段技能的服务范围内；指出缺少的技能，并指向文档或支持渠道。

流程

大多数工作沿着一条主线推进，另有一条支线。

主流程：想法 -> 可运行的演示

1. 让摄像头正常工作 -> luxonis-device-setup
2. 将想法整理成简报 -> luxonis-project-interview
3. 构建精简 PoC -> luxonis-build-poc

第 1 步和第 2 步的顺序灵活：即使还没有设备，也可以进行访谈，因此等待硬件的用户可以先梳理想法。第 3 步是汇合点——它需要简报和已验证的设备。

支线：出现故障、运行缓慢或令人困惑的情况 -> luxonis-troubleshoot。可在任意阶段转入此支线，然后回到主流程。

1. 了解情况

预检当前工作目录，查找流程标记。是否存在就是判断依据；无需深入解析。

!ls -1 2>/dev/null | grep -E '^(DEVICE|PROJECT_BRIEF)\.md$' || echo "no markers"

!cat PROJECT_BRIEF.md 2>/dev/null | head -3 || true

在支持 shell 注入的 Agent（例如 Claude Code）中，上述命令会在路由前执行并填入结果。在不支持的 Agent 中，请忽略这些命令，并自行列出目录内容／读取 PROJECT_BRIEF.md。

结合标记和用户的描述进行判断：

• 存在 DEVICE.md -> 设备已在此处完成验证。
• 存在 PROJECT_BRIEF.md -> 想法已整理成简报。

2. 路由

将情况对应到以下一项：

• 新摄像头，或不确定摄像头是否正常工作／能否连接 -> luxonis-device-setup。
• 有可正常工作的摄像头（或存在 DEVICE.md），但没有 PROJECT_BRIEF.md，且想要构建某个项目 -> luxonis-project-interview。
• 存在 PROJECT_BRIEF.md，且用户想让项目运行起来 -> luxonis-build-poc。
• 应用、管线或设备发现出现故障、运行缓慢或令人困惑的情况 -> luxonis-troubleshoot。

如果情况明确，立即路由。如果情况含糊不清（没有说明具体问题，或只说“帮我看看 OAK”之类），请只问一个澄清问题，然后做出决定：

你已经连接好并能正常使用摄像头了吗？还是目前只有一个想法？

绝不要再问第二个问题。不要开始梳理想法——那是 luxonis-project-interview 的工作，不是此路由器的工作。

设备故障与软件故障

“我的摄像头无法工作”有两种情况。此时正是通过唯一的澄清问题来判断的好时机：

• 软件故障——发现失败、管线报错、深度不准确、FPS 低或输出不明确 -> luxonis-troubleshoot。
• 设备故障——橙色 LED、无法启动、疑似校准故障 -> 这是硬件故障。应判为超出范围，联系 [email protected]，而不是进行故障排查。

3. 结束

已引导——指定下一条命令，并用一行说明它在流程中的位置：

下一步运行 /luxonis-device-setup——该步骤会验证摄像头，然后我们再梳理想法并进行构建。

插件安装可能会给命令添加命名空间，例如 /luxonis:luxonis-device-setup。

超出范围——不要强行路由。指出缺少的技能，并指引用户继续处理：

• 硬件故障（橙色 LED、启动失败、校准问题）-> [email protected]。
• 从 V2 迁移到 V3 -> 目前还没有对应技能；请指向下方文档（之后可能会新增技能）。
• 其他超出四项技能范围的情况（非 OAK 硬件、大规模生产／设备群部署）-> 指出具体情况，并指向 https://docs.luxonis.com。

文档

• 软件中心／入门指南 -- https://docs.luxonis.com/software-v3.md
• 故障排查索引 -- https://docs.luxonis.com/software-v3/troubleshooting.md