doca-structured-tools-contract

DOCA 構造化ツールの契約

まず読むもの： ワークフローに 「doca-structured-tools-contract に従って、構造化ツールを優先する」 と書かれている場合は、必ずこのスキルを参照してください。 最初に ## エージェントの動作契約 を読み、次に該当するスキーマを ## スキーマ で確認します。ホストに構造化ツールがある場合は、その出力を優先してください。ない場合は、同じセクションにある手動の手順に切り替え、どちらの方法を使ったかを必ず報告してください。

対象範囲の境界。 ライブラリコードの作成は構造化ツールの対象ではありません。ライブラリのスキル名を示して、そこで終了してください。コミット前に仕様を確認することは対象範囲内です。validate-before-commit スキーマを適用してください。

このスキルが役立つ質問の例

references/examples.md を参照してください。

このスキルを読み込むタイミング

別のスキルのワークフローに 「構造化ツールを優先する」 と書かれている場合、またはユーザーが複数の手動コマンドをまとめた一度限りの回答を求めている場合は、このスキルを読み込んでください。具体的には、次のような場合です。

• 成果物ごとのスキルの「コマンド」付録が、このスキルを参照している。
• ユーザーが「DOCA のインストールについて、X を教えてくれるコマンドはありますか」と尋ねる。
• validate-before-commit の呼び出しがあるライブラリについて、ユーザーが「コミット前に X が有効かどうかを確認する方法」を尋ねる。
• エージェントが手動で回答を算出し、次回のために構造化ツールのワンライナーを提示しようとしている。

一般的な DOCA の概要、ライブラリ API に関する質問、またはゼロからのインストール手順では、このスキルを読み込まないでください。該当するライブラリスキル、doca-public-knowledge-map、doca-setup を使用してください。 プローブとフォールバックを実行するには、直接またはユーザーが実行するコマンドを通じて、対象ホストへのシェルアクセスが必要です。

このスキルを使用するすべてのエージェントの基本ルール

1. まず検出し、ツールがあると思い込まないでください。 各スキーマには、ツールがインストールされているかを判定するプローブコマンドが示されています。スキーマの出力を信頼できるものとして扱う前に、このコマンドを実行してください。
2. ツールがある場合は構造化ツールを優先し、ない場合は手動に切り替えてください。 プローブが成功し、出力が選択したスキーマに適合する場合、構造化 JSON が信頼できる情報源となります。プローブが失敗した場合、または出力が無効な場合は、手動の手順に従い、同等の回答を作成してください。
3. どちらの方法を使ったかを報告してください。 回答の冒頭で、"構造化 <helper> を使用（パス：<path>）" または "手動の手順に切り替え（構造化 <helper> のプローブに失敗：<reason>）" と伝えてください。スキーマで選択したヘルパーと実際のプローブ失敗理由に置き換え、選択したものとは別のヘルパーを決して報告しないでください。
4. スキーマはここで固定されます。スキルごとのオーバーレイは固定されません。 成果物ごとのスキルでは、スキーマを使用する「コマンド」付録の行を追加してもかまいませんが、スキーマを再定義してはなりません。スキーマの拡張はここで行い、参照する付録にはその内容が継承されます。
5. スキーマにない JSON フィールドを決して作らないでください。 貼り付けられた JSON の追加フィールドは参考情報です。境界としてスキーマを示してください。
6. スキーマが記述するのは契約であり、実装ではありません。 これを満たす実行ファイルの提供は、後続の PR で行われる予定です。このスキルは、他のスキルが公開前にインフラを認識できるようにするためのものです。そのため、ここに記載されているヘルパーは、現時点ではどこにもインストールされていません。利用可能なものとして提示したり、ユーザーにインストールを勧めたりしないでください。プローブを実行し、ないことを一行で報告してから、手動のフォールバックで回答してください。
7. 権限昇格を暗黙に行ってはいけません。 sudo が必要なフォールバックコマンドは、ユーザーが実行するために提示するか、承認済みの特権チャネルを通じてのみ実行してください。ヘルパーがないことを理由に、黙って権限を昇格させてはいけません。いずれの方法もない場合は、ユーザーに実行を依頼するか、その不足を報告してください。

エージェントの動作規約

Command の付録でこの規約が参照されるたびに、次の4ステップのループを実行します。

1. 検出。 スキーマのプローブコマンドを実行します。例： command -v doca-env、 test -f /opt/mellanox/doca/share/version-matrix.json、 command -v doca-capability-snapshot。プローブは読み取り専用で安全です。ヘルパーは PR2 まで延期されているため、プローブの失敗は想定内です。
2. 優先。 プローブが成功した場合は、構造化ツールを実行し、## Schemas のスキーマに従って JSON を解析します。解析が成功し、すべての必須フィールドが文書化された型である場合に限り、その結果を正式なものとして扱います。JSON の形式不正、フィールドの欠落、型の不一致があれば、構造化パスは失敗です。その失敗を報告し、ステップ3に進みます。追加フィールドは参考情報として無視します（ルール5）。有効な構造化出力を「再確認」するために、手動のコマンドチェーンを実行してはいけません。構造化出力がコマンドチェーンに取って代わります。
3. フォールバック。 プローブが失敗した場合は、同じスキーマのセクションに記載された手動のコマンドチェーンを、列挙された順に出力を組み合わせながらたどります。手動コマンドを利用できない場合は、その不足を明示し、該当するスキル（通常は doca-setup）に案内します。それでも解決できない場合は、不足しているコマンドを列挙し、回答を完了できないと伝え、不完全なデータを完全なものとして提示せずに終了します。
4. 報告。 次のいずれかで回答を始めます。
   • 「構造化 <tool> を使用しています（パス：<path>）。」 — プローブが成功し、出力が検証済みの場合。
   • 「手動のコマンドチェーンにフォールバックします（構造化 <tool> のプローブに失敗：<reason>）。」 — プローブが失敗した場合。プローブコマンドと理由を含めます。command -v の失敗は、PATH 上にないことを意味するのであり、確実に存在しないことを意味するわけではありません。インストールを提案してはいけません（ルール6）。
   • 「手動のコマンドチェーンにフォールバックします（<tool> の出力がスキーマ検証に失敗：<reason>）。」 — ヘルパーは存在するものの、出力の形式不正、必須フィールドの欠落、または型の無効がある場合。

報告ステップにより、エージェントが最初にヘルパーを試したことが確認できます。

スキーマ

質問の形式に応じてスキーマを選択します。環境／インストール状態には doca-env、機能の最小バージョンの照会には version-matrix、デバイスごとのライブラリ機能には capability-snapshot、仕様の検証には validate-before-commit、ホストと DPU の比較には2つの collect-state スキーマを使用します。スキルごとの Command 付録でスキーマが指定されている場合は、そのスキーマを直接使用します。各サブセクションには、1つの構造化ツール、そのプローブ、トップレベルの JSON 形式、およびプローブが失敗した場合にたどる手動のコマンドチェーンが記載されています。

doca-env --json スキーマ

検出プローブ： command -v doca-env（インストール時はdoca_capsと同じ$PATH上の場所です）。

トップレベルの構造（JSON オブジェクト）：

フィールド	型	備考
version	object	pkg_config / applications_version / doca_caps / bfb（string|null） / consistent（bool）
devices	array of object	表示されるPCIeファンクションごと：pcie_address（例：0000:03:00.0）、kind（PF|VF|SF）、name、representor_of（string|null）、state（active|down|unknown）、mtu（number）
libraries	array of object	公開DOCAライブラリごとに1つ：pkg_config_name、installed（bool）、pc_path（string|null）
sample_paths	array of object	ライブラリごとに1つ：library、path（ディスク上のサンプルのルート）
drivers	object	mlx5_core_loaded（bool）、mlx5_ib_loaded（bool）、kernel_version（string）
hugepages	object	available_2m（number）、available_1g（number）、mount_point（string|null）
host_kind	string	host | bluefield | unknown
bf_mode	string | null	smartnic | dpu | switch | null（host_kind != bluefieldの場合）

