hsb-app

HSB 应用运行器

当用户想要在连接了 HSB 板卡的开发套件上查找、选择并运行 Holoscan Sensor Bridge 示例应用时，使用此技能。

此技能假设开发套件已完成设置（SSH、演示容器已构建、主机已配置、板卡已连接）。如果尚未完成设置，请先指导用户运行 /hsb-setup。

此工作流会在演示容器中运行应用。只有在用户明确调用时才运行。

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

关卡 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 (optional).

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

关卡 2——展示阶段计划并征求确认。 在采取任何行动之前：

如果用户的请求已包含平台、板卡类型和传感器，也请提前说明：

• 你将扫描 examples/，并根据用户的传感器类型和平台筛选应用
• 你不会自动添加 --headless，只有用户明确要求时才会添加
• 如果用户指定了超时时间（例如“60-second timeout”），说明你会将其用作监控程序的超时时间
• 应用会通过 docker run 在演示容器中运行；基于 Python 的示例使用 python3

展示阶段计划：

HSB App — Phase Plan
  Phase 0: Verify board connectivity and demo container readiness
  Phase 1: Discover user setup and select application to run
  Phase 2: Run application with monitoring, failure analysis, and iterative debugging
  Phase 3: Generate session report (with option to save)

然后明确询问：Shall I proceed with Phase 0? [Y/n]——在用户确认之前，不要开始阶段 0。

关卡 3——快速路径检查。 用户在关卡 2 中确认后，先执行此检查，再执行任何阶段 0 命令：

ssh -o BatchMode=yes $REMOTE_SSH_OPTS $SSH_TARGET \
  "grep _SESSION_VERIFIED /tmp/.claude_hsb_app_session/state.sh 2>/dev/null || echo 'no session'"

如果输出包含 _SESSION_VERIFIED=true，则跳过阶段 0 和阶段 1 的设置发现，直接进入应用选择，并告知用户。

此技能必须执行的操作

1. 验证开发套件可通过 SSH 访问、HSB 板卡已连接且响应正常，并确认演示容器可用。读取当前 FPGA 版本和板卡标识。
2. 与用户沟通，了解其具体设置——开发套件上的代码库位置、HSB 软件版本、板卡类型（Lattice 等）以及已连接的传感器（例如，双 IMX274、VB1940）。然后扫描代码库的用户指南和 examples/ 目录，整理出与用户设置兼容的应用列表。展示列表，并让用户选择要运行的应用。
3. 在演示容器中运行所选应用、监控输出；如果应用失败，则分析日志输出并指导用户进行调试，包括建议修改代码或环境，然后重新运行应用。
4. 生成本次会话的摘要报告，说明遇到的问题、应用的修复措施及结果。提供将报告保存到文件的选项。

兼容 Linux/Windows 的包装器变量

重复使用 hsb-setup 和 hsb-flash 技能中的相同环境变量：

• SSH_TARGET，用于远程登录目标（例如 nvidia@agx-thor-host）
• REMOTE_ROOT，用于远程工作目录
• REMOTE_SUDO，用于特权命令
• REMOTE_SSH_OPTS，用于附加的 SSH 选项
• HSB_PLATFORM，可选的平台提示

如果已设置这些变量，请告知用户这些设置，并直接使用，不要再次询问。

阶段 0 之前，打印解析后的远程执行设置。

必须遵循的交互模式

会话中的首次运行（此前未经验证）

如果不存在有效的会话状态，请展示完整的阶段计划：

• 阶段 0：验证板卡连接情况和演示容器就绪状态
• 阶段 1：了解用户设置并选择要运行的应用
• 阶段 2：运行应用并进行监控、故障分析和迭代调试
• 阶段 3：生成会话报告（可选择保存）

然后一次执行一个阶段。

同一会话中的后续运行（快速路径）

当会话状态文件（/tmp/.claude_hsb_app_session/state.sh）存在，并且包含 _SESSION_VERIFIED=true 时，技能会跳过 Phase 0 和 Phase 1 的环境发现，因为连接和硬件已完成验证。此时通知用户，并直接进入应用选择：

Session already verified — skipping connectivity checks.
  SSH target: $SSH_TARGET
  Board: HSB Lattice | FPGA: XXXX
  Platform: AGX Thor | HSB version: X.X.X
  Sensors: Dual IMX274

Proceeding directly to application selection.

然后执行：

• 仅执行 Phase 1 步骤 2–3（扫描示例、展示应用列表、由用户选择应用）
• Phase 2：运行应用
• Phase 3：会话报告

何时从头重新运行 Phase 0

遇到以下情况时，必须重新运行 Phase 0（忽略快速路径）：

1. 新会话：远程主机上不存在会话状态文件，或启动了新的 Claude Code 会话。
2. 表明连接丢失的执行失败：如果 Phase 2 出现表明开发板或开发套件无法访问的症状（ping 失败、SSH 超时、容器启动失败、No such device 错误），请从会话状态中清除 _SESSION_VERIFIED，并在重试前重新运行 Phase 0。
3. 用户明确提出请求：如果用户说“重新验证”“从头开始”“从头运行”，或调用 /hsb-app --full，则从头运行 Phase 0。

