Back to Details

jetson-link-docs

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

jetson-link-docs

jetson-link-docs

Overview

概述

This skill writes the 
documents:
block of the active Jetson / IGX target-platform profile YAML so downstream skills (
/jetson-generate-kb
, 
/jetson-customize-pinmux
, camera / pcie / uphy, etc.) can resolve doc paths by name. It walks the user through every document slot in the profile schema, tries to auto-bind each slot to a file under 
<documents.root_path>/
via case-insensitive glob matching, and writes the resulting paths back into the active profile.
Scope is registering pointers only — this skill does not fetch or download. The files must already exist on disk under 
<documents.root_path>/
.
此技能会写入当前Jetson/IGX目标平台配置文件YAML中的
documents:
区块，以便下游技能（如
/jetson-generate-kb
、
/jetson-customize-pinmux
、摄像头/PCIe/uphy相关技能等）能够通过名称解析文档路径。它会引导用户完成配置文件schema中的每个文档槽位，尝试通过不区分大小写的glob匹配将每个槽位自动绑定到
<documents.root_path>/
下的文件，并将最终路径写回到当前配置文件中。
本技能的作用范围仅为注册文件指针——不会获取或下载文档。文件必须已存储在
<documents.root_path>/
对应的本地磁盘路径下。

When to invoke

调用时机

  • After 
    /jetson-init-target
    finishes and the user has documents on disk to register.
  • The user wants to add, change, or remove document references on an existing profile.
  • A downstream skill (e.g. 
    jetson-generate-kb
    ) reports "no documents recorded" and the user wants to fix that.
  • 在
    /jetson-init-target
    技能执行完成，且用户已将文档存储到本地磁盘需要注册时。
  • 用户需要在现有配置文件中添加、修改或移除文档引用时。
  • 下游技能（如
    jetson-generate-kb
    ）提示“未记录文档”，用户需要修复该问题时。

Procedure

操作流程

Resolve the active target

确定当前目标

Resolve the active profile + 
<workspace>
per the contract in 
../../context/target-platform-contract.md
. Cache the loaded profile in memory — this skill mutates it in the "Write the 
documents:
block back to the profile" step.
根据
../../context/target-platform-contract.md
中的约定，确定当前配置文件及
<workspace>
路径。将加载的配置文件缓存到内存中——本技能会在“将
documents:
区块写回配置文件”步骤中修改该配置文件。

Load the document-slot schema

加载文档槽位schema

Load 
../../references/platform_template.yaml
. Parse the 
documents:
block. Each per-document field is marked 
<OPTIONAL: description>
. Use the marker description as prompt text verbatim. Match markers with the regex 
^<(REQUIRED|OPTIONAL|DERIVED):\s*(.*)>$
after YAML parsing strips surrounding quotes.
Skip 
custom_carrier_schematic
and 
custom_carrier_pinmux_xls
entirely when the active profile has no 
custom_carrier:
block — both are meaningless without one. This filter applies through the "Scan and auto-match" and "Manual prompts for unmatched fields" steps.
加载
../../references/platform_template.yaml
。解析其中的
documents:
区块。每个文档字段都标记为
<OPTIONAL: description>
。直接使用标记中的描述作为提示文本。在YAML解析去除引号后，使用正则表达式
^<(REQUIRED|OPTIONAL|DERIVED):\s*(.*)>$
匹配标记。
如果当前配置文件中没有
custom_carrier:
区块，则完全跳过
custom_carrier_schematic
和
custom_carrier_pinmux_xls
字段——没有自定义载板时这两个字段毫无意义。此过滤规则适用于“扫描并自动匹配”和“未匹配字段的手动提示”步骤。

Resolve 
documents.root_path

解析
documents.root_path

