hsb-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Holoscan Sensor Bridge demo bring-up

Holoscan Sensor Bridge 演示环境搭建

Use this skill when the user wants to bring up the Holoscan Sensor Bridge demo environment end to end.

This workflow has side effects. Never run it automatically. Only run it when the user explicitly invokes it.

当用户需要端到端搭建Holoscan Sensor Bridge演示环境时，可使用本技能。

本工作流存在副作用。切勿自动运行，仅在用户明确调用时执行。

Before you start — required gates (do these first, in order)

开始前须知——必要前置步骤（按顺序完成）

Gate 1 — Read environment variables. Before doing anything else, check these variables and print their resolved values to the user:

SSH_TARGET      Remote devkit login (e.g. nvidia@192.168.1.50). 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 and REMOTE_ROOT are required. Stop and ask the user for them if either is missing.

Gate 2 — Present the phase plan. Before taking any action, show the user this exact plan and wait for acknowledgement:

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

Gate 3 — Token-budget preflight (Phase 0). Run this before any SSH connection or devkit change. See

## Token-budget preflight

section for the full procedure. Do not proceed to Phase 1 until the budget check passes.

前置步骤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：令牌预算预检
  阶段1：确认平台、设置SSH、克隆仓库、研读用户指南
  阶段2：主机先决条件检查与网络设置
  阶段3：原生CLI构建（仅AGX Thor平台适用 — 其他平台跳过）
  阶段4：构建演示容器、运行容器、ping 192.168.0.2、验证FPGA版本
  阶段5：问题报告（支持保存选项）
  阶段6：停止应用、退出容器、将控制权交还给用户

前置步骤3 — 令牌预算预检（阶段0）。在建立任何SSH连接或修改开发套件之前执行此步骤。查看

## 令牌预算预检

章节获取完整流程。预算检查通过前，不得进入阶段1。

Instructions

使用说明

Invoke this skill by typing

/hsb-setup [PLATFORM] [OPTIONS]

. The skill walks through each phase interactively, prompting for confirmation before making changes.

通过输入

/hsb-setup [PLATFORM] [OPTIONS]

调用本技能。技能会交互式引导完成每个阶段，在进行更改前提示用户确认。

What this skill must do

本技能必须执行的操作

Run the mandatory token-budget preflight before any remote command or devkit configuration change. Estimate the tokens needed to complete all setup phases, check the user's remaining subscription-plan usage with the best available Claude Code/account usage mechanism, display the estimate and result to the user, and stop if the available budget is insufficient or cannot be verified.
prompt the user to confirm that the devkit is connected to the holoscan sensor bridge and everything is powered up and there is an active network connection to the outside world and that the devkit was installed with the proper OS version. if all profile parameters are known look into the repo user guide and draw a diagram of the devkit to sensor for the user to confirm that this is the setup they have.
Once the user confirms the setup is ready, build the ssh connection to the devkit if the user is running the claude skill from an external computer. you can skip this step if claude installed directly on the devkit.
Verify the host devkit platform by running
```
cat /sys/class/dmi/id/product_name
```
on the devkit and comparing the result to the
```
HSB_PLATFORM
```
environment variable using the product-name-to-platform mapping (see "Host platform auto-detection" section). If the command returns a recognized non-empty platform name that differs from
```
HSB_PLATFORM
```
, or if
```
HSB_PLATFORM
```
is empty, update
```
HSB_PLATFORM
```
to match the detected platform and alert the user about the change. If the command returns empty or fails and
```
HSB_PLATFORM
```
is already set, keep the existing value.
Clone or refresh the GitHub repository from the latest
```
main
```
branch. By default this is the public
```
nvidia-holoscan/holoscan-sensor-bridge
```
repo, but the user can override it with a custom repo URL via the
```
HSB_REPO
```
environment variable or the
```
--repo <URL>
```
command-line flag. if the repo is an ssh repo, alert the user if no ssh key is set and provide instructions how to set up the ssh key.
Ask the user which devkit/platform they want to use if it is not already clear.
under the cloned repo root dir, study and understand the user guide at docs/user_guide to learn how to set up host environment for each devkit and OS, demo container, running applications inside and outside the container (where applicable) and flashing the FPGA.
Map that platform to the correct host setup and container build mode and make sure host set up is configured properly per user guide instructions, fix and add any missing configuration or prompt the user with instruction how to fix.
Build the demo container.
Run the demo container.
Verify connectivity to the board at
```
192.168.0.2
```
. if the connection to the board fails, prompt the user for a possiblity of a different ip address.
Verify the FPGA version reading register 0x80. if the FPGA version on the sensor does not match the hsb host software that is on the devkit, suggest the user to use the hsb-flash-skill to flash the board to the proper FPGA version.
Report progress in phases, explain failures clearly, and attempt safe fixes before giving up.
For every issue encountered, create a report that specifies what was the issue and how you overcame it.
Allow the user an option to export the final report to an md file.
once you are done setup, stop any running apps and exit the container giving up control on the devkit to the user at repo home directory on terminal window.

