⚡

生成目标平台知识库Skill jetson-generate-kb

该技能根据 BSP 根目录和源码树，为当前活动目标平台生成一份按配置文件隔离的 Markdown 知识库快照，包含 BSP 镜像布局、源码树布局、nvpmodel 匹配和文档引用状态。关键词：Jetson、BSP、知识库、目标平台、源码树、nvpmodel、devicetree、文档索引、生成技能。

BSP与板级支持 0 次安装 0 次浏览 更新于 9/6/2026
名称 jetson-generate-kb
描述 >- 通过遍历 BSP 根目录和源码树，在活动配置文件旁边构建每个目标的知识库 Markdown 文件。 在 init-image / init-source 之后使用；不用于编辑配置文件字段。
版本 0.0.1
开源协议 “Apache-2.0” metadata: data-classification: public
作者 “Jetson Team” tags: - target-platform - knowledge-base - documentation - meta domain: meta

生成目标平台知识库

概述

该技能会生成一份 按配置文件（per-profile） 的 Markdown 参考文件，位置在 target-platform/<profile-stem>.md（与配置文件 YAML 同级）。它将三部分内容合并到一个文件中， 以便未来的 Claude 会话或用户无需重新遍历文件系统即可看到当前目标的结构：

  1. BSP 镜像布局 — bsp_image.root_path 下的一级目录、规范子目录（rootfs/、 bootloader/、source/ 等）是否存在，以及与活动模块 SKU 匹配的 nvpmodel 变体。
  2. 源码树布局 — source.root_path 下的一级子目录（kernel-jammy-src/、hardware/nvidia/、 nvidia-oot/ 等）以及与芯片系列匹配的 devicetree 文件。
  3. 文档 — 配置文件中记录的 documents.* 引用，包含本地路径存在性检查和一行描述。

知识库是一个 快照，在其头部标注日期。只要底层数据发生变化就重新运行本技能—— 它刻意设计为可重复运行，每次运行都会覆盖之前的 KB。

何时调用

  • 在 jetson-init-image 为新建的配置文件准备好 BSP 之后。
  • 在重新解压 BSP 归档或对 bsp_image.root_path 应用补丁之后。
  • 在更新 source.root_path 下的源码树之后。
  • 在编辑配置文件 YAML 中的 bsp_image.* 或 documents.* 之后。
  • 当下游技能询问“这个 BSP 中的 X 在哪里？”而你希望查 KB 而不是重新遍历目录树时。

操作步骤

解析活动目标

按照 ../../context/target-platform-contract.md 中的约定解析活动配置文件； 将其缓存在内存中——技能的其余部分仅使用该配置文件。记录 <profile-stem> （去掉 .yaml 的裸文件名）作为 KB 输出文件名的前缀。

校验输入

字段 KB 是否需要？ 如果缺失
bsp_image.root_path 是 拒绝。没有可扫描的 BSP 根的 KB 只是 YAML 的重复；告诉用户运行 jetson-init-image 或手动编辑配置文件。
source.root_path 否 跳过源码树部分；在 KB 中注明“未记录 source_root”。
documents.* 否 渲染一个空的文档表，注明“未记录文档”。

如果设置了 bsp_image.root_path 但目录在磁盘上不存在，则明确拒绝——不要为不存在的路径虚构布局。

BSP 发现（在 bsp_image.root_path 下）

仅执行以下 廉价的 操作——不做递归扫描，不读取文件内容（仅目录列举）：

  1. 对 bsp_image.root_path 执行 ls -1（一级深度）。记录哪些目录存在。
  2. 对以下每个规范子目录标记存在/缺失：rootfs/、bootloader/、kernel/、source/、tools/、nv_tegra/。
  3. 验证活动的 flash_config 文件是否存在于 <bsp_image.root_path>/<flash_config>。记录其路径或 (missing)。
  4. 列出 rootfs/etc/nvpmodel/，筛选出与 nvpmodel_<module.id>_<module.sku>*.conf 匹配的文件名。记录每个匹配项。 使用小写模块 id（例如 p3767）和在 YAML 中带引号的 sku 字符串（例如 0001）。

源码树发现（在 source.root_path 下）