完整的确认流程请参见下文的 ## 阶段关卡。

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

• 失败的具体命令
• 可能的根本原因
• 建议采取的安全措施
• 问题是否会阻塞后续流程

阶段详情

完整的分步阶段说明请参见 references/phase-details.md。

执行规则

SSH heredoc 模式

使用与 hsb-setup 和 hsb-flash 相同的持久 SSH 会话模式。每个阶段都通过一个 SSH heredoc 块运行：

ssh -o BatchMode=yes $REMOTE_SSH_OPTS $SSH_TARGET bash -s <<'REMOTE'
set -e

# restore state from previous phase
source /tmp/.claude_hsb_app_session/state.sh 2>/dev/null || true
cd "${_CLAUDE_CWD:-__REMOTE_ROOT__}"

# phase commands
echo "=== Phase N: description ==="
command1
command2

# save state for next phase (preserves _SESSION_VERIFIED if already set)
_PREV_VERIFIED="${_SESSION_VERIFIED:-}"
mkdir -p /tmp/.claude_hsb_app_session
{
  echo "export _CLAUDE_CWD=\"$(pwd)\""
  echo "export PATH=\"$PATH\""
  echo "export REPO_DIR=\"$REPO_DIR\""
  echo "export VERSION=\"$VERSION\""
  echo "export HSB_PLATFORM=\"$HSB_PLATFORM\""
  echo "export BOARD_TYPE=\"$BOARD_TYPE\""
  echo "export SENSORS=\"$SENSORS\""
  echo "export FPGA_VERSION=\"$FPGA_VERSION\""
  echo "export SELECTED_APP=\"$SELECTED_APP\""
  echo "export APP_OPTIONS=\"$APP_OPTIONS\""
  echo "export APP_TIMEOUT=\"$APP_TIMEOUT\""
  [ "$_PREV_VERIFIED" = "true" ] && echo "export _SESSION_VERIFIED=true"
} > /tmp/.claude_hsb_app_session/state.sh
REMOTE

编写 heredoc 时，将 __REMOTE_ROOT__ 替换为 $REMOTE_ROOT 的字面值。

应用的容器使用方式

应用命令在演示容器中运行。使用带命名容器的分离模式。

对于带 --timeout 的应用，使用看门狗模式。对于无限时运行的应用，持续输出日志，并等待用户请求停止。

应用容器清理

每次运行应用后，都要停止并移除容器。清理模式请参见 references/phase-details.md。

会话拆除

Phase 3 完成后（或任何导致工作流停止的故障发生时）：

docker ps --filter "name=hsb_app_" --format '{{.Names}}' | xargs -r docker stop -t 2 2>/dev/null || true
ssh -o BatchMode=yes $REMOTE_SSH_OPTS $SSH_TARGET "rm -rf /tmp/.claude_hsb_app_session"

阶段关卡——阶段之间的用户确认

每个阶段（Phase 0–2）完成后，始终先提示用户确认，再开始下一阶段。

例外：启用 --y（自动批准模式）时，跳过阶段关卡。请参见“自动批准模式（--y）”一节。

Proceed to Phase <N+1> (<phase description>)? [Y/n]

用户响应处理

此技能中的所有提示都要求用户明确输入回复。切勿将空输入或仅按 Enter 视为已作出选择——应重新提示用户。

• “y”、“yes”、“Y”、“ok”、“go”、“continue”、“next” → 继续下一阶段。
• “n”、“no”、“stop”、“abort” → 停止执行。输出：

  App workflow paused after Phase N.
  You can resume by re-invoking the skill.
  

  然后拆除会话。
• 其他任何文本 → 将其视为关于当前阶段的问题或指示。回答后，再次提示用户。
• “retry” → 重新执行当前阶段，再次显示摘要，然后重新提示用户。

例外情况

• Phase 3（会话报告）是最后一个阶段——除非用户想运行另一个应用，否则不要在此阶段后提示。显示报告并询问是否要保存。
• 如果某个阶段失败且无法恢复，则停止并清楚地报告情况。

内置帮助（--help）

如果 $ARGUMENTS 包含 --help 或 -h，则输出以下内容并停止：

HSB Application Runner Skill

USAGE
  /hsb-app [OPTIONS]

OPTIONS
  --help, -h        Show this help message and exit
  --verbose         Show full raw command output for every phase
  --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.
  --timeout N       Set app runtime in seconds (default: no timeout,
                    app runs until user asks to stop)
  --full            Force full verification from Phase 0, even if the
                    session was already verified