在执行任何远程命令或开发套件配置更改之前，运行强制令牌预算预检。估算完成所有设置阶段所需的令牌数量，使用最佳可用的Claude Code/账户使用机制检查用户剩余的订阅计划使用情况，向用户显示估算值和检查结果，若可用预算不足或无法验证则停止操作。
提示用户确认开发套件已连接到Holoscan Sensor Bridge，所有设备已通电，存在对外的活跃网络连接，且开发套件已安装正确版本的操作系统。若所有配置参数已知，查看仓库用户指南并绘制开发套件到传感器的示意图，供用户确认是否与他们的设置一致。
用户确认设置就绪后，若用户从外部计算机运行Claude技能，则建立与开发套件的SSH连接。若Claude直接安装在开发套件上，可跳过此步骤。
通过在开发套件上运行
```
cat /sys/class/dmi/id/product_name
```
并将结果与
```
HSB_PLATFORM
```
环境变量（使用产品名称到平台的映射，见“主机平台自动检测”章节）进行比较，验证主机开发套件平台。若命令返回可识别的非空平台名称且与
```
HSB_PLATFORM
```
不同，或
```
HSB_PLATFORM
```
为空，则更新
```
HSB_PLATFORM
```
以匹配检测到的平台，并向用户发出更改提醒。若命令返回空或执行失败但
```
HSB_PLATFORM
```
已设置，则保留现有值。
从最新的
```
main
```
分支克隆或刷新GitHub仓库。默认是公开的
```
nvidia-holoscan/holoscan-sensor-bridge
```
仓库，但用户可通过
```
HSB_REPO
```
环境变量或
```
--repo <URL>
```
命令行标志覆盖为自定义仓库URL。若仓库是SSH仓库，若未设置SSH密钥则提醒用户，并提供设置SSH密钥的说明。
若尚未明确，询问用户想要使用哪个开发套件/平台。
在克隆的仓库根目录下，研读并理解 docs/user_guide 中的用户指南，学习如何为每个开发套件和操作系统设置主机环境、演示容器、在容器内外运行应用（如适用）以及烧录FPGA。
将平台映射到正确的主机设置和容器构建模式，确保主机按照用户指南说明正确配置，修复并添加任何缺失的配置，或提示用户修复方法。
构建演示容器。
运行演示容器。
验证与板卡
```
192.168.0.2
```
的连接。若与板卡的连接失败，提示用户是否可能使用其他IP地址。
通过读取寄存器0x80验证FPGA版本。若传感器上的FPGA版本与开发套件上的HSB主机软件不匹配，建议用户使用hsb-flash-skill将板卡烧录至正确的FPGA版本。
分阶段报告进度，清晰解释失败原因，并在放弃前尝试安全修复。
对于遇到的每个问题，创建一份报告，说明问题是什么以及如何解决。
允许用户选择将最终报告导出为md文件。
设置完成后，停止所有运行中的应用并退出容器，将开发套件的控制权交还给用户，终端窗口停留在仓库主目录。

Supported platforms and build mapping

支持的平台与构建映射

Use the following mapping unless the repository or current docs in the working tree clearly say otherwise:

IGX Orin with dGPU OS/configuration → build with
```
sh docker/build.sh --dgpu
```
IGX Orin iGPU → build with
```
sh docker/build.sh --igpu
```
AGX Orin → build with
```
sh docker/build.sh --igpu
```
AGX Thor → build with
```
sh docker/build.sh --igpu
```
DGX Spark → build with
```
sh docker/build.sh --igpu
```

If the user says only “IGX Orin”, explicitly ask whether it is iGPU or dGPU OS/configuration.

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

带dGPU操作系统/配置的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操作系统/配置。

Host platform auto-detection

主机平台自动检测

During Phase 1 (after SSH is established or when running locally), verify the actual devkit hardware by reading the DMI product name and comparing it to the

HSB_PLATFORM

environment variable.

