Name: HSB传感器桥接演示环境搭建技能Skill
Rating: 5 (1 reviews)
Author: hsb-setup


名称	hsb-setup
描述	克隆最新的 NVIDIA Holoscan Sensor Bridge 仓库，询问正在使用哪个受支持的开发套件，按平台配置主机，构建正确的演示容器，运行它，并通过 ping 192.168.0.2 验证 HSB 连接。用于 Holoscan Sensor Bridge 安装、构建、容器启动和首次连通性开通。
作者	“Holoscan Team holoscan-team@nvidia.com”
开源协议	“Apache-2.0”
版本	“1.0.0” tags: - holoscan-sensor-bridge - hsb - setup tools: - Read - Write - Edit - Grep - Glob - Bash disable-model-invocation: true allowed-tools: Read,Write,Edit,MultiEdit,Grep,Glob,Bash metadata:
作者	“Holoscan Team holoscan-team@nvidia.com” team: holoscan tags: - holoscan-sensor-bridge - hsb - setup agents: - claude-code - codex

Holoscan 传感器桥接（HSB）演示环境搭建

当用户希望端到端搭建 Holoscan Sensor Bridge 演示环境时使用此技能。该工作流会产生副作用，切勿自动运行，只有在用户明确调用时才运行。

开始前 —— 必需门禁（先按顺序执行这些）

门禁 1 —— 读取环境变量。 在任何其他操作前，检查这些变量并将其解析值打印给用户：

SSH_TARGET      远程开发套件登录名（如 nvidia@192.168.1.50）。若未设置，询问用户。
REMOTE_ROOT     远程工作目录（如 /home/nvidia）。若未设置，询问用户。
REMOTE_SUDO     sudo / sudo -n / "" — 默认值为 "sudo"（若未设置）。
REMOTE_SSH_OPTS 附加 SSH 选项（可选）。
HSB_PLATFORM    平台提示（可为空；将根据硬件自动检测）。
HSB_REPO        自定义仓库 URL — 默认为 https://github.com/nvidia-holoscan/holoscan-sensor-bridge.git

SSH_TARGET 和 REMOTE_ROOT 为必需项。若缺失，请停止并询问用户。

门禁 2 —— 展示阶段计划。 在采取任何行动前，向用户展示以下确切计划并等待确认：

HSB 安装 —— 阶段计划
  阶段 0：Token 预算预检
  阶段 1：确认平台、设置 SSH、克隆仓库、研究用户指南
  阶段 2：主机先决条件检查与网络设置
  阶段 3：原生 CLI 构建（仅 AGX Thor，其他平台跳过）
  阶段 4：构建并运行演示容器，ping 192.168.0.2，验证 FPGA 版本
  阶段 5：问题报告（可选择保存）
  阶段 6：停止应用、退出容器，将控制权交还给用户

门禁 3 —— Token 预算预检（阶段 0）。 在任何 SSH 连接或开发套件更改前运行。完整流程见“## Token 预算预检”部分。预算检查通过前不得进入阶段 1。

说明

通过输入 /hsb-setup [PLATFORM] [OPTIONS] 调用此技能。技能将以交互方式逐阶段推进，并在每次更改前提示确认。

此技能必须完成的事项

在任何远程命令或 devkit 配置更改前运行强制的 token 预算预检。 估算完成所有设置阶段所需 token，使用当前可用的最佳 Claude Code/账户用量机制检查用户剩余套餐用量，向用户显示估算结果；若预算不足或无法验证则停止。
提示用户确认 devkit 已连接到 Holoscan Sensor Bridge，所有设备已通电，可与外部通信，且已安装正确的 OS 版本。若已知所有配置参数，请查阅仓库用户指南，绘制一张“devkit 到传感器”的关系图，供用户确认其当前连接方式。
一旦用户确认设置就绪，若用户从外部计算机运行该技能，则建立到 devkit 的 SSH 连接；若 Claude 已直接安装在 devkit 上，可跳过此步骤。
通过运行 cat /sys/class/dmi/id/product_name 验证 devkit 平台，并使用产品名到平台的映射与 HSB_PLATFORM 环境变量比较。若检测到不同/空的平台，则更新该变量并提醒用户；若命令失败且变量已设置，则保留原值。
从最新 main 分支克隆或刷新 GitHub 仓库。默认仓库为 nvidia-holoscan/holoscan-sensor-bridge，但可通过 HSB_REPO 环境变量或 --repo <URL> 指定自定义仓库。若仓库使用 SSH 但未配置 SSH 密钥，提醒用户并提供配置方法。
若平台尚不明确，询问用户要使用哪个 devkit/平台。
在克隆后的仓库根目录下研究并理解 docs/user_guide，了解各类 devkit 和 OS 的主机环境设置、演示容器、容器内外应用运行（如适用）以及 FPGA 刷写方法。
根据平台映射正确的主机设置和容器构建模式，并按用户指南配置主机；修复缺失配置或引导用户自行修复。
构建演示容器。
运行演示容器。
验证与 192.168.0.2 的连接；若失败，询问用户是否可能使用其他 IP 地址。
读取寄存器 0x80 验证 FPGA 版本。若传感器上的 FPGA 版本与 devkit 上的 HSB 主机软件不匹配，建议用户使用 hsb-flash-skill 将板卡刷写至正确 FPGA 版本。
分阶段汇报进度，清晰解释失败原因，并在放弃前尝试安全修复。
针对每个遇到的问题生成报告，说明问题及解决过程。
允许用户选择是否将最终报告导出为 md 文件。
设置完成后停止所有运行中的应用并退出容器，在仓库主目录的终端窗口将 devkit 控制权交还用户。

