@harmonyos-arkts/d2h 0.1.2 → 0.1.5

package/README.md

@@ -6,14 +6,14 @@ Android 应用迁移到 HarmonyOS 的报告驱动 AI 插件，支持 Claude Code
 
 ## 主流程
 
-1. 检查 Android 技术栈、构建基线和设备环境。HarmonyOS HDC 设备是必需门禁；Android 模拟器是可选对照环境，缺失时只给出安装建议。
+1. 检查 Android 技术栈、构建基线和设备环境。HarmonyOS HDC 设备是必需门禁；Android 运行环境依赖（SDK/adb/模拟器/Android 侧构建测试）已移除，相关检查固定为 `not_applicable`。
 2. 运行 AppGraph 纯源码静态分析（无需编译 Android 工程），生成只读 `.migration/spec/facts/` 与人工查看的 `spec.html`。
 3. 加载 `appgraph-rule-audit`，只读分析页面、跳转、归属、规则贡献和未解析结果，生成 `.migration/rule-audit/` 规则提升候选；它不修改 facts 或规则，也不阻塞迁移。
 4. 从 facts 初始化 `.migration/report/` 报告分片。
 5. 从 `.migration/spec/` 的 Facts 分片契约 `2.0.0` 与受管 correction/review 编译 `.migration/tasks/`，校验 Launcher、行为闭包、Fact 所有权和 Task DAG。
-6. AI 通过 `task next`/`task show` 取得一个完整行为责任，以 Android 源码和运行行为为权威持续实现 HarmonyOS 应用。
-7. 每完成一个可验证 Task，同步填写实现映射和测试证据，并创建 Git 检查点。
-8. 在 HarmonyOS 模拟器或真机上执行端到端功能验证；若 Android 模拟器可用，则同步进行双端页面对照。具备图片理解能力时全面比较视觉细节，否则比较页面内容、控件、状态与交互结果，不宣称像素级一致。发现 facts 遗漏时写入报告 discoveries。
+6. AI 通过 `task next`/`task show` 在 Resolution 阶段取得裁决 Task，在 Execution 阶段取得一个完整 Page Work Package；以 Android 源码和运行行为为权威持续实现 HarmonyOS 应用。
+7. 每完成一个可验证 Page Work Package，同步填写内部 Work Item/Behavior 的实现映射和测试证据，并创建 Git 检查点。
+8. 在 HarmonyOS 模拟器或真机上执行端到端功能验证。Android 运行时对照能力已移除，一致性基准为 Android 源码、静态 facts 与 `evidence compare` 对既有证据目录的比较；发现 facts 遗漏时写入报告 discoveries。
 9. 使用 Task Plan 与报告门禁检查已知 facts 覆盖；最终完成必须同时满足真实应用验收。
 
 Task Planning 的跨仓实现映射、架构图、Agent 生效检查和端到端运行命令见 [`docs/task-planning-implementation-and-runbook.md`](docs/task-planning-implementation-and-runbook.md)。
@@ -34,6 +34,18 @@ android-to-hmos-migration/
 
 ## 安装
 
+D2H 安装器按 `skills/managing-d2h-toolchain/toolchain.json` 中联测的版本安装 AppGraph 和 droid2hmos，并安装 Agent/Skill。工具版本与安装流程由 [`managing-d2h-toolchain`](skills/managing-d2h-toolchain/SKILL.md) 统一管理；其他 Skill 只声明所需能力。使用 0.1.5：
+
+```sh
+npx --yes @harmonyos-arkts/d2h@0.1.5 install --agent opencode
+npx --yes @harmonyos-arkts/d2h@0.1.5 install --agent vscode
+npx --yes @harmonyos-arkts/d2h@0.1.5 doctor --agent vscode
+npx --yes @harmonyos-arkts/d2h@0.1.5 upgrade --check
+npx --yes @harmonyos-arkts/d2h@0.1.5 --check-env --output-dir ./environment-report
+```
+
+VS Code 目标是 Huawei HarmonyOS Dev Assistant 扩展；安装器复制 Agent/Skill、注册 `d2h` 并设置读写编辑权限，同时将模式名显示为“安卓转鸿蒙”。扩展使用已解包的 OpenCode 缓存运行，安装器会同步更新当前活动缓存并备份改动；请先启动扩展一次以生成缓存，安装后在 VS Code 中执行“Developer: Reload Window”使对话后端重新读取配置。`doctor --agent vscode` 会检查扩展文件和活动缓存。详细用法见 [环境检查说明](docs/environment-check.md)。本地 npm link 开发安装不会被自动替换。
+
 Claude Code：
 
 ```text
@@ -41,49 +53,49 @@ Claude Code：
 /plugin install android-to-hmos-migration@android-to-hmos-migration-local
 ```
 
