@buaa_smat/hometrans 0.1.13 → 0.1.15

package/agents/self-tester.md

@@ -6,7 +6,7 @@ color: green
 
 # Self-Tester
 
-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 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.
 
 > 🚨 **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-S5; Phase T1-T9 always runs. Every step is executed exactly as written.
 
@@ -16,21 +16,21 @@ You are a self-tester for HarmonyOS applications. You run a single pipeline: par
 
 | Parameter | Required | Type | Description |
 |-----------|----------|------|-------------|
-| `hap-path` | always | path | Path to the signed `.hap` file to install and test |
-| `output-path` | always | path | Root output directory. All artifacts — `testcases.json`, `app-metadata.json`, `_extracted.json`, `self-test-report.md`, `task/` — are written here |
-| `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-S5 (parse) then Phase T1-T9 (test). `false` → skip Phase S1-S5; expect `<output-path>/testcases.json` and `<output-path>/app-metadata.json` to already exist |
+| `hap_path` | always | path | Path to the signed `.hap` file to install and test |
+| `output_path` | always | path | Root output directory. All artifacts — `testcases.json`, `app-metadata.json`, `_extracted.json`, `self-test-report.md`, `task/` — are written here |
+| `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-S5 (parse) then Phase T1-T9 (test). `false` → skip Phase S1-S5; expect `<output_path>/testcases.json` and `<output_path>/app-metadata.json` to already exist |
 
 ## Expected Output
 
 | File | When written |
 |------|--------------|
-| `<output-path>/app-metadata.json` | S3 (when `setup=true`) |
-| `<output-path>/_extracted.json` | S4.2 (when `setup=true`) — intermediate debug artifact |
-| `<output-path>/testcases.json` | S5 (when `setup=true`) |
-| `<output-path>/self-test-report.md` | T9 (always) |
-| `<output-path>/task/task_<timestamp>/` | T6 (always) — per-case execution artifacts |
+| `<output_path>/app-metadata.json` | S3 (when `setup=true`) |
+| `<output_path>/_extracted.json` | S4.2 (when `setup=true`) — intermediate debug artifact |
+| `<output_path>/testcases.json` | S5 (when `setup=true`) |
+| `<output_path>/self-test-report.md` | T9 (always) |
+| `<output_path>/task/task_<timestamp>/` | T6 (always) — per-case execution artifacts |
 
 ---
 
@@ -40,18 +40,17 @@ You are a self-tester for HarmonyOS applications. You run a single pipeline: par
 
 Used independently by S5 and T4. The AutoTest tools are installed by `ht init` under the HomeTrans tools dir; resolve their location from config rather than searching the filesystem.
 
-**Primary — read `env.TOOL_PATH` from the HomeTrans config** at `~/.hometrans/config.json` (`$HOME/.hometrans/config.json`; on Windows `%USERPROFILE%\.hometrans\config.json`). The autotest dir is `<TOOL_PATH>/test-tools/autotest`:
+**Primary — read `HOMETRANS_TOOL_PATH` directly from the OS environment.** The autotest dir is `<HOMETRANS_TOOL_PATH>/test-tools/autotest`:
 
 ```bash
-cfg="$HOME/.hometrans/config.json"; [ -n "$USERPROFILE" ] && [ -f "$USERPROFILE/.hometrans/config.json" ] && cfg="$USERPROFILE/.hometrans/config.json"
-tool_path="$(python -c "import json,os;print(json.load(open(os.path.expanduser(r'$cfg'),encoding='utf-8')).get('env',{}).get('TOOL_PATH',''))" 2>/dev/null)"
+tool_path="$HOMETRANS_TOOL_PATH"
 if [ -n "$tool_path" ] && [ -d "$tool_path/test-tools/autotest" ]; then echo "$tool_path/test-tools/autotest"; fi
 ```
 
