jetson-init-target

初始化目标平台

概述

此技能用于编写新的目标平台配置 YAML，即 ../../context/target-platform-contract.md 中契约的写入端。它使用 ../../references/bsp-platforms-catalogue.md 作为权威产品 / 刷写配置目录，并使用 ../../references/platform_template.yaml 作为字段架构。

流程是线性的：选择参考产品和刷写配置，然后可选地添加自定义载板详情。两种契约情况——仅参考产品，以及参考产品 + 自定义载板——仅根据用户是否提供自定义载板详情来区分；不会预先询问模式。

范围仅限 reference_devkit: 和 custom_carrier:。 其他区块由同级技能负责：bsp_image: → jetson-init-image；source: → jetson-init-source；documents: → jetson-link-docs。

输出：新的 target-platform/<name>.yaml，以及（默认情况下）指向该文件的更新版 active_target.yml。若要在已编写的配置之间切换，请使用同级技能 jetson-set-target。

调用时机

• 用户要求创建 / 编写 / 添加新的目标平台配置。
• 下游技能因“没有活动目标”而拒绝，且 target-platform/ 中尚无配置 YAML 文件（否则优先使用 jetson-set-target）。
• 用户需要的目标配置尚未存在于磁盘上。

流程

快速启动预填映射

遵循共享的 quick_start_prefill contract。 此技能使用：

• quick_start_prefill.target.active_platform：当其解析为唯一产品时，作为选定的目录条目。
• quick_start_prefill.target.custom_carrier：作为自定义载板意图。

如果 active_platform 解析为一个目录条目，则直接使用。不要再次询问参考产品或刷写配置；使用该条目的默认刷写配置，除非预填内容指定了目录中的某个变体。仅当预填内容缺失、无效、有歧义或指定未知变体时才提问。

技能如何使用模板

在技能启动时加载一次 ../../references/platform_template.yaml，并将其视为提问区块的架构。每个占位值都带有以下三种哨兵标记之一：

标记	行为
<REQUIRED: description>	提示用户填写。必须提供值；接受 NA，但需警告用户下游技能可能会拒绝。
<OPTIONAL: description>	提示用户填写。可以跳过（按 Enter 或输入 NA）；跳过的字段会从写入的配置中省略（不留空键，也不使用 NA 占位符）。
<DERIVED: description>	根据 bsp-platforms-catalogue.md 以及用户在“选择参考产品”和“选择刷写配置”步骤中的选择，以编程方式填充。不提示用户填写。

将标记描述原样用作提示文本。YAML 解析去除外围引号后，使用正则表达式 ^<(REQUIRED|OPTIONAL|DERIVED):\s*(.*)>$ 匹配标记。

区块级别的纳入与否（custom_carrier）由技能流程决定，而不是由标记决定——在区块内部添加 / 删除字段仅需修改模板。

调查当前状态

