hsb-setup

Holoscan Sensor Bridge 演示环境启动

当用户希望端到端启动 Holoscan Sensor Bridge 演示环境时，使用此技能。

此工作流会产生副作用。切勿自动运行。仅当用户明确调用时才运行。

开始前——必需的检查关卡（按顺序执行）

关卡 1 — 读取环境变量。 在执行任何其他操作之前，检查这些变量，并向用户显示解析后的值：

SSH_TARGET      Remote devkit login (e.g. [email protected]). Ask the user if not set.
REMOTE_ROOT     Remote working directory (e.g. /home/nvidia). Ask the user if not set.
REMOTE_SUDO     sudo / sudo -n / "" — default to "sudo" if not set.
REMOTE_SSH_OPTS Additional SSH options (optional).
HSB_PLATFORM    Platform hint — may be empty; will detect from hardware.
HSB_REPO        Custom repo URL — defaults to https://github.com/nvidia-holoscan/holoscan-sensor-bridge.git

SSH_TARGET 和 REMOTE_ROOT 是必需项。如果缺少其中任何一项，请停止并向用户询问。

关卡 2 — 提供阶段计划。 在采取任何行动之前，向用户显示以下准确计划并等待确认：

HSB Setup — Phase Plan
  Phase 0: Token-budget preflight
  Phase 1: Confirm platform, set up SSH, clone repo, study user guide
  Phase 2: Host prerequisite checks and network setup
  Phase 3: Native CLI build (AGX Thor only — skipped for other platforms)
  Phase 4: Build demo container, run it, ping 192.168.0.2, verify FPGA version
  Phase 5: Issues report (with option to save)
  Phase 6: Stop apps, exit container, hand control back to user

关卡 3 — 预先检查令牌预算（阶段 0）。 在建立任何 SSH 连接或更改 devkit 之前运行此检查。完整流程请参阅 ## Token-budget preflight 部分。预算检查通过之前，不要继续执行阶段 1。

说明

输入 /hsb-setup [PLATFORM] [OPTIONS] 来调用此技能。此技能会逐步引导用户完成各个阶段，并在进行更改前提示用户确认。

此技能必须执行的操作

0. 在执行任何远程命令或更改 devkit 配置之前，必须先进行令牌预算预检。 估算完成所有设置阶段所需的令牌数，使用最佳可用的 Claude Code/账户用量查询机制检查用户订阅计划的剩余用量，并向用户显示估算值和查询结果；如果可用预算不足或无法核实，则停止操作。
1. 提示用户确认 devkit 已连接到 holoscan sensor bridge，所有设备均已通电，已连接到外部网络，并且 devkit 安装了正确的 OS 版本。如果已知所有配置参数，则查阅仓库中的用户指南，并绘制 devkit 到 sensor 的连接示意图供用户确认，以确保这与用户的实际设置一致。
2. 用户确认设置已就绪后，如果用户是在外部计算机上运行 Claude 技能，则建立与 devkit 的 SSH 连接。如果 Claude 直接安装在 devkit 上，则可跳过此步骤。
3. 在 devkit 上运行 cat /sys/class/dmi/id/product_name，并根据产品名称到平台的映射（参见“主机平台自动检测”部分），将结果与 HSB_PLATFORM 环境变量进行比较，以验证主机 devkit 平台。如果命令返回已识别且非空的平台名称，但与 HSB_PLATFORM 不同，或者 HSB_PLATFORM 为空，则将 HSB_PLATFORM 更新为检测到的平台，并告知用户此项更改。如果命令返回空值或执行失败，且 HSB_PLATFORM 已设置，则保留现有值。
4. 从最新的 main 分支克隆或更新 GitHub 仓库。默认仓库为公开的 nvidia-holoscan/holoscan-sensor-bridge，但用户可以通过 HSB_REPO 环境变量或 --repo <URL> 命令行标志指定自定义仓库 URL。如果仓库使用 SSH，且未设置 SSH 密钥，则提醒用户并提供 SSH 密钥设置说明。
5. 如果尚不明确，询问用户要使用哪个 devkit/平台。
6. 在克隆的仓库根目录下，研读并理解 docs/user_guide 中的用户指南，了解如何为每种 devkit 和 OS 设置主机环境、演示容器、在容器内外运行应用程序（如适用），以及刷写 FPGA。
7. 将该平台映射到正确的主机设置和容器构建模式，并根据用户指南的说明确保主机设置配置正确；修复并补充缺失的配置，或向用户说明如何修复。
8. 构建演示容器。
9. 运行演示容器。
10. 验证与 192.168.0.2 上开发板的连通性。如果连接失败，询问用户 IP 地址是否可能不同。
11. 读取寄存器 0x80，验证 FPGA 版本。如果 sensor 上的 FPGA 版本与 devkit 上的 hsb 主机软件不匹配，建议用户使用 hsb-flash-skill 将开发板刷写为正确的 FPGA 版本。
12. 分阶段报告进度，清楚说明失败原因，并在放弃前尝试安全的修复方法。
13. 对遇到的每个问题创建报告，说明问题是什么以及如何解决。
14. 允许用户选择将最终报告导出为 md 文件。
15. 设置完成后，停止所有正在运行的应用程序并退出容器，将 devkit 的控制权交还给用户；此时用户应位于终端窗口中的仓库主目录。