Default: 
<workspace>/Documents
. If the profile already records 
documents.root_path
, use it. Otherwise, if 
<workspace>/Documents/
exists, use it (the field is omitted from the written profile — downstream skills fall back to the workspace default). If neither is available, prompt the user for an absolute path, or accept Enter / 
cancel
to skip the auto-scan. A user-provided path that doesn't exist is treated as skipped (warn, don't refuse — the field is OPTIONAL); manual prompts in the "Manual prompts for unmatched fields" step still run.
默认路径：
<workspace>/Documents
。如果配置文件中已记录
documents.root_path
，则使用该路径。否则，如果
<workspace>/Documents/
存在，则使用该路径（此字段不会写入配置文件——下游技能会回退到工作区默认路径）。如果两者都不可用，则提示用户输入绝对路径，或接受回车/
cancel
以跳过自动扫描。用户提供的路径若不存在，将视为跳过（仅发出警告，不拒绝——该字段为可选）；“未匹配字段的手动提示”步骤仍会执行。

Resolve the product token

解析产品令牌

Read the Product Token column from 
../../references/bsp-platforms-catalogue.md
 for the row matching 
reference_devkit.name
. The token is a case-insensitive glob fragment (e.g. 
*orin*nano*
, 
*agx*thor*
) consumed by the fallback patterns in the "Scan and auto-match" step.
If 
reference_devkit.name
has no row in the catalogue, log a warning and proceed without a product-token fallback — the "Scan and auto-match" step still works with strictly SKU-keyed matching.
For custom carriers, derive 
<custom-token>
from 
custom_carrier.name
using this recipe: lowercase, replace each space with 
*
, wrap in 
*
on both ends. E.g. "Acme Vision X1" → 
*acme*vision*x1*
.
从
../../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*
。

Scan and auto-match

扫描并自动匹配