在阶段1（建立SSH连接后或本地运行时），通过读取DMI产品名称并与

HSB_PLATFORM

环境变量进行比较，验证实际开发套件硬件。

Product-name-to-platform mapping

产品名称到平台的映射

The following table maps known

/sys/class/dmi/id/product_name

values to supported

HSB_PLATFORM

values. Match using case-insensitive substring search — the product name may contain additional text (e.g., "Developer Kit", revision numbers).

`product_name` contains (case-insensitive)	Mapped `HSB_PLATFORM`	Notes
`IGX Orin`	`IGX Orin`	Still need to ask iGPU vs dGPU if not already known
`AGX Orin`	`AGX Orin`
`AGX Thor`	`AGX Thor`
`DGX Spark`	`DGX Spark`

If the product name does not match any known pattern, treat it as unrecognized and fall through to the manual platform question in step 5.

下表将已知的

/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的手动平台询问环节。

Detection and reconciliation logic

检测与协调逻辑

Run the following on the devkit (inside the Phase 1 SSH heredoc or locally):

bash

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:-}"

After collecting the output, apply the following reconciliation rules:

DETECTED_PLATFORM
is non-empty and
HSB_PLATFORM
is empty → set

HSB_PLATFORM

DETECTED_PLATFORM

. Alert the user:

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

DETECTED_PLATFORM
is non-empty and differs from
HSB_PLATFORM
→ override

HSB_PLATFORM

with

DETECTED_PLATFORM

. Alert the user:

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>".

DETECTED_PLATFORM
is non-empty and matches
HSB_PLATFORM
→ no change needed. Confirm:

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

DETECTED_PLATFORM
is empty (file missing, unreadable, or unrecognized product name) and
HSB_PLATFORM
is set → keep the existing

HSB_PLATFORM

. Warn:

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

Both
DETECTED_PLATFORM
and
HSB_PLATFORM
are empty → fall through to the manual platform question in step 5.

After reconciliation, persist the updated

HSB_PLATFORM

in the remote session state file so subsequent phases use the correct value.

在开发套件上运行以下命令（在阶段1的SSH heredoc中或本地运行）：

bash

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:-}"

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

DETECTED_PLATFORM
非空且
HSB_PLATFORM
为空 → 将

HSB_PLATFORM

设置为

DETECTED_PLATFORM

。提醒用户：

从硬件自动检测到平台：<DETECTED_PLATFORM>（product_name: <DETECTED_PRODUCT>）。
HSB_PLATFORM 未设置 — 已更新为 "<DETECTED_PLATFORM>"。

DETECTED_PLATFORM
非空且与
HSB_PLATFORM
不同 → 用

DETECTED_PLATFORM

覆盖

HSB_PLATFORM

。提醒用户：

警告：硬件报告为 "<DETECTED_PLATFORM>"（product_name: <DETECTED_PRODUCT>），
但 HSB_PLATFORM 被设置为 "<HSB_PLATFORM>"。
正在更新 HSB_PLATFORM 以匹配检测到的硬件："<DETECTED_PLATFORM>"。

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

平台已验证：<HSB_PLATFORM> 与硬件匹配（product_name: <DETECTED_PRODUCT>）。

DETECTED_PLATFORM
为空（文件缺失、无法读取或产品名称无法识别）且
HSB_PLATFORM
已设置 → 保留现有

HSB_PLATFORM

。警告：

无法从硬件自动检测平台（product_name: "<DETECTED_PRODUCT>"）。
保留现有 HSB_PLATFORM："<HSB_PLATFORM>"。

DETECTED_PLATFORM
和
HSB_PLATFORM
均为空 → 进入步骤5的手动平台询问环节。

协调完成后，将更新后的

HSB_PLATFORM

持久化到远程会话状态文件中，以便后续阶段使用正确的值。

Linux/Windows-friendly wrapper variables

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

When this skill is used from Linux/Windows with a local Claude Code session that shells out to SSH, prefer these environment variables when present:

```
SSH_TARGET
```
for the remote login target such as
```
nvidia@agx-thor-host
```
```
REMOTE_ROOT
```
for the remote working directory where the repo should live
```
REMOTE_SUDO
```
for privileged commands. Accept
```
sudo
```
,
```
sudo -n
```
, or empty string
```
REMOTE_SSH_OPTS
```
for additional SSH options
```
HSB_PLATFORM
```
as an optional platform hint

HSB_REPO

for a custom GitHub repository URL to clone (e.g.

https://github.com/myorg/my-hsb-fork.git

). If not set, defaults to

https://github.com/nvidia-holoscan/holoscan-sensor-bridge.git

If these are set, notify the user of these settings and use them without re-asking unless the user explicitly overrides them.

Before Phase 1, print the resolved remote execution settings you will use, with secrets redacted if needed.

当本技能从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之前，打印将使用的已解析远程执行设置，必要时隐藏敏感信息。

Mandatory interaction pattern

强制交互模式

Present the phase plan from Gate 2 above before making any changes. Skip Phase 3 for non-Thor platforms.

Then execute one phase at a time.

After each non-final phase (Phases 0–5):

Show a phase summary. The detail level depends on
```
--verbose
```
mode (see "Verbosity mode" section):
- Verbose: full output + detailed status block (phase name, what ran, result, next action).
- Concise (default): bullet-point summary with issues highlighted.
Prompt the user with
```
Proceed to Phase <N+1>? [Y/n]
```
while specifing what is phase N+1 and wait for confirmation before continuing (see "Phase gate" section).

If something fails, do not just dump raw logs. Summarize:

the exact command that failed
the likely root cause
what safe repair you will try next
whether the repair succeeded

在进行任何更改之前，展示前置步骤2中的阶段计划。非Thor平台跳过阶段3。

然后逐个阶段执行。

每个非最终阶段（阶段0–5）完成后：

展示阶段摘要。详细程度取决于
```
--verbose
```
模式（见“详细程度模式”章节）：
- 详细模式：完整输出 + 详细状态块（阶段名称、执行内容、结果、下一步操作）。
- 简洁模式（默认）：项目符号摘要，突出显示问题。
提示用户
```
是否进入阶段<N+1>? [Y/n]
```
，同时说明阶段N+1的内容，等待确认后再继续（见“阶段门控”章节）。

若出现失败，不要直接输出原始日志。需总结：

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

Token-budget preflight

令牌预算预检

Phase 0 - token-budget preflight

阶段0 - 令牌预算预检

This phase is mandatory and must run before any SSH connection, repo clone, package/configuration check, container build, reboot, or devkit setting change.

Estimate the full-run token budget for the entire setup workflow, not just the next phase. The values below are conservative heuristics, not measured historical usage. Treat them as initial safety budgets and refine them from actual
```
/hsb-setup
```
run logs once measured token usage is available:
- Reserve at least 280,000 tokens for a complete setup run on IGX Orin, AGX Orin, or DGX Spark.
- Reserve at least 340,000 tokens for AGX Thor because native build and SIPL/FuSa checks add more phases and troubleshooting.
- Add 60,000 tokens when
```
--verbose
```
  , custom repo handling, SSH key remediation, reboot recovery, or extra troubleshooting is expected.
- Use the larger estimate if the platform is not yet known.
Check remaining usage using the best available Claude Code/account usage source for the current subscription plan. Prefer machine-readable or product-provided usage data when available. If no reliable usage source is available, ask the user to provide their current remaining usage/quota from the Claude Code account or plan UI.

When asking the user because usage cannot be self-verified, present the options in this exact order so the safe stop choices appear first:
1. I can't verify — stop: The user cannot determine remaining usage. Stop before Phase 1.
2. I have < {estimate} available — stop: The user checked their plan/account UI and confirms less than the estimated budget remains. Stop before Phase 1.
3. I have ≥ {estimate} available — proceed: The user checked their plan/account UI and confirms at least the estimated budget remains. Proceed to Phase 1.
4. Type something: Treat as a question or free-form instruction, answer it, then re-prompt with the same ordered options.
Do not put the proceed option first. The user must intentionally move past the stop choices before selecting proceed.

Display the result to the user before continuing:

text

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

Stop on insufficient or unverifiable budget:
- If remaining usage is lower than the estimate, stop before Phase 1 and explain that the skill is refusing to start because it may run out of tokens while modifying devkit settings.
- If remaining usage cannot be verified, stop before Phase 1 and ask the user to start a fresh session, upgrade/refresh usage, or provide verifiable remaining usage.
- ```
--y
```
  must not bypass this preflight.

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

估算完整运行的令牌预算，针对整个设置工作流，而非仅下一阶段。以下为保守启发式值，并非实测历史用量。将其视为初始安全预算，一旦有实测令牌用量数据，从实际
```
/hsb-setup
```
运行日志中优化这些值：
- 对于IGX Orin、AGX Orin或DGX Spark的完整设置运行，至少预留280,000令牌。
- 对于AGX Thor，至少预留340,000令牌，因为原生构建和SIPL/FuSa检查会增加更多阶段和故障排查工作。
- 若预期使用
```
--verbose
```
  、自定义仓库处理、SSH密钥修复、重启恢复或额外故障排查，额外添加60,000令牌。
