jetson-link-docs
Vue d'ensemble
Cette skill écrit le bloc documents: du profil YAML de la plateforme cible Jetson / IGX active pour que les skills en aval (/jetson-generate-kb, /jetson-customize-pinmux, camera / pcie / uphy, etc.) puissent résoudre les chemins de documents par nom. Elle guide l'utilisateur à travers chaque slot de document du schéma de profil, essaie d'auto-lier chaque slot à un fichier sous <documents.root_path>/ via une correspondance glob insensible à la casse, et écrit les chemins résultants dans le profil actif.
L'étendue est l'enregistrement de pointeurs uniquement — cette skill ne télécharge ni ne récupère rien. Les fichiers doivent déjà exister sur disque sous <documents.root_path>/.
Quand invoquer
- Après la fin de
/jetson-init-targetet que l'utilisateur a des documents à enregistrer sur disque. - L'utilisateur veut ajouter, modifier ou supprimer des références de documents sur un profil existant.
- Une skill en aval (par ex.
jetson-generate-kb) rapporte « aucun document enregistré » et l'utilisateur veut corriger cela.
Procédure
Résoudre la cible active
Résoudre le profil actif + <workspace> selon le contrat dans ../../context/target-platform-contract.md. Mettre en cache le profil chargé en mémoire — cette skill le mutate à l'étape « Écrire le bloc documents: dans le profil ».
Charger le schéma des slots de document
Charger ../../references/platform_template.yaml. Parser le bloc documents:. Chaque champ par-document est marqué <OPTIONAL: description>. Utiliser la description du marqueur comme texte d'invite verbatim. Matcher les marqueurs avec la regex ^<(REQUIRED|OPTIONAL|DERIVED):\s*(.*)>$ après que le parsing YAML supprime les guillemets environnants.
Ignorer complètement custom_carrier_schematic et custom_carrier_pinmux_xls quand le profil actif n'a pas de bloc custom_carrier: — les deux sont sans sens sans lui. Ce filtre s'applique à travers les étapes « Analyser et auto-matcher » et « Invites manuelles pour les champs sans correspondance ».
Résoudre documents.root_path
Par défaut : <workspace>/Documents. Si le profil enregistre déjà documents.root_path, l'utiliser. Sinon, si <workspace>/Documents/ existe, l'utiliser (le champ est omis du profil écrit — les skills en aval reviennent à la valeur par défaut du workspace). Si aucun n'est disponible, demander à l'utilisateur un chemin absolu, ou accepter Entrée / cancel pour ignorer l'auto-scan. Un chemin fourni par l'utilisateur qui n'existe pas est traité comme ignoré (avertir, ne pas refuser — le champ est OPTIONAL) ; les invites manuelles à l'étape « Invites manuelles pour les champs sans correspondance » s'exécutent toujours.
Résoudre le jeton de produit
Lire la colonne Product Token de ../../references/bsp-platforms-catalogue.md pour la ligne correspondant à reference_devkit.name. Le jeton est un fragment glob insensible à la casse (par ex. *orin*nano*, *agx*thor*) consommé par les patterns de secours à l'étape « Analyser et auto-matcher ».
Si reference_devkit.name n'a pas de ligne dans le catalogue, enregistrer un avertissement et continuer sans secours de jeton de produit — l'étape « Analyser et auto-matcher » fonctionne toujours avec un matching strict basé sur SKU.
Pour les supports personnalisés, dériver <custom-token> de custom_carrier.name avec cette recette : minuscules, remplacer chaque espace par *, envelopper dans * aux deux extrémités. Par ex. "Acme Vision X1" → *acme*vision*x1*.
Analyser et auto-matcher
Ignorer complètement cette étape si documents.root_path n'a pas été résolu à l'étape « Résoudre documents.root_path » (pas de cible de scan → pas d'auto-suggestion ; passer aux invites manuelles à l'étape « Invites manuelles pour les champs sans correspondance »).
Scanner le répertoire une fois (un niveau de profondeur) et essayer d'auto-matcher chaque champ <OPTIONAL:…> restant en utilisant les globs insensibles à la casse ci-dessous. Utiliser les chaînes module.id / carrier.id / custom_carrier.id en minuscules du profil dans la colonne SKU.
| Champ | Glob SKU (primaire) | Glob jeton de produit (secours) |
|---|---|---|
bsp_developer_guide |
*developer*guide*.pdf, *BSP*guide*.pdf |
(pas de secours — pattern est agnostique au produit) |
soc_tech_ref_manual |
*TRM*.pdf, *tech*ref*manual*.pdf |
(pas de secours — idem) |
module_data_sheet |
*<module.id>*data*sheet*.pdf, *<module.id>*datasheet*.pdf |
<token>data*sheet*.pdf, <token>datasheet*.pdf |
module_design_guide |
*<module.id>*design*guide*.pdf, *<module.id>*PDG*.pdf |
<token>design*guide*.pdf, <token>PDG*.pdf |
module_thermal_design_guide |
*<module.id>*thermal*.pdf (couvre « Thermal Design Guide » / « TDG ») |
<token>thermal*.pdf |
module_schematic |
*<module.id>*schem*.pdf |
<token>schem*.pdf |
carrier_board_spec |
*<carrier.id>*board*spec*.pdf, *<carrier.id>*spec*.pdf |
<token>carrier*spec*.pdf |
carrier_schematic |
*<carrier.id>*schem*.pdf |
<token>carrier*schem*.pdf |
custom_carrier_schematic |
*<custom_carrier.id>*schem*.pdf (seulement si support personnalisé) |
<custom-token>schem*.pdf (seulement si support personnalisé) |
ref_devkit_pinmux_xls |
*<carrier.id>*pinmux*.xls* (correspond à .xls, .xlsx, .xlsm) |
<token>pinmux*.xls* |
custom_carrier_pinmux_xls |
*<custom_carrier.id>*pinmux*.xls* (seulement si support personnalisé) |
<custom-token>pinmux*.xls* (seulement si support personnalisé) |
<token> est le jeton de produit résolu du catalogue ; <custom-token> est dérivé de custom_carrier.name selon l'étape « Résoudre le jeton de produit ». Les jetons incluent déjà * aux extrémités, donc le tableau ne les répète pas.
Politique de matching par champ
Pour chaque champ qui a des résultats d'auto-match :
- Prendre l'union des résultats à travers le glob SKU et le glob jeton de produit, puis dédupliquer par chemin absolu — un fichier matché par les deux globs compte une fois.
- Exactement 1 résultat unique → afficher le chemin et demander
utiliser ceci ? (oui/non, oui par défaut). Suroui, l'enregistrer et ignorer l'invite manuelle pour ce champ. Surnon, passer à l'invite manuelle à l'étape « Invites manuelles pour les champs sans correspondance ». - 0 résultat → ignorer complètement l'auto-suggestion pour ce champ ; passer à l'étape « Invites manuelles pour les champs sans correspondance ».
- 2+ résultats uniques → les présenter comme une liste numérotée à l'étape « Invites manuelles pour les champs sans correspondance » pour que l'utilisateur puisse choisir par numéro plutôt que de taper un chemin ; inclure une option
ignorer / NA. Ne jamais lier silencieusement un candidat multi-résultats. - Ne jamais lier silencieusement sans confirmation de l'utilisateur — les mauvais bindings de schéma / pinmux sont réels et coûteux.
Si documents.root_path est organisé en dossiers un niveau plus profond que flat (les archives NVIDIA le sont souvent : Schematics/, Design-Guides/, Pinmux/, etc.), les globs de fichier peuvent retourner zéro résultats même quand les bons documents existent. v0.2 scanne seulement un niveau de profondeur — quand 0 résultats est suspect (documents.root_path existe mais aucun champ n'est auto-lié), surfacer la limitation à l'utilisateur et offrir de passer aux invites manuelles.
Invites manuelles pour les champs sans correspondance
Pour chaque champ qui n'a pas été auto-lié (et n'a pas été filtré à l'étape « Charger le schéma des slots de document »), demander en utilisant la description du marqueur de l'étape « Charger le schéma des slots de document » comme texte d'invite, dans l'ordre des documents. Accepter Entrée et NA indifféremment comme « ignorer ce champ ». Quand l'étape « Politique de matching par champ » a produit 2+ résultats candidats pour un champ, les présenter comme une liste numérotée avec une option ignorer / NA plutôt que de demander un chemin en texte libre.
Valider que les chemins fournis par l'utilisateur existent sur disque (avertir si non, mais ne pas refuser — l'utilisateur peut enregistrer un chemin prévu). Les URLs (valeurs commençant par http://, https://, ou ftp://) sont acceptées verbatim et non validées.
Écrire le bloc documents: dans le profil
Éditer target-platform/<active>.yaml sur place. Préserver tous les autres blocs de haut niveau (reference_devkit:, custom_carrier:, bsp_image:, source:) et leurs commentaires verbatim. Écrire seulement les champs que l'utilisateur a fournis — omettre complètement les champs ignorés / NA (pas de placeholders NA, pas de clés vides).
Comportement marginal : quand tous les champs ont été ignorés (y compris documents.root_path), supprimer complètement le bloc documents: du profil — ne jamais écrire documents: {} ou un bloc de valeurs NA. Quand seul documents.root_path a été fourni (aucun binding par-document), l'enregistrer seul — le chemin a de la valeur comme indice pour les ré-exécutions futures. Lors d'une ré-exécution avec un bloc documents: existant, fusionner : les bindings existants sont préservés à moins que l'utilisateur choisisse un nouveau fichier ou NA ; les champs nouvellement liés sont ajoutés.
Confirmer
Imprimer un résumé :
- Chemin du profil écrit.
documents.root_path— valeur résolue (ou « par défaut — omis »).- Champs auto-liés : compte + liste d'une ligne par champ.
- Champs saisis manuellement : compte + liste.
- Champs ignorés : compte.
- Un rappel que
jetson-generate-kbrelitdocuments.*et devrait être ré-exécuté si un KB existe.
Si une skill en aval a déclenché cette exécution, dire à l'utilisateur de ré-émettre sa demande d'origine ; ne pas la re-déclencher silencieusement.
Pièges
- Le profil actif doit exister. Cette skill écrit dans le profil qui est actif. Si aucun profil n'est actif, refuser et router vers
jetson-set-target/jetson-init-target. - Les globs de jeton de produit sont intentionnellement larges. Un jeton comme
*orin*nano*correspond à la fois aux docs spécifiques Orin-Nano et aux docs combinés Orin-NX/Nano (par ex.Jetson-Orin-NX-Nano-Design-Guide_…). C'est généralement correct pour les docs côté module (NVIDIA expédie des manuels combinés), mais vérifier sur les champs schéma / pinmux / spec où un binding du mauvais produit est coûteux. - Mettre à jour
bsp-platforms-catalogue.mdquand on ajoute de nouvelles lignes de produit. La colonne Product Token est consommée par l'étape « Résoudre le jeton de produit » ; un jeton manquant dégrade l'auto-scan au matching SKU-only (la skill avertit et continue, mais les scansdocuments.root_pathriches en documents se dégradent silencieusement de « 5 auto-binds » à « moins d'auto-binds »). - Utiliser un chargeur YAML round-tripping. L'étape « Écrire le bloc
documents:dans le profil » mutate un fichier YAML existant. Le simpleyaml.safe_load+yaml.safe_dumpperd les commentaires, l'ordre des blocs et le style des guillemets — utiliserruamel.yamlou équivalent pour que les champs et commentaires édités manuellement survivent. - Ré-exécutable. La ré-exécution fusionne les nouveaux bindings ; les bindings existants sont préservés à moins que l'utilisateur ne les change explicitement. Sûr d'invoquer comme partie d'une actualisation de profil.
Prérequis
- Profil cible actif résolu selon
../../context/target-platform-contract.md. - Documents disponibles soit sous le
documents.root_pathenregistré, soit sous le répertoire par défaut<workspace>/Documents/, soit comme chemins / URLs fournis par l'utilisateur lors des invites manuelles. Une racine manquante désactive seulement l'auto-scan ; ce n'est pas un prérequis dur. ruamel.yamlou un autre writer YAML round-tripping pour l'étape d'édition du profil.
Limitations
- Enregistre les pointeurs uniquement ; ne télécharge, ne copie ou ne renomme jamais les fichiers.
- L'ensemble des champs par-document est fixé au schéma dans
../../references/platform_template.yaml— pas de clés ad-hoc. - Le matching glob est fichier-only ; les mauvais noms de fichier dans
documents.root_pathsous-lieront et nécessiteront une sélection manuelle.
Dépannage
documents.root_pathmanquant — l'auto-scan est ignoré. Fournir un chemin racine absolu, entrer les chemins / URLs de documents individuels manuellement, ou ignorer les champs que vous ne voulez pas lier.- Plusieurs fichiers correspondent à un seul slot — la skill s'arrête et demande ; choisir ou renommer le fichier. Exemple : deux fichiers
Jetson-Linux-Developer-Guide*.pdf→ garder la version active, renommer l'ancienne. - Les commentaires du profil se perdent après l'écriture — un writer YAML non-round-tripping a été utilisé ; basculer vers
ruamel.yamlet ré-exécuter contre une copie fraîche vierge. - La validation échoue parce qu'un binding pointe hors de
documents.root_path—documents.*sont des chemins relatifs seulement ; déplacer le fichier sous la racine et réessayer.
Références
../../context/target-platform-contract.md— contrat de plateforme cible ; cette skill consomme et mutate le profil actif.../../references/bsp-platforms-catalogue.md— source de la colonne Product Token pour l'étape « Résoudre le jeton de produit ».../../references/platform_template.yaml— schéma du blocdocuments:(source de vérité pour les invites et la liste des champs).../jetson-init-target/SKILL.md— skill sœur qui authore l'identité cible (reference_devkit:,custom_carrier:optionnel).../jetson-init-image/SKILL.md— skill sœur qui authorebsp_image:.../jetson-init-source/SKILL.md— skill sœur : clone les repos partagés et gère les overridessource.root_path.../jetson-generate-kb/SKILL.md— skill sœur : consomme le blocdocuments:que cette skill écrit.