Skip this step entirely if 
documents.root_path
did not resolve in the "Resolve 
documents.root_path
" step (no scan target → no auto-suggest; fall through to manual prompts in the "Manual prompts for unmatched fields" step).
Scan the directory once (one level deep) and try to auto-match each remaining 
<OPTIONAL:…>
field using the case-insensitive globs below. Use the lower-case 
module.id
/ 
carrier.id
/ 
custom_carrier.id
strings from the profile in the SKU column.
FieldSKU glob (primary)Product-token glob (fallback)
bsp_developer_guide
*developer*guide*.pdf
, 
*BSP*guide*.pdf
(no fallback — pattern is product-agnostic)
soc_tech_ref_manual
*TRM*.pdf
, 
*tech*ref*manual*.pdf
(no fallback — same)
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
(covers "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
(only if custom carrier)
<custom-token>schem*.pdf
(only if custom carrier)
ref_devkit_pinmux_xls
*<carrier.id>*pinmux*.xls*
(matches 
.xls
, 
.xlsx
, 
.xlsm
)
<token>pinmux*.xls*
custom_carrier_pinmux_xls
*<custom_carrier.id>*pinmux*.xls*
(only if custom carrier)
<custom-token>pinmux*.xls*
(only if custom carrier)
<token>
is the catalogue-resolved product token; 
<custom-token>
is derived from 
custom_carrier.name
per the "Resolve the product token" step. Tokens already include leading/trailing 
*
, so the table does not repeat them.
如果在“解析
documents.root_path
”步骤中未解析出路径，则完全跳过此步骤（无扫描目标→无自动建议；直接进入“未匹配字段的手动提示”步骤）。
扫描目录一次（仅一级深度），尝试使用以下不区分大小写的glob自动匹配每个剩余的
<OPTIONAL:…>
字段。使用配置文件中
module.id
/
carrier.id
/
custom_carrier.id
的小写字符串作为SKU列的值。
字段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
生成的。令牌已包含首尾的
*
，因此表格中不再重复。

Match policy per field

每个字段的匹配规则

For each field that has auto-match results:
  • Take the union of hits across the SKU glob and the product- token glob, then deduplicate by absolute path — a file matched by both globs counts once.
  • Exactly 1 unique hit → show the path and prompt 
    use this? (yes/no, default yes)
    . On 
    yes
    , record it and skip the manual prompt for that field. On 
    no
    , fall through to the manual prompt in the "Manual prompts for unmatched fields" step.
  • 0 hits → skip auto-suggest entirely for that field; fall through to the "Manual prompts for unmatched fields" step.
  • 2+ unique hits → present them as a numbered list in the "Manual prompts for unmatched fields" step so the user can pick by number rather than typing a path; include a 
    skip / NA
    option. Never silently bind a multi-hit candidate.
  • Never silently bind without user confirmation — wrong-schematic / wrong-pinmux bindings are real and costly.
If 
documents.root_path
is folder-organised one level deeper than flat (NVIDIA archives often are: 
Schematics/
, 
Design-Guides/
, 
Pinmux/
, etc.), the file globs may return zero hits even when the right documents exist. v0.2 only scans one level deep — when 0 hits is suspicious (
documents.root_path
exists but no fields auto-bound), surface the limitation to the user and offer to fall through to manual prompts.
对于每个有自动匹配结果的字段：
  • 取SKU glob和产品令牌glob匹配结果的并集，然后按绝对路径去重——同一个文件被两个glob匹配到仅算一次。
  • 恰好1个唯一匹配结果 → 显示路径并提示
    use this? (yes/no, default yes)
    。如果选择
    yes
    ，记录该路径并跳过该字段的手动提示。如果选择
    no
    ，进入“未匹配字段的手动提示”步骤。
  • 0个匹配结果 → 完全跳过该字段的自动建议；进入“未匹配字段的手动提示”步骤。
  • 2个及以上唯一匹配结果 → 在“未匹配字段的手动提示”步骤中以编号列表形式展示，用户可通过编号选择，而非手动输入路径；同时提供
    skip / NA
    选项。绝不自动绑定多个匹配结果中的任意一个。
  • 绝不自动绑定，必须经用户确认——绑定错误的原理图/Pinmux会造成严重损失。
如果
documents.root_path
的文件夹结构比扁平结构深一级（NVIDIA归档文件通常如此：
Schematics/
、
Design-Guides/
、
Pinmux/
等），则文件glob可能返回0个匹配结果，即使正确的文档存在。v0.2版本仅扫描一级深度——当出现可疑的0匹配结果（
documents.root_path
存在但无字段自动绑定）时，向用户说明此限制，并提供进入手动提示步骤的选项。

Manual prompts for unmatched fields

未匹配字段的手动提示

For every field that wasn't auto-bound (and wasn't filtered out in the "Load the document-slot schema" step), prompt using the marker description from the "Load the document-slot schema" step as prompt text, in document order. Accept Enter and 
NA
interchangeably as "skip this field". When the "Match policy per field" step produced 2+ candidate hits for a field, present them as a numbered list with a 
skip / NA
option rather than asking for a free-text path.
Validate that user-provided paths exist on disk (warn if not, but do not refuse — the user may be recording a planned path). URLs (values starting with 
http://
, 
https://
, or 
ftp://
) are accepted verbatim and not validated.
对于所有未自动绑定的字段（以及未在“加载文档槽位schema”步骤中被过滤的字段），按照文档顺序，使用“加载文档槽位schema”步骤中的标记描述作为提示文本。接受回车和
NA
作为“跳过此字段”的等价输入。如果“每个字段的匹配规则”步骤中某个字段产生了2个及以上候选匹配结果，则以编号列表形式展示，并提供
skip / NA
选项，而非要求用户输入自由文本路径。
验证用户提供的路径是否存在于磁盘（若不存在则发出警告，但不拒绝——用户可能记录的是计划路径）。URL（以
http://
、
https://
或
ftp://
开头的值）将直接接受，不进行验证。

Write the 
documents:
block back to the profile

将
documents:
区块写回配置文件

Edit 
target-platform/<active>.yaml
in place. Preserve all other top-level blocks (
reference_devkit:
, 
custom_carrier:
, 
bsp_image:
, 
source:
) and their comments verbatim. Write only the fields the user provided — omit skipped / 
NA
fields entirely (no 
NA
placeholders, no empty keys).
Edge behavior: when every field was skipped (including 
documents.root_path
), drop the 
documents:
block entirely from the profile — never write 
documents: {}
or a block of 
NA
values. When only 
documents.root_path
was provided (no per-document binding), record it alone — the path has value as a hint for future re-runs. On re-run with an existing 
documents:
block, merge: existing bindings are preserved unless the user picks a new file or 
NA
; newly bound fields are added.
直接编辑
target-platform/<active>.yaml
文件。保留所有其他顶级区块（
reference_devkit:
、
custom_carrier:
、
bsp_image:
、
source:
）及其注释不变。仅写入用户提供的字段——完全省略跳过/
NA
的字段（不保留
NA
占位符，不保留空键）。
边缘情况：如果所有字段都被跳过（包括
documents.root_path
），则从配置文件中完全删除
documents:
区块——绝不写入
documents: {}
或包含
NA
值的区块。如果仅提供了
documents.root_path
（无单个文档绑定），则仅记录该路径——该路径可作为后续重新运行的提示。重新运行时，如果已有
documents:
区块，则进行合并：除非用户选择新文件或
NA
，否则保留现有绑定；添加新绑定的字段。

