@harmonyos-arkts/d2h 0.1.3 → 0.1.6

package/skills/d2h-utg-ai-generate/tests/test_pipeline.py

@@ -0,0 +1,369 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+SKILL = Path(__file__).resolve().parents[1]
+BUILD = SKILL / "scripts" / "build_utg.py"
+VALIDATE = SKILL / "scripts" / "validate_utg.py"
+BUILD_PAGE = SKILL / "scripts" / "build_page_json.py"
+CAPTURE = SKILL / "scripts" / "capture_from_page_json.ts"
+
+
+class PipelineTest(unittest.TestCase):
+    def test_build_and_validate(self) -> None:
+        with tempfile.TemporaryDirectory() as temp:
+            root = Path(temp)
+            project = root / "project"
+            workspace = root / "workspace"
+            project.mkdir()
+            workspace.mkdir()
+            (project / "App.kt").write_text(
+                "fun root() = Unit\nfun openHome() = Unit\nfun openDialog() = Unit\n",
+                encoding="utf-8",
+            )
+            facts = {
+                "schema_version": "d2h-utg-facts/v1",
+                "graph": {
+                    "app": "Demo",
+                    "package": "com.example.demo",
+                    "architecture": "compose",
+                    "root": "MainActivity",
+                    "start_destination": "home",
+                },
+                "nodes": [
+                    {
+                        "id": "MainActivity", "kind": "activity", "label": "Demo",
+                        "declared_at": "App.kt:1", "extra": {"launcher": True},
+                        "expected": {"activity_any": ["com.example.demo"]},
+                    },
+                    {
+                        "id": "home", "kind": "compose-route", "label": "Home",
+                        "declared_at": "App.kt:2", "expected": {"activity_any": ["com.example.demo"]},
+                    },
+                    {
+                        "id": "overlay:Help", "kind": "dialog", "label": "Help",
+                        "declared_at": "App.kt:3", "expected": {"text_any": ["Help"]},
+                    },
+                ],
+                "edges": [
+                    {
+                        "source": "MainActivity", "target": "home",
+                        "mechanism": "navhost-start", "trigger": "App.kt:2",
+                        "args": {"action": "default", "label": "Demo", "label_source": "string"},
+                        "confidence": "high",
+                    },
+                    {
+                        "source": "home", "target": "overlay:Help",
+                        "mechanism": "open-overlay", "trigger": "App.kt:3",
+                        "args": {"action": "tap", "label": "Help", "label_source": "string"},
+                        "confidence": 0.95,
+                    },
+                ],
+                "unresolved": [],
+            }
+            facts_path = workspace / "utg-facts.json"
+            facts_path.write_text(json.dumps(facts), encoding="utf-8")
+            built = subprocess.run(
+                [sys.executable, str(BUILD), "--facts", str(facts_path),
+                 "--project-root", str(project), "--workspace", str(workspace)],
+                check=False, capture_output=True, text=True,
+            )
+            self.assertEqual(built.returncode, 0, built.stderr)
+            checked = subprocess.run(
+                [sys.executable, str(VALIDATE), "--utg", str(workspace / "utg.json"),
+                 "--click-paths", str(workspace / "click_paths.json"),
+                 "--page-json", str(workspace / "page.json"),
+                 "--project-root", str(project)],
+                check=False, capture_output=True, text=True,
+            )
+            self.assertEqual(checked.returncode, 0, checked.stderr)
+            click_paths = json.loads((workspace / "click_paths.json").read_text())
+            self.assertEqual(click_paths["paths"]["overlay:Help"]["depth"], 2)
+            self.assertEqual(click_paths["paths"]["overlay:Help"]["path_text"], "Demo > Help")
+            page_plan = json.loads((workspace / "page.json").read_text())
+            self.assertEqual(page_plan["schema_version"], "d2h-page-plan/v1")
+            self.assertEqual(page_plan["source"]["version_name"], "")
+            self.assertEqual(page_plan["summary"]["capture_planned"], 2)
+            self.assertEqual(
+                [page["node_id"] for page in page_plan["pages"]],
+                ["MainActivity", "home", "overlay:Help"],
+            )
+            self.assertEqual(page_plan["pages"][2]["steps"], click_paths["paths"]["overlay:Help"]["steps"])
+            capture_keys = [page["capture_key"] for page in page_plan["pages"] if page["capture"]]
+            self.assertEqual(len(set(capture_keys)), 2)
+            self.assertFalse(page_plan["pages"][0]["capture"])
+            self.assertEqual(page_plan["pages"][0]["skip_reason"], "container-node:activity")
+            report = json.loads((workspace / "generation-report.json").read_text())
+            self.assertEqual(report["normalizations"], ["edges[0].confidence: 'high' -> 0.9"])
+            self.assertEqual(report["page_plan"]["capture_planned"], 2)
+
+            dry_run = subprocess.run(
+                ["node", str(CAPTURE), "--page-json", str(workspace / "page.json"),
+                 "--output-workspace", str(workspace / "ui_info"), "--dry-run"],
+                check=False, capture_output=True, text=True,
+            )
+            self.assertEqual(dry_run.returncode, 0, dry_run.stderr)
+            preview = json.loads(dry_run.stdout)
+            self.assertEqual(preview["nodes"], ["home", "overlay:Help"])
+
+            mutated = dict(page_plan)
+            mutated["summary"] = dict(page_plan["summary"])
+            mutated["summary"]["capture_planned"] = 99
+            mutated_path = workspace / "page-mutated.json"
+            mutated_path.write_text(json.dumps(mutated), encoding="utf-8")
+            rejected = subprocess.run(
+                ["node", str(CAPTURE), "--page-json", str(mutated_path),
+                 "--output-workspace", str(workspace / "ui_info"), "--dry-run"],
+                check=False, capture_output=True, text=True,
+            )
+            self.assertEqual(rejected.returncode, 2)
+            self.assertIn("not the deterministic plan", rejected.stderr)
+
+            rebuilt = workspace / "page-rebuilt.json"
+            built_page = subprocess.run(
+                [sys.executable, str(BUILD_PAGE), "--utg", str(workspace / "utg.json"),
+                 "--click-paths", str(workspace / "click_paths.json"),
+                 "--output", str(rebuilt), "--project-root", str(project)],
+                check=False, capture_output=True, text=True,
+            )
+            self.assertEqual(built_page.returncode, 0, built_page.stderr)
+            rebuilt_plan = json.loads(rebuilt.read_text())
+            self.assertEqual(rebuilt_plan["pages"], page_plan["pages"])
+
+            # Runtime orchestration contract without a real device: a fake ADB
+            # implements only the commands used by the standalone TS capture.
+            fake_adb = root / "fake-adb.py"
+            fake_adb.write_text(
+                """#!/usr/bin/env python3
+import sys
+from pathlib import Path
+a=sys.argv[1:]
+if len(a)>=2 and a[0]=='-s': a=a[2:]
+state=Path(__file__).with_name('fake-adb-scrolled')
+if a==['devices']:
+    print('List of devices attached\\nfake\\tdevice')
+elif a[:2]==['shell','pm']:
+    print('package:/data/app/demo.apk')
+elif a[:3]==['shell','dumpsys','window']:
+    print('mCurrentFocus=Window{1 u0 com.example.demo/.MainActivity}')
+elif a[:3]==['shell','dumpsys','activity']:
+    print('topResumedActivity=ActivityRecord{1 com.example.demo/.MainActivity}')
+elif a[:3]==['shell','dumpsys','package']:
+    print('versionCode=1 versionName=')
+elif a[:3]==['shell','wm','density']:
+    print('Physical density: 480')
+elif a[:3]==['shell','wm','size']:
+    print('Physical size: 1080x1920')
+elif a[:3]==['shell','uiautomator','dump']:
+    print('UI hierchary dumped')
+elif a[:2]==['shell','cat']:
+    if state.exists():
+        print('<hierarchy><node text="" content-desc="" resource-id="" clickable="true" long-clickable="false" scrollable="true" enabled="true" bounds="[0,0][200,100]"><node text="Help" content-desc="" resource-id="" clickable="false" long-clickable="false" enabled="true" bounds="[10,10][90,90]"/><node text="" content-desc="Help" resource-id="" clickable="false" long-clickable="false" enabled="true" bounds="[100,10][190,90]"/></node></hierarchy>')
+    else:
+        print('<hierarchy><node text="" content-desc="" resource-id="" clickable="false" long-clickable="false" scrollable="true" enabled="true" bounds="[0,0][200,100]"/></hierarchy>')
+elif a[:3]==['shell','input','swipe']:
+    state.write_text('scrolled')
+    print('OK')
+elif a[:2]==['exec-out','screencap']:
+    sys.stdout.buffer.write(b'\\x89PNG\\r\\n\\x1a\\nFAKE')
+else:
+    print('OK')
+""",
+                encoding="utf-8",
+            )
+            fake_adb.chmod(0o755)
+            # Windows cannot execute a Python shebang. Intercept only this
+            # exact fake path in the test process; production ADB is unchanged.
+            hook = root / 'fake-adb-hook.mjs'
+            hook.write_text(
+                "import cp from 'node:child_process';\n"
+                "import { syncBuiltinESMExports } from 'node:module';\n"
+                "const original = cp.spawnSync;\n"
+                f"const fake = {json.dumps(str(fake_adb))};\n"
+                f"const python = {json.dumps(sys.executable)};\n"
+                "cp.spawnSync = (file, args, options) => file === fake "
+                "? original(python, [fake, ...args], options) : original(file, args, options);\n"
+                "syncBuiltinESMExports();\n", encoding='utf-8',
+            )
+            runtime_workspace = workspace / "runtime"
+            captured = subprocess.run(
+                ["node", "--import", hook.as_uri(), str(CAPTURE), "--page-json", str(workspace / "page.json"),
+                 "--output-workspace", str(runtime_workspace),
+                 "--device", "fake", "--adb-path", str(fake_adb), "--settle-ms", "0"],
+                check=False, capture_output=True, text=True,
+            )
+            self.assertEqual(captured.returncode, 0, captured.stderr)
+            capture_report = json.loads((runtime_workspace / "capture-report.json").read_text())
+            self.assertEqual(capture_report["status"], "complete")
+            self.assertEqual(capture_report["summary"]["captured"], 2)
+            self.assertEqual(capture_report["summary"]["failed"], 0)
+            self.assertEqual(capture_report["summary"]["blocked"], 0)
+            self.assertTrue((runtime_workspace / "pages.json").is_file())
+            for result in capture_report["pages"]:
+                if result["status"] != "captured":
+                    continue
+                self.assertTrue(Path(result["screenshot"]).is_file())
+                self.assertTrue(Path(result["view_tree"]).is_file())
+                self.assertTrue(Path(result["metadata"]).is_file())
+                metadata = json.loads(Path(result["metadata"]).read_text())
+                self.assertTrue(metadata["verification"]["ok"])
+                self.assertTrue((runtime_workspace / metadata["screenshot"]).is_file())
+                self.assertTrue((runtime_workspace / metadata["view_xml"]).is_file())
+                if result["node_id"] == "overlay:Help":
+                    self.assertEqual(metadata["replay_trace"][-1]["matched"]["scrolls"], 1)
+
+    def test_rejects_missing_evidence(self) -> None:
+        with tempfile.TemporaryDirectory() as temp:
+            root = Path(temp)
+            project = root / "project"
+            workspace = root / "workspace"
+            project.mkdir()
+            workspace.mkdir()
+            facts = {
+                "schema_version": "d2h-utg-facts/v1",
+                "graph": {"app": "Demo", "architecture": "compose", "root": "root"},
+                "nodes": [
+                    {"id": "root", "kind": "activity", "label": "Root", "declared_at": "Missing.kt:1"}
+                ],
+                "edges": [],
+                "unresolved": [],
+            }
+            facts_path = workspace / "utg-facts.json"
+            facts_path.write_text(json.dumps(facts), encoding="utf-8")
+            built = subprocess.run(
+                [sys.executable, str(BUILD), "--facts", str(facts_path),
+                 "--project-root", str(project), "--workspace", str(workspace)],
+                check=False, capture_output=True, text=True,
+            )
+            self.assertEqual(built.returncode, 2)
+            self.assertIn("source file does not exist", built.stderr)
+
+    def test_rejects_capture_page_without_arrival_rule(self) -> None:
+        with tempfile.TemporaryDirectory() as temp:
+            root = Path(temp)
+            project = root / "project"
+            workspace = root / "workspace"
+            project.mkdir()
+            workspace.mkdir()
+            (project / "App.kt").write_text("root\n", encoding="utf-8")
+            facts = {
+                "schema_version": "d2h-utg-facts/v1",
+                "graph": {
+                    "app": "Demo",
+                    "package": "com.example.demo",
+                    "architecture": "views",
+                    "root": "root",
+                },
+                "nodes": [
+                    {
+                        "id": "root",
+                        "kind": "activity",
+                        "label": "Root",
+                        "declared_at": "App.kt:1",
+                        "expected": {},
+                    }
+                ],
+                "edges": [],
+                "unresolved": [],
+            }
+            facts_path = workspace / "utg-facts.json"
+            facts_path.write_text(json.dumps(facts), encoding="utf-8")
+            built = subprocess.run(
+                [
+                    sys.executable,
+                    str(BUILD),
+                    "--facts",
+                    str(facts_path),
+                    "--project-root",
+                    str(project),
+                    "--workspace",
+                    str(workspace),
+                ],
+                check=False,
+                capture_output=True,
+                text=True,
+            )
+            self.assertEqual(built.returncode, 2)
+            self.assertIn("supported non-empty arrival rule", built.stderr)
+
+    def test_page_plan_keeps_unreachable_and_skips_nav_graph(self) -> None:
+        with tempfile.TemporaryDirectory() as temp:
+            root = Path(temp)
+            project = root / "project"
+            workspace = root / "workspace"
+            project.mkdir()
+            workspace.mkdir()
+            (project / "App.kt").write_text("root\ngraph\nhidden\n", encoding="utf-8")
+            facts = {
+                "schema_version": "d2h-utg-facts/v1",
+                "graph": {"app": "Demo", "package": "com.example.demo", "architecture": "compose", "root": "root"},
+                "nodes": [
+                    {"id": "root", "kind": "activity", "label": "Root", "declared_at": "App.kt:1"},
+                    {"id": "graph", "kind": "nav-graph", "label": "Graph", "declared_at": "App.kt:2"},
+                    {"id": "hidden", "kind": "dialog", "label": "Hidden", "declared_at": "App.kt:3"},
+                ],
+                "edges": [
+                    {"source": "root", "target": "graph", "mechanism": "navhost-start", "trigger": "App.kt:2", "args": {"action": "default"}, "confidence": 1.0}
+                ],
+                "unresolved": [],
+            }
+            facts_path = workspace / "utg-facts.json"
+            facts_path.write_text(json.dumps(facts), encoding="utf-8")
+            built = subprocess.run(
+                [sys.executable, str(BUILD), "--facts", str(facts_path),
+                 "--project-root", str(project), "--workspace", str(workspace)],
+                check=False, capture_output=True, text=True,
+            )
+            self.assertEqual(built.returncode, 0, built.stderr)
+            plan = json.loads((workspace / "page.json").read_text())
+            by_id = {page["node_id"]: page for page in plan["pages"]}
+            self.assertFalse(by_id["root"]["capture"])
+            self.assertEqual(by_id["root"]["skip_reason"], "container-node:activity")
+            self.assertFalse(by_id["graph"]["capture"])
+            self.assertEqual(by_id["graph"]["skip_reason"], "non-capture-kind:nav-graph")
+            self.assertFalse(by_id["hidden"]["reachable"])
+            self.assertEqual(by_id["hidden"]["skip_reason"], "unreachable-from-root")
+
+    def test_click_path_prefers_unguarded_route(self) -> None:
+        with tempfile.TemporaryDirectory() as temp:
+            root = Path(temp)
+            project = root / "project"
+            workspace = root / "workspace"
+            project.mkdir()
+            workspace.mkdir()
+            (project / "App.kt").write_text("root\nmid\ntarget\n", encoding="utf-8")
+            facts = {
+                "schema_version": "d2h-utg-facts/v1",
+                "graph": {"app": "Demo", "package": "com.example.demo", "architecture": "compose", "root": "root"},
+                "nodes": [
+                    {"id": "root", "kind": "activity", "label": "Root", "declared_at": "App.kt:1", "expected": {"activity_any": ["com.example.demo"]}},
+                    {"id": "mid", "kind": "compose-route", "label": "Mid", "declared_at": "App.kt:2", "expected": {"text_any": ["Mid"]}},
+                    {"id": "target", "kind": "compose-route", "label": "Target", "declared_at": "App.kt:3", "expected": {"text_any": ["Target"]}},
+                ],
+                "edges": [
+                    {"source": "root", "target": "target", "mechanism": "guarded-shortcut", "trigger": "App.kt:3", "guard": {"kind": "setting", "text": "optional start"}, "args": {"action": "default", "label": "Target"}, "confidence": 1.0},
+                    {"source": "root", "target": "mid", "mechanism": "tap", "trigger": "App.kt:2", "args": {"action": "tap", "label": "Mid"}, "confidence": 1.0},
+                    {"source": "mid", "target": "target", "mechanism": "tap", "trigger": "App.kt:3", "args": {"action": "tap", "label": "Target"}, "confidence": 1.0},
+                ],
+                "unresolved": [],
+            }
+            facts_path = workspace / "utg-facts.json"
+            facts_path.write_text(json.dumps(facts), encoding="utf-8")
+            built = subprocess.run(
+                [sys.executable, str(BUILD), "--facts", str(facts_path), "--project-root", str(project), "--workspace", str(workspace)],
+                check=False, capture_output=True, text=True,
+            )
+            self.assertEqual(built.returncode, 0, built.stderr)
+            paths = json.loads((workspace / "click_paths.json").read_text())
+            self.assertEqual(paths["paths"]["target"]["depth"], 2)
+            self.assertEqual([step["target_id"] for step in paths["paths"]["target"]["steps"]], ["root", "mid", "target"])
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,73 @@
+---
+name: d2h-utg-static-generate
+description: 迁移主流程的 Android 静态分析入口，在 Skill 内调用 droid2hmos/AppGraph CLI 生成只读 Facts，再复用应用图生成 UTG、点击路径和采集计划，以源码证据驱动 AI 补充纠错并输出离线 utg.html。也支持独立 UTG 分析；不操作设备或修改应用源码。
+---
+
+# AppGraph 驱动的静态 UTG
+
+这是迁移流程的默认静态分析入口。主 Agent 加载本 Skill 并提供 Android 源码目录、迁移工作区，由本 Skill 调用分析 CLI；主流程不另行触发分析。AppGraph 提供工具生成的确定性事实，生成后保持只读；UTG 和 AI 发现属于消费方派生产物，不把 AI 结论注入 AppGraph 或 `.migration/spec/facts/`。
+
+所需 AppGraph 和 droid2hmos 能力由 `managing-d2h-toolchain` 的清单统一检查和准备；本 Skill 不声明版本，也不安装或升级 CLI。
+
+## 迁移主流程入口
+
+进入本 Skill 前，主 Agent 已完成工程配置及当前阶段所需的准备检查。迁移工作区为 `<源码父目录>/<源码目录名>-migration/.migration/`，已有现场时沿用其实际路径。
+
+1. 在本 Skill 内执行受管分析，检查退出码及返回结果；失败时报告并停止依赖该结果的步骤：
+
+   ```bash
+   droid2hmos analyze android <android-source>
+   ```
+
+2. 确认本次生成的 `<migration-workspace>/spec/index.json`、`spec/facts/` 和 `appgraph/app-graph.json` 存在，核对源码与分析结果。复用这份 AppGraph，不再执行第二次 `appgraph build`：
+
+   ```bash
+   python <skill>/scripts/generate.py --project-root <android-source> --workspace <migration-workspace>/utg --appgraph <migration-workspace>/appgraph/app-graph.json
+   ```
+
+3. 按下文完成源码核验、独立 AI 修补和统一重建。已有 UTG 工作区需显式使用 `--force`；源码或 AppGraph 变化时重新核验旧修补，不能沿用过期指纹。
+4. 将 Facts 位置、受管分析结果、UTG 产物及未解析项交回主 Agent，由主 Agent 接续报告初始化与 Task Plan。UTG discoveries 不替代 Kernel 的 correction/review，也不替代受管分析证据。
+
+Android 分析不运行 Gradle、不启用 `--resolve-dependencies`，不需要 APK 或 Android 设备。已有图缺失时报告分析产物不完整，不在主流程模式中静默切换到独立建图。
+
+## 独立 UTG 输入与运行
+
+要求 Python 3.9+、已有的 `appgraph` CLI，以及真实 Android 源码目录。默认工作区为 `<源码父目录>/<源码目录名>-migration/.migration/utg/`；已有迁移现场时显式传入其 UTG 目录。
+
+```bash
+python <skill>/scripts/generate.py --project-root <android-source> --workspace <utg-workspace>
+# 使用显式选定的已有 AppGraph，跳过 build：
+python <skill>/scripts/generate.py --project-root <android-source> --workspace <utg-workspace> --appgraph <app-graph.json>
+```
+
+独立模式未提供现有图时执行 `appgraph build --platform android --out ...`；只生成 UTG，不替代迁移主流程所需的受管 Facts 分析。不启用 Gradle 依赖解析，不安装或升级 CLI。分析失败必须报告，不能静默改为纯 AI 建图。当前仅接受 Android AppGraph schemaVersion 1。
+
+## 静态投影与核验
+
+脚本优先消费 AppGraph 的 `interactionGraph`，保留页面身份、粗细图别名、控件使用上下文、导航调用点和调用链证据；没有该字段时兼容旧版图。候选节点、歧义归属、无源码行号和未解析目标进入 `review-worklist.json`，不会猜测目标或选择首个页面。
+
+多个已确认启动页面使用不可采集的逻辑入口节点，各入口保持独立边。只有 Manifest 明确提供的启动组件才生成 `start-activity` 操作；缺少启动参数时路径不可执行。宿主关系不直接视为进入关系，只有有证据的初始路由才能生成 `navhost-start`。
+
+返回、弹层关闭和外部 Intent 保留在图元数据的 `boundary_transitions` 及对齐表中：未确定实际目标页面时不建立猜测的页间边。外部 Intent 的实际处理应用仍由运行时解析，不代表已确认浏览器或设备行为。Compose testTag 仅为静态选择器候选，未证明设备树中的可执行映射时不直接转为 ADB resource-id。
+
+读取 `appgraph-utg-facts.json` 和核验清单，结合源码全面检查路由注册、封装函数、方法引用、弹窗、返回、入口和状态条件。不能仅检查脚本已列出的缺口。核验已有导航的触发位置和归属；判断到达条件及实际可执行选择器时读取资源与源码。自然语言操作提示不能作为运行时选择器。
+
+`review-worklist.json` 的 `navigation_candidates` 保留 AppGraph 导航候选两端、路由键和证据；`navigation_review` 显示导航待核验数量。必须逐条以源码处置导航候选（确认新增、修正或排除），并扫描候选之外的封装调用与方法引用。用 `resolved_findings` 关闭已处置的导航告警，保留排除理由与源码行；`navigation_review.status=pending` 时只可称为基础投影或未完成的源码核验，不可报告完整静态 UTG 识别率。导航已核验不意味着所有到达条件和设备选择器已确认。
+
+可复用弹层组件的定义不等同于可进入的独立页面。检查各调用位置与显示条件；同一组件在多个宿主页面使用时，为有证据的调用实例建立独立节点与宿主边，并排除孤立的通用组件投影。不要仅因类型名包含 `Screen` 就接受页面身份；先确认它不是主题枚举、网络状态等数据值。
+
+按 [修补契约](references/discoveries.md) 写入 `discoveries.json`。有明确证据时自动修补，不要求逐条用户确认；不确定的保留 `unresolved`，不编造反向边或运行时确认。无有效入口时先补充有证据的入口再重建；不要伪造根节点。
+
+```bash
+python <skill>/scripts/generate.py --project-root <android-source> --workspace <utg-workspace> --appgraph <app-graph.json> --discoveries <utg-workspace>/discoveries.json --force
+```
+
+`--force` 仅用于本次已选定工作区的派生产物重建。源码或输入图发生变化时旧修补被拒绝；重新生成基础图并重新核验修补，不能只更改指纹绕过检查。
+
+## 交付和下游
+
+输出 `appgraph-utg-facts.json`、`review-worklist.json`、`discoveries.json`、`utg-facts.json`、`utg.json`、`click_paths.json`、`page.json`、`generation-report.json`、`utg.html`。新契约输入还输出 `appgraph-utg-alignment.json`，记录基础来源映射、未投影对象、修补审计及最终节点边身份。复用相邻 `d2h-utg-ai-generate/scripts/` 的规范化、路径、采集计划和可视化代码，两项 Skill 必须一起安装。
+
+HTML 离线展示图、来源、源码证据、修补前对象和未解析项。`static-only` 不代表设备可达；缺少到达规则或路径操作选择器的页面标记 `capture=false`。按清单继续源码核验，而不是为了提高数量猜测条件。
+
+需要设备采集时交给 `d2h-utg-ai-generate` 的已有计划采集入口，传入本工作区的 `page.json`，不要再次建图。报告基础/修补节点边数量、采集不可执行原因、未解析入口或关系及绝对输出路径。

