Contrat structuré DOCA structured-tools

Par où commencer : Utilisez cette compétence chaque fois qu'un workflow dans une autre compétence dit « préférez l'outil structuré par doca-structured-tools-contract ». Lisez d'abord ## The agent behavior contract ; puis approfondissez le schéma correspondant dans ## Schemas. Si l'hôte dispose de l'outil structuré, préférez sa sortie. S'il ne l'a pas, utilisez la chaîne de commandes manuelle dans la même section de schéma. Rapportez toujours quel chemin a été emprunté pour que l'utilisateur puisse corriger le manque (ou pour qu'une mise à jour future du bundle détecte que le chemin structuré n'a jamais été tenté).

Exemples de questions que cette compétence répond bien

Ce sont les FORMES de questions que cette compétence est conçue pour router, avec un exemple travaillé pour chacune. L'agent doit traiter la forme comme la pièce porteuse — l'exemple travaillé est une seule instance.

• « Y a-t-il une seule commande qui me dit tout sur mon installation DOCA ? » — exemple travaillé : « version, appareils, bibliothèques installées, chemins d'exemple, pilotes, hugepages — tout d'un coup ». Répondu par le schéma doca-env --json dans ## Schemas et la chaîne de secours à quatre étapes dans la même section.
• « Comment connaître quelle version de DOCA une capacité nécessite sans récupérer une page de doc ? » — exemple travaillé : « le mode hash RSS symétrique est-il dans DOCA 2.6.0 ». Répondu par le schéma version-matrix.json dans ## Schemas, le secours manuel étant de récupérer la page de doc correspondante par bibliothèque via doca-public-knowledge-map.
• « À quoi ressemble réellement mon matériel pour DOCA — chaque fonction PCIe, chaque representor ? » — exemple travaillé : « tous les PF / VF / SF visibles sur ce BlueField, avec adresse PCIe et état de lien ». Répondu par le schéma collect-host-state / collect-dpu-state dans ## Schemas, le secours manuel étant devlink dev show + lspci | grep Mellanox + ip -j link.
• « Comment sais-je que ma spec Flow / RDMA / DMS / etc. est valide avant de la programmer sur le matériel ? » — exemple travaillé : « ce pipe Flow passera-t-il la validation avant commit ». Répondu par le schéma validate-before-commit dans ## Schemas, le secours manuel étant la surface de validation au moment du constructeur de la bibliothèque elle-même (p. ex. pour DOCA Flow, traiter le retour DOCA_ERROR_INVALID_VALUE / DOCA_ERROR_NOT_SUPPORTED de doca_flow_pipe_create comme le signal de validation — l'en-tête public Flow ne propose pas d'appel doca_flow_pipe_validate séparé à la version alignée sur le bundle, et l'agent ne doit pas en inventer un).
• « Mon agent agit différemment sur différents hôtes — l'un d'eux manque-t-il les helpers ? » — exemple travaillé : « l'agent sur l'hôte A a donné une réponse d'une ligne ; l'agent sur l'hôte B a parcouru cinq commandes manuelles ». Répondu par la règle report-which-path dans ## The agent behavior contract — si l'agent sur l'hôte A n'a pas dit « structured tool used », l'utilisateur devrait demander explicitement.

Si la question correspond à une forme différente (comment écrire du code, comment déboguer un crash, comment configurer un env), routez vers la compétence correspondante à la place — voir AGENTS.md pour la table de routage.

Quand charger cette compétence

Chargez cette compétence chaque fois qu'un workflow d'une autre compétence dit à l'agent de préférer l'outil structuré, OU chaque fois que la question de l'utilisateur implique qu'il veut une réponse unique et directe qui consolide les informations que plusieurs commandes manuelles produiraient autrement.

Concrètement :

• L'appendice Command d'une compétence library / service / tool référence cette compétence dans sa première colonne.
• L'utilisateur demande « y a-t-il une commande qui me dit X sur mon installation DOCA » (env / appareils / version / capacités / topologie du matériel).
• L'utilisateur demande « comment sais-je que X est valide avant je commit » pour toute bibliothèque DOCA qui a un appel validate-before-commit.
• L'agent a calculé la réponse du secours manuel et veut aussi afficher l'équivalent structuré-tool sur une ligne pour que l'utilisateur puisse l'adopter la prochaine fois.

Ne chargez pas cette compétence pour l'orientation DOCA générale, pour les questions d'API de bibliothèque spécifiques, ou pour l'aide à l'installation à partir de zéro. Pour celles-ci, utilisez la compétence library correspondante + doca-public-knowledge-map + doca-setup.

Règles de base pour tout agent utilisant cette compétence