-OpenCode（Node.js 20–24，支持 Windows/macOS/Linux，无需克隆仓库或安装 Shell）：
-
-```sh
-npx --yes @harmonyos-arkts/d2h
-```
-
-安装器把 npm 包内的 `skills/` 和 `agents/` 复制到当前用户的 OpenCode 全局配置目录。更新已有安装时使用：
-
-```sh
-npx --yes @harmonyos-arkts/d2h@latest --force
-```
-
-先预览或指定目录：
-
-```sh
-npx --yes @harmonyos-arkts/d2h --dry-run
-npx --yes @harmonyos-arkts/d2h --config-dir /path/to/opencode
-```
-
-默认目标为 OpenCode，也可显式使用 `--agent opencode`。安装到 DevEco Code：
-
-```sh
-npx --yes @harmonyos-arkts/d2h --agent deveco
-npx --yes @harmonyos-arkts/d2h@latest --agent deveco --force
-```
-
-DevEco Code 默认安装到 `~/.config/deveco`（Windows 为 `%USERPROFILE%\.config\deveco`），目录优先级为 `--config-dir` → `DEVECO_CONFIG_DIR` → `$XDG_CONFIG_HOME/deveco` → `~/.config/deveco`。OpenCode 使用 `OPENCODE_CONFIG_DIR`，两者互不混用。安装完成后重启对应应用；已有配置 JSON 保留。`--config-dir` 与 `--agent` 的参数顺序不影响结果。
-
-默认目录按 `OPENCODE_CONFIG_DIR` → `$XDG_CONFIG_HOME/opencode` → `~/.config/opencode` 解析；Windows 默认 `%USERPROFILE%\.config\opencode`。不会读取或修改 `opencode.json`，不会复制仓库的 `AGENTS.md`。已有相同内容保持不变，冲突时提示 `--force`，其他用户 Agent/Skill 保留。
-
-从仓库安装仍可使用原 Shell 脚本：
+OpenCode（Node.js 22.5–24.x，支持 Windows/macOS/Linux，无需克隆仓库或安装 Shell）：
+
+```sh
+npx --yes @harmonyos-arkts/d2h@0.1.5
+```
+
+安装器把 npm 包内的 `skills/` 和 `agents/` 复制到当前用户的 OpenCode 全局配置目录。更新已有安装时使用：
+
+```sh
+npx --yes @harmonyos-arkts/d2h@0.1.5 --force
+```
+
+先预览或指定目录：
+
+```sh
+npx --yes @harmonyos-arkts/d2h@0.1.5 --dry-run
+npx --yes @harmonyos-arkts/d2h@0.1.5 --config-dir /path/to/opencode
+```
+
+默认目标为 OpenCode，也可显式使用 `--agent opencode`。安装到 DevEco Code：
+
+```sh
+npx --yes @harmonyos-arkts/d2h@0.1.5 --agent deveco
+npx --yes @harmonyos-arkts/d2h@0.1.5 --agent deveco --force
+```
+
+DevEco Code 默认安装到 `~/.config/deveco`（Windows 为 `%USERPROFILE%\.config\deveco`），目录优先级为 `--config-dir` → `DEVECO_CONFIG_DIR` → `$XDG_CONFIG_HOME/deveco` → `~/.config/deveco`。OpenCode 使用 `OPENCODE_CONFIG_DIR`，两者互不混用。安装完成后重启对应应用；已有配置 JSON 保留。`--config-dir` 与 `--agent` 的参数顺序不影响结果。
+
+默认目录按 `OPENCODE_CONFIG_DIR` → `$XDG_CONFIG_HOME/opencode` → `~/.config/opencode` 解析；Windows 默认 `%USERPROFILE%\.config\opencode`。不会读取或修改 `opencode.json`，不会复制仓库的 `AGENTS.md`。已有相同内容保持不变，冲突时提示 `--force`，其他用户 Agent/Skill 保留。
+
+从仓库安装仍可使用原 Shell 脚本：
 
 ```sh
 sh ./install-opencode.sh
 ```
 
-该脚本把 `skills/` 和 `agents/` 安装到当前用户的 OpenCode 全局配置目录，不读取或改写 `opencode.json`。更新已有安装时使用 `--force`；本地开发需要让全局安装实时跟随仓库时使用 `--link --force`。可通过 `--config-dir` 和 `--source-dir` 适配自定义目录，先用 `--dry-run` 检查操作。完整参数见 `sh ./install-opencode.sh --help`。
-
-npm 安装器支持同样的参数，完整说明见 `npx --yes @harmonyos-arkts/d2h --help`。本地开发可使用 `npm run build && node dist/bin/install-opencode.js --source-dir /path/to/repository --link --force`。Windows 下 Agent 文件符号链接需要开发者模式或管理员权限；默认复制模式不需要。不要将 `npx` 缓存作为长期链接来源，缓存清理后链接可能失效。
-
-维护者发布：安装开发依赖后运行 `npm run build`，将 TypeScript 源码编译到 `dist/`；`npm run check && npm test` 检查类型并测试编译后的 CLI，然后 `npm publish`。npm 包使用 `dist/bin/install-opencode.js` 作为入口，包含编译后的运行代码、Agent、完整 Skill 资源树及 schema，不包含 TypeScript 源码、研发文档和测试；发布时不会自动修改用户配置，只有显式执行 `npx` 安装器才会安装。
+该脚本把 `skills/` 和 `agents/` 安装到当前用户的 OpenCode 全局配置目录，不读取或改写 `opencode.json`。更新已有安装时使用 `--force`；本地开发需要让全局安装实时跟随仓库时使用 `--link --force`。可通过 `--config-dir` 和 `--source-dir` 适配自定义目录，先用 `--dry-run` 检查操作。完整参数见 `sh ./install-opencode.sh --help`。
 
-完全退出并重新启动 OpenCode 后，选择 `android-to-hmos-00-orchestrator` 执行完整迁移。
+npm 安装器支持同样的参数，完整说明见 `npx --yes @harmonyos-arkts/d2h@0.1.5 --help`。本地开发可使用 `npm run build && node dist/bin/install-opencode.js --source-dir /path/to/repository --link --force`。Windows 下 Agent 文件符号链接需要开发者模式或管理员权限；默认复制模式不需要。不要将 `npx` 缓存作为长期链接来源，缓存清理后链接可能失效。
+
+维护者发布：安装开发依赖后运行 `npm run build`，将 TypeScript 源码编译到 `dist/`；`npm run check && npm test` 检查类型并测试编译后的 CLI，然后 `npm publish`。npm 包使用 `dist/bin/install-opencode.js` 作为入口，包含编译后的运行代码、Agent、完整 Skill 资源树及 schema，不包含 TypeScript 源码、研发文档和测试；发布时不会自动修改用户配置，只有显式执行 `npx` 安装器才会安装。
+
+完全退出并重新启动 OpenCode 后，选择 `d2h_v2` 执行完整迁移。`android-to-hmos-00-orchestrator` 和 `d2h` 仅为旧名称兼容入口。
 
 ## 命令
 
@@ -102,7 +114,8 @@ droid2hmos task validate <android-project>
 droid2hmos task status <android-project>
 droid2hmos task next <android-project>
 droid2hmos task show <android-project> <task-id> [--cursor <cursor>] [--max-source-context <count>]
-droid2hmos build <android|harmony|all> <android-project>
+droid2hmos build harmony <android-project>
+droid2hmos test harmony <android-project> --runner python --hypium-project <path> (--test-list <name>...|--all) [--target <id>] [--ref <report-ref>...]
 droid2hmos test harmony <android-project> --class <class> [--case <case>] [--target <id>] [--case-timeout-ms <ms>] [--ref <report-ref>...]
 droid2hmos test harmony <android-project> --all [--target <id>] [--case-timeout-ms <ms>] [--ref <report-ref>...]
 droid2hmos service start <name> <android-project> [--health-url <url>] -- <command> [args...]
@@ -113,14 +126,14 @@ droid2hmos service stop <name> <android-project>
 - `init`：从受管 DevEco 模板创建 HarmonyOS 工程壳。
 - `status`：从项目、配置、Preflight、facts、报告、Task Plan、源码指纹和受管证据只读推导当前阶段、允许动作与完成缺口，不维护可漂移的手工状态。
 - `complete`：最终完成硬门禁；任何 guard 模式都不能绕过当前分析、全量回归、报告和逐项证据的新鲜度检查。
-- `analyze android`：通过 AppGraph 对 Android 源码做纯静态分析，生成确定性 facts 和 `spec.html`，无需编译 Android 工程；同时只读清点既有 APK，供双端运行对照决策使用。
+- `analyze android`：通过 AppGraph 对 Android 源码做纯静态分析，生成确定性 facts 和 `spec.html`，无需编译 Android 工程；同时只读清点既有 APK，仅作参考信息（Android 运行时对照能力已移除）。
 - `report init`：从 facts 初始化报告 `1.2.0`；存量 `1.1.0` 报告原地升级但不会伪造来源。
 - `report update/validate`：为 implemented/verified 条目强制记录 Android `sourceProvenance`，校验受管成员、文件 hash、可用 Task closure 和 HarmonyOS 路径；项目内事件文件不被当作可信 D1 来源，缺少运行器集成时返回 `unavailable`，D2 抽样只产生 warning。当前不拦截宿主普通文件写入，最高默认证据级别为 `declared-hash-validated`。
 - `report`：校验后生成 `.migration/report/report.html`。HTML 主体面向用户展示迁移结论、未完成内容、下一步、端到端测试、差异和阻塞；页面/控件/导航、内部 ref 与文件映射仅作为默认折叠的技术追溯附录。
 - `task plan/validate`：确定性生成并校验 `.migration/tasks/`；计划基线绑定 Facts、correction/review 和 Android 指纹，并按可观察行为而不是单个 Entry/Issue 聚合责任。
 - `task status/next/show`：只读推导 Task 运行态、选择 Ready Frontier，并按需分页返回源码上下文；不写新的状态机文件。
 - `build harmony`：直接读取 DevEco JSON5 配置生成应用构建命令；Hvigor 增量命中时可复用不早于当前构建输入的非空 HAP，过期产物会失败；`config.json` 不保存 HarmonyOS 构建命令。
-- `test harmony`：确定性构建应用与 ohosTest HAP、安装到明确目标设备并运行 Hypium；多设备时必须传 `--target`，测试失败、忽略、零执行或缺少结果摘要都会失败。用重复的 `--ref` 声明本次测试实际覆盖的报告项，未覆盖的 `verified` 项不能通过 `complete`。
+- `test harmony`：确定性构建应用 HAP 并运行 Hypium。迁移流程统一使用 `--runner python --hypium-project <path> --test-list <name>...` 执行 `d2h-hypium-forge` 生成的 `.hypium_forge/` Python 用例（定向执行、无 `--all`，需 `python -m pip install hypium -U`）；`--class/--case/--all` 的 ArkTS ohosTest runner 仅用于存量资产。多设备时必须传 `--target`，测试失败、忽略、零执行或缺少结果摘要都会失败。用重复的 `--ref` 声明本次测试实际覆盖的报告项，未覆盖的 `verified` 项不能通过 `complete`。
 
 ## 核心产物
 
