jetson-generate-kb

生成目标知识库

概览

此技能会生成一份按配置文件分别保存的 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/ 等），以及与芯片系列匹配的设备树文件。
3. 文档——配置文件中记录的 documents.* 引用，包括本地路径存在性检查和单行描述。

知识库是带日期的快照，日期会写在标题中。底层数据发生变化时，请重新运行此技能——此技能可重复运行，每次运行都会覆盖之前的知识库。

何时调用

• jetson-init-image 为新建的配置文件准备好 BSP 后。
• 重新解压 BSP 压缩包或在 bsp_image.root_path 下应用补丁后。
• 更新 source.root_path 下的源码树后。
• 编辑配置文件 YAML 中的 bsp_image.* 或 documents.* 后。
• 下游技能询问“X 在此 BSP 中的哪里？”且你想查阅知识库，而不是重新遍历目录树时。

流程

解析当前目标

根据 ../../context/target-platform-contract.md 中的约定解析当前配置文件，并将其 缓存到内存中——此技能的其余步骤仅使用此配置文件。记录 <profile-stem>（不含 .yaml 的纯文件名）， 作为知识库输出文件名的主干。

验证输入

字段	知识库是否必需？	缺失时的处理
bsp_image.root_path	是	拒绝执行。没有 BSP 根目录可供扫描的知识库只是重复陈述 YAML；告知用户运行 jetson-init-image 或手动编辑配置文件。
source.root_path	否	跳过源码树部分；在知识库中注明“未记录 source_root”。
documents.*	否	渲染空的 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 个，则记录总数并注明“仅显示前 30 个”。

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

根据 module.id 推导 <chip>：

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

如果 module.id 不在此表中，将芯片记录为 unknown (module.id=<value>)，并跳过芯片前缀设备树 筛选。

文档处理

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

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

每个字段的一行描述来自 ../../references/platform_template.yaml 中的标记 — 去掉 <OPTIONAL: …> 包装，并使用其中的文本。

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

呈现并写入知识库

使用下方结构呈现 Markdown。标题中使用今天的日期 （YYYY-MM-DD）。始终覆盖目标位置已有的知识库文件 — 覆盖前不要询问；重复运行正是预期用途。

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

呈现后的结构

# Target knowledge base — <profile-stem>

> Generated <YYYY-MM-DD> from `<bsp_image.root_path>` (BSP version `<bsp_image.version>`).
> Re-run `jetson-generate-kb` after extracting a new BSP, applying
> patches, or editing profile fields. This file is a regenerated
> snapshot — do not hand-edit.

## Profile facts

- **Reference devkit:** `<reference_devkit.name>`
- **Module:** `<module.id>-<module.sku>` (`<chip family label>`)
- **Reference carrier:** `<carrier.id>-<carrier.sku>`
- **Custom carrier:** `<custom_carrier.name>` (`<custom_carrier.id>-<custom_carrier.sku>`)  _← omit this row if Case 1_
- **Active flash conf:** `<flash_config>`
- **BSP path:** `<bsp_image.root_path>`
- **BSP version:** `<bsp_image.version>`
- **Source root:** `<source.root_path>`  _← or "_not recorded_" if NA_

## BSP image layout

Top-level directories under `<bsp_image.root_path>`:

| Directory | Present | Purpose |
|---|---|---|
| `rootfs/`     | ✓ / ✗ | userspace rootfs (nvpmodel, nvfan, systemd units, etc.) |
| `bootloader/` | ✓ / ✗ | firmware blobs, BCT, MB1/MB2 dts |
| `kernel/`     | ✓ / ✗ | prebuilt kernel + modules |
| `source/`     | ✓ / ✗ | BSP source tree (kernel, OOT drivers, DT) |
| `tools/`      | ✓ / ✗ | flashing helpers, jetson-io, kernel_flash |
| `nv_tegra/`   | ✓ / ✗ | nvidia firmware tarballs, kernel-supplements |

Active flash conf `<flash_config>`: present at
`<bsp_image.root_path>/<flash_config>` _or_ `(missing — verify before flashing)`.

