luxonis-build-poc

Luxonis Build POC

実機の OAK デバイスでブリーフの中核的な価値を実証する、実行可能な最小限のスライスを構築します。パイプラインを一から考案するのではなく、最も近い既知の正常動作する Luxonis の例を適応してください。広範囲にわたるものの配線が不十分なアプリより、エンドツーエンドで動作する垂直スライスを 1 つ用意するほうが優れています。

最後は、次のいずれか 1 つの状態にしてください。

• running-demo -- スライスが動作し、ブリーフで求められている成功の観察結果を示します。報告する正確なコマンド／スニペットを再実行して、そのことを証明してください。
• blocked -- ローカルで実行可能なデモに到達できません。阻害要因となっているレイヤーを 1 つ、その証拠、次のアクション（例：luxonis-device-setup でデバイスを確認する）とともに報告してください。

基本方針

- **既知の正常動作する例を適応し、DepthAI API を記憶だけで考案しないでください。** API 呼び出しは、クローンした例または参照したドキュメントのページに必ず紐付けてください。 - **パイプラインのコードを書く前に `depthai` のバージョンを確認してください。** 必ず DepthAI v3 を対象とし、v2 は対象にしないでください。両者には大きな違いがあります。インストール済みのメジャーバージョンに合わせ、v3 のコードに v2 の API を混在させないでください。DepthAI v3 では、`ColorCamera`／`MonoCamera` はすべてのプラットフォーム（RVC2、RVC4 の両方）で非推奨です。`Camera` ノードを使用してください。 - **まず垂直スライスを 1 つ用意してください。** 2 つ目の動作、オプション、仕上げを追加する前に、単一の経路をエンドツーエンドで動作させてください。 - **DepthAI をソースからコンパイルしないでください。** それが必要と思われる場合は、**blocked** としてください。

1. 事前確認

作業ディレクトリとユーザーの入力を確認してください。PROJECT_BRIEF.md（構築するもの）と DEVICE.md（以前に確認済みのデバイスについてキャッシュされた記録）が存在する場合は、読み込んでください。自分で必要な情報を確認し、Luxonis の関連スキルが別途インストールされていると決めつけないでください。まずブリーフを確認し、次にデバイスを確認してください。

ブリーフ。 PROJECT_BRIEF.md がない場合、目的に特化したツールは /luxonis-project-interview です（ユーザーが利用できる場合）。利用できない場合は、目標（動作、対象、成功の観察結果）を 1 段落にまとめて、そのまま続行してください。ここで詳細なインタビューは実施しないでください。

デバイス。 実行可能なデモは実機で動作します。DepthAI は OAK が接続されていないと動作しません（RVC2 と RVC4 の両方）。ホストのみでの動作モードやシミュレーションモードはありません。リプレイはデバイス上の入力ソースであり、デバイスの代わりにはなりません。DEVICE.md は確認の手掛かりであって、デバイスが接続されている証拠ではありません。また、情報が古い可能性もあります。ファイルの有無ではなく、ライブ接続の可否でデバイスを確認してください。

• DEVICE.md がある場合は、記録内容を簡単なライブチェックと照合してください。記録されたデバイスを引き続き開けるなら、それを使用してください。代わりに別のデバイスが見つかった場合は、ライブ検出の結果を優先してそのデバイスを使用し、DEVICE.md の更新を提案してください。
• DEVICE.md がない場合でも、「デバイスなし」と決めつけないでください。最小限の到達性プローブを実行してください（既知の正常動作する DepthAI スニペットでデバイスを開き、1 フレームをストリーミングできるか）。ここではこのプローブのみを実施してください。USB／udev、PoE、アドプションに関する実際のセットアップ作業が必要な形で失敗した場合は、/luxonis-device-setup に引き継いでください。
• デバイスに到達できる場合 -> スライスを構築して実行してください（通常はこれで running-demo になります）。
• デバイスに到達できない場合 -> スライスを構築し、正確な実行コマンドを準備してから、blocked で終了してください。スライスのコードは完成しており、実行準備もできていますが、動作の証明には確認済みのデバイスが必要です。/luxonis-device-setup を実行してから、このスキルを再実行してください。

