@harmonyos-arkts/droid2hmos 0.0.8 → 0.0.9

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 HarmonyOS-AI
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 HarmonyOS-AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,249 +1,249 @@
-# android-to-hmos-migration
-
-Android 应用迁移到 HarmonyOS 的报告驱动 AI 插件，支持 Claude Code 与 OpenCode。
-
-插件以 Android 源码、外部依赖和 AppGraph 确定性 facts 为防遗漏基线，由一个主 Agent 持续完成原生 HarmonyOS 实现、测试和端到端验证。迁移报告只记录 Android→HarmonyOS 映射与测试证据，不替代真实实现。
-
-## 主流程
-
-迁移工作区固定位于安卓工程父目录下的 `<工程名>-migration/.migration/`，由 CLI 自动创建；下文 `.migration/...` 均相对该工作区根目录。
-
-1. 检查 Android 技术栈、构建基线和设备环境。HarmonyOS HDC 设备是必需门禁；Android 运行环境依赖（SDK/adb/模拟器/Android 侧构建测试）已移除，相关检查固定为 `not_applicable`。
-2. 运行 AppGraph，生成只读 `.migration/spec/facts/` 与人工查看的 `spec.html`。
-3. 从 facts 初始化 `.migration/report/` 报告分片。
-4. 从 `.migration/spec/` 的 Facts 分片契约 `2.0.0` 与受管 correction/review 编译 `.migration/tasks/`，校验 Launcher、行为闭包、Fact 所有权和 Task DAG。
-5. AI 通过 `task next`/`task show` 取得一个完整行为责任，以 Android 源码和运行行为为权威持续实现 HarmonyOS 应用。
-6. 每完成一个可验证 Task，同步填写实现映射和测试证据，并创建 Git 检查点。
-7. 在 HarmonyOS 模拟器或真机上执行端到端功能验证。Android 运行时对照能力已移除，一致性基准为 Android 源码、静态 facts 与 `evidence compare` 对既有证据目录的比较；发现 facts 遗漏时写入报告 discoveries。
-8. 使用 Task Plan 与报告门禁检查已知 facts 覆盖；最终完成必须同时满足真实应用验收。
-
-## 保留结构
-
-```text
-android-to-hmos-migration/
-├── .claude-plugin/          # Claude Code 插件清单
-├── agents/                  # 报告驱动主 Agent
-├── opencode/agents.json     # OpenCode Agent 权限
-├── src/                     # OpenCode 插件入口、CLI 与命令实现（src/commands/）
-├── schemas/                 # facts、报告与 Preflight 契约
-├── skills/                  # Preflight、工程壳、报告、经验和流程复盘
-└── package.json
-```
-
-## 安装
-
-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：
-
-```bash
-npm run install:opencode -- /path/to/android-project
-# 或直接执行独立安装脚本：
-./scripts/install-opencode.sh /path/to/android-project
-```
-
-该安装脚本生成项目级 `.opencode/agent`、`.opencode/skill` 和一个同时承载 Plugin/CLI 的 `.opencode/plugin/android-to-hmos-migration.js`。不会再生成 `.opencode/android-to-hmos-migration` 运行时目录，无需修改全局配置。首次遇到同名非托管文件时会停止；确认覆盖可使用 `--force`。
-
-也可直接引用插件包：
-
-```json
-{
-  "plugin": ["D:/code/a2h/android-to-hmos-migration"]
-}
-```
-
-重启后选择 `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 preflight <android-project> [--sdk-path <path>] [--no-init-harmony]
-droid2hmos config init <android-project> [--harmony-project <path>]
-droid2hmos config validate <android-project>
-droid2hmos report init <android-project>
-droid2hmos report validate <android-project> [--require-complete]
-droid2hmos report <android-project> [--require-complete]
-droid2hmos report render <android-project>
-droid2hmos report update <android-project> --ref <ref> [--status <status>] [--harmony-file <path>] [--android-source <path>] [--evidence <path>] [--difference <text>]
-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 arkts] --class <class> [--case <case>] [--target <serial>] [--case-timeout-ms <ms>] [--ref <report-ref>...]
-droid2hmos test harmony <android-project> [--runner arkts] --all [--target <serial>] [--case-timeout-ms <ms>] [--ref <report-ref>...]
-droid2hmos test harmony <android-project> --runner python --hypium-project <path> --test-list <name>... [--target <serial>] [--python <path>] [--report-path <path>] [--ref <report-ref>...]
-droid2hmos checkpoint status <android-project>
-droid2hmos checkpoint create <android-project> --message <message> (--include <path>...|--all)
-droid2hmos device check harmony
-droid2hmos sign <android-project> [--target <serial>] [--force]
-droid2hmos evidence capture harmony <android-project> --name <name> [--target <id>]
-droid2hmos evidence compare <android-project> --name <name> --android <evidence-dir> --harmony <harmony-evidence-dir>
-droid2hmos evidence flow harmony <android-project> --name <name> [--class <class> [--case <case>]|--all]
-droid2hmos mock init <android-project> --spec <protocol-spec.json>
-droid2hmos upgrade
-droid2hmos service start <name> <android-project> [--health-url <url>] -- <command> [args...]
-droid2hmos service status <name> <android-project>
-droid2hmos service stop <name> <android-project>
-```
-
-- `init`：在 Android 工程的同级目录创建 `{Android应用名称}Ohos` HarmonyOS 工程，按本机 SDK 调整版本，完成受管 DevEco 登录和自动签名。
-- `status`：只读检查现场并推导 `phase`、`allowedActions`、证据新鲜度和 `completion.unmet`，不写入一份可漂移的状态机文件。
-- `complete`：最终硬门禁；只有 Preflight/设备、当前 Android 分析、完整报告、当前 HarmonyOS 全量回归和逐项受管证据都成立时返回成功。
-- `preflight`：读取 CLI 内置的全局 `config/preflight-checklist.json`，按其中启用的 Android 技术栈、Git、主机工具链、DevEco CLI 登录、AppGraph、配置、Android 构建/模拟器、HarmonyOS 工程/SDK/构建/设备门禁执行，并生成 `.migration/preflight-report.json`。硬门禁失败后停止后续阶段；修改 `enabled` 会影响该 CLI 处理的所有项目。
-- Preflight 的完整检查项、阻断规则和当前边界见 [`docs/preflight-checks.md`](docs/preflight-checks.md)。
-- `config`：初始化或校验 `.migration/config.json`（harmony-project 路径）。`androidBuild`/`androidTest` 字段仅为兼容旧工作区保留，不再有设置入口也不执行（Android 构建与测试能力已移除）。
-- `analyze android`：通过 AppGraph 对 Android 源码做纯静态分析，生成确定性 facts 和 `spec.html`，无需 APK；同时只读清点既有 APK（写入 `spec/android-apk-inventory.json`），仅作参考信息（Android 运行时对照能力已移除）。Android Gradle 依赖分析入口暂时关闭，受管 AppGraph 调用拒绝 `--resolve-dependencies`；源码分析不执行 Gradle。
-- `analyze harmony`：分析 HarmonyOS 工程，并自动读取 `config.json` 中经验证的 HarmonyOS SDK 路径。
-- `report init`：从 facts 初始化报告 `1.2.0`；存量 `1.1.0` 报告会原地升级并为条目补空 `sourceProvenance`，不伪造来源。
-- `report validate`：检查报告结构、facts 覆盖、Android 受管成员清单/hash/范围、Task source closure、D1 顺序审计与 D2 稳定抽样；项目内自行写入的事件文件不被信任，没有运行器可信集成时 D1 明确返回 `unavailable`，D2 只产生 warning。`--require-complete` 用于最终门禁。
-- `report`：缺少报告时先初始化，随后校验并生成 `.migration/report/report.html`；HTML 主体展示迁移结论、测试证据、差异和阻塞。
-- `task plan/validate`：确定性生成并校验 `.migration/tasks/`；计划基线绑定 Facts、correction/review 和 Android 指纹。任务按可观察行为聚合：Launcher 生命周期并入 Bootstrap，共享调用链的系统回调并入发起 Journey，同一决策范围的 unresolved 合并为一个 resolution。
-- `task status/next/show`：只读推导 Task 运行态、选择 Ready Frontier，并按需分页返回源码上下文；不写新的状态机文件。
-- `build harmony`：读取 DevEco JSON5 配置生成应用构建命令；Hvigor 命中增量缓存时允许复用不早于当前构建输入的非空 HAP，源码更新但产物过旧仍会失败。
-- `sign`：真机自动签名。检测目标设备（默认第一个可响应设备，可用 `--target` 指定），读取设备 UDID，在签名材料未覆盖该设备时自动执行 `devecocli signature generate --force` 重新生成（devecocli 会把当前连接的设备注册进调试 profile）；模拟器自动跳过。同时读取真机系统版本判据（`param get const.ohos.apiversion` 声称值与 `/system/etc/abc/framework/stateMgmt.abc` 文件头解析出的运行时字节码上限取较小值；log 版镜像 param 可能虚报），若有效 API 低于工程 `compatibleSdkVersion` 则自动下调兼容版本（`targetSdkVersion` 保持不变，产物 abc 字节码版本由 compatibleSdkVersion 决定），保证老系统真机可安装且可启动。覆盖情况记录在 `.migration/signature/devices.json`，材料未变化时不重复生成；`--force` 强制重签。
-- `test harmony`：支持 ArkTS 与 Python Hypium。多设备时优先真机，安装前自动检查签名和兼容版本；ArkTS 支持 `--case-timeout-ms` 和严格测试摘要校验，`--ref` 声明受管证据覆盖的报告项。Android 侧测试已移除。
-- `checkpoint`：检查 Git 基线并重新校验源码治理，或只提交显式 `--include` 的文件；`--all` 必须由调用者明确选择。声明的 Android 来源和 HarmonyOS 实现必须分别与所属 Git 仓库的 index 一致。默认同级 HarmonyOS 工程若尚未建仓，首次 checkpoint 会初始化独立仓库并继承 Android 仓库的提交身份；两个仓库按实际变更分别提交并返回各自 commit，不会移动或嵌套工程。`checkpoint-provenance.json` 写入兄弟迁移工作区的 `.migration/audit/`，记录完整成员清单、文件 hash、映射、所属仓库和本次 commit；不会在 Android 工程内创建 `.migration/`。提交前的暂存或一致性检查失败会回滚本次产生的暂存项。
-- `device` 与 `evidence`：检查 HarmonyOS 设备，采集截图、UI Tree 和有限设备日志，生成交互前后证据包，并对既有证据目录做截图身份/尺寸及 UI Tree 文本的确定性比较（Android 端采集已移除）。视觉一致性仍需图片审查。
-- `report update`：按 ref 更新状态、实现文件、Android 源码依据、测试证据和差异字段。`--android-source` 写入当前文件 SHA-256；`implemented` / `verified` 必须具备有效 `sourceProvenance`。
-- `mock init`：从有 Android 源码证据的协议 JSON 生成无第三方依赖的 Node.js Mock Server、四类场景和请求 transcript；不会凭空推断接口。
-- `upgrade`：通过 npm 将当前安装的 CLI 包全局升级到最新版本。
-- `service start/status/stop`：启动、检查或停止 Mock Server 等长驻服务，并记录 PID 和独立日志。
-
-### HarmonyOS Hypium 测试
-
-ArkTS/Hypium 用例位于 HarmonyOS 工程的 `ohosTest` target：
-
-```bash
-droid2hmos test harmony /path/to/android-project --runner arkts --class SettingsPageTest --case changeLanguage --target <serial>
-droid2hmos test harmony /path/to/android-project --runner arkts --all
-```
-
-Python Hypium 模式执行已经存在的 Python 测试工程，不自动生成测试代码。该工程需包含 `testcases/`，每个 `--test-list` 对应其中的 `<name>.json`；运行环境需先安装 Hypium：
-
-```bash
-python3 -m pip install hypium -U
-
-droid2hmos test harmony /path/to/android-project \
-  --runner python \
-  --hypium-project /path/to/hypium-project \
-  --test-list Login \
-  --test-list Settings \
-  --target <serial>
-```
-
-可重复传入 `--test-list`，也可用分号连接多个名称。`--python <path>` 指定 Python 解释器，`--report-path <path>` 指定报告目录；未指定时报告写入 Android 工程同级的 `<工程名>-migration/.migration/hypium-python-reports/`。
-
-### 命令执行日志
-
-公开迁移命令默认在 Android 工程的 `.migration/logs/` 记录结构化执行日志，无需增加参数。每天的摘要写入 `daily/YYYY-MM-DD.jsonl`，每次执行的完整记录写入 `runs/YYYY-MM-DD/<run-id>.json`，`index.json` 指向最近一次执行。密码、Token、Secret 和 API Key 参数会自动脱敏；日志写入失败不会改变原命令退出码。
-
-```text
-droid2hmos logs list <android-project> [YYYY-MM-DD]
-droid2hmos logs show <android-project> <run-id>
-droid2hmos logs failures <android-project>
-droid2hmos logs stats <android-project>
-```
-
-`help`、`internal`、`dev` 和日志查询本身不写执行日志，避免内部动作和查询行为污染迁移操作统计。
-
-### Migration Kernel
-
-CLI 的 Kernel Interface 是 `inspectMigration`、`guardMigrationAction` 和 `recordObservation`，公开命令对应 `status`、各动作的前置 guard，以及命令结果中的 `managedEvidence`。Kernel 每次从项目事实重新计算，不信任 AI 手工推进的阶段标记：
-
-- `phase` 只解释现场，`allowedActions` 提供多个安全能力，AI 仍决定实现批次和技术方案；
-- Android 或 HarmonyOS 源码变化会改变内容指纹，使旧分析或旧测试证据自动失效；
-- 失败收据提供 `retry.kind`、策略和最多自动重试次数；
-- `DROID2HMOS_GUARD_MODE=shadow` 可用于观察非最终动作，但 `complete` 始终不可降级；
-- HarmonyOS 测试收据记录目标设备、结构化测试结果与 `coveredRefs`；最终门禁逐 ref 校验覆盖关系；
-- 证据产物按 SHA-256 归档到 `.migration/evidence/blobs/`，后续日志覆盖或归档内容被篡改都会使收据失效。
-
-## Mock Server 协议输入
-
-`mock init` 要求每条路由都提供 `success`、`empty`、`business-failure` 和 `boundary`，并记录非空 `sourceEvidence`：
-
-```json
-{
-  "version": 1,
-  "routes": [
-    {
-      "method": "GET",
-      "path": "/notes",
-      "sourceEvidence": ["app/src/main/java/example/NotesApi.kt:18"],
-      "scenarios": {
-        "success": { "status": 200, "body": [{ "id": "1", "title": "示例" }] },
-        "empty": { "status": 200, "body": [] },
-        "business-failure": { "status": 403, "body": { "error": "denied" } },
-        "boundary": { "status": 200, "body": [{ "id": "max", "title": "边界数据" }] }
-      }
-    }
-  ]
-}
-```
-
-运行时通过请求头 `x-droid2hmos-scenario` 或查询参数 `scenario` 选择场景。
-
-## 核心产物
-
-迁移产物统一存放在安卓工程父目录下的独立工作区 `<AndroidProject>-migration/` 中，不再写入安卓工程内部。创建 `.migration/` 时会自动在工作区根目录生成 `.gitignore`（内容 `.migration/`），防止迁移产物被上层 Git 仓库提交到远端：
-
-```text
-<父目录>/AndroidProject-migration/
-├── .gitignore                # 忽略 .migration/，防止误提交
-└── .migration/
-    ├── preflight-report.json
-    ├── spec/
-    │   ├── index.json
-    │   ├── facts/
-    │   └── spec.html
-    ├── report/
-    │   ├── index.json
-    │   ├── pages/
-    │   ├── interactions/
-    │   ├── discoveries.json
-    │   ├── final-acceptance.json
-    │   ├── summary.json
-    │   ├── validation.json
-    │   └── report.html
-    ├── tasks/
-    │   ├── graph.json
-    │   ├── index.json
-    │   ├── briefs/*.md
-    │   └── acceptance/*.json
-    ├── evidence/
-    │   ├── index.json
-    │   ├── blobs/<sha256>/
-    │   └── managed/*.json
-    ├── audit/
-    │   ├── source-events.jsonl       # 仅供可信运行器导入；项目文件本身不构成可信证据
-    │   ├── android-source-manifest.json
-    │   ├── source-order-audit.json
-    │   └── literal-drift-audit.json
-    └── experience/lessons.md
-```
-
-受管 checkpoint 的 `.migration/audit/checkpoint-provenance.json` 与其他迁移产物一样保留在上述兄弟迁移工作区，不进入 Android 或 HarmonyOS Git 仓库；其中记录 Android/HarmonyOS 文件各自所属仓库及本次生成的 commit。默认同级 HarmonyOS 工程由独立 Git commit 保存。
-
-AppGraph 保持独立命令，由 npm 依赖提供并保证 `appgraph` 可从 PATH 执行。
-
-Windows 下的构建与测试同样通过有限命令运行器执行，禁止把 Gradle 管道到 `Select-Object`、`tail` 等会延迟退出的命令。长驻服务必须使用 `service start`，避免命令运行器等待后代进程而挂死。
-
-## 构建与校验
-
-```text
-npm run build
-npm run check
-npm test
-```
-
-报告通过只证明已知 facts 有记录，不证明迁移成功。最终标准始终是：HarmonyOS 应用中的所有页面、控件、导航、Dialog 和业务功能与 Android 的外部可观察行为一致，并通过真实设备端到端验证。
+# android-to-hmos-migration
+
+Android 应用迁移到 HarmonyOS 的报告驱动 AI 插件，支持 Claude Code 与 OpenCode。
+
+插件以 Android 源码、外部依赖和 AppGraph 确定性 facts 为防遗漏基线，由一个主 Agent 持续完成原生 HarmonyOS 实现、测试和端到端验证。迁移报告只记录 Android→HarmonyOS 映射与测试证据，不替代真实实现。
+
+## 主流程
+
+迁移工作区固定位于安卓工程父目录下的 `<工程名>-migration/.migration/`，由 CLI 自动创建；下文 `.migration/...` 均相对该工作区根目录。
+
+1. 检查 Android 技术栈、构建基线和设备环境。HarmonyOS HDC 设备是必需门禁；Android 运行环境依赖（SDK/adb/模拟器/Android 侧构建测试）已移除，相关检查固定为 `not_applicable`。
+2. 运行 AppGraph，生成只读 `.migration/spec/facts/` 与人工查看的 `spec.html`。
+3. 从 facts 初始化 `.migration/report/` 报告分片。
+4. 从 `.migration/spec/` 的 Facts 分片契约 `2.0.0` 与受管 correction/review 编译 `.migration/tasks/`，校验 Launcher、行为闭包、Fact 所有权和 Task DAG。
+5. AI 通过 `task next`/`task show` 取得一个完整行为责任，以 Android 源码和运行行为为权威持续实现 HarmonyOS 应用。
+6. 每完成一个可验证 Task，同步填写实现映射和测试证据，并创建 Git 检查点。
+7. 在 HarmonyOS 模拟器或真机上执行端到端功能验证。Android 运行时对照能力已移除，一致性基准为 Android 源码、静态 facts 与 `evidence compare` 对既有证据目录的比较；发现 facts 遗漏时写入报告 discoveries。
+8. 使用 Task Plan 与报告门禁检查已知 facts 覆盖；最终完成必须同时满足真实应用验收。
+
+## 保留结构
+
+```text
+android-to-hmos-migration/
+├── .claude-plugin/          # Claude Code 插件清单
+├── agents/                  # 报告驱动主 Agent
+├── opencode/agents.json     # OpenCode Agent 权限
+├── src/                     # OpenCode 插件入口、CLI 与命令实现（src/commands/）
+├── schemas/                 # facts、报告与 Preflight 契约
+├── skills/                  # Preflight、工程壳、报告、经验和流程复盘
+└── package.json
+```
+
+## 安装
+
+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：
+
+```bash
+npm run install:opencode -- /path/to/android-project
+# 或直接执行独立安装脚本：
+./scripts/install-opencode.sh /path/to/android-project
+```
+
+该安装脚本生成项目级 `.opencode/agent`、`.opencode/skill` 和一个同时承载 Plugin/CLI 的 `.opencode/plugin/android-to-hmos-migration.js`。不会再生成 `.opencode/android-to-hmos-migration` 运行时目录，无需修改全局配置。首次遇到同名非托管文件时会停止；确认覆盖可使用 `--force`。
+
+也可直接引用插件包：
+
+```json
+{
+  "plugin": ["D:/code/a2h/android-to-hmos-migration"]
+}
+```
+
+重启后选择 `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 preflight <android-project> [--sdk-path <path>] [--no-init-harmony]
+droid2hmos config init <android-project> [--harmony-project <path>]
+droid2hmos config validate <android-project>
+droid2hmos report init <android-project>
+droid2hmos report validate <android-project> [--require-complete]
+droid2hmos report <android-project> [--require-complete]
+droid2hmos report render <android-project>
+droid2hmos report update <android-project> --ref <ref> [--status <status>] [--harmony-file <path>] [--android-source <path>] [--evidence <path>] [--difference <text>]
+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 arkts] --class <class> [--case <case>] [--target <serial>] [--case-timeout-ms <ms>] [--ref <report-ref>...]
+droid2hmos test harmony <android-project> [--runner arkts] --all [--target <serial>] [--case-timeout-ms <ms>] [--ref <report-ref>...]
+droid2hmos test harmony <android-project> --runner python --hypium-project <path> --test-list <name>... [--target <serial>] [--python <path>] [--report-path <path>] [--ref <report-ref>...]
+droid2hmos checkpoint status <android-project>
+droid2hmos checkpoint create <android-project> --message <message> (--include <path>...|--all)
+droid2hmos device check harmony
+droid2hmos sign <android-project> [--target <serial>] [--force]
+droid2hmos evidence capture harmony <android-project> --name <name> [--target <id>]
+droid2hmos evidence compare <android-project> --name <name> --android <evidence-dir> --harmony <harmony-evidence-dir>
+droid2hmos evidence flow harmony <android-project> --name <name> [--class <class> [--case <case>]|--all]
+droid2hmos mock init <android-project> --spec <protocol-spec.json>
+droid2hmos upgrade
+droid2hmos service start <name> <android-project> [--health-url <url>] -- <command> [args...]
+droid2hmos service status <name> <android-project>
+droid2hmos service stop <name> <android-project>
+```
+
+- `init`：在 Android 工程的同级目录创建 `{Android应用名称}Ohos` HarmonyOS 工程，按本机 SDK 调整版本，完成受管 DevEco 登录和自动签名。
+- `status`：只读检查现场并推导 `phase`、`allowedActions`、证据新鲜度和 `completion.unmet`，不写入一份可漂移的状态机文件。
+- `complete`：最终硬门禁；只有 Preflight/设备、当前 Android 分析、完整报告、当前 HarmonyOS 全量回归和逐项受管证据都成立时返回成功。
+- `preflight`：读取 CLI 内置的全局 `config/preflight-checklist.json`，按其中启用的 Android 技术栈、Git、主机工具链、DevEco CLI 登录、AppGraph、配置、Android 构建/模拟器、HarmonyOS 工程/SDK/构建/设备门禁执行，并生成 `.migration/preflight-report.json`。硬门禁失败后停止后续阶段；修改 `enabled` 会影响该 CLI 处理的所有项目。
+- Preflight 的完整检查项、阻断规则和当前边界见 [`docs/preflight-checks.md`](docs/preflight-checks.md)。
+- `config`：初始化或校验 `.migration/config.json`（harmony-project 路径）。`androidBuild`/`androidTest` 字段仅为兼容旧工作区保留，不再有设置入口也不执行（Android 构建与测试能力已移除）。
+- `analyze android`：通过 AppGraph 对 Android 源码做纯静态分析，生成确定性 facts 和 `spec.html`，无需 APK；同时只读清点既有 APK（写入 `spec/android-apk-inventory.json`），仅作参考信息（Android 运行时对照能力已移除）。Android Gradle 依赖分析入口暂时关闭，受管 AppGraph 调用拒绝 `--resolve-dependencies`；源码分析不执行 Gradle。
+- `analyze harmony`：分析 HarmonyOS 工程，并自动读取 `config.json` 中经验证的 HarmonyOS SDK 路径。
+- `report init`：从 facts 初始化报告 `1.2.0`；存量 `1.1.0` 报告会原地升级并为条目补空 `sourceProvenance`，不伪造来源。
+- `report validate`：检查报告结构、facts 覆盖、Android 受管成员清单/hash/范围、Task source closure、D1 顺序审计与 D2 稳定抽样；项目内自行写入的事件文件不被信任，没有运行器可信集成时 D1 明确返回 `unavailable`，D2 只产生 warning。`--require-complete` 用于最终门禁。
+- `report`：缺少报告时先初始化，随后校验并生成 `.migration/report/report.html`；HTML 主体展示迁移结论、测试证据、差异和阻塞。
+- `task plan/validate`：确定性生成并校验 `.migration/tasks/`；计划基线绑定 Facts、correction/review 和 Android 指纹。任务按可观察行为聚合：Launcher 生命周期并入 Bootstrap，共享调用链的系统回调并入发起 Journey，同一决策范围的 unresolved 合并为一个 resolution。
+- `task status/next/show`：只读推导 Task 运行态、选择 Ready Frontier，并按需分页返回源码上下文；不写新的状态机文件。
+- `build harmony`：读取 DevEco JSON5 配置生成应用构建命令；Hvigor 命中增量缓存时允许复用不早于当前构建输入的非空 HAP，源码更新但产物过旧仍会失败。
+- `sign`：真机自动签名。检测目标设备（默认第一个可响应设备，可用 `--target` 指定），读取设备 UDID，在签名材料未覆盖该设备时自动执行 `devecocli signature generate --force` 重新生成（devecocli 会把当前连接的设备注册进调试 profile）；模拟器自动跳过。同时读取真机系统版本判据（`param get const.ohos.apiversion` 声称值与 `/system/etc/abc/framework/stateMgmt.abc` 文件头解析出的运行时字节码上限取较小值；log 版镜像 param 可能虚报），若有效 API 低于工程 `compatibleSdkVersion` 则自动下调兼容版本（`targetSdkVersion` 保持不变，产物 abc 字节码版本由 compatibleSdkVersion 决定），保证老系统真机可安装且可启动。覆盖情况记录在 `.migration/signature/devices.json`，材料未变化时不重复生成；`--force` 强制重签。
+- `test harmony`：支持 ArkTS 与 Python Hypium。多设备时优先真机，安装前自动检查签名和兼容版本；ArkTS 支持 `--case-timeout-ms` 和严格测试摘要校验，`--ref` 声明受管证据覆盖的报告项。Android 侧测试已移除。
+- `checkpoint`：检查 Git 基线并重新校验源码治理，或只提交显式 `--include` 的文件；`--all` 必须由调用者明确选择。声明的 Android 来源和 HarmonyOS 实现必须分别与所属 Git 仓库的 index 一致。默认同级 HarmonyOS 工程若尚未建仓，首次 checkpoint 会初始化独立仓库并继承 Android 仓库的提交身份；两个仓库按实际变更分别提交并返回各自 commit，不会移动或嵌套工程。`checkpoint-provenance.json` 写入兄弟迁移工作区的 `.migration/audit/`，记录完整成员清单、文件 hash、映射、所属仓库和本次 commit；不会在 Android 工程内创建 `.migration/`。提交前的暂存或一致性检查失败会回滚本次产生的暂存项。
+- `device` 与 `evidence`：检查 HarmonyOS 设备，采集截图、UI Tree 和有限设备日志，生成交互前后证据包，并对既有证据目录做截图身份/尺寸及 UI Tree 文本的确定性比较（Android 端采集已移除）。视觉一致性仍需图片审查。
+- `report update`：按 ref 更新状态、实现文件、Android 源码依据、测试证据和差异字段。`--android-source` 写入当前文件 SHA-256；`implemented` / `verified` 必须具备有效 `sourceProvenance`。
+- `mock init`：从有 Android 源码证据的协议 JSON 生成无第三方依赖的 Node.js Mock Server、四类场景和请求 transcript；不会凭空推断接口。
+- `upgrade`：通过 npm 将当前安装的 CLI 包全局升级到最新版本。
+- `service start/status/stop`：启动、检查或停止 Mock Server 等长驻服务，并记录 PID 和独立日志。
+
+### HarmonyOS Hypium 测试
+
+ArkTS/Hypium 用例位于 HarmonyOS 工程的 `ohosTest` target：
+
+```bash
+droid2hmos test harmony /path/to/android-project --runner arkts --class SettingsPageTest --case changeLanguage --target <serial>
+droid2hmos test harmony /path/to/android-project --runner arkts --all
+```
+
+Python Hypium 模式执行已经存在的 Python 测试工程，不自动生成测试代码。该工程需包含 `testcases/`，每个 `--test-list` 对应其中的 `<name>.json`；运行环境需先安装 Hypium：
+
+```bash
+python3 -m pip install hypium -U
+
+droid2hmos test harmony /path/to/android-project \
+  --runner python \
+  --hypium-project /path/to/hypium-project \
+  --test-list Login \
+  --test-list Settings \
+  --target <serial>
+```
+
+可重复传入 `--test-list`，也可用分号连接多个名称。`--python <path>` 指定 Python 解释器，`--report-path <path>` 指定报告目录；未指定时报告写入 Android 工程同级的 `<工程名>-migration/.migration/hypium-python-reports/`。
+
+### 命令执行日志
+
+公开迁移命令默认在 Android 工程的 `.migration/logs/` 记录结构化执行日志，无需增加参数。每天的摘要写入 `daily/YYYY-MM-DD.jsonl`，每次执行的完整记录写入 `runs/YYYY-MM-DD/<run-id>.json`，`index.json` 指向最近一次执行。密码、Token、Secret 和 API Key 参数会自动脱敏；日志写入失败不会改变原命令退出码。
+
+```text
+droid2hmos logs list <android-project> [YYYY-MM-DD]
+droid2hmos logs show <android-project> <run-id>
+droid2hmos logs failures <android-project>
+droid2hmos logs stats <android-project>
+```
+
+`help`、`internal`、`dev` 和日志查询本身不写执行日志，避免内部动作和查询行为污染迁移操作统计。
+
+### Migration Kernel
+
+CLI 的 Kernel Interface 是 `inspectMigration`、`guardMigrationAction` 和 `recordObservation`，公开命令对应 `status`、各动作的前置 guard，以及命令结果中的 `managedEvidence`。Kernel 每次从项目事实重新计算，不信任 AI 手工推进的阶段标记：
+
+- `phase` 只解释现场，`allowedActions` 提供多个安全能力，AI 仍决定实现批次和技术方案；
+- Android 或 HarmonyOS 源码变化会改变内容指纹，使旧分析或旧测试证据自动失效；
+- 失败收据提供 `retry.kind`、策略和最多自动重试次数；
+- `DROID2HMOS_GUARD_MODE=shadow` 可用于观察非最终动作，但 `complete` 始终不可降级；
+- HarmonyOS 测试收据记录目标设备、结构化测试结果与 `coveredRefs`；最终门禁逐 ref 校验覆盖关系；
+- 证据产物按 SHA-256 归档到 `.migration/evidence/blobs/`，后续日志覆盖或归档内容被篡改都会使收据失效。
+
+## Mock Server 协议输入
+
+`mock init` 要求每条路由都提供 `success`、`empty`、`business-failure` 和 `boundary`，并记录非空 `sourceEvidence`：
+
+```json
+{
+  "version": 1,
+  "routes": [
+    {
+      "method": "GET",
+      "path": "/notes",
+      "sourceEvidence": ["app/src/main/java/example/NotesApi.kt:18"],
+      "scenarios": {
+        "success": { "status": 200, "body": [{ "id": "1", "title": "示例" }] },
+        "empty": { "status": 200, "body": [] },
+        "business-failure": { "status": 403, "body": { "error": "denied" } },
+        "boundary": { "status": 200, "body": [{ "id": "max", "title": "边界数据" }] }
+      }
+    }
+  ]
+}
+```
+
+运行时通过请求头 `x-droid2hmos-scenario` 或查询参数 `scenario` 选择场景。
+
+## 核心产物
+
+迁移产物统一存放在安卓工程父目录下的独立工作区 `<AndroidProject>-migration/` 中，不再写入安卓工程内部。创建 `.migration/` 时会自动在工作区根目录生成 `.gitignore`（内容 `.migration/`），防止迁移产物被上层 Git 仓库提交到远端：
+
+```text
+<父目录>/AndroidProject-migration/
+├── .gitignore                # 忽略 .migration/，防止误提交
+└── .migration/
+    ├── preflight-report.json
+    ├── spec/
+    │   ├── index.json
+    │   ├── facts/
+    │   └── spec.html
+    ├── report/
+    │   ├── index.json
+    │   ├── pages/
+    │   ├── interactions/
+    │   ├── discoveries.json
+    │   ├── final-acceptance.json
+    │   ├── summary.json
+    │   ├── validation.json
+    │   └── report.html
+    ├── tasks/
+    │   ├── graph.json
+    │   ├── index.json
+    │   ├── briefs/*.md
+    │   └── acceptance/*.json
+    ├── evidence/
+    │   ├── index.json
+    │   ├── blobs/<sha256>/
+    │   └── managed/*.json
+    ├── audit/
+    │   ├── source-events.jsonl       # 仅供可信运行器导入；项目文件本身不构成可信证据
+    │   ├── android-source-manifest.json
+    │   ├── source-order-audit.json
+    │   └── literal-drift-audit.json
+    └── experience/lessons.md
+```
+
+受管 checkpoint 的 `.migration/audit/checkpoint-provenance.json` 与其他迁移产物一样保留在上述兄弟迁移工作区，不进入 Android 或 HarmonyOS Git 仓库；其中记录 Android/HarmonyOS 文件各自所属仓库及本次生成的 commit。默认同级 HarmonyOS 工程由独立 Git commit 保存。
+
+AppGraph 保持独立命令，由 npm 依赖提供并保证 `appgraph` 可从 PATH 执行。
+
+Windows 下的构建与测试同样通过有限命令运行器执行，禁止把 Gradle 管道到 `Select-Object`、`tail` 等会延迟退出的命令。长驻服务必须使用 `service start`，避免命令运行器等待后代进程而挂死。
+
+## 构建与校验
+
+```text
+npm run build
+npm run check
+npm test
+```
+
+报告通过只证明已知 facts 有记录，不证明迁移成功。最终标准始终是：HarmonyOS 应用中的所有页面、控件、导航、Dialog 和业务功能与 Android 的外部可观察行为一致，并通过真实设备端到端验证。