### nvpmodel files matching the active SKU

Filtered from `rootfs/etc/nvpmodel/` by `nvpmodel_<module.id>_<module.sku>*.conf`:

- `<each match, one per line>`

The active variant at boot is selected by `nvpower.sh` from
`/proc/device-tree/compatible` plus super / safety state — see
`jetson-customize-nvpmodel` for the resolution rules.

## Source tree layout

(omit this whole section if `source.root_path` is `NA`/missing)

Top-level subtrees under `<source.root_path>`:

| Subtree | Present | Purpose |
|---|---|---|
| `kernel-jammy-src/`   | ✓ / ✗ | mainline 5.x kernel sources |
| `hardware/nvidia/`    | ✓ / ✗ | NVIDIA platform DTs (per chip family) |
| `nvidia-oot/`         | ✓ / ✗ | NVIDIA out-of-tree kernel modules |
| `nvgpu/`              | ✓ / ✗ | GPU driver |
| `nvethernetrm/`       | ✓ / ✗ | ethernet driver |
| `nvdisplay/`          | ✓ / ✗ | display driver |
| `hwpm/`               | ✓ / ✗ | hardware performance monitor |
| `kernel-devicetree/`  | ✓ / ✗ | devicetree sources |

### Devicetree files for chip family `<chip>`

(omit if `kernel-devicetree/generic-dts/dts/` is absent)

Files matching `tegra<chip>*` under `kernel-devicetree/generic-dts/dts/`:

- `<each match, one per line — cap at 30, then a "first 30 of N" note>`

## Documents

| Field | Reference |
|---|---|
| Documents root folder                    | `<doc_root>`                    _or_ _not recorded_ |
| BSP / Jetson Linux developer guide       | `<bsp_developer_guide>`         _or_ _not recorded_ |
| Tegra SoC Technical Reference Manual     | `<soc_tech_ref_manual>`         _or_ _not recorded_ |
| Jetson module data sheet                 | `<module_data_sheet>`           _or_ _not recorded_ |
| Jetson module design guide (PDG)         | `<module_design_guide>`         _or_ _not recorded_ |
| Jetson module thermal design guide (TDG) | `<module_thermal_design_guide>` _or_ _not recorded_ |
| Jetson module schematic                  | `<module_schematic>`            _or_ _not recorded_ |
| Reference carrier board specification    | `<carrier_board_spec>`          _or_ _not recorded_ |
| Reference carrier schematic              | `<carrier_schematic>`           _or_ _not recorded_ |
| Custom carrier schematic                 | `<custom_carrier_schematic>`    _or_ _not recorded / N/A (no custom carrier)_ |
| Reference-devkit pinmux spreadsheet      | `<ref_devkit_pinmux_xls>`       _or_ _not recorded_ |
| Custom-carrier pinmux spreadsheet        | `<custom_carrier_pinmux_xls>`   _or_ _not recorded / N/A (no custom carrier)_ |