2. ナレッジの参照

Luxonis 固有の事実（デバイスの機能、API／SDK、コマンド、バージョン要件）については、必ず `https://docs.luxonis.com/llms.txt` から最新のドキュメントを読み、リンク先の `.md` ページをたどってください。ドキュメントに記載がない場合に限り、ウェブ検索を行ってください。こうした事実について、モデルの記憶を根拠に回答してはいけません。

実装の参考には、クローンしたサンプルコードを使用してください。参照先は、DepthAI v3 に対応する main ブランチ上の、厳選された oak-examples リポジトリだけです。実際にサンプルを使う段階になってからクローンしてください。

• ~/.luxonis/agent-context（ユーザーのホームディレクトリ内の .luxonis/agent-context フォルダー）が存在しない場合は作成してください。
• https://github.com/luxonis/oak-examples を HTTPS 経由（SSH は使用しないでください）で、main に固定して浅くクローンしてください。ネットワークが停止しても処理がハングせず中断されるよう、git の低速時ガード（http.lowSpeedLimit=1000、http.lowSpeedTime=60）を設定してください。ホストのシェルに適したコマンドを使い、一時的な隣接パス（例：oak-examples.tmp）にクローンして、成功した場合に限り所定の場所へ名前を変更してください。これにより、クローンが失敗しても不完全なチェックアウトが残りません。チェックアウトがすでに存在する場合は、早送りのみのプルで更新してください。
• チェックアウトに INDEX.md が含まれている場合に限り、使用可能です。クローンが失敗した場合やディレクトリが不完全な場合は、サンプルを利用不可として扱い、最新のドキュメントを参照してください。不完全なチェックアウトを読んだり、ウェブ検索で見つけた古いサンプルや v2 時代のサンプルで代用したりしてはいけません。常に DepthAI v3 を使用し、v2 は使用しないでください。

エージェント向けカタログを使ってチェックアウト内を調べてください。INDEX.md（概要を Tags／Shape／Mode に照らして確認）と ESSENTIAL_KNOWLEDGE.md（共通の用語を確認）を読み、次に選んだサンプルの AGENTS.md、その後に README.md を読んでください。oakctl がある場合は、oakctl app examples list でサンプルを参照する方法もあります。

3. 概要に基づいて実行方法を選ぶ

概要で指定された希望する実行場所とデバイスファミリーによって、構成が決まります。

• カメラに接続したノートパソコン／コンピューター -> ホスト側スクリプト（Shape: script、 Mode: host）。ホスト上で実行する、depthai を使った通常の Python です。
• コンピューターを接続せず、カメラ上で実行 -> スタンドアロン OAK アプリ（Mode: standalone）。 oakapp.toml とともにパッケージ化し、oakctl app run で実行します。RVC4／OAK4 が必要です。

対象が不明な場合は、質問を 1 つだけしてください。両方を作ってはいけません。選んだ実行方法と Shape／Mode がすでに一致するサンプルを選び、変換ではなく適応を行ってください。

4. 垂直スライスを 1 つ作る

最も近いサンプルを出発点にし、概要の主要な動作を実現するために変更を最小限に抑えてください。ホストの依存関係は分離された 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>
  

実行に失敗した場合は、仮説を1 つずつ検証し、同じコマンドを再実行してください。変更を積み重ねたり、デバイスへのコマンドを並行して実行したりしないよう、変更を順番に適用します。再実行に成功した場合に限り、running-demo と宣言してください。実行できない場合（デバイスがない、またはオフラインの場合）は、その旨を明確に伝え、blocked としてください。実行していないデモを実行済みと主張してはいけません。

スライスが実行できたら、そこで終了してください。前提条件、正確な実行コマンド、明らかな次の手順をチャットに記録します（ユーザーが希望する場合は、短い POC_NOTES.md に記録してもかまいません）。求められていない範囲の拡張は行わないでください。

ガードレール

• 特権操作や永続的な変更には事前確認を求めます。 グローバルな pip／プロジェクト依存関係の変更、OS の更新、フラッシュ、工場出荷時設定へのリセット、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