手動でのフォールバック手順（順番どおりに実行し、出力を組み合わせて同じ情報を構成します）：

1. pkg-config --modversion doca-common → version.pkg_config
2. cat /opt/mellanox/doca/applications/VERSION → version.applications_version
3. doca_caps --version → version.doca_caps
4. doca_caps --list-devs → devices配列（PCIeアドレス + 種別 + representor）
5. まずdoca-common.pcを検索します：find /opt/mellanox/doca -name doca-common.pc -print -quitの結果が空なら、そこで停止し、不完全なインストールの問題を示してdoca-setupに誘導します。空のglobは決して展開しないでください。それ以外の場合は、PCDIRをそのディレクトリに設定し、for pc in "$PCDIR"/*.pc; do pkg-config --exists "$(basename "$pc" .pc)" && echo "$pc"; doneを実行します → libraries配列。PCDIRがディレクトリではない場合、または解決されるモジュールがない場合は、問題を示してdoca-setupに誘導します。PCDIRは通常、DOCA 3.3以降では/opt/mellanox/doca/lib/<arch>-linux-gnu/pkgconfig、従来型または分割プロファイルのインストールでは/opt/mellanox/doca/infrastructure/lib/pkgconfigです。
6. ls /opt/mellanox/doca/samples/ → sample_paths配列
7. lsmod | grep -E '^mlx5_(core|ib)' + uname -r → driversオブジェクト
8. cat /proc/meminfo | grep -i Huge → hugepagesオブジェクト
9. dmidecode -s system-product-name（BlueFieldではcat /proc/device-tree/model） → host_kind
10. mlxconfig -d <pcie> q INTERNAL_CPU_MODEL → bf_mode（host_kind == bluefieldの場合）

version-matrix.json スキーマ

検出プローブ: test -f /opt/mellanox/doca/share/version-matrix.json。

トップレベルの構造（JSON オブジェクト）:

フィールド	型	備考
schema_version	string	この契約の semver。スキーマ変更時に更新されます
generated_at	string	ISO-8601 形式の生成タイムスタンプ
entries	array of object	（ライブラリ、機能）ペアごとに 1 行

エントリーごとの構造:

フィールド	型	備考
library	string	pkg-config のモジュール名（doca-flow、doca-rdma、doca-comch、…）
capability	string	機械可読な機能名。対応する doca_<lib>_cap_* クエリについては、ライブラリごとの Command 付録を参照してください
display_name	string	人が読めるラベル。報告時は引用符で囲みます
min_doca_version	string	その機能が利用可能になった最初の DOCA リリース（semver）
max_doca_version	string | null	利用可能だった最後のリリース（null = 現在も利用可能）
source_url	string	この行の根拠となった公開ドキュメントの URL
source_quote	string	この行の根拠となった公開ドキュメントの文章そのもの

手動での代替確認手順:

1. 対応するスキルの CAPABILITIES.md テーブルで、ライブラリと機能を特定します。
2. doca-public-knowledge-map を使用して、ライブラリごとのドキュメントページを取得します。
3. そのページで機能名を検索し、"available since" の文言をそのまま抜き出して引用します。
4. ユーザーのホストで pkg-config --modversion doca-<library> を実行して照合します。バージョンが "available since" の記載より古い場合、ドキュメントの内容にかかわらず、このインストールではその機能を利用できません。

capability-snapshot スキーマ

検出プローブ: command -v doca-capability-snapshot（インストール時は doca_caps と同じ $PATH）。

トップレベルの構造（JSON オブジェクト）:

フィールド	型	備考
snapshot_at	string	ISO-8601 形式のタイムスタンプ
doca_version	string	スナップショット作成時点の doca_caps --version
host_kind	string	host | bluefield
devices	array of object	doca_devinfo ごとに 1 つ。pcie_address、library_capabilities（ライブラリから機能フラグへのマップ）を含みます

手動での代替確認手順:

1. doca_caps --list-devs → デバイス列挙
2. デバイスごとの詳細：doca_caps --pci-addr <bdf>（副作用なし。doca-caps を参照）。出力されない機能が必要な場合に限り、同梱サンプルのライブラリ独自の ## test ワークフローを使用します。スナップショットのために新しいテストコードを書くことは絶対に避けてください。

validate-before-commit スキーマ

検出プローブ： command -v doca-validate。ライブラリ固有のコンストラクター時検証サーフェスは検出プローブではなく、状態を変更する可能性があります。公開されている Flow ヘッダーには doca_flow_pipe_validate シンボルはありません。決してこれをでっち上げたり、ヘルパーの有無をテストするために doca_flow_pipe_create を使ったりしないでください。

トップレベルの形式（JSON オブジェクト）：

フィールド	型	備考
library	string	仕様の対象となる DOCA ライブラリ
spec_path	string	検証対象の仕様ファイルのディスク上のパス
result	string	pass | fail | skip
checks	array of object	チェックごとの項目：name、status（pass | fail | skip）、details、remediation（string | null）

手動フォールバックの手順：

1. 該当するスキルの ## test ワークフローで、ライブラリ固有の検証サーフェスを確認します。一部のライブラリでは専用の _validate 呼び出しを使用します。状態を変更する _create 内のコンストラクター時チェックは、読み取り専用のバリデーターではありません。特に、doca_flow_pipe_create は前提条件を満たした後に実行する doca-flow TASKS.md ## test に属します。コミット前のプローブとして決して呼び出さないでください。呼び出し元が読み取り専用の検証を求めていて、API に専用のバリデーターがない場合は、result: skip を報告し、ライブラリごとの ## test ワークフローに案内して終了します（手順 2 と 3 はスキップします）。
2. コミット／作成／送信の呼び出しより前に、その読み取り専用バリデーターを呼び出します（状態を変更する _create は決して呼び出しません）。
3. 結果を適切に対応付けます。DOCA_ERROR_INVALID_VALUE と DOCA_ERROR_NOT_SUPPORTED は result: fail とします。権限、トランスポート、デバイス利用不可、その他の運用上のエラーは result: skip とし、doca_error_get_descr() のテキストと修正方法を checks エントリーに記載します。検証を実行できないことを仕様の失敗にしてはいけません。

collect-host-state および collect-dpu-state のスキーマ

コマンドを実行する側に対応するヘルパーを選択します。ホストでは doca-collect-host-state を、BlueField では doca-collect-dpu-state を使用します。両方が存在していても、相手側へのアクセスが可能とは限りません。差分を確認する場合は、各側で個別に収集して比較します。

検出プローブ： command -v doca-collect-host-state（ホスト）／ command -v doca-collect-dpu-state（BlueField）。

トップレベルの形式（JSON オブジェクト）、両方で共通：

| side | string | host | dpu | | doca_version | string | doca_caps --version | | firmware_version | string | flint -d <pcie> q の出力（sudo） | | kernel_version | string | uname -r | | mlx5_modules | array of string | 読み込まれている mlx5_* モジュール | | bf_mode | string | null | smartnic | dpu | switch | null | | devices | array of object | PCIe 機能ごとの項目：pcie_address、kind（PF | VF | SF）、state、mtu、representor_of |

手動フォールバックの手順（各側）：

1. doca_caps --version → doca_version
2. uname -r → kernel_version
3. lsmod | grep mlx5 → mlx5_modules
4. devlink dev show + lspci | grep Mellanox + ip -j link → devices と PCIe アドレスを列挙
5. 検出した PCIe ターゲットごとに、承認済みの特権チャネル経由で flint -d <pcie> q を実行 → firmware_version
6. 検出した BlueField ターゲットで、mlxconfig -d <pcie> q INTERNAL_CPU_MODEL を実行 → bf_mode

両側の形式は対称なので、ホスト ↔ BlueField 間の不一致を診断する際にエージェントが差分を確認できます。

PR2 実行ファイルとの関係

ここに記載したヘルパーはまだ提供されていません（基本ルール 6）。提供された際は、上記のスキーマを変更せずに満たします。他のスキルに遡及的な改修は必要ありません。