@harmonyos-arkts/d2h 0.1.2 → 0.1.5

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

@@ -0,0 +1,255 @@
+#!/usr/bin/env python3
+"""
+scan_features.py — 扫描鸿蒙工程，产出功能场景矩阵（features.json + features.md）。
+
+场景矩阵模型（覆盖度评估的基础）:
+  页面（路由可达） × 交互点（可操作控件/事件） × 状态（数据/条件分支）
+
+输出 features.json:
+{
+  "project_dir": "...",
+  "bundle": "hm.xxx",
+  "pages": [
+    {
+      "page": "Index", "path": "pages/Index", "file": "...",
+      "nav_in": ["入口"] ,            # 如何到达（入口/router.pushUrl 链）
+      "interactions": [                # 交互点（含已有 ID）
+        {"kind": "click", "target": "id_or_text", "desc": "设置按钮", "has_id": true}
+      ],
+      "states": [                      # 可区分状态（条件渲染/数据驱动）
+        {"name": "列表为空", "evidence": "if (!items.length)", "line": 42}
+      ],
+      "data_sources": ["mock", "http", "preferences"]
+    }
+  ],
+  "permissions": ["ohos.permission.INTERNET", ...],   # 需预授/确认的权限
+  "has_login": true|false,                            # 登录页检测
+  "nav_graph": {"pages/Index": ["pages/Settings", ...]}  # 静态跳转图
+}
+
+用法: scan_features.py <harmony_project_dir> [--out features.json]
+"""
+import argparse
+import json
+import os
+import re
+import sys
+
+# 登录页特征
+LOGIN_HINTS = ['登录', 'login', 'Login', 'signin', 'SignIn', '账号', '密码', 'password', '手机号']
+# 数据源特征
+DATA_HINTS = {
+    'http': re.compile(r'https?://|@ohos\.net\.http|axios|rcp'),
+    'preferences': re.compile(r'@ohos\.data\.preferences|preferences\.getPreferences'),
+    'mock': re.compile(r'\bmock\b|MockData|EMOJI_DATA|SAMPLE_', re.I),
+    'db': re.compile(r'@ohos\.data\.relationalStore|relationalStore'),
+}
+# 交互控件（组件级）
+INTERACTIVE_COMPONENTS = ('Button', 'TextInput', 'TextArea', 'Toggle', 'Slider',
+                          'Radio', 'Checkbox', 'Select', 'Search', 'Stepper',
+                          'Rating', 'DatePicker', 'TextPicker', 'TimePicker',
+                          'Image', 'Hyperlink', 'Navigator')
+# 非组件关键词（生命周期/builder/容器等误判源）
+NON_COMPONENT = re.compile(r'^(onPageShow|onBackPress|aboutToAppear|aboutToDisappear|'
+                           r'\w*[Bb]uilder|TabContent|ForEach|LazyForEach|Repeat|'
+                           r'Navigation|NavDestination|if|else|while|for|struct|class|build)\b')
+# 风险权限（需用户确认/无法预授）
+RISKY_PERMS = {'ohos.permission.USER_AUTH', 'ohos.permission.MANAGE_FINGERPRINT'}
+
+
+def read(p):
+    try:
+        return open(p, encoding='utf-8', errors='ignore').read()
+    except OSError:
+        return ''
+
+
+def find_pages(root):
+    """定位入口模块与页面集。"""
+    # 找含 UIAbility+loadContent 的模块（entry 或自定义）
+    modules = []
+    for cand in sorted(os.listdir(root)):
+        mdir = os.path.join(root, cand)
+        if os.path.isdir(mdir) and os.path.isdir(os.path.join(mdir, 'src', 'main')):
+            modules.append(cand)
+        elif os.path.isdir(mdir) and cand not in ('oh_modules', '.hypium_forge', 'AppScope', 'hvigor', 'build', 'doc'):
+            # 二级模块容器（features/commons 下可能有独立模块）
+            for sub in sorted(os.listdir(mdir)):
+                sdir = os.path.join(mdir, sub)
+                if os.path.isdir(os.path.join(sdir, 'src', 'main')):
+                    modules.append(f'{cand}/{sub}')
+
+    pages = {}
+    nav_graph = {}
+    entry_module, entry_page = None, None
+    for m in modules:
+        mdir = os.path.join(root, m, 'src', 'main')
+        # Ability 的 loadContent
+        for dp, _d, files in os.walk(os.path.join(mdir, 'ets')):
+            for f in files:
+                if f.endswith('.ets'):
+                    src = read(os.path.join(dp, f))
+                    mm = re.search(r"loadContent\(\s*'([^']+)'", src)
+                    if mm and entry_page is None:
+                        entry_module, entry_page = m, mm.group(1)
+        # 路由表（可能多个）
+        for dp, _d, files in os.walk(os.path.join(mdir, 'resources')):
+            for f in files:
+                if f.endswith('_pages.json'):
+                    try:
+                        routes = json.load(open(os.path.join(dp, f))).get('src', [])
+                    except (OSError, json.JSONDecodeError):
+                        routes = []
+                    for r in routes:
+                        pages.setdefault((m, r), None)
+        # @Entry 页面兜底（覆盖路由表留下的 None 值）
+        ets_root = os.path.join(mdir, 'ets')
+        for dp, _d, files in os.walk(ets_root):
+            for f in files:
+                if f.endswith('.ets') and '@Entry' in read(os.path.join(dp, f)):
+                    rel = os.path.relpath(os.path.join(dp, f), ets_root)[:-4]
+                    if pages.get((m, rel)) is None:
+                        pages[(m, rel)] = os.path.join(dp, f)
+    return modules, pages, entry_module, entry_page
+
+
+def scan_page(file_path):
+    """单页扫描：交互点/状态/数据源/跳转。"""
+    src = read(file_path)
+    lines = src.split('\n')
+    interactions, states, navs = [], [], []
+    data_sources = [k for k, rx in DATA_HINTS.items() if rx.search(src)]
+
+    # 组件构造 + 邻近 .id()/文本
+    for i, ln in enumerate(lines):
+        m = re.match(r'^\s*(\w+)\s*(?:\(\s*(?:{[^}]*})?\s*\)?\s*(?:\{\s*)?)$', ln) or \
+            re.match(r'^\s*(Button|Text|Image|Toggle|TextInput)\s*\(', ln)
+        if not m or NON_COMPONENT.match(m.group(1)):
+            continue
+        comp = m.group(1)
+        # 向后 15 行找 .id / 文本内容 / onClick
+        after = '\n'.join(lines[i:min(len(lines), i + 15)])
+        idm = re.search(r"\.id\(\s*'([^']+)'", after)
+        txtm = re.search(r"(?:Text|Button)\s*\(\s*(?:this\.)?[\w.]*?'([^']{1,24})'", '\n'.join(lines[max(0,i-1):i+6]))
+        onclick = bool(re.search(r'\.on[A-Z]\w*\(', after))
+        if comp in INTERACTIVE_COMPONENTS or onclick:
+            target = idm.group(1) if idm else (txtm.group(1) if txtm else None)
+            if comp == 'Image' and not onclick:
+                continue
+            # 纯容器按行号定位且无文本无 id —— 噪声，剔除
+            if not target and comp in ('Column', 'Row', 'Stack', 'Flex', 'ListItem', 'List', 'Grid', 'Refresh', 'TabContent'):
+                continue
+            interactions.append({
+                'kind': 'click' if comp != 'TextInput' else 'input',
+                'target': target or f'line{i+1}:{comp}',
+                'desc': (txtm.group(1) if txtm else comp),
+                'has_id': bool(idm), 'line': i + 1, 'type': comp
+            })
+        # router 跳转
+        for nm in re.finditer(r"router\.(?:pushUrl|replaceUrl)\(\s*{\s*url:\s*'([^']+)'", after):
+            navs.append(nm.group(1))
+
+    # 条件状态（if 分支）
+    for i, ln in enumerate(lines):
+        if re.match(r'^\s*if\s*\(', ln):
+            cond = ln.strip()
+            states.append({'name': cond[:60], 'evidence': cond, 'line': i + 1})
+    return interactions, states[:20], navs, data_sources
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument('harmony')
+    ap.add_argument('--out', default=None)
+    args = ap.parse_args()
+    root = args.harmony
+
+    app_json5 = os.path.join(root, 'AppScope', 'app.json5')
+    bundle = ''
+    m = re.search(r'"bundleName"\s*:\s*"([^"]+)"', read(app_json5))
+    if m:
+        bundle = m.group(1)
+
+    modules, pages, entry_module, entry_page = find_pages(root)
+    if not pages:
+        print('错误: 未找到任何页面（路由表或 @Entry）', file=sys.stderr)
+        sys.exit(1)
+
+    # 权限（各模块 module.json5）
+    perms = []
+    for mdir in modules:
+        mj = os.path.join(root, mdir, 'src', 'main', 'module.json5')
+        perms += re.findall(r'"name"\s*:\s*"(ohos\.permission\.[\w.]+)"', read(mj))
+    perms = sorted(set(perms))
+
+    # 登录检测
+    has_login = False
+    for (mname, route), f in pages.items():
+        src = read(f) if f else ''
+        if any(h in src for h in LOGIN_HINTS):
+            # 有登录字样的页面
+            if re.search(r'登录|login|Login', src):
+                has_login = True
+
+    result = {'project_dir': os.path.abspath(root), 'bundle': bundle,
+              'entry': {'module': entry_module, 'page': entry_page},
+              'pages': [], 'permissions': perms, 'has_login': has_login,
+              'nav_graph': {}}
+
+    n_int = n_state = 0
+    for (mname, route), f in sorted(pages.items()):
+        if not f:
+            continue
+        interactions, states, navs, data_sources = scan_page(f)
+        result['pages'].append({
+            'page': os.path.basename(route), 'path': route, 'module': mname,
+            'file': os.path.abspath(f),
+            'nav_in': ['entry'] if route == entry_page else ['router:见 nav_graph'],
+            'interactions': interactions, 'states': states,
+            'data_sources': data_sources
+        })
+        result['nav_graph'][route] = sorted(set(navs))
+        n_int += len(interactions)
+        n_state += len(states)
+
+    # ── 深扫：多模块架构的真实 UI 在 features/commons 的 @Component 组件里 ──
+    seen_files = {p['file'] for p in result['pages']}
+    for m in modules:
+        ets_root = os.path.join(root, m, 'src', 'main', 'ets')
+        if not os.path.isdir(ets_root):
+            continue
+        for dp, _d, files in os.walk(ets_root):
+            for f in files:
+                if not f.endswith('.ets'):
+                    continue
+                fp = os.path.join(dp, f)
+                if fp in seen_files:
+                    continue
+                src = read(fp)
+                # 含 build() 的组件（@Component/@ComponentV2 struct）才算 UI 单元
+                if '@Component' in src and re.search(r'\bbuild\s*\(\s*\)', src):
+                    interactions, states, navs, data_sources = scan_page(fp)
+                    if not interactions and not states:
+                        continue
+                    rel = os.path.relpath(fp, os.path.join(root, m, 'src', 'main', 'ets'))[:-4]
+                    result['pages'].append({
+                        'page': os.path.splitext(f)[0], 'path': f'comp:{m}/{rel}',
+                        'module': m, 'file': os.path.abspath(fp),
+                        'nav_in': ['builder/comp'], 'interactions': interactions,
+                        'states': states, 'data_sources': data_sources
+                    })
+                    n_int += len(interactions)
+                    n_state += len(states)
+
+    payload = json.dumps(result, indent=2, ensure_ascii=False)
+    if args.out:
+        os.makedirs(os.path.dirname(os.path.abspath(args.out)), exist_ok=True)
+        open(args.out, 'w', encoding='utf-8').write(payload)
+        print(f'扫描完成: {len(result["pages"])} 页面 / {n_int} 交互点 / {n_state} 状态 / '
+              f'{len(perms)} 权限 / 登录页={"有" if has_login else "无"} → {args.out}')
+    else:
+        print(payload)
+
+
+if __name__ == '__main__':
+    main()

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

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""upgrade_asserts.py — 存量用例断言批量升级（EXEC-041）。
+
+目标：把「仅 exist」的用例批量升级为值级断言，让存量测试具备发现能力。
+
+升级规则（保守机械，不造新值——只把已有期望变强）：
+  R1  expect:"exist" + 文本型 target（非 snake_case id）→ expect:"equals"（同 target）
+      理由：equals 是 EQUALS 精确匹配，能抓 CONTAINS 命中的前缀污染（❄️Gallery 类）
+  R2  expect:"exist" + key 型 target → 保留（页面锚点合法），但在用例末尾若
+      仍无值级断言，追加 count 断言（target=该 key，value=1，唯一性）
+  R3  absent/checked 等已是值级，不动
+  每次升级在 note 里追加留痕（防驯化审计）。
+
+用法: python3 upgrade_asserts.py [--cases cases.json] [--dry-run]
+"""
+import argparse
+import json
+import re
+
+ID_LIKE = re.compile(r'^(tc_[a-z0-9_]+|[a-z][a-z0-9]*(_[a-z0-9]+)+|line\d+:\w+)$')
+
+
+def upgrade(cases, dry=False):
+    changed = 0
+    for c in cases:
+        has_value = any(s.get('expect') in
+                        ('equals', 'absent', 'text', 'text_contains', 'count',
+                         'below', 'checked', 'unchecked', 'enabled', 'disabled', 'toast')
+                        for s in c.get('steps', []))
+        for s in c.get('steps', []):
+            if s.get('expect') != 'exist':
+                continue
+            t = str(s.get('target', ''))
+            if t and not ID_LIKE.match(t):
+                # R1: 文本期望 → 精确
+                s['expect'] = 'equals'
+                c.setdefault('note', '')
+                c['note'] += f"[断言升级R1 exist→equals: {t[:20]}]"
+                changed += 1
+            elif t and ID_LIKE.match(t):
+                # R2: key 锚点保留，仅当全例无值级时补 count
+                if not has_value and s is c['steps'][-1]:
+                    c['steps'].append({'action': '断言升级R2:控件唯一性', 'target': t,
+                                       'expect': 'count', 'value': '1'})
+                    c['note'] = (c.get('note', '') + f"[断言升级R2 补count: {t[:20]}]")
+                    changed += 1
+    return changed
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument('--cases', default='cases.json')
+    ap.add_argument('--dry-run', action='store_true')
+    args = ap.parse_args()
+    cases = json.load(open(args.cases, encoding='utf-8'))
+    n = upgrade(cases, args.dry_run)
+    if args.dry_run:
+        print(f'[dry-run] 将升级 {n} 处')
+    else:
+        json.dump(cases, open(args.cases, 'w', encoding='utf-8'), ensure_ascii=False, indent=1)
+        print(f'[written] 升级 {n} 处 → {args.cases}')
+
+
+if __name__ == '__main__':
+    main()

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

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+"""validate_scenarios.py — 场景库质量门禁（下游唯一基础的准入校验）。
+
+校验规则（不通过进 scenarios_blocker.md，禁止进入用例生成）：
+  1. 必备字段：id / name / desc / converted / test_intent
+  2. 可观察业务效果：desc 须含效果关键词（新增/删除/…），纯导航词（进入/打开/跳转XX页）
+     且无效果词 = 拦截
+  3. 入口可定位：page_path 或前置路径字段存在（深层链路须写明）
+  4. converted=false 必须带 reason（未迁移/能力缺失/暂不测试）
+  5. 行为预期依据：source_ref / spec_ref 至少其一（默认值/联动从源码或规格推导）
+
+用法: python3 validate_scenarios.py scenarios.json [--out scenarios_blocker.md]
+退出码：0=全过（或仅警告）；1=存在 blocker。
+"""
+import argparse
+import json
+import re
+import sys
+
+REQUIRED = ['id', 'name', 'desc', 'converted', 'test_intent']
+EFFECT_WORDS = ['新增', '删除', '修改', '保存', '收藏', '取消', '成功', '失败', '提示',
+                '计数', '状态', '切换', '变为', '出现', '消失', '显示', '回显', '+1', '变更为']
+NAV_ONLY = re.compile(r'^(进入|打开|跳转|前往|查看)[^，。]{1,12}(页|面|界面)$')
+INTENTS = ('资源渲染', '功能交互', '配置生效', '导航流转', '状态机', '数据输入')
+
+
+def check(sc):
+    bid = sc.get('id', '?')
+    errs, warns = [], []
+    for f in REQUIRED:
+        if not str(sc.get(f, '')).strip():
+            errs.append(f'缺必备字段 {f}')
+    desc = str(sc.get('desc', ''))
+    if desc:
+        if NAV_ONLY.match(desc.strip()):
+            errs.append('desc 纯导航无可观察效果（"进入XX页"不是业务效果）')
+        elif not any(w in desc for w in EFFECT_WORDS):
+            errs.append(f'desc 无效果关键词（须含 {"/".join(EFFECT_WORDS[:6])}… 之一）')
+    if not (sc.get('page_path') or sc.get('precond_pages') or '前置' in desc or '路径' in desc):
+        warns.append('入口路径未标注（深层链路须在 desc 写前置路径）')
+    if sc.get('converted') is False and not str(sc.get('reason', '')).strip():
+        errs.append('converted=false 必须带 reason（未迁移/能力缺失/暂不测试）')
+    if not (sc.get('source_ref') or sc.get('spec_ref') or sc.get('evidence')):
+        warns.append('行为预期无源码/规格依据标注（默认值/联动禁直觉推断）')
+    ti = str(sc.get('test_intent', ''))
+    if ti and not any(t in ti for t in INTENTS):
+        errs.append(f'test_intent 非法 "{ti}"')
+    return bid, errs, warns
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument('scenarios')
+    ap.add_argument('--out', default='scenarios_blocker.md')
+    args = ap.parse_args()
+    try:
+        scenes = json.load(open(args.scenarios, encoding='utf-8'))
+    except Exception as e:
+        print(f'✗ scenarios.json 解析失败: {e}')
+        sys.exit(1)
+    if not scenes:
+        print('✗ 场景库为空——空库不允许生成用例（空跑=伪覆盖）')
+        sys.exit(1)
+
+    lines = ['# 场景库 Blocker（未通过质量门禁，禁止进入用例生成）', '']
+    n_err = n_warn = 0
+    for sc in scenes:
+        bid, errs, warns = check(sc)
+        for e in errs:
+            lines.append(f'- **BLOCKER** {bid}: {e}')
+        for w in warns:
+            lines.append(f'- ⚠ {bid}: {w}')
+        n_err += len(errs)
+        n_warn += len(warns)
+    print(f'场景库校验: {len(scenes)} 场景 | {n_err} blocker / {n_warn} 警告')
+    if n_err:
+        open(args.out, 'w', encoding='utf-8').write('\n'.join(lines) + '\n')
+        print(f'→ {args.out}（blocker 场景退回宿主 agent 修复）')
+        sys.exit(1)
+    print('✓ 全部通过（警告项自行斟酌）')
+
+
+if __name__ == '__main__':
+    main()

package/skills/d2h-utg-ai-generate/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: d2h-utg-ai-generate
+description: Independently generate or repair a source-derived UI Transition Graph with AI-assisted code understanding. Produces schema-checked utg.json, click_paths.json, and page.json for Android View/Fragment, Jetpack Compose, Voyager, and uni-app/Vue projects; for Android runtime capture, replays the generated plan directly through ADB and captures screenshots plus UIAutomator view trees. Use when source analysis must produce a UTG and optionally collect device evidence without another skill or AI navigation service.
+---
+
+# AI-assisted source UTG generation
+
+Use source evidence to identify pages and transitions, then hand only structured facts to the bundled deterministic scripts. The model must not directly author the final `utg.json`, `click_paths.json`, or `page.json`.
+
+This skill owns two explicit phases:
+
+1. **Source phase** — runs for independent generation or repair; produces the validated graph, paths, and capture plan without requiring a device. Skip it in explicit existing-plan capture mode.
+2. **Runtime phase** — runs when screenshot/DOM capture is requested and an unlocked Android ADB device is available. The bundled TypeScript script consumes `page.json`, replays deterministic navigation steps through ADB, and captures device evidence itself.
+
+The source-analysis mode runs independently. The explicit existing-plan capture mode may consume a validated page.json produced by d2h-utg-static-generate; it must not repeat source analysis or overwrite that graph. Do not use AutoGLM or blind crawling. The runtime phase is targeted deterministic replay, not blind crawling: only nodes marked `capture=true` in `page.json` are requested.
+
+## Inputs
+
+Resolve absolute paths for:
+
+- `source_project_dir` — application source root.
+- `output_workspace` — a new or explicitly selected UTG workspace. In the droid2hmos migration flow, set this to `<工程名>-migration/.migration/utg/` so the UTG artifacts live in the migration workspace alongside `spec/`, `report/`, `tasks/`, `arch/`, instead of inside either source project.
+- Optional existing `utg.json` and `click_paths.json` when the user requests repair.
+- Optional page/module scope. Never broaden a scoped request silently.
+- For runtime capture: Node.js 22.18+ (or 23.6+), `adb`, an installed APK on an unlocked device, optional `device_serial`, and `capture_workspace` (default `<output_workspace>/../ui_info` — a `ui_info/` sibling of the UTG workspace; in the migration flow use `<工程名>-migration/.migration/ui_info/`, sibling of `.migration/utg/`).
+
+Write to a new workspace unless the user explicitly requested repair in place. Do not overwrite unrelated UTG or capture artifacts.
+
+## Existing-plan capture mode
+
+When the caller provides an existing `page.json`, skip source-generation steps 1–5. Validate the referenced graph/path/plan with `scripts/validate_utg.py --utg <utg.json> --click-paths <click_paths.json> --page-json <page.json> --project-root <source>`. Run `node scripts/capture_from_page_json.ts --page-json <page.json> --output-workspace <capture-workspace> --dry-run` first; this validates without touching a device. If capture was requested, run the same command without `--dry-run` and apply all existing device boundaries below. Do not reinterpret `capture=false` nodes as capture tasks or regenerate the plan to force them eligible. The capture plan remains read-only; runtime outputs go to its selected capture workspace.
+
+## Workflow
+
+1. Classify the source stack from its manifests, build files, route registries, and navigation dependencies.
+2. Read [references/extraction-guide.md](references/extraction-guide.md) for the detected stack. Locate entry points, page declarations, navigation calls, back transitions, overlays, modes, deep links, and state guards.
+3. Read [references/facts-contract.md](references/facts-contract.md), then write `<output_workspace>/utg-facts.json`. Every emitted node and edge must cite an existing project-relative `file:line`. Every capture-eligible node needs at least one source-grounded `expected` arrival rule. Record `graph.version_name` and `graph.build_variant` when the source makes them deterministic. Put uncertain or unresolved findings in the top-level `unresolved` array instead of turning them into graph facts.
+4. Build the final artifacts with the deterministic generator. This writes `utg.json`, `click_paths.json`, and `page.json` atomically from the same normalized facts:
+
+   ```bash
+   python scripts/build_utg.py \
+     --facts <output_workspace>/utg-facts.json \
+     --project-root <source_project_dir> \
+     --workspace <output_workspace>
+   ```
+
+   Use `--force` only when the user requested regeneration/repair or the files belong to the current incomplete run. The build also renders the self-contained `utg.html` interactive visualization; a visualization failure is non-blocking.
+5. Validate the graph, paths, and page plan independently:
+
+   ```bash
+   python scripts/validate_utg.py \
+     --utg <output_workspace>/utg.json \
+     --click-paths <output_workspace>/click_paths.json \
+     --page-json <output_workspace>/page.json \
+     --project-root <source_project_dir>
+   ```
+
+6. Fix facts, not generated JSON. Rebuild and revalidate until valid or until remaining ambiguity requires user/runtime evidence.
+7. When runtime capture is requested, verify `node --version`, `adb devices`, that the app is installed, and that the device is unlocked. Compare the installed package version with `page.json.source.version_name`; the script stops on a mismatch. Then run:
+
+   ```bash
+   node scripts/capture_from_page_json.ts \
+     --page-json <output_workspace>/page.json \
+     --output-workspace <capture_workspace> \
+     [--device <device_serial>] \
+     [--adb-path <adb>] \
+     [--satisfied-state content,login] \
+     [--max-scrolls 4]
+   ```
+
+   The zero-dependency TypeScript script validates the plan and its UTG/path pair, force-stops and launches the package for each selected page, then replays supported steps using only `adb shell`: `launch/default` (no-op after launch), `tap/click/open/navigate/select`, `long-press`, `back`, `home`, `swipe`, and URI deep links. It parses the UIAutomator hierarchy, promotes a semantic match to its clickable ancestor, deduplicates matches that lead to the same target, and scrolls to search for off-screen targets. Prefer an explicit `args.selector`; `nl_hint` is documentation and is never executed as a selector. A normalized coordinate requires both source evidence and the explicit `--allow-coordinate-fallback` flag.
+8. Inspect `<capture_workspace>/capture-report.json`. A page counts as captured only when deterministic replay completed, its `expected` arrival rules passed, and its `screenshot.png`, `view.xml`, and `meta.json` were atomically promoted. Pages whose state requirements were not asserted are `blocked`, not captured. Record failed and blocked pages as manual follow-up work.
+9. The runtime phase writes `<capture_workspace>/pages.json` directly in `page.json` order and includes only successful captures. `page.json` remains the pre-capture plan; `pages.json` is the post-capture conversion index.
+
+Use `--dry-run` on `capture_from_page_json.ts` to validate and print selected nodes plus their required states without touching a device. Use `--only nodeA,nodeB` only for an explicitly scoped capture or retry; it must be a subset of `capture=true` nodes. Use `--satisfied-state` only for conditions verified in the current device/app state. Use `--allow-partial` only when the caller wants a zero exit code despite failed or blocked pages; their status remains visible in `capture-report.json`.
+
+Runtime capture does not authorize modifying application source, rebuilding or reinstalling the APK, clearing app data, changing locale, changing display size/density, granting permissions, or changing device roles/settings. Stop and ask before any such expansion. If the user authorizes a temporary device mutation, record the original value first and restore it in a `finally` path; never leave a device override behind silently.
+
+## Evidence rules
+
+- A source fact needs a real project-relative `file:line`; the scripts reject missing files and out-of-range lines.
+- Prefer navigation call sites for edge `trigger`, not only route declarations.
+- Use a numeric confidence in `[0, 1]`. The builder accepts `high`, `medium`, and `low` only as a compatibility input and records their normalization.
+- Use `guard` for reachability preconditions. Do not claim a guarded page is fresh-install reachable without evidence.
+- Use `args.label_source="nl_hint"` only when literal UI text/content description is unavailable, and include `args.nl_hint` plus evidence.
+- Never invent reverse/back edges merely to make the graph connected. Emit them only when source behavior supports them.
+- Keep external destinations out of the graph unless the source project owns the destination UI. Record them in node/widget metadata or `unresolved`.
+
+## Deterministic invariants
+
+The bundled scripts own all final-format mechanics:
+
+- canonical node/edge defaults, numeric confidence, and parallel-edge keys;
+- referential integrity and root validation;
+- in-app paths from the declared root that minimize guard requirements before hop count;
+- deep-link fallback only for nodes not reachable through normal in-app edges;
+- `depth`, `clicks`, `labels`, `kind`, `path_text`, and `unreachable`;
+- stable capture ordering, collision-safe capture keys, per-node capture eligibility, and exact copied navigation steps in `page.json`;
+- atomic writes and a machine-readable `generation-report.json`.
+
+Do not hand-edit these derived fields.
+
+## Required outputs
+
+The completed workspace contains:
+
+- `utg-facts.json` — AI-authored source facts and unresolved findings.
+- `utg.json` — normalized node-link directed multigraph.
+- `click_paths.json` — deterministic paths derived from that exact graph.
+- `page.json` — deterministic, schema-checked runtime capture plan derived from that exact graph/path pair. It includes every UTG node, marking unreachable/container nodes with `capture=false` and a reason.
+- `generation-report.json` — counts, normalizations, warnings, and unresolved items.
+- `utg.html` — self-contained interactive visualization rendered by `build_utg.py`; before runtime capture, screenshot thumbnails are empty.
+
+The schemas are [references/utg-schema.json](references/utg-schema.json), [references/click-paths-schema.json](references/click-paths-schema.json), and [references/page-schema.json](references/page-schema.json).
+
+When runtime capture runs, it additionally produces:
+
+- `<capture_workspace>/<capture_key>/screenshot.png`;
+- `<capture_workspace>/<capture_key>/view.xml`;
+- `<capture_workspace>/<capture_key>/meta.json`;
+- `<capture_workspace>/pages.json` — verified captured pages in downstream conversion order;
+- `<capture_workspace>/capture-report.json` — per-planned-node captured/failed/skipped status and exact artifact paths.
+
+## Report
+
+Report the node count by kind, edge count by mechanism, reachable/unreachable counts, `page.json` capture-planned/skipped counts, unresolved findings, validation result, provenance method (`ai-source-analysis`), and absolute output paths. Clearly state that source-derived reachability is not runtime confirmation.
+
+If runtime capture ran, also report selected/captured/failed counts, screenshot and DOM root paths, `capture-report.json`, `pages.json`, and every failed replay that needs manual setup or a better source selector. A valid source phase with a partial runtime phase is not a total failure: preserve the valid graph and report capture limitations precisely.

package/skills/d2h-utg-ai-generate/references/click-paths-schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://hometrans.local/schemas/click-paths-v2.json",
+  "title": "HomeTrans deterministic click paths",
+  "type": "object",
+  "required": ["root", "paths", "unreachable"],
+  "properties": {
+    "root": {"type": "string", "minLength": 1},
+    "paths": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["depth", "steps", "labels", "clicks", "kind", "path_text"],
+        "properties": {
+          "depth": {"type": "integer", "minimum": 0},
+          "steps": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "object",
+              "required": ["action", "label", "target_id", "target_kind", "guard"],
+              "properties": {
+                "action": {"type": "string", "minLength": 1},
+                "label": {"type": ["string", "null"]},
+                "label_source": {"type": ["string", "null"]},
+                "label_ambiguous": {"type": "boolean"},
+                "target_id": {"type": "string", "minLength": 1},
+                "target_kind": {"type": "string", "minLength": 1},
+                "guard": {"type": ["object", "null"]},
+                "mechanism": {"type": "string"},
+                "nl_hint": {"type": "string"},
+                "selector": {
+                  "type": "object",
+                  "properties": {
+                    "text": {"type": "string", "minLength": 1},
+                    "text_any": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
+                    "content_desc": {"type": "string", "minLength": 1},
+                    "content_desc_any": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
+                    "resource_id": {"type": "string", "minLength": 1},
+                    "resource_id_any": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}},
+                    "normalized_point": {
+                      "type": "array",
+                      "prefixItems": [
+                        {"type": "number", "minimum": 0, "maximum": 1},
+                        {"type": "number", "minimum": 0, "maximum": 1}
+                      ],
+                      "minItems": 2,
+                      "maxItems": 2
+                    }
+                  },
+                  "additionalProperties": false
+                },
+                "direction": {"enum": ["up", "down", "left", "right"]},
+                "distance": {"type": "number", "minimum": 0.1, "maximum": 0.8},
+                "duration_ms": {"type": "integer", "minimum": 0},
+                "max_scrolls": {"type": "integer", "minimum": 0}
+              },
+              "additionalProperties": true
+            }
+          },
+          "labels": {"type": "array", "items": {"type": "string"}},
+          "clicks": {"type": "integer", "minimum": 0},
+          "kind": {"type": "string", "minLength": 1},
+          "path_text": {"type": "string", "minLength": 1}
+        },
+        "additionalProperties": false
+      }
+    },
+    "unreachable": {
+      "type": "array",
+      "items": {"type": "string", "minLength": 1},
+      "uniqueItems": true
+    }
+  },
+  "additionalProperties": false
+}

package/skills/d2h-utg-ai-generate/references/extraction-guide.md

@@ -0,0 +1,34 @@
+# Source extraction guide
+
+Read only the section matching the detected stack. Record source facts rather than framework tutorials.
+
+## Android View / Fragment
+
+Start with merged-source equivalents of the manifest, launcher activities, navigation XML, fragment transactions, explicit/implicit intents, menus/preferences, dialog construction, and callbacks that invoke navigation. Treat an implicit intent whose destination is outside the project as an external boundary, not an owned page.
+
+## Jetpack Compose / Navigation-Compose
+
+Locate `NavHost`, graph start destinations, `composable`/`navigation` declarations, route registries, `navigate`, `popBackStack`, deep links, modal state controlling dialogs/sheets, and callbacks passed across composables. Resolve route templates and arguments without substituting sample runtime values. A navigation graph container may be a `nav-graph` node when it is needed to preserve source topology, but click paths should still land on actual pages through its start edge.
+
+## Voyager or other source routers
+
+Locate screen objects/classes, navigator creation, `push`/`replace`/`pop`, tab navigators, nested routers, and modal navigators. Use the router's stable code identity as the node ID. Do not collapse distinct state variants unless the rendered UI and reachable actions are equivalent.
+
+## uni-app / Vue
+
+Start with `pages.json`, subpackages, tab bar entries, `uni.navigateTo`, `redirectTo`, `reLaunch`, `switchTab`, `navigateBack`, router wrappers, and conditional component branches. Normalize source-owned route paths consistently. Treat downloaded WGT bundles and server-provided decorated-page configs as unresolved boundaries unless those inputs are supplied.
+
+## Overlays, modes, and state
+
+Dialogs, sheets, menus, selection modes, PiP, and meaningful empty/populated variants must be nodes when they expose distinct user actions or coverage obligations, even when they are state-driven rather than router destinations. Omit only purely decorative/transient UI, and state that reason in `unresolved`. Pair open/dismiss transitions only when each direction is supported by source behavior. Record permissions, login, content, server configuration, hardware, build flavor, and time-window constraints as guards.
+
+## Completeness pass
+
+Before building, compare:
+
+- declared routes versus nodes;
+- navigation call targets versus nodes;
+- nodes with no incoming edge other than legitimate roots/entry points;
+- nodes with no outgoing edge where back/dismiss behavior should exist;
+- ambiguous or computed targets versus `unresolved`;
+- every fact's evidence against the current source tree.