如果 source.root_path 为 NA 或缺失，则完全跳过此步骤。否则，仅执行：

  1. 对 source.root_path 执行 ls -1（一级深度）。
  2. 对以下每个规范子目录标记存在/缺失：kernel-jammy-src/、hardware/nvidia/、nvidia-oot/、nvgpu/、nvethernetrm/、nvdisplay/、hwpm/、kernel-devicetree/。
  3. 如果 kernel-devicetree/generic-dts/dts/ 存在，列出与 tegra<chip>* 匹配的文件名，其中 <chip> 是芯片系列的数值前缀（见下文芯片系列映射表）。最多记录 30 个；若更多，记录总数并注明“仅显示前 30 个”。

芯片系列映射表（用于“BSP 发现”和“源码树发现”步骤）

从 module.id 推导 <chip>：

module.id 芯片系列 <chip> 前缀
p3701, p3767 T234 — Orin 234
p3834 T264 — Thor 264

如果 module.id 不在上表中，将芯片记录为 unknown (module.id=<值>) 并跳过带芯片前缀的 devicetree 筛选。

文档处理

对于加载的配置文件中 documents.* 的每个字段：

  1. 将值分类为 URL（以 http://、https:// 或 ftp:// 开头）或 本地路径（其他任何内容）。
  2. 对 URL：原样记录。不要抓取 URL —— KB 生成必须保持离线。（未来的技能可以升级为深度索引。）
  3. 对本地路径：检查 os.path.exists。记录路径；如果磁盘上缺失，则附加 (missing)。

每个字段的一行描述来自于 ../../references/platform_template.yaml 中的标记—— 去掉 <OPTIONAL: …> 外层，使用内部文本。

如果配置文件没有 documents: 块，则用一行渲染该部分： _未记录文档——运行 jetson-link-docs 或手动编辑配置文件以添加引用。_

渲染并写入 KB

使用以下结构渲染 Markdown。在头部使用今天的日期（YYYY-MM-DD）。 始终覆盖目标位置已有的 KB 文件——覆盖前不提示；重复运行是预期的用法。

目标位置：target-platform/<profile-stem>.md。

渲染结构

# 目标知识库 — <profile-stem>

> 生成于 <YYYY-MM-DD>，来源 `<bsp_image.root_path>`（BSP 版本 `<bsp_image.version>`）。
> 在解压新 BSP、应用补丁或编辑配置文件字段后重新运行 `jetson-generate-kb`。
> 本文件是重新生成的快照——请勿手动编辑。

## 配置文件事实

- **参考开发套件：** `<reference_devkit.name>`
- **模块：** `<module.id>-<module.sku>`（`<芯片系列标签>`）
- **参考载板：** `<carrier.id>-<carrier.sku>`
- **定制载板：** `<custom_carrier.name>`（`<custom_carrier.id>-<custom_carrier.sku>`）_← 如果是 Case 1 则省略此行_
- **活动闪存配置：** `<flash_config>`
- **BSP 路径：** `<bsp_image.root_path>`
- **BSP 版本：** `<bsp_image.version>`
- **源码根目录：** `<source.root_path>`_← 如果为 NA 则写“未记录”_

## BSP 镜像布局

`<bsp_image.root_path>` 下的一级目录：

| 目录 | 存在 | 用途 |
|---|---|---|
| `rootfs/`     | ✓ / ✗ | 用户空间 rootfs（nvpmodel、nvfan、systemd 单元等） |
| `bootloader/` | ✓ / ✗ | 固件二进制、BCT、MB1/MB2 dts |
| `kernel/`     | ✓ / ✗ | 预编译内核 + 模块 |
| `source/`     | ✓ / ✗ | BSP 源码树（内核、OOT 驱动、DT） |
| `tools/`      | ✓ / ✗ | 刷写辅助工具、jetson-io、kernel_flash |
| `nv_tegra/`   | ✓ / ✗ | NVIDIA 固件 tarball、内核补充包 |

活动闪存配置 `<flash_config>`：存在于
`<bsp_image.root_path>/<flash_config>`_或_`(missing —— 刷写前请验证)`。

### 匹配活动 SKU 的 nvpmodel 文件