(Local paths are tagged ` (missing)` if absent on disk. URLs are
recorded verbatim and not fetched. If `doc_root` is set, also tag
` (missing)` on it if the directory itself is gone — that signals
auto-mapping in `jetson-link-docs` won't work on a re-run.)

## How to refresh this file

Re-run `jetson-generate-kb` whenever any of the following changes:

- the BSP at `<bsp_image.root_path>` is re-extracted, patched, or upgraded,
- the source tree at `<source.root_path>` changes,
- the active profile's `bsp_image.*` or `documents.*` fields are edited.

This file is overwritten on every run. Do not hand-edit it — edit the
source data (profile YAML or the BSP tree) and re-run instead.

确认

打印简短摘要：

• 输出路径：target-platform/<profile-stem>.md。
• BSP 顶层目录数量，以及存在 / 缺失的规范子树。
• 活跃 SKU 的 nvpmodel 匹配数量。
• 源代码树部分：已呈现或已跳过（并说明原因）。
• 文档：已记录字段数量、标记为 (missing) 的本地路径数量。

如果下游技能触发了此次运行，告知用户重新提交其原始请求。

注意事项

• 知识库是快照，不是实时视图。 带日期的标题具有权威性 — 如果日期不是今天，BSP / 源代码 / 文档可能已发生变化。按需重新运行。
• 始终覆盖。 覆盖 target-platform/<profile-stem>.md 中已有的知识库前，不会询问。这是有意设计的 — 可重复运行正是全部意义所在。告知用户不要手动编辑该文件；应编辑配置文件 YAML 或 BSP，然后重新生成。
• 当 bsp_image.root_path = NA 时拒绝执行。 没有 BSP 路径的配置文件会生成没有内容的知识库。不要写入该文件 — 应改为指引用户填写配置文件 YAML。
• 不获取 URL。 文档 URL 按原样记录。升级为深度索引（HTTP HEAD、PDF 解析）不在 v0.1 的范围内。
• 不进行递归扫描。 每个目录只发现一层，最多进行一次定向 glob（nvpmodel + 设备树）。绝不遍历整个 BSP — 它体积庞大且速度缓慢。
• 设备树列表最多列出 30 项，以保持知识库易读。截断时显示“前 30 项，共 N 项”。
• 不要从设置技能中自动调用。 设置技能可以在摘要中建议运行此技能，但由用户选择是否运行。自动运行会隐藏 I/O 步骤，并让 BSP / 文档路径不完整的用户感到意外。
• 文件名冲突风险。 知识库位于 <stem>.yaml 旁边的 target-platform/<stem>.md。不要在 jetson-set-target 的配置文件列表逻辑中误读 .md 文件（它目前只筛选 *.yaml，但添加新文件类型前请先检查）。
• 芯片系列映射表很短。 如果未来添加了表中未列出的模块 SKU，将跳过设备树筛选步骤 — 知识库会记为 chip: unknown，而不是凭空编造 <chip> 前缀。新增芯片时请更新此技能的芯片系列表。

前提条件

• 已根据 ../../context/target-platform-contract.md 解析活动目标配置文件。
• /jetson-init-image 已记录 bsp_image:；这是唯一 必需的磁盘目录树。如果缺少 source.root_path，则渲染知识库时 不包含源代码树部分。
• 可选：如果用户希望包含源代码树发现结果，则 /jetson-init-source 已解析 source:。
• 可选但建议：/jetson-link-docs 已写入 documents: 块。

限制

• 对 BSP 和源代码树进行只读操作；绝不编辑配置文件 YAML 或重写源文件。
• 设备树文件枚举依赖此技能中的芯片系列表；对于未知的模块 SKU，知识库中会记录 chip: unknown，而不会伪造前缀。
• 文件名布局固定为 target-platform/<stem>.md，以便与配置文件 YAML 放在一起；重命名 YAML 会导致链接失效。

故障排除

• 找不到 bsp_image.root_path — 重新运行 /jetson-init-image，以便提取 BSP 并记录路径，然后再重新生成知识库。
• 源代码树扫描包含了错误的子目录 — source.root_path 覆盖值已过时；重新运行 /jetson-init-source，或修正配置文件字段。
• 知识库中缺少 documents: 块 — 从未运行过 /jetson-link-docs；知识库会回退到“未绑定文档”，而不会猜测路径。
• 设备树部分内容过少或为空 — 芯片系列表未涵盖活动 SoC；更新此表并重新运行。

参考资料

• ../../context/target-platform-contract.md — 此技能遵循的读取顺序约定。
• ../../context/bsp-customization-workflow.md — 规范 BSP/源代码子目录列表的来源。
• ../../references/platform_template.yaml — documents 字段单行说明的来源。
• ../jetson-init-target/SKILL.md — 用于编写活动目标身份信息的同级技能。
• ../jetson-init-image/SKILL.md — 用于编写此技能扫描的 BSP 镜像元数据的同级技能。
• ../jetson-set-target/SKILL.md — 用于切换此技能解析的活动指针的同级技能。