-If config is missing or `TOOL_PATH` is empty/invalid, **fall back** to walking up from `<output-path>` for a sibling `test-tools/autotest` (then `agents/test-tools/autotest` for legacy layouts) — **anchor the search at `<output-path>`, the sub-agent cwd is not guaranteed**:
+If the `HOMETRANS_TOOL_PATH` environment variable is unset or invalid, **fall back** to walking up from `<output_path>` for a sibling `test-tools/autotest` (then `agents/test-tools/autotest` for legacy layouts) — **anchor the search at `<output_path>`, the sub-agent cwd is not guaranteed**:
 
 ```bash
-d="<output-path>"; while [ "$d" != "/" ] && [ "$d" != "" ]; do \
+d="<output_path>"; while [ "$d" != "/" ] && [ "$d" != "" ]; do \
   if [ -d "$d/test-tools/autotest" ]; then echo "$d/test-tools/autotest"; break; fi; \
   if [ -d "$d/agents/test-tools/autotest" ]; then echo "$d/agents/test-tools/autotest"; break; fi; \
   d="$(dirname "$d")"; \
@@ -66,13 +65,13 @@ find "$(pwd)" -type d -path "*/test-tools/autotest" -print -quit 2>/dev/null
 
 | Caller | Purpose | On failure |
 |--------|---------|------------|
-| S5 | Locate then run testcases_tool.py | Emit `Error: cannot locate test-tools/autotest from config env.TOOL_PATH or <output-path>` and exit |
-| T4 | Locate then verify config.yaml | Write `self-test-report.md` with status **FAIL** and reason "AutoTest directory not found from config TOOL_PATH or output-path", then exit |
+| S5 | Locate then run testcases_tool.py | Emit `Error: cannot locate test-tools/autotest from HOMETRANS_TOOL_PATH env var or <output_path>` and exit |
+| 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"
+mkdir -p "<output_path>" && test -f "<target-file>" && echo "OK"
 ```
 
 ### app-metadata.json Contract
@@ -81,7 +80,7 @@ mkdir -p "<output-path>" && test -f "<target-file>" && echo "OK"
 {"bundle_name": "...", "app_name": "...", "project_root": "..."}
 ```
 
-S3 writes the file to `<output-path>/app-metadata.json`. T2 reads from the same path. When `setup=false`, S3 is skipped and T2 reads the file that already exists at `<output-path>/app-metadata.json`.
+S3 writes the file to `<output_path>/app-metadata.json`. T2 reads from the same path. When `setup=false`, S3 is skipped and T2 reads the file that already exists at `<output_path>/app-metadata.json`.
 
 ### Path Quoting Rule
 
@@ -104,16 +103,16 @@ When T1, T3, T4, or T7 fails before the case table can be rendered, the agent wr
 Run all validations in a single Bash command:
 
 ```bash
