hsb-setup
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseHoloscan 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.gitSSH_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 userGate 3 — Token-budget preflight (Phase 0). Run this before any SSH connection or devkit change. See section for the full procedure. Do not proceed to Phase 1 until the budget check passes.
## Token-budget preflight前置步骤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.gitSSH_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 . The skill walks through each phase interactively, prompting for confirmation before making changes.
/hsb-setup [PLATFORM] [OPTIONS]通过输入 调用本技能。技能会交互式引导完成每个阶段,在进行更改前提示用户确认。
/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 on the devkit and comparing the result to the
cat /sys/class/dmi/id/product_nameenvironment 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 fromHSB_PLATFORM, or ifHSB_PLATFORMis empty, updateHSB_PLATFORMto match the detected platform and alert the user about the change. If the command returns empty or fails andHSB_PLATFORMis already set, keep the existing value.HSB_PLATFORM - Clone or refresh the GitHub repository from the latest branch. By default this is the public
mainrepo, but the user can override it with a custom repo URL via thenvidia-holoscan/holoscan-sensor-bridgeenvironment variable or theHSB_REPOcommand-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.--repo <URL> - 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 . if the connection to the board fails, prompt the user for a possiblity of a different ip address.
192.168.0.2 - 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 - 从最新的 分支克隆或刷新GitHub仓库。默认是公开的
main仓库,但用户可通过nvidia-holoscan/holoscan-sensor-bridge环境变量或HSB_REPO命令行标志覆盖为自定义仓库URL。若仓库是SSH仓库,若未设置SSH密钥则提醒用户,并提供设置SSH密钥的说明。--repo <URL> - 若尚未明确,询问用户想要使用哪个开发套件/平台。
- 在克隆的仓库根目录下,研读并理解 docs/user_guide 中的用户指南,学习如何为每个开发套件和操作系统设置主机环境、演示容器、在容器内外运行应用(如适用)以及烧录FPGA。
- 将平台映射到正确的主机设置和容器构建模式,确保主机按照用户指南说明正确配置,修复并添加任何缺失的配置,或提示用户修复方法。
- 构建演示容器。
- 运行演示容器。
- 验证与板卡 的连接。若与板卡的连接失败,提示用户是否可能使用其他IP地址。
192.168.0.2 - 通过读取寄存器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 environment variable.
HSB_PLATFORM在阶段1(建立SSH连接后或本地运行时),通过读取DMI产品名称并与 环境变量进行比较,验证实际开发套件硬件。
HSB_PLATFORMProduct-name-to-platform mapping
产品名称到平台的映射
The following table maps known values to supported values. Match using case-insensitive substring search — the product name may contain additional text (e.g., "Developer Kit", revision numbers).
/sys/class/dmi/id/product_nameHSB_PLATFORM | Mapped | Notes |
|---|---|---|
| | Still need to ask iGPU vs dGPU if not already known |
| | |
| | |
| |
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.
下表将已知的 值映射到受支持的 值。使用不区分大小写的子字符串搜索匹配——产品名称可能包含额外文本(例如“Developer Kit”、版本号)。
/sys/class/dmi/id/product_nameHSB_PLATFORM | 映射的 | 说明 |
|---|---|---|
| | 若尚未明确,仍需询问是iGPU还是dGPU |
| | |
| | |
| |
若产品名称与任何已知模式不匹配,则视为无法识别,进入步骤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:
-
is non-empty and
DETECTED_PLATFORMis empty → setHSB_PLATFORMtoHSB_PLATFORM. Alert the user:DETECTED_PLATFORMPlatform auto-detected from hardware: <DETECTED_PLATFORM> (product_name: <DETECTED_PRODUCT>). HSB_PLATFORM was not set — updating to "<DETECTED_PLATFORM>". -
is non-empty and differs from
DETECTED_PLATFORM→ overrideHSB_PLATFORMwithHSB_PLATFORM. Alert the user:DETECTED_PLATFORMWARNING: 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>". -
is non-empty and matches
DETECTED_PLATFORM→ no change needed. Confirm:HSB_PLATFORMPlatform verified: <HSB_PLATFORM> matches hardware (product_name: <DETECTED_PRODUCT>). -
is empty (file missing, unreadable, or unrecognized product name) and
DETECTED_PLATFORMis set → keep the existingHSB_PLATFORM. Warn:HSB_PLATFORMCould not auto-detect platform from hardware (product_name: "<DETECTED_PRODUCT>"). Keeping existing HSB_PLATFORM: "<HSB_PLATFORM>". -
Bothand
DETECTED_PLATFORMare empty → fall through to the manual platform question in step 5.HSB_PLATFORM
After reconciliation, persist the updated in the remote session state file so subsequent phases use the correct value.
HSB_PLATFORM在开发套件上运行以下命令(在阶段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均为空 → 进入步骤5的手动平台询问环节。HSB_PLATFORM
协调完成后,将更新后的 持久化到远程会话状态文件中,以便后续阶段使用正确的值。
HSB_PLATFORMLinux/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:
- for the remote login target such as
SSH_TARGETnvidia@agx-thor-host - for the remote working directory where the repo should live
REMOTE_ROOT - for privileged commands. Accept
REMOTE_SUDO,sudo, or empty stringsudo -n - for additional SSH options
REMOTE_SSH_OPTS - as an optional platform hint
HSB_PLATFORM - for a custom GitHub repository URL to clone (e.g.
HSB_REPO). If not set, defaults tohttps://github.com/myorg/my-hsb-fork.githttps://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_TARGETnvidia@agx-thor-host - 用于存放仓库的远程工作目录
REMOTE_ROOT - 用于特权命令。接受
REMOTE_SUDO、sudo或空字符串sudo -n - 用于额外SSH选项
REMOTE_SSH_OPTS - 作为可选的平台提示
HSB_PLATFORM - 用于克隆自定义GitHub仓库URL(例如
HSB_REPO)。若未设置,默认值为https://github.com/myorg/my-hsb-fork.githttps://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 mode (see "Verbosity mode" section):
--verbose- 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 while specifing what is phase N+1 and wait for confirmation before continuing (see "Phase gate" section).
Proceed to Phase <N+1>? [Y/n]
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的内容,等待确认后再继续(见“阶段门控”章节)。
是否进入阶段<N+1>? [Y/n]
若出现失败,不要直接输出原始日志。需总结:
- 失败的确切命令
- 可能的根本原因
- 接下来将尝试的安全修复方法
- 修复是否成功
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 actualrun logs once measured token usage is available:
/hsb-setup- 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 , custom repo handling, SSH key remediation, reboot recovery, or extra troubleshooting is expected.
--verbose - 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:
- I can't verify — stop: The user cannot determine remaining usage. Stop before Phase 1.
- I have < {estimate} available — stop: The user checked their plan/account UI and confirms less than the estimated budget remains. Stop before Phase 1.
- I have ≥ {estimate} available — proceed: The user checked their plan/account UI and confirms at least the estimated budget remains. Proceed to Phase 1.
- 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.
- must not bypass this preflight.
--y
此阶段为强制阶段,必须在建立任何SSH连接、克隆仓库、检查包/配置、构建容器、重启或更改开发套件设置之前执行。
-
估算完整运行的令牌预算,针对整个设置工作流,而非仅下一阶段。以下为保守启发式值,并非实测历史用量。将其视为初始安全预算,一旦有实测令牌用量数据,从实际运行日志中优化这些值:
/hsb-setup- 对于IGX Orin、AGX Orin或DGX Spark的完整设置运行,至少预留280,000令牌。
- 对于AGX Thor,至少预留340,000令牌,因为原生构建和SIPL/FuSa检查会增加更多阶段和故障排查工作。
- 若预期使用 、自定义仓库处理、SSH密钥修复、重启恢复或额外故障排查,额外添加60,000令牌。
--verbose - 若平台未知,使用较大的估算值。
-
检查剩余用量,使用当前订阅计划最佳可用的Claude Code/账户用量来源。优先使用机器可读或产品提供的用量数据。若没有可靠的用量来源,询问用户从Claude Code账户或计划UI中提供当前剩余用量/配额。若因无法自行验证而询问用户,按以下确切顺序呈现选项,确保安全停止选项排在前面:
- 无法验证——停止:用户无法确定剩余用量。在阶段1前停止。
- 可用用量<{估算值}——停止:用户已检查计划/账户UI,确认剩余用量少于估算预算。在阶段1前停止。
- 可用用量≥{估算值}——继续:用户已检查计划/账户UI,确认剩余用量至少为估算预算。进入阶段1。
- 输入其他内容:视为问题或自由格式指令,回答后重新提示相同的有序选项。
不要将继续选项放在第一位。用户必须有意跳过停止选项后才能选择继续。 -
向用户显示检查结果,然后再继续: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 for network and Docker setup?
sudo
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板卡是否已物理连接并通电?
- 您是否同意执行需要权限的网络和Docker设置命令?
sudo
若用户已提供其中任何一项,请勿再次询问。
Available Scripts
可用脚本
| Script | Purpose | Arguments |
|---|---|---|
| Structured shell execution with timestamped logs per phase | |
Use to run phase steps with automatic logging.
run_script(scripts/hsb_phase_runner.sh, <phase_name>, <command>)| 脚本 | 用途 | 参数 |
|---|---|---|
| 结构化shell执行,每个阶段生成带时间戳的日志 | |
使用 运行阶段步骤,自动生成日志。
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 (, Docker access,
git-lfs, network route).xhost - 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.
适用时按以下顺序尝试修复:
- 若失败看起来是暂时性的,重新运行一次失败的命令。
- 修复缺失的先决条件(、Docker访问权限、
git-lfs、网络路由)。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内置帮助(--help
)
--helpIf contains or , do not run the workflow. Instead, print the following help text verbatim and stop:
$ARGUMENTS--help-hHoloscan 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 --helpAfter printing the help text, do not proceed with any phases or ask any questions.
See the section in Built-in help () for invocation examples.
EXAMPLES--helpWhen contains a platform, use it instead of asking again. Strip , , , and from the arguments before parsing the platform name.
$ARGUMENTS--verbose--y--repo <URL>--help若 包含 或 ,请勿运行工作流。相反,逐字打印以下帮助文本并停止:
$ARGUMENTS--help-hHoloscan 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