jetson-link-docs

jetson-link-docs

概述

此技能会编写当前 Jetson / IGX 目标平台配置文件 YAML 中的 documents: 块，以便下游技能 （/jetson-generate-kb、/jetson-customize-pinmux、camera / 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——没有自定义载板时，这两项毫无意义。此筛选在“扫描并自动匹配”和“为未匹配字段手动提问”步骤中均适用。

解析 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，则完全跳过此步骤（没有扫描目标 → 不提供自动建议；转到“未匹配字段的手动提示”步骤，显示手动提示）。

扫描目录一次（向下一级），并尝试使用以下不区分大小写的 glob 模式，为每个剩余的 <OPTIONAL:…> 字段自动匹配。在 SKU 列中使用配置文件里的小写 module.id / carrier.id / custom_carrier.id 字符串。

字段	SKU glob（主要）	产品 token 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> 是通过目录解析出的产品 token；<custom-token> 根据“解析产品 token”步骤中的 custom_carrier.name 派生。Token 已包含前后缀 *，因此表中不再重复添加。

每个字段的匹配策略

对于有自动匹配结果的每个字段：

• 合并 SKU glob 和产品 token glob 的匹配结果，然后按绝对路径去重 — 同时匹配 两种 glob 的文件只计一次。
• 恰好匹配到 1 个文件 → 显示路径并提示 use this? (yes/no, default yes)。如果选择 yes，则记录路径并跳过 该字段的手动提示。如果选择 no，则转到 “未匹配字段的手动提示”步骤。
• 匹配到 0 个文件 → 跳过该字段的自动建议；转到 “未匹配字段的手动提示”步骤。
• 匹配到 2 个或更多文件 → 在“未匹配字段的手动提示”步骤中将 文件列为编号列表，让用户按编号选择，而不是输入路径；包含 skip / NA 选项。绝不静默绑定多个候选文件中的任何一个。
• 绝不在未经用户确认的情况下静默绑定 — 错误绑定原理图或引脚复用文件会造成实际且高昂的损失。

如果 documents.root_path 下的文件夹层级比平铺目录多一级 （NVIDIA 归档目录经常如此，例如 Schematics/、Design-Guides/、 Pinmux/ 等），即使存在正确文档，文件 glob 也可能匹配到 0 个文件。v0.2 仅扫描一级 — 当匹配到 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”）。
• 自动绑定字段：数量 + 每个字段一行的列表。
• 手动输入字段：数量 + 列表。
• 跳过字段：数量。
• 提醒用户 jetson-generate-kb 会重新读取 documents.*，如果知识库已存在，应重新运行该命令。

如果此次运行由下游技能触发，请告知用户重新提交其原始请求；不要静默地重新触发该请求。

注意事项

• 活动配置文件必须存在。 此技能会写回当前活动的配置文件。如果没有活动配置文件，则拒绝操作，并引导用户使用 jetson-set-target / jetson-init-target。
• 产品标记通配模式有意设置得较宽泛。 像 *orin*nano* 这样的标记既会匹配 Orin-Nano 专用文档，也会匹配 Orin-NX/Nano 组合文档（例如 Jetson-Orin-NX-Nano-Design-Guide_…）。这通常适用于模块侧文档（NVIDIA 会发布组合手册），但对于原理图 / pinmux / 规格字段，错误的产品绑定代价较高，因此请仔细核验。
• 添加新产品行时，请更新 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 中的架构，不支持临时添加键。
• Glob 匹配仅针对文件名；若 documents.root_path 中的文件名不正确， 将导致绑定不足，需要手动选择。

故障排除

• 缺少 documents.root_path — 将跳过自动扫描。请提供 绝对根路径，手动输入单个文档路径 / URL， 或跳过不想绑定的字段。
• 多个文件匹配同一个槽位 — 技能会停止并提示； 请选择或重命名文件。例如，两个 Jetson-Linux-Developer-Guide*.pdf 文件 → 保留当前版本， 重命名旧版本。
• 写入后配置文件注释丢失 — 使用了无法往返还原的 YAML 编写器；请切换到 ruamel.yaml， 并针对全新的原始副本重新运行。
• 绑定指向 documents.root_path 之外，导致验证失败 — documents.* 仅支持相对路径；请将 文件移至根目录下，然后重试。

参考资料

• ../../context/target-platform-contract.md — 目标平台契约；此技能会读取并修改当前配置文件。
• ../../references/bsp-platforms-catalogue.md — “解析产品标记”步骤中 产品标记 列的来源。
• ../../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: 块。