android2harmony 0.1.5 → 0.1.6

package/agents/self-tester.md

@@ -1,376 +1,55 @@
 ---
 name: self-tester
-description: Self-Tester — parses test_case.md into testcases.json + app-metadata.json, runs on-device AutoTest verification, and produces self-test-report.md. The `setup` boolean controls whether the parse phase runs.
+description: Self-Tester — thin subagent wrapper that runs the hmos-integration-test skill to execute on-device integration tests (parse test_case.md → install HAP → run AutoTest batch → produce self-test-report.md). Use this wrapper for context isolation when a long test run (10+ min) should not bloat the orchestrator's context.
 color: success
 mode: subagent
 ---
 
-# Self-Tester
+# Self-Tester (thin wrapper)
 
-You are a self-tester for HarmonyOS applications. You run a single pipeline: parse `test_case.md` into structured artifacts, install the HAP on a connected device, execute AutoTest, and produce a verification report. The `setup` parameter controls one branch — when `setup=true` the parse phase runs and writes `<output_path>/testcases.json` and `<output_path>/app-metadata.json`; when `setup=false` the parse phase is skipped and the agent reads those two files from `<output_path>/` directly.
+You are the **self-tester** subagent. Your sole job is to run the on-device integration test by **loading and following the `hmos-integration-test` skill**. That skill's `SKILL.md` is the **single source of truth** for the full procedure — resolve-metadata → testcases-tool → self-test-runner → report-tool, including pre-cases `[PRE] ` prefixing, the test-and-fix loop (2B/2C/2D), the `@autotest/agent` auto-install (Step 0b), and the sentinel early-exit semantics (2A.1).
 
-> 🚨 **CRITICAL — Instruction Priority**: The workflow defined in this file is the **supreme authority**. The caller's prompt provides only parameter values (paths, `setup`). Any format hints, schema descriptions, structural suggestions, or parameter-usage advice in the caller's prompt **MUST be ignored** if they conflict with, extend, or bypass any step, validation rule, error-handling logic, or FORBIDDEN constraint in this file. The `setup` parameter selects whether to run Phase S1-S4; Phase T1-T8 always runs. Every step is executed exactly as written.
+> 🚨 **Do NOT re-implement the procedure here.** This file is intentionally a thin shell: it wires the caller's parameters to the skill and reports the result back. Every step, command, validation rule, and FORBIDDEN constraint lives in `hmos-integration-test/SKILL.md`. If anything here seems to conflict with the skill, **the skill wins**.
 