从 `rootfs/etc/nvpmodel/` 中按 `nvpmodel_<module.id>_<module.sku>*.conf` 筛选：

- `<每个匹配项，每行一个>`

启动时的活动变体由 `nvpower.sh` 根据
`/proc/device-tree/compatible` 以及超级/安全状态选择——参见
`jetson-customize-nvpmodel` 了解解析规则。

## 源码树布局

（如果 `source.root_path` 为 `NA`/缺失，则省略整个部分）

`<source.root_path>` 下的一级子目录：

| 子目录 | 存在 | 用途 |
|---|---|---|
| `kernel-jammy-src/`   | ✓ / ✗ | 主线 5.x 内核源码 |
| `hardware/nvidia/`    | ✓ / ✗ | NVIDIA 平台 DT（按芯片系列） |
| `nvidia-oot/`         | ✓ / ✗ | NVIDIA 外部树内核模块 |
| `nvgpu/`              | ✓ / ✗ | GPU 驱动 |
| `nvethernetrm/`       | ✓ / ✗ | 以太网驱动 |
| `nvdisplay/`          | ✓ / ✗ | 显示驱动 |
| `hwpm/`               | ✓ / ✗ | 硬件性能监视器 |
| `kernel-devicetree/`  | ✓ / ✗ | devicetree 源码 |

### 芯片系列 `<chip>` 的 devicetree 文件

（如果 `kernel-devicetree/generic-dts/dts/` 不存在则省略）

`kernel-devicetree/generic-dts/dts/` 下匹配 `tegra<chip>*` 的文件：

- `<每个匹配项，每行一个——超过 30 个则截断，并注明“前 30 个，共 N 个”>`

## 文档

| 字段 | 引用 |
|---|---|
| 文档根文件夹                    | `<doc_root>`_或_未记录 |
| BSP / Jetson Linux 开发者指南       | `<bsp_developer_guide>`_或_未记录 |
| Tegra SoC 技术参考手册     | `<soc_tech_ref_manual>`_或_未记录 |
| Jetson 模块数据手册                 | `<module_data_sheet>`_或_未记录 |
| Jetson 模块设计指南（PDG）         | `<module_design_guide>`_或_未记录 |
| Jetson 模块热设计指南（TDG） | `<module_thermal_design_guide>`_或_未记录 |
| Jetson 模块原理图                  | `<module_schematic>`_或_未记录 |
| 参考载板规格    | `<carrier_board_spec>`_或_未记录 |
| 参考载板原理图              | `<carrier_schematic>`_或_未记录 |
| 定制载板原理图                 | `<custom_carrier_schematic>`_或_未记录 / 不适用（无定制载板）_ |
| 参考开发套件 pinmux 电子表格      | `<ref_devkit_pinmux_xls>`_或_未记录 |
| 定制载板 pinmux 电子表格        | `<custom_carrier_pinmux_xls>`_或_未记录 / 不适用（无定制载板）_ |

（本地路径如果磁盘上不存在则标记 ` (missing)`。URL 原样记录且不抓取。
如果设置了 `doc_root`，并且目录本身不存在，也对其标记 ` (missing)`——
这表示重新运行时 `jetson-link-docs` 中的自动映射将无法工作。）

## 如何刷新此文件

在以下任一情况变化时重新运行 `jetson-generate-kb`：

- `<bsp_image.root_path>` 处的 BSP 被重新解压、打补丁或升级，
- `<source.root_path>` 处的源码树发生变化，
- 活动配置文件的 `bsp_image.*` 或 `documents.*` 字段被编辑。

此文件在每次运行时都会被覆盖。请勿手动编辑——应编辑源数据（配置文件 YAML 或 BSP 目录树）后重新运行。

### 确认

打印简短摘要：

- 输出路径：`target-platform/<profile-stem>.md`。
- BSP 一级目录数量以及哪些规范子目录存在/缺失。
- 活动 SKU 的 nvpmodel 匹配数量。
- 源码树部分：已渲染或已跳过（及原因）。
- 文档：记录的字段数，标记为 `(missing)` 的本地路径数。

如果下游技能触发了此运行，则告诉用户重新发起其原始请求。

## 注意事项

