@buaa_smat/hometrans 0.1.0 → 0.1.2

package/agents/test-tools/autotest/self_test_runner.py

@@ -0,0 +1,773 @@
+#!/usr/bin/env python3
+"""
+自测执行器 - 统一的进程管理和测试执行
+
+子命令：
+    run      - 准备环境后后台启动 AutoTest.batch
+    status   - 查询后台执行状态（RUNNING/COMPLETED/CRASHED）
+    kill     - 终止后台进程
+    clean    - 重置本目录状态（.venv / 残留中间产物 / 残留进程），不动全局 uv 缓存
+
+使用示例：
+    python self_test_runner.py run --testcases testcases.json --hap app.hap --bundle-name com.xxx
+    python self_test_runner.py run --testcases testcases.jsonl --hap app.hap --bundle-name com.xxx
+    python self_test_runner.py status --task-dir task
+    python self_test_runner.py kill --task-dir task
+    python self_test_runner.py clean
+
+`--testcases` 同时接受 JSON 数组（旧 `testcases.json`）与 JSONL，JSON 数组会自动转换成 JSONL。
+
+执行流程：
+    主进程：清理 + 校验 config.yaml + uv sync + hdc install hap（等待完成）
+            ↓
+    后台：python -m AutoTest.batch（循环执行 testcases.jsonl，cwd 为 task_<timestamp> 子目录）
+
+依赖：harmony-autotest 与 hypium_mcp 均在 pyproject.toml 中声明为远程 whl URL
+依赖；`uv sync` 会拉取到本目录 .venv 内，不再需要手动 pip install。
+
+AutoTest.batch 启动时 cwd 设为 task_<timestamp>，因此 hypium_mcp.log / tmp_hypium/
+等中间产物会落在 task 子目录内，避免污染插件源码目录。
+"""
+
+import argparse
+import glob
+import hashlib
+import io
+import json
+import logging
+import os
+import shutil
+import subprocess
+import sys
+import time
+import traceback
+from datetime import datetime
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+HAP_INSTALL_WAIT = 10
+INSTALL_TIMEOUT = 120
+UV_TIMEOUT = 600
+API_KEY_PLACEHOLDER = "YOUR_API_KEY_HERE"
+DEFAULT_CATEGORY = "self_test"
+
+logger = logging.getLogger("self_test_runner")
+
+
+# =============================================================================
+# 公共函数：进程管理
+# =============================================================================
+
+def _get_python_processes():
+    if sys.platform != "win32":
+        return []
+
+    ps_cmd = (
+        'Get-CimInstance Win32_Process -Filter "Name=\'python.exe\'" '
+        '| Select-Object ProcessId,CommandLine '
+        '| ForEach-Object { "$($_.ProcessId)|$($_.CommandLine)" }'
+    )
+    try:
+        result = subprocess.run(
+            ["powershell.exe", "-NoProfile", "-Command", ps_cmd],
+            capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=15,
+        )
+    except Exception:
+        return []
+
+    if not result.stdout:
+        return []
+
+    processes = []
+    for line in result.stdout.splitlines():
+        line = line.strip()
+        if not line or "|" not in line:
+            continue
+        pid_str, cmdline = line.split("|", 1)
+        try:
+            pid = int(pid_str.strip())
+            processes.append((pid, cmdline.strip()))
+        except ValueError:
+            continue
+    return processes
+
+
+def _get_process_cmdline(pid: int) -> str | None:
+    if sys.platform == "win32":
+        ps_cmd = f"(Get-CimInstance Win32_Process -Filter \"ProcessId={pid}\").CommandLine"
+        try:
+            result = subprocess.run(
+                ["powershell.exe", "-NoProfile", "-Command", ps_cmd],
+                capture_output=True, text=True, timeout=10,
+            )
+            return result.stdout.strip() or None
+        except Exception:
+            return None
+    else:
+        try:
+            return Path(f"/proc/{pid}/cmdline").read_text().replace("\x00", " ").strip()
+        except Exception:
+            return None
+
+
+def _pid_alive(pid: int) -> bool:
+    if sys.platform == "win32":
+        import ctypes
+        kernel32 = ctypes.windll.kernel32
+        SYNCHRONIZE = 0x00100000
+        PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
+        handle = kernel32.OpenProcess(SYNCHRONIZE | PROCESS_QUERY_LIMITED_INFORMATION, False, pid)
+        if handle == 0:
+            return False
+        ret = kernel32.WaitForSingleObject(handle, 0)
+        kernel32.CloseHandle(handle)
+        return ret == 0x00000102  # WAIT_TIMEOUT
+    else:
+        try:
+            os.kill(pid, 0)
+            return True
+        except ProcessLookupError:
+            return False
+        except PermissionError:
+            return True
+
+
+def _kill_process_tree(pid: int):
+    if sys.platform == "win32":
+        subprocess.run(["taskkill", "/F", "/T", "/PID", str(pid)], capture_output=True, timeout=10)
+    else:
+        try:
+            os.killpg(os.getpgid(pid), 9)
+        except Exception:
+            os.kill(pid, 9)
+
+
+# =============================================================================
+# 公共函数：清理
+# =============================================================================
+
+def _pyproject_sha256() -> str:
+    """Hash the active pyproject.toml so we can detect dep changes."""
+    return hashlib.sha256((SCRIPT_DIR / "pyproject.toml").read_bytes()).hexdigest()
+
+
+def _venv_is_fresh() -> bool:
+    """venv exists AND was built against the current pyproject.toml content."""
+    venv = SCRIPT_DIR / ".venv"
+    marker = venv / ".pyproject.sha256"
+    if not (venv / "pyvenv.cfg").exists() or not marker.exists():
+        return False
+    try:
+        return marker.read_text(encoding="utf-8").strip() == _pyproject_sha256()
+    except OSError:
+        return False
+
+
+def _stamp_venv() -> None:
+    """Record pyproject hash inside the venv so next run can short-circuit."""
+    marker = SCRIPT_DIR / ".venv" / ".pyproject.sha256"
+    if marker.parent.exists():
+        try:
+            marker.write_text(_pyproject_sha256(), encoding="utf-8")
+        except OSError as e:
+            logger.warning(f"无法写入 venv 标记 {marker}: {e}")
+
+
+def cleanup_before_run(force_reinit: bool = False):
+    _kill_stale_processes()
+    # 兼容旧版：把之前留在 tools/autotest/ 顶层的 tmp_hypium / hypium_mcp.log
+    # 等清掉。新流程下 batch 会在 task_<ts> 目录里生成它们，不会再到这里。
+    _clean_stale_artifacts(SCRIPT_DIR)
+    if force_reinit:
+        logger.info("--force-reinit 指定，强制清理 venv")
+        _clean_venv()
+    elif _venv_is_fresh():
+        logger.info("venv 已就绪（pyproject.toml hash 未变），跳过 venv 清理")
+    else:
+        logger.info("venv 不存在或 pyproject.toml 已变更，重建 venv")
+        _clean_venv()
+
+
+def _kill_stale_processes():
+    if sys.platform != "win32":
+        return
+
+    my_pid = os.getpid()
+    # 包含 AutoTest.batch 本体 + hypium_mcp（uvicorn 子进程）+ harmony_autotest 模块入口，
+    # 三类都可能在中断后变成孤儿。
+    markers = [
+        "AutoTest.batch",
+        "-m AutoTest ",
+        "hypium_mcp",
+        "harmony_autotest",
+        "harmony-autotest",
+    ]
+
+    logger.info("=== 清理残留进程 ===")
+
+    processes = _get_python_processes()
+    stale = [(pid, cmd) for pid, cmd in processes if pid != my_pid and any(m in cmd for m in markers)]
+
+    if not stale:
+        logger.info("无残留进程")
+        return
+
+    for pid, cmd in stale:
+        logger.warning(f"杀掉残留进程 PID={pid}: {cmd[:80]}...")
+        try:
+            _kill_process_tree(pid)
+        except Exception as e:
+            logger.warning(f"杀进程失败 PID={pid}: {e}")
+    time.sleep(2)
+
+
+_STALE_ARTIFACT_NAMES = (
+    "tmp_hypium",
+    "hypium_mcp.log",
+    "batch.pid",
+    "batch_stdout.log",
+)
+
+
+def _clean_stale_artifacts(base_dir: Path):
+    """删除 batch 跑完留下的本地中间产物（在 base_dir 顶层查找）。"""
+    for name in _STALE_ARTIFACT_NAMES:
+        p = base_dir / name
+        if not p.exists():
+            continue
+        try:
+            if p.is_dir():
+                shutil.rmtree(p, ignore_errors=True)
+            else:
+                p.unlink()
+            logger.info(f"删除残留: {p}")
+        except OSError as e:
+            logger.warning(f"无法删除 {p}: {e}")
+
+
+def _clean_venv():
+    venv_path = SCRIPT_DIR / ".venv"
+
+    logger.info("=== 清理虚拟环境 ===")
+    if venv_path.exists():
+        logger.info(f"删除: {venv_path}")
+        try:
+            shutil.rmtree(venv_path, ignore_errors=True)
+        except OSError as e:
+            logger.warning(f"无法删除 {venv_path}: {e}")
+
+    for pycache in SCRIPT_DIR.rglob("__pycache__"):
+        if pycache.is_dir():
+            try:
+                shutil.rmtree(pycache, ignore_errors=True)
+            except Exception:
+                pass
+
+
+# =============================================================================
+# run 子命令
+# =============================================================================
+
+def setup_logging(output_dir: str):
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    log_path = Path(output_dir) / f"self_test_{timestamp}.log"
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+    fmt = logging.Formatter("[%(asctime)s] %(levelname)s %(message)s", datefmt="%Y-%m-%d %H:%M:%S")
+    fh = logging.FileHandler(str(log_path), mode="w", encoding="utf-8")
+    fh.setFormatter(fmt)
+    sh = logging.StreamHandler(
+        io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace")
+        if hasattr(sys.stdout, "buffer") else sys.stdout
+    )
+    sh.setFormatter(fmt)
+    logger.addHandler(fh)
+    logger.addHandler(sh)
+    logger.setLevel(logging.DEBUG)
+    logger.info(f"日志文件: {log_path}")
+
+
+def run_cmd(cmd, *, check=True, timeout=None, **kwargs):
+    cmd_str = cmd if isinstance(cmd, str) else " ".join(str(c) for c in cmd)
+    logger.info(f">>> {cmd_str}")
+    try:
+        result = subprocess.run(cmd, timeout=timeout, **kwargs)
+    except subprocess.TimeoutExpired:
+        logger.error(f"命令超时 ({timeout}s): {cmd_str}")
+        raise
+    except Exception:
+        logger.error(f"命令异常:\n{traceback.format_exc()}")
+        raise
+    if result.returncode != 0:
+        logger.warning(f"退出码={result.returncode}: {cmd_str}")
+        if hasattr(result, "stdout") and result.stdout:
+            logger.warning(f"  stdout: {result.stdout.strip() if isinstance(result.stdout, str) else result.stdout}")
+        if hasattr(result, "stderr") and result.stderr:
+            logger.warning(f"  stderr: {result.stderr.strip() if isinstance(result.stderr, str) else result.stderr}")
+        if check:
+            sys.exit(result.returncode)
+    else:
+        logger.debug(f"成功 (rc=0): {cmd_str}")
+    return result
+
+
+def get_hdc():
+    hdc = shutil.which("hdc") or shutil.which("hdc.exe")
+    if not hdc:
+        logger.error("hdc 未找到")
+        sys.exit(1)
+    return hdc
+
+
+def get_uv():
+    """查找 uv 可执行文件。优先使用 UV_BIN 环境变量，否则在 PATH 中搜索。"""
+    uv = os.environ.get("UV_BIN") or shutil.which("uv") or shutil.which("uv.exe")
+    if not uv or not Path(uv).exists():
+        logger.error(
+            "uv 未找到。请确认：\n"
+            "  1) uv 已安装且其所在目录在当前 shell 的 PATH 中（PowerShell 中可用 `where.exe uv` 验证）\n"
+            "  2) 或显式设置环境变量 UV_BIN 指向 uv 可执行文件的绝对路径"
+        )
+        sys.exit(1)
+    logger.info(f"uv: {uv}")
+    return uv
+
+
+def _uv_env():
+    env = os.environ.copy()
+    env["UV_NO_PROGRESS"] = "1"
+    env["RUST_LOG"] = "off"
+    return env
+
+
+def _prepare_testcases_jsonl(input_path: Path, task_subdir: Path) -> Path:
+    """将 `--testcases` 入参规范化为 JSONL 路径。
+
+    - 若 input 是 JSON 数组（旧 `testcases.json` 格式），转成 JSONL
+      落到 `task_subdir/testcases.jsonl`，缺失字段按需补：
+        * `uuid` 用 case_name md5 前 8 位（缺 case_name 时用 idx）
+        * `spec` 补空字符串
+      其它字段原样保留。
+    - 若 input 已是 JSONL（每行一个 JSON 对象），原路径透传。
+
+    检测策略：剥掉 BOM/前导空白后看首字符是否为 `[`。
+    """
+    if not input_path.exists():
+        logger.error(f"测试用例文件不存在: {input_path}")
+        sys.exit(1)
+
+    text = input_path.read_text(encoding="utf-8-sig")
+    stripped = text.lstrip()
+    if not stripped:
+        logger.error(f"测试用例文件为空: {input_path}")
+        sys.exit(1)
+
+    if stripped[0] == "[":
+        try:
+            arr = json.loads(text)
+        except json.JSONDecodeError as e:
+            logger.error(f"测试用例 JSON 数组解析失败 {input_path}: {e}")
+            sys.exit(1)
+        if not isinstance(arr, list):
+            logger.error(f"测试用例文件根不是数组: {input_path}")
+            sys.exit(1)
+
+        out_path = task_subdir / "testcases.jsonl"
+        with out_path.open("w", encoding="utf-8") as f:
+            for idx, case in enumerate(arr, 1):
+                if not isinstance(case, dict):
+                    logger.error(f"用例 #{idx} 不是 JSON 对象: {case!r}")
+                    sys.exit(1)
+                if not case.get("uuid"):
+                    seed = case.get("case_name") or f"case_{idx}"
+                    case["uuid"] = hashlib.md5(seed.encode("utf-8")).hexdigest()[:8]
+                if "spec" not in case:
+                    case["spec"] = ""
+                f.write(json.dumps(case, ensure_ascii=False) + "\n")
+        logger.info(f"已将 JSON 数组转换为 JSONL: {out_path}（{len(arr)} 条用例）")
+        return out_path
+
+    # 视作 JSONL，逐行校验
+    lines = [l for l in text.splitlines() if l.strip()]
+    for i, line in enumerate(lines, 1):
+        try:
+            json.loads(line)
+        except json.JSONDecodeError as e:
+            logger.error(f"JSONL 第 {i} 行解析失败 {input_path}: {e}")
+            sys.exit(1)
+    logger.info(f"测试用例文件已为 JSONL，原样透传: {input_path}（{len(lines)} 条用例）")
+    return input_path
+
+
+def validate_config(config_path: Path) -> None:
+    """确保用户已提供 config.yaml 且 api_key 已替换。"""
+    if not config_path.exists():
+        logger.error(
+            f"未找到配置文件: {config_path}\n"
+            f"请复制 `config.yaml.example` 为 `config.yaml` 并填入真实 api_key 后重试。"
+        )
+        sys.exit(1)
+
+    try:
+        text = config_path.read_text(encoding="utf-8")
+    except OSError as e:
+        logger.error(f"无法读取配置文件 {config_path}: {e}")
+        sys.exit(1)
+
+    if API_KEY_PLACEHOLDER in text:
+        logger.error(
+            f"配置文件 {config_path} 中仍包含占位符 `{API_KEY_PLACEHOLDER}`，请将所有 api_key 替换为真实值后重试。"
+        )
+        sys.exit(1)
+
+
+def cmd_run(args):
+    """run 子命令：准备环境 + 后台执行 AutoTest.batch"""
+    task_dir = Path(args.task_dir).resolve()
+    task_dir.mkdir(parents=True, exist_ok=True)
+    output_dir = Path(args.output_dir).resolve() if args.output_dir else task_dir
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    setup_logging(str(output_dir))
+    logger.info(f"Python: {sys.executable}")
+    logger.info(
+        f"参数: testcases={args.testcases}, hap={args.hap}, bundle={args.bundle_name}, "
+        f"task_dir={task_dir}, category={args.category}, config={args.config}"
+    )
+    logger.info(
+        "前置用例（若有）已并入 testcases，以 case_name 前缀 `[PRE]` 标识；"
+        "self_test_runner 不再单独处理 pre-case。"
+    )
+
+    target_venv = (SCRIPT_DIR / ".venv").resolve()
+    try:
+        Path(sys.executable).resolve().relative_to(target_venv)
+        msg = (
+            f"Refusing to run: this script is executing inside {target_venv}, "
+            f"which it is about to delete and recreate (Windows file locks will leave "
+            f"the venv in a broken state). Invoke with the system Python instead, e.g. "
+            f"`python self_test_runner.py run ...` (NOT `uv run python ...`)."
+        )
+        logger.error(msg)
+        print(json.dumps({"status": "ERROR", "reason": msg}))
+        sys.exit(2)
+    except ValueError:
+        pass
+
+    # 创建本次任务专属子目录 task_<timestamp>，供 status 子命令通过 glob 找到
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    task_subdir = task_dir / f"task_{timestamp}"
+    task_subdir.mkdir(parents=True, exist_ok=True)
+
+    pid_file = task_dir / "batch.pid"
+    stdout_log = task_dir / "batch_stdout.log"
+
+    # 杀掉上次残留进程
+    if pid_file.exists():
+        try:
+            old_pid = int(pid_file.read_text().strip())
+            if _pid_alive(old_pid):
+                cmdline = _get_process_cmdline(old_pid)
+                if cmdline and "AutoTest.batch" in cmdline:
+                    logger.warning(f"杀掉上次残留进程 PID={old_pid}")
+                    _kill_process_tree(old_pid)
+                    time.sleep(2)
+        except (ValueError, OSError):
+            pass
+
+    try:
+        # 在删 venv / 跑 uv 之前先校验 uv 与 config.yaml，避免清理后才发现缺东西
+        uv = get_uv()
+
+        config_path = Path(args.config).resolve() if args.config else (SCRIPT_DIR / "config.yaml")
+        validate_config(config_path)
+        logger.info(f"配置文件: {config_path}")
+
+        cleanup_before_run(force_reinit=args.force_reinit)
+
+        logger.info("=== Step 1: uv sync（确保 harmony-autotest + 传递依赖已安装） ===")
+        run_cmd([uv, "sync"], cwd=str(SCRIPT_DIR), capture_output=True, text=True,
+                encoding="utf-8", timeout=UV_TIMEOUT, env=_uv_env())
+        _stamp_venv()
+
+        hdc = get_hdc()
+
+        logger.info(f"=== Step 2a: uninstall {args.bundle_name} ===")
+        run_cmd([hdc, "uninstall", args.bundle_name], capture_output=True, text=True,
+                encoding="utf-8", timeout=INSTALL_TIMEOUT, check=False)
+
+        logger.info(f"=== Step 2b: install {args.hap} ===")
+        hap = Path(args.hap)
+        if not hap.exists():
+            logger.error(f"hap 不存在: {args.hap}")
+            sys.exit(1)
+        result = run_cmd([hdc, "install", "-r", str(hap)], capture_output=True, text=True,
+                         encoding="utf-8", timeout=INSTALL_TIMEOUT, check=False)
+        if result.returncode == 0 or "successfully" in (result.stdout or ""):
+            logger.info("安装成功")
+            time.sleep(HAP_INSTALL_WAIT)
+        else:
+            logger.error(f"安装失败: {result.stdout}")
+            sys.exit(1)
+
+        # 测试用例规范化：旧 JSON 数组 → JSONL；本身就是 JSONL 透传
+        # 前置用例（若有）已经是 testcases 的第一条，case_name 以 [PRE] 开头
+        testcases_jsonl = _prepare_testcases_jsonl(
+            Path(args.testcases).resolve(), task_subdir,
+        )
+
+        # 构建 AutoTest.batch 命令
+        # `--project SCRIPT_DIR` 让 uv 在任意 cwd 下都能找到正确的 venv；
+        # 而 cwd 设为 task_subdir，hypium_mcp.log / tmp_hypium/ 等中间产物随之落在 task 子目录。
+        cmd = [
+            uv, "run", "--project", str(SCRIPT_DIR), "python", "-m", "AutoTest.batch",
+            "--task-dir", str(task_subdir),
+            "--testcases", str(testcases_jsonl),
+            "--category", args.category,
+            "--work-dir", str(SCRIPT_DIR),
+            "--config", str(config_path),
+        ]
+
+        # 后台启动 AutoTest.batch
+        logger.info("=== Step 3: 后台启动 AutoTest.batch ===")
+        batch_env = os.environ.copy()
+        batch_env["PYTHONIOENCODING"] = "utf-8"
+        batch_env["PYTHONUTF8"] = "1"
+        batch_env["PYTHONUNBUFFERED"] = "1"
+
+        log_fh = open(stdout_log, "w", encoding="utf-8")
+        popen_kwargs = dict(
+            stdin=subprocess.DEVNULL,
+            stdout=log_fh,
+            stderr=subprocess.STDOUT,
+            env=batch_env,
+        )
+        if sys.platform == "win32":
+            # CREATE_NEW_CONSOLE | CREATE_NEW_PROCESS_GROUP — survive parent shell exit
+            popen_kwargs["creationflags"] = 0x00000010 | 0x00000200
+        else:
+            popen_kwargs["start_new_session"] = True
+
+        proc = subprocess.Popen(cmd, cwd=str(task_subdir), **popen_kwargs)
+        pid_file.write_text(str(proc.pid), encoding="utf-8")
+
+        logger.info(f"后台进程 PID={proc.pid}")
+        print(json.dumps({
+            "status": "RUNNING",
+            "pid": proc.pid,
+            "pid_file": str(pid_file),
+            "stdout_log": str(stdout_log),
+            "task_dir": str(task_dir),
+            "task_subdir": str(task_subdir),
+        }))
+
+    except SystemExit:
+        raise
+    except Exception:
+        logger.error(f"异常:\n{traceback.format_exc()}")
+        sys.exit(1)
+
+
+# =============================================================================
+# status 子命令
+# =============================================================================
+
+def _find_task_subdir(task_dir: Path) -> Path | None:
+    candidates = sorted(task_dir.glob("task_*"), key=lambda p: p.name, reverse=True)
+    return candidates[0] if candidates else None
+
+
+def _find_latest_log(output_dir: Path) -> Path | None:
+    candidates = sorted(output_dir.glob("self_test_*.log"), key=lambda p: p.name, reverse=True)
+    candidates += sorted(output_dir.glob("batch_stdout.log"), key=lambda p: p.name, reverse=True)
+    return candidates[0] if candidates else None
+
+
+def _log_status(task_dir: Path, result: dict):
+    log_file = task_dir / "status_history.log"
+    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    log_file.parent.mkdir(parents=True, exist_ok=True)
+    existing = log_file.read_text(encoding="utf-8") if log_file.exists() else ""
+    log_file.write_text(existing + f"[{timestamp}] {json.dumps(result, ensure_ascii=False)}\n", encoding="utf-8")
+
+
+def cmd_status(args):
+    """status 子命令：查询 AutoTest.batch 执行状态"""
+    task_dir = Path(args.task_dir)
+    output_dir = Path(args.output_dir) if args.output_dir else task_dir
+
+    pid_file = task_dir / "batch.pid"
+    if not pid_file.exists():
+        print(json.dumps({"status": "NOT_STARTED"}))
+        sys.exit(4)
+
+    pid = int(pid_file.read_text().strip())
+    alive = _pid_alive(pid)
+
+    task_subdir = _find_task_subdir(task_dir)
+    jsonl_file = task_subdir / "task_results.jsonl" if task_subdir else None
+
+    cases_done = 0
+    last_case = ""
+    if jsonl_file and jsonl_file.exists():
+        lines = jsonl_file.read_text(encoding="utf-8").strip().splitlines()
+        cases_done = len(lines)
+        if lines:
+            last_case = json.loads(lines[-1]).get("case_name", "")
+
+    summary_file = task_subdir / "summary.json" if task_subdir else None
+    has_summary = summary_file and summary_file.exists()
+
+    log_tail = ""
+    log_file = _find_latest_log(output_dir)
+    if log_file and log_file.exists():
+        log_tail = "\n".join(log_file.read_text(encoding="utf-8").strip().splitlines()[-5:])
+
+    if has_summary:
+        summary = json.loads(summary_file.read_text(encoding="utf-8"))
+        result = {
+            "status": "COMPLETED",
+            "pid": pid,
+            "task_subdir": str(task_subdir),
+            "cases_done": summary.get("total_cases", cases_done),
+            "pass_count": summary.get("pass_count", summary.get("success_count", 0)),
+            "fail_count": summary.get("fail_count", 0),
+            "unknown_count": summary.get("unknown_count", 0),
+            "pass_rate": summary.get("pass_rate", 0),
+            "log_tail": log_tail,
+        }
+        print(json.dumps(result))
+        _log_status(task_dir, result)
+        sys.exit(0)
+    elif alive:
+        result = {
+            "status": "RUNNING",
+            "pid": pid,
+            "cases_done": cases_done,
+            "last_case": last_case,
+            "task_subdir": str(task_subdir) if task_subdir else None,
+            "log_tail": log_tail,
+        }
+        print(json.dumps(result))
+        _log_status(task_dir, result)
+        sys.exit(2)
+    else:
+        result = {
+            "status": "CRASHED",
+            "pid": pid,
+            "cases_done": cases_done,
+            "last_case": last_case,
+            "task_subdir": str(task_subdir) if task_subdir else None,
+            "log_tail": log_tail,
+        }
+        print(json.dumps(result))
+        _log_status(task_dir, result)
+        sys.exit(3)
+
+
+# =============================================================================
+# kill 子命令
+# =============================================================================
+
+def cmd_kill(args):
+    """kill 子命令：终止 AutoTest.batch 进程"""
+    task_dir = Path(args.task_dir)
+    pid_file = task_dir / "batch.pid"
+
+    if not pid_file.exists():
+        print(json.dumps({"status": "NO_PID_FILE", "killed": False}))
+        return
+
+    pid = int(pid_file.read_text().strip())
+
+    if not _pid_alive(pid):
+        print(json.dumps({"status": "ALREADY_DEAD", "pid": pid, "killed": False}))
+        return
+
+    cmdline = _get_process_cmdline(pid)
+    if cmdline and "AutoTest.batch" not in cmdline:
+        print(json.dumps({
+            "status": "REFUSED", "pid": pid, "killed": False,
+            "reason": "非 AutoTest.batch 进程", "cmdline": cmdline,
+        }))
+        return
+
+    _kill_process_tree(pid)
+    print(json.dumps({"status": "KILLED", "pid": pid, "killed": True}))
+
+
+# =============================================================================
+# clean 子命令
+# =============================================================================
+
+def cmd_clean(args):
+    """clean 子命令：彻底重置本地状态以便重跑。
+
+    动作：
+      - 杀掉所有残留 AutoTest.batch / hypium_mcp / harmony_autotest 进程
+      - 删除 .venv 及 __pycache__
+      - 删除本目录顶层的 tmp_hypium / hypium_mcp.log / batch.pid / batch_stdout.log
+
+    NOT touched: 全局 uv 缓存。重建缓存需重新从 gitcode 拉 6 个 whl，
+    单纯"重跑一遍"不需要碰它。需要的话用 `uv cache clean` 自己清。
+    """
+    # 控制台输出即可，不写 self_test_*.log（避免污染 output-dir）
+    logging.basicConfig(
+        level=logging.INFO,
+        format="[%(asctime)s] %(levelname)s %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+    logger.setLevel(logging.INFO)
+
+    _kill_stale_processes()
+    _clean_venv()
+    _clean_stale_artifacts(SCRIPT_DIR)
+    print(json.dumps({"status": "CLEANED"}, ensure_ascii=False))
+
+
+# =============================================================================
+# 主入口
+# =============================================================================
+
+def main():
+    parser = argparse.ArgumentParser(description="自测执行器")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # run 子命令
+    p_run = sub.add_parser("run", help="准备环境并执行用例")
+    p_run.add_argument("--testcases", required=True,
+                       help="测试用例文件，JSON 数组或 JSONL，传入 JSON 数组时会自动转换为 JSONL")
+    p_run.add_argument("--hap", required=True, help=".hap 文件")
+    p_run.add_argument("--bundle-name", required=True, help="包名")
+    p_run.add_argument("--task-dir", default="task", help="任务目录（内部会创建 task_<timestamp> 子目录）")
+    p_run.add_argument("--output-dir", default=None, help="日志目录")
+    p_run.add_argument("--category", default=DEFAULT_CATEGORY, help="测试分类名称，传给 AutoTest.batch")
+    p_run.add_argument("--config", default=None,
+                       help="AutoTest 配置文件绝对路径；默认为脚本同目录下的 config.yaml")
+    p_run.add_argument("--force-reinit", action="store_true",
+                       help="强制清理 .venv 并重新 uv sync；默认仅在 pyproject.toml 内容变更时才重建")
+    p_run.set_defaults(func=cmd_run)
+
+    # status 子命令
+    p_status = sub.add_parser("status", help="查询执行状态")
+    p_status.add_argument("--task-dir", required=True)
+    p_status.add_argument("--output-dir", default=None)
+    p_status.set_defaults(func=cmd_status)
+
+    # kill 子命令
+    p_kill = sub.add_parser("kill", help="终止进程")
+    p_kill.add_argument("--task-dir", required=True)
+    p_kill.set_defaults(func=cmd_kill)
+
+    # clean 子命令
+    p_clean = sub.add_parser(
+        "clean",
+        help="重置本地状态（杀残留进程、删 .venv、删本目录残留中间产物），不动全局 uv 缓存",
+    )
+    p_clean.set_defaults(func=cmd_clean)
+
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()