@harmonyos-arkts/d2h 0.1.11 → 0.1.13

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

@@ -1,659 +1,659 @@
-# coding: utf-8
-"""d2h-hypium-forge 共享库（自动生成）
-
-前置条件分组编排约定（TD-004）：
-  需要登录态的用例文件顶部声明  PRECOND = 'logged_in'
-  首启态（bm clean）用例声明      PRECOND = 'first_launch'
-  缺省                          PRECOND = 'anonymous'
-  run_direct 按 anonymous→logged_in→first_launch 分组排序（破坏性递增，clean 类排尾），
-  组内软隔离（launch() 默认 reset_data=False，preferences 保留→登录态保持）。
-  ensure_login 等 setup 必须【幂等】：先探测状态（抽屉用户名已就位）再决定是否走完整
-  UI 登录——组首一次完整 setup，组内后续直接复用（省重复登录/注册）。
-  组首条执行时环境变量 FORGE_GROUP_FIRST=1（可选做完整冷启验证）。
-"""
-import os as _os
-import time
-from hypium import *
-from hypium.model import MatchPattern, UiParam
-
-try:
-    WAIT_SCALE = float(_os.environ.get('FORGE_WAIT_SCALE', '1') or 1)
-except ValueError:
-    WAIT_SCALE = 1.0
-
-
-def _w(sec):
-    """等待时长缩放（env FORGE_WAIT_SCALE，默认 1 不变）：调试迭代期设 0.5
-    可把失败路径的超时烧穿时间减半（Grit 实证 FAIL 用例 17-36s 多为等待超时）；
-    正式回归/出报告必须保持 1，防止慢设备真问题被截短掩盖。"""
-    return max(0.5, sec * WAIT_SCALE)
-
-PACKAGE = "me.hackerchick.raisetoanswer"
-ABILITY = "EntryAbility"
-ENTRY_PAGE = "pages/Index"
-
-
-# ── Level 0 统一引导引擎（TD-008）：权限/隐私/广告/引导弹窗 + tab 归位，一揽子消化 ──
-# 关卡模型：每关 = 探测特征文案集合 → 处置（点击命中项）→ 循环消化到无特征。
-# app 级配置 GATES（按需增删）；bootstrap 幂等（主页锚可见即成功），超时输出页面快照供分诊。
-
-GATES = [
-    {"name": "privacy",    "texts": ["同意并继续", "同意", "知道了", "我知道了"]},
-    {"name": "permission", "texts": ["仅在使用中允许", "使用应用时允许", "允许"]},
-    {"name": "ad",         "texts": ["跳过", "关闭广告", "不再显示", "以后再说", "暂不"]},
-]
-
-def _page_texts(d):
-    try:
-        return [(c.getText() or '') for c in (d.find_all_components(BY.type("Text")) or [])
-                if c.getText()]
-    except Exception:
-        return []
-
-
-def _visible_clickables(d):
-    """一次拉全 Text+Button 可见文案集合（弹窗消化轮询的单 RPC 扫描，
-    替代逐文案 find_component 的 12+ RPC/轮——冷启消化从 ~3s/轮 降到 ~0.6s/轮）。"""
-    out = []
-    try:
-        for by in (BY.type("Text"), BY.type("Button")):
-            for c in (d.find_all_components(by) or []):
-                t = c.getText() or ""
-                if t:
-                    out.append(t)
-    except Exception:
-        pass
-    return out
-
-def bootstrap(d, gates=None, home_tab="", anchor_key="", total=60, log=print):
-    """冷启到可用基座。流程：轮询消化全部弹窗关卡（一轮多点，直到无特征）→
-    tab 归位（点目标 tab + 验证锚）→ 主页锚可见返回 True。
-    anchor_key 是"基座就绪"的唯一判据（app 级配置，如目标 tab 的内容控件 id）。"""
-    gates = gates if gates is not None else GATES
-    all_texts = [t for g in gates for t in g["texts"]]
-    t0 = time.time()
-    dismissed = []
-    while time.time() - t0 < total:
-        # 1) 主页锚已可见 → 提前成功（幂等）
-        if anchor_key:
-            try:
-                if d.find_component(BY.key(anchor_key)) is not None:
-                    if dismissed:
-                        log(f"  [L0] 弹窗消化: {dismissed}")
-                    return True
-            except Exception:
-                pass
-        # 2) 消化所有弹窗关卡：一轮拉全可见文案（单 RPC 扫描），本地匹配命中再点击
-        hit_any = False
-        vis = set(_visible_clickables(d))
-        for t in all_texts:
-            if t == (home_tab or "") or t not in vis:
-                continue
-            try:
-                d.touch(BY.text(t))
-                dismissed.append(t)
-                hit_any = True
-                time.sleep(1.2)
-                break  # 点一个后重新扫（弹窗可能叠加/消失后露下一个）
-            except Exception:
-                pass
-        if hit_any:
-            continue
-        pts = _page_texts(d)
-        # 3) 无弹窗特征：tab 归位（点目标 tab，锚验证）
-        if home_tab and home_tab in pts:
-            if anchor_key:
-                try:
-                    if d.find_component(BY.key(anchor_key)) is not None:
-                        return True
-                except Exception:
-                    pass
-            try:
-                d.touch(BY.text(home_tab))
-                time.sleep(2.0)
-            except Exception:
-                pass
-        time.sleep(0.9)
-    # 超时：输出页面快照供分诊
-    log(f"  [L0] ✗ bootstrap 超时 {total}s；页面文本快照: {_page_texts(d)[:15]}")
-    return False
-
-
-# ── Level 0 前置三件套（TD-007：冷启自适应，用例不得自带）────────────────
-# ① 首启弹窗 dismiss：多文案轮询（隐私/权限/引导），幂等无弹窗秒过
-FIRST_RUN_DISMISS_TEXTS = ["同意并继续", "同意", "允许", "仅在使用中允许", "我知道了", "知道了", "暂不", "以后再说"]
-
-def dismiss_first_run(d, rounds=3, gap=1.2):
-    for _ in range(rounds):
-        hit = False
-        for t in FIRST_RUN_DISMISS_TEXTS:
-            try:
-                c = d.find_component(BY.text(t))
-                if c is not None:
-                    d.touch(BY.text(t)); time.sleep(gap); hit = True; break
-            except Exception:
-                pass
-        if not hit:
-            return
-
-# ② 首页 tab 归位：应用默认落在非目标 tab（如广场）时点回目标 tab（HOME_TAB 应用级配置）
-def ensure_home_tab(d, tab_text, timeout=10):
-    t0 = time.time()
-    while time.time() - t0 < timeout:
-        try:
-            if d.find_component(BY.text(tab_text)) is not None:
-                d.touch(BY.text(tab_text)); time.sleep(1.5); return True
-        except Exception:
-            pass
-        time.sleep(0.8)
-    return False
-
-# ③ 冷启三件套：launch 内自动执行——弹窗 dismiss + tab 归位（HOME_TAB 非空时）
-HOME_TAB = ""  # 应用级：主功能 tab 文案（如 "玩安卓"）；空串跳过归位
-
-
-def launch(d, want="", reset_data=False, force=False):
-    """v3-①②（EXEC-034）：want=启动参数（'k=v;k2=v2' → hdc aa start --ps 透传，启动参数门控应用免人工补丁）；
-    reset_data=True → bm clean -n 清应用数据（用例级状态重置，防跨用例泄漏）；
-    force=True → 强制冷启（断言冷启行为的用例用）。
-    热启动（run_direct 组内非首条置 FORGE_WARM_LAUNCH=1）：HOME_ANCHOR 已在位即软复用
-    当前会话跳过 stop/start/bootstrap（省冷启 8-12s/例）；锚不可见自动回退完整冷启。"""
-    import os as _os, subprocess as _sp
-    if not want and not reset_data and not force and _os.environ.get("FORGE_WARM_LAUNCH") == "1":
-        anchor = globals().get("HOME_ANCHOR", "")
-        if anchor:
-            try:
-                if d.find_component(BY.key(anchor)) is not None:
-                    return  # 基座已就位：软复用（上一用例恰好停在本页）
-            except Exception:
-                pass
-    d.stop_app(PACKAGE)
-    time.sleep(0.8)
-    if reset_data:
-        hdc = _os.environ.get("FORGE_HDC", "hdc")
-        dev = _os.environ.get("FORGE_DEVICE", "127.0.0.1:5555")
-        try:
-            # DEVIATION-3: bm clean 不带 -d 时仅清 cache(-c),持久化不清,用例间状态泄漏
-            # (TC02 关 answer 残留致 TC03/08/09 连锁失败);本机 bm 无 -b 选项,-d 清数据
-            _sp.run([hdc, "-t", dev, "shell", "bm", "clean", "-n", PACKAGE, "-d"],
-                    capture_output=True, timeout=15)
-            time.sleep(0.5)
-        except Exception as e:
-            print("  [reset] bm clean 失败:", e)
-    if want:
-        hdc = _os.environ.get("FORGE_HDC", "hdc")
-        dev = _os.environ.get("FORGE_DEVICE", "127.0.0.1:5555")
-        args = ["aa", "start", "-b", PACKAGE, "-a", ABILITY]
-        for kv in want.split(";"):
-            if "=" in kv:
-                k, v = kv.split("=", 1)
-                # DEVIATION-1: aa start 的 --ps 只接受空格分隔 key value,等号形式报
-                # "invalid number of parameters for option --ps" 导致带参启动全部失败
-                args += ["--ps", k, v]
-        # EXEC-038 修复：带参启动 3 轮重试 + 实测探活（FORGE_WANT_PROBE=key，可寻才算活）
-        probe = _os.environ.get("FORGE_WANT_PROBE", "")
-        for attempt in range(3):
-            try:
-                _sp.run([hdc, "-t", dev, "shell", "aa", "force-stop", PACKAGE], capture_output=True, timeout=10)
-                time.sleep(0.8)
-                _sp.run([hdc, "-t", dev, "shell"] + args, capture_output=True, timeout=15)
-                time.sleep(3.0)
-                if probe:
-                    c = None
-                    try:
-                        c = d.find_component(BY.key(probe))
-                    except Exception:
-                        pass
-                    if c is None:
-                        print(f"  [want] 第{attempt+1}轮探活失败(key={probe})，重试")
-                        time.sleep(1.5)
-                        continue
-                _dismiss_first_run(d)
-                return
-            except Exception as e:
-                print("  [want] 带参启动异常，重试:", e)
-                time.sleep(1.5)
-        print("  [want] 3 轮未探活成功，继续交由断言暴露")
-    d.start_app(PACKAGE, ABILITY)
-    ok = bootstrap(d, home_tab=HOME_TAB, anchor_key=HOME_ANCHOR)
-    if not ok:
-        raise AssertionError("L0 bootstrap failed（弹窗/tab 未消化，见日志快照）")
-    time.sleep(1.5)  # bootstrap 锚已验证就位，1.5s 落座余量（原 2.5s）
-    _dismiss_first_run(d)
-
-
-def _dismiss_first_run(d):
-    """首启弹窗一键处置（权限/隐私协议）——单 RPC 拉全文案本地匹配"""
-    vis = set(_visible_clickables(d))
-    for txt in ["同意并继续", "允许", "我知道了", "暂不", "以后再说", "同意"]:
-        if txt not in vis:
-            continue
-        try:
-            c = d.find_component(BY.text(txt))
-            if c:
-                c.click()
-                time.sleep(0.8)
-                vis = set(_visible_clickables(d))  # 点掉一层后重扫（可能叠弹窗）
-        except Exception:
-            pass
-
-
-def stop(d):
-    d.stop_app(PACKAGE)
-
-
-def nav_to(d, page):
-    """导航到目标页：入口页直接用；非入口页用返回键回根后再走用例自带链（由用例 steps 驱动）"""
-    if page == ENTRY_PAGE:
-        return
-    # 返回根页（最多 5 次）
-    for _ in range(5):
-        try:
-            if d.find_component(BY.key("__never__")) is None:
-                pass
-        except Exception:
-            pass
-        d.press_back()
-        time.sleep(0.4)
-
-
-TAB_LABELS = ["首页", "视频", "我的"]
-
-
-def click_tab(d, label):
-    """底部 Tab 切换：定位文本→bounds 中心 touch（比例坐标兜底）"""
-    import time as _t
-    for _ in range(8):
-        try:
-            comps = d.find_all_components(BY.text(label))
-            if comps:
-                c = comps[-1]  # 底部 tab 是同名文本中最靠下的
-                b = c.getBounds()
-                cx = (b.left + b.right) // 2
-                cy = (b.top + b.bottom) // 2
-                d.touch((int(cx), int(cy)))
-                _t.sleep(1.2)
-                return
-        except Exception:
-            pass
-        _t.sleep(0.25)
-    idx = TAB_LABELS.index(label) if label in TAB_LABELS else 2
-    w, h = d.get_display_size()
-    d.touch((int(w * (idx + 0.5) / len(TAB_LABELS)), int(h * 0.945)))
-    time.sleep(1.2)
-
-
-def click_text(d, txt, wait=6):
-    """按可见文本点击（tab 名/中文按钮等无 ID 控件）。
-    先试 BY.key——无下划线的单词 id（如 fab）无法与文本区分（_is_id_like 局限），此处兜底。"""
-    import time as _t
-    try:
-        c = d.find_component(BY.key(txt))
-        if c:
-            c.click()
-            _t.sleep(1.0)
-            return
-    except Exception:
-        pass
-    deadline = _t.time() + _w(wait)
-    while _t.time() < deadline:
-        try:
-            c = d.find_component(BY.text(txt, MatchPattern.CONTAINS))
-            if c:
-                c.click()
-                _t.sleep(1.0)
-                return
-        except Exception:
-            pass
-        _t.sleep(0.25)
-    raise AssertionError("text not clickable: " + txt)
-
-
-def click_type_first(d, ctype, wait=6):
-    """点击指定类型的第一个组件（lineN:Type 引用的兜底点击）"""
-    import time as _t
-    deadline = _t.time() + _w(wait)
-    while _t.time() < deadline:
-        try:
-            comps = d.find_all_components(BY.type(ctype))
-            if comps:
-                b = comps[0].getBounds()
-                d.touch(((b.left + b.right) // 2, (b.top + b.bottom) // 2))
-                _t.sleep(1.2)
-                return
-        except Exception:
-            pass
-        _t.sleep(0.25)
-    raise AssertionError("type not clickable: " + ctype)
-
-
-def id_click(d, cid, wait=6):
-    comp = _find(d, cid, wait)
-    comp.click()
-    time.sleep(1.0)
-
-
-def id_input(d, cid, text, wait=6):
-    comp = _find(d, cid, wait)
-    d.input_text(comp, text)
-    time.sleep(0.6)
-
-
-def _find(d, cid, wait=6):
-    import time as _t
-    deadline = _t.time() + _w(wait)
-    while _t.time() < deadline:
-        try:
-            c = d.find_component(BY.key(cid))
-            if c:
-                return c
-        except Exception:
-            pass
-        try:
-            c = d.find_component(BY.id(cid))
-            if c:
-                return c
-        except Exception:
-            pass
-        _t.sleep(0.25)
-    raise AssertionError("component not found: " + cid)
-
-
-def smart_click(d, cid, txt=None, wait=6):
-    """key 优先点击；失败且有 txt 时文本点击（mine 类 HAR 模块 ID 丢失边界）"""
-    import time as _t
-    deadline = _t.time() + _w(wait)
-    while _t.time() < deadline:
-        try:
-            c = d.find_component(BY.key(cid))
-            if c:
-                c.click()
-                _t.sleep(1.0)
-                return
-        except Exception:
-            pass
-        _t.sleep(0.25)
-    if txt and txt.startswith("line"):
-        import re as _re
-        m = _re.match(r"line\d+:(\w+)", txt)
-        if m:
-            click_type_first(d, m.group(1), wait)
-            return
-    if txt:
-        click_text(d, txt, wait)
-        return
-    raise AssertionError("component not found: " + cid)
-
-
-def scroll_text_exist(d, txt, wait=6):
-    """滚动查找文本，双向（EXEC-005）：上滑 N 次找 → 未中则下滑回落 N 次找。
-    单向滚动在连续断言场景必挂：上一断言滑到底后，本断言目标在上方，单向永远回不去。"""
-    import time as _t
-    w, h = d.get_display_size()
-    def _check():
-        try:
-            return d.find_component(BY.text(txt, MatchPattern.CONTAINS)) is not None
-        except Exception:
-            return False
-    for direction in (UiParam.UP, UiParam.DOWN):
-        for i in range(6):
-            if _check():
-                return True
-            d.swipe(direction, distance=40)
-            _t.sleep(1.0)
-    return text_exist(d, txt, wait)
-
-
-def smart_check(d, cid, txt=None, wait=6):
-    """key 优先断言；失败且有 txt 时降级文本断言（部分 HAR 模块 .id 运行时丢弃的边界）"""
-    import time as _t
-    deadline = _t.time() + _w(wait)
-    while _t.time() < deadline:
-        try:
-            c = d.find_component(BY.key(cid))
-            if c:
-                return True
-        except Exception:
-            pass
-        _t.sleep(0.25)
-    if txt and txt.startswith("line"):
-        import re as _re
-        m = _re.match(r"line\d+:(\w+)", txt)
-        if m:
-            d.check_component_exist(BY.type(m.group(1)), wait_time=wait)
-            return True
-    if txt:
-        return text_exist(d, txt, wait)
-    raise AssertionError("component not found: " + cid)
-
-
-def text_equals(d, txt, wait=6):
-    """精确文本断言（EQUALS）——CONTAINS 会被前缀污染（如 ❄️Gallery 含 Gallery），
-    恢复/状态标记类断言必须用本原语。存在且精确相等返回 True，否则抛。"""
-    import time as _t
-    deadline = _t.time() + _w(wait)
-    while _t.time() < deadline:
-        try:
-            c = d.find_component(BY.text(txt))
-            if c:
-                return True
-        except Exception:
-            pass
-        _t.sleep(0.25)
-    raise AssertionError("text (exact) not found: " + txt)
-
-
-def text_absent(d, txt, wait=3):
-    """文本不存在断言（反向；等待短暂稳定后确认消失）"""
-    import time as _t
-    _t.sleep(1.0)
-    try:
-        c = d.find_component(BY.text(txt, MatchPattern.CONTAINS))
-        if c:
-            raise AssertionError("text should be absent but found: " + txt)
-    except AssertionError:
-        raise
-    except Exception:
-        pass
-    return True
-
-
-def step_shot(d, label="step"):
-    """分步截图：一个动作/断言一张页面图（run_direct 设 FORGE_SHOT_DIR/FORGE_CASE 时启用）。
-    文件名 <case>_<序号>_<label>.jpeg，供 test-report.html 按步回放页面。
-    FORGE_SHOT_MODE=off 时跳过；fail 模式下 PASS 用例的过程图由 run_direct 统一清理。"""
-    import os as _os
-    if _os.environ.get("FORGE_SHOT_MODE") == "off":
-        return
-    base = _os.environ.get("FORGE_SHOT_DIR")
-    case = _os.environ.get("FORGE_CASE", "case")
-    if not base:
-        return
-    n = step_shot.n.get(case, 0) + 1
-    try:
-        d.screenshot(_os.path.join(base, "%s_%02d_%s.jpeg" % (case, n, label)))
-        step_shot.n[case] = n
-    except Exception:
-        pass
-
-
-step_shot.n = {}
-
-
-def wait_for(d, by, timeout=10, interval=0.5):
-    """轮询等待控件出现（首屏锚点等待用）；返回组件或 None，不抛异常"""
-    import time as _t
-    end = _t.time() + _w(timeout)
-    while _t.time() < end:
-        try:
-            c = d.find_component(by)
-            if c:
-                return c
-        except Exception:
-            pass
-        _t.sleep(interval)
-    return None
-
-
-def text_exist(d, txt, wait=6):
-    """文本存在断言（BY.text CONTAINS）。
-    契约：存在返回 True；不存在【抛 AssertionError】——永不返回 False。
-    run_direct/analyze_results 依赖异常文本做 FAIL 判定与失败聚类，勿改为静默返回。"""
-    import time as _t
-    deadline = _t.time() + _w(wait)
-    while _t.time() < deadline:
-        try:
-            c = d.find_component(BY.text(txt, MatchPattern.CONTAINS))
-            if c:
-                return True
-        except Exception:
-            pass
-        _t.sleep(0.25)
-    raise AssertionError("text not found: " + txt)
-
-
-def text_value_equals(d, cid, expected, wait=6):
-    """值断言（EXEC-040 实证+反证）：getText() 精确等于期望——锚定 key 控件动态内容。"""
-    import time as _t
-    deadline = _t.time() + _w(wait)
-    while _t.time() < deadline:
-        try:
-            c = d.find_component(BY.key(cid))
-            if c and c.getText() == expected:
-                return True
-        except Exception:
-            pass
-        _t.sleep(0.25)
-    got = None
-    try:
-        c = d.find_component(BY.key(cid))
-        got = c.getText() if c else '(not found)'
-    except Exception:
-        pass
-    raise AssertionError(f"text value mismatch: expect {expected!r} got {got!r} (key={cid})")
-
-
-def text_value_contains(d, cid, part, wait=6):
-    """值包含断言：getText() 包含子串（动态文案前缀不定时用）。"""
-    import time as _t
-    deadline = _t.time() + _w(wait)
-    while _t.time() < deadline:
-        try:
-            c = d.find_component(BY.key(cid))
-            if c and part in (c.getText() or ''):
-                return True
-        except Exception:
-            pass
-        _t.sleep(0.25)
-    raise AssertionError(f"text value not containing {part!r} (key={cid})")
-
-
-def count_equals(d, target, expected, wait=6):
-    """计数断言（EXEC-040 实证）：key 或 CONTAINS 文本匹配的组件数==期望。"""
-    import time as _t, re as _re
-    deadline = _t.time() + _w(wait)
-    last = -1
-    while _t.time() < deadline:
-        try:
-            if _re.match(r'^[a-z][a-z0-9_]+$', target):
-                comps = d.find_all_components(BY.key(target))
-            else:
-                comps = d.find_all_components(BY.text(target, MatchPattern.CONTAINS))
-            last = len(comps) if comps else 0
-            if last == expected:
-                return True
-        except Exception:
-            pass
-        _t.sleep(0.25)
-    raise AssertionError(f"count mismatch: expect {expected} got {last} (target={target})")
-
-
-def is_below(d, cid, ref_cid, wait=6):
-    """几何断言（EXEC-040 实证）：cid 的 top >= ref_cid 的 bottom（垂直次序）。"""
-    import time as _t
-    deadline = _t.time() + _w(wait)
-    while _t.time() < deadline:
-        try:
-            a = d.find_component(BY.key(cid)); b = d.find_component(BY.key(ref_cid))
-            if a and b and a.getBounds().top >= b.getBounds().bottom:
-                return True
-        except Exception:
-            pass
-        _t.sleep(0.25)
-    raise AssertionError(f"geometry: {cid} not below {ref_cid}")
-
-
-def toast_exist(d, txt, wait=4, poll=0.5):
-    """Toast 断言（v3.1）：轮询 hilog 捕获 Toast 文本。需 FORGE_HDC/FORGE_DEVICE。"""
-    import os as _os, subprocess as _sp, time as _tt
-    hdc = _os.environ.get("FORGE_HDC", "hdc"); dev = _os.environ.get("FORGE_DEVICE", "127.0.0.1:5555")
-    deadline = _tt.time() + _w(wait)
-    while _tt.time() < deadline:
-        try:
-            r = _sp.run([hdc, "-t", dev, "shell", "hilog", "-x"],
-                        capture_output=True, timeout=8, text=True, errors="ignore")
-            if txt in (r.stdout or ""):
-                return True
-        except Exception:
-            pass
-        _tt.sleep(poll)
-    raise AssertionError("toast not found in hilog: " + txt)
-
-
-# ── 强断言原语（2026-09-29 吸收自 none 臂实证：无 skill 的 LLM 凭通用能力即达成 34% 强断言，
-#     B 线无理由低于此——Toast/系统事件/数据断言按下表选型，禁止只写 exist）──
-def _hdc(args, timeout=20):
-    import subprocess as _sp, os as _os
-    dev = _os.environ.get("FORGE_DEVICE", "127.0.0.1:5555")
-    cmd = [HDC_BIN, "-t", dev] + args
-    r = _sp.run(cmd, capture_output=True, timeout=timeout)
-    return (r.stdout + r.stderr).decode("utf-8", "ignore")
-
-
-def _dump_layout(timeout=20):
-    """取当前全量布局 JSON（含系统对话框/浮层），返回原始文本（Round-2：确保本地 tmp 目录存在）"""
-    import json as _json, os as _os
-    _os.makedirs("./tmp", exist_ok=True)
-    _hdc(["shell", "uitest", "dumpLayout", "-p", "/data/local/tmp/forge_dump.json"], timeout=timeout)
-    _hdc(["file", "recv", "/data/local/tmp/forge_dump.json", "./tmp/forge_dump.json"], timeout=timeout)
-    try:
-        return open("./tmp/forge_dump.json", encoding="utf-8").read()
-    except Exception:
-        return ""
-
-
-def hilog_clear():
-    """清 hilog 缓冲，防止上一用例残留关键字造成假 PASS（tag=RaiseToAnswer）"""
-    _hdc(["shell", "hilog", "-r"])
-    time.sleep(0.3)
-
-
-HILOG_TAG = 'JSAPP'
-
-
-def hilog_tail(tag=None, n=400):
-    tag = tag or HILOG_TAG
-    """读取 tag 过滤的最近 n 行 hilog（诊断用）"""
-    import subprocess as _sp, os as _os
-    dev = _os.environ.get("FORGE_DEVICE", "127.0.0.1:5555")
-    r = _sp.run([HDC_BIN, "-t", dev, "shell", "hilog", "-z", str(n), "-T", tag],
-                capture_output=True, timeout=15)
-    return r.stdout.decode("utf-8", "ignore")
-
-
-def toast_text_seen(d, txt, timeout=6):
-    """Toast 文本断言（dump 版）。无 ID 例外：Toast 为瞬时浮层无稳定 ID，且 hypium find_component
-    实测看不到 Toast 子窗口，故以 uitest dumpLayout 原文轮询（首轮实测教训 Round-1）。"""
-    deadline = time.time() + _w(timeout)
-    while time.time() < deadline:
-        raw = _dump_layout()
-        if txt in raw:
-            return True
-        time.sleep(0.6)
-    raise AssertionError("toast not seen: " + txt)
-
-
-def bm_clean():
-    """清应用持久化数据（公开包装；import * 不导出 _ 前缀——Round-1 教训）"""
-    _hdc(["shell", "bm", "clean", "-n", PACKAGE, "-d"])
-    time.sleep(0.6)
+# coding: utf-8
+"""d2h-hypium-forge 共享库（自动生成）
+
+前置条件分组编排约定（TD-004）：
+  需要登录态的用例文件顶部声明  PRECOND = 'logged_in'
+  首启态（bm clean）用例声明      PRECOND = 'first_launch'
+  缺省                          PRECOND = 'anonymous'
+  run_direct 按 anonymous→logged_in→first_launch 分组排序（破坏性递增，clean 类排尾），
+  组内软隔离（launch() 默认 reset_data=False，preferences 保留→登录态保持）。
+  ensure_login 等 setup 必须【幂等】：先探测状态（抽屉用户名已就位）再决定是否走完整
+  UI 登录——组首一次完整 setup，组内后续直接复用（省重复登录/注册）。
+  组首条执行时环境变量 FORGE_GROUP_FIRST=1（可选做完整冷启验证）。
+"""
+import os as _os
+import time
+from hypium import *
+from hypium.model import MatchPattern, UiParam
+
+try:
+    WAIT_SCALE = float(_os.environ.get('FORGE_WAIT_SCALE', '1') or 1)
+except ValueError:
+    WAIT_SCALE = 1.0
+
+
+def _w(sec):
+    """等待时长缩放（env FORGE_WAIT_SCALE，默认 1 不变）：调试迭代期设 0.5
+    可把失败路径的超时烧穿时间减半（Grit 实证 FAIL 用例 17-36s 多为等待超时）；
+    正式回归/出报告必须保持 1，防止慢设备真问题被截短掩盖。"""
+    return max(0.5, sec * WAIT_SCALE)
+
+PACKAGE = "me.hackerchick.raisetoanswer"
+ABILITY = "EntryAbility"
+ENTRY_PAGE = "pages/Index"
+
+
+# ── Level 0 统一引导引擎（TD-008）：权限/隐私/广告/引导弹窗 + tab 归位，一揽子消化 ──
+# 关卡模型：每关 = 探测特征文案集合 → 处置（点击命中项）→ 循环消化到无特征。
+# app 级配置 GATES（按需增删）；bootstrap 幂等（主页锚可见即成功），超时输出页面快照供分诊。
+
+GATES = [
+    {"name": "privacy",    "texts": ["同意并继续", "同意", "知道了", "我知道了"]},
+    {"name": "permission", "texts": ["仅在使用中允许", "使用应用时允许", "允许"]},
+    {"name": "ad",         "texts": ["跳过", "关闭广告", "不再显示", "以后再说", "暂不"]},
+]
+
+def _page_texts(d):
+    try:
+        return [(c.getText() or '') for c in (d.find_all_components(BY.type("Text")) or [])
+                if c.getText()]
+    except Exception:
+        return []
+
+
+def _visible_clickables(d):
+    """一次拉全 Text+Button 可见文案集合（弹窗消化轮询的单 RPC 扫描，
+    替代逐文案 find_component 的 12+ RPC/轮——冷启消化从 ~3s/轮 降到 ~0.6s/轮）。"""
+    out = []
+    try:
+        for by in (BY.type("Text"), BY.type("Button")):
+            for c in (d.find_all_components(by) or []):
+                t = c.getText() or ""
+                if t:
+                    out.append(t)
+    except Exception:
+        pass
+    return out
+
+def bootstrap(d, gates=None, home_tab="", anchor_key="", total=60, log=print):
+    """冷启到可用基座。流程：轮询消化全部弹窗关卡（一轮多点，直到无特征）→
+    tab 归位（点目标 tab + 验证锚）→ 主页锚可见返回 True。
+    anchor_key 是"基座就绪"的唯一判据（app 级配置，如目标 tab 的内容控件 id）。"""
+    gates = gates if gates is not None else GATES
+    all_texts = [t for g in gates for t in g["texts"]]
+    t0 = time.time()
+    dismissed = []
+    while time.time() - t0 < total:
+        # 1) 主页锚已可见 → 提前成功（幂等）
+        if anchor_key:
+            try:
+                if d.find_component(BY.key(anchor_key)) is not None:
+                    if dismissed:
+                        log(f"  [L0] 弹窗消化: {dismissed}")
+                    return True
+            except Exception:
+                pass
+        # 2) 消化所有弹窗关卡：一轮拉全可见文案（单 RPC 扫描），本地匹配命中再点击
+        hit_any = False
+        vis = set(_visible_clickables(d))
+        for t in all_texts:
+            if t == (home_tab or "") or t not in vis:
+                continue
+            try:
+                d.touch(BY.text(t))
+                dismissed.append(t)
+                hit_any = True
+                time.sleep(1.2)
+                break  # 点一个后重新扫（弹窗可能叠加/消失后露下一个）
+            except Exception:
+                pass
+        if hit_any:
+            continue
+        pts = _page_texts(d)
+        # 3) 无弹窗特征：tab 归位（点目标 tab，锚验证）
+        if home_tab and home_tab in pts:
+            if anchor_key:
+                try:
+                    if d.find_component(BY.key(anchor_key)) is not None:
+                        return True
+                except Exception:
+                    pass
+            try:
+                d.touch(BY.text(home_tab))
+                time.sleep(2.0)
+            except Exception:
+                pass
+        time.sleep(0.9)
+    # 超时：输出页面快照供分诊
+    log(f"  [L0] ✗ bootstrap 超时 {total}s；页面文本快照: {_page_texts(d)[:15]}")
+    return False
+
+
+# ── Level 0 前置三件套（TD-007：冷启自适应，用例不得自带）────────────────
+# ① 首启弹窗 dismiss：多文案轮询（隐私/权限/引导），幂等无弹窗秒过
+FIRST_RUN_DISMISS_TEXTS = ["同意并继续", "同意", "允许", "仅在使用中允许", "我知道了", "知道了", "暂不", "以后再说"]
+
+def dismiss_first_run(d, rounds=3, gap=1.2):
+    for _ in range(rounds):
+        hit = False
+        for t in FIRST_RUN_DISMISS_TEXTS:
+            try:
+                c = d.find_component(BY.text(t))
+                if c is not None:
+                    d.touch(BY.text(t)); time.sleep(gap); hit = True; break
+            except Exception:
+                pass
+        if not hit:
+            return
+
+# ② 首页 tab 归位：应用默认落在非目标 tab（如广场）时点回目标 tab（HOME_TAB 应用级配置）
+def ensure_home_tab(d, tab_text, timeout=10):
+    t0 = time.time()
+    while time.time() - t0 < timeout:
+        try:
+            if d.find_component(BY.text(tab_text)) is not None:
+                d.touch(BY.text(tab_text)); time.sleep(1.5); return True
+        except Exception:
+            pass
+        time.sleep(0.8)
+    return False
+
+# ③ 冷启三件套：launch 内自动执行——弹窗 dismiss + tab 归位（HOME_TAB 非空时）
+HOME_TAB = ""  # 应用级：主功能 tab 文案（如 "玩安卓"）；空串跳过归位
+
+
+def launch(d, want="", reset_data=False, force=False):
+    """v3-①②（EXEC-034）：want=启动参数（'k=v;k2=v2' → hdc aa start --ps 透传，启动参数门控应用免人工补丁）；
+    reset_data=True → bm clean -n 清应用数据（用例级状态重置，防跨用例泄漏）；
+    force=True → 强制冷启（断言冷启行为的用例用）。
+    热启动（run_direct 组内非首条置 FORGE_WARM_LAUNCH=1）：HOME_ANCHOR 已在位即软复用
+    当前会话跳过 stop/start/bootstrap（省冷启 8-12s/例）；锚不可见自动回退完整冷启。"""
+    import os as _os, subprocess as _sp
+    if not want and not reset_data and not force and _os.environ.get("FORGE_WARM_LAUNCH") == "1":
+        anchor = globals().get("HOME_ANCHOR", "")
+        if anchor:
+            try:
+                if d.find_component(BY.key(anchor)) is not None:
+                    return  # 基座已就位：软复用（上一用例恰好停在本页）
+            except Exception:
+                pass
+    d.stop_app(PACKAGE)
+    time.sleep(0.8)
+    if reset_data:
+        hdc = _os.environ.get("FORGE_HDC", "hdc")
+        dev = _os.environ.get("FORGE_DEVICE", "127.0.0.1:5555")
+        try:
+            # DEVIATION-3: bm clean 不带 -d 时仅清 cache(-c),持久化不清,用例间状态泄漏
+            # (TC02 关 answer 残留致 TC03/08/09 连锁失败);本机 bm 无 -b 选项,-d 清数据
+            _sp.run([hdc, "-t", dev, "shell", "bm", "clean", "-n", PACKAGE, "-d"],
+                    capture_output=True, timeout=15)
+            time.sleep(0.5)
+        except Exception as e:
+            print("  [reset] bm clean 失败:", e)
+    if want:
+        hdc = _os.environ.get("FORGE_HDC", "hdc")
+        dev = _os.environ.get("FORGE_DEVICE", "127.0.0.1:5555")
+        args = ["aa", "start", "-b", PACKAGE, "-a", ABILITY]
+        for kv in want.split(";"):
+            if "=" in kv:
+                k, v = kv.split("=", 1)
+                # DEVIATION-1: aa start 的 --ps 只接受空格分隔 key value,等号形式报
+                # "invalid number of parameters for option --ps" 导致带参启动全部失败
+                args += ["--ps", k, v]
+        # EXEC-038 修复：带参启动 3 轮重试 + 实测探活（FORGE_WANT_PROBE=key，可寻才算活）
+        probe = _os.environ.get("FORGE_WANT_PROBE", "")
+        for attempt in range(3):
+            try:
+                _sp.run([hdc, "-t", dev, "shell", "aa", "force-stop", PACKAGE], capture_output=True, timeout=10)
+                time.sleep(0.8)
+                _sp.run([hdc, "-t", dev, "shell"] + args, capture_output=True, timeout=15)
+                time.sleep(3.0)
+                if probe:
+                    c = None
+                    try:
+                        c = d.find_component(BY.key(probe))
+                    except Exception:
+                        pass
+                    if c is None:
+                        print(f"  [want] 第{attempt+1}轮探活失败(key={probe})，重试")
+                        time.sleep(1.5)
+                        continue
+                _dismiss_first_run(d)
+                return
+            except Exception as e:
+                print("  [want] 带参启动异常，重试:", e)
+                time.sleep(1.5)
+        print("  [want] 3 轮未探活成功，继续交由断言暴露")
+    d.start_app(PACKAGE, ABILITY)
+    ok = bootstrap(d, home_tab=HOME_TAB, anchor_key=HOME_ANCHOR)
+    if not ok:
+        raise AssertionError("L0 bootstrap failed（弹窗/tab 未消化，见日志快照）")
+    time.sleep(1.5)  # bootstrap 锚已验证就位，1.5s 落座余量（原 2.5s）
+    _dismiss_first_run(d)
+
+
+def _dismiss_first_run(d):
+    """首启弹窗一键处置（权限/隐私协议）——单 RPC 拉全文案本地匹配"""
+    vis = set(_visible_clickables(d))
+    for txt in ["同意并继续", "允许", "我知道了", "暂不", "以后再说", "同意"]:
+        if txt not in vis:
+            continue
+        try:
+            c = d.find_component(BY.text(txt))
+            if c:
+                c.click()
+                time.sleep(0.8)
+                vis = set(_visible_clickables(d))  # 点掉一层后重扫（可能叠弹窗）
+        except Exception:
+            pass
+
+
+def stop(d):
+    d.stop_app(PACKAGE)
+
+
+def nav_to(d, page):
+    """导航到目标页：入口页直接用；非入口页用返回键回根后再走用例自带链（由用例 steps 驱动）"""
+    if page == ENTRY_PAGE:
+        return
+    # 返回根页（最多 5 次）
+    for _ in range(5):
+        try:
+            if d.find_component(BY.key("__never__")) is None:
+                pass
+        except Exception:
+            pass
+        d.press_back()
+        time.sleep(0.4)
+
+
+TAB_LABELS = ["首页", "视频", "我的"]
+
+
+def click_tab(d, label):
+    """底部 Tab 切换：定位文本→bounds 中心 touch（比例坐标兜底）"""
+    import time as _t
+    for _ in range(8):
+        try:
+            comps = d.find_all_components(BY.text(label))
+            if comps:
+                c = comps[-1]  # 底部 tab 是同名文本中最靠下的
+                b = c.getBounds()
+                cx = (b.left + b.right) // 2
+                cy = (b.top + b.bottom) // 2
+                d.touch((int(cx), int(cy)))
+                _t.sleep(1.2)
+                return
+        except Exception:
+            pass
+        _t.sleep(0.25)
+    idx = TAB_LABELS.index(label) if label in TAB_LABELS else 2
+    w, h = d.get_display_size()
+    d.touch((int(w * (idx + 0.5) / len(TAB_LABELS)), int(h * 0.945)))
+    time.sleep(1.2)
+
+
+def click_text(d, txt, wait=6):
+    """按可见文本点击（tab 名/中文按钮等无 ID 控件）。
+    先试 BY.key——无下划线的单词 id（如 fab）无法与文本区分（_is_id_like 局限），此处兜底。"""
+    import time as _t
+    try:
+        c = d.find_component(BY.key(txt))
+        if c:
+            c.click()
+            _t.sleep(1.0)
+            return
+    except Exception:
+        pass
+    deadline = _t.time() + _w(wait)
+    while _t.time() < deadline:
+        try:
+            c = d.find_component(BY.text(txt, MatchPattern.CONTAINS))
+            if c:
+                c.click()
+                _t.sleep(1.0)
+                return
+        except Exception:
+            pass
+        _t.sleep(0.25)
+    raise AssertionError("text not clickable: " + txt)
+
+
+def click_type_first(d, ctype, wait=6):
+    """点击指定类型的第一个组件（lineN:Type 引用的兜底点击）"""
+    import time as _t
+    deadline = _t.time() + _w(wait)
+    while _t.time() < deadline:
+        try:
+            comps = d.find_all_components(BY.type(ctype))
+            if comps:
+                b = comps[0].getBounds()
+                d.touch(((b.left + b.right) // 2, (b.top + b.bottom) // 2))
+                _t.sleep(1.2)
+                return
+        except Exception:
+            pass
+        _t.sleep(0.25)
+    raise AssertionError("type not clickable: " + ctype)
+
+
+def id_click(d, cid, wait=6):
+    comp = _find(d, cid, wait)
+    comp.click()
+    time.sleep(1.0)
+
+
+def id_input(d, cid, text, wait=6):
+    comp = _find(d, cid, wait)
+    d.input_text(comp, text)
+    time.sleep(0.6)
+
+
+def _find(d, cid, wait=6):
+    import time as _t
+    deadline = _t.time() + _w(wait)
+    while _t.time() < deadline:
+        try:
+            c = d.find_component(BY.key(cid))
+            if c:
+                return c
+        except Exception:
+            pass
+        try:
+            c = d.find_component(BY.id(cid))
+            if c:
+                return c
+        except Exception:
+            pass
+        _t.sleep(0.25)
+    raise AssertionError("component not found: " + cid)
+
+
+def smart_click(d, cid, txt=None, wait=6):
+    """key 优先点击；失败且有 txt 时文本点击（mine 类 HAR 模块 ID 丢失边界）"""
+    import time as _t
+    deadline = _t.time() + _w(wait)
+    while _t.time() < deadline:
+        try:
+            c = d.find_component(BY.key(cid))
+            if c:
+                c.click()
+                _t.sleep(1.0)
+                return
+        except Exception:
+            pass
+        _t.sleep(0.25)
+    if txt and txt.startswith("line"):
+        import re as _re
+        m = _re.match(r"line\d+:(\w+)", txt)
+        if m:
+            click_type_first(d, m.group(1), wait)
+            return
+    if txt:
+        click_text(d, txt, wait)
+        return
+    raise AssertionError("component not found: " + cid)
+
+
+def scroll_text_exist(d, txt, wait=6):
+    """滚动查找文本，双向（EXEC-005）：上滑 N 次找 → 未中则下滑回落 N 次找。
+    单向滚动在连续断言场景必挂：上一断言滑到底后，本断言目标在上方，单向永远回不去。"""
+    import time as _t
+    w, h = d.get_display_size()
+    def _check():
+        try:
+            return d.find_component(BY.text(txt, MatchPattern.CONTAINS)) is not None
+        except Exception:
+            return False
+    for direction in (UiParam.UP, UiParam.DOWN):
+        for i in range(6):
+            if _check():
+                return True
+            d.swipe(direction, distance=40)
+            _t.sleep(1.0)
+    return text_exist(d, txt, wait)
+
+
+def smart_check(d, cid, txt=None, wait=6):
+    """key 优先断言；失败且有 txt 时降级文本断言（部分 HAR 模块 .id 运行时丢弃的边界）"""
+    import time as _t
+    deadline = _t.time() + _w(wait)
+    while _t.time() < deadline:
+        try:
+            c = d.find_component(BY.key(cid))
+            if c:
+                return True
+        except Exception:
+            pass
+        _t.sleep(0.25)
+    if txt and txt.startswith("line"):
+        import re as _re
+        m = _re.match(r"line\d+:(\w+)", txt)
+        if m:
+            d.check_component_exist(BY.type(m.group(1)), wait_time=wait)
+            return True
+    if txt:
+        return text_exist(d, txt, wait)
+    raise AssertionError("component not found: " + cid)
+
+
+def text_equals(d, txt, wait=6):
+    """精确文本断言（EQUALS）——CONTAINS 会被前缀污染（如 ❄️Gallery 含 Gallery），
+    恢复/状态标记类断言必须用本原语。存在且精确相等返回 True，否则抛。"""
+    import time as _t
+    deadline = _t.time() + _w(wait)
+    while _t.time() < deadline:
+        try:
+            c = d.find_component(BY.text(txt))
+            if c:
+                return True
+        except Exception:
+            pass
+        _t.sleep(0.25)
+    raise AssertionError("text (exact) not found: " + txt)
+
+
+def text_absent(d, txt, wait=3):
+    """文本不存在断言（反向；等待短暂稳定后确认消失）"""
+    import time as _t
+    _t.sleep(1.0)
+    try:
+        c = d.find_component(BY.text(txt, MatchPattern.CONTAINS))
+        if c:
+            raise AssertionError("text should be absent but found: " + txt)
+    except AssertionError:
+        raise
+    except Exception:
+        pass
+    return True
+
+
+def step_shot(d, label="step"):
+    """分步截图：一个动作/断言一张页面图（run_direct 设 FORGE_SHOT_DIR/FORGE_CASE 时启用）。
+    文件名 <case>_<序号>_<label>.jpeg，供 test-report.html 按步回放页面。
+    FORGE_SHOT_MODE=off 时跳过；fail 模式下 PASS 用例的过程图由 run_direct 统一清理。"""
+    import os as _os
+    if _os.environ.get("FORGE_SHOT_MODE") == "off":
+        return
+    base = _os.environ.get("FORGE_SHOT_DIR")
+    case = _os.environ.get("FORGE_CASE", "case")
+    if not base:
+        return
+    n = step_shot.n.get(case, 0) + 1
+    try:
+        d.screenshot(_os.path.join(base, "%s_%02d_%s.jpeg" % (case, n, label)))
+        step_shot.n[case] = n
+    except Exception:
+        pass
+
+
+step_shot.n = {}
+
+
+def wait_for(d, by, timeout=10, interval=0.5):
+    """轮询等待控件出现（首屏锚点等待用）；返回组件或 None，不抛异常"""
+    import time as _t
+    end = _t.time() + _w(timeout)
+    while _t.time() < end:
+        try:
+            c = d.find_component(by)
+            if c:
+                return c
+        except Exception:
+            pass
+        _t.sleep(interval)
+    return None
+
+
+def text_exist(d, txt, wait=6):
+    """文本存在断言（BY.text CONTAINS）。
+    契约：存在返回 True；不存在【抛 AssertionError】——永不返回 False。
+    run_direct/analyze_results 依赖异常文本做 FAIL 判定与失败聚类，勿改为静默返回。"""
+    import time as _t
+    deadline = _t.time() + _w(wait)
+    while _t.time() < deadline:
+        try:
+            c = d.find_component(BY.text(txt, MatchPattern.CONTAINS))
+            if c:
+                return True
+        except Exception:
+            pass
+        _t.sleep(0.25)
+    raise AssertionError("text not found: " + txt)
+
+
+def text_value_equals(d, cid, expected, wait=6):
+    """值断言（EXEC-040 实证+反证）：getText() 精确等于期望——锚定 key 控件动态内容。"""
+    import time as _t
+    deadline = _t.time() + _w(wait)
+    while _t.time() < deadline:
+        try:
+            c = d.find_component(BY.key(cid))
+            if c and c.getText() == expected:
+                return True
+        except Exception:
+            pass
+        _t.sleep(0.25)
+    got = None
+    try:
+        c = d.find_component(BY.key(cid))
+        got = c.getText() if c else '(not found)'
+    except Exception:
+        pass
+    raise AssertionError(f"text value mismatch: expect {expected!r} got {got!r} (key={cid})")
+
+
+def text_value_contains(d, cid, part, wait=6):
+    """值包含断言：getText() 包含子串（动态文案前缀不定时用）。"""
+    import time as _t
+    deadline = _t.time() + _w(wait)
+    while _t.time() < deadline:
+        try:
+            c = d.find_component(BY.key(cid))
+            if c and part in (c.getText() or ''):
+                return True
+        except Exception:
+            pass
+        _t.sleep(0.25)
+    raise AssertionError(f"text value not containing {part!r} (key={cid})")
+
+
+def count_equals(d, target, expected, wait=6):
+    """计数断言（EXEC-040 实证）：key 或 CONTAINS 文本匹配的组件数==期望。"""
+    import time as _t, re as _re
+    deadline = _t.time() + _w(wait)
+    last = -1
+    while _t.time() < deadline:
+        try:
+            if _re.match(r'^[a-z][a-z0-9_]+$', target):
+                comps = d.find_all_components(BY.key(target))
+            else:
+                comps = d.find_all_components(BY.text(target, MatchPattern.CONTAINS))
+            last = len(comps) if comps else 0
+            if last == expected:
+                return True
+        except Exception:
+            pass
+        _t.sleep(0.25)
+    raise AssertionError(f"count mismatch: expect {expected} got {last} (target={target})")
+
+
+def is_below(d, cid, ref_cid, wait=6):
+    """几何断言（EXEC-040 实证）：cid 的 top >= ref_cid 的 bottom（垂直次序）。"""
+    import time as _t
+    deadline = _t.time() + _w(wait)
+    while _t.time() < deadline:
+        try:
+            a = d.find_component(BY.key(cid)); b = d.find_component(BY.key(ref_cid))
+            if a and b and a.getBounds().top >= b.getBounds().bottom:
+                return True
+        except Exception:
+            pass
+        _t.sleep(0.25)
+    raise AssertionError(f"geometry: {cid} not below {ref_cid}")
+
+
+def toast_exist(d, txt, wait=4, poll=0.5):
+    """Toast 断言（v3.1）：轮询 hilog 捕获 Toast 文本。需 FORGE_HDC/FORGE_DEVICE。"""
+    import os as _os, subprocess as _sp, time as _tt
+    hdc = _os.environ.get("FORGE_HDC", "hdc"); dev = _os.environ.get("FORGE_DEVICE", "127.0.0.1:5555")
+    deadline = _tt.time() + _w(wait)
+    while _tt.time() < deadline:
+        try:
+            r = _sp.run([hdc, "-t", dev, "shell", "hilog", "-x"],
+                        capture_output=True, timeout=8, text=True, errors="ignore")
+            if txt in (r.stdout or ""):
+                return True
+        except Exception:
+            pass
+        _tt.sleep(poll)
+    raise AssertionError("toast not found in hilog: " + txt)
+
+
+# ── 强断言原语（2026-09-29 吸收自 none 臂实证：无 skill 的 LLM 凭通用能力即达成 34% 强断言，
+#     B 线无理由低于此——Toast/系统事件/数据断言按下表选型，禁止只写 exist）──
+def _hdc(args, timeout=20):
+    import subprocess as _sp, os as _os
+    dev = _os.environ.get("FORGE_DEVICE", "127.0.0.1:5555")
+    cmd = [HDC_BIN, "-t", dev] + args
+    r = _sp.run(cmd, capture_output=True, timeout=timeout)
+    return (r.stdout + r.stderr).decode("utf-8", "ignore")
+
+
+def _dump_layout(timeout=20):
+    """取当前全量布局 JSON（含系统对话框/浮层），返回原始文本（Round-2：确保本地 tmp 目录存在）"""
+    import json as _json, os as _os
+    _os.makedirs("./tmp", exist_ok=True)
+    _hdc(["shell", "uitest", "dumpLayout", "-p", "/data/local/tmp/forge_dump.json"], timeout=timeout)
+    _hdc(["file", "recv", "/data/local/tmp/forge_dump.json", "./tmp/forge_dump.json"], timeout=timeout)
+    try:
+        return open("./tmp/forge_dump.json", encoding="utf-8").read()
+    except Exception:
+        return ""
+
+
+def hilog_clear():
+    """清 hilog 缓冲，防止上一用例残留关键字造成假 PASS（tag=RaiseToAnswer）"""
+    _hdc(["shell", "hilog", "-r"])
+    time.sleep(0.3)
+
+
+HILOG_TAG = 'JSAPP'
+
+
+def hilog_tail(tag=None, n=400):
+    tag = tag or HILOG_TAG
+    """读取 tag 过滤的最近 n 行 hilog（诊断用）"""
+    import subprocess as _sp, os as _os
+    dev = _os.environ.get("FORGE_DEVICE", "127.0.0.1:5555")
+    r = _sp.run([HDC_BIN, "-t", dev, "shell", "hilog", "-z", str(n), "-T", tag],
+                capture_output=True, timeout=15)
+    return r.stdout.decode("utf-8", "ignore")
+
+
+def toast_text_seen(d, txt, timeout=6):
+    """Toast 文本断言（dump 版）。无 ID 例外：Toast 为瞬时浮层无稳定 ID，且 hypium find_component
+    实测看不到 Toast 子窗口，故以 uitest dumpLayout 原文轮询（首轮实测教训 Round-1）。"""
+    deadline = time.time() + _w(timeout)
+    while time.time() < deadline:
+        raw = _dump_layout()
+        if txt in raw:
+            return True
+        time.sleep(0.6)
+    raise AssertionError("toast not seen: " + txt)
+
+
+def bm_clean():
+    """清应用持久化数据（公开包装；import * 不导出 _ 前缀——Round-1 教训）"""
+    _hdc(["shell", "bm", "clean", "-n", PACKAGE, "-d"])
+    time.sleep(0.6)