⚡

Jetson文档绑定Skill jetson-link-docs

该技能用于将预下载的Jetson/IGX参考文档（开发者指南、设计指南、引脚复用表、原理图）自动或手动绑定到活动目标平台profile的documents块中，支持通过文件名通配符匹配、手动路径/URL输入，并将结果写回YAML配置。适用于Jetson平台BSP文档管理、知识库生成、引脚定制等场景。关键词：Jetson, IGX, 文档绑定, target-platform, profile, BSP, 参考文档, pinmux, 原理图, YAML配置。

BSP与板级支持 0 次安装 0 次浏览 更新于 9/6/2026
名称 jetson-link-docs
描述 >- 将预下载的 Jetson 参考文档（开发者指南、设计指南、引脚复用、原理图）绑定到活动 profile 的 documents 块中。在文档暂存到磁盘后使用；不用于下载。
版本 0.0.1
开源协议 “Apache-2.0” metadata: data-classification: public
作者 “Jetson Team” tags: - target-platform - documents - setup domain: meta

jetson-link-docs

概述

本技能写入活动 Jetson / IGX 目标平台 profile YAML 的 documents: 块，以便下游技能（/jetson-generate-kb、/jetson-customize-pinmux、摄像头 / PCIe / UPHY 等）可以按名称解析文档路径。它引导用户完成 profile schema 中的每个文档槽位，尝试在 <documents.root_path>/ 下通过不区分大小写的 glob 匹配将每个槽位自动绑定到文件，并将生成的路径写回活动 profile。

范围仅注册指针 —— 本技能不获取或下载。文件必须已存在于 <documents.root_path>/ 下的磁盘上。

何时调用

  • /jetson-init-target 完成且用户在磁盘上有要注册的文档后。
  • 用户想添加、更改或删除现有 profile 上的文档引用。
  • 下游技能（例如 jetson-generate-kb）报告“未记录文档”，而用户想修复该问题。

流程

解析活动目标

按照 ../../context/target-platform-contract.md 中的约定解析活动 profile + <workspace>。将加载的 profile 缓存在内存中 —— 本技能在“将 documents: 块写回 profile”步骤中会修改它。

加载文档槽位 schema

加载 ../../references/platform_template.yaml。解析 documents: 块。每个文档字段都标记为 <OPTIONAL: description>。使用标记描述作为提示文本（逐字）。在 YAML 解析去除周围引号后，用正则表达式 ^<(REQUIRED|OPTIONAL|DERIVED):\\s*(.*)>$ 匹配标记。

当活动 profile 没有 custom_carrier: 块时，完全跳过 custom_carrier_schematic 和 custom_carrier_pinmux_xls —— 没有 custom_carrier 它们都没有意义。此过滤适用于“扫描并自动匹配”和“手动提示未匹配字段”步骤。

解析 documents.root_path

默认值：<workspace>/Documents。如果 profile 已记录 documents.root_path，使用它。否则，如果 <workspace>/Documents/ 存在，使用它（该字段从写入的 profile 中省略 —— 下游技能回退到工作区默认值）。如果两者都不可用，提示用户输入绝对路径，或接受 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”→“acmevisionx1”。

扫描并自动匹配

如果在“解析 documents.root_path”步骤中 documents.root_path 未解析，则完全跳过此步骤（没有扫描目标→没有自动建议；转入“手动提示未匹配字段”步骤中的手动提示）。

扫描目录一次（一级深度），尝试使用下面的不区分大小写的 glob 自动匹配每个剩余的 <OPTIONAL:…> 字段。在 SKU 列中使用 profile 中的小写 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 个唯一命中 → 显示路径并提示 使用这个吗？(yes/no, 默认 yes)。如果 yes，记录它并跳过该字段的手动提示。如果 no，落到“手动提示未匹配字段”步骤中的手动提示。
  • 0 个命中 → 完全跳过该字段的自动建议；落到“手动提示未匹配字段”步骤。
  • 2+ 个唯一命中 → 在“手动提示未匹配字段”步骤中将其显示为编号列表，以便用户按编号选择而不是输入路径；包含一个 skip / NA 选项。绝不静默绑定多命中候选。
  • 绝不静默绑定未经用户确认 —— 错误的原理图 / 引脚复用绑定是真实且代价高昂的。

如果 documents.root_path 是比平面更深一层组织的文件夹（NVIDIA 归档通常如此：Schematics/、Design-Guides/、Pinmux/ 等），文件 glob 即使存在正确的文档也可能返回零命中。v0.2 只扫描一层深度 —— 当 0 命中可疑时（documents.root_path 存在但没有字段自动绑定），向用户说明该限制，并提供转入手动提示。

手动提示未匹配字段

