jetson-quick-start

快速入门 — BSP 自定义入口

jetson-quick-start 是一个分发器和信息收集表单。它不会下载、解压、物化源文件、绑定文档或派生载板文件。它会选择设置路径、收集核心答案，然后将这些答案交给负责实际工作的技能。

模式

不要通过单独的提示询问设置模式。应将其作为核心快速入门问卷的第一个字段，并按以下固定顺序显示选项：

1. Auto Setup
2. Guided Setup
3. Use Existing Workspace

将 cancel 作为单独的退出操作提供，而不是设置模式。

模式	适用情形	计划使用的技能
Auto Setup	全新工作区，且网络可用	目标设置、/jetson-download-bsp、/jetson-init-image、/jetson-init-source、/jetson-link-docs、/jetson-generate-kb、可选的 /jetson-derive-carrier
Guided Setup	用户已有路径、仓库或存档	目标设置、/jetson-init-image、/jetson-init-source、/jetson-link-docs、/jetson-generate-kb、可选的 /jetson-derive-carrier
Use Existing Workspace	BSP 映像、源代码树和文档均已准备就绪	目标设置、工作区验证、/jetson-generate-kb、可选的 /jetson-derive-carrier；仅当缺少前置条件时才转到初始化技能

目标设置是指保留当前配置文件、通过 /jetson-set-target 切换，或通过 /jetson-init-target 创建配置文件。

流程

打印免责声明

在打开核心问卷或检查设置输入之前，准确打印以下免责声明块一次：

================================================================================
DISCLAIMER
These skills help automate Jetson BSP setup and customization, but they do not
replace NVIDIA official documentation or engineering review. Review generated
plans, commands, diffs, and commit messages before accepting them.

Flashing can erase device storage or leave a target temporarily unbootable.
Keep backups and verify the active target, BSP release, and hardware setup
before deploy steps.
================================================================================

免责声明确认关卡

打印免责声明后，立即打开一个单问题的独立 AskUserQuestions 免责声明表单，并等待用户提交答案后再执行任何其他操作。不要通过纯文本聊天回复、推断的默认值、先前运行状态、当前配置文件、缓存答案或任何其他非 UI 信号收集免责声明确认。

该表单必须且只能包含一个问题：

1. accept_disclaimer — 提示语：“接受免责声明并继续快速入门？”选项：accept_disclaimer 和 cancel。

只有已提交的 accept_disclaimer 选项才算接受。免责声明表单与核心问卷分开，不能替代四个对路由至关重要的核心问题。

如果无法打开表单、表单不可用、用户取消、未返回已提交的答案集，或返回了 accept_disclaimer 以外的任何答案，则立即停止，并说明必须通过 AskUserQuestions 接受免责声明后才能继续快速入门。

强制问卷关卡

免责声明获接受后，jetson-quick-start 必须打开核心 AskUserQuestions 问卷，并等待用户提交答案后才能分发任何设置任务。如果无法打开问卷、问卷不可用、用户取消，或未返回已提交的答案集，则立即停止，并说明没有问卷就无法继续快速入门。

不要使用现有的当前配置文件、工作区状态、tarball 名称、缓存答案、发行版兼容性或“显而易见”的默认值继续操作。在此关卡收到已提交的 mode 答案和规范化的 quick_start_prefill 之前，不要调用下游技能。

调查目标状态