package/skills/d2h-utg-static-generate/references/discoveries.md

@@ -0,0 +1,38 @@
+# 独立 AI 修补契约
+
+```json
+{
+  "schema_version": "d2h-utg-discoveries/v1",
+  "input_fingerprint": "复制 review-worklist.json 的指纹",
+  "operations": [
+    {
+      "kind": "edge",
+      "op": "add",
+      "id": "ai:settings-about",
+      "reason": "导航封装导致 AppGraph 漏掉调用关系",
+      "evidence": "app/src/main/java/Settings.kt:42",
+      "value": {
+        "id": "ai:settings-about",
+        "source": "现有来源节点ID",
+        "target": "现有目标节点ID",
+        "mechanism": "compose-navigate",
+        "trigger": "app/src/main/java/Settings.kt:42",
+        "confidence": 0.9,
+        "args": {"action": "tap", "selector": {"text": "关于"}, "label_source": "string"},
+        "guard": null
+      }
+    }
+  ],
+  "unresolved": []
+}
+```
+
+`kind=node|edge` 支持 `add|replace|exclude`。replace 是完整对象替换，不是字段补丁，必须保持目标 id。node 使用现有 UTG facts 节点契约，包括 `declared_at`、`kind`、`label`；有证据时补 `expected`、`required_state`。edge 使用上述字段。id 不得采用可能碰撞的页面显示名称。
+
+入口纠错使用 `kind=graph, op=replace, id=root, value=<页面ID>`，并提供入口源码证据。
+
+每项必须有非空 reason 和真实项目相对 file:line evidence。脚本验证位置存在，不代表自动证明语义；Agent 必须核对该行和上下文确实支持结论。同一对象只能有一个操作；重复新增、目标不存在、悬空边及输入图/源码指纹不一致会失败。排除节点时必须显式处理关联边，不隐式删除导航。
+
+结果统一标记 `ai-source-review` 和 `static-only`，审计保存在图元数据的 discovery_audit（含原对象）。不会修改 AppGraph 输入。未知运行时目标保留 unresolved；登录等条件使用真实证据，不以置信度代替证据。
+
+已核验解决的工作清单项可写入顶层 `resolved_findings` 数组，每项包含清单中的 `id`、`reason`、`evidence`。脚本验证引用和证据后从最终 unresolved 中移除，并保留解决记录；基础清单仍保持原样。不要把仍需运行时验证的问题标记已解决。