@@ -176,3 +189,24 @@ Migration Kernel 在独立 CLI 中实现 `inspect → guard → execute → reco
 报告通过只证明已知 facts 有记录，不证明迁移成功。最终标准始终是：HarmonyOS 应用中的所有页面、控件、导航、Dialog 和业务功能与 Android 的外部可观察行为一致，并通过真实设备端到端验证。
 
 Windows 下所有 Gradle/Hvigor 测试与构建均由 Preflight 的有限命令运行器执行：禁用 Daemon、禁止输出管道、日志直接落盘并设置超时，避免构建成功后 OpenCode 因继承的输出句柄永久卡死。
+
+## AppGraph 静态 UTG
+
+AppGraph 与 droid2hmos 的包、精确版本和命令能力只在 `skills/managing-d2h-toolchain/toolchain.json` 中声明。其他 Agent/Skill 直接使用已检查的 CLI，不再维护依赖块；`npm run check` 验证清单与环境约束一致，安装和升级仅由 `managing-d2h-toolchain` 调用 D2H 安装器执行。
+
+主流程加载 `d2h-utg-static-generate` 完成 Android 静态分析，由 Skill 内部调用 `droid2hmos analyze android` 生成受管 Facts，再复用本次 AppGraph 构建基础 UTG、完成 AI 源码核验与独立修补，统一重建并输出离线 `utg.html`。主流程不另行调用分析 CLI，图生成不重复执行 AppGraph 分析。生成后的原始图和 facts 保持只读，不操作设备。
+
+主流程操作步骤见 [Skill 的迁移主流程入口](skills/d2h-utg-static-generate/SKILL.md)。独立生成 UTG 可运行：
+
+```bash
+python skills/d2h-utg-static-generate/scripts/generate.py --project-root <Android源码> --workspace <迁移现场>/.migration/utg
+```
+
+可用 `--appgraph <app-graph.json>` 消费现有图。Agent 阅读 `review-worklist.json`、核对源码后填写 `discoveries.json`，用相同命令加 `--force` 重建；源码和输入图变化会拒绝旧修补。完整契约见 [新 Skill](skills/d2h-utg-static-generate/SKILL.md)。静态到达性不是运行时确认；缺少到达规则或执行选择器的页面不安排采集。设备采集通过现有 AI Skill 的已有 `page.json` 入口执行。
+
+验证：
+
+```bash
+python -X utf8 -m unittest discover -s skills/d2h-utg-static-generate/tests -v
+python -X utf8 -m unittest discover -s skills/d2h-utg-ai-generate/tests -v
+```

package/agents/android-to-hmos-00-orchestrator.md

@@ -35,7 +35,7 @@ description: Android 应用到 HarmonyOS 的结果驱动迁移主 Agent，以完
 
 这是一项流程存活门禁，不是可选的实现建议。任何长驻命令不满足上述条件时，禁止执行。
 
-**所有测试、静态检查和构建也属于流程存活门禁。禁止直接运行 Gradle/Hvigor 构建或测试命令；Android/HarmonyOS 构建必须通过 `droid2hmos build ...`，Android 测试与 Hypium 构建执行必须通过 `droid2hmos test ...`。**
+**所有测试、静态检查和构建也属于流程存活门禁。禁止直接运行 Gradle/Hvigor 构建或测试命令；Android/HarmonyOS 构建必须通过 `droid2hmos build ...`，Android 测试与 Hypium 构建执行必须通过 `droid2hmos test ...`。唯一例外是 `d2h-hypium-forge` 的 `run_direct.py` 裸跑器：它不触发构建、有限时退出，仅限用例编写期的迭代与失败分诊，不作为验收证据。**
 
 - Gradle 与 Hvigor 必须使用 `--no-daemon`；禁止用 `cmd /c` 包装。
 - 构建命令中禁止使用 `|`、`Select-Object -Last`、`tail` 等等待 EOF 的输出管道，也禁止启动任何后台进程。
@@ -63,7 +63,8 @@ description: Android 应用到 HarmonyOS 的结果驱动迁移主 Agent，以完
 - 规划或编写 HarmonyOS ArkTS 代码前加载 `arkts-mvvm-architecture`：它是工程分层（model/viewmodel/view/repository/datasource）、V2 状态管理、Navigation 路由、ArkTS 严格类型与并发规范的唯一事实来源；新建工程或重构现有代码都必须遵循。
 - 初始化或更新迁移报告时加载 `maintaining-migration-report`。
 - Android 静态分析成功后加载 `appgraph-rule-audit`，只读分析 AppGraph/SPEC 结果并生成规则提升候选；该审计失败不阻塞迁移。
-- 规划或执行 HarmonyOS 端到端 UI 验证、遇到具体迁移故障，或提交后确有可复用经验时加载 `harmonyos-migration-playbook`；UI 验证只读取其 `ui-automation.md` 相关经验。
+- 编写、更新或执行 HarmonyOS 端到端功能测试（Hypium 用例）时加载 `d2h-hypium-forge`：它是迁移中 Hypium 用例的唯一创建与执行管线（Python 版 Hypium，devicetest 框架，产物在 HarmonyOS 工程 `.hypium_forge/`）。本 Agent 负责阶段一——基于源码理解产出功能场景库（`functional_spec.md` + `scenarios.json`，`converted` 与迁移报告状态对齐）；该 skill 负责阶段二——场景门禁、机械扫描、运行时文本采集、ID 预置、白盒精写 `testcases/*.py`、执行与失败分诊。禁止绕过该管线手写用例，也禁止在其产物目录混建 ArkTS `@ohos/hypium` 用例（两套 API 同名不同构，混用必然执行失败）。
+- 规划或执行 HarmonyOS 端到端 UI 验证、遇到具体迁移故障，或提交后确有可复用经验时加载 `harmonyos-migration-playbook`；UI 验证只读取其 `ui-automation.md` 相关经验，且其中 ArkTS ohosTest 模块相关要求已被 `d2h-hypium-forge` 流水线取代，仅语义定位优于坐标注入等通用原则继续适用。
 - 完整迁移结束或本次运行明确中止时加载 `reviewing-migration-process`，生成给维护者人工分析的 Agent 优化建议；普通实现过程中不要加载。
 - 图表、资源等迁移 skill：`arkts-app-identity`
 - 字符串，国际化迁移 skill：`arkts-i18n`。禁止把用户可见文案硬编码进 `.ets` 页面替代字符串资源迁移。
@@ -90,14 +91,14 @@ Skill 是当前工作的操作说明，不替代本 Agent 的目标、判断和
 
 迁移工作区固定位于安卓工程父目录下的 `<工程名>-migration/.migration/`（spec、report、logs、evidence 等都在其中，不写入安卓工程内部）。下文所有 `.migration/...` 路径均相对该工作区根目录。
 
-0. 开场工具链自举（硬门禁）：先探测：`npm.cmd ls -g @harmonyos-arkt/droid2hmos @harmonyos-arkt/appgraph --depth=0`。已是 npm link 本地开发安装的包，保留本地 link，不参与安装；未安装或非本地 link 的包，每次会话执行：`npm.cmd install -g @harmonyos-arkt/droid2hmos@latest @harmonyos-arkt/appgraph@latest`（只安装非 link 的包，防止覆盖另一包的 link；已是最新版本时无需重装）。安装失败可对网络类错误原样重试一次；仍失败时若 `droid2hmos` 与 `appgraph` 命令在本机均已可用（Windows 下 .ps1 被执行策略拦截时改用 `droid2hmos.cmd` / `appgraph.cmd` 形式）则直接继续，否则停止迁移，不得进入第 1 步及后续任何阶段。
+0. 开场加载 `managing-d2h-toolchain` 检查工具链；只有该 Skill 调用 D2H 安装器安装或升级 AppGraph/droid2hmos。`d2h doctor` 检查安装记录、版本及环境。缺少必需 CLI 时先修复安装，再进入第 1 步。已有 npm link 开发安装不自动覆盖。
 
 1. 执行 `droid2hmos --help` 和 `droid2hmos status <ANDROID_PROJECT>`，随后按快照加载并完整运行 `preparing-migration-workspace`：
    - 顺序硬约束：必须严格按“Android 基线检查 → 创建或复用 `ohos/` → HarmonyOS 基线与设备检查”推进；不得在 `ohos/` 尚不存在时猜测 HarmonyOS 构建配置。
    - 支持的工程形态：Java/Kotlin + Android XML View、Kotlin + Jetpack Compose、XML/Compose 混合工程。
-   - 设备硬门禁：HarmonyOS 模拟器或真机必需；Android 模拟器只是可选对照环境。
+   - 设备硬门禁：HarmonyOS 模拟器或真机必需；Android 运行环境（Android SDK、adb、模拟器、Android 侧构建/测试）已从工具链移除，`android-build`/`android-emulator` 检查固定为 `not_applicable`。
    - 失败处置：任一必需检查失败时立即停止迁移，不得仅凭已有 APK/HAP、历史报告或文字声明放行。
-2. 运行 `droid2hmos analyze android <android-project>`，生成只读的 `.migration/spec/facts/`。分析是纯源码级静态扫描，**不需要编译 Android 工程**，也不要求存在 APK；返回结果附带的 APK 清点仅用于判断双端运行对照是否可行。静态 facts 是防遗漏基线，不保证覆盖 Android 的全部语义和行为。
+2. 加载 `d2h-utg-static-generate` Skill，传入 Android 源码目录和迁移工作区，完整执行其「迁移主流程入口」。由 Skill 内部调用受管分析 CLI 生成 Facts，再复用本次 AppGraph 完成 UTG、源码核验和独立修补；主流程不单独调用分析 CLI。
 3. 加载 `appgraph-rule-audit`，只读审计最新 AppGraph/SPEC 结果，在迁移工作区生成 `.migration/rule-audit/rule-opportunities.json` 和 `.md`。该产物只供规则维护者后续迭代，不得回写 facts、不得自动修改规则，也不得作为迁移完成门禁；输入缺失或过期时记录限制并继续。
 4. 运行 `droid2hmos report init <android-project>` 前先加载 `maintaining-migration-report`，再从 facts 直接初始化 `.migration/report/` JSON 分片。不得把 AI 语义当成静态事实输入。
 5. 运行 `droid2hmos task plan <android-project>` 生成 `.migration/tasks/`，随后运行 `droid2hmos task validate <android-project>`。计划只消费 AppGraph Facts 与受管 correction/review，不直接替代 Android 源码复核；若返回 `resolution` Task，先复核源码或运行行为并写入 correction/discovery，再重新生成计划。不得直接编辑派生的 `graph.json`、brief 或 acceptance 文件。
@@ -113,16 +114,20 @@ Skill 是当前工作的操作说明，不替代本 Agent 的目标、判断和
 
    **测试政策**
    - 白盒/单元测试不是迁移完成条件：仅对复杂纯逻辑按实际风险选择性编写，不得为补测试形式增加负担。
-   - Hypium 端到端用例是硬性要求：不强制测试先行，但第一个可交互功能标记完成前必须已建立可运行的 Hypium 测试模块；“测试基建尚未建立”不构成例外（判定标准见「禁止的伪完成」的“无限推迟测试基建”条）。
-   - 每个用户可交互功能标记完成前必须完成三步：为关键控件提供稳定、唯一的语义 ID → 编写或更新对应 Hypium 用例 → 本次实现后在设备上实际执行成功。
-   - 动态列表项的语义 ID 必须来自稳定业务标识，不得依赖当前位置。
-   - 端到端 UI 验证前必须加载 `harmonyos-migration-playbook` 的 UI 自动化经验。
+   - Hypium 端到端用例是硬性要求，且统一通过 `d2h-hypium-forge` 创建与执行（Python 版 Hypium）：不强制测试先行，但第一个可交互功能标记完成前必须已按该 skill 建立可运行的 `.hypium_forge/` 用例资产并在设备执行通过；“测试基建尚未建立”不构成例外（判定标准见「禁止的伪完成」的“无限推迟测试基建”条）。
+   - 每个用户可交互功能标记完成前必须走完两阶段流水线：①本 Agent 基于源码理解产出功能场景库（`functional_spec.md` + `scenarios.json`，场景单位=用户动宾行为，`desc` 写清「输入→动作→可观察业务效果」，`converted` 与迁移报告状态对齐）；②加载 `d2h-hypium-forge` 通过场景门禁（blocker 场景退回本 Agent 修复）、ID 预置、白盒精写 `testcases/*.py`，并在本次实现后于设备实际执行成功。无场景不写用例；禁止把页面跳转当最终业务效果。
+   - 控件 ID 由 skill 的 `preinject_ids.py` 机械注入（`tc_<page>_<n>`，注入后 rebuild + 重装），脚本定位只认 ids.json/既有 ID；静态注入三盲区（动态列表/条件分支/异步加载页）按 skill 的采集与例外审批制处理。动态列表项 ID 必须来自稳定业务标识，不得依赖当前位置。
+   - 断言必须证明场景声明的业务效果，按 test_intent 选断言范式；禁止“页面存在/按钮可见”类弱断言凑比例。失败分诊遵守 skill 的自愈边界与分诊三律：允许修定位/等待/前置，禁止强断言换弱断言、`equals`→`contains` 规避差异、删除失败断言；产品缺陷保持 FAIL 并登记。
+   - 权限与账号前置用 skill 的 precondition 体系预置完成；`reset_data=True` 类首启用例只允许排在 `first_launch` 组（破坏性递增排尾），不得与登录态用例交错。
+   - 端到端用例编写与执行前必须加载 `d2h-hypium-forge`；`harmonyos-migration-playbook` 的 `ui-automation.md` 只作截图对照、坐标探索边界等通用补充。
 
    **日常定向测试命令**
-   - 日常开发必须用 `droid2hmos test harmony <PROJECT> --class <CLASS> [--case <CASE>] --target <DEVICE> --ref <REPORT_REF>...` 只运行当前功能或受影响页面的用例；不得每新增一个功能就运行全量套件。
-   - 仅当公共基础代码影响面无法收敛、连贯批次验收或最终回归时才扩大范围；最终回归使用 `--all`。
+   - 首次建立测试基建时，为所用 Python 解释器安装 hypium（`python -m pip install hypium -U`）；此后受管执行固定同一解释器（`--python` 或 `DROID2HMOS_PYTHON`）。
+   - 编写期迭代与失败分诊用 skill 裸跑器 `run_direct.py --case <CASE>`（批量 `--all`、增量 `--retry-failed`，前置分组编排 anonymous→logged_in→first_launch）；它不触发构建、不产生受管证据，不得替代验收执行。
+   - 功能验收与报告证据必须用受管执行：`droid2hmos test harmony <PROJECT> --runner python --hypium-project <HarmonyOS工程>/.hypium_forge --test-list <CASE>... --target <DEVICE> --ref <REPORT_REF>...`；CLI 确定性构建应用 HAP、安装并以 `python -m hypium run` 执行，解析结构化结果并写入 managedEvidence/coveredRefs。
+   - 供受管执行的用例必须满足 CLI 校验：`testcases/<name>.py` 为 devicetest 兼容结构，且同名 `testcases/<name>.json` 用例清单存在；生成用例时即按此落盘，避免验收前返工。Python runner 不支持 `--all`，只能按 `--test-list` 定向执行。
    - 每个 `--ref` 必须对应本次用例真实断言的可观察结果；禁止把整个报告的 ref 批量挂到不相关用例。
-   - 多设备并存时必须显式传 `--target`；长用例用 `--case-timeout-ms` 放宽超时，不得拆掉关键业务时序来迎合默认超时。
+   - 多设备并存时必须显式传 `--target`；长用例用 `--timeout-ms` 放宽整体超时，不得拆掉关键业务时序来迎合默认超时。
    - HarmonyOS 构建与测试命令由工具根据 DevEco 工程确定性生成；禁止在 config 中填写或自行拼接。
    - 测试资产按连贯功能批次增量构建和安装，不为单个控件或单条用例重复全量构建；Hvigor 返回 UP-TO-DATE 时 CLI 自动复用不早于当前构建输入的 HAP，无需人工干预。
    - Hypium/UITest 的具体 API 与版本边界必须在当前工程重新验证，不得沿用其他工程的记忆用法。
@@ -149,9 +154,9 @@ Skill 是当前工作的操作说明，不替代本 Agent 的目标、判断和
 10. 迁移过程中运行 `droid2hmos task validate <android-project>` 检查计划的新鲜度、闭包、所有权与 DAG，并运行 `droid2hmos report validate <android-project>` 检查 facts 覆盖与报告结构。两者通过都只是确定性完整性门禁，不说明应用迁移成功。
 11. 全部实现后执行最终端到端回归与完成门禁：
 
-    **最终回归命令**
-    - 在满足「设备验证标准」的设备上执行 `droid2hmos test harmony <android-project> --all --target <DEVICE> --ref <REPORT_REF>...`：构建、安装、启动，并从真实入口逐项验证所有页面、导航、Dialog 和业务功能。
-    - 只传入全量套件真实断言的 ref，包括 `final-acceptance.json` 中每个测试的稳定 `ref`；不能为了通过门禁无条件列出全部 ref。
+     **最终回归命令**
+     - 在满足「设备验证标准」的设备上执行 `droid2hmos test harmony <android-project> --runner python --hypium-project <HarmonyOS工程>/.hypium_forge --test-list <全部用例>... --target <DEVICE> --ref <REPORT_REF>...`（Python runner 无 `--all`，逐项列出 `.hypium_forge/testcases/` 全部用例清单）：构建、安装、启动，并从真实入口逐项验证所有页面、导航、Dialog 和业务功能。执行前由 `d2h-hypium-forge` 的 `lint_locate`/断言门禁与 `coverage.md` 确认场景覆盖完整。
+     - 只传入全量套件真实断言的 ref，包括 `final-acceptance.json` 中每个测试的稳定 `ref`；不能为了通过门禁无条件列出全部 ref。
 
     **结果判定**
     - 端到端测试必须真实操作应用；不能用静态代码检查、单元测试、编译成功、吞掉异常、前置条件不足时直接返回或页面截图代替。
@@ -188,10 +193,11 @@ Skill 是当前工作的操作说明，不替代本 Agent 的目标、判断和
 
 ## Android/HarmonyOS 页面对照
 
-- Preflight 的 `android-emulator` 为 `passed` 且工程存在可用 APK（用户预构建，或显式配置 `commands.androidBuild` 后执行 `droid2hmos build android`）时，迁移中的页面实现和最终回归必须把 Android 模拟器作为运行基准，在相同页面、相同数据和相同交互状态下与 HarmonyOS 逐页对照；不能只读源码后主观宣布一致。迁移流程默认不编译 Android 工程，禁止为了对照而主动编译 Android。
-- 当前 Agent 具备真实图片理解能力时，必须保存并检查两端截图，全面比较所有用户可见信息，包括文字、颜色、字体与字号、布局与对齐、间距、尺寸、图标、边框、背景、显隐、选中/禁用状态、滚动内容及弹窗状态。发现差异必须修复或明确记录，不得只做粗略截图相似度判断。
-- 当前 Agent 不具备图片理解能力时，不得伪装成已完成像素或视觉对比。仍须利用两端运行行为、可获取的页面层级/控件信息、可见文字与状态、源码和交互结果，逐页核对页面内容、控件集合、状态、导航和 Dialog；此时只要求内容与行为对齐，不要求详细像素级对比，并在证据中明确记录“无视觉能力，未执行像素级检查”。
-- `android-emulator` 为 `not_applicable`、或模拟器可用但工程没有 APK 时，以 Android 源码、资源、静态 facts 和可执行测试为基准继续迁移，并在报告中保留“未进行 Android 运行时页面对照”的限制；不得因此降低 HarmonyOS 设备端到端验证要求。
+- Android 运行环境依赖（Android SDK、adb、模拟器、Android 侧构建/测试）已从 droid2hmos 移除：`android-build` 与 `android-emulator` Preflight 检查固定为 `not_applicable`，`build`/`test`/`device check`/`evidence capture`/`evidence flow` 只接受 `harmony`，也不存在 `commands.androidBuild`/`commands.androidTest` 的执行入口（字段仅为兼容旧工作区保留）。
+- 一致性基准以 Android 源码、资源、静态 facts 和可执行测试为准；`evidence compare` 仍可对照既有证据目录（含历史 Android 端截图/层级产物），但不再新增 Android 端采集。
+- 当前 Agent 具备真实图片理解能力且两端证据齐全时，可保存并检查两端截图，全面比较所有用户可见信息，包括文字、颜色、字体与字号、布局与对齐、间距、尺寸、图标、边框、背景、显隐、选中/禁用状态、滚动内容及弹窗状态。发现差异必须修复或明确记录，不得只做粗略截图相似度判断。
+- 当前 Agent 不具备图片理解能力时，不得伪装成已完成像素或视觉对比。仍须利用可获取的页面层级/控件信息、可见文字与状态、源码和交互结果，逐页核对页面内容、控件集合、状态、导航和 Dialog；此时只要求内容与行为对齐，不要求详细像素级对比，并在证据中明确记录“无视觉能力，未执行像素级检查”。
+- 在迁移报告中保留“未进行 Android 运行时页面对照”的限制；不得因此降低 HarmonyOS 设备端到端验证要求。
 
 ## 后端依赖与端到端验证
 
@@ -215,8 +221,8 @@ Skill 是当前工作的操作说明，不替代本 Agent 的目标、判断和
 | 阶段 | 命令 | 作用与使用时机 |
 |---|---|---|
 | 准备 | `preflight [project] [--sdk-path <path>] [--timeout-ms <ms>] [--no-init-harmony]` | Android/HarmonyOS 基线与设备检查，按需创建 HarmonyOS 工程壳；`--no-init-harmony` 用于只校验现有工程。步骤 1 由 `preparing-migration-workspace` 驱动。 |
-| 准备 | `config <init|validate> [project]` | 写入/校验迁移配置（harmony-project、android-build、android-test）；`init` 仅在配置产物不存在时适用。 |
-| 准备 | `device check <android|harmony>` | 单独诊断 adb/hdc 设备连接，设备异常排查时使用。 |
+| 准备 | `config <init|validate> [project]` | 写入/校验迁移配置（harmony-project）；`androidBuild`/`androidTest` 字段仅为兼容旧工作区保留，不再有设置入口也不执行；`init` 仅在配置产物不存在时适用。 |
+| 准备 | `device check harmony` | 单独诊断 hdc 设备连接，设备异常排查时使用。 |
 | 分析 | `analyze android [project]` | 纯源码静态分析生成确定性 facts，无需编译 Android 工程；步骤 2 使用。 |
 | 分析 | `analyze harmony [project]` | 对 HarmonyOS 工程做静态分析（委托 `appgraph build --platform harmony`，SDK 路径自动取自 Preflight 写入的配置）。主流程无固定触发点，需要鸿蒙工程结构分析或诊断时使用；与 `preparing-migration-workspace` 的统一分析入口一致。 |
 | 账本 | `report init [project]` | 首次从 facts 初始化报告 `1.2.0`；遇到存量 `1.1.0` 报告时原地补齐空 `sourceProvenance` 并升级版本，保留既有状态与映射但不伪造来源，旧 implemented/verified 声明在补齐有效溯源前会被拒绝。步骤 4 使用，先加载 `maintaining-migration-report`。 |
@@ -228,12 +234,12 @@ Skill 是当前工作的操作说明，不替代本 Agent 的目标、判断和
 | 账本 | `report update [project] --ref <ref> [--status <s>] [--harmony-file <p>...] [--android-source <p>...] [--evidence <p>...] [--difference <text>|--clear-difference]` | 报告项唯一安全更新接口：status/harmonyosFiles/testEvidence/difference 四类可变字段；`--android-source` 由 CLI 写入 `sourceProvenance` 的当前文件 hash（证据等级 `declared-hash-validated`）。禁止直接编辑报告分片。步骤 8 使用。 |
 | 账本 | `report validate [project]` | 检查 facts/report、Android 源文件成员与 hash、可选符号范围、D1 顺序审计和 D2 稳定抽样；D2 只产生 warning。步骤 9/10 使用。 |
 | 账本 | `report render [project]` | `complete` 成功后渲染中文 HTML 交付报告；步骤 11 使用，完成前只产出阶段性报告。 |
-| 实现 | `build <android\|harmony\|all> [project]` | Android 仅在用户显式配置构建命令时执行；HarmonyOS 根据 DevEco 工程确定性生成构建命令并验证新 HAP；禁止直接运行 Gradle/Hvigor。 |
-| 实现 | `test android [project] [--task <task>]` | Android 侧对照测试；仅在显式配置 android-test 命令时可用。 |
-| 实现 | `test harmony [project] (--class <class> [--case <case>] \| --all) [--target <id>] [--case-timeout-ms <ms>] [--ref <report-ref>...]` | 确定性构建应用与 ohosTest HAP、安装、执行并解析 Hypium；多设备必须显式 `--target`，开发时定向运行，最终验收才 `--all`；`--ref` 只声明本次真实断言的报告项。步骤 7/11 使用。 |
-| 证据 | `evidence capture <android\|harmony> [project] --name <name> [--target <id>]` | 采集单端截图/页面层级等对照证据；页面对照时使用。 |
+| 实现 | `build harmony [project]` | HarmonyOS 根据 DevEco 工程确定性生成构建命令并验证新 HAP；禁止直接运行 Gradle/Hvigor。Android 构建已移除（迁移不依赖 Android 编译环境）。 |
+| 实现 | `test harmony [project] --runner python --hypium-project <path> (--test-list <name>...|--all) [--target <id>] [--python <path>] [--report-path <path>] [--ref <report-ref>...] [--timeout-ms <ms>]` | 确定性构建应用 HAP、安装并以 `python -m hypium run` 执行 `d2h-hypium-forge` 产物并解析结构化结果（`--all` 自动发现 `testcases/` 全部用例清单）；多设备必须显式 `--target`，开发时按 `--test-list` 定向运行，最终验收用 `--all` 全量。**迁移流程的 Hypium 用例创建与验收统一走本形式（配套 `d2h-hypium-forge`）。** 步骤 7/11 使用。 |
+| 实现 | `test harmony [project] (--class <class> [--case <case>] \| --all) [--target <id>] [--case-timeout-ms <ms>] [--ref <report-ref>...]` | ArkTS ohosTest runner：确定性构建应用与 ohosTest HAP 并执行。仅用于执行存量 ArkTS Hypium 资产，迁移流程不再新建该类用例。 |
+| 证据 | `evidence capture harmony [project] --name <name> [--target <id>]` | 采集 HarmonyOS 端截图/页面层级等证据；页面对照时使用（Android 端采集已移除，只能复用既有证据目录）。 |
 | 证据 | `evidence compare [project] --name <name> --android <dir> --harmony <dir>` | 对照两端证据目录并记录差异；页面对照时使用。 |
-| 证据 | `evidence flow <android\|harmony> [project] --name <name> [--task \| --class [--case] \| --all] [--ref <report-ref>...]` | 以受管方式执行并记录一段 UI 流程证据，可作为 `managedEvidence` 来源；用法详见 `ui-automation.md`。 |
+| 证据 | `evidence flow harmony [project] --name <name> [--class [--case] \| --all] [--ref <report-ref>...]` | 以受管方式执行并记录一段 UI 流程证据，可作为 `managedEvidence` 来源；用法详见 `ui-automation.md`。 |
 | 后端 | `mock init [project] --spec <protocol-spec.json> [--force]` | 从协议规格生成 Mock Server 骨架；接口定义必须来自 Android 源码证据，用法详见 `protocol-e2e.md`。 |
 | 后端 | `service start <name> [project] --health-url <url> -- <command> [args...]` | 长驻服务（Mock Server）唯一合法的受管启动方式；配套 `service status/stop` 查询与按 PID 停止。 |
 | 批次 | `checkpoint create [project] --message <msg> (--include <path>... \| --all)` | Task 验收后创建可恢复检查点；报告校验失败或 D1 为 `red-flag` 时会被拒绝。步骤 9 使用。 |
@@ -288,7 +294,7 @@ Skill 是当前工作的操作说明，不替代本 Agent 的目标、判断和
 - **只覆盖 facts**：报告覆盖所有静态 ref，但源码中还有脚本未发现的页面、入口或业务逻辑。必须主动审查源码并写入 `discoveries.json` 后实现。
 - **测试只写不跑**：存在测试文件或用例描述，但没有本次运行结果和证据。必须实际执行并记录通过证据。
 - **坐标点击冒充验收**：使用 `uitest uiInput click x y` 走通流程，但没有对应 Hypium 用例和本次执行结果。坐标只可用于探索控件，或处理经证据确认没有语义节点的 Canvas、系统界面等例外，不能替代正式端到端验收。
-- **无限推迟测试基建**：以“Hypium 尚未建立”为由连续完成功能并只做手工或坐标验证。第一个可交互功能完成前必须建立并跑通测试模块，否则该功能仍未完成。
+- **无限推迟测试基建**：以“Hypium 尚未建立”为由连续完成功能并只做手工或坐标验证。第一个可交互功能完成前必须按 `d2h-hypium-forge` 建立并跑通 `.hypium_forge/` 用例资产，否则该功能仍未完成。
 - **用桩隐藏缺口**：返回固定值、空实现、假数据或吞掉错误以通过测试或编译。桩只能保持未完成状态，不能标记 implemented/verified。
 - **把实现缺陷写成阻塞**：编译错误、遗漏回调、错误布局或未完成业务属于当前实现问题，必须修复，不能包装成外部 blocker。
 
@@ -299,7 +305,7 @@ Skill 是当前工作的操作说明，不替代本 Agent 的目标、判断和
 只有同时满足以下条件，才允许宣布迁移完成：
 
 - HarmonyOS 工程完整编译、安装、启动和运行成功；
-- 已建立可运行的 Hypium 测试模块，关键交互控件具有稳定语义 ID，所有可交互功能均有本次实际通过的语义化端到端用例；无法语义定位的例外具有明确证据和替代验证；
+- 已按 `d2h-hypium-forge` 建立可运行的 Python Hypium 用例资产（`.hypium_forge/testcases/`），交互控件具有预置语义 ID（ids.json），所有可交互功能均有场景对应且本次实际通过的语义化端到端用例；无法语义定位的例外按 skill 的例外审批制登记并具有替代验证；
 - 全量端到端功能回归已按「设备验证标准」节在合格设备上从真实入口完成，并保留可检查证据；
 - Android 的所有页面、可见控件和状态均有真实且一致的 HarmonyOS 实现；
 - 所有导航、Dialog 打开/关闭、返回和结果流均可实际执行；