@harmonyos-arkts/d2h 0.1.2 → 0.1.5

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

@@ -0,0 +1,249 @@
+#!/usr/bin/env python3
+"""
+merge_appgraph.py — AppGraph(analyze android) facts × forge scan_features 语义合并。
+
+定位：scan_features 只见鸿蒙侧静态树（.id/行号/if 分支），缺行为语义；
+AppGraph facts 是安卓权威行为账本（控件/入口/事件/handler/callTrace/导航边/trigger 分类），
+但无鸿蒙侧定位事实。本脚本按 token 集合 join（answerFeature ↔ feature_answer_switch）
+把 Android 语义注入 features.json，产出同名 schema 的增强版，供 evaluate_coverage /
+用例设计（handler 名直接揭示联动语义）/ agent 融合（ref 体系对齐迁移报告）消费。
+
+用法:
+  merge_appgraph.py --features features.json --facts <android>/.migration/spec/facts \
+                    [--out features.merged.json]
+无 AppGraph facts 时退出码 2（调用方回退纯 scan_features）。
+"""
+import argparse
+import glob
+import json
+import os
+import re
+
+
+def tokens(s):
+    """camelCase + snake_case 统一切词：answerFeature 与 feature_answer → {answer, feature}。"""
+    parts = [p.lower() for p in re.findall(r'[A-Z]?[a-z0-9]+', str(s or ''))]
+    return set(parts) - {'menu', 'click', 'button', 'entry', 'the', 'id', 'app'}
+
+
+def norm_name(s):
+    return re.sub(r'[^a-z0-9]', '', str(s or '').lower())
+
+
+def join_key_candidates(name):
+    t = tokens(name)
+    return t, norm_name(name)
+
+
+def match(names, pool, event=None):
+    """names: 候选语义名（carrier/label/event 提取）；规则：norm 相等 > token 全等 >
+    android ⊂ forge id（容许 _switch 类小后缀）；checked 类事件优先 *_switch 目标。"""
+    for name in names:
+        if not name:
+            continue
+        ct, cn = tokens(name), norm_name(name)
+        if not ct and not cn:
+            continue
+        for ft in sorted(pool):
+            if cn and norm_name(ft) == cn:
+                return ft
+        cands = []
+        for ft in sorted(pool):
+            ftt = tokens(ft)
+            if not ftt or not ct:
+                continue
+            if ct == ftt:
+                cands.append((0, ft))
+            elif ct < ftt and len(ftt) <= len(ct) + 2:
+                cands.append((1, ft))
+        if not cands:
+            continue
+        cands.sort()
+        if event and str(event).startswith('checked'):
+            for _, ft in cands:
+                if 'switch' in ft or 'toggle' in ft:
+                    return ft
+        return cands[0][1]
+    return None
+
+
+def event_tokens(event):
+    """menu-click:privacy_policy → ['privacy_policy']；checked-change → []。"""
+    m = re.match(r'^menu-click:(\w+)$', str(event or ''))
+    return [m.group(1)] if m else []
+
+
+def harvest_ids(project_dir):
+    """收割工程内可静态定位的 ID：.id('x') 字面量 + 组件参数 *Id: 'x'（如 rowId）。
+    模板拼接 .id(`${rowId}_switch`) 无法静态解析，由 prop 值 + 已知后缀兜底。"""
+    pool = {}
+    root = os.path.join(project_dir or '.', '')
+    for path in glob.glob(os.path.join(root, '**', '*.ets'), recursive=True):
+        if os.sep + 'ohosTest' in path or os.sep + '.hypium_forge' in path:
+            continue
+        try:
+            src = open(path, encoding='utf-8').read()
+        except Exception:
+            continue
+        for m in re.finditer(r"\.id\(\s*['\"`]([\w-]+)['\"`]\s*\)", src):
+            line = src[:m.start()].count('\n') + 1
+            pool.setdefault(m.group(1), {'file': os.path.relpath(path, root), 'line': line})
+        for m in re.finditer(r"\b\w*[Ii]d\s*:\s*['\"]([\w-]+)['\"]", src):
+            for cand in (m.group(1), f"{m.group(1)}_switch"):
+                pool.setdefault(cand, {'file': os.path.relpath(path, root), 'line': src[:m.start()].count('\n') + 1})
+    return pool
+
+
+def load_appgraph(facts_dir):
+    controls, entries, nav = [], [], []
+    inter_path = os.path.join(facts_dir, 'interactions.json')
+    if os.path.isdir(facts_dir):
+        pages = sorted(glob.glob(os.path.join(facts_dir, 'pages', '*.json')))
+    else:
+        pages = []
+    for p in pages:
+        if os.path.basename(p) == 'index.json' or os.path.basename(p) == 'unassigned.json':
+            continue
+        try:
+            d = json.load(open(p, encoding='utf-8'))
+        except Exception:
+            continue
+        controls += d.get('controls', []) or []
+        entries += d.get('entries', []) or []
+    if os.path.exists(inter_path):
+        try:
+            nav = json.load(open(inter_path, encoding='utf-8')).get('interactions', []) or []
+        except Exception:
+            nav = []
+    return controls, entries, nav
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument('--features', required=True)
+    ap.add_argument('--facts', required=True)
+    ap.add_argument('--out', default=None)
+    args = ap.parse_args()
+
+    if not os.path.isdir(args.facts):
+        print(f'[x] AppGraph facts 不存在: {args.facts}')
+        raise SystemExit(2)
+    feats = json.load(open(args.features, encoding='utf-8'))
+    controls, entries, nav = load_appgraph(args.facts)
+    if not entries and not controls:
+        print('[x] facts 为空，回退 scan_features')
+        raise SystemExit(2)
+
+    forge_targets = []
+    for pg in feats.get('pages', []):
+        for it in pg.get('interactions', []):
+            forge_targets.append(it.get('target'))
+    id_pool = harvest_ids(feats.get('project_dir', '.'))
+    pool = set(forge_targets) | set(id_pool.keys())
+
+    android_entries = []
+    for e in entries:
+        rec = {
+            'name': e.get('carrierName') or e.get('displayLabel'),
+            'event': e.get('event'),
+            'handlers': e.get('handlerNames', []) or [],
+            'trigger': e.get('triggerCategory'),
+            'ref': e.get('entryRef'),
+            'label': e.get('displayLabel'),
+            'android_evidence': (e.get('sourceEvidence') or [{}])[0].get('file', ''),
+        }
+        android_entries.append(rec)
+
+    android_controls = []
+    for c in controls:
+        android_controls.append({
+            'name': c.get('name'),
+            'ref': c.get('controlRef'),
+            'evidence': (c.get('sourceEvidence') or [{}])[0].get('file', ''),
+        })
+
+    matched, unmatched = {}, []
+    for ae in android_entries:
+        if ae['trigger'] != 'user':
+            continue
+        cand = [ae['name'], ae['label']] + event_tokens(ae['event'])
+        ft = match(cand, pool, ae['event'])
+        if ft:
+            ae['forge_target'] = ft
+            matched.setdefault(ft, []).append(ae)
+        else:
+            unmatched.append(ae)
+
+    nav_edges = [{'from': n.get('fromRef'), 'to': n.get('toRef'), 'relation': n.get('relation')}
+                 for n in nav]
+
+    enriched_pages = []
+    for pg in feats.get('pages', []):
+        for it in pg.get('interactions', []):
+            hits = matched.get(it.get('target'), [])
+            if hits:
+                h = hits[0]
+                it['android_event'] = h['event']
+                it['android_handlers'] = h['handlers']
+                it['android_ref'] = h['ref']
+                it['android_evidence'] = h['android_evidence']
+        enriched_pages.append(pg)
+
+    entry_path = next((p['path'] for p in enriched_pages if enriched_pages and p['path'] == feats.get('entry', {}).get('page')),
+                      enriched_pages[0]['path'] if enriched_pages else None)
+    entry_idx = next((i for i, p in enumerate(enriched_pages) if p['path'] == entry_path), 0)
+
+    def owner_unit(h, loc):
+        """归属：checked-change → 拥有 lineN:Toggle 的组件单元（并移除被具体化的 lineN）；
+        其余 → 入口页。"""
+        if str(h['event']).startswith('checked'):
+            for i, p in enumerate(enriched_pages):
+                for it in p.get('interactions', []):
+                    if str(it.get('target', '')).startswith('line') and it.get('type') == 'Toggle':
+                        p['interactions'] = [x for x in p['interactions'] if x is not it]
+                        return i
+        return entry_idx
+
+    for ft, hits in matched.items():
+        if any(ft == it.get('target') for pg in enriched_pages for it in pg.get('interactions', [])):
+            continue
+        loc = id_pool.get(ft, {})
+        h = hits[0]
+        enriched_pages[owner_unit(h, loc)]['interactions'].append({
+            'kind': 'click' if 'click' in str(h['event']) else 'toggle',
+            'target': ft,
+            'desc': f"android:{h['name']}({h['event']})",
+            'has_id': ft in id_pool,
+            'line': loc.get('line', 0),
+            'type': 'IdRef',
+            'android_event': h['event'],
+            'android_handlers': h['handlers'],
+            'android_ref': h['ref'],
+            'android_evidence': h['android_evidence'],
+            'android_file': loc.get('file', ''),
+        })
+
+    feats['pages'] = enriched_pages
+    feats['android'] = {
+        'controls': android_controls,
+        'entries_user': [e for e in android_entries if e['trigger'] == 'user'],
+        'entries_system': [e for e in android_entries if e['trigger'] != 'user'],
+        'nav_edges': nav_edges,
+        'unmatched_user_entries': unmatched,
+        'source': args.facts,
+    }
+
+    out = args.out or args.features.replace('.json', '.merged.json')
+    json.dump(feats, open(out, 'w', encoding='utf-8'), ensure_ascii=False, indent=1)
+    print(f'合并完成: controls={len(android_controls)} user入口={len(feats["android"]["entries_user"])} '
+          f'系统入口={len(feats["android"]["entries_system"])} join命中={len(matched)}/{len(matched)+len(unmatched)} '
+          f'导航边={len(nav_edges)} → {out}')
+    for ft, hits in sorted(matched.items()):
+        for h in hits:
+            print(f'  [+] {h["name"]}({h["event"]}) → {ft}  handlers={h["handlers"]}')
+    for u in unmatched:
+        print(f'  [?] 未join: {u["name"]} ({u["event"]}) handlers={u["handlers"]}')
+
+
+if __name__ == '__main__':
+    main()

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

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""
+precondition.py — 测试前置自动化：权限预授 + 登录/账号策略 + 首启弹窗处理。
+
+原则（项目经验 2）:
+  所有权限和账号默认优先完成确认/登录；无法自动完成的，生成明确的用户提醒清单
+  （而非留到用例执行中反复失败）。
+
+动作:
+  1. 解析 module.json5 权限 → hdc pm grant 预授（按 ACL 级别分类:
+     normal/system_basic → 尝试预授；user_grant 运行时权限 → 模拟器上多数可 grant）
+  2. 登录页检测 → 三级策略:
+     a. mock 登录入口（源码含"模拟登录"）→ 自动用之
+     b. UI 自动化登录（已知测试账号）→ 提醒用户提供或用环境变量
+     c. 不可自动 → 用户提醒清单
+  3. 首启弹窗预处置（隐私协议/权限弹窗）→ 输出 dismiss 脚本片段
+
+用法:
+  precondition.py --features features.json --device 127.0.0.1:5555 [--user-account-env HM_TEST_ACCOUNT]
+输出: preconditions.md（执行结果 + 用户提醒清单）
+"""
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+
+HDC = '/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/toolchains/hdc'
+
+# 鸿蒙权限 → 授予难度（默认可 grant / 需弹窗确认 / 系统级不可授）
+GRANTABLE = re.compile(r'ohos\.permission\.(INTERNET|GET_NETWORK_INFO|KEEP_BACKGROUND_RUNNING|'
+                       r'REQUIRE_FORM|PUBLISH_AGENT_REMINDER|VIBRATE|QUERY_AUDIO_DEVICE_STATE)')
+# 运行时弹窗类（模拟器可 pm grant）
+RUNTIME = re.compile(r'ohos\.permission\.(READ_|WRITE_|MICROPHONE|CAMERA|LOCATION|MEDIA|'
+                     r'APPTRACKING|CALENDAR|CONTACTS|DISTRIBUTED)')
+# 用户身份类（不可自动，需用户操作）
+USER_IDENTITY = re.compile(r'ohos\.permission\.(USER_AUTH|MANAGE_FINGERPRINT|ACCESS_USER_AUTH|'
+                           r'SECURE_SESSION|READ_HEALTH|SPORT)')
+
+
+def hdc(device, *args, capture=True):
+    cmd = [HDC, '-t', device] + list(args)
+    try:
+        r = subprocess.run(cmd, capture_output=capture, text=True, timeout=30)
+        return (r.stdout or '') + (r.stderr or '')
+    except Exception as e:
+        return f'ERROR: {e}'
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument('--features', required=True)
+    ap.add_argument('--device', default='127.0.0.1:5555')
+    ap.add_argument('--bundle', default=None)
+    ap.add_argument('--test-account-env', default='HM_TEST_ACCOUNT',
+                    help='测试账号环境变量名（格式 user:pass）')
+    args = ap.parse_args()
+
+    feats = json.load(open(args.features, encoding='utf-8'))
+    bundle = args.bundle or feats.get('bundle')
+    if not bundle:
+        print('错误: 无法确定 bundleName', file=sys.stderr)
+        sys.exit(1)
+
+    report = [f'# 测试前置报告（{bundle} @ {args.device}）', '']
+    reminders = []
+
+    # ── 1. 权限预授 ──
+    report.append('## 权限预授')
+    ok, skipped, user_confirm = [], [], []
+    for perm in feats.get('permissions', []):
+        if USER_IDENTITY.search(perm):
+            user_confirm.append(perm)
+            continue
+        if GRANTABLE.search(perm) or RUNTIME.search(perm):
+            out = hdc(args.device, 'shell', 'atm', 'perm', '-g', bundle, perm)
+            granted = 'grant' in out.lower() and 'fail' not in out.lower()
+            if not granted:
+                out2 = hdc(args.device, 'shell', f'pm grant {bundle} {perm}')
+                granted = 'fail' not in out2.lower() and 'Exception' not in out2
+            (ok if granted else skipped).append(perm)
+        else:
+            skipped.append(perm)
+    report.append(f'- 已预授 {len(ok)}: {", ".join(ok) or "无"}')
+    if skipped:
+        report.append(f'- 跳过 {len(skipped)}（授予失败或需特殊签名）: {", ".join(skipped)}')
+    if user_confirm:
+        report.append(f'- 需用户在设备上确认: {", ".join(user_confirm)}')
+        reminders.append(f'身份类权限需手动确认: {", ".join(user_confirm)}')
+    report.append('')
+
+    # ── 2. 登录策略（用户 2026-09-27 指正：不能止步于标 BLOCKED，必须提醒用户三选一）──
+    report.append('## 登录/账号策略')
+    if feats.get('has_login'):
+        acct = os.environ.get(args.test_account_env, '')
+        if acct:
+            report.append(f'- 检测到登录页；使用环境变量 {args.test_account_env} 提供的测试账号（自动登录用例将启用）')
+        else:
+            report.append('- 检测到登录页；**未设置测试账号（export '
+                          f'{args.test_account_env}=user:pass）**。登录域用例暂标 BLOCKED，'
+                          '**请从以下三种方式选择其一解除**：')
+            report.append('  1. **手动登录**：在模拟器/真机上人工完成一次登录（登录态持久，最真实，'
+                          '适合无需反复切换账号的场景）——完成后告知，BLOCKED 用例即可重跑；')
+            report.append('  2. **提供账号密码**：给出测试账号，构造登录用例（输入账号密码→提交→断言登录成功），'
+                          '登录链路本身也被覆盖——需 export 环境变量或直接告知；')
+            report.append('  3. **mock 登录态**：修改代码伪造已登录状态（如 userName 直接赋值）——'
+                          '**注意：这不是真实功能状态**，仅解锁被门禁的功能验证（hn-android FS-41 先例），'
+                          '需在用例/代码注释标明，且登录链路本身仍属未覆盖。')
+            reminders.append('登录域用例 BLOCKED 待解除：手动登录设备 / 提供测试账号 / mock 登录态（三选一，见 preconditions.md）')
+    else:
+        report.append('- 未检测到登录页，无需账号')
+    report.append('')
+
+    # ── 3. 首启弹窗预处置 ──
+    report.append('## 首启弹窗预处置（自动 dismiss 片段，注入 _common.launch）')
+    report.append('```python')
+    report.append('# 常见首启弹窗一键处理（在 launch 后 sleep 1 时执行）')
+    report.append('for txt in ["同意并继续", "允许", "我知道了", "暂不", "以后再说"]:')
+    report.append('    try:')
+    report.append('        c = d.find_component(BY.text(txt))')
+    report.append('        if c: c.click(); time.sleep(0.8)')
+    report.append('    except Exception: pass')
+    report.append('```')
+    report.append('')
+
+    if reminders:
+        report += ['## ⚠️ 用户提醒清单', *[f'- {r}' for r in reminders], '']
+    else:
+        report.append('## 用户提醒清单: 无（全部前置已自动完成）')
+
+    out_md = os.path.join(os.path.dirname(os.path.abspath(args.features)),
+                          'preconditions.md')
+    open(out_md, 'w', encoding='utf-8').write('\n'.join(report))
+    print('\n'.join(report))
+    print(f'\n报告: {out_md}')
+
+
+if __name__ == '__main__':
+    main()

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

@@ -0,0 +1,232 @@
+#!/usr/bin/env python3
+"""preinject_ids.py — ID 预置（铁律①的机械强制，先于脚本编写，不依赖 cases DSL）。
+
+输入 features.json（scan_features 产物），对全部 has_id=False 的交互点批量注入
+`.id('tc_<page>_<n>')`（资源文案/精确模糊文本/行号三路定位，属性链内插桩永远合法），
+输出 ids.json 映射（脚本编写只认此表与既有 ID）。注入后须 rebuild + uninstall&&install。
+
+用法:
+  python3 preinject_ids.py --features features.json [--out ids.json]
+"""
+import argparse
+import glob
+import json
+import os
+import re
+
+TEXT_PAT = re.compile(
+    r"^(\s*)(Text|Button|Toggle|Checkbox|Radio|MenuItem|Image|Row|Column)\("
+    r"[^\n]*?['\"](.*?)['\"][^\n]*\)?\s*$")
+
+
+def read(p):
+    return open(p, encoding='utf-8').read()
+
+
+def insert_after_component(lines, i):
+    depth = 0
+    started = False
+    for k in range(i, min(len(lines), i + 40)):
+        depth += lines[k].count('(') - lines[k].count(')')
+        started = True
+        if started and depth <= 0 and k > i:
+            return k + 1
+        if started and depth < 0:
+            return k
+    return min(len(lines), i + 12)
+
+
+def find_and_inject(page_file, target, seq):
+    """三路定位注入：资源文案 → 精确/模糊文本 → 行号。返回 (id or None, modified_src)。"""
+    src = read(page_file)
+    lines = src.split('\n')
+    tid = f"tc_{os.path.splitext(os.path.basename(page_file))[0].lower()}_{seq}"
+
+    if target and re.search(rf"\.id\(\s*'{re.escape(target)}'", src):
+        return target, src
+
+    if target and 'app.string.' in src:
+        modroot = page_file
+        for _ in range(4):
+            modroot = os.path.dirname(modroot)
+            cand = os.path.join(modroot, 'resources', 'base', 'element', 'string.json')
+            if os.path.exists(cand):
+                resname = None
+                try:
+                    for item in json.load(open(cand, encoding='utf-8')).get('string', []):
+                        if item.get('value') == target:
+                            resname = item.get('name')
+                            break
+                except Exception:
+                    pass
+                if resname:
+                    break
+        if resname:
+            rx = re.compile(r"[\$r]\(\s*'app\.string\." + re.escape(resname) + r"'")
+            for i, ln in enumerate(lines):
+                if rx.search(ln):
+                    for k in range(i, min(len(lines), i + 10)):
+                        if re.match(r'^\s*\.[a-zA-Z]', lines[k]):
+                            indent = re.match(r'(\s*)', lines[k]).group(1)
+                            lines.insert(k, f"{indent}.id('{tid}')")
+                            return tid, '\n'.join(lines)
+                    indent = re.match(r'(\s*)', ln).group(1)
+                    lines.insert(i + 1, f"{indent}  .id('{tid}')")
+                    return tid, '\n'.join(lines)
+
+    if target:
+        for i, ln in enumerate(lines):
+            m = TEXT_PAT.match(ln)
+            if not m:
+                continue
+            if m.group(3) == target or (target in m.group(3) or m.group(3) in target):
+                seg = '\n'.join(lines[i:i + 25])
+                if re.search(r'\.id\(', seg):
+                    idm = re.search(r"\.id\(\s*'([^']+)'", seg)
+                    if idm:
+                        return idm.group(1), src
+                for k in range(i + 1, min(len(lines), i + 15)):
+                    if re.match(r'^\s*\.[a-zA-Z]', lines[k]):
+                        indent = re.match(r'(\s*)', lines[k]).group(1)
+                        lines.insert(k, f"{indent}.id('{tid}')")
+                        return tid, '\n'.join(lines)
+                j = insert_after_component(lines, i)
+                lines.insert(j, f"{m.group(1)}  .id('{tid}')")
+                return tid, '\n'.join(lines)
+
+    tc = re.match(r'line(\d+):(\w+)', target or '')
+    if tc:
+        i = int(tc.group(1)) - 1
+        if 0 <= i < len(lines):
+            for k in range(i + 1, min(len(lines), i + 9)):
+                if re.match(r'^\s*\.[a-zA-Z]', lines[k]):
+                    indent = re.match(r'(\s*)', lines[k]).group(1)
+                    lines.insert(k, f"{indent}.id('{tid}')")
+                    return tid, '\n'.join(lines)
+            for k in range(i, max(0, i - 8), -1):
+                if re.match(r'^\s*\.[a-zA-Z]', lines[k]):
+                    indent = re.match(r'(\s*)', lines[k]).group(1)
+                    lines.insert(k + 1, f"{indent}.id('{tid}')")
+                    return tid, '\n'.join(lines)
+    return None, src
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument('--features', required=True)
+    ap.add_argument('--out', default=None)
+    args = ap.parse_args()
+    feats = json.load(open(args.features, encoding='utf-8'))
+    project = feats['project_dir']
+    out = args.out or os.path.join(os.path.dirname(args.features), 'ids.json')
+    mapping = {}
+    if os.path.exists(out):
+        try:
+            mapping = json.load(open(out, encoding='utf-8'))
+        except Exception:
+            mapping = {}
+    injected = existing = missed = 0
+    for pg in feats.get('pages', []):
+        fpath = pg.get('file')
+        if not fpath or not os.path.exists(fpath):
+            continue
+        seq = 0
+        for it in pg.get('interactions', []):
+            target = it.get('target')
+            desc = it.get('desc')
+            if not target:
+                continue
+            seq += 1
+            key = f"{pg['page']}:{desc or target}"
+            prev = mapping.get(key)
+            if prev and re.search(rf"\.id\(\s*'{re.escape(prev)}'", read(fpath)):
+                existing += 1
+                continue
+            if it.get('has_id'):
+                existing += 1
+                mapping[key] = target
+                continue
+            tid, new_src = find_and_inject(fpath, target, seq)
+            if not tid:
+                tid2, new_src2 = find_and_inject(fpath, f"line{it.get('line')}:{it.get('type')}", seq)
+                tid, new_src = tid2 or tid, new_src2 if tid2 else new_src
+            if tid:
+                disk = read(fpath)
+                if new_src != disk:
+                    open(fpath, 'w', encoding='utf-8').write(new_src)  # 逐次落盘（页尾统一写会丢同页其余注入）
+                    injected += 1
+                else:
+                    existing += 1
+                mapping[key] = tid
+            else:
+                missed += 1
+    for res_id in re.findall(r"\.id\('([a-z][a-z0-9_]+)'\)", '\n'.join(
+            read(p) for p in glob.glob(os.path.join(project, '**', '*.ets'), recursive=True)
+            if 'oh_modules' not in p))[:0]:
+        pass
+    # 连续 .id() 消除（TD-006）：注入点组件已有语义 id 时，删除本轮新插的机械 id，
+    # mapping 改指向已有 id——运行时链式 .id() 后者覆盖前者，机械 id 失效且污染源码
+    import glob as _g
+    fixed = 0
+    for pg in feats.get('pages', []):
+        fp = pg.get('file')
+        if not fp or not os.path.exists(fp):
+            continue
+        try:
+            src = open(fp, encoding='utf-8').read()
+        except Exception:
+            continue
+        new_src = src
+        for m in re.finditer(r"\.id\('(tc_[^']+)'\)\s*\.id\('([^']+)'\)", src):
+            dead, alive = m.group(1), m.group(2)
+            new_src = new_src.replace(f".id('{dead}')\n", '', 1).replace(f".id('{dead}')", '', 1)
+            for k, v in list(mapping.items()):
+                if v == dead:
+                    mapping[k] = alive
+            fixed += 1
+        if new_src != src:
+            open(fp, 'w', encoding='utf-8').write(new_src)
+    # ID 稳定性门禁（TD-013）：旧 ids.json 被用例引用的 id 若在新轮消失 → BLOCKER 阻断，
+    # 禁止静默让用例回退 text 定位（run 期间 id 漂移的机制化防线）
+    old_out = out + '.prev'
+    if os.path.exists(out):
+        import shutil as _sh
+        _sh.copy(out, old_out)
+        try:
+            old_map = json.load(open(old_out, encoding='utf-8'))
+        except Exception:
+            old_map = {}
+        gone = {k: v for k, v in old_map.items() if v not in set(mapping.values())
+                and v not in {m for m in mapping.values()}}
+        if gone:
+            print(f'✗ BLOCKER：上一轮 {len(gone)} 个 id 本轮消失（用例可能引用，禁静默回退 text）：')
+            for k, v in list(gone.items())[:6]:
+                print(f'    {k} → {v}')
+            print('   处置：核对注入冲突/页面改动，或显式重命名并同步全部用例后重跑。')
+    json.dump(mapping, open(out, 'w', encoding='utf-8'), ensure_ascii=False, indent=1)
+    print(f'ID 预置完成: 新注入 {injected} / 已有 {existing} / 未定位 {missed}'
+          f' / 连续id消除 {fixed} → {out}')
+
+    # 语法快速自检：检测连续 .id() 调用（最常见注入冲突）
+    import re as _re
+    _warn = 0
+    for pg in feats.get('pages', []):
+        fp = pg.get('file')
+        if not fp or not os.path.exists(fp):
+            continue
+        try:
+            src = open(fp, encoding='utf-8').read()
+            for m in _re.finditer(r"\.id\(\s*'[^']+'\s*\)\s*\.id\(", src):
+                print(f'  ⚠️ 语法风险: {os.path.basename(fp)} 存在连续 .id() 调用')
+                _warn += 1
+        except Exception:
+            pass
+    if _warn:
+        print(f'⚠️ 发现 {_warn} 处语法风险——建议先跑构建验证再使用 ids.json')
+    else:
+        print('✓ 语法快速检查通过')
+    print('⚠️ 注入后必须 rebuild + uninstall&&install 再执行脚本')
+
+
+if __name__ == '__main__':
+    main()