支持的平台和构建映射

除非代码库或工作树中的当前文档明确说明其他情况，否则请使用以下映射：

• IGX Orin with dGPU OS/configuration → 使用 sh docker/build.sh --dgpu 构建
• IGX Orin iGPU → 使用 sh docker/build.sh --igpu 构建
• AGX Orin → 使用 sh docker/build.sh --igpu 构建
• AGX Thor → 使用 sh docker/build.sh --igpu 构建
• DGX Spark → 使用 sh docker/build.sh --igpu 构建

如果用户只说“IGX Orin”，请明确询问是 iGPU 还是 dGPU OS/configuration。

主机平台自动检测

在阶段 1（建立 SSH 连接后或在本地运行时），通过读取 DMI 产品名称并将其与 HSB_PLATFORM 环境变量进行比较，核实 devkit 的实际硬件。

产品名称到平台的映射

下表将已知的 /sys/class/dmi/id/product_name 值映射到受支持的 HSB_PLATFORM 值。使用不区分大小写的子串搜索进行匹配——产品名称可能包含其他文本（例如“Developer Kit”、修订版本号）。

product_name 包含（不区分大小写）	映射的 HSB_PLATFORM	备注
IGX Orin	IGX Orin	如果尚不清楚，还需询问是 iGPU 还是 dGPU
AGX Orin	AGX Orin
AGX Thor	AGX Thor
DGX Spark	DGX Spark

如果产品名称与任何已知模式都不匹配，则将其视为无法识别，并转到第 5 步中的手动平台问题。

检测与协调逻辑

在 devkit 上运行以下命令（位于阶段 1 的 SSH heredoc 中或在本地运行）：

DETECTED_PRODUCT=""
if [ -f /sys/class/dmi/id/product_name ]; then
  DETECTED_PRODUCT=$(cat /sys/class/dmi/id/product_name 2>/dev/null | tr -d '\n')
fi

DETECTED_PLATFORM=""
if echo "$DETECTED_PRODUCT" | grep -qi "IGX Orin"; then
  DETECTED_PLATFORM="IGX Orin"
elif echo "$DETECTED_PRODUCT" | grep -qi "AGX Orin"; then
  DETECTED_PLATFORM="AGX Orin"
elif echo "$DETECTED_PRODUCT" | grep -qi "AGX Thor"; then
  DETECTED_PLATFORM="AGX Thor"