检查 target-platform/active_target.yml 和现有的 target-platform/*.yaml 配置文件。如果存在活动配置文件，显示 reference_devkit.name、可选的 custom_carrier.name 以及活动的 flash_config。不要根据 tar 包、仓库名称 或文档标题推断平台身份。

阅读 ../../references/bsp-platforms-catalogue.md 并解析产品 / 芯片 / SKU / flash-config 表中的每一行。 此目录是完整 active_platform 问卷选项列表的来源。如果列表不完整，请更新目录； 不要在 quick-start 中复制或修补平台列表。quick-start 预处理期间不要读取 jetson-init-target/SKILL.md，也不要运行 init-target 流程；下游目标创建仍由 jetson-init-target 负责。

保持调查轻量，以便尽快显示核心问卷： 读取目标配置文件指针 / 摘要，在有帮助时执行成本低廉的路径存在性 检查，并仅从官方归档获取用于填充 bsp_release 选项所需的轻量级 Jetson Linux 发布元数据。解析所有当前发布版块，而不只是看起来与所选平台匹配的版块。在 用户提交核心问卷之前，不要扫描大型 BSP / 源代码 / 文档目录、检查归档、生成知识库内容或运行设置工具。为全部三种模式准备可能的计划；仅在表单 提交后才选择实际的下游计划。

打印平台参考列表

打开 AskUserQuestions UI 之前，打印从 bsp-platforms-catalogue.md 解析出的完整平台列表，并为本次运行分配稳定的数字索引：

Available platforms:
T234 - Orin
  1. Jetson AGX Orin 64GB | CVM P3701-0005 | CVB P3737-0000 | jetson-agx-orin-devkit.conf
  ...
T264 - Thor
  N. Jetson AGX Thor T5000 | CVM P3834-0008 | CVB P4071-0000 | jetson-agx-thor-devkit.conf

这些索引仅用于紧接着的问卷。 不要自动选择索引，即使存在活动配置文件或只有一个明显匹配项，也不得自动选择。

提交核心问卷

使用 AskUserQuestions UI，为整个设置流程生成一份可点击选择的核心问卷。不要通过纯文本提示、聊天中的内嵌问题、推断默认值或手动摘要确认来收集 quick-start 答案。

这是硬性关卡：不得跳过，不得使用单配置文件捷径，也不得根据 active_target.yml、文件名、tar 包、仓库 名称、发布版本兼容性、工作区状态、缓存答案或先前运行记录自动选择 mode、active_platform、bsp_release 或 custom_carrier。现有活动配置文件可以作为选项显示，但在用户提交 AskUserQuestions 表单之前，不得选中。

由于 AskUserQuestions 最多只能提出四个问题，核心表单必须仅包含路由必需字段：

1. mode — Auto Setup、Guided Setup、Use Existing Workspace 或 cancel。
2. active_platform — 使用打印出的完整平台列表；遵循下方的 active-platform 问题规则。
3. bsp_release — 本次运行从官方 Jetson Linux 存档生成的近期全局具体版本候选项快捷选项，按点分隔的数字顺序从新到旧排列，另加 skip。严格保留官方列出的每个版本标记；具体标记可以有两个或三个数字部分，例如 38.2、38.2.1、38.4 或 R36.4.4。不要将 38.2 规范化为 38.2.0，也不要推断缺失的补丁版本号。不要硬编码或缓存候选项。如果元数据获取缓慢或失败，仍须显示 skip 和一个可输入的具体版本选项。快速启动时不要按平台筛选此列表；至少包含存档中每个当前主要版本系列的最新具体版本条目。如果解析结果只包含一个主要版本系列，则视为版本列表不完整，并改为提供 skip 和输入选项，而不是显示不完整的候选列表。
4. custom_carrier — 如果所选/当前配置文件已有自定义载板，则提供 keep_existing_custom_carrier、 no_custom_carrier、 add_custom_carrier 和 skip；否则提供 no_custom_carrier、add_custom_carrier 和 skip。

用户只提交一次此 AskUserQuestions 表单。只有在提交后， mode、当前平台、BSP 版本和自定义载板意图才能决定运行哪些下游技能，以及使用或忽略哪些预填答案。如果没有已提交的表单结果，则停止；绝不继续使用推断出的答案。add_custom_carrier 仅用于路由意图；载板名称、ID、SKU、修订版和自定义刷写配置仍由下游负责。

使用共享的 User input prompt style 渲染表单，并将提交的 UI 答案规范化为 quick_start_prefill。遵循共享的 quick_start_prefill contract。 当前平台问题规则：

• 在问卷前打印完整的带索引平台列表。
• 显式选项仅包括每个芯片系列组的第一行，并标注完整列表中的索引和产品名称，例如 Index 1 — Jetson AGX Orin 64GB。
• 对于所有其他平台，用户选择 Type something，并输入打印列表中的数字索引。Type something 必须是工具内置的自由输入行，不能是自定义显式选项。
• 提示文本："选择一个平台快捷选项，或选择 Type something 并输入上方打印的完整平台列表中的数字索引。输入 skip 可跳过平台选择，并由下游设置流程稍后询问。"
• 只有平台快捷选项可以作为显式选项。不要添加 skip、Other 或自定义手动输入选项；必须通过内置的 Type something 路径输入 skip。提示文本中不要将 Type something 改写为 Other。
• 不要在此处解析刷写配置变体；将所选目录条目传递给 jetson-init-target，由其负责验证和选择刷写配置。

每个非 skip 答案都必须明确，并且可由负责的下游技能直接使用；任何未知内容都使用 skip。BSP 版本答案必须是具体版本标记，可带可选前缀 R，并包含两个或三个数字部分（例如 R38.4、38.2、38.2.1 或 36.4.4）。像 R38.x 这样的系列占位符或“稍后固定版本”都不可接受；应改用 skip。传递 quick_start_prefill.download.bsp_release 时，严格保留用户/源版本标记。 镜像路径、源代码路径、文档路径、载板详情、仓库覆盖项、工具链选择和文档绑定都属于非核心设置细节。将这些事项交由负责的下游技能处理。下游设置技能在安全的情况下应采用文档说明的默认值，无需提问；只有遇到冲突、覆盖、不兼容的发行版、缺失的构件，或用户要求覆盖默认值时才提问。

对于 Auto Setup，/jetson-download-bsp 负责列出所选平台支持的 BSP 发行版，并在平台与 BSP 不兼容时发出警告。快速开始可以传递用户请求的全局候选项或指定的发行版，但不会自行验证支持情况或覆盖兼容性决策。

构建预填信息包

仅规范化明确提供且非 skip 的答案，并将其保留在内存中：

quick_start_prefill:
  mode: Auto Setup | Guided Setup | Use Existing Workspace
  target: { active_platform, custom_carrier }
  download: { bsp_release }

省略任何跳过的字段，并省略没有核心答案的所有者子集。只需进行足够的验证以避免明显的路由错误，例如模式为空或 BSP 占位符。下游默认值属于技能行为，不是预填字段。不要编造缺失的身份信息，也不要从快速开始写入配置文件区块。

调用下游技能

根据 quick_start_prefill.mode、目标状态和前置条件检查来制定下游计划。调用下游技能前，打印一份不阻塞流程的执行计划摘要，其中包括所选模式、目标平台意图、请求的 BSP 发行版或交由下游选择发行版的安排、自定义载板意图、按顺序计划调用的下游技能，以及下游技能可能仍会询问的非核心细节。不要要求用户批准此摘要；除非用户在核心问卷中选择了 cancel，否则继续分派任务。这不会绕过下游的阻塞式验证关卡。

将相关的 quick_start_prefill 子集以及顶层 mode 传递给每个下游技能。 下游技能必须使用有效的预填答案，并针对缺失、无效、含糊或不兼容的必填输入再次提问；同时负责修改其配置文件区块：reference_devkit:、custom_carrier:、bsp_image:、source: 或 documents:。

对于 Use Existing Workspace，请验证：

• <bsp_image.root_path or workspace/Image>/Linux_for_Tegra/ 存在。
• Linux_for_Tegra/rootfs/etc/nv_tegra_release 存在，证明 apply_binaries.sh 已运行；否则转到 /jetson-init-image。
• <source.root_path or workspace/Source>/Linux_for_Tegra/ 存在且为 git 仓库。
• 存在时，记录的 documents: 路径均存在。

最后说明已执行的技能、已跳过的技能、尚待解答的下游问题，以及工作区是否已准备好用于 customize-*。

建议的 I/O 定制后续步骤

在分发摘要后，仅当活动配置文件的 documents: 块中至少有一个与载板相关的槽位通过 /jetson-link-docs 绑定时，才打印非阻塞的“后续步骤 — I/O 定制”列表。符合条件的槽位包括：

• documents.carrier_board_spec
• documents.carrier_schematic
• documents.ref_devkit_pinmux_xls
• documents.custom_carrier_schematic
• documents.custom_carrier_pinmux_xls

如果这些槽位均未绑定，请跳过此步骤——用户尚未提供这些技能所依赖的载板文件，正确的后续步骤是 /jetson-link-docs，而不是 customize-* 技能。用一行说明（“未绑定载板文档 — 请运行 /jetson-link-docs，先注册载板原理图 / pinmux xlsx，再进行 I/O 定制”），然后停止。

如果至少绑定了一个符合条件的槽位，请打印以下列表。 为板载外设适配开发板通常从 pinmux 和 UPHY 开始，然后针对各控制器分别处理：

• /jetson-customize-pinmux — 每个引脚的 SFIO / 方向 / 上拉状态 （使用 documents.custom_carrier_pinmux_xls 或 documents.ref_devkit_pinmux_xls）。
• /jetson-customize-uphy — 通过 ODMDATA 分配 UPHY 通道 （使用 documents.module_design_guide 和 documents.custom_carrier_schematic / documents.carrier_schematic）。
• /jetson-customize-pcie — 每个控制器的 PCIe 布线 （使用 documents.module_design_guide、 documents.custom_carrier_schematic / documents.carrier_schematic， 以及 documents.custom_carrier_pinmux_xls / documents.ref_devkit_pinmux_xls）。
• /jetson-customize-usb — 启用 / 禁用 USB2 / USB3 SS 端口 （使用 documents.module_design_guide、 documents.custom_carrier_schematic / documents.carrier_schematic， 以及 documents.custom_carrier_pinmux_xls / documents.ref_devkit_pinmux_xls）。
• /jetson-customize-mgbe — 多千兆以太网 PHY 布线 （使用 documents.module_design_guide、 documents.custom_carrier_schematic / documents.carrier_schematic， 以及 documents.custom_carrier_pinmux_xls / documents.ref_devkit_pinmux_xls）。
• /jetson-customize-camera — CSI / MIPI / GMSL 传感器启用 （使用 documents.module_design_guide 和 documents.custom_carrier_schematic / documents.carrier_schematic）。

对于每个建议的技能，如果有必需的 documents.* 槽位尚未绑定，请标注“先运行 /jetson-link-docs 以绑定 ”，而不是隐藏该技能——用户可能希望修正绑定后重试。 此处不要调用 customize-* 技能；快速入门到给出建议为止。

目的

单一入口，用于收集四个对路由至关重要的答案 （mode、active_platform、bsp_release、custom_carrier），并分发到相应的下游 Setup 技能。它不是一站式安装程序——不会自行下载、解压、物化或绑定任何内容。

前置条件

• 可访问 bsp-platforms-catalogue.md（用于构建平台列表）。
• 已提交免责声明 AskUserQuestions 表单中的 accept_disclaimer 答案。
• AskUserQuestions UI 可用——快速入门在未提交免责声明表单和核心问卷表单时会拒绝继续。
• 仅 Auto Setup 分支需要网络访问（/jetson-download-bsp 才是实际的获取工具）。

限制

• 最多询问四个核心问题；任何非核心值（镜像路径、源路径、文档路径、载板 ID、工具链）均由负责的下游技能处理。
• 不验证平台与 BSP 版本的兼容性——这是 /jetson-download-bsp 的工作。
• 不写入 target-platform/*.yaml；配置文件的修改由 /jetson-init-target、/jetson-init-image 等负责。

故障排除

• 以“questionnaire cancelled”退出 — 必须提交表单；重新运行 /jetson-quick-start 并完成四个问题。
• 以“disclaimer not accepted”退出 — 重新运行 /jetson-quick-start，阅读 免责声明，并在准备好继续时，在免责声明表单中选择 accept_disclaimer。
• 未自动选择活动配置文件 — 这是设计如此；即使只有一个匹配的配置文件，用户也必须在表单中明确选择。
• 输入了未知的 bsp_release — 按原样传入；/jetson-download-bsp 会根据官方归档验证该版本。

注意事项

• 核心问卷只询问一次。下游技能会询问非核心值、空值、无效值或有歧义的选项。
• 将 quick_start_prefill 保留在内存中，除非用户要求保存。
• 此处绝不要构造 NVIDIA 工件 URL；/jetson-download-bsp 会从所选的 Jetson Linux 归档版本中跟进链接。
• platform_template.yaml 没有 User Guide / Release Notes 栏位。请将这些文件或 URL 存放在最终摘要或知识库中，不要将其虚构为配置文件字段。

参考资料

• ../../context/bsp-customization-workflow.md
• ../../references/bsp-platforms-catalogue.md
• ../../references/platform_template.yaml
• ../jetson-download-bsp/SKILL.md
• Jetson Linux 归档：https://developer.nvidia.com/embedded/jetson-linux-archive