支持平台与构建模式

除非当前工作树中的仓库/文档明确说明其他方式，否则使用以下映射：

带 dGPU OS/配置的 IGX Orin → 使用 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/配置。

主机平台自动检测

阶段 1（SSH 建立后或本地运行时）应读取 DMI 产品名并与 HSB_PLATFORM 环境变量对比。产品名与平台的映射：

product_name 包含（不区分大小写）	HSB_PLATFORM	备注
`IGX Orin`	`IGX Orin`	若未知，还需询问 iGPU/dGPU
`AGX Orin`	`AGX Orin`
`AGX Thor`	`AGX Thor`
`DGX Spark`	`DGX Spark`

若产品名无匹配项，则视为无法识别，并回到手动平台问题。

在 devkit 上运行以下检测脚本，并按照一致性规则处理结果（详见原英文文档）：

# 检测逻辑示例
DETECTED_PRODUCT=$(cat /sys/class/dmi/id/product_name 2>/dev/null | tr -d '
')
# ...

检测后若 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：自定义仓库 URL，默认见前文

若已设置这些变量，通知用户并直接使用，除非用户显式覆盖。阶段 1 前打印已解析的远程执行设置（必要时对机密信息脱敏）。

强制交互模式

在执行任何更改前展示阶段计划；非 Thor 平台跳过阶段 3。逐一执行阶段。每个非最终阶段（0–5）结束后：

展示阶段摘要，详细度由 --verbose 决定：详细模式显示完整输出和状态块；简洁模式显示要点和问题。
提示 Proceed to Phase <N+1>? [Y/n]，并等待用户确认。

若失败，不得直接倾倒原始日志，应总结：失败命令、可能原因、下一步安全修复、修复是否成功。

Token 预算预检

阶段 0 为强制阶段，必须在任何 SSH、克隆、配置检查、容器构建、重启或对象修改之前执行。

估算整个设置流程的 token 预算：IGX Orin / AGX Orin / DGX Spark 完整运行至少 280,000 tokens；AGX Thor 至少 340,000 tokens；若涉及 --verbose、自定义仓库、SSH 密钥修复、重启恢复等额外处理，额外增加 60,000 tokens。
使用当前可用的最佳 Claude Code/账户用量来源检查剩余用量；若无法自行验证，按用户提示顺序（先停止选项后继续）向用户请求。
向用户显示预检结果（估算、依据、余量、可用量、PASS/FAIL）。
若剩余用量低于估算或无法验证，停止并阻止进入阶段 1；--y 不能绕过预检。

平台缺失时需询问的问题

使用哪个平台？可选：IGX Orin iGPU、IGX Orin dGPU、AGX Orin、AGX Thor、DGX Spark
HSB 板是否已物理连接并通电？
是否接受需要 sudo 的网络和 Docker 设置命令？

若已提供信息则不再询问。

可用脚本

脚本	用途	参数
`scripts/hsb_phase_runner.sh`	带时间戳日志的结构化 shell 阶段执行	`<phase_name> <command>`

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

阶段详情

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

恢复策略

在适用时按顺序尝试：

若失败看起来是暂时的，重试一次。
修复缺失的先决条件（git-lfs、Docker 权限、xhost、网络路由）。
刷新仓库状态和 LFS 内容。
仅重跑失败阶段，不要重跑整个工作流。
仍无法解决则停止，给出简洁诊断和可复制粘贴的命令列表。

此技能的相关支持文件

权威构建与主机设置摘要：docs/platform-mapping.md
常见修复逻辑：docs/failure-playbook.md
结构化执行辅助脚本：scripts/hsb_phase_runner.sh

内置帮助（`--help`）

若 $ARGUMENTS 含 --help 或 -h，不要运行工作流，而是输出以下帮助文本并停止：

Holoscan 传感器桥接 —— 演示环境搭建技能

用法
  /hsb-setup [平台] [选项]

平台（可选，省略时提示）
  AGX Orin        NVIDIA Jetson AGX Orin（iGPU，使用 --igpu 构建）
  AGX Thor        NVIDIA Jetson AGX Thor（iGPU，使用 --igpu 构建）
  IGX Orin iGPU    NVIDIA IGX Orin iGPU 配置（使用 --igpu）
  IGX Orin dGPU    NVIDIA IGX Orin 带独立 GPU（使用 --dgpu）
  DGX Spark       NVIDIA DGX Spark（iGPU，使用 --igpu）

选项
  --help, -h      显示帮助并退出
  --verbose       显示每阶段完整原始输出（默认为简洁要点）
  --y             自动批准阶段门（跳过确认），不推荐
  --repo <URL>    克隆自定义仓库，优先级高于 HSB_REPO

环境变量
  SSH_TARGET, REMOTE_ROOT, REMOTE_SUDO, REMOTE_SSH_OPTS, HSB_PLATFORM, HSB_REPO

阶段
  0 Token 预算预检
  1 平台确认、克隆仓库、研究指南
  2 主机检查与网络设置
  3 原生 CLI 构建（仅 AGX Thor）
  4 构建/运行容器并验证连通性
  5 生成报告（可导出）
  6 停止并交还控制权

示例
  /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。