elif echo "$DETECTED_PRODUCT" | grep -qi "DGX Spark"; then
  DETECTED_PLATFORM="DGX Spark"
fi

echo "DETECTED_PRODUCT=$DETECTED_PRODUCT"
echo "DETECTED_PLATFORM=$DETECTED_PLATFORM"
echo "HSB_PLATFORM=${HSB_PLATFORM:-}"

收集输出后，应用以下协调规则：

1. DETECTED_PLATFORM 非空且 HSB_PLATFORM 为空 → 将 HSB_PLATFORM 设置为 DETECTED_PLATFORM。提醒用户：

   Platform auto-detected from hardware: <DETECTED_PLATFORM> (product_name: <DETECTED_PRODUCT>).
   HSB_PLATFORM was not set — updating to "<DETECTED_PLATFORM>".
   

2. DETECTED_PLATFORM 非空且与 HSB_PLATFORM 不同 → 将 HSB_PLATFORM 覆盖为 DETECTED_PLATFORM。提醒用户：

   WARNING: Hardware reports "<DETECTED_PLATFORM>" (product_name: <DETECTED_PRODUCT>),
   but HSB_PLATFORM was set to "<HSB_PLATFORM>".
   Updating HSB_PLATFORM to match the detected hardware: "<DETECTED_PLATFORM>".
   

3. DETECTED_PLATFORM 非空且与 HSB_PLATFORM 匹配 → 无需更改。确认：

   Platform verified: <HSB_PLATFORM> matches hardware (product_name: <DETECTED_PRODUCT>).
   

4. DETECTED_PLATFORM 为空（文件缺失、不可读或产品名称无法识别）且 HSB_PLATFORM 已设置 → 保留现有的 HSB_PLATFORM。发出警告：

   Could not auto-detect platform from hardware (product_name: "<DETECTED_PRODUCT>").
   Keeping existing HSB_PLATFORM: "<HSB_PLATFORM>".
   

5. DETECTED_PLATFORM 和 HSB_PLATFORM 均为空 → 转到第 5 步中的手动平台问题。

协调后，将更新后的 HSB_PLATFORM 保存到远程会话状态文件中，以便后续阶段使用正确的值。

适用于 Linux/Windows 的包装器变量

从 Linux/Windows 使用此技能，且本地 Claude Code 会话通过 SSH 调用命令时，如果以下环境变量已设置，请优先使用：

• SSH_TARGET：远程登录目标，例如 nvidia@agx-thor-host
• REMOTE_ROOT：远程工作目录，即代码库应所在的位置
• REMOTE_SUDO：用于特权命令。接受 sudo、sudo -n 或空字符串
• REMOTE_SSH_OPTS：其他 SSH 选项
• HSB_PLATFORM：可选的平台提示
• HSB_REPO：用于克隆的自定义 GitHub 代码库 URL（例如 https://github.com/myorg/my-hsb-fork.git）。如果未设置，默认使用 https://github.com/nvidia-holoscan/holoscan-sensor-bridge.git

如果这些变量已设置，请告知用户这些设置，并使用它们，除非用户明确要求覆盖。

在阶段 1 之前，打印解析后的远程执行设置；如有需要，请对机密信息进行脱敏。

强制交互模式

在进行任何更改之前，先展示上方 Gate 2 中的阶段计划。非 Thor 平台跳过 Phase 3。

然后每次只执行一个阶段。

每个非最终阶段（Phases 0–5）结束后：

1. 显示阶段摘要。详细程度取决于 --verbose 模式（参见“Verbosity mode”部分）：
   • Verbose：完整输出 + 详细状态块（阶段名称、执行内容、结果、下一步操作）。
   • 简洁（默认）：使用项目符号总结，并突出显示问题。
2. 向用户询问 Proceed to Phase <N+1>? [Y/n]，同时说明 Phase N+1 是什么，并等待确认后再继续（参见“Phase gate”部分）。

如果出现故障，不要只倾倒原始日志。请总结：