Confirm

确认

Print a summary:
  • Profile path written.
  • documents.root_path
    — resolved value (or "default — omitted").
  • Auto-bound fields: count + per-field one-line list.
  • Manually entered fields: count + list.
  • Skipped fields: count.
  • A reminder that 
    jetson-generate-kb
    re-reads 
    documents.*
    and should be re-run if a KB exists.
If a downstream skill triggered this run, tell the user to re-issue their original request; do not silently re-trigger it.
打印摘要：
  • 写入的配置文件路径。
  • documents.root_path
    ——解析后的值（或“默认值——已省略”）。
  • 自动绑定字段：数量+每个字段的单行列表。
  • 手动输入字段：数量+列表。
  • 跳过的字段：数量。
  • 提醒用户
    jetson-generate-kb
    会重新读取
    documents.*
    字段，若已有知识库则需重新运行该技能。
如果是下游技能触发了本次运行，告知用户重新发出原始请求；不自动重新触发下游技能。

Gotchas

注意事项

  • Active profile must exist. This skill writes back to whichever profile is active. If no profile is active, refuse and route to 
    jetson-set-target
    / 
    jetson-init-target
    .
  • Product-token globs are intentionally broad. A token like 
    *orin*nano*
    matches both Orin-Nano-specific docs and combined Orin-NX/Nano docs (e.g. 
    Jetson-Orin-NX-Nano-Design-Guide_…
    ). That is usually correct for module-side docs (NVIDIA ships combined manuals), but verify on schematic / pinmux / spec fields where wrong-product binding is costly.
  • Update 
    bsp-platforms-catalogue.md
    when adding new product rows.     The Product Token column is consumed by the "Resolve the product token" step; a missing token degrades the auto-scan to SKU-only matching (the skill warns and continues, but doc-rich 
    documents.root_path
    scans will degrade silently from "5 auto-binds" to "fewer auto- binds").
  • Use a round-tripping YAML loader. the "Write the 
    documents:
    block back to the profile" step mutates an existing YAML file. Plain 
    yaml.safe_load
    + 
    yaml.safe_dump
    loses comments, block ordering, and quoting style — use 
    ruamel.yaml
    or equivalent so hand-edited fields and comments survive.
  • Re-runnable. Re-running merges new bindings; existing bindings are preserved unless the user explicitly changes them. Safe to invoke as part of a profile refresh.
  • 必须存在当前配置文件。此技能会写回到当前激活的配置文件中。如果没有激活的配置文件，拒绝执行并引导至
    jetson-set-target
    /
    jetson-init-target
    技能。
  • 产品令牌glob故意设置为宽泛匹配。类似
    *orin*nano*
    的令牌会同时匹配Orin-Nano专用文档和Orin-NX/Nano组合文档（例如
    Jetson-Orin-NX-Nano-Design-Guide_…
    ）。对于模块端文档，这通常是正确的（NVIDIA发布的是组合手册），但在原理图/Pinmux/规格字段中需进行验证，因为绑定错误产品的文档会造成严重损失。
  • 添加新产品行时更新
    bsp-platforms-catalogue.md
    。Product Token列会被“解析产品令牌”步骤使用；缺少令牌会使自动扫描降级为仅SKU匹配（技能会发出警告并继续执行，但文档丰富的
    documents.root_path
    扫描会从“自动绑定5个字段”静默降级为“自动绑定更少字段”）。
  • 使用支持往返的YAML加载器。“将
    documents:
    区块写回配置文件”步骤会修改现有YAML文件。普通的
    yaml.safe_load
    +
    yaml.safe_dump
    会丢失注释、区块顺序和引用格式——使用
    ruamel.yaml
    或类似工具，确保手动编辑的字段和注释得以保留。
  • 可重复运行。重新运行会合并新的绑定；除非用户明确修改，否则保留现有绑定。可安全地作为配置文件刷新流程的一部分调用。