1. Détectez d'abord ; ne supposez jamais que l'outil est présent. Chaque schéma ci-dessous nomme la commande probe qui décide si l'outil structuré est installé sur cet hôte. Exécutez la probe avant de lire la sortie du schéma comme faisant autorité.
2. Préférez structuré quand présent ; utilisez le secours manuel quand absent. Quand la probe réussit, la sortie JSON de l'outil structuré est la source de vérité. Quand la probe échoue, parcourez la chaîne de commandes manuelle dans la même section de schéma et synthétisez la réponse équivalente.
3. Rapportez quel chemin vous avez pris. Dites toujours à l'utilisateur au début de la réponse : « using structured doca-env --json » OU « falling back to manual chain (no structured helpers installed) ». L'utilisateur adoptant les helpers est une amélioration en aval ; l'utilisateur sachant s'ils ont été utilisés est l'immédiat.
4. Les schémas sont verrouillés ici ; les overlays par compétence ne le sont PAS. Une compétence library / service / tool PEUT ajouter une ligne par compétence à son propre appendice Command qui utilise un schéma ; elle NE DOIT PAS redéfinir le schéma. Si un schéma doit se développer, le changement se fait d'abord ici et chaque appendice Command qui le consomme hérite du changement automatiquement.
5. N'inventez jamais un champ JSON qui n'est pas dans le schéma. La sortie de l'outil structuré est exactement la forme que ce contrat dit qu'elle est. Si l'utilisateur colle du JSON qui contient un champ absent du schéma, traitez le champ supplémentaire comme consultatif et citez le schéma officiel comme la limite.
6. Les schémas décrivent des contrats, pas des implémentations. Les exécutables qui satisfont ces contrats sont reportés à une PR ultérieure sur la feuille de route du responsable. Cette compétence existe pour que chaque autre compétence du bundle puisse être aware de l'infra avant que les exécutables ne soient disponibles.

Le contrat de comportement de l'agent

Le contrat est une boucle à quatre étapes que l'agent exécute chaque fois qu'un appendice Command d'une compétence référence ce contrat :

1. Détectez. Exécutez la commande probe listée dans la section de schéma pour l'outil pertinent. Exemples : command -v doca-env, test -f /opt/mellanox/doca/share/version-matrix.json, command -v doca-capability-snapshot. Les probes sont en lecture seule et sûres à exécuter sur n'importe quel hôte.
2. Préférez. Si la probe réussit, invoquez l'outil structuré et analysez son JSON selon le schéma dans ## Schemas. La sortie est la réponse faisant autorité pour ce tour. N'exécutez PAS aussi la chaîne manuelle « pour vérifier » — le contrat est que l'outil structuré remplace la chaîne.
3. Utilisez le secours. Si la probe échoue, parcourez la chaîne de commandes manuelle documentée dans la même section de schéma. Synthétisez la réponse en combinant les sorties des commandes manuelles dans l'ordre que la chaîne les liste. Si une commande manuelle n'est pas disponible sur l'hôte, signalez-la comme un manque et routez l'utilisateur vers la compétence correspondante (généralement doca-setup).
4. Rapportez. Ouvrez la réponse avec l'un des :
   • « Using structured <tool> (path: <path>). » — quand la probe a réussi.
   • « Falling back to manual chain (no structured <tool> on this host). » — quand la probe a échoué. Plus une remarque d'une ligne pointant l'utilisateur sur comment installer les helpers quand ils deviennent disponibles.

L'étape de rapport est le signal du bundle à l'utilisateur que l'agent a essayé les helpers, pas seulement la chaîne manuelle. Sans lui, un agent qui utilise toujours le secours ressemble de manière identique à un agent qui ne savait jamais que les helpers existaient.

Schémas

Chaque sous-section ci-dessous nomme UN outil structuré avec lequel le bundle s'attend à interopérer, donne sa probe de détection, nomme sa forme JSON de haut niveau, et liste la chaîne de commandes manuelle que l'agent parcourt quand la probe échoue.

Schéma doca-env --json

Probe de détection : command -v doca-env. L'outil structuré, s'il est installé, vit au même emplacement $PATH que doca_caps (c.-à-d. sous le bin/ de l'arborescence d'installation DOCA).

Forme de haut niveau (objet JSON) :