• 失败的确切命令
• 可能的根本原因
• 接下来将尝试的安全修复
• 修复是否成功

Token 预算预检

Phase 0 - token 预算预检

此阶段为必需阶段，必须在任何 SSH 连接、克隆仓库、检查软件包/配置、构建容器、重启或更改 devkit 设置之前执行。

1. 估算整个设置工作流的完整运行所需 token 预算，而不仅是下一阶段所需预算。以下数值是保守的启发式估算，并非基于历史用量的实测值。请将其视为初始安全预算，并在获得实测 token 用量后，根据实际的 /hsb-setup 运行日志进行调整：

   • IGX Orin、AGX Orin 或 DGX Spark 的完整设置运行至少预留 280,000 tokens。
   • AGX Thor 至少预留 340,000 tokens，因为原生构建和 SIPL/FuSa 检查会增加阶段和故障排查工作。
   • 如果预计会使用 --verbose、处理自定义仓库、修复 SSH 密钥、恢复重启或进行额外故障排查，则增加 60,000 tokens。
   • 如果平台尚未确定，则采用较大的估算值。

2. 使用当前订阅计划所能获取的最佳 Claude Code/账户用量来源，检查剩余额度。如果有机器可读的数据或产品提供的用量数据，请优先使用。如果没有可靠的用量来源，请让用户提供其 Claude Code 账户或计划界面中显示的当前剩余额度。

   如果无法自行核实用量，需要询问用户，请按以下确切顺序提供选项，以便先显示安全停止选项：

   1. 我无法核实 — 停止：用户无法确定剩余额度。在 Phase 1 之前停止。
   2. 我有 < {estimate} 可用 — 停止：用户已查看其计划/账户界面，并确认剩余额度低于估算预算。在 Phase 1 之前停止。
   3. 我有 ≥ {estimate} 可用 — 继续：用户已查看其计划/账户界面，并确认剩余额度至少达到估算预算。继续 Phase 1。
   4. 输入其他内容：将其视为问题或自由格式指令，回答后，再按相同顺序重新提示选项。

   不要将继续选项放在首位。用户必须主动越过停止选项后才能选择继续。

3. 继续之前，向用户显示结果：

   Token-budget preflight
   - Estimated tokens required for complete /hsb-setup run: <estimate>
   - Estimate basis: conservative heuristic; refine from actual run logs when available
   - Safety margin included: <margin>
   - Remaining plan usage available: <available or "unverified">
   - Result: PASS / FAIL
   

4. 预算不足或无法核实预算时停止：

   • 如果剩余额度低于估算值，则在 Phase 1 之前停止，并说明该技能拒绝启动，因为它可能在修改 devkit 设置时耗尽 token。
   • 如果无法核实剩余额度，则在 Phase 1 之前停止，并要求用户开启新会话、升级/刷新用量，或提供可核实的剩余额度。
   • --y 不能绕过此预检。

缺少信息时要询问的平台问题

只询问必要的问题：

1. 你使用的是哪个平台？
   • IGX Orin iGPU
   • IGX Orin dGPU
   • AGX Orin
   • AGX Thor
   • DGX Spark
2. HSB 板是否已实际连接并通电？
3. 你是否接受需要使用 sudo 进行网络和 Docker 设置的命令？

如果用户已经提供了其中任何信息，就不要再次询问。

可用脚本

脚本	用途	参数
scripts/hsb_phase_runner.sh	按阶段执行结构化 Shell 命令，并为每个阶段生成带时间戳的日志	<phase_name> <command>

使用 run_script(scripts/hsb_phase_runner.sh, <phase_name>, <command>) 运行阶段步骤并自动记录日志。

阶段详情

完整的分步阶段说明、输出样式、详细程度行为、自动批准模式、阶段门规则和持久 SSH 会话模型，请参阅 references/phase-details.md。

恢复手册

