jetson-link-docs

jetson-link-docs

概要

このスキルは、アクティブな Jetson / IGX ターゲットプラットフォームプロファイル YAML の documents: ブロックを記述します。これにより、後続のスキル （/jetson-generate-kb、/jetson-customize-pinmux、カメラ／pcie／ uphy など）が名前でドキュメントのパスを解決できるようになります。プロファイルのスキーマにあるすべてのドキュメントスロットをユーザーに案内し、大文字と小文字を区別しない glob マッチングによって各スロットを <documents.root_path>/ 以下のファイルに自動的に割り当てようとし、結果のパスをアクティブなプロファイルに書き戻します。

対象範囲はポインターの登録のみです。このスキルはファイルを取得したり、ダウンロードしたりしません。ファイルはすでに <documents.root_path>/ 以下のディスク上に存在している必要があります。

呼び出すタイミング

• /jetson-init-target の完了後、登録するドキュメントがディスク上にある場合。
• 既存のプロファイルにドキュメント参照を追加、変更、または削除したい場合。
• 後続のスキル（例：jetson-generate-kb）で「ドキュメントが記録されていません」と報告され、ユーザーが修正を希望する場合。

手順

アクティブなターゲットを解決する

../../context/target-platform-contract.md の契約に従って、アクティブなプロファイルと <workspace> を解決します。読み込んだプロファイルはメモリに保持します。このスキルは「documents: ブロックをプロファイルに書き戻す」手順でプロファイルを変更します。

ドキュメントスロットのスキーマを読み込む

../../references/platform_template.yaml を読み込みます。documents: ブロックを解析します。各ドキュメントフィールドには <OPTIONAL: description> が付いています。このマーカーの説明をプロンプト文としてそのまま使用します。YAML の解析時に前後の引用符が取り除かれた後、正規表現 ^<(REQUIRED|OPTIONAL|DERIVED):\s*(.*)>$ を使ってマーカーを照合します。

アクティブなプロファイルに custom_carrier: ブロックがない場合は、custom_carrier_schematic と custom_carrier_pinmux_xls を完全にスキップします。どちらも custom_carrier: ブロックがなければ意味を持ちません。このフィルターは「スキャンして自動照合する」と「未照合フィールドを手動で確認する」の手順にも適用されます。

documents.root_path を解決する

デフォルトは <workspace>/Documents です。プロファイルにすでに documents.root_path が記録されている場合は、その値を使用します。それ以外の場合、<workspace>/Documents/ が存在すれば、それを使用します（このフィールドは書き込むプロファイルから省略され、後続のスキルはワークスペースのデフォルトにフォールバックします）。どちらも利用できない場合は、絶対パスをユーザーに尋ねるか、Enter ／ cancel を受け付けて自動スキャンをスキップします。ユーザーが指定したパスが存在しない場合は、スキップとして扱います（警告は出しますが、拒否はしません。このフィールドは OPTIONAL です）。「未照合フィールドを手動で確認する」手順では、引き続き手動で確認します。

製品トークンを解決する

../../references/bsp-platforms-catalogue.md から、reference_devkit.name に一致する行の Product Token 列を読み取ります。このトークンは、大文字と小文字を区別しない glob の一部で、「スキャンして自動照合する」手順のフォールバックパターンで使用されます（例：*orin*nano*、*agx*thor*）。

reference_devkit.name がカタログのどの行にも一致しない場合は、警告を記録し、製品トークンによるフォールバックを使わずに処理を続行します。「スキャンして自動照合する」手順では、SKU による厳密な照合は引き続き機能します。

カスタムキャリアの場合は、次の手順で custom_carrier.name から <custom-token> を導出します。小文字に変換し、各スペースを * に置き換えて、両端を * で囲みます。例：「Acme Vision X1」→ *acme*vision*x1*。

スキャンと自動照合

「documents.root_path の解決」ステップで documents.root_path が解決されなかった場合は、このステップ全体をスキップします（スキャン対象がないため自動候補提示は行わず、「一致しないフィールドの手動プロンプト」ステップに進みます）。

ディレクトリを一度（1階層のみ）スキャンし、以下の大文字小文字を区別しない glob を使って、残りの各 <OPTIONAL:…> フィールドを自動照合します。SKU 列には、プロファイルの小文字の module.id / carrier.id / custom_carrier.id 文字列を使用します。