1. 如果 target-platform/ 不存在，则创建该目录，并将 ../../references/active_target_template.yaml 复制到 target-platform/active_target.yml（注意使用 .yml 扩展名）。
2. 读取 target-platform/active_target.yml。
3. 列出 target-platform/*.yaml（排除 active_target.yml）。

情况	操作
不存在任何配置文件 YAML	继续——这是引导初始化情况。新配置将在“写入”步骤中自动设为 active_target（“确认”步骤中不显示激活提示）。
存在配置文件，active: NA	显示现有配置文件列表，并确认用户想要编写新配置（而不是通过 jetson-set-target 激活现有配置之一）。
存在配置文件，且 active: 指向一个存在的文件	显示当前激活的配置和完整列表。询问用户想要（a）在现有配置旁编写新配置，还是（b）通过 jetson-set-target 切换到现有配置之一。如果选择（b），则停止并告知用户运行 jetson-set-target。
active: 指向一个不存在的文件	告知用户该指针已失效；提供编写新配置（并替换指针）或手动修复指针的选项。

读取平台目录

读取 ../../references/bsp-platforms-catalogue.md。 解析 “产品 / 芯片 / SKU / 刷写配置映射” 表——该表是产品名称、CVM/CVB SKU、默认刷写配置和变体后缀的权威来源。不要扫描 Linux_for_Tegra/*.conf 或解析 conf 文件名；目录中已汇总这些信息。

选择参考产品（基准）

提问前打印完整目录列表。按芯片系列对条目分组，并为本次运行中的每个条目分配稳定索引。列表仅根据 bsp-platforms-catalogue.md 构建；不要从示例或其他文档复制平台条目。

从打印的列表中，为每个芯片系列分组选取第一行，构建明确的快捷选项。每个快捷选项标签都必须包含完整列表中的索引和产品名称，例如 Index 1 — Jetson AGX Orin 64GB。不要硬编码产品名称；应从解析出的目录条目中生成快捷选项。这些快捷选项是此问题仅有的明确选项。手动输入索引必须使用工具内置的 Type something 输入项；不要为手动输入额外添加第三个自定义选项。

提示文本：

选择一个平台快捷选项，或选择 Type something 并输入上方完整平台列表中的数字索引。如果你的硬件是搭载这些 Jetson 模块之一的定制载板，请选择最接近的参考开发套件作为基准。输入 cancel 取消本次运行。

不要显示 T234 / Orin family 或 T264 / Thor family 这样的芯片系列选项。不要显示 Type index、Manual entry、Other platform 或任何自定义手动输入选项。唯一的手动输入途径是工具提供的 Type something 行。不要将 Other 添加为选项，也不要在提示文本中将 Type something 改述为 Other。此步骤不接受产品名称子字符串匹配；输入必须是打印出的完整列表中的数字索引或 cancel。不允许输入 skip，因为此技能无法在没有参考平台的情况下编写目标配置文件。

将快捷选项或输入的索引解析为且仅解析为一个目录条目。如果输入的索引超出范围或无效，请显示有效索引范围并再次询问。如果用户输入 skip，请说明 jetson-init-target 需要一个参考平台，并再次询问。如果用户输入 cancel，则停止操作，不写入配置文件。

选择刷写配置

在目录表格中，默认刷写配置是选项 1；变体列列出后缀，即选项 2..N。将后缀追加到默认配置的基础文件名，即可还原每个变体的完整配置文件名。如果某行的变体列中写有 (same as <other>)，则原样复用所引用行的变体列表。仅根据选定的目录行构建此列表。

提示词：

请选择一个数字，或按 Enter 接受默认值（1）。

如果所选行没有变体（目录中标记为 —），则使用默认配置继续执行“可选：添加自定义载板详情”步骤。

边界情况：

• 原始配置变体（目录中标记为 (raw)）。对于 Orin Nano，-a0-maxn (raw) → p3768-0000-p3767-0000-a0-maxn.conf。原样使用原始文件名。
• **(same as <other>) 占位符。**原样复用所引用行的变体。

可选：添加自定义载板详情

选择基准配置和刷写配置后，确定配置文件是否还应记录一个自定义载板。如果 quick_start_prefill.target.custom_carrier 是有效且明确的意图，则直接使用：

• add_custom_carrier → 记录 custom_carrier:，并收集下方缺少的载板元数据。
• no_custom_carrier → 不添加 custom_carrier:，并继续执行“确认”步骤。
• keep_existing_custom_carrier 仅在编辑已有的活动配置文件且其中已包含 custom_carrier: 时有效。由于此技能会创建新配置文件，因此应将其视为意图不明确，并询问下方的自定义载板意向问题。
• skip 或缺少预填值 → 询问下方的自定义载板意向问题。

如果意图尚未明确，则使用 AskUserQuestions 界面询问用户是否还想添加自定义载板。此处为有限选项；仅显示 add 和 skip：

是否要为使用此 Jetson 模块的客户设计载板添加自定义载板详情？（add / skip，默认值为 skip）

如果确定的意图是 skip，则省略 custom_carrier: 块并继续执行“确认”步骤。

如果确定的意图是 add，则通过 AskUserQuestions 界面收集所有仍缺少的 custom_carrier: 值。不得通过纯文本提示、聊天中的内联问题、自由形式的摘要确认、推断出的默认值或作为可选项提供的示例值来收集自定义载板元数据。如果问题数量超出界面限制，则拆分为多个 AskUserQuestions 表单。

在第一个 AskUserQuestions 表单中，按模板文档顺序询问 custom_carrier.name、custom_carrier.id、custom_carrier.sku 和 custom_carrier.revision。对于这四个字段，向用户展示的唯一可选路径必须是工具内置的 Type something 行。不得添加示例值、“其他”、猜测的板卡 ID、猜测的 SKU、常见修订版本字符串或任何明确的领域选项。这些是客户提供的元数据：必须原样保留用户输入的内容，不得要求或验证任何命名约定、前缀、大小写、字符集、位数或 SKU 格式。仅验证必填字段非空，除非用户明确输入 NA。根据约定，必填字段可以填写 NA；请警告用户，如果下游技能要求某字段提供实际值，可能会拒绝继续操作。

已知 custom_carrier.name 后，如果 custom_carrier.flash_config 仍缺失，则通过第二个 AskUserQuestions 表单收集。仅将建议的默认值显示为明确选项，并允许用户使用内置的 Type something 行输入自定义 .conf 文件名。文件名必须非空且以 .conf 结尾；不得根据板卡 ID、SKU 或任何猜测的约定推导文件名。

字段专属行为（仅靠标记无法表达的默认值／建议）：

• custom_carrier.flash_config — 建议使用 kebab-case 格式的默认值 custom_carrier.name + ".conf"（例如："Acme Vision X1" → acme-vision-x1.conf）。
• custom_carrier.name — 提示词："请准确输入您希望记录的面向客户的自定义载板或产品名称。格式不限。"仅使用 Type something。
• custom_carrier.id — 提示词："请准确输入您希望记录的自定义载板 ID 或项目 ID。格式不限。" 仅使用 Type something。
• custom_carrier.sku — 提示词："请准确输入您希望记录的自定义载板 SKU 或变体标识符。格式不限。" 仅使用 Type something；写入 YAML 时加引号，以保留看起来像数字的值及前导零。
• custom_carrier.revision — 提示词："请准确输入您希望记录的自定义载板修订版或构建标识符，或按 Enter 键跳过。格式不限。"仅使用 Type something；跳过时省略。

如果用户不知道某个值，建议在已启动的目标设备上读取 /proc/device-tree/chosen/ids。如果确实无法获取，则必填字段接受 NA，可选字段可以省略。

模板有意省略了 custom_carrier.module 和 custom_carrier.chip_family——模块身份来自 reference_devkit.module（同一块 Jetson 模块可插入这两种载板）。不要重新添加这两个字段。

确认

显示拟定的 YAML。具体格式取决于用户是否在“可选：添加自定义载板详情”步骤中添加了自定义载板详情。**示例：**参见 references/ui-samples.md，其中提供了仅含参考信息和参考信息 + 自定义载板的 YAML 格式示例，以及关于哪个同级技能会追加哪个代码块的说明。

建议的文件名：

• **仅含参考信息：**使用所选目录行中的产品名称转换为 kebab-case，并添加 .yaml 后缀。例如：Jetson AGX Thor T5000 → jetson-agx-thor-t5000.yaml；Jetson AGX Orin 32GB → jetson-agx-orin-32gb.yaml。不要根据 flash_config 推导文件名；多个产品可能共用一个默认 conf。
• **包含自定义载板：**使用转换为 kebab-case 的 custom_carrier.name。例如： "Acme Vision X1" → acme-vision-x1.yaml。

如果建议的文件名唯一，且由所选平台名称或自定义载板名称生成，则直接使用该文件名，无需询问。打印文件名并继续。仅在文件名冲突、生成的名称为空、输入含糊或用户明确要求自定义文件名时才询问。然后处理激活：

• 引导初始化场景（在“调查当前状态”步骤中不存在任何配置文件 YAML）：**不要提示用户。**这是第一个配置文件，因此会在“写入”步骤中自动激活。告知用户正在进行此操作，避免静默自动激活。
• 已存在配置文件：询问是否激活新配置文件（默认：是）。仅当用户要编写多个配置文件以供之后选择时，才拒绝激活——用户可以使用 jetson-set-target 激活其中任意一个。

写入（并可选择激活）

1. 写入 target-platform/<filename>.yaml。如果文件已存在，覆盖前先询问；绝不静默覆盖。

2. 满足以下任一条件时，编辑 target-platform/active_target.yml，将其设为 active: <filename>.yaml：

   • 这是“调查当前状态”步骤中的引导初始化场景（本次运行开始前不存在任何配置文件 YAML）——自动激活，不受此前用户输入影响。
   • 已存在配置文件，且用户在“确认”步骤中同意激活。

   保留头部注释块；仅修改 active: 行。 如果已存在配置文件，且用户拒绝激活，则保持 active_target.yml 不变。

确认

打印摘要：配置文件路径、活动指针（如果未激活，则显示“未更改”）、Tegra 系列（T234 / T264）、是否记录了 custom_carrier:，以及提醒用户下游技能会解析到当前活动的配置文件。如果用户创建了多个配置文件但未激活任何一个，提示他们使用 jetson-set-target 进行选择。

后续步骤（Setup → Customize 链）：

1. /jetson-init-image — 提取 BSP 并追加 bsp_image:。
2. /jetson-init-source — 克隆共享仓库（如果用户希望将 source.root_path 写入配置文件，还可选择覆盖 <workspace>/Source）。
3. /jetson-link-docs (可选) — 在配置文件的 documents: 块中登记预先下载的 BSP / 原理图 / pinmux 文档路径。

然后，在使用任何 customize-* 技能（Customize）之前：

4. /jetson-generate-kb — customize-* 技能会查询此知识库，以获取特定目标的文件位置。
5. /jetson-derive-carrier (仅适用于自定义载板) — 根据参考开发套件生成自定义载板的刷写配置和配套 DTSI。在自定义载板上使用针对单项配置的 customize-* 技能之前，必须先执行此步骤。

如果下游技能触发了本次运行，请告知用户重新发起原始请求；不要静默地再次触发该技能。

前提条件

• 可通过 References 部分中的相对路径访问 bsp-platforms-catalogue.md 和 platform_template.yaml。
• 对 target-platform/ 具有写入权限（如果请求激活，还需对 target-platform/active_target.yml 具有写入权限）。
• 如需查询“这是哪种模组 / 载板？”，需在已启动的设备上访问 /proc/device-tree/chosen/ids。

限制

• 仅负责 reference_devkit:、custom_carrier: 和 active_target.yml 指针；拒绝写入 bsp_image:、source: 或 documents:。
• 不会臆造 SKU、模组 ID、自定义载板元数据或刷写配置 — 如果用户不知道所需值，则记录为 NA 或中止操作。

故障排除

• 用户要求切换而不是创建配置文件 — 拒绝并引导用户使用 jetson-set-target；不要重新创建现有配置文件。
• 在产品命名对应的目录中找不到条目 — 先将条目添加到 bsp-platforms-catalogue.md；不要修改此技能内的产品列表。
• 必填字段仍为 NA — 下游 customize-* 技能可能会拒绝执行；获取缺失值（读取 /proc/device-tree/chosen/ids）后重新运行。
• 激活后 active_target.yml 丢失了注释块 — 使用了无法往返保留内容的 YAML 写入器；切换到 ruamel.yaml 并从模板恢复。

完整的注意事项列表（目录 / 模板分离、NA 处理、conf 冲突规则等）请参阅 references/gotchas.md。

参考资料

• ../../references/bsp-platforms-catalogue.md — 产品 / 刷写配置目录（是“选择参考产品”和“选择刷写配置”步骤的事实来源）。
• ../../context/target-platform-contract.md — 此技能写入的契约。
• ../../references/platform_template.yaml — 目标配置文件的模式模板（是“可选：添加自定义载板详情”步骤的事实来源）。
• ../../references/active_target_template.yaml — 活动目标指针的模式模板。
• ../jetson-set-target/SKILL.md — 同级技能：在已编写的配置文件之间切换活动指针。
• ../jetson-init-image/SKILL.md — 同级技能：提取 BSP 镜像并编写 bsp_image: 块。
• ../jetson-init-source/SKILL.md — 同级技能：克隆共享仓库并（可选）编写 source: 块。
• ../jetson-link-docs/SKILL.md — 同级技能：通过注册预先下载的文件来编写 documents: 块。