@harmonyos-arkts/d2h 0.1.10 → 0.1.12

package/.claude-plugin/marketplace.json

@@ -1,13 +1,15 @@
-{
-  "name": "android-to-hmos-migration-local",
-  "description": "Android 到 HarmonyOS 迁移插件的本地开发市场",
-  "owner": { "name": "chuanqi" },
-  "plugins": [
-    {
-      "name": "android-to-hmos-migration",
-      "description": "基于确定性 facts 和迁移报告的 Android 到 HarmonyOS 迁移流程",
-      "version": "0.1.0",
-      "source": "./"
-    }
-  ]
-}
+{
+  "name": "android-to-hmos-migration-local",
+  "description": "Android 到 HarmonyOS 迁移插件的本地开发市场",
+  "owner": {
+    "name": "chuanqi"
+  },
+  "plugins": [
+    {
+      "name": "android-to-hmos-migration",
+      "description": "基于确定性 facts 和迁移报告的 Android 到 HarmonyOS 迁移流程",
+      "version": "0.1.0",
+      "source": "./"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -1,7 +1,13 @@
-{
-  "name": "android-to-hmos-migration",
-  "description": "基于确定性 facts、迁移报告与端到端验证的 Android 到 HarmonyOS 迁移插件",
-  "version": "0.1.0",
-  "license": "MIT",
-  "keywords": ["android", "harmonyos", "arkts", "migration", "appgraph"]
-}
+{
+  "name": "android-to-hmos-migration",
+  "description": "基于确定性 facts、迁移报告与端到端验证的 Android 到 HarmonyOS 迁移插件",
+  "version": "0.1.12",
+  "license": "MIT",
+  "keywords": [
+    "android",
+    "harmonyos",
+    "arkts",
+    "migration",
+    "appgraph"
+  ]
+}

package/AGENTS.md

@@ -1,5 +1,5 @@
-# Android to HarmonyOS Migration
-
-处理迁移请求时，由当前正式主 Agent `agents/d2h_v2.md` 统一编排专项 Skill。`agents/android-to-hmos-00-orchestrator.md` 和 `agents/d2h.md` 仅保留旧名称兼容，不是规则真源。
-
-以真实 HarmonyOS 应用质量为目标，以 AppGraph facts 和迁移报告降低遗漏风险。不要恢复已废弃的旧 SPEC/PLAN/TASK 多 Agent 文档流程或静态转译器；当前使用的 Kernel Task Plan（`droid2hmos task plan/validate/next/show` 派生计划）属于 Migration Kernel 协议，不在此列。
+# Android to HarmonyOS Migration
+
+处理迁移请求时，由当前正式主 Agent `agents/d2h_v2.md` 统一编排专项 Skill。`agents/android-to-hmos-00-orchestrator.md` 和 `agents/d2h.md` 仅保留旧名称兼容，不是规则真源。
+
+以真实 HarmonyOS 应用质量为目标，以 AppGraph facts 和迁移报告降低遗漏风险。不要恢复已废弃的旧 SPEC/PLAN/TASK 多 Agent 文档流程或静态转译器；当前使用的 Kernel Task Plan（`droid2hmos task plan/validate/next/show` 派生计划）属于 Migration Kernel 协议，不在此列。

package/README.md

@@ -1,213 +1,213 @@
-# android-to-hmos-migration
-
-Android 应用迁移到 HarmonyOS 的报告驱动 AI 插件，支持 Claude Code 与 OpenCode。
-
-插件以 Android 源码、外部依赖和 AppGraph 确定性 facts 为防遗漏基线，由一个主 Agent 持续完成原生 HarmonyOS 实现、测试和端到端验证。迁移报告只记录 Android→HarmonyOS 映射与测试证据，不替代真实实现。
-
-## 主流程
-
-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` 在 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)。
-Task 从真实入口到提取、闭包、合并、所有权、依赖、推荐和执行的完整原则见 [`docs/task-planning-principles.md`](docs/task-planning-principles.md)。
-
-## 保留结构
-
-```text
-android-to-hmos-migration/
-├── .claude-plugin/          # Claude Code 插件清单
-├── agents/                  # 报告驱动主 Agent
-├── docs/                    # 流程与 Task Planning Strategy 设计
-├── opencode/agents.json     # OpenCode Agent 权限
-├── schemas/                 # facts、报告与 Preflight 契约
-├── skills/                  # 工作区准备、工程架构规范、报告、经验和流程复盘
-└── install-opencode.sh      # OpenCode Agent/Skill 安装器
-```
-
-## 安装
-
-D2H 安装器按 `skills/managing-d2h-toolchain/toolchain.json` 中联测的版本安装 AppGraph、droid2hmos 和 Agent/Skill，原有行为保持不变。[`managing-d2h-toolchain`](skills/managing-d2h-toolchain/SKILL.md) 现在也能独立检查、按需安装同一工具组合，不依赖 `d2h` 命令：在 Skill 目录运行 `node scripts/manage-toolchain.mjs check`，未通过时运行 `node scripts/manage-toolchain.mjs install`。以下命令可使用 D2H 安装器；独立 Skill 脚本随本版本提供：
-
-```sh
-npx --yes @harmonyos-arkts/d2h@0.1.10 install --agent opencode
-npx --yes @harmonyos-arkts/d2h@0.1.10 install --agent vscode
-npx --yes @harmonyos-arkts/d2h@0.1.10 install --agent vscode --remote
-npx --yes @harmonyos-arkts/d2h@0.1.10 doctor --agent vscode
-npx --yes @harmonyos-arkts/d2h@0.1.10 upgrade --check
-npx --yes @harmonyos-arkts/d2h@0.1.10 --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)。受管 CLI 的全局 npm link 默认保留；显式运行 `d2h install --force --agent vscode` 或 Skill 的 `node scripts/manage-toolchain.mjs install --force` 才会替换全局链接，不会修改链接指向的源码目录。
-
-Claude Code：
-
-```text
-/plugin marketplace add D:/code/a2h/android-to-hmos-migration
-/plugin install android-to-hmos-migration@android-to-hmos-migration-local
-```
-
-OpenCode（Node.js 22.5–24.x，支持 Windows/macOS/Linux，无需克隆仓库或安装 Shell）：
-
-```sh
-npx --yes @harmonyos-arkts/d2h@0.1.10
-```
-
-安装器把 npm 包内的 `skills/` 和 `agents/` 复制到当前用户的 OpenCode 全局配置目录。更新已有安装时使用：
-
-```sh
-npx --yes @harmonyos-arkts/d2h@0.1.10 --force
-```
-
-先预览或指定目录：
-
-```sh
-npx --yes @harmonyos-arkts/d2h@0.1.10 --dry-run
-npx --yes @harmonyos-arkts/d2h@0.1.10 --config-dir /path/to/opencode
-```
-
-默认目标为 OpenCode，也可显式使用 `--agent opencode`。安装到 DevEco Code：
-
-```sh
-npx --yes @harmonyos-arkts/d2h@0.1.10 --agent deveco
-npx --yes @harmonyos-arkts/d2h@0.1.10 --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`，两者互不混用。安装时会在目标的 `opencode.json` 插件数组中加入仅用于 `d2h` 的 `opencode-metrics-plugin-lite`；加 `--remote` 则使用 `opencode-metrics-plugin`。重复安装会切换版本，不会同时启用两者。安装完成后重启对应应用；已有其他配置保留。`--config-dir` 与 `--agent` 的参数顺序不影响结果。
-
-默认目录按 `OPENCODE_CONFIG_DIR` → `$XDG_CONFIG_HOME/opencode` → `~/.config/opencode` 解析；Windows 默认 `%USERPROFILE%\.config\opencode`。安装器仅更新 `opencode.json` 的 metrics 插件条目，不会复制仓库的 `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@0.1.10 --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` 仅为旧名称兼容入口。
-
-## 命令
-
-```text
-droid2hmos init <android-project> [--target <harmony-project>]
-droid2hmos status <android-project>
-droid2hmos complete <android-project>
-droid2hmos analyze <android|harmony|all> <android-project>
-droid2hmos report init <android-project>
-droid2hmos report validate <android-project> [--require-complete]
-droid2hmos report update <android-project> --ref <ref> [--status <status>] [--harmony-file <path>] [--android-source <path>] [--evidence <path>]
-droid2hmos report <android-project> [--require-complete]
-droid2hmos report render <android-project>
-droid2hmos task plan <android-project>
-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 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...]
-droid2hmos service status <name> <android-project>
-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，仅作参考信息（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`：确定性构建应用 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`。
-
-## 核心产物
-
-迁移产物统一存放在安卓工程父目录下的独立工作区 `<AndroidProject>-migration/` 中，不再写入安卓工程内部。CLI 在创建 `.migration/` 前会自动在工作区根目录生成 `.gitignore`（内容 `.migration/`），防止迁移产物被上层 Git 仓库提交到远端：
-
-```text
-AndroidProject/.migration/
-├── preflight-report.json
-├── spec/
-│   ├── index.json
-│   ├── facts/
-│   └── spec.html
-├── report/
-│   ├── index.json
-│   ├── pages/
-│   ├── interactions/
-│   ├── discoveries.json
-│   ├── summary.json            # AI填写的用户总结
-│   ├── final-acceptance.json
-│   ├── validation.json
-│   └── report.html             # 脚本生成的用户报告
-├── tasks/
-│   ├── graph.json              # droid2hmos 生成的派生 Task DAG
-│   ├── index.json
-│   ├── briefs/*.md
-│   └── acceptance/*.json
-├── evidence/
-│   ├── index.json              # 最近一次受管动作证据索引
-│   ├── blobs/<sha256>/         # 完成门禁校验的内容寻址证据产物
-│   └── managed/*.json          # 与 facts/源码指纹绑定的 CLI 收据
-├── audit/
-│   ├── source-events.jsonl     # 可选可信有序事件输入
-│   ├── android-source-manifest.json # 受管 Android 成员与 hash
-│   ├── checkpoint-provenance.json  # 随受管 checkpoint 强制进入 Git commit
-│   ├── source-order-audit.json
-│   └── literal-drift-audit.json
-└── experience/lessons.md
-```
-
-AppGraph 保持独立仓库。Preflight 安装器始终解析 `Harmony-Ai-Tool/appgraph` 的 `main` 当前提交，按精确 SHA 隔离缓存到 `~/.android-to-hmos/tools/`；远端不可达时 Preflight 失败。
-
-## CLI 与校验
-
-```text
-droid2hmos --version
-droid2hmos --help
-```
-
-本仓库不再内置 CLI Implementation，也没有 Node.js 构建入口。Task Planning 的策略、Agent 流程和 JSON 契约维护在本仓库；Facts Adapter、闭包/所有权/DAG 编译、计划落盘和所有确定性命令由独立 `droid2hmos` 包实现。生成的计划位于被迁移 Android 工程的 `.migration/tasks/`，不写回任一工具仓库。
-
-Migration Kernel 在独立 CLI 中实现 `inspect → guard → execute → record`：阶段只是解释性快照，AI 仍自主决定批次和实现方式；命令前置条件、失败重试分类、证据新鲜度和最终完成条件由确定性代码检查。正常流程不依赖 AI 猜测“已经到达哪个节点”，也不要求写入 `.migration/state.json`。
-
-报告通过只证明已知 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` 验证清单与环境约束一致。D2H 安装器与 `managing-d2h-toolchain/scripts/manage-toolchain.mjs` 均使用这份清单；Skill 脚本可在没有 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
+# android-to-hmos-migration
+
+Android 应用迁移到 HarmonyOS 的报告驱动 AI 插件，支持 Claude Code 与 OpenCode。
+
+插件以 Android 源码、外部依赖和 AppGraph 确定性 facts 为防遗漏基线，由一个主 Agent 持续完成原生 HarmonyOS 实现、测试和端到端验证。迁移报告只记录 Android→HarmonyOS 映射与测试证据，不替代真实实现。
+
+## 主流程
+
+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` 在 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)。
+Task 从真实入口到提取、闭包、合并、所有权、依赖、推荐和执行的完整原则见 [`docs/task-planning-principles.md`](docs/task-planning-principles.md)。
+
+## 保留结构
+
+```text
+android-to-hmos-migration/
+├── .claude-plugin/          # Claude Code 插件清单
+├── agents/                  # 报告驱动主 Agent
+├── docs/                    # 流程与 Task Planning Strategy 设计
+├── opencode/agents.json     # OpenCode Agent 权限
+├── schemas/                 # facts、报告与 Preflight 契约
+├── skills/                  # 工作区准备、工程架构规范、报告、经验和流程复盘
+└── install-opencode.sh      # OpenCode Agent/Skill 安装器
+```
+
+## 安装
+
+D2H 安装器按 `skills/managing-d2h-toolchain/toolchain.json` 中联测的版本安装 AppGraph、droid2hmos 和 Agent/Skill，原有行为保持不变。[`managing-d2h-toolchain`](skills/managing-d2h-toolchain/SKILL.md) 现在也能独立检查、按需安装同一工具组合，不依赖 `d2h` 命令：在 Skill 目录运行 `node scripts/manage-toolchain.mjs check`，未通过时运行 `node scripts/manage-toolchain.mjs install`。以下命令可使用 D2H 安装器；独立 Skill 脚本随本版本提供：
+
+```sh
+npx --yes @harmonyos-arkts/d2h@0.1.11 install --agent opencode
+npx --yes @harmonyos-arkts/d2h@0.1.11 install --agent vscode
+npx --yes @harmonyos-arkts/d2h@0.1.11 install --agent vscode --remote
+npx --yes @harmonyos-arkts/d2h@0.1.11 doctor --agent vscode
+npx --yes @harmonyos-arkts/d2h@0.1.11 upgrade --check
+npx --yes @harmonyos-arkts/d2h@0.1.11 --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)。受管 CLI 的全局 npm link 默认保留；显式运行 `d2h install --force --agent vscode` 或 Skill 的 `node scripts/manage-toolchain.mjs install --force` 才会替换全局链接，不会修改链接指向的源码目录。
+
+Claude Code：
+
+```text
+/plugin marketplace add D:/code/a2h/android-to-hmos-migration
+/plugin install android-to-hmos-migration@android-to-hmos-migration-local
+```
+
+OpenCode（Node.js 22.5–24.x，支持 Windows/macOS/Linux，无需克隆仓库或安装 Shell）：
+
+```sh
+npx --yes @harmonyos-arkts/d2h@0.1.11
+```
+
+安装器把 npm 包内的 `skills/` 和 `agents/` 复制到当前用户的 OpenCode 全局配置目录。更新已有安装时使用：
+
+```sh
+npx --yes @harmonyos-arkts/d2h@0.1.11 --force
+```
+
+先预览或指定目录：
+
+```sh
+npx --yes @harmonyos-arkts/d2h@0.1.11 --dry-run
+npx --yes @harmonyos-arkts/d2h@0.1.11 --config-dir /path/to/opencode
+```
+
+默认目标为 OpenCode，也可显式使用 `--agent opencode`。安装到 DevEco Code：
+
+```sh
+npx --yes @harmonyos-arkts/d2h@0.1.11 --agent deveco
+npx --yes @harmonyos-arkts/d2h@0.1.11 --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`，两者互不混用。安装时会在目标的 `opencode.json` 插件数组中加入仅用于 `d2h` 的 `opencode-metrics-plugin-lite`；加 `--remote` 则使用 `opencode-metrics-plugin`。重复安装会切换版本，不会同时启用两者。安装完成后重启对应应用；已有其他配置保留。`--config-dir` 与 `--agent` 的参数顺序不影响结果。
+
+默认目录按 `OPENCODE_CONFIG_DIR` → `$XDG_CONFIG_HOME/opencode` → `~/.config/opencode` 解析；Windows 默认 `%USERPROFILE%\.config\opencode`。安装器仅更新 `opencode.json` 的 metrics 插件条目，不会复制仓库的 `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@0.1.11 --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` 仅为旧名称兼容入口。
+
+## 命令
+
+```text
+droid2hmos init <android-project> [--target <harmony-project>]
+droid2hmos status <android-project>
+droid2hmos complete <android-project>
+droid2hmos analyze <android|harmony|all> <android-project>
+droid2hmos report init <android-project>
+droid2hmos report validate <android-project> [--require-complete]
+droid2hmos report update <android-project> --ref <ref> [--status <status>] [--harmony-file <path>] [--android-source <path>] [--evidence <path>]
+droid2hmos report <android-project> [--require-complete]
+droid2hmos report render <android-project>
+droid2hmos task plan <android-project>
+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 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...]
+droid2hmos service status <name> <android-project>
+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，仅作参考信息（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`：确定性构建应用 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`。
+
+## 核心产物
+
+迁移产物统一存放在安卓工程父目录下的独立工作区 `<AndroidProject>-migration/` 中，不再写入安卓工程内部。CLI 在创建 `.migration/` 前会自动在工作区根目录生成 `.gitignore`（内容 `.migration/`），防止迁移产物被上层 Git 仓库提交到远端：
+
+```text
+AndroidProject/.migration/
+├── preflight-report.json
+├── spec/
+│   ├── index.json
+│   ├── facts/
+│   └── spec.html
+├── report/
+│   ├── index.json
+│   ├── pages/
+│   ├── interactions/
+│   ├── discoveries.json
+│   ├── summary.json            # AI填写的用户总结
+│   ├── final-acceptance.json
+│   ├── validation.json
+│   └── report.html             # 脚本生成的用户报告
+├── tasks/
+│   ├── graph.json              # droid2hmos 生成的派生 Task DAG
+│   ├── index.json
+│   ├── briefs/*.md
+│   └── acceptance/*.json
+├── evidence/
+│   ├── index.json              # 最近一次受管动作证据索引
+│   ├── blobs/<sha256>/         # 完成门禁校验的内容寻址证据产物
+│   └── managed/*.json          # 与 facts/源码指纹绑定的 CLI 收据
+├── audit/
+│   ├── source-events.jsonl     # 可选可信有序事件输入
+│   ├── android-source-manifest.json # 受管 Android 成员与 hash
+│   ├── checkpoint-provenance.json  # 随受管 checkpoint 强制进入 Git commit
+│   ├── source-order-audit.json
+│   └── literal-drift-audit.json
+└── experience/lessons.md
+```
+
+AppGraph 保持独立仓库。Preflight 安装器始终解析 `Harmony-Ai-Tool/appgraph` 的 `main` 当前提交，按精确 SHA 隔离缓存到 `~/.android-to-hmos/tools/`；远端不可达时 Preflight 失败。
+
+## CLI 与校验
+
+```text
+droid2hmos --version
+droid2hmos --help
+```
+
+本仓库不再内置 CLI Implementation，也没有 Node.js 构建入口。Task Planning 的策略、Agent 流程和 JSON 契约维护在本仓库；Facts Adapter、闭包/所有权/DAG 编译、计划落盘和所有确定性命令由独立 `droid2hmos` 包实现。生成的计划位于被迁移 Android 工程的 `.migration/tasks/`，不写回任一工具仓库。
+
+Migration Kernel 在独立 CLI 中实现 `inspect → guard → execute → record`：阶段只是解释性快照，AI 仍自主决定批次和实现方式；命令前置条件、失败重试分类、证据新鲜度和最终完成条件由确定性代码检查。正常流程不依赖 AI 猜测“已经到达哪个节点”，也不要求写入 `.migration/state.json`。
+
+报告通过只证明已知 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` 验证清单与环境约束一致。D2H 安装器与 `managing-d2h-toolchain/scripts/manage-toolchain.mjs` 均使用这份清单；Skill 脚本可在没有 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
 ```