HSBFPGA烧录Skill hsb-flash

HSB FPGA 烧录

在用户想要对连接到受支持的 NVIDIA 开发套件的 HSB 板上的 FPGA 固件进行烧录（升级或降级）时，使用此技能。

此技能支持两种板型：

1. HSB Lattice 板 — 独立 FPGA 板，带有 Lattice CPNX100 FPGA
2. Leopard Imaging VB1940 — “一体化”相机，带集成 Lattice FPGA

关键安全规则：绝不混合板型命令。 在 Lattice 板上使用 program_leopard_cpnx100，或在 VB1940 上使用 program_lattice_cpnx100，可能会永久损坏设备。该技能在任何烧录操作之前必须检测并确认板类型，如果板类型不明确或不匹配，则拒绝继续。

此工作流有副作用（会永久修改 FPGA 固件）。切勿自动运行。仅当用户明确调用时才运行。

使用警告： 此技能使用新固件烧录 FPGA。在调用之前，请用户确保他们有足够的 Claude Code 用量/令牌来完成工作流。

开始之前——必需步骤（按顺序首先执行）

Gate 1 — 读取环境变量

检查这些变量并打印解析值：

SSH_TARGET    远程开发套件登录（例如 nvidia@192.168.1.50）。如未设置则询问用户。
REMOTE_ROOT   远程工作目录（例如 /home/nvidia）。如未设置则询问用户。
REMOTE_SUDO   sudo / sudo -n / "" — 默认 "sudo"。
REMOTE_SSH_OPTS 其他 SSH 选项（可选）。
HSB_PLATFORM  平台提示（可选）。

SSH_TARGET 和 REMOTE_ROOT 是必需的。缺失时停止并询问用户。

Gate 2 — 展示烧录摘要和阶段计划

如果用户请求已包含板类型、当前 FPGA 版本和目标 FPGA 版本，则在阶段计划前陈述：烧录工具（Lattice 用 program_lattice_cpnx100，VB1940 用 program_leopard_cpnx100——绝不混用）、manifest 版本和文件名、CLI 标志（--force --accept-eula），过程是单步还是通过网关 2412 的两步。对于 VB1940，说明不需要 v2.0.0 临时仓库。对于从 FPGA 2407 的两步升级，说明第 1 步使用 hololink --force fpga_version（而不是 hololink enumerate，它与 FPGA 2407 不兼容）并采用 v2.0.0 标志位置：hololink --force program scripts/manifest.yaml --accept-eula。

然后展示阶段计划并明确询问：是否可以继续烧录工作流？[Y/n]。

HSB 烧录——阶段计划
  阶段 0：令牌预算预检
  阶段 1：验证板连接，检测板类型（Lattice 或 VB1940），读取 FPGA 版本
  阶段 2：选择目标 FPGA 版本
  阶段 3：准备烧录基础设施和 YAML 文件，提交烧录计划以供批准
  阶段 4：执行烧录过程（带断电重启验证）
  阶段 5：总结报告（可选择保存）
  阶段 6：清理烧录产物

Gate 3 — 令牌预算预检（阶段 0）

在阶段计划展示且用户确认后运行。

Gate 4 — 明确确认板类型

在任何烧录命令前，与用户确认板是 Lattice 还是 VB1940。

说明

通过键入 /hsb-flash [OPTIONS] 调用此技能。技能自动检测板类型，呈现烧录计划，并在每个烧录步骤前要求确认。参见 references/help-text.md 获取完整 --help 输出。

此技能必须执行的操作

0. 运行强制令牌预算预检。
1. 验证 HSB 板连接、SSH 可用性，读取当前 FPGA 版本，并识别板类型（Lattice 或 VB1940）。先尝试 hololink enumerate；失败则回退到 hololink --force fpga_version。对 Lattice 板如仍失败，检出 HSB v2.0.0 仓库重试；如再失败，假设版本为 2407。VB1940 无法读取时询问用户。
2. 询问目标 FPGA 版本（或接受 latest）。可用版本取决于板类型。
3. 处理未记录版本：检查公开 RELEASE_NOTES 中的新版本；若匹配则检出对应仓库并更新本技能映射表；若为开发版本则使用现有仓库烧录。
4. 确定正确烧录流程并准备脚本/YAML。
   • Lattice 板：根据方向选择对应版本仓库；复制/修补 manifest；确定单步或两步流程；阅读用户指南提取命令，添加 --force --accept-eula；注意 v2.0.0 的 flag 位置；完成后清理临时仓库。
   • VB1940：使用现有仓库，始终单步。 提交完整烧录计划供批准。
5. 执行烧录：安全检查、完整日志、每次关键操作前要求明确确认；命令必须在 demo 容器内运行；验证新版本匹配。
6. 生成总结报告并可保存。
7. 清理所有烧录产物。

支持的板类型

板类型	标识符	描述
Lattice	lattice	HSB Lattice CPNX100-ETH-SENSOR-BRIDGE 独立 FPGA 板
VB1940	vb1940	Leopard Imaging VB1940“一体化”Eagle 相机，带集成 Lattice FPGA

支持的 FPGA 版本

Lattice 板 FPGA 版本

版本	YAML 源版本	备注
2407	v2.0.0	支持的最早版本
2412	v2.0.0	两步烧录的网关版本
2507	v2.3.1
2510	v2.5.0	最新支持版本

VB1940 FPGA 版本

版本	YAML 源版本	HSB 版本	备注
2507	v2.3.0	v2.3.0
2510	v2.5.0	v2.5.0	最新支持版本

VB1940 不支持 2407/2412。

烧录基础设施

参见 references/flashing-infrastructure.md。

仓库选择和检出（仅 Lattice）

• 升级：查找目标 FPGA 版本的 YAML 源版本。
• 降级：查找当前 FPGA 版本的 YAML 源版本。
• 如遇未记录版本，自动检查新发布并更新映射。

检出逻辑、两步说明、VB1940 注意及变量保存在 references/phase-details.md 中。

强制交互模式

展示阶段计划并逐步执行，每阶段后询问是否继续。--y 可跳过门控。失败时要总结命令、原因、建议和是否阻塞。

阶段详情/内置帮助/调用示例

分别参见 references/phase-details.md、references/help-text.md。