对于每个未自动绑定（且未在“加载文档槽位 schema”步骤中被过滤掉）的字段，使用“加载文档槽位 schema”步骤中的标记描述作为提示文本，按文档顺序提示。接受 Enter 和 NA 互换作为“跳过此字段”。当“每个字段的匹配策略”步骤为一个字段产生 2+ 个候选命中时，将其显示为带 skip / NA 选项的编号列表，而不是要求自由文本路径。

验证用户提供的路径在磁盘上存在（如果不存在则警告，但不要拒绝 —— 用户可能记录的是计划中的路径）。URL（以 http://、https:// 或 ftp:// 开头的值）原样接受，不进行验证。

将 documents: 块写回 profile

就地编辑 target-platform/<active>.yaml。保留所有其他顶级块（reference_devkit:、custom_carrier:、bsp_image:、source:）及其注释原样。只写入用户提供的字段 —— 完全省略跳过的 / NA 字段（没有 NA 占位符，没有空键）。

边界行为：当所有字段都被跳过（包括 documents.root_path）时，从 profile 中完全删除 documents: 块 —— 绝不写 documents: {} 或一堆 NA 值。当只提供了 documents.root_path（没有文档级绑定）时，单独记录它 —— 该路径对于将来重新运行具有作为提示的价值。在具有现有 documents: 块的情况下重新运行时，合并：除非用户选择新文件或 NA，否则保留现有绑定；新增绑定会添加。

确认

打印摘要：

  • 写入的 profile 路径。
  • documents.root_path — 解析值（或“默认 — 省略”）。
  • 自动绑定字段：数量 + 每个字段的单行列表。
  • 手动输入的字段：数量 + 列表。
  • 跳过的字段：数量。
  • 提醒：jetson-generate-kb 会重新读取 documents.*，如果存在 KB 应重新运行。

如果下游技能触发了此运行，请告诉用户重新发出其原始请求；不要静默地重新触发它。

注意事项

  • 活动 profile 必须存在。 本技能写回当前活动的任何 profile。如果没有活动 profile，拒绝并路由到 jetson-set-target / jetson-init-target。
  • 产品令牌 glob 有意宽泛。 像 *orin*nano* 这样的令牌同时匹配 Orin-Nano 专用文档和组合 Orin-NX/Nano 文档（例如 Jetson-Orin-NX-Nano-Design-Guide_…）。对于模块侧文档这通常是正确的（NVIDIA 提供组合手册），但请在原理图 / 引脚复用 / 规格字段上验证，因为错误产品绑定代价高昂。
  • 添加新产品行时更新 bsp-platforms-catalogue.md。 Product Token 列由“解析产品令牌”步骤使用；缺少令牌会将自动扫描降级为仅 SKU 匹配（技能会警告并继续，但文档丰富的 documents.root_path 扫描会从“5 个自动绑定”静默降级为“更少自动绑定”）。
  • 使用往返 YAML 加载器。 “将 documents: 块写回 profile”步骤会修改现有 YAML 文件。普通 yaml.safe_load + yaml.safe_dump 会丢失注释、块顺序和引用风格 —— 使用 ruamel.yaml 或等效工具，以便保留手动编辑的字段和注释。
  • 可重新运行。 重新运行会合并新的绑定；除非用户显式更改，否则保留现有绑定。作为 profile 刷新的一部分安全调用。

先决条件

  • 按 ../../context/target-platform-contract.md 解析活动目标 profile。
  • 文档要么在记录的 documents.root_path 下，要么在默认的 <workspace>/Documents/ 下，要么在手动提示期间作为用户提供的路径 / URL 提供。缺少根只禁用自动扫描；它不是硬性先决条件。
  • ruamel.yaml 或另一个用于 profile 编辑步骤的往返 YAML 写入器。

限制

  • 仅注册指针；从不下载、复制或重命名文件。
  • 每文档字段集固定为 ../../references/platform_template.yaml 中的 schema —— 不支持临时键。
  • Glob 匹配仅基于文件名；documents.root_path 中文件名错误会导致绑定不足，需要手动选择。

故障排除

  • documents.root_path 缺失 — 跳过自动扫描。提供绝对根路径，手动输入单个文档路径 / URL，或跳过不想绑定的字段。
  • 多个文件匹配单个槽位 — 技能停止并提示；选择或重命名文件。示例：两个 Jetson-Linux-Developer-Guide*.pdf 文件 → 保留活动版本，重命名过期文件。
  • 写入后 profile 注释丢失 — 使用了非往返 YAML 写入器；切换到 ruamel.yaml 并针对新的原始副本重新运行。
  • 验证失败因为绑定指向 documents.root_path 之外 — documents.* 只是相对路径；将文件移到根目录下并重试。

参考