@harmonyos-arkts/d2h 0.1.6 → 0.1.8

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

@@ -14,6 +14,16 @@ run_direct.py — 裸 hypium 直跑器（无 devicetest/xdevice 依赖）+ 前
 用法:
   单条:  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
@@ -23,6 +33,7 @@ import hashlib
 import importlib.util
 import json
 import os
+import re
 import sys
 import time
 import traceback
@@ -71,6 +82,39 @@ def _scene_evidence(d, n=8):
         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()
@@ -80,20 +124,27 @@ def run_one(d, mod_path, name):
             _sample_state = None
             try:
                 os.environ['FORGE_CASE'] = name
-                if SHOT_DIR:  # 过程采样：每 2.5s 一帧（<case>_pNN.jpeg），执行过程关键画面自动留存
+                if SHOT_DIR:  # 过程采样：每 2.5s 一帧（<case>_pNN.jpeg）；连续相同帧去重（静态页 8 帧→1 帧）
                     import threading
-                    state = {'n': 0, 'stop': False}
+                    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(2.5)
+                            _t.sleep(interval)
                             if state['stop']:
                                 break
-                            state['n'] += 1
                             try:
-                                _shot(d, os.path.join(SHOT_DIR, f"{name}_p{state['n']:02d}.jpeg"), f'proc{state["n"]:02d}')
+                                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)
@@ -153,7 +204,56 @@ def run_one(d, mod_path, name):
         return name, 'FAIL', msg, round(time.time() - t0, 1)
 
 
-SHOT_DIR = None  # 本次运行的截图目录（main 里初始化）
+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])} 个）')
 
 
 # ---------------- 产品代码变更检测（增量重试回归门禁） ----------------
@@ -224,40 +324,124 @@ def src_tree_hash():
     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_src_hash(result_path):
+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')).get('srcHash')
+            return json.load(open(mp, encoding='utf-8'))
         except Exception:
-            return None
-    return None
+            return {}
+    return {}
 
 
-def _write_src_meta(result_path, src_hash, mode):
+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)
-        json.dump({'srcHash': src_hash, 'ts': time.time(), 'mode': mode},
-                  open(mp, 'w', encoding='utf-8'), indent=1)
+        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
 
-def _init_shot_dir():
-    global SHOT_DIR
-    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）读取
 
 
 HDC_BIN = '/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains/hdc'
@@ -299,9 +483,119 @@ def main():
                          '产品代码(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()
-    global DEVICE_SN
+    # 阶梯防护 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:
@@ -310,7 +604,7 @@ def main():
         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)
-        # ---- 回归门禁：产品代码变更 → 自动全量（TD-019）----
+        # ---- 回归门禁：产品代码变更 → 全量 或 范围回归（touched，TD-019+）----
         cur_hash = src_tree_hash()
         if not args.force_incremental:
             prev_hash = _read_prev_src_hash(prev)
@@ -321,9 +615,28 @@ def main():
                 print('⚠ results.meta.json 无上轮 srcHash 记录（旧版产物）→ 保守全量重跑（本轮后建立指纹）')
                 args.all = True
             elif cur_hash != prev_hash:
-                print(f'⚠ 产品代码已变更（srcHash {prev_hash} → {cur_hash}）：旧 PASS 可能回归 → 自动升级为全量重跑')
-                print('  （确认仅测试脚本变更可加 --force-incremental 强制增量）')
-                args.all = True
+                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)
@@ -334,34 +647,116 @@ def main():
             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']
-            print(f'增量重试: 重跑 {len(ordered)} 条 / 保留 PASS {len(keep)} 条（srcHash 未变: {cur_hash}）')
+                    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:
+    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）'); sys.exit(1)
+        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)
-        n, status, msg, dur = run_one(d, os.path.join(args.dir, f), name)
+        _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(2)
+        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')
@@ -379,13 +774,49 @@ def main():
         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:  # 全量/合并结果写入后记录产品代码指纹（供下轮增量门禁比对）
-        _write_src_meta(out, src_tree_hash(), 'full' if args.all else 'retry')
+    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__':