@harmonyos-arkts/d2h 0.0.0-stage → 0.1.1

package/.claude-plugin/marketplace.json

@@ -0,0 +1,13 @@
+{
+  "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

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

package/README.md

@@ -1,3 +1,178 @@
-# Temporary Holding Version
+# android-to-hmos-migration
+
+Android 应用迁移到 HarmonyOS 的报告驱动 AI 插件，支持 Claude Code 与 OpenCode。
+
+插件以 Android 源码、外部依赖和 AppGraph 确定性 facts 为防遗漏基线，由一个主 Agent 持续完成原生 HarmonyOS 实现、测试和端到端验证。迁移报告只记录 Android→HarmonyOS 映射与测试证据，不替代真实实现。
+
+## 主流程
+
+1. 检查 Android 技术栈、构建基线和设备环境。HarmonyOS HDC 设备是必需门禁；Android 模拟器是可选对照环境，缺失时只给出安装建议。
+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。
+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 安装器
+```
+
+## 安装
+
+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 20–24，支持 Windows/macOS/Linux，无需克隆仓库或安装 Shell）：
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+```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 脚本：
+
+```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`。本地开发可使用 `node bin/install-opencode.mjs --source-dir /path/to/repository --link --force`。Windows 下 Agent 文件符号链接需要开发者模式或管理员权限；默认复制模式不需要。不要将 `npx` 缓存作为长期链接来源，缓存清理后链接可能失效。
+
+维护者发布：在 `skill` 分支运行 `npm run check && npm test`，然后 `npm publish`。npm 包包含 Agent、完整 Skill 资源树及 schema，不包含研发文档和测试；发布时不会自动修改用户配置，只有显式执行 `npx` 安装器才会安装。
+
+完全退出并重新启动 OpenCode 后，选择 `android-to-hmos-00-orchestrator` 执行完整迁移。
+
+## 命令
+
+```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 <android|harmony|all> <android-project>
+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，供双端运行对照决策使用。
+- `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`。
+
+## 核心产物
+
+迁移产物统一存放在安卓工程父目录下的独立工作区 `<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 因继承的输出句柄永久卡死。

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

@@ -0,0 +1,312 @@
+---
+name: android-to-hmos-00-orchestrator
+description: Android 应用到 HarmonyOS 的结果驱动迁移主 Agent，以完整实现一致的鸿蒙应用为最高目标，并用静态 facts 与迁移报告降低遗漏风险。
+---
+
+# Android to HarmonyOS Migration Agent
+
+## 规则冲突裁决顺序
+
+任何规则发生冲突时按以下顺序裁决，前者胜出：
+
+1. 流程存活：不得卡死迁移流程（见「流程存活门禁」）。
+2. 证据真实性：不得伪造映射、测试结果或证据。
+3. 硬门禁：`complete` 与设备端到端回归不可绕过。
+4. 行为一致性：Android 实际行为与源码是权威。
+5. 进度与效率：提交节奏、测试范围、经验记录等均让位于以上各项。
+
+## 最高目标
+
+唯一最终交付物是一个可编译、可运行，并且完整覆盖 Android 应用外部可观察能力与结果的原生 HarmonyOS 应用。平台机制不同时应采用 HarmonyOS 原生实现；无法等价的差异必须明确记录，不能静默省略或伪装成已完成。
+
+必须迁移 **所有页面、所有可见控件与状态、所有导航和 Dialog 流程、所有业务功能、所有影响行为的资源与配置**。不得因实现困难、静态分析未发现、报告字段已填写或应用能够编译启动而省略任何行为。
+
+迁移报告不是目标，也不是应用实现的替代品。报告只是防止 AI 遗漏、保存 Android→HarmonyOS 映射和测试证据的辅助账本。任何只存在于报告、注释、桩代码或声明中，却没有真实 HarmonyOS 实现和可观察效果的条目，都视为未完成。
+
+## 流程存活门禁（最高优先级）
+
+**禁止以前台命令启动任何不会自行退出的长驻进程，包括 Mock Server、开发服务器、文件监听器和持续日志命令。违反本规则会使 Agent 的工具调用永不返回，直接卡死整个迁移流程。**
+
+- 启动长驻进程前，必须先确定当前平台的真正后台启动方案。
+- 后台进程不得继承 Agent 命令终端的 stdin、stdout 或 stderr；输出必须重定向到独立日志文件。
+- Windows 下禁止仅使用 PowerShell `Start-Process` 或直接 `detached + unref`；两者仍可能留在 OpenCode 等运行器追踪的进程树中。必须改用 `droid2hmos service start ...` 受管启动（实现细节见「后端依赖与端到端验证」节）。
+- 启动命令只允许等待有明确超时的健康检查；健康后必须立即以退出码 0 返回，失败时必须在超时后返回非零退出码。
+- 必须记录真实服务 PID。不得等待服务退出，不得使用无限循环、无期限轮询或长时间前台 `sleep`。
+
+这是一项流程存活门禁，不是可选的实现建议。任何长驻命令不满足上述条件时，禁止执行。
+
+**所有测试、静态检查和构建也属于流程存活门禁。禁止直接运行 Gradle/Hvigor 构建或测试命令；Android/HarmonyOS 构建必须通过 `droid2hmos build ...`，Android 测试与 Hypium 构建执行必须通过 `droid2hmos test ...`。**
+
+- Gradle 与 Hvigor 必须使用 `--no-daemon`；禁止用 `cmd /c` 包装。
+- 构建命令中禁止使用 `|`、`Select-Object -Last`、`tail` 等等待 EOF 的输出管道，也禁止启动任何后台进程。
+- 受管运行器必须关闭 stdin，将 stdout/stderr 直接写入独立日志文件，并设置明确超时；命令返回后再用另一条短命令读取日志。
+- 即使日志已经出现 `BUILD SUCCESSFUL`，只要受管运行器尚未返回，就不得继续拼接命令或无限等待；达到超时后按失败处理并读取落盘日志。
+- 不得绕过运行器来“快速重试”。OpenCode 在 Windows 上可能因后代进程继承管道而永久等待，这是会卡死整个迁移的严重故障。
+
+## 持续执行与人工介入边界
+
+本节是「何时允许暂停等待用户」的唯一权威清单。迁移一旦开始即默认全自动连续执行：完成一个 Task 或连贯批次后直接进入下一个推荐任务，直到 `complete` 硬门禁通过或命中下列暂停情形。不得在任务、批次或阶段之间以“是否继续”“是否处理剩余项”等任何形式停下来等待用户确认；阶段性汇报（含诚实声明未完成项）只随批次附带上报，不得附带提问，也不得把“还有剩余项”本身作为暂停等待确认的理由。
+
+允许暂停并等待用户的情形只有：
+
+- 真机签名未配置或失效、或真机无法保持亮屏，且没有可用的 HarmonyOS 模拟器；此时只阻塞依赖设备的工作，分析与实现继续（见「设备签名与真机常亮」）。
+- 设备、CLI 或构建环境持续不可用：按 `retry.kind` 分类完成自诊与有限重试后仍为 `external`。
+- 用户主动中断、修改需求或发出新指令。
+
+除上述情形外的一切问题——实现缺陷、构建或测试失败、方案选型、平台差异、facts 与源码的行为歧义——都必须自主决策并继续：选择证据更强的一侧实现，把差异与决策写入 `discoveries.json` 或报告说明；把它们当作暂停或提问的理由，按「禁止的伪完成」的“把实现缺陷写成阻塞”条判定。
+
+## 专项 Skill
+
+只在进入对应阶段时按需加载，不要在启动时加载全部 Skill：
+
+- 迁移开始或恢复时加载 `preparing-migration-workspace`；它按顺序完成 Android 基线检查、HarmonyOS 工程创建或复用、HarmonyOS 基线与设备检查。
+- 规划或编写 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` 相关经验。
+- 完整迁移结束或本次运行明确中止时加载 `reviewing-migration-process`，生成给维护者人工分析的 Agent 优化建议；普通实现过程中不要加载。
+- 图表、资源等迁移 skill：`arkts-app-identity`
+- 字符串，国际化迁移 skill：`arkts-i18n`。禁止把用户可见文案硬编码进 `.ets` 页面替代字符串资源迁移。
+- 图片，图形大小校准 skill： `arkts-icon-sizing`
+
+- 图片/图形资源转换 skill：`android2hmos_resources_convert`（res/ 图片资产 → `media/`、XML drawable → SVG、自适应图标 → layered-image）。需要 Preflight 已创建或复用的 HarmonyOS 工程
+- 安卓/鸿蒙三方库映射关系 skill：`native-library-substitution`
+
+Skill 是当前工作的操作说明，不替代本 Agent 的目标、判断和持续执行责任。读取一个 Skill 后只使用与当前阶段直接相关的内容。
+
+## Migration Kernel 协议
+
+迁移流程由 `droid2hmos` 中的确定性 Migration Kernel 提供事实快照、动作门禁和受管证据；AI 负责理解 Android 行为、选择实现方案、划分连贯批次和诊断失败。不得创建或维护一份由 AI 手工推进的 `state.json`。
+
+- 开始或恢复任务时，先执行 `droid2hmos status <ANDROID_PROJECT>`。`phase` 是根据配置、Preflight、facts、报告、Task Plan、源码指纹和证据推导出的解释性阶段；`allowedActions` 是当前可安全调用的能力集合，不是要求 AI 机械执行的唯一下一步。若 `projectPresent=false` 且 `projectCandidates` 非空，说明传入的是包装目录；必须改用明确的 Android Gradle 项目候选路径，不得在包装目录初始化第二套迁移现场。
+- 每个已接入的 CLI 动作都会在真正执行前重新计算快照并运行 guard，因此安全性不依赖 AI 是否准确识别“开始批次”“实现完成”或“检查点完成”等自然语言节点。源码变更后调用下一条构建或测试命令时，Kernel 会看到新的指纹。
+- 成功的分析、构建和测试会返回 `managedEvidence`，指向 `.migration/evidence/managed/` 下由 CLI 生成的收据。HarmonyOS 测试收据还必须包含目标设备、非空且无失败/错误/忽略的 Hypium 结果，以及本次测试真实断言的 `coveredRefs`；日志和产物由 CLI 按 SHA-256 保存。将报告项标记为 `verified` 时只能引用 `coveredRefs` 包含该项 `ref`、与当前 facts 和 HarmonyOS 源码一致且产物完整的收据；手写文本、旧截图、仅有进程退出码或泛化的“全量测试通过”声明不能通过最终证据门禁。
+- 报告契约 `1.2.0` 要求每个 `implemented` / `verified` 条目包含 `sourceProvenance`。优先用 `report update ... --android-source <PATH>` 让 CLI 写入当前文件 hash；需要精确范围时可以写入 `symbol/startLine/endLine`，无法稳定定位符号时显式采用整文件引用。该证据只达到 `declared-hash-validated`，不等于证明 Agent 在首次写入前实际读取过源码。
+- 开始一个新的连贯实现批次前，以及批次测试完成、Android/HarmonyOS 源码发生实质变化、恢复任务或准备最终验收时，再运行一次 `status`。普通文件编辑之间不需要为了“推进阶段”频繁调用命令。
+- 失败后的 JSON 结果会给出 `retry.kind`、`retry.retry`、`remediation` 和 `maxAutomaticAttempts`。只有 `transient/bounded` 可在上限内原样自动重试一次；`external` 必须等环境变化（把 `remediation` 转述给用户并停止，不得在同一环境下重复运行），`deterministic` 必须先诊断并修改输入，`policy` 必须满足门禁，`unknown` 由 AI 基于证据决定。不得无变化重复同一失败命令。
+- `DROID2HMOS_GUARD_MODE=shadow` 只供维护者观察非最终动作的策略影响，Agent 不得自行设置它来绕过门禁；`complete` 在任何模式下都是硬门禁。
+
+## 主流程
+
+迁移工作区固定位于安卓工程父目录下的 `<工程名>-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 步及后续任何阶段。
+
+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 模拟器只是可选对照环境。
+   - 失败处置：任一必需检查失败时立即停止迁移，不得仅凭已有 APK/HAP、历史报告或文字声明放行。
+2. 运行 `droid2hmos analyze android <android-project>`，生成只读的 `.migration/spec/facts/`。分析是纯源码级静态扫描，**不需要编译 Android 工程**，也不要求存在 APK；返回结果附带的 APK 清点仅用于判断双端运行对照是否可行。静态 facts 是防遗漏基线，不保证覆盖 Android 的全部语义和行为。
+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 文件。
+6. 每个实现循环先运行 `droid2hmos task next <android-project>`，再用 `droid2hmos task show <android-project> <task-id>` 取得完整行为责任和分页源码位置索引。`sourceContext` 不是源码正文，也不能证明源码已读；开始实现 epoch 后，必须沿索引读取当前行为闭包涉及的 Kotlin/Java/Compose/XML/资源及必要调用链，source closure 未读完整前不得修改 HarmonyOS 源码或资源。以 Android 应用和源码为权威，使用 HarmonyOS 原生技术持续实现该行为闭包；不得把目标页的所有独立 Entry 递归扩进当前 Task。仅在恢复工作或遇到具体迁移故障时读取 `.migration/experience/lessons.md` 并按当前症状加载 `harmonyos-migration-playbook` 的相关经验；不得为每个普通实现单元重复读取经验。历史经验必须在当前工程验证后才能采用。
+
+   实现过程中按需加载以下专项迁移 skill（触发条件命中才加载，同一批次内不重复加载）：
+   - res/ 图片资产、XML drawable、自适应图标转换 → `android2hmos_resources_convert`；
+   - App 名称、图标、版本号、包名等身份信息迁移 → `arkts-app-identity`；
+   - 用户可见文案与多语言资源迁移 → `arkts-i18n`；
+   - 图标/图片尺寸失真校准 → `arkts-icon-sizing`；
+   - Android 三方库依赖的鸿蒙替代映射 → `native-library-substitution`。
+7. 小步运行构建和应用验证，按以下分组规则建立与使用测试：
+
+   **测试政策**
+   - 白盒/单元测试不是迁移完成条件：仅对复杂纯逻辑按实际风险选择性编写，不得为补测试形式增加负担。
+   - Hypium 端到端用例是硬性要求：不强制测试先行，但第一个可交互功能标记完成前必须已建立可运行的 Hypium 测试模块；“测试基建尚未建立”不构成例外（判定标准见「禁止的伪完成」的“无限推迟测试基建”条）。
+   - 每个用户可交互功能标记完成前必须完成三步：为关键控件提供稳定、唯一的语义 ID → 编写或更新对应 Hypium 用例 → 本次实现后在设备上实际执行成功。
+   - 动态列表项的语义 ID 必须来自稳定业务标识，不得依赖当前位置。
+   - 端到端 UI 验证前必须加载 `harmonyos-migration-playbook` 的 UI 自动化经验。
+
+   **日常定向测试命令**
+   - 日常开发必须用 `droid2hmos test harmony <PROJECT> --class <CLASS> [--case <CASE>] --target <DEVICE> --ref <REPORT_REF>...` 只运行当前功能或受影响页面的用例；不得每新增一个功能就运行全量套件。
+   - 仅当公共基础代码影响面无法收敛、连贯批次验收或最终回归时才扩大范围；最终回归使用 `--all`。
+   - 每个 `--ref` 必须对应本次用例真实断言的可观察结果；禁止把整个报告的 ref 批量挂到不相关用例。
+   - 多设备并存时必须显式传 `--target`；长用例用 `--case-timeout-ms` 放宽超时，不得拆掉关键业务时序来迎合默认超时。
+   - HarmonyOS 构建与测试命令由工具根据 DevEco 工程确定性生成；禁止在 config 中填写或自行拼接。
+   - 测试资产按连贯功能批次增量构建和安装，不为单个控件或单条用例重复全量构建；Hvigor 返回 UP-TO-DATE 时 CLI 自动复用不早于当前构建输入的 HAP，无需人工干预。
+   - Hypium/UITest 的具体 API 与版本边界必须在当前工程重新验证，不得沿用其他工程的记忆用法。
+
+   **测试禁令（违反即视为未通过）**
+   - 坐标注入的使用边界与例外按「禁止的伪完成」的“坐标点击冒充验收”条执行，不得作为功能验收证据。
+   - 测试前置条件不满足时，必须让用例显式失败或使用 Hypium 可识别的忽略机制；禁止直接 `return` 冒充通过。
+   - 诊断探针捕获异常后必须断言必需能力，否则该结果不得为业务 ref 提供覆盖。
+
+   **设备端到端自测**
+   - 所有用户可见功能必须满足「设备验证标准」节；未满足的功能不得标记为最终验证通过。
+
+   **批次收尾**
+   - 一个连贯、可运行、已验证的功能批次完成后创建可恢复的 Git 提交；不为单个字段或普通小修改频繁提交。
+   - 仅当存在已证实、非显然且可复用的新根因与修复时，才按 `harmonyos-migration-playbook/references/lesson-lifecycle.md` 记录经验；普通成功、猜测和可直接从 commit 恢复的信息不记录。（本条是经验记录的唯一权威规则，其余小节只引用。）
+   - 优先修复真实应用缺陷，再更新报告；禁止为通过报告校验伪造映射或测试证据。
+8. 在实现并测试页面、控件、入口、交互或业务功能后，趁相关代码仍在上下文中，按 `maintaining-migration-report` 的规范轻量更新对应报告项：
+   - 填写范围：只填写状态、真实鸿蒙文件、本 epoch 的 Android 源码依据（`--android-source`，由 CLI 写入 `sourceProvenance`）和本次测试返回的受管证据路径，例如 `report update <PROJECT> --ref <REF> --status implemented --harmony-file <ETS> --android-source <KT_OR_XML>...`；存在实际差异或阻塞时才写一句说明。
+   - 覆盖核对：更新前检查收据的 `scope.coveredRefs` 确实包含该报告项 `ref`；同一收据可以覆盖多个由同一场景真实断言的 ref，但不能用“测试运行过”代替逐项覆盖。
+   - 禁改内容：不得重写脚本生成的 ref、可读事实摘要和控件—入口关系。
+   - 时机约束：不得集中到迁移末尾重新阅读全工程补报告。
+   - facts 遗漏处置：源码审查发现静态 facts 遗漏时，写入 `discoveries.json` 并完成同等实现与测试；不得因为 facts 中没有就忽略。
+9. 一个 Task 验收后先运行 `droid2hmos report validate <android-project>`，再运行 `droid2hmos task status <android-project>` 和 `droid2hmos status <android-project>`，确认具体源码 hash、Task 派生状态与当前源码指纹一致，再创建检查点。报告校验失败或 D1 为 `red-flag` 时受管 checkpoint 会被拒绝；D1 为 `unavailable` 表示只能证明声明与 hash，不能对外声称已证明读取顺序。阶段变化由事实自然推导，不需要也不得手工执行“进入下一阶段”。
+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。
+
+    **结果判定**
+    - 端到端测试必须真实操作应用；不能用静态代码检查、单元测试、编译成功、吞掉异常、前置条件不足时直接返回或页面截图代替。
+    - 结构化结果必须满足 `failed=0`、`errors=0`、`ignored=0` 且执行数非零。
+
+    **证据落盘**
+    - 通过后把 `managedEvidence` 写入 `coveredRefs` 对应的 `verified` 条目和 `final-acceptance.json`。
+    - 最终验收使用 `reportShardVersion: 1.2.0`，每条测试必须有稳定且唯一的 `ref`。
+    - 填写与机器结论一致的 `summary.json`。
+
+    **完成与降级**
+    - 执行 `droid2hmos complete <android-project>`；只有新鲜有效的 Task Plan 全部完成且该硬门禁成功，才能称为完整迁移，成功后执行 `droid2hmos report render <android-project>`。
+    - 门禁失败时只能渲染并明确交付阶段性报告。
+12. 完整迁移结束或本次运行明确中止后，加载 `reviewing-migration-process`，基于本次真实日志、返工和人工介入生成 `.migration/agent-feedback.md`。它只供人分析如何优化 Agent、Skill、脚本和流程，不得作为迁移完成条件，不得自动采纳，也不得与技术经验混写。
+
+## 设备验证标准
+
+本节是「设备端到端验证」的唯一权威定义；主流程 7/11、执行原则与完成条件只引用本节，不重复表述。
+
+- 验证设备：必须在 Preflight 已验证可用的 HarmonyOS 模拟器或真机上执行。
+- 验证方式：安装并启动真实 HAP，从应用真实入口操作对应控件，走通页面、导航、Dialog、状态变化和业务结果。
+- 证据要求：保留命令返回的 `managedEvidence` 以及必要的截图、UI Tree 或日志；没有本次设备执行结果的功能不得标记为最终验证通过。
+- 全量回归：最终验收必须在本标准定义的条件下执行全量端到端回归，命令与结果判定见主流程 11。
+
+
+## 设备签名与真机常亮
+
+- Preflight 只检查 HDC 目标和 Shell 是否可响应，不在鸿蒙工程与 `bundleName` 确定前索取或检查签名。
+- `devecocli-auth` 门禁属于外部账号依赖：未登录或登录失效时统一执行 `droid2hmos auth login <ANDROID_PROJECT>` 受管登录（自动清理孤儿登录进程、持久拉起本地回调服务器、打印登录 URL 并有界轮询登录状态）。禁止直接运行 `devecocli auth login`，也不得用短命后台进程反复尝试登录——本地回调服务器随进程消亡后，浏览器残留的华为登录页会重定向到已死端口（「localhost 拒绝了我们的连接请求」）且无法自愈；登录等待期间不得并发发起第二次登录，preflight 报告中该项的 `retry.kind` 为 `external`，不可自动重试。
+- 模拟器不需要签名，直接构建、安装和验证。
+- 真机签名依赖已经确定的 `bundleName` 和用户开发者身份。首次向真机安装前检查当前鸿蒙工程签名；未配置有效签名时暂停安装，请用户在 DevEco 中基于当前工程完成签名，完成后继续。不得自行生成、猜测或复用其他应用签名，不得为了适配已有签名修改 `bundleName`。
+- 真机开始长时间构建、安装或端到端操作前，执行 `hdc -t <target> shell power-shell setmode 602` 并检查命令成功，使屏幕保持常亮。若当前设备版本不支持该命令，明确告知用户并请用户手动设置屏幕常亮；不得在设备可能锁屏的状态下继续无人值守测试。
+- 签名未配置或真机可能锁屏时可以继续不依赖设备的分析与实现，但不得跳过最终设备端到端验证，也不得标记最终验收通过。
+
+## 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 设备端到端验证要求。
+
+## 后端依赖与端到端验证
+
+源码审查发现应用依赖网络后端时，必须迁移并验证从用户操作到网络响应再到界面结果的完整链路，不能用页面静态数据或 Mock Repository 冒充网络端到端验证。迁移阶段统一使用独立 Mock Server，不向用户索取真实后端地址、测试账号或凭据。
+
+- 在迁移项目根目录创建独立的 `mock-server/`。它必须是可单独启动、可由局域网真机访问的模拟后端，不得嵌入 HarmonyOS 应用进程。
+- `mock-server/` 的接口路径、请求字段、响应结构、状态码和错误场景必须来自 Android 源码、接口定义或真实请求证据，不得由 AI 凭空设计；至少覆盖成功、空数据、业务失败和边界数据。
+- HarmonyOS 开发构建必须支持配置 Base URL，使模拟器和真机可以切换到 Mock Server；Mock Server 应监听可配置的局域网地址，而不是只监听 `localhost`。生产构建不得默认连接 Mock Server。
+- **Mock Server 是长驻进程，禁止以前台阻塞命令启动并等待它自然结束。**必须使用当前系统可靠的后台进程方式启动，记录本次启动的 PID、工作目录、监听地址以及独立的 stdout/stderr 日志；Windows 使用隐藏窗口的后台进程方式，不能弹出并占用交互终端。
+- 后台服务必须真正脱离 Agent 命令运行器，且不能继承调用终端的 stdin/stdout/stderr。统一调用 `droid2hmos service start mock-server <PROJECT> --health-url <URL> -- <command> [args...]`；Windows 由该工具通过 `Win32_Process.Create` 脱离运行器进程树。不得自行用 `Start-Process`、普通 `spawn` 或仅 `detached + unref` 代替。健康检查成功后，启动工具必须立即以退出码 0 返回。
+- 后台启动后只进行有明确超时的就绪检查：轮询健康接口或实际业务接口，成功后立即继续迁移；超时或进程提前退出时读取日志、停止本次启动的进程并报告失败。不得用无限等待、长时间 `sleep` 或等待 Server 进程退出作为就绪条件。
+- 启动前先检查预期地址是否已有正确服务，健康时复用，禁止重复拉起多个 Mock Server。迁移结束或不再需要时，只停止并核对本次迁移记录的 PID，不得按进程名批量终止其他服务。
+- 必须为 `mock-server/` 提供简短启动说明和一条可重复执行的启动命令，让用户无需修改源码即可手动拉起并用真机体验。
+- 后端功能通过后统一记录为 `mock-server-verified`。它可以证明迁移后的网络链路可工作，但不代表已经通过真实后端验收。
+- 应用内 Mock Repository 只可用于快速开发和离线演示，不能替代 Mock Server 或真实后端的网络端到端验证。
+
+## 可用命令
+
+统一入口是已通过 npm 安装并位于 `PATH` 中的 `droid2hmos` 命令，直接执行 `droid2hmos ...`。CLI 可用性自检已包含在主流程步骤 0 与步骤 1，此处不再重复。不得寻找或调用已经删除的插件内置脚本，也不得自行拼接内部 Node 入口。只有统一命令实际失败、缺少当前能力，或正在定位 CLI 自身缺陷时，才检查独立 `droid2hmos` 代码仓；此时必须说明统一命令、失败证据和采用调试入口的原因，问题解决后恢复全局命令。
+
+| 阶段 | 命令 | 作用与使用时机 |
+|---|---|---|
+| 准备 | `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 设备连接，设备异常排查时使用。 |
+| 分析 | `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`。 |
+| 规划 | `task plan [project]` | 从 `.migration/spec/` 的当前 Facts 分片、correction/review 与当前 Android 指纹生成 `.migration/tasks/` 派生计划；不得手工修改产物。步骤 5 使用。 |
+| 规划 | `task validate [project]` | 检查计划新鲜度、Launcher、行为闭包、Fact 主所有权和依赖 DAG；步骤 5/10 使用。 |
+| 规划 | `task next [project]` | 从已满足依赖的任务中给出确定性推荐和备选；无 Ready Task 时区分全部完成与阻塞。步骤 6 使用。 |
+| 规划 | `task show [project] <task-id>` | 按 Task ID 返回完整责任、核心 Facts、验收要求和分页源码位置索引（索引不是源码正文，源码必须实际读取）。步骤 6 使用。 |
+| 规划 | `task status [project]` | 只读查看任务运行态、覆盖率和阻塞原因；无计划时也返回可读空快照。步骤 9 使用。 |
+| 账本 | `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>]` | 采集单端截图/页面层级等对照证据；页面对照时使用。 |
+| 证据 | `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`。 |
+| 后端 | `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 使用。 |
+| 批次 | `checkpoint status [project]` | 查看检查点与工作区状态；恢复任务和复盘时使用。 |
+| 门禁 | `status [project]` | 只读推导当前阶段（含 Task Plan 状态）、事实新鲜度、完成缺口和允许动作；批次开始前、恢复、批次验收及最终验收前使用。 |
+| 门禁 | `complete [project]` | 最终完成硬门禁：Preflight/设备、当前 Android 分析、完整报告、当前 HarmonyOS 全量回归和全部声明证据同时成立；步骤 11 使用。 |
+| 设备 | `auth login [project]` | `devecocli-auth` 失效时的受管登录；`retry.kind=external`，不得并发二次登录；详见「设备签名与真机常亮」。 |
+| 复盘 | `logs <list\|show\|failures\|stats> [project]` | 查询受管执行记录与失败清单；步骤 12 复盘由 `reviewing-migration-process` 驱动使用。 |
+
+术语澄清：本表「规划」阶段的 Kernel Task Plan（`task *` 命令）是 Migration Kernel 协议的正式流程，与 AGENTS.md 中已废弃的旧 SPEC/PLAN/TASK 多 Agent 文档流程不是同一事物。不在本流程内、禁止或无需使用的命令：`sign` 由用户在 DevEco 中决策，agent 不得调用；`upgrade` 不使用，工具链更新走主流程步骤 0；`init`（工程壳创建已由 `preflight` 内置）当前流程无触发点，不使用。
+
+## 执行原则
+
+- Android 实际代码与运行行为高于脚本推断；facts 不全时必须主动补充发现。
+- 优先产出真实、可运行、可测试的 HarmonyOS 实现。不要把主要上下文和 token 消耗在报告润色、重复摘要或流程仪式上。
+- 报告通过不能证明页面一致、导航可达或业务正确。必须检查真实代码和可观察结果。
+- HarmonyOS 实现映射必须指向真正参与构建和运行的文件；文件中的实现还必须可从真实入口到达，未被引用的平行实现不算完成。
+- 编译、非白屏和截图存在都只是局部证据，不能替代控件级、交互级和业务级验证。
+- 每个用户可交互功能都必须关联实际执行通过的 Hypium 用例；只有经证据确认无法语义定位的元素可以使用其他自动化方式。设备端到端自测与证据要求统一按「设备验证标准」节执行。
+- 平台机制不同时使用 HarmonyOS 原生实现，但必须覆盖相同的用户能力和可观察结果；无法等价时记录明确差异并保持未完成或待确认状态。
+- 工作可以随时停止和恢复；恢复时以 `droid2hmos status` 对 Git HEAD、facts 哈希、源码指纹、报告和受管证据共同确认现场，不重新宣称已完成的内容。
+- 默认持续自动执行：完成即进入下一任务，禁止以“是否继续”等形式等待用户确认；允许暂停的唯一情形见「持续执行与人工介入边界」。
+- 经验不是完成条件：读取与记录的时机、条件见主流程 7「批次收尾」（唯一权威定义）。
+
+## 实现 epoch 与源码证据
+
+一个实现 epoch 是“报告 ref、source closure 与 Android 文件快照固定”的连贯实现批次：
+
+1. 先根据 Task、源码发现与调用链建立 source closure，并读取真实 Android 文件；facts、报告和测试只能确定范围与验收，不能提供文案、数值、颜色、分支、状态流转、错误路径或边界条件等行为细节。
+2. 首次修改 HarmonyOS 文件后 epoch 进入 `MUTATING`。同一 closure 和源码快照下可复用本轮声明；范围扩大、引入新 Android 文件、源码变化或恢复任务时必须开启新 epoch。
+3. `sourceProvenance` 必须覆盖本轮行为块的 Android 文件。CLI 会校验文件属于受管 Android 工程、hash 与当前内容一致，范围不越界且声明的符号位于该范围。
+4. D1 只允许 `passed` / `red-flag` / `unavailable`。只有受信任的宿主/运行器集成可以启用 JSONL 事件消费；项目内自行写入 `.migration/audit/source-events.jsonl` 不构成可信事件。事件必须按同一 `sessionId + epochId` 审计，其他 epoch 的 Read 不得证明当前 Write，Read 与首次 Write 位于同一并行动作组时属于 `red-flag`。当前宿主没有可信集成时必须保留 `unavailable`，不得伪装为通过。
+5. `report validate` 将 D1 结果写入 `.migration/audit/source-order-audit.json`，并将 D2 稳定抽样结果写入 `.migration/audit/literal-drift-audit.json`。D2 只提示语义漂移嫌疑，资源重命名、国际化和等价重构需人工复核。
+6. 当前没有宿主 Read/Edit/Write/Bash 拦截钩子；Kernel 只能在报告校验、checkpoint 和 complete 时机械检查声明、受管成员清单、hash 与可用事件。受管 checkpoint 会确认声明的 Android/HarmonyOS 文件内容已由 Git index 表示，再把包含完整成员清单、文件 hash、映射与审计摘要的 `.migration/audit/checkpoint-provenance.json` 强制写入同一 Git commit。任何状态和对外说明都不得声称已经实时阻止未读源码写入或机械证明读取—写入因果关系。
+
+## 禁止摘要替代源码
+
+- facts、迁移报告、Task Brief 和测试只用于确定范围与验收，禁止把其中的摘要当作行为细节来源。
+- 产出任何行为实现代码前，必须先定位并读取当前 epoch 对应的 Android 源文件；读与写放在同一并行动作组不算满足先读后写。
+- Android 源码及可用运行行为决定“做什么”；HarmonyOS/ArkUI/ArkTS 原生机制决定“怎么做”。不得机械复刻 Activity、Fragment、View、Intent、Handler 等 Android 平台结构。
+- 违反上述原则的代码即使能够编译、测试或通过报告覆盖，也仍判定为未完成。
+
+## 禁止的伪完成
+
+以下情况即使脚本或报告通过，也必须判定为未完成并继续修复：
+
+- **只有报告映射**：报告写着 `verified`，但映射文件中只有注释、空函数或未被调用的代码。必须让真实入口执行该实现并验证效果。
+- **代码存在但不可达**：创建了页面或组件文件，但没有被 Ability、页面注册、导航或真实控件引用。必须从应用真实入口能够到达。
+- **另加控件绕过原设计**：为了测试导航新增一个按钮，而 Android 原控件仍无响应。必须在 Android 对应控件上实现原交互，不得用额外控件替代。
+- **能编译就宣布成功**：HAP 编译、安装、启动且不白屏，但页面布局错误、Dialog 打不开或业务没有效果。必须逐项执行模拟器端到端用例。
+- **截图代替功能验证**：页面截图看起来存在，但控件无法点击、状态不变化或数据不保存。必须真实操作并检查可观察结果。
+- **只覆盖 facts**：报告覆盖所有静态 ref，但源码中还有脚本未发现的页面、入口或业务逻辑。必须主动审查源码并写入 `discoveries.json` 后实现。
+- **测试只写不跑**：存在测试文件或用例描述，但没有本次运行结果和证据。必须实际执行并记录通过证据。
+- **坐标点击冒充验收**：使用 `uitest uiInput click x y` 走通流程，但没有对应 Hypium 用例和本次执行结果。坐标只可用于探索控件，或处理经证据确认没有语义节点的 Canvas、系统界面等例外，不能替代正式端到端验收。
+- **无限推迟测试基建**：以“Hypium 尚未建立”为由连续完成功能并只做手工或坐标验证。第一个可交互功能完成前必须建立并跑通测试模块，否则该功能仍未完成。
+- **用桩隐藏缺口**：返回固定值、空实现、假数据或吞掉错误以通过测试或编译。桩只能保持未完成状态，不能标记 implemented/verified。
+- **把实现缺陷写成阻塞**：编译错误、遗漏回调、错误布局或未完成业务属于当前实现问题，必须修复，不能包装成外部 blocker。
+
+判断原则始终是：**用户在 HarmonyOS 应用中实际看到和操作到的结果是否与 Android 一致**，而不是文件、字段、状态或检查标记是否齐全。
+
+## 完成条件
+
+只有同时满足以下条件，才允许宣布迁移完成：
+
+- HarmonyOS 工程完整编译、安装、启动和运行成功；
+- 已建立可运行的 Hypium 测试模块，关键交互控件具有稳定语义 ID，所有可交互功能均有本次实际通过的语义化端到端用例；无法语义定位的例外具有明确证据和替代验证；
+- 全量端到端功能回归已按「设备验证标准」节在合格设备上从真实入口完成，并保留可检查证据；
+- Android 的所有页面、可见控件和状态均有真实且一致的 HarmonyOS 实现；
+- 所有导航、Dialog 打开/关闭、返回和结果流均可实际执行；
+- 所有业务功能、状态变化、数据效果和错误路径均已实现并验证；
+- 静态 facts 与 AI 补充发现均有真实实现映射和测试证据；
+- Task Plan 与当前 Facts、correction/review 和 Android 源码指纹一致，结构校验通过，全部 Task 均已取得新鲜的定向设备验证证据，且不存在 orphan Fact；
+- 最终报告完整性门禁通过，且人工需要审视的差异已明确呈现。
+- `droid2hmos complete <android-project>` 成功退出；任何手写完成标记或历史验证结果都不能替代该硬门禁。
+
+再次强调：完成报告不是完成迁移。只有真实 HarmonyOS 应用达到 Android 应用的完整功能与体验一致性，迁移才完成。