在适用时按以下顺序尝试这些修复：

1. 如果故障看起来是暂时性的，请重新运行一次失败的命令。
2. 修复缺失的先决条件（git-lfs、Docker 访问权限、xhost、网络路由）。
3. 刷新仓库状态和 LFS 内容。
4. 只重新运行失败的阶段，不要重新运行整个工作流。
5. 如果仍然受阻，请停止，并提供简明的故障诊断以及一组可供用户复制粘贴的命令。

此技能的支持文件

• 有关此技能使用的权威构建和主机设置摘要，请参阅 docs/platform-mapping.md。
• 有关常见的修复逻辑，请参阅 docs/failure-playbook.md。
• 需要结构化 Shell 命令执行和带时间戳的日志时，可使用 scripts/hsb_phase_runner.sh 作为辅助工具。

内置帮助（--help）

如果 $ARGUMENTS 包含 --help 或 -h，不要运行工作流。而是原样打印以下帮助文本，然后停止：

Holoscan Sensor Bridge — Demo Bring-Up Skill

USAGE
  /hsb-setup [PLATFORM] [OPTIONS]

PLATFORM (optional — will prompt if omitted)
  AGX Orin          NVIDIA Jetson AGX Orin (iGPU, build with --igpu)
  AGX Thor          NVIDIA Jetson AGX Thor (iGPU, build with --igpu)
  IGX Orin iGPU     NVIDIA IGX Orin in iGPU configuration (build with --igpu)
  IGX Orin dGPU     NVIDIA IGX Orin with discrete GPU (build with --dgpu)
  DGX Spark         NVIDIA DGX Spark (iGPU, build with --igpu)

OPTIONS
  --help, -h        Show this help message and exit
  --verbose         Show full raw command output for every phase
                    (default is concise bullet-point summaries)
  --y               Auto-approve all phase gates (skip user confirmation
                    between phases). Not recommended — a confirmation
                    warning is shown before proceeding. All output is
                    saved to a timestamped log file.
  --repo <URL>      Clone a custom GitHub repo instead of the default
                    nvidia-holoscan/holoscan-sensor-bridge.
                    Can also be set via the HSB_REPO env var.
                    Priority: --repo flag > HSB_REPO env var > default repo

ENVIRONMENT VARIABLES (set before invoking the skill)
  SSH_TARGET        Remote login target (e.g. [email protected])
  REMOTE_ROOT       Remote working directory for repo clone and builds
  REMOTE_SUDO       Privilege escalation: 'sudo', 'sudo -n', or ''
  REMOTE_SSH_OPTS   Additional SSH options (e.g. -o ServerAliveInterval=30)
  HSB_PLATFORM      Platform hint (same values as PLATFORM above)
  HSB_REPO          Custom GitHub repo URL (overridden by --repo flag)

WORKFLOW PHASES
  Phase 0   Token-budget preflight; verify enough plan usage for a full run
  Phase 1   Confirm platform, clone repo, and study user guide
  Phase 2   Host prerequisite checks and network setup
  Phase 3   Native build of CLI tools (AGX Thor only, skipped otherwise)
  Phase 4   Build, run demo container, and verify connectivity
  Phase 5   Produce issues report, optionally export to file
  Phase 6   Stop apps, exit container, hand off to user

  The skill prompts for confirmation between each phase.

EXAMPLES
  /hsb-setup AGX Thor
  /hsb-setup AGX Thor --verbose
  /hsb-setup AGX Thor --y
  /hsb-setup IGX Orin dGPU --repo https://github.com/myorg/my-fork.git
  /hsb-setup --help

打印帮助文本后，不要继续执行任何阶段，也不要提问。

调用示例请参阅内置帮助（--help）中的 EXAMPLES 部分。

如果 $ARGUMENTS 包含平台名称，请使用该平台，不要再次询问。解析平台名称前，从参数中移除 --verbose、--y、--repo <URL> 和 --help。