hsb-test

HSB QA 测试运行器

当用户希望针对 HSB 开发板和开发套件执行 QA 测试计划时，使用此技能。该技能会读取测试文档（本地文件或网页链接），筛选出可在用户特定硬件配置上自动运行的测试，逐项执行并评估通过或失败，最后生成完整的结果报告。

此技能假定开发套件已完成设置（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——展示阶段计划、询问测试文档并获得确认。 采取任何行动之前：

1. 展示阶段计划：

HSB Test — Phase Plan
  Phase 0: Verify devkit SSH, board ping, and demo container availability
  Phase 1: Obtain test document, confirm setup, build executable test plan
  Phase 2: Execute tests, record pass/fail, analyze failures
  Phase 3: Produce test results report (with option to save)
  Phase 4: Clean up test artifacts

2. 如果用户尚未提供测试文档路径或 URL，请停止并询问——在用户提供之前，不得进入阶段 0 或任何其他阶段：Please provide the path or URL to your test document:。如果用户已指定具体测试（例如“仅运行连通性检查”），请说明将运行和跳过哪些阶段，并指出测试将按用户的平台、开发板和传感器配置进行筛选，并分类为可自动化或手动测试。

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

此技能必须执行的操作

1. 验证开发套件可通过 SSH 访问、HSB 开发板已连接且响应正常，并且演示容器可用。读取当前 FPGA 版本和开发板标识。通过已设置的环境变量或询问用户，确认传感器/摄像头类型、HSB 开发套件以及所用的发布仓库。如果尚未准备就绪，请提供调用 /hsb-setup 来准备开发套件的选项。
2. 从用户处获取测试计划文档（文件路径或 URL）。确认用户在阶段 0 中提供的配置详情（仓库位置、HSB 版本、平台、开发板类型、传感器）。检查测试计划和仓库的 examples/ 目录，确定哪些测试可以自动运行。跳过手动测试以及需要额外设备的测试。向用户展示可执行的测试计划并征求批准。
3. 按顺序执行每个测试用例。对于每项测试：运行应用，依据测试计划中的标准评估通过或失败，并记录结果。如果失败，分析日志、提出修复建议，并让用户决定如何继续，然后再运行下一项测试。
4. 生成结构化测试结果报告，其中包含每项测试的通过/失败状态、遇到的问题以及已应用的修复措施。提供保存报告的选项。
5. 清理所有测试产物（容器、临时文件、会话状态）。

兼容 Linux/Windows 的包装器变量

复用其他 HSB 技能中的同一组环境变量：

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

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

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

强制交互模式

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

当不存在有效的会话状态时，显示完整的阶段计划：

• Phase 0：验证开发板连接、演示容器就绪状态和用户设置（发布仓库、平台、传感器/摄像头）
• Phase 1：获取测试计划、确认设置、构建可执行测试列表
• Phase 2：执行测试计划，并逐项评估通过/失败
• Phase 3：生成测试结果报告（可选择保存）
• Phase 4：清理

然后一次执行一个阶段。

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

当会话状态文件（/tmp/.claude_hsb_test_session/state.sh）存在，并且包含 _SESSION_VERIFIED=true 时，该技能会跳过 Phase 0 和 Phase 1 的设置确认，因为连接、硬件、发布仓库、平台和传感器/摄像头均已验证。请改为告知用户并直接进入测试计划收集：

Session already verified — skipping connectivity checks.
  SSH target: $SSH_TARGET
  Release repo: /home/work/holoscan-sensor-bridge (HSB vX.X.X)
  Platform: AGX Thor
  Board: HSB Lattice | FPGA: XXXX
  Sensors: Dual IMX274

Proceeding directly to test plan intake.

然后执行：

• Phase 1（收集测试计划并构建测试列表——跳过设置确认）
• Phase 2：执行测试计划
• Phase 3：测试结果报告
• Phase 4：清理

何时从头重新运行 Phase 0

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

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

完整的确认流程请参阅下文的 ## Phase gate。

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

• 失败的确切命令
• 可能的根本原因
• 建议采取的安全措施
• 该问题是否会阻塞后续操作

阶段详情

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

执行规则

SSH heredoc 模式

使用与其他 HSB 技能相同的持久 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_test_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_test_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 TEST_PLAN_SOURCE=\"$TEST_PLAN_SOURCE\""
  [ "$_PREV_VERIFIED" = "true" ] && echo "export _SESSION_VERIFIED=true"
} > /tmp/.claude_hsb_test_session/state.sh
REMOTE

组合 heredoc 时，将 __REMOTE_ROOT__ 替换为 $REMOTE_ROOT 的字面值。

测试的容器用法

测试命令在演示容器中运行。请使用带有命名容器的分离运行模式，并使用 watchdog 强制执行超时。

每项测试的默认超时时间：120 秒（2 分钟）。可通过以下方式覆盖：

• 在技能调用中使用 --timeout N（应用于所有测试）
• 在测试计划中为单项测试指定超时时间