- 若平台未知，使用较大的估算值。
检查剩余用量，使用当前订阅计划最佳可用的Claude Code/账户用量来源。优先使用机器可读或产品提供的用量数据。若没有可靠的用量来源，询问用户从Claude Code账户或计划UI中提供当前剩余用量/配额。

若因无法自行验证而询问用户，按以下确切顺序呈现选项，确保安全停止选项排在前面：
1. 无法验证——停止：用户无法确定剩余用量。在阶段1前停止。
2. 可用用量<{估算值}——停止：用户已检查计划/账户UI，确认剩余用量少于估算预算。在阶段1前停止。
3. 可用用量≥{估算值}——继续：用户已检查计划/账户UI，确认剩余用量至少为估算预算。进入阶段1。
4. 输入其他内容：视为问题或自由格式指令，回答后重新提示相同的有序选项。
不要将继续选项放在第一位。用户必须有意跳过停止选项后才能选择继续。

向用户显示检查结果，然后再继续：

text

令牌预算预检
- 完整运行/hsb-setup所需的估算令牌数量：<估算值>
- 估算依据：保守启发式值；有实际运行日志时从日志中优化
- 包含的安全余量：<余量>
- 计划可用剩余用量：<可用量或“未验证”>
- 结果：通过/失败

预算不足或无法验证时停止：
- 若剩余用量低于估算值，在阶段1前停止，并说明技能拒绝启动的原因是修改开发套件设置时可能会耗尽令牌。
- 若剩余用量无法验证，在阶段1前停止，并要求用户启动新会话、升级/刷新用量或提供可验证的剩余用量。
- ```
--y
```
  不得绕过此预检。

Platform questions to ask when missing

缺失信息时需询问的平台问题

Ask only the minimum required questions:

Which platform are you using?
- IGX Orin iGPU
- IGX Orin dGPU
- AGX Orin
- AGX Thor
- DGX Spark
Is the HSB board already physically connected and powered on?
Are you okay with commands that require
```
sudo
```
for network and Docker setup?

If the user already provided any of these, do not ask again.

仅询问必要的最少问题：

您使用的是哪个平台？
- IGX Orin iGPU
- IGX Orin dGPU
- AGX Orin
- AGX Thor
- DGX Spark
HSB板卡是否已物理连接并通电？
您是否同意执行需要
```
sudo
```
权限的网络和Docker设置命令？

若用户已提供其中任何一项，请勿再次询问。

Available Scripts

可用脚本

Script	Purpose	Arguments
`scripts/hsb_phase_runner.sh`	Structured shell execution with timestamped logs per phase	`<phase_name> <command>`

Use

run_script(scripts/hsb_phase_runner.sh, <phase_name>, <command>)

to run phase steps with automatic logging.

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

使用

run_script(scripts/hsb_phase_runner.sh, <phase_name>, <command>)

运行阶段步骤，自动生成日志。

Phase details

阶段详情

See references/phase-details.md for full step-by-step phase instructions, output style, verbosity behavior, auto-approve mode, phase gate rules, and the persistent SSH session model.

查看 references/phase-details.md 获取完整的分步阶段说明、输出样式、详细程度行为、自动批准模式、阶段门控规则以及持久SSH会话模型。

Recovery playbook

恢复手册

Try these fixes in order when applicable:

Re-run the failing command once if the failure looks transient.
Fix missing prerequisites (
```
git-lfs
```
, Docker access,
```
xhost
```
, network route).
Refresh repo state and LFS content.
Re-run only the failed phase, not the whole workflow.
If still blocked, stop with a concise diagnosis and a copy-paste command list for the user.

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

若失败看起来是暂时性的，重新运行一次失败的命令。
修复缺失的先决条件（
```
git-lfs
```
、Docker访问权限、
```
xhost
```
、网络路由）。
刷新仓库状态和LFS内容。
仅重新运行失败的阶段，而非整个工作流。
若仍受阻，停止操作并提供简洁的诊断结果和供用户复制粘贴的命令列表。

Supporting files in this skill

本技能中的支持文件

See docs/platform-mapping.md for the authoritative build and host-setup summary used by this skill.
See docs/failure-playbook.md for common remediation logic.
Use scripts/hsb_phase_runner.sh as a helper when you want structured shell execution and timestamped logs.