ENVIRONMENT VARIABLES (set before invoking the skill)
  SSH_TARGET        Remote login target (e.g. [email protected])
  REMOTE_ROOT       Remote working directory
  REMOTE_SUDO       Privilege escalation: 'sudo', 'sudo -n', or ''
  REMOTE_SSH_OPTS   Additional SSH options
  HSB_PLATFORM      Platform hint
  HSB_REPO_DIR      Repo directory name under REMOTE_ROOT (default: holoscan-sensor-bridge)
                    Example: HSB_REPO_DIR=hololink → repo at $REMOTE_ROOT/hololink

WORKFLOW PHASES
  Phase 0   Verify board connectivity and demo container readiness
            (skipped on repeat runs in the same session)
  Phase 1   Discover user setup, scan examples, select application
            (setup discovery skipped on repeat runs)
  Phase 2   Run application with monitoring and iterative debugging
  Phase 3   Generate and optionally save session report

EXAMPLES
  /hsb-app
  /hsb-app --verbose
  /hsb-app --timeout 60
  /hsb-app --timeout 30 --verbose
  /hsb-app --y
  /hsb-app --y --timeout 120
  /hsb-app --full
  /hsb-app --help

调用示例

• /hsb-app
• /hsb-app --verbose
• /hsb-app --timeout 60
• /hsb-app --timeout 30 --verbose
• /hsb-app --y
• /hsb-app --y --timeout 120
• /hsb-app --full
• /hsb-app --full --verbose
• /hsb-app --help

详细模式（--verbose）

此技能支持 --verbose 标志：

检测标志

检查 $ARGUMENTS（斜杠命令之后的文本）是否包含以下任一标志：--help / -h、--verbose、--y、--timeout N 或 --full（不区分大小写）。在进一步解析参数之前，移除所有标志（及其值）。

出现 --full 时，忽略所有缓存的会话状态，并从头开始运行阶段 0。

详细模式（启用时）

• 显示每条 SSH 命令的完整原始输出
• 内联显示应用的完整输出（所有 stdout/stderr）
• 显示详细的阶段状态块

简洁模式（默认，未启用 --verbose）

• 每个阶段结束后显示项目符号摘要
• 隐藏原始命令输出
• 显示应用输出中的关键行（启动、错误、摘要），但不显示每条帧日志
• 使用 4 行格式显示问题（症状、原因、解决方法、是否阻塞）

自动批准模式（--y）

此技能支持 --y 标志，可跳过所有阶段关卡，从头到尾运行整个工作流，无需在各阶段之间等待用户确认。不建议在常规使用中启用此模式。

确认警告

检测到 --y 时，显示警告并请用户确认：

⚠  WARNING: Auto-approve mode (--y) is enabled.

This is NOT RECOMMENDED. All phase gates will be skipped and the entire
workflow will run without pausing for your confirmation between phases.

You will not be able to review intermediate results, ask questions, or
abort between phases. All output will be saved to a timestamped log file.

NOTE: In auto-approve mode, the app selection in Phase 1 will still
require your input (you must choose which app to run), but the app will
run with default settings automatically. Debug iterations in Phase 2
will be skipped — the app runs once and the result is reported.

Type 'yes' to confirm auto-approve mode, or anything else to cancel:

• 如果用户回复 "yes"（完全匹配，不区分大小写）→ 启用自动批准模式。
• 任何其他回复 → 取消自动批准模式，并以交互方式运行。

启用 --y 时的行为

1. 跳过各阶段之间的阶段关卡。
2. 选择应用仍需用户输入——用户必须选择要运行的应用。
3. 自动使用应用默认设置——跳过“使用默认设置还是自定义”提示，并使用默认选项运行应用。
4. 如果命令行中未指定 --timeout，超时默认为 30 秒（以避免无限期挂起）。
5. 跳过调试迭代——如果应用在阶段 2 失败，会记录失败，但不会进行交互式调试。工作流将直接进入报告阶段。
6. 日志文件：启动时在 $REMOTE_ROOT/ 或当前目录下创建 hsb-app-log-YYYY-MM-DD-HHMMSS.md。
7. 仍会实时显示阶段摘要。
8. 如果失败会阻塞工作流，仍会停止工作流。

与其他标志组合使用

• --y --verbose：自动批准，并显示完整原始输出。
• --y --timeout N：自动批准，并设置固定的应用运行时长。
• 单独使用 --y：自动批准，输出简洁且不设置超时（在自动批准模式下，应用默认运行 30 秒，以避免无限期挂起）。

超时处理（--timeout）

此技能支持 --timeout N 标志，其中 N 是应用运行的秒数。

检测标志

在 $ARGUMENTS 中匹配 --timeout，后接以空格分隔的整数。例如：--timeout 60。

行为

• 已设置时：应用运行恰好 N 秒，然后通过 docker stop 停止。向用户显示在此期间收集的输出。
• 未设置时（交互模式）：应用持续运行，直到用户要求停止。告知用户如何请求停止。
• 未设置时（自动批准模式）：应用默认运行 30 秒，以防止无限期挂起。

验证

• N 必须是正整数
• 最小值：5 秒
• 最大值：3600 秒（1 小时）
• 如果无效，显示错误并请用户提供有效的超时时长