フィールド	SKU glob（優先）	製品トークン glob（代替）
bsp_developer_guide	*developer*guide*.pdf、*BSP*guide*.pdf	(代替なし — パターンは製品に依存しません)
soc_tech_ref_manual	*TRM*.pdf、*tech*ref*manual*.pdf	(代替なし — 同上)
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（「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（カスタムキャリアの場合のみ）	<custom-token>schem*.pdf（カスタムキャリアの場合のみ）
ref_devkit_pinmux_xls	*<carrier.id>*pinmux*.xls*（.xls、.xlsx、.xlsm に一致）	<token>pinmux*.xls*
custom_carrier_pinmux_xls	*<custom_carrier.id>*pinmux*.xls*（カスタムキャリアの場合のみ）	<custom-token>pinmux*.xls*（カスタムキャリアの場合のみ）

<token> はカタログで解決された製品トークンです。<custom-token> は「製品トークンの解決」ステップに従って custom_carrier.name から導出されます。トークンには先頭と末尾の * がすでに含まれているため、表では繰り返し記載していません。

フィールドごとの照合ポリシー

自動照合の結果がある各フィールドについて、次のように処理します。

• SKU glob と製品トークン glob で見つかった結果の和集合を取り、絶対パスで重複を除去します。両方の glob に一致したファイルも1件として数えます。
• 一意な一致がちょうど1件 → パスを表示し、use this? (yes/no, default yes) と尋ねます。yes の場合はそのパスを記録し、そのフィールドの手動プロンプトをスキップします。no の場合は「一致しないフィールドの手動プロンプト」ステップに進みます。
• 一致が0件 → そのフィールドの自動候補提示をスキップし、「一致しないフィールドの手動プロンプト」ステップに進みます。
• 一意な一致が2件以上 → 「一致しないフィールドの手動プロンプト」ステップで番号付きリストとして提示し、パスを入力する代わりに番号で選べるようにします。skip / NA の選択肢も含めます。複数候補がある場合、候補を黙って割り当ててはいけません。
• ユーザーの確認なしに黙って割り当ててはいけません。回路図やピンマップを誤って割り当てると、実害とコストが生じます。

documents.root_path 内のフォルダーがフラットな構成より1階層深い場合（NVIDIA のアーカイブでは Schematics/、Design-Guides/、Pinmux/ などがよくあります）、該当するドキュメントが存在していてもファイル glob の一致が0件になることがあります。v0.2 では1階層のみをスキャンします。一致が0件で不自然な場合（documents.root_path は存在するものの、自動割り当てされたフィールドがない場合）は、この制限をユーザーに伝え、手動プロンプトに進む選択肢を提示します。

一致しないフィールドの手動プロンプト

自動バインドされなかったフィールド（および「ドキュメントスロットスキーマの読み込み」ステップで除外されなかったフィールド）ごとに、「ドキュメントスロットスキーマの読み込み」ステップのマーカーの説明をプロンプトテキストとして使用し、ドキュメントの順序でプロンプトを表示します。Enter と NA はどちらも「このフィールドをスキップ」として受け付けます。「フィールドごとの一致ポリシー」ステップで、あるフィールドに対して候補が2件以上見つかった場合は、自由入力でパスを尋ねるのではなく、skip / NA の選択肢を含む番号付きリストを提示します。

ユーザーが入力したパスがディスク上に存在するか検証します（存在しない場合は警告しますが、拒否はしません。ユーザーが予定しているパスを記録している可能性があります）。URL（http://、https://、または ftp:// で始まる値）はそのまま受け入れ、検証しません。

documents: ブロックをプロファイルに書き戻す

target-platform/<active>.yaml を直接編集します。他のトップレベルブロック（reference_devkit:、custom_carrier:、bsp_image:、source:）とそのコメントはすべてそのまま保持します。ユーザーが入力したフィールドのみを書き込みます。スキップされたフィールドや NA フィールドは完全に省略し（NA のプレースホルダーや空のキーは書き込みません）。

動作上の注意：すべてのフィールド（documents.root_path を含む）がスキップされた場合は、プロファイルから documents: ブロック全体を削除します。documents: {} や NA 値のブロックは決して書き込みません。documents.root_path のみが入力され（ドキュメントごとのバインドがない場合）、それだけを記録します。このパスは今後の再実行時のヒントとして役立ちます。既存の documents: ブロックがある状態で再実行する場合はマージします。ユーザーが新しいファイルまたは NA を選択しない限り、既存のバインドは保持されます。新たにバインドされたフィールドは追加します。

確認

概要を出力します。

• 書き込み先のプロファイルパス。
• documents.root_path — 解決された値（または「default — omitted」）。
• 自動バインドされたフィールド：件数とフィールドごとの1行の一覧。
• 手動入力されたフィールド：件数と一覧。
• スキップされたフィールド：件数。
• jetson-generate-kb は documents.* を再読み込みするため、KB が存在する場合は再実行する必要がある旨のリマインダー。