查看 docs/platform-mapping.md 获取本技能使用的权威构建和主机设置摘要。
查看 docs/failure-playbook.md 获取常见修复逻辑。
当需要结构化shell执行和带时间戳的日志时，使用 scripts/hsb_phase_runner.sh 作为辅助工具。

Built-in help (

--help

)

内置帮助（

--help

）

$ARGUMENTS

contains

--help

-h

, do not run the workflow. Instead, print the following help text verbatim and stop:

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. ubuntu@10.0.0.1)
  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

After printing the help text, do not proceed with any phases or ask any questions.

See the

EXAMPLES

section in Built-in help (

--help

) for invocation examples.

When

$ARGUMENTS

contains a platform, use it instead of asking again. Strip

--verbose

--y

--repo <URL>

, and

--help

from the arguments before parsing the platform name.

若

$ARGUMENTS

包含

--help

或

-h

，请勿运行工作流。相反，逐字打印以下帮助文本并停止：

Holoscan Sensor Bridge — 演示环境搭建技能

用法
  /hsb-setup [PLATFORM] [OPTIONS]

平台（可选 — 若省略将提示用户）
  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>      克隆自定义GitHub仓库而非默认的
                    nvidia-holoscan/holoscan-sensor-bridge。
                    也可通过HSB_REPO环境变量设置。
                    优先级：--repo标志 > HSB_REPO环境变量 > 默认仓库

环境变量（调用技能前设置）
  SSH_TARGET        远程登录目标（例如 ubuntu@10.0.0.1）
  REMOTE_ROOT       用于克隆仓库和构建的远程工作目录
  REMOTE_SUDO       权限提升方式：'sudo'、'sudo -n' 或 ''
  REMOTE_SSH_OPTS   额外SSH选项（例如 -o ServerAliveInterval=30）
  HSB_PLATFORM      平台提示（与上述平台值相同）
  HSB_REPO          自定义GitHub仓库URL（被--repo标志覆盖）

工作流阶段
  阶段0   令牌预算预检；验证计划剩余用量是否足够完成完整运行
  阶段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

）中的

示例

章节获取调用示例。

若

$ARGUMENTS

包含平台，使用该平台而非再次询问。在解析平台名称之前，从参数中移除

--verbose

、

--y

、

--repo <URL>

和

--help

。

hsb-setup

Original

Translation

Holoscan Sensor Bridge demo bring-up

Holoscan Sensor Bridge 演示环境搭建

Before you start — required gates (do these first, in order)

开始前须知——必要前置步骤（按顺序完成）

Instructions

使用说明

What this skill must do

本技能必须执行的操作

Supported platforms and build mapping

支持的平台与构建映射

Host platform auto-detection

主机平台自动检测

Product-name-to-platform mapping

产品名称到平台的映射

Detection and reconciliation logic

检测与协调逻辑

Linux/Windows-friendly wrapper variables

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

Mandatory interaction pattern

强制交互模式

Token-budget preflight

令牌预算预检

Phase 0 - token-budget preflight

阶段0 - 令牌预算预检

Platform questions to ask when missing

缺失信息时需询问的平台问题

Available Scripts

可用脚本

Phase details

阶段详情

Recovery playbook

恢复手册

Supporting files in this skill

本技能中的支持文件

Built-in help (
`--help`
)

内置帮助（
`--help`
）

hsb-setup

Original

Translation

Holoscan Sensor Bridge demo bring-up

Holoscan Sensor Bridge 演示环境搭建

Before you start — required gates (do these first, in order)

开始前须知——必要前置步骤（按顺序完成）

Instructions

使用说明

What this skill must do

本技能必须执行的操作

Supported platforms and build mapping

支持的平台与构建映射

Host platform auto-detection

主机平台自动检测

Product-name-to-platform mapping

产品名称到平台的映射

Detection and reconciliation logic

检测与协调逻辑

Linux/Windows-friendly wrapper variables

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

Mandatory interaction pattern

强制交互模式

Token-budget preflight

令牌预算预检

Phase 0 - token-budget preflight

阶段0 - 令牌预算预检

Platform questions to ask when missing

缺失信息时需询问的平台问题

Available Scripts

可用脚本

Phase details

阶段详情

Recovery playbook

恢复手册

Supporting files in this skill

本技能中的支持文件

Built-in help (--help)

内置帮助（--help）

Built-in help (
`--help`
)

内置帮助（
`--help`
）