每个测试容器运行后的清理

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

会话拆除

由 Phase 4 处理。如果工作流在 Phase 4 之前中止：

docker ps --filter "name=hsb_test_" --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_test_session"

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

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

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

例外：Phase 4（清理）在 Phase 3 之后自动运行，无需关卡。

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

用户响应处理

此技能中的所有提示都要求用户明确输入。绝不要将空白输入或仅按 Enter 视为已选择；应重新提示用户。

• "y"、"yes"、"Y"、"ok"、"go"、"continue"、"next" → 进入下一阶段。
• "n"、"no"、"stop"、"abort" → 停止执行。打印：

  QA testing paused after Phase N.
  You can resume by re-invoking the skill.
  

  然后运行会话清理。
• 任何其他文本 → 将其视为关于当前阶段的问题或指令。回答后重新提示。
• "retry" → 重新执行当前阶段，再次显示摘要，然后重新提示。

例外情况

• 阶段 4（清理）是最后一个阶段——阶段 3 完成后，或用户拒绝运行其他测试计划后，将自动运行。
• 如果某个阶段失败且无法恢复，则停止并明确报告，然后运行清理。

内置帮助（--help）

如果 $ARGUMENTS 包含 --help 或 -h，打印以下内容并停止：

HSB QA Test Runner Skill

USAGE
  /hsb-test [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 and skip interactive
                    debugging on test failures. Not recommended — a
                    confirmation warning is shown before proceeding.
                    All output is saved to a timestamped log file.
  --timeout N       Set per-test runtime in seconds (default: 120s).
                    Tests stop after N seconds or when pass/fail can
                    be determined, whichever comes first.
  --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

WORKFLOW PHASES
  Phase 0   Verify board connectivity, demo container readiness,
            and user setup (release repo, platform, sensor/camera)
            (skipped on repeat runs in the same session)
  Phase 1   Obtain test plan, confirm setup, build executable test list
            (setup confirmation skipped on repeat runs)
  Phase 2   Execute test plan with per-test pass/fail evaluation
  Phase 3   Generate and optionally save test results report
  Phase 4   Cleanup (automatic)

EXAMPLES
  /hsb-test
  /hsb-test --verbose
  /hsb-test --timeout 60
  /hsb-test --y
  /hsb-test --y --timeout 60
  /hsb-test --full
  /hsb-test --help

调用示例

• /hsb-test
• /hsb-test --verbose
• /hsb-test --timeout 60
• /hsb-test --timeout 60 --verbose
• /hsb-test --y
• /hsb-test --y --timeout 60
• /hsb-test --full
• /hsb-test --full --verbose
• /hsb-test --help

详细模式（--verbose）

此技能支持 --verbose 标志：

检测标志

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

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

详细模式（启用时）

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

简洁模式（默认，不含 --verbose）

• 每个阶段结束后显示项目符号摘要
• 隐藏原始命令输出
• 显示关键测试输出行（启动、错误、通过/失败指示），但不显示每一行
• 按 4 行格式显示问题（症状、原因、解决方案、阻塞情况）

自动批准模式（--y）

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

确认警告

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

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

This is NOT RECOMMENDED for QA testing. All phase gates will be skipped
and the entire test plan will execute without pausing for your
confirmation between phases or tests.

You will not be able to review intermediate results, intervene on
failures, or abort between tests. All output will be saved to a
timestamped log file.

NOTE: In auto-approve mode, you must still provide the test plan in
Phase 1. Failed tests are logged but not interactively debugged —
testing continues to the next test automatically.

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

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

启用 --y 时的行为

1. 跳过阶段关卡，直接进入后续阶段。
2. 跳过测试计划审批——自动执行生成的测试计划。
3. 测试失败时不暂停——记录失败，并自动继续下一个测试用例。
4. 跳过测试间提示——测试连续运行，无需确认。
5. 应用默认超时——每项测试为 120 秒；如果指定了 --timeout N，则使用该值。
6. 日志文件：启动时在 $REMOTE_ROOT/ 或当前目录下创建，文件名为 hsb-test-log-YYYY-MM-DD-HHMMSS.md。
7. 仍会实时显示阶段摘要。
8. 阻塞性连接故障仍会停止工作流，并触发重新验证。

与其他标志组合使用

• --y --verbose：自动批准并显示完整原始输出。
• --y --timeout N：自动批准，并为每项测试设置自定义超时时间。
• --y --full：自动批准，并从阶段 0 开始强制执行完整验证。

超时处理（--timeout）

此技能支持 --timeout N 标志，其中 N 是每项测试的运行秒数。

行为

• 设置时：每项测试最多运行 N 秒，然后停止。根据此时间段内收集到的输出判定通过或失败。
• 未设置时：默认情况下，每项测试最多运行 120 秒（2 分钟），或在可以根据输出判定通过或失败时停止，以先发生者为准。
• 单项测试覆盖：如果测试计划为某项测试指定了超时时间，该值优先于默认值和 --timeout 标志。

验证

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