@harmonyos-arkts/d2h 0.1.11 → 0.1.13

package/skills/d2h-hypium-forge/scripts/run_direct.py

@@ -1,823 +1,823 @@
-#!/usr/bin/env python3
-"""
-run_direct.py — 裸 hypium 直跑器（无 devicetest/xdevice 依赖）+ 前置条件分组编排。
-
-编排规则（TD-004 修正：共用前置条件，防交错破坏）：
-  用例文件可声明模块级常量 PRECOND（缺省 'anonymous'）：
-    - 'anonymous'    无状态要求（软启动即可）
-    - 'logged_in'    需登录态（组内软隔离保持 preferences，ensure_login 幂等复用）
-    - 'first_launch' 需首启态（bm clean 破坏性最大，强制排尾，不再破坏后续）
-  执行顺序 = 组序（anonymous → logged_in → first_launch）→ 组内文件名序。
-  组切换打印分隔；results.json 每条附 group 字段（可分组统计）。
-  组首条置 os.environ['FORGE_GROUP_FIRST']='1'（用例可选做完整冷启验证），执行后清除。
-
-用法:
-  单条:  python3 run_direct.py --case F01_func_normal_001 [--dir testcases]
-  批量:  python3 run_direct.py --all [--dir testcases]
-  子串:  python3 run_direct.py --filter TC3 [--dir testcases]   # 跑文件名含 TC3 的用例（保留分组序）
-
-截图与留存（防 reports/ 无限膨胀——Grit 实证 15 轮全量 5266 张/666MB）:
-  --shots fail  默认。PASS 用例仅留 <case>_end.jpeg；过程帧(_pNN)/分步图 仅 FAIL 时保留；
-                连续相同帧自动去重（静态页面 8 帧 → 1 帧）
-  --shots all   全程留存（需逐步回放页面时用）
-  --shots off   完全不截图（纯冒烟）
-  --acceptance  验收模式：强制全量 + 全程截图，目录写 .acceptance 标记独立保护（保留最近 2 次）
-  --keep-reports N  中间(非验收)运行目录保留最近 N 份（默认 0=即用即弃；env FORGE_KEEP_REPORTS）
-  env FORGE_SHOT_MODE  同 --shots（CLI 优先）
-
-要求: 用例 .py 文件含 process_case(d) 顶层函数；或兼容 devicetest 风格（反射 process 方法）。
-结果: 逐条打印 PASS/FAIL + 汇总，写 results.json
-"""
-import argparse
-import hashlib
-import importlib.util
-import json
-import os
-import re
-import sys
-import time
-import traceback
-
-sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
-
-from hypium import UiDriver
-
-# 前置组执行序：破坏性递增（first_launch 会 bm clean，必须排尾）
-GROUP_ORDER = {'anonymous': 0, 'logged_in': 1, 'first_launch': 2}
-
-
-def load_case(path):
-    spec = importlib.util.spec_from_file_location('case_mod', path)
-    mod = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(mod)
-    return mod
-
-
-def case_group(mod):
-    g = str(getattr(mod, 'PRECOND', 'anonymous') or 'anonymous')
-    return g if g in GROUP_ORDER else 'anonymous'
-
-
-def order_files(dir_):
-    """返回 [(filename, group)]，按 组序→文件名 排序；只 import 一次读 PRECOND。"""
-    files = sorted(f for f in os.listdir(dir_) if f.endswith('.py') and not f.startswith('_'))
-    tagged = []
-    for f in files:
-        try:
-            mod = load_case(os.path.join(dir_, f))
-            tagged.append((f, case_group(mod)))
-        except Exception:
-            tagged.append((f, 'anonymous'))  # import 失败留给 run_one 报 FAIL，不在此拦截
-    tagged.sort(key=lambda x: (GROUP_ORDER[x[1]], x[0]))
-    return tagged
-
-
-def _scene_evidence(d, n=8):
-    # FAIL 现场证据: 当前页面 Text 摘要(进 results.msg, 供下轮 LLM 直读省重取证)
-    try:
-        ts = [(c.getText() or '')[:12] for c in (d.find_all_components(BY.type('Text')) or [])]
-        ts = [t for t in ts if t][:n]
-        return ' | 现场Text: ' + '/'.join(ts) if ts else ' | 现场Text: (空)'
-    except Exception:
-        return ''
-
-
-def _file_digest(path):
-    try:
-        return hashlib.sha1(open(path, 'rb').read()).hexdigest()
-    except Exception:
-        return None
-
-
-def _clean_pass_shots(name):
-    """shots=fail 模式：PASS 用例只留 <case>_end.jpeg，删过程帧(_pNN)与分步图(_NN_label)。"""
-    if not SHOT_DIR:
-        return
-    import glob as _g
-    freed = 0
-    for pat in (os.path.join(SHOT_DIR, name + '_p*.jpeg'),
-                os.path.join(SHOT_DIR, name + '_fail.jpeg')):
-        for p in _g.glob(pat):
-            try:
-                freed += os.path.getsize(p)
-                os.remove(p)
-            except OSError:
-                pass
-    for p in _g.glob(os.path.join(SHOT_DIR, name + '_*.jpeg')):
-        base = os.path.basename(p)
-        if re.match(r'^%s_\d{2}_.*\.jpeg$' % re.escape(name), base):  # step_shot 分步图
-            try:
-                freed += os.path.getsize(p)
-                os.remove(p)
-            except OSError:
-                pass
-    if freed:
-        print(f'  [shots] PASS 清理过程帧 {name}: -{freed // 1024}KB')
-
-
-def run_one(d, mod_path, name):
-    mod = load_case(mod_path)
-    t0 = time.time()
-    try:
-        if hasattr(mod, 'process_case'):
-            sampler = None
-            _sample_state = None
-            try:
-                os.environ['FORGE_CASE'] = name
-                if SHOT_DIR:  # 过程采样：每 2.5s 一帧（<case>_pNN.jpeg）；连续相同帧去重（静态页 8 帧→1 帧）
-                    import threading
-                    state = {'n': 0, 'stop': False, 'last': None}
-                    _sample_state = state
-
-                    def _sample():
-                        import time as _t
-                        interval = 3.5 if SHOT_MODE == 'fail' else 2.5  # fail 模式降频，减少 RPC 争抢
-                        while not state['stop']:
-                            _t.sleep(interval)
-                            if state['stop']:
-                                break
-                            try:
-                                p = os.path.join(SHOT_DIR, f"{name}_p{state['n'] + 1:02d}.jpeg")
-                                _shot(d, p, f'proc{state["n"] + 1:02d}')
-                                dg = _file_digest(p)
-                                if dg is not None and dg == state['last']:
-                                    os.remove(p)  # 与上一帧相同（页面静止）→ 不留不计数
-                                else:
-                                    state['last'] = dg
-                                    state['n'] += 1
-                            except Exception:
-                                pass
-                    sampler = threading.Thread(target=_sample, daemon=True)
-                    sampler.start()
-                mod.process_case(d)
-                if SHOT_DIR:
-                    _shot(d, os.path.join(SHOT_DIR, name + '_end.jpeg'), 'end-shot')
-            except Exception as _ex:
-                if SHOT_DIR:
-                    _shot(d, os.path.join(SHOT_DIR, name + '_fail.jpeg'), 'fail-shot')
-                raise type(_ex)(str(_ex) + _scene_evidence(d)) from None
-            finally:
-                _sample_state and _sample_state.__setitem__('stop', True)
-                os.environ.pop('FORGE_CASE', None)
-        else:  # devicetest 风格兜底：实例化伪 TestCase
-            cls = None
-            for attr in dir(mod):
-                obj = getattr(mod, attr)
-                if isinstance(obj, type) and hasattr(obj, 'process') and attr != 'TestCase':
-                    cls = obj
-                    break
-            if cls is None:
-                return name, 'SKIP', 'no process func', 0
-
-            # devicetest TestCase.__init__(TAG, controllers) —— 直跑时跳过基类构造
-            inst = object.__new__(cls)
-            inst.driver = d
-            inst.device1 = d.device if hasattr(d, 'device') else None
-            inst.TAG = name
-            # 直跑跳过 __init__：软断言收集器等实例属性需补默认值
-            if hasattr(cls, '_soft_check') and not hasattr(inst, '_errors'):
-                inst._errors = []
-            # setup 也在 try/finally 内：setup 抛异常时 teardown 仍执行
-            try:
-                if hasattr(cls, 'setup'):
-                    cls.setup(inst)
-                try:
-                    os.environ['FORGE_CASE'] = name  # 分步截图命名用
-                    cls.process(inst)
-                    if SHOT_DIR:
-                        _shot(d, os.path.join(SHOT_DIR, f'{name}_end.jpeg'), 'end-shot')
-                except Exception:
-                    if SHOT_DIR:
-                        _shot(d, os.path.join(SHOT_DIR, f'{name}_fail.jpeg'), 'fail-shot')
-                    raise
-            finally:
-                os.environ.pop('FORGE_CASE', None)
-                if hasattr(cls, 'teardown'):
-                    try:
-                        cls.teardown(inst)
-                    except Exception:
-                        pass
-        return name, 'PASS', '', round(time.time() - t0, 1)
-    except Exception as e:
-        tb = traceback.format_exc().strip().split('\n')
-        msg = f'{e} | {tb[-1][:120] if len(tb) > 1 else ""}'
-        return name, 'FAIL', msg, round(time.time() - t0, 1)
-
-
-SHOT_DIR = None  # 本次运行的截图目录（main 里初始化；None=不截图）
-SHOT_MODE = 'fail'  # fail: PASS 只留 end 帧 | all: 全留 | off: 不截
-
-# TD-LADDER v2 预算：同一修复周期内允许的"显式全量"(--all/--acceptance) 次数；超限须 --force-all。
-# 目的：堵住 --acceptance 被当日常全量跑（Grit 实证：13 次 acceptance 全量 157min，占测试时间 65%）。
-LADDER_FULL_BUDGET = int(os.environ.get('FORGE_FULL_BUDGET', '2'))
-
-
-def _init_shot_dir():
-    global SHOT_DIR
-    if SHOT_MODE == 'off':
-        os.environ.pop('FORGE_SHOT_DIR', None)  # step_shot 由此禁用
-        return
-    import datetime
-    SHOT_DIR = os.path.join('reports', datetime.datetime.now().strftime('%Y-%m-%d'),
-                            datetime.datetime.now().strftime('%H-%M-%S'))
-    os.makedirs(SHOT_DIR, exist_ok=True)
-    os.environ['FORGE_SHOT_DIR'] = SHOT_DIR  # 分步截图（step_shot）读取
-
-
-def _prune_reports(keep, acceptance_keep=2):
-    """截图留存策略：中间(非验收)运行目录即用即弃，验收目录永久保护。
-
-    - 当前运行目录（SHOT_DIR）永不清
-    - 带 .acceptance 标记的验收目录：保留最近 acceptance_keep 次（全程截图证据）
-    - 其余中间运行目录：保留最近 keep 次（默认 0=即用即弃，agent 当轮取证后即回收）"""
-    import glob as _g
-    runs = sorted(_g.glob(os.path.join('reports', '*', '*')),
-                  key=lambda p: os.path.getmtime(p) if os.path.isdir(p) else 0, reverse=True)
-    runs = [r for r in runs if os.path.isdir(r)]
-    pinned = [r for r in runs if os.path.exists(os.path.join(r, '.acceptance'))]
-    regular = [r for r in runs if r not in pinned]
-    doomed = [r for r in regular[keep:] if os.path.abspath(r) != os.path.abspath(SHOT_DIR or '')]
-    doomed += pinned[acceptance_keep:]
-    freed = 0
-    for p in doomed:
-        for dirpath, _dirs, files in os.walk(p):
-            for fn in files:
-                try:
-                    freed += os.path.getsize(os.path.join(dirpath, fn))
-                except OSError:
-                    pass
-        import shutil as _sh
-        _sh.rmtree(p, ignore_errors=True)
-    for dp in _g.glob(os.path.join('reports', '*')):
-        if os.path.isdir(dp) and not os.listdir(dp):
-            os.rmdir(dp)
-    if doomed:
-        print(f'[retention] 中间运行即用即弃: 清理 {len(doomed)} 个旧目录 -{freed // 1048576}MB'
-              f'（验收目录保留 {len(pinned[:acceptance_keep])} 个）')
-
-
-# ---------------- 产品代码变更检测（增量重试回归门禁） ----------------
-# 背景：--retry-failed 只重跑 FAIL/SKIP，PASS 保留原结果；若上一轮之后修改了产品代码
-# （entry/src/main/ets），旧 PASS 可能已回归（实证：Profiles TC09/TC14 PASS→FAIL 靠全量重跑才抓到）。
-# 门禁：结果侧车 results.meta.json 记录 srcHash；增量重试前重算，不一致 → 自动升级为全量重跑。
-
-def _find_src_root():
-    """定位被测工程 entry/src/main/ets：FORGE_SRC_DIR 优先；否则在父/祖父目录的
-    *Ohos|ohos 兄弟工程中，按 forge 目录名令牌匹配（timer-hypium→TimerOhos）；
-    匹配失败且候选不唯一时返回 None（门禁将保守全量，宁可多跑不漏回归）。"""
-    env = os.environ.get('FORGE_SRC_DIR')
-    if env and os.path.isdir(env):
-        return env
-    import re as _re
-    here = os.path.abspath(os.getcwd())
-
-    def _norm(s):
-        s = s.lower()
-        changed = True
-        while changed:
-            changed = False
-            for suf in ('-ohos', 'ohos', '-hypium', 'hypium', '-forge', 'forge', '-migration', 'migration'):
-                if s.endswith(suf) and len(s) > len(suf):
-                    s = s[:-len(suf)]
-                    changed = True
-        return s
-
-    token = _norm(_re.split(r'[-_.]', os.path.basename(here))[0])
-    if token in ('hypium', 'tmp', 'testcases', 'forge', ''):  # <X>-migration/hypium_forge → 用父目录令牌
-        token = _norm(_re.split(r'[-_.]', os.path.basename(os.path.dirname(here)))[0])
-    cands = []  # (src_root, 归一化工程名)
-    for base in (os.path.dirname(here), os.path.dirname(os.path.dirname(here))):
-        if not base or not os.path.isdir(base):
-            continue
-        for d in sorted(os.listdir(base)):
-            if d.endswith('Ohos') or d == 'ohos':
-                cand = os.path.join(base, d, 'entry', 'src', 'main', 'ets')
-                if os.path.isdir(cand):
-                    cands.append((cand, _norm(d)))
-    if not cands:
-        return None
-    if len(cands) == 1:
-        return cands[0][0]
-    for cand, dn in cands:
-        if dn == token or dn.startswith(token) or token.startswith(dn):
-            return cand
-    return None
-
-
-def src_tree_hash():
-    """entry/src/main/ets 下全部 .ets/.ts 内容哈希（排序后串联），产品代码指纹。"""
-    root = _find_src_root()
-    if not root:
-        return None
-    h = hashlib.sha256()
-    for dirpath, dirs, files in os.walk(root):
-        dirs[:] = sorted(d for d in dirs if d not in ('build', 'oh_modules', '.preview'))
-        for fn in sorted(files):
-            if not fn.endswith(('.ets', '.ts')):
-                continue
-            p = os.path.join(dirpath, fn)
-            h.update(os.path.relpath(p, root).encode())
-            try:
-                h.update(open(p, 'rb').read())
-            except OSError:
-                return None
-    return h.hexdigest()[:16]
-
-
-def src_file_hashes():
-    """每个 .ets/.ts 文件内容哈希 {相对路径: hash}——范围回归的变更定位基础。"""
-    root = _find_src_root()
-    if not root:
-        return None
-    out = {}
-    for dirpath, dirs, files in os.walk(root):
-        dirs[:] = sorted(d for d in dirs if d not in ('build', 'oh_modules', '.preview'))
-        for fn in sorted(files):
-            if not fn.endswith(('.ets', '.ts')):
-                continue
-            p = os.path.join(dirpath, fn)
-            try:
-                out[os.path.relpath(p, root)] = hashlib.sha1(open(p, 'rb').read()).hexdigest()[:12]
-            except OSError:
-                return None
-    return out
-
-
-def _meta_path(result_path):
-    return os.path.join(os.path.dirname(os.path.abspath(result_path)) or '.',
-                        'results.meta.json')
-
-
-def _read_prev_meta(result_path):
-    mp = _meta_path(result_path)
-    if os.path.exists(mp):
-        try:
-            return json.load(open(mp, encoding='utf-8'))
-        except Exception:
-            return {}
-    return {}
-
-
-def _read_prev_src_hash(result_path):
-    return _read_prev_meta(result_path).get('srcHash')
-
-
-def _update_ladder_meta(result_path, last_full_hash=None, explicit_full=False, all_pass=False, mode=None):
-    """TD-LADDER v2 预算状态（与 srcHash 记录共存于 results.meta.json）：
-    - last_full_hash: 最近一次"全量"运行的源码指纹（供"源码未变禁重复全量"判定）；
-    - explicit_full: 本轮是否显式全量（--all/--acceptance，不含 --retry-failed 自动升级）→ 计次；
-    - all_pass: 本轮零失败 → 计次归零，开启新修复周期。"""
-    try:
-        mp = _meta_path(result_path)
-        meta = {}
-        if os.path.exists(mp):
-            try:
-                meta = json.load(open(mp, encoding='utf-8'))
-            except Exception:
-                meta = {}
-        if last_full_hash:
-            meta['lastFullSrcHash'] = last_full_hash
-            meta['lastFullTs'] = time.time()
-        if mode:
-            meta['lastMode'] = mode
-        if all_pass:
-            meta['explicitFullCount'] = 0
-        elif explicit_full:
-            meta['explicitFullCount'] = int(meta.get('explicitFullCount') or 0) + 1
-        json.dump(meta, open(mp, 'w', encoding='utf-8'), indent=1)
-    except Exception:
-        pass
-
-
-def _write_src_meta(result_path, src_hash, mode, files=None):
-    if not src_hash:
-        return
-    try:
-        mp = _meta_path(result_path)
-        meta = {'srcHash': src_hash, 'ts': time.time(), 'mode': mode}
-        if files:
-            meta['files'] = files  # 供下轮范围回归 diff（旧 meta 无此键 → 保守全量）
-        json.dump(meta, open(mp, 'w', encoding='utf-8'), indent=1)
-    except Exception:
-        pass
-
-
-# ---------------- 范围回归（touched scope）：改动定位 → 受影响用例子集 ----------------
-# 门禁升级不再非黑即白：产品代码变更时，若改动文件全部是"用例可定位的 UI 文件"
-# （ids.json 键前缀），则只重跑 FAIL/SKIP + 引用了这些文件的用例；其余 PASS 保留。
-# 任一改动文件是共享逻辑（viewmodel/repository/model）或不可定位 → 保守全量。
-# 引用识别不到依赖（纯文本交互）的 PASS 用例保守并入范围；范围超 60% 直接全量。
-
-_STR_LIT = re.compile(r"""['"]([A-Za-z_][A-Za-z0-9_]{2,})['"]""")
-
-
-def _load_id_file_map(ids_path):
-    """ids.json（preinject 产物）{'File:locator': id} → {id: 文件基名(lower)}。"""
-    try:
-        m = json.load(open(ids_path, encoding='utf-8'))
-        return {str(v): str(k).split(':')[0].lower() for k, v in m.items()}
-    except Exception:
-        return None
-
-
-def case_dep_files(path, id2file):
-    """用例源码中引用的 id 字面量 → 依赖 UI 文件基名集合（空集=纯文本交互，无法定位）。"""
-    try:
-        src = open(path, encoding='utf-8').read()
-    except Exception:
-        return None
-    deps = set()
-    for lit in _STR_LIT.findall(src):
-        f = id2file.get(lit)
-        if f:
-            deps.add(f)
-    return deps
-
-
-def plan_touched_scope(changed_rel, id2file, dir_):
-    """返回受影响 UI 文件基名集合；改动越界（非 UI 文件）返回 None=保守全量。"""
-    changed_bases = {os.path.basename(c).rsplit('.', 1)[0].lower() for c in changed_rel}
-    ui_bases = set(id2file.values())
-    if not changed_bases <= ui_bases:
-        return None
-    return changed_bases
-
-
-
-HDC_BIN = '/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains/hdc'
-DEVICE_SN = None  # main() 里从 args.device 赋值
-
-
-def _shot(d, path, label='shot'):
-    """截图（尽力而为，绝不影响结果记录）：d.screenshot 优先，失败走 hdc snapshot_display。"""
-    os.makedirs(os.path.dirname(path) if os.path.dirname(path) else '.', exist_ok=True)
-    try:
-        d.screenshot(path)
-        print(f'  [{label}] {path}')
-        return
-    except Exception:
-        pass
-    try:
-        import subprocess as _sp
-        dev = DEVICE_SN or os.environ.get('FORGE_DEVICE', '127.0.0.1:5555')
-        remote = f'/data/local/tmp/_forge_shot.jpeg'
-        _sp.run([HDC_BIN, '-t', dev, 'shell', 'snapshot_display', '-f', remote],
-                capture_output=True, timeout=10)
-        _sp.run([HDC_BIN, '-t', dev, 'file', 'recv', remote, path],
-                capture_output=True, timeout=15)
-        _sp.run([HDC_BIN, '-t', dev, 'shell', 'rm', '-f', remote],
-                capture_output=True, timeout=5)
-        print(f'  [{label}] {path} (hdc)')
-    except Exception as exc:
-        print(f'  [{label}] 不可用: {exc}')
-
-
-def main():
-    ap = argparse.ArgumentParser()
-    ap.add_argument('--case', default=None)
-    ap.add_argument('--all', action='store_true')
-    ap.add_argument('--dir', default='testcases')
-    ap.add_argument('--device', default='127.0.0.1:5555')
-    ap.add_argument('--retry-failed', action='store_true',
-                    help='增量重试：只重跑 results.json 中 FAIL/SKIP 条（PASS 保留原结果，合并写出）；'
-                         '产品代码(entry/src/main/ets)较上轮有变更时自动升级为全量重跑')
-    ap.add_argument('--force-incremental', action='store_true',
-                    help='跳过产品代码变更门禁，强制增量（仅测试脚本变更时使用）')
-    ap.add_argument('--regression-scope', choices=('touched', 'full'), default=None,
-                    help='产品代码变更时的回归范围: touched=FAIL/SKIP+引用改动UI文件的用例(默认) | full=全量'
-                         '（env FORGE_REGRESSION_SCOPE 同义；改动含共享逻辑文件时 touched 自动退化为 full）')
-    ap.add_argument('--cold', action='store_true',
-                    help='--case 单条验证时强制冷启（默认热启动软复用，省 8-12s；断言冷启行为时用）')
-    ap.add_argument('--case-timeout', type=int, default=240,
-                    help='单用例看门狗秒数（默认 240，超时记 FAIL 继续下一条，防挂死烧设备时间；0=关闭）')
-    ap.add_argument('--flake-retry', type=int, default=1,
-                    help='瞬态失败（watchdog/连接类）轮末自动复测次数（默认 1，省一轮 agent 往返；0=关闭）')
-    ap.add_argument('--filter', default=None,
-                    help='子串过滤用例文件名（保留分组序），如 --filter TC3 跑 TC30/TC31/TC35')
-    ap.add_argument('--shots', choices=('fail', 'all', 'off'), default=None,
-                    help='截图策略: fail=PASS只留end帧/FAIL留全过程(默认) | all=全程留存 | off=不截')
-    ap.add_argument('--keep-reports', type=int, default=None,
-                    help='中间(非验收)运行目录保留最近 N 份（默认 0=即用即弃，当轮取证后即回收；'
-                         'env FORGE_KEEP_REPORTS）。验收目录(.acceptance)不受此限制，独立保留最近 2 次')
-    ap.add_argument('--force-all', action='store_true',
-                    help='跳过修复轮 --all 防护（仅限确有必要的全量场景；正常流程: --case 单条 → '
-                         '--retry-failed 增量 → --acceptance 终局验收）')
-    ap.add_argument('--acceptance', action='store_true',
-                    help='验收模式：强制全量 + 全程截图(--shots all，显式传 --shots 时以显式为准)，'
-                         '结果目录写入 .acceptance 标记——prune 永不清理最近的验收目录（保留最近 2 次），'
-                         '作为最终质量门的完整截图证据')
-    args = ap.parse_args()
-    # 阶梯防护 v2（TD-LADDER）：所有"显式全量"（--all / --acceptance / 变相全量的 --filter）统一受管。
-    #   R1 上轮有 FAIL/SKIP                    → 必须先修（--case/--retry-failed），禁止全量；
-    #   R2/R2b 源码未变且已全量过                → 重复全量无新结论；--acceptance 仅当"上次也是同源验收"才拦；
-    #   R3 本周期显式全量已达上限                → 见 LADDER_FULL_BUDGET；
-    #   L2 零进展（连续两轮失败签名一致且源码未变）→ 拒绝重跑，必须先 probe 定案改码。
-    # 免检：--retry-failed 因源码变更自动升级的全量（非显式，不占预算）；--force-all 逃生。
-    _prev_path = os.path.join(os.path.abspath(args.dir), '..', 'results.json')
-    _prev_res, _meta = None, {}
-    if os.path.exists(_prev_path):
-        try:
-            _prev_res = json.load(open(_prev_path, encoding='utf-8'))
-        except Exception:
-            _prev_res = None
-        _meta = _read_prev_meta(_prev_path)
-    _pending = [str(r.get('case', '?')) for r in (_prev_res or [])
-                if r.get('status') in ('FAIL', 'SKIP')]
-    _cur_hash = src_tree_hash()
-    _last_full_hash = _meta.get('lastFullSrcHash')
-    _full_count = int(_meta.get('explicitFullCount') or 0)
-
-    # L1：--filter 覆盖超半数用例 = 变相全量，按显式全量纳管
-    _filter_full = False
-    if args.filter:
-        try:
-            _all_files = order_files(args.dir)
-            _hit = [f for f, _g in _all_files if args.filter in f]
-            _filter_full = bool(_all_files) and len(_hit) > max(5, int(len(_all_files) * 0.25))
-            if _filter_full:
-                print(f'ℹ --filter "{args.filter}" 覆盖 {len(_hit)}/{len(_all_files)} 条（>25% 且 >5）= 变相全量，按全量纳管')
-        except Exception:
-            _filter_full = False
-
-    def _ladder_block(reason):
-        print('⛔ 阶梯防护：拒绝显式全量（--all / --acceptance / 变相 --filter）')
-        print(f'   原因：{reason}')
-        print('   ▶ 单条验证: --case <失败用例>')
-        print('   ▶ 增量重跑: --retry-failed（源码变更时按 srcHash 自动收窄/升级）')
-        print('   ▶ 全绿后再做 终局验收: --acceptance（证据留档，全程截图）')
-        print('   ▶ 确有必要的一次性全量: --force-all（跳过防护，自担"无进展"风险）')
-        sys.exit(2)
-
-    explicit_full = (args.all or args.acceptance or _filter_full) and not args.force_all
-    if explicit_full:
-        _reason = None
-        if _pending:
-            _reason = (f'上轮 results.json 尚有 {len(_pending)} 条 FAIL/SKIP：'
-                       + '、'.join(_pending[:6]) + (' …' if len(_pending) > 6 else ''))
-        elif (not args.acceptance) and _cur_hash and _last_full_hash == _cur_hash:
-            _reason = '源码自上次全量以来未变化（srcHash 相同），重复全量不会得到新结论'
-        elif (args.acceptance and _meta.get('lastMode') == 'acceptance'
-              and _cur_hash and _last_full_hash == _cur_hash):
-            _reason = '上次已是同源验收（srcHash 相同），无需重复验收'
-        elif _full_count >= LADDER_FULL_BUDGET:
-            _reason = f'本修复周期显式全量已达 {_full_count} 次（上限 {LADDER_FULL_BUDGET}）'
-        if _reason:
-            _ladder_block(_reason)
-
-    # L2：零进展硬阻断——连续两轮失败签名一致且源码未变时，重跑（增量/全量）必然同样失败。
-    if not args.force_all and not args.case and _cur_hash and _pending \
-            and _meta.get('srcHash') == _cur_hash:
-        _prev_prev = os.path.join(os.path.abspath(args.dir), '..', 'results.prev.json')
-        if os.path.exists(_prev_prev):
-            try:
-                _pp = json.load(open(_prev_prev, encoding='utf-8'))
-
-                def _failsig(lst):
-                    return sorted({(r.get('msg') or '').split(' | ')[0][:60]
-                                   for r in lst if r.get('status') == 'FAIL'})
-
-                if _failsig(_pp) and _failsig(_pp) == _failsig(_prev_res or []):
-                    print('⛔ 阶梯防护（L2 零进展）：连续两轮失败签名集完全一致，且源码未变化。')
-                    print('   重复重跑必然同样失败——请先用 probe.py（tree/hilog/db-pull）定案并修改代码。')
-                    print('   确需强跑: --force-all')
-                    sys.exit(2)
-            except Exception:
-                pass
-    global DEVICE_SN, SHOT_MODE
-    DEVICE_SN = args.device
-    SHOT_MODE = args.shots or os.environ.get('FORGE_SHOT_MODE', 'fail')
-    if args.acceptance:
-        args.all = True  # 验收=强制全量
-        if not args.shots:
-            SHOT_MODE = 'all'  # 验收全程截图（显式 --shots 优先）
-        print('═══ 验收模式: 全量 + 全程截图 + .acceptance 标记（prune 保护） ═══')
-    if SHOT_MODE not in ('fail', 'all', 'off'):
-        SHOT_MODE = 'fail'
-    os.environ['FORGE_SHOT_MODE'] = SHOT_MODE  # step_shot(_common) 同步感知 off
-    keep_reports = args.keep_reports if args.keep_reports is not None else int(
-        os.environ.get('FORGE_KEEP_REPORTS', '0') or 0)
-    sys.path.insert(0, os.path.abspath(args.dir))
-
-    if args.case:
-        ordered = [(f'{args.case}.py', 'anonymous')]
-    elif args.retry_failed:
-        prev = os.path.join(os.path.abspath(args.dir), '..', 'results.json')
-        if not os.path.exists(prev):
-            print('--retry-failed 需要 results.json'); sys.exit(1)
-        # ---- 回归门禁：产品代码变更 → 全量 或 范围回归（touched，TD-019+）----
-        cur_hash = src_tree_hash()
-        if not args.force_incremental:
-            prev_hash = _read_prev_src_hash(prev)
-            if cur_hash is None:
-                print('⚠ 未定位到 entry/src/main/ets（可用 FORGE_SRC_DIR 指定），无法判定产品代码变更 → 保守全量重跑')
-                args.all = True
-            elif prev_hash is None:
-                print('⚠ results.meta.json 无上轮 srcHash 记录（旧版产物）→ 保守全量重跑（本轮后建立指纹）')
-                args.all = True
-            elif cur_hash != prev_hash:
-                scope_mode = (args.regression_scope
-                              or os.environ.get('FORGE_REGRESSION_SCOPE') or 'touched')
-                touched = None
-                if scope_mode == 'touched':
-                    prev_files = _read_prev_meta(prev).get('files')
-                    cur_files = src_file_hashes()
-                    if prev_files and cur_files:
-                        changed_rel = {r for r in cur_files if prev_files.get(r) != cur_files[r]}
-                        changed_rel |= set(prev_files) - set(cur_files)  # 删除/改名也算
-                        ids_path = os.path.join(os.path.dirname(os.path.abspath(prev)), 'ids.json')
-                        id2file = _load_id_file_map(ids_path)
-                        if id2file is not None and changed_rel:
-                            touched = plan_touched_scope(changed_rel, id2file, args.dir)
-                            globals()['_ID2FILE'] = id2file
-                if touched:
-                    print(f'⚡ 产品代码变更限于 UI 文件 {sorted(touched)} → 范围回归: '
-                          f'FAIL/SKIP + 引用这些文件的用例（其余 PASS 保留）')
-                    globals()['_SCOPE_BASES'] = touched
-                else:
-                    print(f'⚠ 产品代码已变更（srcHash {prev_hash} → {cur_hash}）：改动含共享/不可定位文件 '
-                          f'→ 自动升级为全量重跑（改单页时可检查 ids.json 覆盖；强制收窄 --regression-scope touched）')
-                    args.all = True
-        prev_res = {str(r.get('case')).split('_')[0]: r
-                    for r in json.load(open(prev, encoding='utf-8'))}
-        all_ordered = order_files(args.dir)
-        if args.all:  # 门禁升级为全量：不保留旧 PASS
-            ordered = all_ordered
-            print(f'全量重跑（产品代码变更门禁）: {len(ordered)} 条')
-        else:
-            ordered = [(f, g) for f, g in all_ordered
-                       if f[:-3].split('_')[0] not in prev_res
-                       or prev_res[f[:-3].split('_')[0]].get('status') != 'PASS']
-            scope_bases = globals().get('_SCOPE_BASES')
-            if scope_bases:  # touched：并入"引用改动文件的 PASS 用例"（无依赖的保守并入）
-                id2file = globals().get('_ID2FILE') or {}
-                extra, ambiguous = [], 0
-                for f, g in all_ordered:
-                    cid = f[:-3].split('_')[0]
-                    if cid in prev_res and prev_res[cid].get('status') == 'PASS':
-                        deps = case_dep_files(os.path.join(args.dir, f), id2file)
-                        if deps is None or not deps or (deps & scope_bases):
-                            if deps is None or not deps:
-                                ambiguous += 1
-                            extra.append((f, g))
-                if len(ordered) + len(extra) > max(3, int(len(all_ordered) * 0.6)):
-                    print(f'⚠ 范围回归覆盖 {len(ordered) + len(extra)}/{len(all_ordered)} 条（含无依赖 {ambiguous}）'
-                          f'→ 超过 60% 阈值，升级全量')
-                    ordered = all_ordered
-                    args.all = True
-                else:
-                    ordered = ordered + extra
-                    ordered.sort(key=lambda x: (GROUP_ORDER[x[1]], x[0]))
-                    print(f'范围回归: FAIL/SKIP+受影响 {len(ordered)} 条（含无依赖纯文本用例 {ambiguous}，保守并入）')
-            keep = [prev_res[f[:-3].split('_')[0]] for f, g in all_ordered
-                    if f[:-3].split('_')[0] in prev_res
-                    and prev_res[f[:-3].split('_')[0]].get('status') == 'PASS'
-                    and (f, g) not in ordered]
-            print(f'增量重试: 重跑 {len(ordered)} 条 / 保留 PASS {len(keep)} 条')
-            globals()['_RETRY_KEEP'] = keep
-    elif args.all or args.filter:
-        ordered = order_files(args.dir)
-        if args.filter:
-            ordered = [(f, g) for f, g in ordered if args.filter in f]
-            if not ordered:
-                print(f'--filter "{args.filter}" 无匹配用例'); sys.exit(1)
-    else:
-        print('指定 --case X / --all / --retry-failed / --filter'); sys.exit(1)
-
-    _init_shot_dir()
-    os.environ['FORGE_DEVICE'] = args.device   # launch(want/reset) 的 hdc 透传用
-
-    d = UiDriver.connect(device_sn=args.device)
-    import signal
-
-    def _watchdog_arm(sec):
-        if sec and hasattr(signal, 'SIGALRM'):
-            def _handler(signum, frame):
-                raise TimeoutError(f'case watchdog {sec}s')
-            signal.signal(signal.SIGALRM, _handler)
-            signal.alarm(sec)
-
-    def _watchdog_disarm():
-        if hasattr(signal, 'SIGALRM'):
-            signal.alarm(0)
-
-    results = []
-    cur_group = None
-    first_in_group = True
-    for f, grp in ordered:
-        name = f[:-3]
-        if grp != cur_group:  # 组切换：首启组排尾，此前组状态不被回头破坏
-            cur_group = grp
-            first_in_group = True
-            print(f'\n────── 前置组 [{grp}] 开始（{grp} 组内软隔离共享前置）──────', flush=True)
-            os.environ['FORGE_GROUP_FIRST'] = '1'
-        # 热启动：组内非首条且锚已在位时 launch() 软复用当前会话（省冷启 8-12s/例）；
-        # first_launch 组（bm clean）与组首条（冷启验证）保持冷启；
-        # --case 单条验证默认热启动（--cold 强制冷启）
-        warm = (grp in ('anonymous', 'logged_in') and not first_in_group) or \
-               (args.case and not args.cold and grp != 'first_launch')
-        if warm:
-            os.environ['FORGE_WARM_LAUNCH'] = '1'
-        else:
-            os.environ.pop('FORGE_WARM_LAUNCH', None)
-        print(f'▶ {name} ...', flush=True)
-        _watchdog_arm(args.case_timeout)
-        try:
-            n, status, msg, dur = run_one(d, os.path.join(args.dir, f), name)
-        except TimeoutError as te:
-            n, status, msg, dur = name, 'FAIL', f'{te}（挂死截断，已跳下一条）', round(time.time(), 0)
-        finally:
-            _watchdog_disarm()
-        os.environ.pop('FORGE_GROUP_FIRST', None)
-        first_in_group = False
-        print(f'  {status} ({dur}s) {msg[:110]}', flush=True)
-        if status == 'PASS' and SHOT_MODE == 'fail':
-            _clean_pass_shots(name)  # PASS 只留 end 帧，FAIL 保留全过程证据
-        results.append({'case': n, 'status': status, 'msg': msg, 'dur': dur, 'group': grp})
-        time.sleep(0.5)  # launch 自带落座等待，长睡交给用例前置
-
-    # ---- 瞬态失败轮末复测：watchdog/连接类抖动当场再跑一次，PASS 记 flake-retry ----
-    # （省一轮"agent 读结果→重跑全量"往返；断言类失败不自动复测，防掩盖真缺陷）
-    if args.flake_retry > 0:
-        TRANSIENT = re.compile(r'watchdog|connector|Fail to get device|device disconnect|TimeoutError', re.I)
-        for r in list(results):
-            if r['status'] == 'FAIL' and TRANSIENT.search(r.get('msg', '')):
-                print(f'▶ {r["case"]} 瞬态失败特征，轮末复测...', flush=True)
-                os.environ.pop('FORGE_WARM_LAUNCH', None)  # 复测走完整冷启（连接类抖动需重连）
-                _watchdog_arm(args.case_timeout)
-                try:
-                    n2, st2, msg2, dur2 = run_one(d, os.path.join(args.dir, r['case'] + '.py'), r['case'])
-                except TimeoutError as te:
-                    n2, st2, msg2, dur2 = r['case'], 'FAIL', str(te), 0
-                finally:
-                    _watchdog_disarm()
-                if st2 == 'PASS':
-                    r.update({'status': 'PASS',
-                              'msg': f'flake-retry 二跑 PASS（首跑: {r["msg"][:60]}）',
-                              'dur': round(r['dur'] + dur2, 1)})
-                    print(f'  PASS(2nd) {r["case"]}', flush=True)
-                else:
-                    r['msg'] = f'{r["msg"]} | 复测仍失败: {msg2[:60]}'
-
-    results = globals().get('_RETRY_KEEP', []) + results
-    p = sum(1 for r in results if r['status'] == 'PASS')
-    f_ = sum(1 for r in results if r['status'] == 'FAIL')
-    print(f'\n══════ 直跑汇总: PASS={p} FAIL={f_} SKIP={len(results)-p-f_} / {len(results)} ══════')
-    from collections import Counter
-    print('分组: ' + ', '.join(f'{g}={c}' for g, c in Counter(r['group'] for r in results).items()))
-    # 同族错误聚类（分诊三律①：同消息视为同族，一次定案禁逐条实验）
-    fails = [r for r in results if r['status'] == 'FAIL']
-    if fails:
-        import re as _re
-        def _sig(m):
-            head = (m or '').split(' | ')[0]
-            return _re.sub(r'[:：].+', ': X', head)[:60]
-        clus = Counter(_sig(r.get('msg')) for r in fails)
-        print('同族聚类: ' + ' ; '.join(f'{c}×[{k}]' for k, c in clus.most_common(4)))
-    out = 'results.json' if (args.all or args.retry_failed) else 'results-%s.json' % (args.case or 'single').split('_')[0]
-    # ---- 零进展检测：失败签名集与上一轮完全一致 → 修复未生效，重跑必复现 ----
-    # （Grit 实证泥潭：taskSaveButton 同族失败连卡 5 轮全量 71min。触发即亮牌，
-    #  agent 应停止重跑、转 probe.py/hilog 定案——分诊三律② 同族定案实验 ≤2 次）
-    if fails and os.path.exists(out):
-        try:
-            prev_list = json.load(open(out, encoding='utf-8'))
-
-            def _sigset(lst):
-                from collections import Counter as _C
-                return _C(re.sub(r'[:：].+', '', (r.get('msg') or '')).split(' | ')[0][:60]
-                          for r in lst if r.get('status') == 'FAIL')
-
-            if _sigset(prev_list) and _sigset(prev_list) == _sigset(results):
-                print('\n⚠⚠ 零进展警告: 失败签名集与上一轮完全一致（'
-                      + ', '.join(f'{c}×{k}' for k, c in _sigset(results).most_common(3))
-                      + '）——修复未生效，重复重跑必然同样失败。'
-                        '停止重跑，用 probe.py（tree/hilog/db-pull）定案后改代码，再回来跑。')
-        except Exception:
-            pass
-    if os.path.exists(out):  # 修复轮重跑前保留上一轮原始记录（自愈边界：修≠覆盖历史）
-        import shutil as _sh
-        _sh.copy(out, out.replace('.json', '.prev.json'))
-    json.dump(results, open(out, 'w', encoding='utf-8'), ensure_ascii=False, indent=1)
-    if args.all or args.retry_failed:  # 全量/合并结果写入后记录产品代码指纹（供下轮增量门禁/范围回归比对）
-        _cur_src_hash = src_tree_hash()
-        _mode = 'acceptance' if args.acceptance else ('full' if args.all else 'retry')
-        _write_src_meta(out, _cur_src_hash, _mode, files=src_file_hashes())
-        _update_ladder_meta(out, last_full_hash=(_cur_src_hash if args.all else None),
-                            explicit_full=explicit_full, all_pass=(f_ == 0), mode=_mode)
-    if args.acceptance and SHOT_DIR:  # 验收目录打标：prune 独立保护，全程截图永久留存
-        try:
-            json.dump({'ts': time.time(), 'total': len(results), 'pass': p, 'fail': f_,
-                       'srcHash': _read_prev_src_hash(out) or ''},
-                      open(os.path.join(SHOT_DIR, '.acceptance'), 'w', encoding='utf-8'), indent=1)
-            print(f'[acceptance] 验收证据目录已保护: {SHOT_DIR}（PASS={p} FAIL={f_}）')
-        except Exception:
-            pass
-    print('明细: ' + out)
-    if fails and not args.retry_failed:  # 阶梯重跑提示（防修复后无脑 --all 空转设备时间）
-        first_fail = fails[0]['case']
-        print(f'\n▶ 下一步（重跑阶梯，禁直接 --all）: '
-              f'先 `--case {first_fail}` 验证修复 → 再 `--retry-failed`（改过产品代码会自动升级全量）')
-    _prune_reports(keep_reports)
-
-
-if __name__ == '__main__':
-    main()
+#!/usr/bin/env python3
+"""
+run_direct.py — 裸 hypium 直跑器（无 devicetest/xdevice 依赖）+ 前置条件分组编排。
+
+编排规则（TD-004 修正：共用前置条件，防交错破坏）：
+  用例文件可声明模块级常量 PRECOND（缺省 'anonymous'）：
+    - 'anonymous'    无状态要求（软启动即可）
+    - 'logged_in'    需登录态（组内软隔离保持 preferences，ensure_login 幂等复用）
+    - 'first_launch' 需首启态（bm clean 破坏性最大，强制排尾，不再破坏后续）
+  执行顺序 = 组序（anonymous → logged_in → first_launch）→ 组内文件名序。
+  组切换打印分隔；results.json 每条附 group 字段（可分组统计）。
+  组首条置 os.environ['FORGE_GROUP_FIRST']='1'（用例可选做完整冷启验证），执行后清除。
+
+用法:
+  单条:  python3 run_direct.py --case F01_func_normal_001 [--dir testcases]
+  批量:  python3 run_direct.py --all [--dir testcases]
+  子串:  python3 run_direct.py --filter TC3 [--dir testcases]   # 跑文件名含 TC3 的用例（保留分组序）
+
+截图与留存（防 reports/ 无限膨胀——Grit 实证 15 轮全量 5266 张/666MB）:
+  --shots fail  默认。PASS 用例仅留 <case>_end.jpeg；过程帧(_pNN)/分步图 仅 FAIL 时保留；
+                连续相同帧自动去重（静态页面 8 帧 → 1 帧）
+  --shots all   全程留存（需逐步回放页面时用）
+  --shots off   完全不截图（纯冒烟）
+  --acceptance  验收模式：强制全量 + 全程截图，目录写 .acceptance 标记独立保护（保留最近 2 次）
+  --keep-reports N  中间(非验收)运行目录保留最近 N 份（默认 0=即用即弃；env FORGE_KEEP_REPORTS）
+  env FORGE_SHOT_MODE  同 --shots（CLI 优先）
+
+要求: 用例 .py 文件含 process_case(d) 顶层函数；或兼容 devicetest 风格（反射 process 方法）。
+结果: 逐条打印 PASS/FAIL + 汇总，写 results.json
+"""
+import argparse
+import hashlib
+import importlib.util
+import json
+import os
+import re
+import sys
+import time
+import traceback
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from hypium import UiDriver
+
+# 前置组执行序：破坏性递增（first_launch 会 bm clean，必须排尾）
+GROUP_ORDER = {'anonymous': 0, 'logged_in': 1, 'first_launch': 2}
+
+
+def load_case(path):
+    spec = importlib.util.spec_from_file_location('case_mod', path)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def case_group(mod):
+    g = str(getattr(mod, 'PRECOND', 'anonymous') or 'anonymous')
+    return g if g in GROUP_ORDER else 'anonymous'
+
+
+def order_files(dir_):
+    """返回 [(filename, group)]，按 组序→文件名 排序；只 import 一次读 PRECOND。"""
+    files = sorted(f for f in os.listdir(dir_) if f.endswith('.py') and not f.startswith('_'))
+    tagged = []
+    for f in files:
+        try:
+            mod = load_case(os.path.join(dir_, f))
+            tagged.append((f, case_group(mod)))
+        except Exception:
+            tagged.append((f, 'anonymous'))  # import 失败留给 run_one 报 FAIL，不在此拦截
+    tagged.sort(key=lambda x: (GROUP_ORDER[x[1]], x[0]))
+    return tagged
+
+
+def _scene_evidence(d, n=8):
+    # FAIL 现场证据: 当前页面 Text 摘要(进 results.msg, 供下轮 LLM 直读省重取证)
+    try:
+        ts = [(c.getText() or '')[:12] for c in (d.find_all_components(BY.type('Text')) or [])]
+        ts = [t for t in ts if t][:n]
+        return ' | 现场Text: ' + '/'.join(ts) if ts else ' | 现场Text: (空)'
+    except Exception:
+        return ''
+
+
+def _file_digest(path):
+    try:
+        return hashlib.sha1(open(path, 'rb').read()).hexdigest()
+    except Exception:
+        return None
+
+
+def _clean_pass_shots(name):
+    """shots=fail 模式：PASS 用例只留 <case>_end.jpeg，删过程帧(_pNN)与分步图(_NN_label)。"""
+    if not SHOT_DIR:
+        return
+    import glob as _g
+    freed = 0
+    for pat in (os.path.join(SHOT_DIR, name + '_p*.jpeg'),
+                os.path.join(SHOT_DIR, name + '_fail.jpeg')):
+        for p in _g.glob(pat):
+            try:
+                freed += os.path.getsize(p)
+                os.remove(p)
+            except OSError:
+                pass
+    for p in _g.glob(os.path.join(SHOT_DIR, name + '_*.jpeg')):
+        base = os.path.basename(p)
+        if re.match(r'^%s_\d{2}_.*\.jpeg$' % re.escape(name), base):  # step_shot 分步图
+            try:
+                freed += os.path.getsize(p)
+                os.remove(p)
+            except OSError:
+                pass
+    if freed:
+        print(f'  [shots] PASS 清理过程帧 {name}: -{freed // 1024}KB')
+
+
+def run_one(d, mod_path, name):
+    mod = load_case(mod_path)
+    t0 = time.time()
+    try:
+        if hasattr(mod, 'process_case'):
+            sampler = None
+            _sample_state = None
+            try:
+                os.environ['FORGE_CASE'] = name
+                if SHOT_DIR:  # 过程采样：每 2.5s 一帧（<case>_pNN.jpeg）；连续相同帧去重（静态页 8 帧→1 帧）
+                    import threading
+                    state = {'n': 0, 'stop': False, 'last': None}
+                    _sample_state = state
+
+                    def _sample():
+                        import time as _t
+                        interval = 3.5 if SHOT_MODE == 'fail' else 2.5  # fail 模式降频，减少 RPC 争抢
+                        while not state['stop']:
+                            _t.sleep(interval)
+                            if state['stop']:
+                                break
+                            try:
+                                p = os.path.join(SHOT_DIR, f"{name}_p{state['n'] + 1:02d}.jpeg")
+                                _shot(d, p, f'proc{state["n"] + 1:02d}')
+                                dg = _file_digest(p)
+                                if dg is not None and dg == state['last']:
+                                    os.remove(p)  # 与上一帧相同（页面静止）→ 不留不计数
+                                else:
+                                    state['last'] = dg
+                                    state['n'] += 1
+                            except Exception:
+                                pass
+                    sampler = threading.Thread(target=_sample, daemon=True)
+                    sampler.start()
+                mod.process_case(d)
+                if SHOT_DIR:
+                    _shot(d, os.path.join(SHOT_DIR, name + '_end.jpeg'), 'end-shot')
+            except Exception as _ex:
+                if SHOT_DIR:
+                    _shot(d, os.path.join(SHOT_DIR, name + '_fail.jpeg'), 'fail-shot')
+                raise type(_ex)(str(_ex) + _scene_evidence(d)) from None
+            finally:
+                _sample_state and _sample_state.__setitem__('stop', True)
+                os.environ.pop('FORGE_CASE', None)
+        else:  # devicetest 风格兜底：实例化伪 TestCase
+            cls = None
+            for attr in dir(mod):
+                obj = getattr(mod, attr)
+                if isinstance(obj, type) and hasattr(obj, 'process') and attr != 'TestCase':
+                    cls = obj
+                    break
+            if cls is None:
+                return name, 'SKIP', 'no process func', 0
+
+            # devicetest TestCase.__init__(TAG, controllers) —— 直跑时跳过基类构造
+            inst = object.__new__(cls)
+            inst.driver = d
+            inst.device1 = d.device if hasattr(d, 'device') else None
+            inst.TAG = name
+            # 直跑跳过 __init__：软断言收集器等实例属性需补默认值
+            if hasattr(cls, '_soft_check') and not hasattr(inst, '_errors'):
+                inst._errors = []
+            # setup 也在 try/finally 内：setup 抛异常时 teardown 仍执行
+            try:
+                if hasattr(cls, 'setup'):
+                    cls.setup(inst)
+                try:
+                    os.environ['FORGE_CASE'] = name  # 分步截图命名用
+                    cls.process(inst)
+                    if SHOT_DIR:
+                        _shot(d, os.path.join(SHOT_DIR, f'{name}_end.jpeg'), 'end-shot')
+                except Exception:
+                    if SHOT_DIR:
+                        _shot(d, os.path.join(SHOT_DIR, f'{name}_fail.jpeg'), 'fail-shot')
+                    raise
+            finally:
+                os.environ.pop('FORGE_CASE', None)
+                if hasattr(cls, 'teardown'):
+                    try:
+                        cls.teardown(inst)
+                    except Exception:
+                        pass
+        return name, 'PASS', '', round(time.time() - t0, 1)
+    except Exception as e:
+        tb = traceback.format_exc().strip().split('\n')
+        msg = f'{e} | {tb[-1][:120] if len(tb) > 1 else ""}'
+        return name, 'FAIL', msg, round(time.time() - t0, 1)
+
+
+SHOT_DIR = None  # 本次运行的截图目录（main 里初始化；None=不截图）
+SHOT_MODE = 'fail'  # fail: PASS 只留 end 帧 | all: 全留 | off: 不截
+
+# TD-LADDER v2 预算：同一修复周期内允许的"显式全量"(--all/--acceptance) 次数；超限须 --force-all。
+# 目的：堵住 --acceptance 被当日常全量跑（Grit 实证：13 次 acceptance 全量 157min，占测试时间 65%）。
+LADDER_FULL_BUDGET = int(os.environ.get('FORGE_FULL_BUDGET', '2'))
+
+
+def _init_shot_dir():
+    global SHOT_DIR
+    if SHOT_MODE == 'off':
+        os.environ.pop('FORGE_SHOT_DIR', None)  # step_shot 由此禁用
+        return
+    import datetime
+    SHOT_DIR = os.path.join('reports', datetime.datetime.now().strftime('%Y-%m-%d'),
+                            datetime.datetime.now().strftime('%H-%M-%S'))
+    os.makedirs(SHOT_DIR, exist_ok=True)
+    os.environ['FORGE_SHOT_DIR'] = SHOT_DIR  # 分步截图（step_shot）读取
+
+
+def _prune_reports(keep, acceptance_keep=2):
+    """截图留存策略：中间(非验收)运行目录即用即弃，验收目录永久保护。
+
+    - 当前运行目录（SHOT_DIR）永不清
+    - 带 .acceptance 标记的验收目录：保留最近 acceptance_keep 次（全程截图证据）
+    - 其余中间运行目录：保留最近 keep 次（默认 0=即用即弃，agent 当轮取证后即回收）"""
+    import glob as _g
+    runs = sorted(_g.glob(os.path.join('reports', '*', '*')),
+                  key=lambda p: os.path.getmtime(p) if os.path.isdir(p) else 0, reverse=True)
+    runs = [r for r in runs if os.path.isdir(r)]
+    pinned = [r for r in runs if os.path.exists(os.path.join(r, '.acceptance'))]
+    regular = [r for r in runs if r not in pinned]
+    doomed = [r for r in regular[keep:] if os.path.abspath(r) != os.path.abspath(SHOT_DIR or '')]
+    doomed += pinned[acceptance_keep:]
+    freed = 0
+    for p in doomed:
+        for dirpath, _dirs, files in os.walk(p):
+            for fn in files:
+                try:
+                    freed += os.path.getsize(os.path.join(dirpath, fn))
+                except OSError:
+                    pass
+        import shutil as _sh
+        _sh.rmtree(p, ignore_errors=True)
+    for dp in _g.glob(os.path.join('reports', '*')):
+        if os.path.isdir(dp) and not os.listdir(dp):
+            os.rmdir(dp)
+    if doomed:
+        print(f'[retention] 中间运行即用即弃: 清理 {len(doomed)} 个旧目录 -{freed // 1048576}MB'
+              f'（验收目录保留 {len(pinned[:acceptance_keep])} 个）')
+
+
+# ---------------- 产品代码变更检测（增量重试回归门禁） ----------------
+# 背景：--retry-failed 只重跑 FAIL/SKIP，PASS 保留原结果；若上一轮之后修改了产品代码
+# （entry/src/main/ets），旧 PASS 可能已回归（实证：Profiles TC09/TC14 PASS→FAIL 靠全量重跑才抓到）。
+# 门禁：结果侧车 results.meta.json 记录 srcHash；增量重试前重算，不一致 → 自动升级为全量重跑。
+
+def _find_src_root():
+    """定位被测工程 entry/src/main/ets：FORGE_SRC_DIR 优先；否则在父/祖父目录的
+    *Ohos|ohos 兄弟工程中，按 forge 目录名令牌匹配（timer-hypium→TimerOhos）；
+    匹配失败且候选不唯一时返回 None（门禁将保守全量，宁可多跑不漏回归）。"""
+    env = os.environ.get('FORGE_SRC_DIR')
+    if env and os.path.isdir(env):
+        return env
+    import re as _re
+    here = os.path.abspath(os.getcwd())
+
+    def _norm(s):
+        s = s.lower()
+        changed = True
+        while changed:
+            changed = False
+            for suf in ('-ohos', 'ohos', '-hypium', 'hypium', '-forge', 'forge', '-migration', 'migration'):
+                if s.endswith(suf) and len(s) > len(suf):
+                    s = s[:-len(suf)]
+                    changed = True
+        return s
+
+    token = _norm(_re.split(r'[-_.]', os.path.basename(here))[0])
+    if token in ('hypium', 'tmp', 'testcases', 'forge', ''):  # <X>-migration/hypium_forge → 用父目录令牌
+        token = _norm(_re.split(r'[-_.]', os.path.basename(os.path.dirname(here)))[0])
+    cands = []  # (src_root, 归一化工程名)
+    for base in (os.path.dirname(here), os.path.dirname(os.path.dirname(here))):
+        if not base or not os.path.isdir(base):
+            continue
+        for d in sorted(os.listdir(base)):
+            if d.endswith('Ohos') or d == 'ohos':
+                cand = os.path.join(base, d, 'entry', 'src', 'main', 'ets')
+                if os.path.isdir(cand):
+                    cands.append((cand, _norm(d)))
+    if not cands:
+        return None
+    if len(cands) == 1:
+        return cands[0][0]
+    for cand, dn in cands:
+        if dn == token or dn.startswith(token) or token.startswith(dn):
+            return cand
+    return None
+
+
+def src_tree_hash():
+    """entry/src/main/ets 下全部 .ets/.ts 内容哈希（排序后串联），产品代码指纹。"""
+    root = _find_src_root()
+    if not root:
+        return None
+    h = hashlib.sha256()
+    for dirpath, dirs, files in os.walk(root):
+        dirs[:] = sorted(d for d in dirs if d not in ('build', 'oh_modules', '.preview'))
+        for fn in sorted(files):
+            if not fn.endswith(('.ets', '.ts')):
+                continue
+            p = os.path.join(dirpath, fn)
+            h.update(os.path.relpath(p, root).encode())
+            try:
+                h.update(open(p, 'rb').read())
+            except OSError:
+                return None
+    return h.hexdigest()[:16]
+
+
+def src_file_hashes():
+    """每个 .ets/.ts 文件内容哈希 {相对路径: hash}——范围回归的变更定位基础。"""
+    root = _find_src_root()
+    if not root:
+        return None
+    out = {}
+    for dirpath, dirs, files in os.walk(root):
+        dirs[:] = sorted(d for d in dirs if d not in ('build', 'oh_modules', '.preview'))
+        for fn in sorted(files):
+            if not fn.endswith(('.ets', '.ts')):
+                continue
+            p = os.path.join(dirpath, fn)
+            try:
+                out[os.path.relpath(p, root)] = hashlib.sha1(open(p, 'rb').read()).hexdigest()[:12]
+            except OSError:
+                return None
+    return out
+
+
+def _meta_path(result_path):
+    return os.path.join(os.path.dirname(os.path.abspath(result_path)) or '.',
+                        'results.meta.json')
+
+
+def _read_prev_meta(result_path):
+    mp = _meta_path(result_path)
+    if os.path.exists(mp):
+        try:
+            return json.load(open(mp, encoding='utf-8'))
+        except Exception:
+            return {}
+    return {}
+
+
+def _read_prev_src_hash(result_path):
+    return _read_prev_meta(result_path).get('srcHash')
+
+
+def _update_ladder_meta(result_path, last_full_hash=None, explicit_full=False, all_pass=False, mode=None):
+    """TD-LADDER v2 预算状态（与 srcHash 记录共存于 results.meta.json）：
+    - last_full_hash: 最近一次"全量"运行的源码指纹（供"源码未变禁重复全量"判定）；
+    - explicit_full: 本轮是否显式全量（--all/--acceptance，不含 --retry-failed 自动升级）→ 计次；
+    - all_pass: 本轮零失败 → 计次归零，开启新修复周期。"""
+    try:
+        mp = _meta_path(result_path)
+        meta = {}
+        if os.path.exists(mp):
+            try:
+                meta = json.load(open(mp, encoding='utf-8'))
+            except Exception:
+                meta = {}
+        if last_full_hash:
+            meta['lastFullSrcHash'] = last_full_hash
+            meta['lastFullTs'] = time.time()
+        if mode:
+            meta['lastMode'] = mode
+        if all_pass:
+            meta['explicitFullCount'] = 0
+        elif explicit_full:
+            meta['explicitFullCount'] = int(meta.get('explicitFullCount') or 0) + 1
+        json.dump(meta, open(mp, 'w', encoding='utf-8'), indent=1)
+    except Exception:
+        pass
+
+
+def _write_src_meta(result_path, src_hash, mode, files=None):
+    if not src_hash:
+        return
+    try:
+        mp = _meta_path(result_path)
+        meta = {'srcHash': src_hash, 'ts': time.time(), 'mode': mode}
+        if files:
+            meta['files'] = files  # 供下轮范围回归 diff（旧 meta 无此键 → 保守全量）
+        json.dump(meta, open(mp, 'w', encoding='utf-8'), indent=1)
+    except Exception:
+        pass
+
+
+# ---------------- 范围回归（touched scope）：改动定位 → 受影响用例子集 ----------------
+# 门禁升级不再非黑即白：产品代码变更时，若改动文件全部是"用例可定位的 UI 文件"
+# （ids.json 键前缀），则只重跑 FAIL/SKIP + 引用了这些文件的用例；其余 PASS 保留。
+# 任一改动文件是共享逻辑（viewmodel/repository/model）或不可定位 → 保守全量。
+# 引用识别不到依赖（纯文本交互）的 PASS 用例保守并入范围；范围超 60% 直接全量。
+
+_STR_LIT = re.compile(r"""['"]([A-Za-z_][A-Za-z0-9_]{2,})['"]""")
+
+
+def _load_id_file_map(ids_path):
+    """ids.json（preinject 产物）{'File:locator': id} → {id: 文件基名(lower)}。"""
+    try:
+        m = json.load(open(ids_path, encoding='utf-8'))
+        return {str(v): str(k).split(':')[0].lower() for k, v in m.items()}
+    except Exception:
+        return None
+
+
+def case_dep_files(path, id2file):
+    """用例源码中引用的 id 字面量 → 依赖 UI 文件基名集合（空集=纯文本交互，无法定位）。"""
+    try:
+        src = open(path, encoding='utf-8').read()
+    except Exception:
+        return None
+    deps = set()
+    for lit in _STR_LIT.findall(src):
+        f = id2file.get(lit)
+        if f:
+            deps.add(f)
+    return deps
+
+
+def plan_touched_scope(changed_rel, id2file, dir_):
+    """返回受影响 UI 文件基名集合；改动越界（非 UI 文件）返回 None=保守全量。"""
+    changed_bases = {os.path.basename(c).rsplit('.', 1)[0].lower() for c in changed_rel}
+    ui_bases = set(id2file.values())
+    if not changed_bases <= ui_bases:
+        return None
+    return changed_bases
+
+
+
+HDC_BIN = '/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains/hdc'
+DEVICE_SN = None  # main() 里从 args.device 赋值
+
+
+def _shot(d, path, label='shot'):
+    """截图（尽力而为，绝不影响结果记录）：d.screenshot 优先，失败走 hdc snapshot_display。"""
+    os.makedirs(os.path.dirname(path) if os.path.dirname(path) else '.', exist_ok=True)
+    try:
+        d.screenshot(path)
+        print(f'  [{label}] {path}')
+        return
+    except Exception:
+        pass
+    try:
+        import subprocess as _sp
+        dev = DEVICE_SN or os.environ.get('FORGE_DEVICE', '127.0.0.1:5555')
+        remote = f'/data/local/tmp/_forge_shot.jpeg'
+        _sp.run([HDC_BIN, '-t', dev, 'shell', 'snapshot_display', '-f', remote],
+                capture_output=True, timeout=10)
+        _sp.run([HDC_BIN, '-t', dev, 'file', 'recv', remote, path],
+                capture_output=True, timeout=15)
+        _sp.run([HDC_BIN, '-t', dev, 'shell', 'rm', '-f', remote],
+                capture_output=True, timeout=5)
+        print(f'  [{label}] {path} (hdc)')
+    except Exception as exc:
+        print(f'  [{label}] 不可用: {exc}')
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument('--case', default=None)
+    ap.add_argument('--all', action='store_true')
+    ap.add_argument('--dir', default='testcases')
+    ap.add_argument('--device', default='127.0.0.1:5555')
+    ap.add_argument('--retry-failed', action='store_true',
+                    help='增量重试：只重跑 results.json 中 FAIL/SKIP 条（PASS 保留原结果，合并写出）；'
+                         '产品代码(entry/src/main/ets)较上轮有变更时自动升级为全量重跑')
+    ap.add_argument('--force-incremental', action='store_true',
+                    help='跳过产品代码变更门禁，强制增量（仅测试脚本变更时使用）')
+    ap.add_argument('--regression-scope', choices=('touched', 'full'), default=None,
+                    help='产品代码变更时的回归范围: touched=FAIL/SKIP+引用改动UI文件的用例(默认) | full=全量'
+                         '（env FORGE_REGRESSION_SCOPE 同义；改动含共享逻辑文件时 touched 自动退化为 full）')
+    ap.add_argument('--cold', action='store_true',
+                    help='--case 单条验证时强制冷启（默认热启动软复用，省 8-12s；断言冷启行为时用）')
+    ap.add_argument('--case-timeout', type=int, default=240,
+                    help='单用例看门狗秒数（默认 240，超时记 FAIL 继续下一条，防挂死烧设备时间；0=关闭）')
+    ap.add_argument('--flake-retry', type=int, default=1,
+                    help='瞬态失败（watchdog/连接类）轮末自动复测次数（默认 1，省一轮 agent 往返；0=关闭）')
+    ap.add_argument('--filter', default=None,
+                    help='子串过滤用例文件名（保留分组序），如 --filter TC3 跑 TC30/TC31/TC35')
+    ap.add_argument('--shots', choices=('fail', 'all', 'off'), default=None,
+                    help='截图策略: fail=PASS只留end帧/FAIL留全过程(默认) | all=全程留存 | off=不截')
+    ap.add_argument('--keep-reports', type=int, default=None,
+                    help='中间(非验收)运行目录保留最近 N 份（默认 0=即用即弃，当轮取证后即回收；'
+                         'env FORGE_KEEP_REPORTS）。验收目录(.acceptance)不受此限制，独立保留最近 2 次')
+    ap.add_argument('--force-all', action='store_true',
+                    help='跳过修复轮 --all 防护（仅限确有必要的全量场景；正常流程: --case 单条 → '
+                         '--retry-failed 增量 → --acceptance 终局验收）')
+    ap.add_argument('--acceptance', action='store_true',
+                    help='验收模式：强制全量 + 全程截图(--shots all，显式传 --shots 时以显式为准)，'
+                         '结果目录写入 .acceptance 标记——prune 永不清理最近的验收目录（保留最近 2 次），'
+                         '作为最终质量门的完整截图证据')
+    args = ap.parse_args()
+    # 阶梯防护 v2（TD-LADDER）：所有"显式全量"（--all / --acceptance / 变相全量的 --filter）统一受管。
+    #   R1 上轮有 FAIL/SKIP                    → 必须先修（--case/--retry-failed），禁止全量；
+    #   R2/R2b 源码未变且已全量过                → 重复全量无新结论；--acceptance 仅当"上次也是同源验收"才拦；
+    #   R3 本周期显式全量已达上限                → 见 LADDER_FULL_BUDGET；
+    #   L2 零进展（连续两轮失败签名一致且源码未变）→ 拒绝重跑，必须先 probe 定案改码。
+    # 免检：--retry-failed 因源码变更自动升级的全量（非显式，不占预算）；--force-all 逃生。
+    _prev_path = os.path.join(os.path.abspath(args.dir), '..', 'results.json')
+    _prev_res, _meta = None, {}
+    if os.path.exists(_prev_path):
+        try:
+            _prev_res = json.load(open(_prev_path, encoding='utf-8'))
+        except Exception:
+            _prev_res = None
+        _meta = _read_prev_meta(_prev_path)
+    _pending = [str(r.get('case', '?')) for r in (_prev_res or [])
+                if r.get('status') in ('FAIL', 'SKIP')]
+    _cur_hash = src_tree_hash()
+    _last_full_hash = _meta.get('lastFullSrcHash')
+    _full_count = int(_meta.get('explicitFullCount') or 0)
+
+    # L1：--filter 覆盖超半数用例 = 变相全量，按显式全量纳管
+    _filter_full = False
+    if args.filter:
+        try:
+            _all_files = order_files(args.dir)
+            _hit = [f for f, _g in _all_files if args.filter in f]
+            _filter_full = bool(_all_files) and len(_hit) > max(5, int(len(_all_files) * 0.25))
+            if _filter_full:
+                print(f'ℹ --filter "{args.filter}" 覆盖 {len(_hit)}/{len(_all_files)} 条（>25% 且 >5）= 变相全量，按全量纳管')
+        except Exception:
+            _filter_full = False
+
+    def _ladder_block(reason):
+        print('⛔ 阶梯防护：拒绝显式全量（--all / --acceptance / 变相 --filter）')
+        print(f'   原因：{reason}')
+        print('   ▶ 单条验证: --case <失败用例>')
+        print('   ▶ 增量重跑: --retry-failed（源码变更时按 srcHash 自动收窄/升级）')
+        print('   ▶ 全绿后再做 终局验收: --acceptance（证据留档，全程截图）')
+        print('   ▶ 确有必要的一次性全量: --force-all（跳过防护，自担"无进展"风险）')
+        sys.exit(2)
+
+    explicit_full = (args.all or args.acceptance or _filter_full) and not args.force_all
+    if explicit_full:
+        _reason = None
+        if _pending:
+            _reason = (f'上轮 results.json 尚有 {len(_pending)} 条 FAIL/SKIP：'
+                       + '、'.join(_pending[:6]) + (' …' if len(_pending) > 6 else ''))
+        elif (not args.acceptance) and _cur_hash and _last_full_hash == _cur_hash:
+            _reason = '源码自上次全量以来未变化（srcHash 相同），重复全量不会得到新结论'
+        elif (args.acceptance and _meta.get('lastMode') == 'acceptance'
+              and _cur_hash and _last_full_hash == _cur_hash):
+            _reason = '上次已是同源验收（srcHash 相同），无需重复验收'
+        elif _full_count >= LADDER_FULL_BUDGET:
+            _reason = f'本修复周期显式全量已达 {_full_count} 次（上限 {LADDER_FULL_BUDGET}）'
+        if _reason:
+            _ladder_block(_reason)
+
+    # L2：零进展硬阻断——连续两轮失败签名一致且源码未变时，重跑（增量/全量）必然同样失败。
+    if not args.force_all and not args.case and _cur_hash and _pending \
+            and _meta.get('srcHash') == _cur_hash:
+        _prev_prev = os.path.join(os.path.abspath(args.dir), '..', 'results.prev.json')
+        if os.path.exists(_prev_prev):
+            try:
+                _pp = json.load(open(_prev_prev, encoding='utf-8'))
+
+                def _failsig(lst):
+                    return sorted({(r.get('msg') or '').split(' | ')[0][:60]
+                                   for r in lst if r.get('status') == 'FAIL'})
+
+                if _failsig(_pp) and _failsig(_pp) == _failsig(_prev_res or []):
+                    print('⛔ 阶梯防护（L2 零进展）：连续两轮失败签名集完全一致，且源码未变化。')
+                    print('   重复重跑必然同样失败——请先用 probe.py（tree/hilog/db-pull）定案并修改代码。')
+                    print('   确需强跑: --force-all')
+                    sys.exit(2)
+            except Exception:
+                pass
+    global DEVICE_SN, SHOT_MODE
+    DEVICE_SN = args.device
+    SHOT_MODE = args.shots or os.environ.get('FORGE_SHOT_MODE', 'fail')
+    if args.acceptance:
+        args.all = True  # 验收=强制全量
+        if not args.shots:
+            SHOT_MODE = 'all'  # 验收全程截图（显式 --shots 优先）
+        print('═══ 验收模式: 全量 + 全程截图 + .acceptance 标记（prune 保护） ═══')
+    if SHOT_MODE not in ('fail', 'all', 'off'):
+        SHOT_MODE = 'fail'
+    os.environ['FORGE_SHOT_MODE'] = SHOT_MODE  # step_shot(_common) 同步感知 off
+    keep_reports = args.keep_reports if args.keep_reports is not None else int(
+        os.environ.get('FORGE_KEEP_REPORTS', '0') or 0)
+    sys.path.insert(0, os.path.abspath(args.dir))
+
+    if args.case:
+        ordered = [(f'{args.case}.py', 'anonymous')]
+    elif args.retry_failed:
+        prev = os.path.join(os.path.abspath(args.dir), '..', 'results.json')
+        if not os.path.exists(prev):
+            print('--retry-failed 需要 results.json'); sys.exit(1)
+        # ---- 回归门禁：产品代码变更 → 全量 或 范围回归（touched，TD-019+）----
+        cur_hash = src_tree_hash()
+        if not args.force_incremental:
+            prev_hash = _read_prev_src_hash(prev)
+            if cur_hash is None:
+                print('⚠ 未定位到 entry/src/main/ets（可用 FORGE_SRC_DIR 指定），无法判定产品代码变更 → 保守全量重跑')
+                args.all = True
+            elif prev_hash is None:
+                print('⚠ results.meta.json 无上轮 srcHash 记录（旧版产物）→ 保守全量重跑（本轮后建立指纹）')
+                args.all = True
+            elif cur_hash != prev_hash:
+                scope_mode = (args.regression_scope
+                              or os.environ.get('FORGE_REGRESSION_SCOPE') or 'touched')
+                touched = None
+                if scope_mode == 'touched':
+                    prev_files = _read_prev_meta(prev).get('files')
+                    cur_files = src_file_hashes()
+                    if prev_files and cur_files:
+                        changed_rel = {r for r in cur_files if prev_files.get(r) != cur_files[r]}
+                        changed_rel |= set(prev_files) - set(cur_files)  # 删除/改名也算
+                        ids_path = os.path.join(os.path.dirname(os.path.abspath(prev)), 'ids.json')
+                        id2file = _load_id_file_map(ids_path)
+                        if id2file is not None and changed_rel:
+                            touched = plan_touched_scope(changed_rel, id2file, args.dir)
+                            globals()['_ID2FILE'] = id2file
+                if touched:
+                    print(f'⚡ 产品代码变更限于 UI 文件 {sorted(touched)} → 范围回归: '
+                          f'FAIL/SKIP + 引用这些文件的用例（其余 PASS 保留）')
+                    globals()['_SCOPE_BASES'] = touched
+                else:
+                    print(f'⚠ 产品代码已变更（srcHash {prev_hash} → {cur_hash}）：改动含共享/不可定位文件 '
+                          f'→ 自动升级为全量重跑（改单页时可检查 ids.json 覆盖；强制收窄 --regression-scope touched）')
+                    args.all = True
+        prev_res = {str(r.get('case')).split('_')[0]: r
+                    for r in json.load(open(prev, encoding='utf-8'))}
+        all_ordered = order_files(args.dir)
+        if args.all:  # 门禁升级为全量：不保留旧 PASS
+            ordered = all_ordered
+            print(f'全量重跑（产品代码变更门禁）: {len(ordered)} 条')
+        else:
+            ordered = [(f, g) for f, g in all_ordered
+                       if f[:-3].split('_')[0] not in prev_res
+                       or prev_res[f[:-3].split('_')[0]].get('status') != 'PASS']
+            scope_bases = globals().get('_SCOPE_BASES')
+            if scope_bases:  # touched：并入"引用改动文件的 PASS 用例"（无依赖的保守并入）
+                id2file = globals().get('_ID2FILE') or {}
+                extra, ambiguous = [], 0
+                for f, g in all_ordered:
+                    cid = f[:-3].split('_')[0]
+                    if cid in prev_res and prev_res[cid].get('status') == 'PASS':
+                        deps = case_dep_files(os.path.join(args.dir, f), id2file)
+                        if deps is None or not deps or (deps & scope_bases):
+                            if deps is None or not deps:
+                                ambiguous += 1
+                            extra.append((f, g))
+                if len(ordered) + len(extra) > max(3, int(len(all_ordered) * 0.6)):
+                    print(f'⚠ 范围回归覆盖 {len(ordered) + len(extra)}/{len(all_ordered)} 条（含无依赖 {ambiguous}）'
+                          f'→ 超过 60% 阈值，升级全量')
+                    ordered = all_ordered
+                    args.all = True
+                else:
+                    ordered = ordered + extra
+                    ordered.sort(key=lambda x: (GROUP_ORDER[x[1]], x[0]))
+                    print(f'范围回归: FAIL/SKIP+受影响 {len(ordered)} 条（含无依赖纯文本用例 {ambiguous}，保守并入）')
+            keep = [prev_res[f[:-3].split('_')[0]] for f, g in all_ordered
+                    if f[:-3].split('_')[0] in prev_res
+                    and prev_res[f[:-3].split('_')[0]].get('status') == 'PASS'
+                    and (f, g) not in ordered]
+            print(f'增量重试: 重跑 {len(ordered)} 条 / 保留 PASS {len(keep)} 条')
+            globals()['_RETRY_KEEP'] = keep
+    elif args.all or args.filter:
+        ordered = order_files(args.dir)
+        if args.filter:
+            ordered = [(f, g) for f, g in ordered if args.filter in f]
+            if not ordered:
+                print(f'--filter "{args.filter}" 无匹配用例'); sys.exit(1)
+    else:
+        print('指定 --case X / --all / --retry-failed / --filter'); sys.exit(1)
+
+    _init_shot_dir()
+    os.environ['FORGE_DEVICE'] = args.device   # launch(want/reset) 的 hdc 透传用
+
+    d = UiDriver.connect(device_sn=args.device)
+    import signal
+
+    def _watchdog_arm(sec):
+        if sec and hasattr(signal, 'SIGALRM'):
+            def _handler(signum, frame):
+                raise TimeoutError(f'case watchdog {sec}s')
+            signal.signal(signal.SIGALRM, _handler)
+            signal.alarm(sec)
+
+    def _watchdog_disarm():
+        if hasattr(signal, 'SIGALRM'):
+            signal.alarm(0)
+
+    results = []
+    cur_group = None
+    first_in_group = True
+    for f, grp in ordered:
+        name = f[:-3]
+        if grp != cur_group:  # 组切换：首启组排尾，此前组状态不被回头破坏
+            cur_group = grp
+            first_in_group = True
+            print(f'\n────── 前置组 [{grp}] 开始（{grp} 组内软隔离共享前置）──────', flush=True)
+            os.environ['FORGE_GROUP_FIRST'] = '1'
+        # 热启动：组内非首条且锚已在位时 launch() 软复用当前会话（省冷启 8-12s/例）；
+        # first_launch 组（bm clean）与组首条（冷启验证）保持冷启；
+        # --case 单条验证默认热启动（--cold 强制冷启）
+        warm = (grp in ('anonymous', 'logged_in') and not first_in_group) or \
+               (args.case and not args.cold and grp != 'first_launch')
+        if warm:
+            os.environ['FORGE_WARM_LAUNCH'] = '1'
+        else:
+            os.environ.pop('FORGE_WARM_LAUNCH', None)
+        print(f'▶ {name} ...', flush=True)
+        _watchdog_arm(args.case_timeout)
+        try:
+            n, status, msg, dur = run_one(d, os.path.join(args.dir, f), name)
+        except TimeoutError as te:
+            n, status, msg, dur = name, 'FAIL', f'{te}（挂死截断，已跳下一条）', round(time.time(), 0)
+        finally:
+            _watchdog_disarm()
+        os.environ.pop('FORGE_GROUP_FIRST', None)
+        first_in_group = False
+        print(f'  {status} ({dur}s) {msg[:110]}', flush=True)
+        if status == 'PASS' and SHOT_MODE == 'fail':
+            _clean_pass_shots(name)  # PASS 只留 end 帧，FAIL 保留全过程证据
+        results.append({'case': n, 'status': status, 'msg': msg, 'dur': dur, 'group': grp})
+        time.sleep(0.5)  # launch 自带落座等待，长睡交给用例前置
+
+    # ---- 瞬态失败轮末复测：watchdog/连接类抖动当场再跑一次，PASS 记 flake-retry ----
+    # （省一轮"agent 读结果→重跑全量"往返；断言类失败不自动复测，防掩盖真缺陷）
+    if args.flake_retry > 0:
+        TRANSIENT = re.compile(r'watchdog|connector|Fail to get device|device disconnect|TimeoutError', re.I)
+        for r in list(results):
+            if r['status'] == 'FAIL' and TRANSIENT.search(r.get('msg', '')):
+                print(f'▶ {r["case"]} 瞬态失败特征，轮末复测...', flush=True)
+                os.environ.pop('FORGE_WARM_LAUNCH', None)  # 复测走完整冷启（连接类抖动需重连）
+                _watchdog_arm(args.case_timeout)
+                try:
+                    n2, st2, msg2, dur2 = run_one(d, os.path.join(args.dir, r['case'] + '.py'), r['case'])
+                except TimeoutError as te:
+                    n2, st2, msg2, dur2 = r['case'], 'FAIL', str(te), 0
+                finally:
+                    _watchdog_disarm()
+                if st2 == 'PASS':
+                    r.update({'status': 'PASS',
+                              'msg': f'flake-retry 二跑 PASS（首跑: {r["msg"][:60]}）',
+                              'dur': round(r['dur'] + dur2, 1)})
+                    print(f'  PASS(2nd) {r["case"]}', flush=True)
+                else:
+                    r['msg'] = f'{r["msg"]} | 复测仍失败: {msg2[:60]}'
+
+    results = globals().get('_RETRY_KEEP', []) + results
+    p = sum(1 for r in results if r['status'] == 'PASS')
+    f_ = sum(1 for r in results if r['status'] == 'FAIL')
+    print(f'\n══════ 直跑汇总: PASS={p} FAIL={f_} SKIP={len(results)-p-f_} / {len(results)} ══════')
+    from collections import Counter
+    print('分组: ' + ', '.join(f'{g}={c}' for g, c in Counter(r['group'] for r in results).items()))
+    # 同族错误聚类（分诊三律①：同消息视为同族，一次定案禁逐条实验）
+    fails = [r for r in results if r['status'] == 'FAIL']
+    if fails:
+        import re as _re
+        def _sig(m):
+            head = (m or '').split(' | ')[0]
+            return _re.sub(r'[:：].+', ': X', head)[:60]
+        clus = Counter(_sig(r.get('msg')) for r in fails)
+        print('同族聚类: ' + ' ; '.join(f'{c}×[{k}]' for k, c in clus.most_common(4)))
+    out = 'results.json' if (args.all or args.retry_failed) else 'results-%s.json' % (args.case or 'single').split('_')[0]
+    # ---- 零进展检测：失败签名集与上一轮完全一致 → 修复未生效，重跑必复现 ----
+    # （Grit 实证泥潭：taskSaveButton 同族失败连卡 5 轮全量 71min。触发即亮牌，
+    #  agent 应停止重跑、转 probe.py/hilog 定案——分诊三律② 同族定案实验 ≤2 次）
+    if fails and os.path.exists(out):
+        try:
+            prev_list = json.load(open(out, encoding='utf-8'))
+
+            def _sigset(lst):
+                from collections import Counter as _C
+                return _C(re.sub(r'[:：].+', '', (r.get('msg') or '')).split(' | ')[0][:60]
+                          for r in lst if r.get('status') == 'FAIL')
+
+            if _sigset(prev_list) and _sigset(prev_list) == _sigset(results):
+                print('\n⚠⚠ 零进展警告: 失败签名集与上一轮完全一致（'
+                      + ', '.join(f'{c}×{k}' for k, c in _sigset(results).most_common(3))
+                      + '）——修复未生效，重复重跑必然同样失败。'
+                        '停止重跑，用 probe.py（tree/hilog/db-pull）定案后改代码，再回来跑。')
+        except Exception:
+            pass
+    if os.path.exists(out):  # 修复轮重跑前保留上一轮原始记录（自愈边界：修≠覆盖历史）
+        import shutil as _sh
+        _sh.copy(out, out.replace('.json', '.prev.json'))
+    json.dump(results, open(out, 'w', encoding='utf-8'), ensure_ascii=False, indent=1)
+    if args.all or args.retry_failed:  # 全量/合并结果写入后记录产品代码指纹（供下轮增量门禁/范围回归比对）
+        _cur_src_hash = src_tree_hash()
+        _mode = 'acceptance' if args.acceptance else ('full' if args.all else 'retry')
+        _write_src_meta(out, _cur_src_hash, _mode, files=src_file_hashes())
+        _update_ladder_meta(out, last_full_hash=(_cur_src_hash if args.all else None),
+                            explicit_full=explicit_full, all_pass=(f_ == 0), mode=_mode)
+    if args.acceptance and SHOT_DIR:  # 验收目录打标：prune 独立保护，全程截图永久留存
+        try:
+            json.dump({'ts': time.time(), 'total': len(results), 'pass': p, 'fail': f_,
+                       'srcHash': _read_prev_src_hash(out) or ''},
+                      open(os.path.join(SHOT_DIR, '.acceptance'), 'w', encoding='utf-8'), indent=1)
+            print(f'[acceptance] 验收证据目录已保护: {SHOT_DIR}（PASS={p} FAIL={f_}）')
+        except Exception:
+            pass
+    print('明细: ' + out)
+    if fails and not args.retry_failed:  # 阶梯重跑提示（防修复后无脑 --all 空转设备时间）
+        first_fail = fails[0]['case']
+        print(f'\n▶ 下一步（重跑阶梯，禁直接 --all）: '
+              f'先 `--case {first_fail}` 验证修复 → 再 `--retry-failed`（改过产品代码会自动升级全量）')
+    _prune_reports(keep_reports)
+
+
+if __name__ == '__main__':
+    main()