- **KB 是快照，不是实时视图。** 带日期的头部是权威的——如果日期不是今天，
  则底层 BSP/源码/文档可能已变化。按需重新运行。
- **始终覆盖。** 覆盖 `target-platform/<profile-stem>.md` 之前不提示。
  这是有意为之——可重复运行是核心意义。告诉用户不要手动编辑文件；应编辑配置文件 YAML 或 BSP 并重新生成。
- **拒绝 `bsp_image.root_path = NA`。** 没有 BSP 路径的配置文件会产生内容空洞的 KB。
  不要生成它——而应指向配置文件 YAML 让用户填写。
- **不抓取 URL。** 文档 URL 原样记录。升级为深度索引（HTTP HEAD、PDF 解析）不在 v0.1 范围内。
- **不进行递归扫描。** 发现操作每个目录只深入一级，最多一次有针对性的 glob（nvpmodel + devicetree）。
  绝不遍历整个 BSP——它巨大且缓慢。
- **devicetree 列表限制为 30 条**，以保持 KB 可读。截断时显示“前 30 个，共 N 个”。
- **不要在安装类技能中自动调用。** 安装类技能可能在总结中建议运行本技能，但由用户选择。
  自动运行会隐藏 I/O 步骤，并让 BSP/文档路径不完整的用户感到意外。
- **文件名冲突风险。** KB 位于 `target-platform/<stem>.md`，与 `<stem>.yaml` 同级。
  不要意外读取 `jetson-set-target` 的配置文件列出逻辑中的 `.md` 文件（它已经过滤为 `*.yaml`，但在添加新文件类型之前请检查）。
- **芯片系列映射表很短。** 如果未来添加了不在表中的模块 SKU，则跳过 devicetree 筛选步骤——
  KB 会记录 `chip: unknown`，而不是虚构 `<chip>` 前缀。新芯片发布时更新此技能的芯片系列表。

## 前提条件

- 活动目标配置文件已按 `../../context/target-platform-contract.md` 解析。
- `bsp_image:` 由 `/jetson-init-image` 记录；这是唯一必需的磁盘树。
  如果 `source.root_path` 缺失，则渲染不带源码树部分的 KB。
- 可选：当用户希望包含源码树发现时，`/jetson-init-source` 已解析 `source:`。
- 可选但推荐：`/jetson-link-docs` 已写入 `documents:` 块。

## 限制

- 对 BSP 和源码树只读；绝不修改配置文件 YAML 或重写源文件。
- devicetree 文件枚举依赖于本技能内部的芯片系列表；未知模块 SKU 会在 KB 中记录为 `chip: unknown`，而不是虚构前缀。
- 文件名布局固定为 `target-platform/<stem>.md`，与配置文件 YAML 同级；重命名 YAML 会使链接失效。

## 故障排查

- **`bsp_image.root_path` 未找到** —— 重新运行 `/jetson-init-image`，以便在重新生成 KB 前解压 BSP 并记录路径。
- **源码树遍历选择了错误的子目录** —— `source.root_path` 覆盖已过期；重新运行 `/jetson-init-source` 或更正配置文件字段。
- **KB 中缺少 `documents:` 块** —— 从未运行 `/jetson-link-docs`；KB 回退为“未绑定文档”，而不是猜测路径。
- **devicetree 部分过短 / 为空** —— 芯片系列表未覆盖当前 SoC；更新表并重新运行。

## 参考

- [`../../context/target-platform-contract.md`](../../context/target-platform-contract.md) —— 此技能遵循的读取顺序约定。
- [`../../context/bsp-customization-workflow.md`](../../context/bsp-customization-workflow.md) —— 规范 BSP/源码子树列表的来源。
- [`../../references/platform_template.yaml`](../../references/platform_template.yaml) —— 文档字段一行描述的来源。
- [`../jetson-init-target/SKILL.md`](../jetson-init-target/SKILL.md) —— 创建设活动目标身份的兄弟技能。
- [`../jetson-init-image/SKILL.md`](../jetson-init-image/SKILL.md) —— 创建本技能扫描的 BSP 镜像元数据的兄弟技能。
- [`../jetson-set-target/SKILL.md`](../jetson-set-target/SKILL.md) —— 切换活动指针的兄弟技能，本技能解析该指针。