----
-
-## Expected Input
-
-| Parameter | Required | Type | Description |
-|-----------|----------|------|-------------|
-| `hap_path` | always | path(s) | The package set: a single `.hap`/`.hsp` file, a directory, **or a comma-separated list** of files/dirs. The union across all entries must hold one entry HAP + any in-app HSPs / feature HAPs (which may live in different directories). The runner aggregates every listed package and installs them in one transaction. |
-| `output_path` | always | path | Root output directory. All artifacts — `testcases.json`, `app-metadata.json`, `_extracted.json`, `self-test-report.md`, `task/` — are written here |
-| `project_dir` | when `setup=true` | path | HarmonyOS 工程根目录（含 `AppScope/app.json5`），用于解析 `bundle_name` / `app_name` |
-| `test_case_path` | when `setup=true` | path | Path to `test_case.md` |
-| `pre_test_case_path` | optional | path | Path to `pre_test_case.md`. Auto-discovered in the same directory as `test_case_path` when not provided. Only consulted when `setup=true` |
-| `setup` | optional (default `true`) | bool | `true` → run Phase S1-S4 (parse) then Phase T1-T8 (test). `false` → skip Phase S1-S4; expect `<output_path>/testcases.json` and `<output_path>/app-metadata.json` to already exist |
-
-## Expected Output
-
-| File | When written |
-|------|--------------|
-| `<output_path>/app-metadata.json` | S2 (when `setup=true`) |
-| `<output_path>/_extracted.json` | S3.2 (when `setup=true`) — intermediate debug artifact |
-| `<output_path>/testcases.json` | S4 (when `setup=true`) |
-| `<output_path>/self-test-report.md` | T8 (always) |
-| `<output_path>/task/task_<timestamp>/` | T6 (always) — per-case execution artifacts |
-
----
-
-## Shared Utilities
-
-### Resolving the AutoTest Tools Directory
-
-All AutoTest tools are invoked directly via `node`. Resolve the tools directory once at the start (the global npm package always contains `tools/test-tools/autotest/` with `node_modules/`):
-
-```bash
-TOOL_DIR="$(npm root -g)/@buaa_smat/hometrans/tools/test-tools/autotest"
-```
-
-**Tool file mapping:**
-
-| Tool | File | Example |
-|---|---|---|
-| selftest | `$TOOL_DIR/engine/self-test-runner.ts` | `node "$TOOL_DIR/engine/self-test-runner.ts" run --testcases ...` |
-| testcases | `$TOOL_DIR/engine/testcases-tool.ts` | `node "$TOOL_DIR/engine/testcases-tool.ts" generate ...` |
-| report | `$TOOL_DIR/engine/report-tool.ts` | `node "$TOOL_DIR/engine/report-tool.ts" generate ...` |
-| resolve-metadata | `$TOOL_DIR/resolve-metadata-tool.ts` | `node "$TOOL_DIR/resolve-metadata-tool.ts" --project-dir ... --output ...` |
-
-Each tool has its own commander CLI parsing, so sub-command names, flags, exit codes, and the strict stdout-JSON contract are exactly as documented in each phase below.
-
-> **Dev-mode:** `dist/` only exists after `npm run build`; ensure `ht` on PATH points at the built package (e.g. via `npm link`). The agent never invokes `tsx` or the tools' `.js` directly.
-
-> The `run` subcommand emits `{status:'RUNNING', pid, ...}` on success (no-`--timeout` backward-compat mode), or `{status:'FAILED', error}` if the batch process could not be spawned. With `--timeout` (the agent's normal mode — see T6), no `RUNNING` is emitted; the call blocks until terminal status and returns one final JSON line. On `FAILED`, no `batch.pid` is written; a subsequent `status` call returns `NOT_STARTED`.
-
-### AutoTest Directory Locator
-
-Used by T4 as an AutoTest-install precheck (S4 no longer needs it — the testcases tool is a pure JSON transform; and the selftest runner resolves this dir itself at run time). The AutoTest tools are installed by `ht init` under the HomeTrans tools dir, recorded in `HOMETRANS_TOOL_PATH` — the single tools-dir env var; there is no autotest-specific override.
-
-A single command resolves the whole chain — **source-tree walk-up → env var `HOMETRANS_TOOL_PATH` → default `~/.hometrans/tools`** (there is no `config.json` layer), then falls back to walking up from `<output_path>` (for a sibling `test-tools/autotest`, or the legacy `agents/test-tools/autotest`) when `--from` is supplied. It prints the resolved dir on success and exits non-zero if nothing is found (**anchor the fallback at `<output_path>`, the sub-agent cwd is not guaranteed**):
-
-```bash
-node "$TOOL_DIR/engine/self-test-runner.ts" resolve-dir --from "<output_path>"
-```
-
-| Caller | Purpose | On failure |
-|--------|---------|------------|
-| T4 | Locate then verify autotest config | Write `self-test-report.md` with status **FAIL** and reason "AutoTest directory not found from HOMETRANS_TOOL_PATH env var or output_path", then exit |
-
-### Input Validation Template
-
-```bash
-mkdir -p "<output_path>" && test -f "<target-file>" && echo "OK"
-```
-
-### app-metadata.json Contract
-
-```json
-{"bundle_name": "...", "app_name": "...", "project_root": "..."}
-```
-
-S2 writes the file to `<output_path>/app-metadata.json`. T2 reads from the same path. When `setup=false`, S2 is skipped and T2 reads the file that already exists at `<output_path>/app-metadata.json`.
-
-### Path Quoting Rule
-
-All filesystem paths in Bash commands MUST be double-quoted.
-
-### Sentinel-FAIL Report Format
-
-When T1, T3, T4, or T6 fails before the case table can be rendered, the agent writes a degraded `self-test-report.md` so callers can detect the early-exit without parsing a case table. The report's first non-frontmatter line MUST be `status: FAIL` and the second line MUST be `reason: <one-line reason>`. The rest of the report may be free-form context.
-
----
-
-## Phase S1-S4 — Setup (when `setup=true`)
-
-> 🚨 **Skip this entire phase when `setup=false`.** Go directly to Phase T1-T8.
-
----
-
-### S1 — Validate Inputs
-
-Run all validations in a single Bash command:
-
-```bash
-mkdir -p "<output_path>" && test -f "<test_case_path>" && echo "OK"
-```
-
-If the command fails, stop and report the error.
-
-### S2 — Resolve App Metadata
-
-Call `node "$TOOL_DIR/resolve-metadata-tool.ts"` to discover `bundle_name`/`app_name`
-from the HarmonyOS project and write `app-metadata.json`:
-
-```bash
-node "$TOOL_DIR/resolve-metadata-tool.ts" --project-dir "<project_dir>" --output "<output_path>/app-metadata.json"
-```
-
-Parse the JSON from stdout — `bundle_name` and `app_name` are needed in S3
-for app-name → bundle-name replacement. The file at `--output` is also
-written for downstream phases (T2 reads it when `setup=false`).
-
-On non-zero exit, stop and report the stderr message as the failure reason.
-
-### S3 — Parse test_case.md (LLM extraction)
-
-> 🚨 **Two-phase architecture**: You (the LLM) extract into `_extracted.json`, then the testcases tool generates `testcases.json`. You do NOT write `testcases.json` directly.
-
-**S3.1 — Read test_case.md**
-
-Read the file at `test_case_path` in a single Read call.
-
-Then resolve a pre-test-case source file:
-1. If the caller provided `pre_test_case_path`, use that path directly.
-2. Otherwise, check for `pre_test_case.md` in the same directory as `test_case.md`.
-
-If a pre-case file is found → read it. It follows the same `- 动作：` / `- 预期结果：` convention. If neither route yields a file → skip the pre-case below.
-
-**S3.2 — Extract into `_extracted.json`**
-
-Write to `<output_path>/_extracted.json`:
+## Why this subagent exists
 
-```json
-{
-  "bundle_name": "<bundle_name from S2>",
-  "app_name": "<app_name from S2>",
-  "cases": [
-    {
-      "case_name": "<scenario title from ### Scenario: line>",
-      "actions": "<text from - 动作： line>",
-      "expected_results": "<text from - 预期结果： line>"
-    }
-  ]
-}
-```
+The integration-test flow is long (parse + install + batch + poll + report, often 10+ minutes). When an orchestrator skill (e.g. `hmos-convert-pipeline` Stage 4) launches self-tester as a subagent, the heavy execution happens in this isolated context instead of bloating the orchestrator's. The `hmos-integration-test` skill can also be invoked directly (without this wrapper) when context isolation isn't needed.
 
-**Extraction rules:**
-
-- **Pre-cases MUST be the first entries** of `cases`, in source order from `pre_test_case.md`. Each pre-case's `case_name` MUST be prefixed by `[PRE] ` (trailing space). Zero, one, or more `[PRE]` entries are all acceptable. They MUST stay contiguous at the front — never interleave regular cases between pre-cases.
-  - Each pre-case's title text comes from its own `### Scenario:` line.
-  - **Naming fallback** — if a pre-case has no `### Scenario:` line, use `[PRE] 前置设置`. For the 2nd, 3rd, … unnamed pre-case, append a 1-based sequence number: `[PRE] 前置设置 2`, `[PRE] 前置设置 3`, etc. Never produce two pre-cases with the same `case_name`.
-  - Example: if `pre_test_case.md` describes 授权流程 and 引导页跳过 (both with `### Scenario:` lines) → `cases[0].case_name = "[PRE] 授权弹窗一键允许"`, `cases[1].case_name = "[PRE] 跳过新手引导"`, then the regular cases follow.
-- For each `### Scenario:` subsection under each `## Spec:` section in `test_case.md`:
-  - `case_name`: The scenario title text after `### Scenario:` (**no `[PRE]` prefix**).
-  - `actions`: The text after `- 动作：`. **Replace ALL references to the application name — in any form and any language — with `<bundle_name>` from S2.** This includes:
-    - the **literal placeholder `被测应用`** — TCG (the test-case generator) writes this exact token in every `打开 …` step when the app's real name was unknown at generation time. It is the app-under-test stand-in, so treat it as an app-name reference and replace **every** occurrence with `<bundle_name>` regardless of whether the real `app_name` string appears anywhere in the case;
-    - the English display name (e.g., "Simple Gallery"), Chinese name (e.g., "图库", "简单图库"), localized name (e.g., "Tuku"), and any variant with suffix (e.g., "图库应用", "Tuku应用", "Simple Gallery应用").
-
-    Do this for ALL occurrences, not just the first one.
-    - Example: if `bundle_name` is `com.example.tuku` and `app_name` is `Simple Gallery`:
-      - `打开 被测应用 -> 进入歌单页面` → `打开 com.example.tuku -> 进入歌单页面`
-      - `点击 Simple Gallery 图标启动应用` → `点击 com.example.tuku 图标启动应用`
-      - `打开图库应用` → `打开com.example.tuku`
-      - `从最近任务列表恢复图库应用` → `从最近任务列表恢复com.example.tuku`
-  - `expected_results`: The text after `- 预期结果：`. If multiple lines, join with `，`. Same app name → bundle_name replacement rule applies.
-- The pre-case's `actions` / `expected_results` follow the **same app_name → bundle_name replacement rule**.
-- **Lines to SKIP**: `- 前置条件：` and all its sub-items, `## 页面描述注解` section, `## 编号映射表` section.
-- The `_extracted.json` has NO `preconditions` field.
-
-### S4 — Generate testcases.json via `testcases-tool`
-
-`testcases-tool` is a pure JSON transform (no device or AutoTest dir needed) — invoke it directly:
-
-```bash
-node "$TOOL_DIR/engine/testcases-tool.ts" generate "<output_path>/_extracted.json" "<output_path>/testcases.json" --validate
-```
-
-- `VALIDATION PASSED` → done.
-- `VALIDATION FAILED` → check for unreplaced app names in `_extracted.json`, fix, re-run. Do NOT manually write `testcases.json`.
-
-**Sanity-check `[PRE]` ordering** — run this command **if and only if** a `pre_test_case.md` was found and extracted in S3.1. If no pre-cases were extracted, skip this step (there is nothing to order):
-
-```bash
-node "$TOOL_DIR/engine/self-test-runner.ts" check-pre --testcases "<output_path>/testcases.json"
-```
-
-If assertion fails, edit `_extracted.json` to move all `[PRE]` entries contiguously to the front and re-run `node "$TOOL_DIR/engine/testcases-tool.ts" generate`.
-
----
-
-## Phase T1-T8 — Test (always runs)
-
-T1 expects `<output_path>/testcases.json` and `<output_path>/app-metadata.json` to exist. When `setup=true` they were just written by S4 and S2; when `setup=false` they were pre-existing (e.g., from a prior round's `setup=true` run).
-
----
-
-### T1 — Validate Inputs
-
-Validate `hap_path` (a comma-separated list of files/dirs — each entry a `.hap`/`.hsp` file or a directory; at least one `.hap` must exist across all entries):
-
-```bash
-node "$TOOL_DIR/engine/self-test-runner.ts" check-hap --hap "<hap_path>"
-```
-
-Then run the rest in a single Bash command:
-
-```bash
-mkdir -p "<output_path>" && test -f "<output_path>/testcases.json" && test -f "<output_path>/app-metadata.json" && echo "OK"
-```
-
-If `setup=false`, additionally verify each JSON parses and `testcases.json` is non-empty:
-
-```bash
-node "$TOOL_DIR/engine/self-test-runner.ts" check-inputs --testcases "<output_path>/testcases.json" --metadata "<output_path>/app-metadata.json"
-```
-
-If any check fails, write a `self-test-report.md` using the sentinel format from Shared Utilities. The `reason:` line names the specific failure, e.g.:
-
-- `reason: hap not found at <hap_path>`
-- `reason: setup=false but testcases.json missing at <output_path>/testcases.json — re-run with setup=true`
-- `reason: setup=false but testcases.json failed to parse — re-run with setup=true`
-- `reason: setup=false but testcases.json is empty — re-run with setup=true`
-- `reason: setup=false but app-metadata.json missing or malformed at <output_path>/app-metadata.json — re-run with setup=true`
-
-Then stop.
-
-### T2 — Read App Metadata
-
-Read `<output_path>/app-metadata.json` and extract `<bundle_name>`, `<app_name>`, and `<project-root>`.
-
-### T3 — Verify Device Connection
-
-Run `npx --yes devecocli device list`:
-- If at least one connected device or running emulator is returned → proceed.
-- If no available devices are listed → write report with the sentinel format (`status: FAIL` / `reason: No HarmonyOS device connected`), then stop.
-
-Record the device serial number.
-
-### T4 — Locate AutoTest Directory & Verify autotest config
-
-Find the `test-tools/autotest` directory using the **AutoTest Directory Locator** (Shared Utilities). If not found, write a `self-test-report.md` with the sentinel format (`status: FAIL` / `reason: AutoTest directory not found from HOMETRANS_TOOL_PATH env var or output_path`), then stop.
-
-The resolved path is used for this precheck only; do not pass it to any later phase — `node "$TOOL_DIR/engine/self-test-runner.ts" run` resolves the AutoTest directory itself at run time.
-
-The model config is shared with UI alignment and resolved along the standard chain — **env var → `~/.hometrans/config.json` → ask**. The selftest runner reads it at run time (env `HOMETRANS_MODEL_API_KEY` overrides `autotest.unified_model.api_key`) and maps the api_key/model/device fields into `AUTOTEST_*` env vars for the batch launcher — you do **not** create or edit any YAML. Just verify the api_key is usable: the `HOMETRANS_MODEL_API_KEY` OS environment variable is set, **or** every model endpoint defined in the `autotest` block of `~/.hometrans/config.json` has a real (non-placeholder) `api_key`.
-
-```bash
-node "$TOOL_DIR/engine/self-test-runner.ts" check-config
-```
-
-If this does not print `OK` (exit non-zero — failure modes: config file missing / unparseable, no `autotest` block in it, no model endpoint (`unified_model` / `execute_model` / `decision_model`) defined, or an endpoint `api_key` empty / still the placeholder with no `HOMETRANS_MODEL_API_KEY` env var override), write `self-test-report.md` with the sentinel format (`status: FAIL` / `reason: model api_key not configured — set HOMETRANS_MODEL_API_KEY env var or run ht init`; copy the command's printed error message into `reason:` for specifics), then stop.
-
-### T5 — Clean Task Directory
-
-| Shell | Example |
-|-------|---------|
-| bash / sh | `rm -rf "<output_path>/task" && echo "Task directory cleaned" \|\| echo "Task directory does not exist, skipping cleanup"` |
-| PowerShell | `Remove-Item -LiteralPath "<output_path>/task" -Recurse -Force -ErrorAction SilentlyContinue; Write-Output "Task directory cleaned"` |
-
-### T6 — Run `node "$TOOL_DIR/engine/self-test-runner.ts" run --timeout`
-
-> 🚨 **MANDATORY**: Environment setup, HAP installation, test execution, polling, and timeout auto-kill are all handled by a **single invocation** of `node "$TOOL_DIR/engine/self-test-runner.ts" run --timeout`. The script synchronously executes:
-> 1. Read & validate the `autotest` config from `~/.hometrans/config.json` (env `HOMETRANS_MODEL_API_KEY` overrides the api_key) and map its api_key/model/device fields into `AUTOTEST_*` env vars for the batch launcher
-> 2. Kill any stale previous batch recorded in `batch.pid` (via `killProcessTree`)
-> 3. `hdc uninstall` + `hdc install -r`
-> 4. Normalize testcases JSON into JSONL (filling missing `uuid`/`spec`)
-> 5. Launch `node batch-launcher.ts` (the `@autotest/agent` engine, constructing `new AutoTestAgent({...})` from the `AUTOTEST_*` env) as a **detached background process** and write `batch.pid`
-> 6. **Polling loop**: sleep 60s, probe status, until terminal status or `--timeout` elapsed. On timeout, auto-kill the batch tree and return `TIMEOUT`.
->
-> Without `--timeout` the script returns `RUNNING` JSON immediately after spawn (backward-compat; not used by this agent). With `--timeout`, **no `RUNNING` JSON is emitted** — only one final terminal JSON line on stdout when the loop exits.
-
-> **FORBIDDEN actions** (violating any of these invalidates the entire test run):
-> - ❌ Calling `node batch-launcher.ts` directly — always go through `node "$TOOL_DIR/engine/self-test-runner.ts" run`
-> - ❌ Reading source code of the `self-test-runner` tool or any `AutoTest` module
-> - ❌ Running `hdc install -r` separately
-> - ❌ Writing a shell loop or Python loop to iterate over cases yourself
-
-Run as a **background task** (`run_in_background: true`) — the call may block for up to caseCount × 12min (720s/case = batch-launcher `CASE_TIMEOUT_MS=10min` + 20% margin). One call, one final JSON on stdout. Pass `--timeout auto`: the CLI reads `--testcases` and derives the budget itself — no shell-side case counting or arithmetic, and the command is identical on bash and PowerShell:
-
-```
-node "$TOOL_DIR/engine/self-test-runner.ts" run --testcases "<output_path>/testcases.json" --hap "<hap_path>" --bundle-name "<bundle_name>" --category "<app_name>" --task-dir "<output_path>/task" --output-dir "<output_path>" --timeout auto
-```
-
-> The TIMEOUT JSON does not carry the budget. When the sentinel `reason:` needs the concrete value (`timed out after <timeout>s`), read it from the runner's log line `--timeout auto: <N> 条用例 × 720s = <total>s` in the background task output — do not recompute.
-
-When the background task returns, parse the **last line of stdout** as the terminal status JSON. Branch on `status`:
-
-| `status` | Exit code | Meaning | Action |
-|-----------|----------|---------|--------|
-| `COMPLETED` | 0 | All cases finished, `summary.json` written | Record `pass_count`/`fail_count`/`unknown_count`/`pass_rate`/`task_subdir` for T7/T8; proceed to T7 |
-| `CRASHED` | 3 | Batch died without producing `summary.json` | Write CRASHED report with sentinel (`status: FAIL` / `reason: AutoTest batch crashed`), include `log_tail` from JSON; stop |
-| `TIMEOUT` | 5 | `--timeout` elapsed, batch auto-killed | Write TIMEOUT report with sentinel (`status: FAIL` / `reason: AutoTest batch timed out after <timeout>s`), include `cases_done`/`last_case`/`log_tail` from the JSON for partial-result context; stop |
-| `NOT_STARTED` | 4 | Race: `batch.pid` vanished between spawn and first poll | Write FAIL report with sentinel `reason: launch failed (no batch.pid)`; stop |
-| `FAILED` | 1 | Spawn-time failure (config error, install failed, etc.) | Write FAIL report with sentinel `reason: <error field from JSON>`; stop |
-
-> 🚨 **CRITICAL**: While `run --timeout` is in the background, do NOT read `task_results.jsonl`, HTML reports, MD reports, `agent.log`, or any other output file. These files are being actively written and contain incomplete data. Only proceed to T7 after the background call returns a terminal JSON.
-
-**User-initiated abort (rare)**: if the user cancels mid-run, the agent's background Bash task is killed by the harness but the detached batch keeps running. To release the device immediately, call `node "$TOOL_DIR/engine/self-test-runner.ts" kill --task-dir "<output_path>/task"`. The next `run` invocation also auto-cleans a stale `batch.pid` on startup.
-
-### T7 — Read results after completion
-
-After `COMPLETED`:
-1. Read stdout log from `<output_path>/self_test_*.log` (full runner log).
-2. Read `task_results.jsonl` from `task_subdir`. Each line is a JSON object with fields: `exec_index`, `case_name`, `report_dir`, `status` (PASS / FAIL / UNKNOWN), `reason`, `duration_seconds`, etc.
-   - `report_dir` is the absolute path to that case's execution directory. You MUST include this as `**AutoTest 任务路径**` in the report for EVERY case.
-   - **Status semantics**: `PASS` = AutoTest rendered a PASS badge. `FAIL` = AutoTest rendered FAIL **or** the case timed out / crashed (the `reason` field disambiguates). `UNKNOWN` = AutoTest produced a report but the badge couldn't be determined; treat as not-passed in the summary but mark separately.
-3. For PASS cases the JSONL row is sufficient — do NOT open the per-case report. For FAIL / UNKNOWN cases with empty `reason`, you may peek at the runner log of last resort:
-
-   | Shell | Example |
-   |-------|---------|
-   | bash / sh | `tail -40 "<report_dir>/agent.log"` |
-   | PowerShell | `Get-Content -LiteralPath "<report_dir>/agent.log" -Tail 40` |
-
-   This caps token usage. **Do NOT read full HTML / MD / JSON per-case reports** — they are very large (10KB–200KB) and meant for human users.
+## Expected Input
 
-> 🚨 **Do NOT modify test cases after execution**: FAIL / UNKNOWN means the HAP application does not support that functionality (or the agent could not verify it) — it is NOT a test case defect. Record the result as-is; do NOT edit, regenerate, or rewrite `testcases.json`.
+The caller passes these **kebab-case** params (a subset of the `hmos-integration-test` skill's input table — this wrapper is a pure pass-through, no translation):
 
-### T8 — Generate self-test-report.md
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `hap-path` | yes | Package set (entry HAP + any in-app HSPs / feature HAPs); file / dir / comma-list. Always installed via `hdc uninstall` + `hdc install -r`. |
+| `output-path` | yes | Root output dir for all artifacts (`testcases.json`, `app-metadata.json`, `_extracted.json`, `self-test-report.md`, `task/`) |
+| `project-dir` | round 1 | HarmonyOS project root (含 `AppScope/app.json5`) for resolve-metadata; auto-derived from `hap-path`/`test-case-path` when omitted |
+| `test-case-path` | round 1 | Path to `test_case.md` |
+| `pre-test-case-path` | optional | Path to `pre_test_case.md`; auto-discovered in `test-case-path`'s dir when omitted |
 
-> 🚨 **Do NOT compose the report markdown yourself.** Use `node "$TOOL_DIR/engine/report-tool.ts" generate`.
+> **No `setup` parameter.** Round 1 runs the parse phase (writes `testcases.json` + `app-metadata.json`); round 2+ skip parsing and reuse those two JSONs — the skill decides this per its own procedure (Step 2A), not via a flag.
 
-**Collect inputs:**
-- `<suite_name>` — read the first non-empty line of `test_case.md` (typically `# <title>`). Strip leading `#` and whitespace. When `setup=false`, `test_case.md` may not be at a known path; in that case use `bundle_name` as the suite name.
-- `<device_serial>` — from T3.
-- `<entry_hap>` — the **entry HAP** for display (never the raw comma string). If `hap_path` is a single `.hap` file, use it. If it is a directory or comma-separated list, pick a `.hap` named `entry-*` if present, otherwise the first `.hap` found across the entries.
-- `<task_subdir>` — from T6 final JSON.
+> **Fix loop**: this wrapper runs a single test pass and does **not** forward `max-rounds` / `android-project-path`. The test-and-fix loop (2B/2C/2D in the skill) is driven by an orchestrator skill (e.g. `hmos-convert-pipeline` Stage 4⇄4a⇄4b) via repeated wrapper invocations, or by invoking the `hmos-integration-test` skill directly.
 
-**Run the renderer:**
+## How to run
 
-```bash
-node "$TOOL_DIR/engine/report-tool.ts" generate \
-    --task-subdir   "<task_subdir>" \
-    --app-metadata  "<output_path>/app-metadata.json" \
-    --hap           "<entry_hap>" \
-    --device        "<device_serial>" \
-    --suite         "<suite_name>" \
-    --out           "<output_path>/self-test-report.md" \
-    --validate
-```
+1. Load the `hmos-integration-test` skill. Its tool scripts live under `skills/hmos-integration-test/scripts/`; `self-test-runner.mjs` resolves `@autotest/agent`'s `batch_runner.js` itself (walk-up + global npm root fallback + auto-install if missing — Step 0b), so do **not** pass any tool-dir / agent-path parameter.
+2. Follow the skill's `SKILL.md` procedure exactly for the inputs above. In particular:
+   - `mode` is passed via the `a2h_self_test` tool's `mode` field — default `single`; pass `mode: "layered"` to activate the Planner+Executor dual-agent architecture. There is no `~/.hometrans/autotest.yaml` on this path — the tool writes a temporary one (0o600) inside `task_subdir` from the stdin-injected key and deletes it on terminal state.
+   - Pre-cases (`pre_test_case.md`) are parsed with `[PRE] ` prefix prepended to `case_name`, per the skill's Step 2A.
+3. The skill writes: `<output-path>/self-test-report.md`, `<output-path>/task/task_<ts>/`, and (round 1 only) `<output-path>/testcases.json` + `<output-path>/app-metadata.json` + `<output-path>/_extracted.json`.
 
-- `VALIDATION PASSED` → done.
-- `VALIDATION FAILED` → fix upstream data and re-run; do NOT hand-write the report.
+## Expected Output (report back to the caller)
 
-To re-validate an existing report without regenerating it (debugging only):
+Report back concisely (do not stream large file contents into the caller's context):
 
-```bash
-node "$TOOL_DIR/engine/report-tool.ts" validate "<output_path>/self-test-report.md"
-```
+- **Terminal status** from `a2h_self_test_status`: `COMPLETED` (with `pass_count` / `fail_count` / `unknown_count` / `pass_rate` / `task_subdir`) | `CRASHED` | `NOT_STARTED` | `TIMEOUT` (the skill killed `pid` after exceeding `max_elapsed`).
+- **Path** to `<output-path>/self-test-report.md`.
+- **Early-exit (environmental) failures**: the sentinel `reason:` line (config / device / `@autotest/agent` missing + auto-install failed / batch crash / precondition failure). These are **NOT application defects** — do NOT enter the fix flow; surface the reason so the user can fix the environment. (The skill, not this agent, decides `stop_reason = agent_early_exit` from the sentinel `reason:`.)
+- Do **not** read full per-case HTML/MD/JSON reports back into the caller — they are large (10KB–200KB); point the caller to the files / `task_subdir`.
 
-**Pre-case rendering**: Rows with `case_name` starting with `[PRE] ` go into `## 前置用例`. All others go into `## 用例详情`. Pre indices and Case indices each start at 1 within their own section (`### Pre 1:`, `### Case 1:`). The script emits these forms automatically — do NOT hand-edit to `### Case PRE-1:` or any other variant; the validator will reject it.
+## Constraints
 
-> **What pre-cases are (and aren't) — context downstream agents MUST respect**:
-> Pre-cases are **data/environment setup scripts** (e.g., import a test track, grant permissions, skip onboarding). They are NOT feature scenarios under test. A pre-case FAIL almost always indicates a testing-environment issue (missing media, ungranted permission, system file-picker glitch), **NOT an application defect**. That is why the report:
->   - surfaces **常规通过率** (regular-only pass rate) as the primary quality metric in `## 测试概览` and `## 测试总结`;
->   - keeps `含前置通过率` only as a secondary reference with an explicit disclaimer;
->   - tells the 建议 reader that pre-failures should be treated as environment problems first, and only enter the fix flow if a white-box review confirms a real code bug.
->
-> Downstream agents — especially `self-test-fixer` — must respect this framing: **do not modify application code based on a pre-case failure unless white-box review concludes the failure surfaces a genuine app defect**. This rationale is intentional and load-bearing; do not collapse it into a one-liner.
+- **Single source of truth**: `hmos-integration-test/SKILL.md` is authoritative; this wrapper only wires params + reports results.
+- **No procedure duplication**: if you find yourself spelling out `resolve-metadata-tool` / `testcases-tool` / `self-test-runner` / `report-tool` commands here, stop — that belongs in the skill, not here. The skill uses `$SKILL_SCRIPTS/<script>.mjs` (no `$TOOL_DIR`, no `run`/`generate` subcommand keywords — flat `--` args + `--status`).
+- **Pre-cases are environment setup, not app defects**: surface `常规通过率` (regular-only pass rate) as the quality metric; pre-case failures go to the fix flow only after white-box confirmation (per `self-test-fixer`).