下流のスキルがこの実行を起動した場合は、元のリクエストを再度送信するようユーザーに伝えます。黙って再起動してはいけません。

注意事項

• アクティブなプロファイルが必要です。 このスキルはアクティブなプロファイルに書き戻します。アクティブなプロファイルがない場合は拒否し、jetson-set-target / jetson-init-target に案内してください。
• 製品トークンのグロブは意図的に広く設定されています。 *orin*nano* のようなトークンは、Orin Nano 固有のドキュメントと、Orin NX/Nano の両方を含むドキュメント（例：Jetson-Orin-NX-Nano-Design-Guide_…）に一致します。モジュール関連のドキュメントでは通常これで問題ありません（NVIDIA は複数製品をまとめたマニュアルを提供しています）が、製品の取り違えによる影響が大きい回路図／ピンマルチプレクサ／仕様のフィールドでは確認してください。
• 新しい製品行を追加する場合は、bsp-platforms-catalogue.md を更新してください。 製品トークン列は「製品トークンの解決」ステップで使用されます。トークンがないと、自動スキャンは SKU のみでの一致に劣化します（スキルは警告して続行しますが、ドキュメントが豊富な documents.root_path のスキャンは、「自動バインド5件」から「自動バインド件数の減少」へと、警告なしに劣化します）。
• ラウンドトリップ可能な YAML ローダーを使用してください。 「documents: ブロックをプロファイルに書き戻す」ステップでは、既存の YAML ファイルを変更します。単純な yaml.safe_load と yaml.safe_dump の組み合わせでは、コメント、ブロックの順序、引用符のスタイルが失われます。手動編集されたフィールドやコメントを保持できるよう、ruamel.yaml または同等のものを使用してください。
• 再実行可能です。 再実行すると新しいバインドがマージされます。ユーザーが明示的に変更しない限り、既存のバインドは保持されます。プロファイルの更新時に安全に実行できます。

前提条件

• アクティブなターゲットプロファイルが ../../context/target-platform-contract.md に従って解決されていること。
• ドキュメントが、記録済みの documents.root_path、デフォルトの <workspace>/Documents/、または手動プロンプトでユーザーが指定したパス／URLのいずれかから利用できること。ルートが見つからない場合は自動スキャンが無効になるだけで、必須条件ではありません。
• プロファイルの編集ステップで使用する ruamel.yaml またはその他のラウンドトリップ可能な YAML ライター。

制限事項

• ポインターを登録するだけです。ファイルのダウンロード、コピー、名前の変更は行いません。
• ドキュメントごとのフィールドセットは、../../references/platform_template.yaml のスキーマで固定されています。その場限りのキーは追加できません。
• グロブによる照合はファイル名のみが対象です。documents.root_path 内のファイル名が不適切な場合、紐付けが不足し、手動での選択が必要になります。

トラブルシューティング

• documents.root_path がない — 自動スキャンはスキップされます。絶対パスを指定するか、個々のドキュメントのパス／URLを手動で入力するか、紐付けたくないフィールドはスキップしてください。
• 1 つのスロットに複数のファイルが一致する — スキルは停止して選択を求めます。ファイルを選ぶか、名前を変更してください。例：Jetson-Linux-Developer-Guide*.pdf に 2 つのファイルが一致する場合は、現行バージョンを残し、古いバージョンの名前を変更します。
• 書き込み後にプロファイルのコメントが失われる — ラウンドトリップに対応していない YAML ライターが使われました。ruamel.yaml に切り替え、新しい未編集のコピーを使って再実行してください。
• 紐付け先が documents.root_path の外部を指しているため検証に失敗する — documents.* は相対パスのみ指定できます。ファイルをルート配下に移動してから再試行してください。

参考資料

• ../../context/target-platform-contract.md — ターゲットプラットフォームの契約です。このスキルはアクティブなプロファイルを使用し、変更します。
• ../../references/bsp-platforms-catalogue.md — 「製品トークンを解決する」ステップで使う Product Token 列の参照元です。
• ../../references/platform_template.yaml — documents: ブロックのスキーマです（プロンプトとフィールド一覧の信頼できる情報源）。
• ../jetson-init-target/SKILL.md — ターゲットの識別情報（reference_devkit:、任意の custom_carrier:）を作成する関連スキルです。
• ../jetson-init-image/SKILL.md — bsp_image: を作成する関連スキルです。
• ../jetson-init-source/SKILL.md — 共有リポジトリをクローンし、source.root_path のオーバーライドを処理する関連スキルです。
• ../jetson-generate-kb/SKILL.md — このスキルが書き込む documents: ブロックを使用する関連スキルです。