Prerequisites

前置条件

  • Active target profile resolved per 
    ../../context/target-platform-contract.md
    .
  • Documents available either under the recorded 
    documents.root_path
    , under default 
    <workspace>/Documents/
    , or as user-provided paths / URLs during manual prompts. A missing root only disables auto-scan; it is not a hard prerequisite.
  • ruamel.yaml
    or another round-tripping YAML writer for the profile edit step.
  • 根据
    ../../context/target-platform-contract.md
    解析出当前目标配置文件。
  • 文档已存储在已记录的
    documents.root_path
    下、默认的
    <workspace>/Documents/
    下，或可在手动提示步骤中由用户提供路径/URL。缺少根路径仅会禁用自动扫描；并非硬性前置条件。
  • 配置文件编辑步骤需使用
    ruamel.yaml
    或其他支持往返的YAML写入工具。

Limitations

限制

  • Registers pointers only; never downloads, copies, or renames files.
  • Per-document field set is fixed to the schema in 
    ../../references/platform_template.yaml
    — no ad-hoc keys.
  • Glob matching is filename-only; bad filenames in 
    documents.root_path
    will under-bind and require manual selection.
  • 仅注册指针；绝不下载、复制或重命名文件。
  • 单个文档字段集固定为
    ../../references/platform_template.yaml
    中的schema——不支持临时键。
  • Glob匹配仅基于文件名；
    documents.root_path
    中的文件名不符合规则会导致自动绑定失败，需要手动选择。

Troubleshooting

故障排除

  • documents.root_path
    missing     — auto-scan is skipped. Provide an absolute root path, enter individual document paths / URLs manually, or skip the fields you do not want to bind.
  • Multiple files match a single slot — the skill stops and prompts; pick or rename the file. Example: two 
    Jetson-Linux-Developer-Guide*.pdf
    files → keep the active version, rename the stale one.
  • Profile comments lost after write — a non-round-tripping YAML writer was used; switch to 
    ruamel.yaml
    and rerun against a fresh pristine copy.
  • Validation fails because a binding points outside 
    documents.root_path
     — 
    documents.*
    are relative paths only; move the file under the root and retry.
  • documents.root_path
    缺失    ——自动扫描被跳过。提供绝对根路径，手动输入单个文档路径/URL，或跳过不需要绑定的字段。
  • 多个文件匹配单个槽位——技能会停止并提示；选择或重命名文件。示例：两个
    Jetson-Linux-Developer-Guide*.pdf
    文件→保留当前版本，重命名旧版本。
  • 写入后配置文件注释丢失——使用了不支持往返的YAML加载器；切换到
    ruamel.yaml
    并针对原始干净副本重新运行。
  • 验证失败，因为绑定指向
    documents.root_path
    外部    ——
    documents.*
    仅支持相对路径；将文件移动到根路径下并重试。

References

参考资料

  • ../../context/target-platform-contract.md
     — target-platform contract; this skill consumes and mutates the active profile.
  • ../../references/bsp-platforms-catalogue.md
     — source of the Product Token column for the "Resolve the product token" step.
  • ../../references/platform_template.yaml
     — schema for the 
    documents:
    block (source of truth for prompts and field list).
  • ../jetson-init-target/SKILL.md
     — sibling skill that authors target identity (
    reference_devkit:
    , optional 
    custom_carrier:
    ).
  • ../jetson-init-image/SKILL.md
     — sibling skill that authors 
    bsp_image:
    .
  • ../jetson-init-source/SKILL.md
     — sibling skill: clones shared repos and handles 
    source.root_path
    overrides.
  • ../jetson-generate-kb/SKILL.md
     — sibling skill: consumes the 
    documents:
    block this skill writes.
  • ../../context/target-platform-contract.md
    ——目标平台约定；此技能会读取并修改当前配置文件。
  • ../../references/bsp-platforms-catalogue.md
    ——“解析产品令牌”步骤中Product Token列的来源。
  • ../../references/platform_template.yaml
    ——
    documents:
    区块的schema（提示文本和字段列表的权威来源）。
  • ../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:
    区块。