Chaîne de secours manuelle (exécutez dans l'ordre ; combinez les sorties pour synthétiser la même réponse) :

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 → tableau devices (analysez adresse PCIe + kind + representor)
5. PCDIR="$(dirname "$(find /opt/mellanox/doca -name doca-common.pc -print -quit)")"; for pc in "$PCDIR"/*.pc; do pkg-config --exists "$(basename "$pc" .pc)" && echo "$pc"; done → tableau libraries. PCDIR est communément /opt/mellanox/doca/lib/<arch>-linux-gnu/pkgconfig sur DOCA 3.3+, ou /opt/mellanox/doca/infrastructure/lib/pkgconfig sur les installations legacy / split-profile ; le dériver du doca-common.pc en direct (équivalemment pkg-config --variable=pcfiledir doca-common) évite le piège du glob vide du codage en dur de infrastructure/.
6. ls /opt/mellanox/doca/samples/ → tableau sample_paths
7. lsmod | grep -E '^mlx5_(core|ib)' et uname -r → objet drivers
8. cat /proc/meminfo | grep -i Huge → objet hugepages
9. dmidecode -s system-product-name (ou cat /proc/device-tree/model sur BlueField) → host_kind
10. mlxconfig -d <pcie> q INTERNAL_CPU_MODEL → bf_mode (quand host_kind == bluefield)

Schéma version-matrix.json

Probe de détection : test -f /opt/mellanox/doca/share/version-matrix.json (ou un emplacement frère documenté au moment de l'installation par le fichier qui le livre).

Forme de haut niveau (objet JSON) :

Forme par entrée :

Chaîne de secours manuelle :

1. Identifiez la bibliothèque + capacité qu'l'utilisateur a demandée (via la table ## Capacités et modes de la compétence library correspondante).
2. Récupérez la page de doc correspondante par bibliothèque via doca-public-knowledge-map.
3. Cherchez sur la page le nom de capacité ; extrayez la prose « disponible depuis » ; citez-la verbatim.
4. Vérifiez contre pkg-config --modversion doca-<library> sur l'hôte de l'utilisateur ; si la version installée est plus ancienne que la ligne « disponible depuis », la capacité n'est pas sur cette installation indépendamment de ce que dit la doc publique.

Schéma capability-snapshot

Probe de détection : command -v doca-capability-snapshot. L'outil structuré, s'il est installé, vit au même emplacement $PATH que doca_caps.

Forme de haut niveau (objet JSON) :

Chaîne de secours manuelle :

1. doca_caps --list-devs → énumération des appareils
2. Pour chaque appareil + chaque bibliothèque d'intérêt : invoquez la famille de requête doca_<lib>_cap_* spécifique à la bibliothèque à partir d'un petit programme de test (l'agent guide l'utilisateur pour l'écrire, selon le workflow ## test de la bibliothèque elle-même).

Schéma validate-before-commit

Probe de détection : command -v doca-validate (inter-bibliothèque) OU la surface de validation spécifique à la bibliothèque au moment du constructeur (p. ex. pour Flow, le retour DOCA_ERROR_INVALID_VALUE / DOCA_ERROR_NOT_SUPPORTED de doca_flow_pipe_create — l'en-tête public Flow à cette release ne livra pas de symbole doca_flow_pipe_validate séparé ; l'agent utilise le chemin d'échec du constructeur comme le signal de validation). L'outil structuré enveloppe les appels spécifiques à la bibliothèque et retourne un résultat JSON uniforme.

Forme de haut niveau (objet JSON) :

Chaîne de secours manuelle :

1. Trouvez la surface de validation spécifique à la bibliothèque dans le workflow ## test de la compétence correspondante. Pour certaines libs c'est un appel _validate dédié ; pour d'autres (notamment DOCA Flow) c'est la validation au moment du constructeur intégrée dans la famille d'appels _create / _cfg (p. ex. doca_flow_pipe_create pour Flow) dont le retour DOCA_ERROR_INVALID_VALUE / DOCA_ERROR_NOT_SUPPORTED est le signal de validation. L'ancre ## test par compétence de la lib nomme lequel.
2. Invoquez-le avant tout appel commit / create / submit.
3. Traitez un retour non-DOCA_SUCCESS comme result: fail ; mappez le texte doca_error_get_descr() dans une seule entrée checks.

Schémas collect-host-state et collect-dpu-state

Probes de détection : command -v doca-collect-host-state (à exécuter du côté hôte) et command -v doca-collect-dpu-state (à exécuter du côté BlueField).

Forme de haut niveau (objet JSON), partagée par les deux :

Chaîne de secours manuelle (par côté) :

1. doca_caps --version → doca_version
2. flint -d <pcie> q (sudo) → firmware_version
3. uname -r → kernel_version
4. lsmod | grep mlx5 → mlx5_modules
5. mlxconfig -d <pcie> q INTERNAL_CPU_MODEL → bf_mode
6. devlink dev show + ip -j link → tableau devices

Les deux côtés sont délibérément symétriques pour que l'agent puisse les différencier trivialement quand il diagnostique les incompatibilités hôte ↔ BlueField.

Relation avec les exécutables PR2

Les schémas ci-dessus décrivent des contrats. Les implémentations qui satisfont chaque contrat sont reportées à une PR ultérieure sur la feuille de route du responsable.

La raison pour laquelle cette compétence existe avant que les exécutables soient disponibles est pour que chaque autre compétence du bundle puisse être aware de l'infra à partir de PR1 en avant : chaque appendice Command d'une compétence library / service / tool référence ce contrat dans sa première ligne, donc quand les exécutables arrivent dans PR2 les compétences n'ont pas besoin de retrofit.

Conséquence concrète pour les contributeurs écrivant une nouvelle compétence library : quand vous construisez l'appendice Command, ne dupliquez pas la chaîne de secours manuelle — liez vers la section de schéma correspondante de cette compétence et ajoutez seulement l'overlay par bibliothèque (p. ex. « Flow-spécifique : traitez le retour DOCA_ERROR_INVALID_VALUE / DOCA_ERROR_NOT_SUPPORTED de doca_flow_pipe_create comme le signal de validation ; l'en-tête public Flow à cette release ne livra pas de symbole doca_flow_pipe_validate séparé — n'en inventez pas un »). La chaîne de secours elle-même vit ici.

Audit d'URL

Cette compétence référence les URLs externes suivantes. Toutes DOIVENT être publiques et DOIVENT se résoudre. Le lint exécute la vérification d'URL dans CI.