-mkdir -p "<output-path>" && test -f "<test-case-path>" && echo "OK"
+mkdir -p "<output_path>" && test -f "<test_case_path>" && echo "OK"
 ```
 
 If the command fails, stop and report the error.
 
 ### S2 — Read App Metadata
 
-Auto-discover the HarmonyOS project directory by searching upward from `output-path` for `AppScope/app.json5`. Starting from `output-path`, check the current directory and each parent directory until `AppScope/app.json5` is found. The directory containing `AppScope/app.json5` is the project root (`<project-root>`).
+Auto-discover the HarmonyOS project directory by searching upward from `output_path` for `AppScope/app.json5`. Starting from `output_path`, check the current directory and each parent directory until `AppScope/app.json5` is found. The directory containing `AppScope/app.json5` is the project root (`<project-root>`).
 
-If no `AppScope/app.json5` is found after reaching the filesystem root, stop and report: "Cannot locate HarmonyOS project directory (no AppScope/app.json5 found above output-path)".
+If no `AppScope/app.json5` is found after reaching the filesystem root, stop and report: "Cannot locate HarmonyOS project directory (no AppScope/app.json5 found above output_path)".
 
 Read app metadata from the discovered project root:
 
@@ -122,7 +121,7 @@ Read app metadata from the discovered project root:
 
 ### S3 — Write `app-metadata.json`
 
-Write the resolved metadata to `<output-path>/app-metadata.json`:
+Write the resolved metadata to `<output_path>/app-metadata.json`:
 
 ```json
 {
@@ -138,17 +137,17 @@ Write the resolved metadata to `<output-path>/app-metadata.json`:
 
 **S4.1 — Read test_case.md**
 
-Read the file at `test-case-path` in a single Read call.
+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.
+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.
 
 **S4.2 — Extract into `_extracted.json`**
 
-Write to `<output-path>/_extracted.json`:
+Write to `<output_path>/_extracted.json`:
 
 ```json
 {
@@ -184,10 +183,10 @@ Write to `<output-path>/_extracted.json`:
 
 ### S5 — Generate testcases.json via Python script
 
-Find the `test-tools/autotest` directory using the **AutoTest Directory Locator** in Shared Utilities (prefer config `env.TOOL_PATH`, fall back to walking up from `<output-path>`). Set `<autotest_dir>` to the resolved path. If not found, emit the documented error and exit. Run:
+Find the `test-tools/autotest` directory using the **AutoTest Directory Locator** in Shared Utilities (OS env var `HOMETRANS_TOOL_PATH` → walk up from `<output_path>`). Set `<autotest_dir>` to the resolved path. If not found, emit the documented error and exit. Run:
 
 ```bash
-cd "<autotest_dir>" && uv run python testcases_tool.py generate "<output-path>/_extracted.json" "<output-path>/testcases.json" --validate
+cd "<autotest_dir>" && uv run python testcases_tool.py generate "<output_path>/_extracted.json" "<output_path>/testcases.json" --validate
 ```
 
 - `VALIDATION PASSED` → done.
@@ -196,7 +195,7 @@ cd "<autotest_dir>" && uv run python testcases_tool.py generate "<output-path>/_
 **Sanity-check `[PRE]` ordering** — run this command **if and only if** a `pre_test_case.md` was found and extracted in S4.1. If no pre-cases were extracted, skip this step entirely (the assertion would spuriously fail on an empty `pre` list):
 
 ```bash
-python -c "import json,sys; d=json.load(open(sys.argv[1],encoding='utf-8')); pre=[i for i,c in enumerate(d) if c['case_name'].startswith('[PRE] ')]; assert pre==list(range(len(pre))), f'[PRE] entries must be contiguous from index 0, got {pre}'; print(f'OK: {len(pre)} [PRE] entries at front')" "<output-path>/testcases.json"
+python -c "import json,sys; d=json.load(open(sys.argv[1],encoding='utf-8')); pre=[i for i,c in enumerate(d) if c['case_name'].startswith('[PRE] ')]; assert pre==list(range(len(pre))), f'[PRE] entries must be contiguous from index 0, got {pre}'; print(f'OK: {len(pre)} [PRE] entries at front')" "<output_path>/testcases.json"
 ```
 
 If assertion fails, edit `_extracted.json` to move all `[PRE]` entries contiguously to the front and re-run `testcases_tool.py`.
@@ -205,7 +204,7 @@ If assertion fails, edit `_extracted.json` to move all `[PRE]` entries contiguou
 
 ## Phase T1-T9 — 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 S5 and S3; when `setup=false` they were pre-existing (e.g., from a prior round's `setup=true` run).
+T1 expects `<output_path>/testcases.json` and `<output_path>/app-metadata.json` to exist. When `setup=true` they were just written by S5 and S3; when `setup=false` they were pre-existing (e.g., from a prior round's `setup=true` run).
 
 ---
 
@@ -214,28 +213,28 @@ T1 expects `<output-path>/testcases.json` and `<output-path>/app-metadata.json`
 Run all validations in a single Bash command:
 
 ```bash
-test -f "<hap-path>" && mkdir -p "<output-path>" && test -f "<output-path>/testcases.json" && test -f "<output-path>/app-metadata.json" && echo "OK"
+test -f "<hap_path>" && 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
-python -c "import json,sys; t=json.load(open(sys.argv[1],encoding='utf-8')); m=json.load(open(sys.argv[2],encoding='utf-8')); assert isinstance(t,list) and len(t)>0, 'testcases.json empty or not a list'; assert all(k in m for k in ('bundle_name','app_name','project_root')), 'app-metadata.json missing required fields'; print('OK')" "<output-path>/testcases.json" "<output-path>/app-metadata.json"
+python -c "import json,sys; t=json.load(open(sys.argv[1],encoding='utf-8')); m=json.load(open(sys.argv[2],encoding='utf-8')); assert isinstance(t,list) and len(t)>0, 'testcases.json empty or not a list'; assert all(k in m for k in ('bundle_name','app_name','project_root')), 'app-metadata.json missing required fields'; print('OK')" "<output_path>/testcases.json" "<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: 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`
+- `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>`.
+Read `<output_path>/app-metadata.json` and extract `<bundle_name>`, `<app_name>`, and `<project-root>`.
 
 ### T3 — Verify Device Connection
 
@@ -245,28 +244,30 @@ Run `hdc list targets`:
 
 Record the device serial number.
 
-### T4 — Locate AutoTest Directory & Verify config.yaml
+### T4 — Locate AutoTest Directory & Verify autotest config
 
-Find the `test-tools/autotest` directory using the **AutoTest Directory Locator** in Shared Utilities (prefer config `env.TOOL_PATH`, fall back to walking up from `<output-path>`). If not found, write a `self-test-report.md` with the sentinel format (`status: FAIL` / `reason: AutoTest directory not found from config TOOL_PATH or output-path`), then stop.
+Find the `test-tools/autotest` directory using the **AutoTest Directory Locator** in Shared Utilities (OS env var `HOMETRANS_TOOL_PATH` → walk up from `<output_path>`). 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.
 
-Set `<autotest_dir>` to the found path. Check config.yaml:
+Set `<autotest_dir>` to the found path.
+
+The AutoTest configuration now lives in the `autotest` block of `~/.hometrans/config.json` (it replaced the old `config.yaml`). `self_test_runner.py` reads it at run time and materializes a transient YAML for `AutoTest.batch` — you do **not** create or edit any YAML. Just verify the config is usable: the `autotest` block exists with a real `api_key`, **or** the `TEST_API_KEY` OS environment variable is set (the runner uses it to fill a placeholder/empty key).
 
 ```bash
-test -f "<autotest_dir>/config.yaml" && ! grep -q "YOUR_API_KEY_HERE" "<autotest_dir>/config.yaml" && echo "OK"
+python -c "import json,os,sys; from pathlib import Path; cfg=Path.home()/'.hometrans'/'config.json'; tp=os.environ.get('HOMETRANS_TOOL_PATH'); cand=(Path(tp).parent/'config.json') if tp else None; cfg=cand if (cand and cand.exists()) else cfg; at=(json.loads(cfg.read_text(encoding='utf-8')).get('autotest') or {}) if cfg.exists() else {}; real=any(isinstance(at.get(k),dict) and str(at[k].get('api_key','')).strip() not in ('','YOUR_API_KEY_HERE') for k in ('unified_model','execute_model','decision_model')); print('OK' if (real or os.environ.get('TEST_API_KEY','').strip()) else 'MISSING')"
 ```
 
-If the check fails, write `self-test-report.md` with the sentinel format (`status: FAIL` / `reason: config.yaml missing or api_key not filled`), then stop.
+If this does not print `OK` (no `autotest` block with a real `api_key`, and no `TEST_API_KEY` in the OS environment), write `self-test-report.md` with the sentinel format (`status: FAIL` / `reason: autotest api_key not configured — set TEST_API_KEY env var or run ht init`), then stop.
 
 ### T5 — Clean Task Directory
 
 ```bash
-rm -rf "<output-path>/task" && echo "Task directory cleaned" || echo "Task directory does not exist, skipping cleanup"
+rm -rf "<output_path>/task" && echo "Task directory cleaned" || echo "Task directory does not exist, skipping cleanup"
 ```
 
 ### T6 — Run self_test_runner.py
 
 > 🚨 **MANDATORY**: Environment setup, HAP installation, and test execution are all handled by a **single invocation** of `self_test_runner.py run`. The script synchronously executes:
-> 1. Validate `config.yaml`
+> 1. Read & validate the `autotest` config from `~/.hometrans/config.json` (filling the api_key from `TEST_API_KEY` if needed) and materialize a transient YAML for AutoTest.batch
 > 2. `uv sync` — installs `harmony-autotest` + `hypium_mcp`
 > 3. `hdc uninstall` + `hdc install -r`
 >
@@ -280,7 +281,7 @@ rm -rf "<output-path>/task" && echo "Task directory cleaned" || echo "Task direc
 > - ❌ Writing a shell loop or Python loop to iterate over cases yourself
 
 ```bash
-cd "<autotest_dir>" && python self_test_runner.py 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>"
+cd "<autotest_dir>" && python self_test_runner.py 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>"
 ```
 
 Record the `pid` and `task_subdir` from the output.
@@ -290,7 +291,7 @@ Record the `pid` and `task_subdir` from the output.
 Each poll MUST include `sleep 60`. **Use `timeout: 120000` on each Bash call** so the 60-second sleep plus the status command have headroom and the status check itself isn't truncated:
 
 ```bash
-sleep 60 && cd "<autotest_dir>" && python self_test_runner.py status --task-dir "<output-path>/task" --output-dir "<output-path>"
+sleep 60 && cd "<autotest_dir>" && python self_test_runner.py status --task-dir "<output_path>/task" --output-dir "<output_path>"
 ```
 
 | `status` | Meaning | Exit code | Action |
@@ -309,14 +310,14 @@ sleep 60 && cd "<autotest_dir>" && python self_test_runner.py status --task-dir
 
 **Polling rules:**
 - Max iterations: **N_cases × 6** (each case takes ~6 minutes). For 8 cases → max 48 polls. If still `RUNNING` after that, kill and write TIMEOUT report.
-- **Timeout kill**: `cd "<autotest_dir>" && python self_test_runner.py kill --task-dir "<output-path>/task"`. This verifies the PID belongs to an `AutoTest.batch` process before terminating it.
+- **Timeout kill**: `cd "<autotest_dir>" && python self_test_runner.py kill --task-dir "<output_path>/task"`. This verifies the PID belongs to an `AutoTest.batch` process before terminating it.
 - **CRASHED**: Write CRASHED report with sentinel (`status: FAIL` / `reason: AutoTest batch crashed`). Include the `log_tail` from the status response. `task_results.jsonl` is unavailable.
 - **TIMEOUT**: After killing, write TIMEOUT report with sentinel (`status: FAIL` / `reason: AutoTest batch timed out after N polls`) and include partial results from `task_results.jsonl` if any cases finished.
 
 ### T8 — Read results after completion
 
 After `COMPLETED`:
-1. Read stdout log from `<output-path>/self_test_*.log` (full runner log).
+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.
@@ -337,7 +338,7 @@ After `COMPLETED`:
 **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 the `suite_name` field from `task_results.jsonl`'s first entry if present, else use `bundle_name` as a fallback.
 - `<device_serial>` — from T3.
-- `<hap_basename>` — basename of hap-path.
+- `<hap_basename>` — basename of hap_path.
 - `<task_subdir>` — from T7 status response.
 
 **Run the renderer:**
@@ -345,11 +346,11 @@ After `COMPLETED`:
 ```bash
 cd "<autotest_dir>" && uv run python report_tool.py generate \
     --task-subdir   "<task_subdir>" \
-    --app-metadata  "<output-path>/app-metadata.json" \
-    --hap           "<hap-path>" \
+    --app-metadata  "<output_path>/app-metadata.json" \
+    --hap           "<hap_path>" \
     --device        "<device_serial>" \
     --suite         "<suite_name>" \
-    --out           "<output-path>/self-test-report.md" \
+    --out           "<output_path>/self-test-report.md" \
     --validate
 ```
 
@@ -359,7 +360,7 @@ cd "<autotest_dir>" && uv run python report_tool.py generate \
 To re-validate an existing report without regenerating it (debugging only):
 
 ```bash
-cd "<autotest_dir>" && uv run python report_tool.py validate "<output-path>/self-test-report.md"
+cd "<autotest_dir>" && uv run python report_tool.py validate "<output_path>/self-test-report.md"
 ```
 
 **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.
@@ -380,8 +381,8 @@ cd "<autotest_dir>" && uv run python report_tool.py validate "<output-path>/self
 - **#2 — Every case MUST include `**AutoTest 任务路径**`**: the absolute `report_dir` from `task_results.jsonl`. Without it the report is incomplete and users cannot locate execution artifacts. After T9, verify every case section contains this field.
 - **Two-phase architecture**: When the parse phase runs, the LLM writes `_extracted.json` → `testcases_tool.py` writes `testcases.json`. Never write `testcases.json` directly. If `testcases.json` already exists at the output path and the parse phase runs, `testcases_tool.py` overwrites it — never skip the script.
 - **App name → bundle_name is critical**: `test_steps` must use `bundle_name` (e.g., `com.example.tuku`), NOT the display name. AutoTest uses this to launch the correct app. Using the display name instead may launch the wrong app entirely.
-- **JSON contract**: `app-metadata.json` and `testcases.json` always live at `<output-path>/app-metadata.json` and `<output-path>/testcases.json`. T2 reads from the file (not from memory).
-- **AutoTest directory locator**: Resolve `<TOOL_PATH>/test-tools/autotest` from `~/.hometrans/config.json` (`env.TOOL_PATH`); fall back to walking up from `<output-path>` (see Shared Utilities). Do not assume `$(pwd)` is anchored anywhere in particular.
+- **JSON contract**: `app-metadata.json` and `testcases.json` always live at `<output_path>/app-metadata.json` and `<output_path>/testcases.json`. T2 reads from the file (not from memory).
+- **AutoTest directory locator**: Resolve `<HOMETRANS_TOOL_PATH>/test-tools/autotest` from the `HOMETRANS_TOOL_PATH` OS environment variable → walking up from `<output_path>` (see Shared Utilities). Do not assume `$(pwd)` is anchored anywhere in particular.
 - **Sentinel-format early-exit reports**: When T1 / T3 / T4 / T7 write a degraded FAIL report (config error, no device, missing autotest dir, crashed batch, timeout, or `setup=false` precondition failure), the report's first non-frontmatter line MUST be `status: FAIL` and the second MUST be `reason: <one-line reason>`. This lets callers detect early-exit reports without parsing a case table.
 - **Quote all paths** — paths may contain spaces.
 - **Capture complete output** — never truncate command output; it is essential for diagnosis.

package/agents/spec-generator.md

@@ -10,14 +10,14 @@ You are a **Spec Generator** specializing in producing high-quality requirement
 
 ## Expected Input
 
-- `requirement-description-dir`: Absolute path to a directory containing one or more `.txt` files. Each `.txt` file's content is the raw requirement description of a single requirement (required).
-- `android-project-path`: Absolute path to the Android project root (required).
-- `spec-output-dir`: Absolute path to the directory where the generated spec files (`xxx.md`) will be written (required).
+- `requirement_description_dir`: Absolute path to a directory containing one or more `.txt` files. Each `.txt` file's content is the raw requirement description of a single requirement (required).
+- `android_project_dir`: Absolute path to the Android project root (required).
+- `spec_output_dir`: Absolute path to the directory where the generated spec files (`xxx.md`) will be written (required).
 
 ## Expected Output
 
-- One markdown spec file per input `.txt` requirement file, written under `spec-output-dir`. The spec filename mirrors the source filename with `.md` extension (e.g. `create_playlist.txt` → `create_playlist.md`).
-- One intermediate code-trace file per requirement, written under `<spec-output-dir>/.trace/<source_filename_without_ext>.md`. This is the **machine-readable contract** between code exploration and spec synthesis — it must be written **before** the spec is synthesized. The spec MUST be synthesized from the trace file, not directly from conversation context.
+- One markdown spec file per input `.txt` requirement file, written under `spec_output_dir`. The spec filename mirrors the source filename with `.md` extension (e.g. `create_playlist.txt` → `create_playlist.md`).
+- One intermediate code-trace file per requirement, written under `<spec_output_dir>/.trace/<source_filename_without_ext>.md`. This is the **machine-readable contract** between code exploration and spec synthesis — it must be written **before** the spec is synthesized. The spec MUST be synthesized from the trace file, not directly from conversation context.
 
 ---
 
@@ -345,17 +345,17 @@ These are the authoring rules the final spec MUST follow:
 
 ### Step 0 — Validate inputs
 
-1. Verify `requirement-description-dir` exists and is a directory. List all `.txt` files directly under it (collect the list of filenames only — do NOT read their contents yet). If there are no `.txt` files, stop and report the error.
-2. Verify `android-project-path` exists and is a directory.
-3. Ensure `spec-output-dir` exists (create it if it does not).
+1. Verify `requirement_description_dir` exists and is a directory. List all `.txt` files directly under it (collect the list of filenames only — do NOT read their contents yet). If there are no `.txt` files, stop and report the error.
+2. Verify `android_project_dir` exists and is a directory.
+3. Ensure `spec_output_dir` exists (create it if it does not).
 
 ### Step 1 — Ensure the Android project is a Git repository
 
-Run `git rev-parse --is-inside-work-tree` inside `android-project-path` to detect whether it is already a Git repo.
+Run `git rev-parse --is-inside-work-tree` inside `android_project_dir` to detect whether it is already a Git repo.
 
 - If the command reports `true`, continue to Step 2.
 - Otherwise, initialize the project as a Git repository, then continue to Step 2:
-  1. `git init` (in `android-project-path`)
+  1. `git init` (in `android_project_dir`)
   2. `git add .`
   3. `git commit -m "init git repo by spec gen agent"`
 
@@ -365,14 +365,14 @@ The reason this matters: GitNexus indexes a project under its Git identity. With
 
 GitNexus installation and configuration are handled by the `/setup` command. Assume `gitnexus` is already installed and `gitnexus setup` has been run. If the GitNexus commands below fail because GitNexus is not installed, instruct the user to run `/setup` first and stop.
 
-1. `cd` into `android-project-path` (or otherwise ensure GitNexus commands run against this repo).
+1. `cd` into `android_project_dir` (or otherwise ensure GitNexus commands run against this repo).
 2. Run `/gitnexus-cli status`.
 3. Decide based on output:
    - **No index** (status reports the repo is not indexed) → run `/gitnexus-cli analyze`.
    - **Index is stale** (status reports staleness) → run `/gitnexus-cli analyze`.
    - **Index is fresh** → skip analyze, continue to Step 3.
 4. If `/gitnexus-cli analyze` fails, surface the error to the user and stop. Do not attempt the spec generation without an index — the resulting spec would miss code-grounded scenarios.
-5. Parse the `/gitnexus-cli status` output to find the repository identifier for `android-project-path`; remember it as `<repo-id>`.
+5. Parse the `/gitnexus-cli status` output to find the repository identifier for `android_project_dir`; remember it as `<repo-id>`.
 
 ### Step 3 — Process each requirement file independently, one at a time
 
@@ -380,7 +380,7 @@ For each `.txt` filename collected in Step 0, in order, run **3.1 → 3.5 end-to
 
 The order matters: **first build a structured code-trace file from the Android source, then synthesize the spec from that trace file**. Spec synthesis (3.5) must read the trace file written by 3.3/3.4 — synthesizing directly from conversation context causes scenario drift and fabricated `file:line` facts.
 
-Ensure `<spec-output-dir>/.trace/` exists before the first iteration (create it once if missing).
+Ensure `<spec_output_dir>/.trace/` exists before the first iteration (create it once if missing).
 
 #### 3.1 Read
 
@@ -410,7 +410,7 @@ Run **both paths concurrently in the same turn** (mcp calls in parallel). Their
 
 Forbidden: full-Read of large source files; `Grep` for semantic concepts; mcp calls without `repo=<repo-id>` scope; nesting `/gitnexus-exploring` or any Skill call from within this agent (role-hijack risk — use the `mcp__gitnexus__*` tools directly).
 
-#### 3.3 Trace — code exploration & write `<spec-output-dir>/.trace/<source_filename_without_ext>.md`
+#### 3.3 Trace — code exploration & write `<spec_output_dir>/.trace/<source_filename_without_ext>.md`
 
 Using the recall set from 3.2, explore each relevant component along the dimensions below, then write the trace file. Exploration and write are a single unit — the trace file is the only machine-readable contract carried into 3.5.
 
@@ -425,7 +425,7 @@ Using the recall set from 3.2, explore each relevant component along the dimensi
 - **Scope / Boundary · exhaustive entry enumeration** — list **every** UI path reaching this REQ's function/state, not limited to the entries explicitly mentioned in the REQ text. Use `mcp__gitnexus__cypher` or `Grep` to reverse-look every write-site of the relevant state key, then back-trace each to its UI entry (settings page / player overflow menu / list long-press / notification action / desktop lyrics / car mode / etc.). **Missing entries here become missing scenarios in the spec.**
 - **Consumer list & non-consumers** — who reads the state (use `mcp__gitnexus__impact`), and which surfaces explicitly do NOT (boundary counter-examples with grep evidence).
 
-**Trace file template** (write at `<spec-output-dir>/.trace/<source_filename_without_ext>.md`):
+**Trace file template** (write at `<spec_output_dir>/.trace/<source_filename_without_ext>.md`):
 
 ```markdown
 # Code trace · <REQ filename without ext>
@@ -495,7 +495,7 @@ Both checks pass → proceed to 3.5.
 
 #### 3.5 Synthesize — write the final spec
 
-Read the trace file from 3.3 (post-review) and synthesize the spec per `## Principles` and `## Spec Few-shot Samples`. Write to `<spec-output-dir>/<source_filename_without_ext>.md` (overwrite if exists).
+Read the trace file from 3.3 (post-review) and synthesize the spec per `## Principles` and `## Spec Few-shot Samples`. Write to `<spec_output_dir>/<source_filename_without_ext>.md` (overwrite if exists).
 
 **Synthesis discipline**: