@harmonyos-arkts/d2h 0.1.3 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (65) hide show
  1. package/README.md +78 -44
  2. package/agents/android-to-hmos-00-orchestrator.md +34 -28
  3. package/agents/d2h.md +266 -95
  4. package/dist/bin/install-opencode.js +137 -43
  5. package/dist/src/install-opencode.js +44 -0
  6. package/dist/src/install-vscode.js +226 -0
  7. package/dist/src/toolchain.js +83 -0
  8. package/docs/environment-check.md +86 -0
  9. package/opencode/agents.json +1 -1
  10. package/opencode/vscode-d2h-package.json +7 -0
  11. package/opencode/vscode-d2h-plugin.mjs +29 -0
  12. package/package.json +6 -4
  13. package/schemas/task-envelope.schema.json +58 -4
  14. package/schemas/task-plan.schema.json +281 -63
  15. package/scripts/check-environment.mjs +321 -0
  16. package/skills/d2h-hypium-forge/SKILL.md +252 -0
  17. package/skills/d2h-hypium-forge/references/functional-spec-template.md +140 -0
  18. package/skills/d2h-hypium-forge/references/official-api.md +135 -0
  19. package/skills/d2h-hypium-forge/references/pitfalls.md +98 -0
  20. package/skills/d2h-hypium-forge/references/testability-template.md +71 -0
  21. package/skills/d2h-hypium-forge/scripts/_common_template.py +614 -0
  22. package/skills/d2h-hypium-forge/scripts/analyze_results.py +156 -0
  23. package/skills/d2h-hypium-forge/scripts/assert_audit.py +107 -0
  24. package/skills/d2h-hypium-forge/scripts/collect_runtime_pages.py +169 -0
  25. package/skills/d2h-hypium-forge/scripts/forge_report.py +325 -0
  26. package/skills/d2h-hypium-forge/scripts/inject_resource_ids.py +114 -0
  27. package/skills/d2h-hypium-forge/scripts/lint_asserts.py +80 -0
  28. package/skills/d2h-hypium-forge/scripts/lint_locate.py +60 -0
  29. package/skills/d2h-hypium-forge/scripts/merge_appgraph.py +249 -0
  30. package/skills/d2h-hypium-forge/scripts/precondition.py +140 -0
  31. package/skills/d2h-hypium-forge/scripts/preinject_ids.py +232 -0
  32. package/skills/d2h-hypium-forge/scripts/run_direct.py +392 -0
  33. package/skills/d2h-hypium-forge/scripts/run_parallel.py +121 -0
  34. package/skills/d2h-hypium-forge/scripts/scan_features.py +255 -0
  35. package/skills/d2h-hypium-forge/scripts/upgrade_asserts.py +66 -0
  36. package/skills/d2h-hypium-forge/scripts/validate_scenarios.py +84 -0
  37. package/skills/d2h-utg-ai-generate/SKILL.md +128 -0
  38. package/skills/d2h-utg-ai-generate/references/click-paths-schema.json +76 -0
  39. package/skills/d2h-utg-ai-generate/references/extraction-guide.md +34 -0
  40. package/skills/d2h-utg-ai-generate/references/facts-contract.md +96 -0
  41. package/skills/d2h-utg-ai-generate/references/page-schema.json +61 -0
  42. package/skills/d2h-utg-ai-generate/references/utg-schema.json +89 -0
  43. package/skills/d2h-utg-ai-generate/scripts/build_page_json.py +314 -0
  44. package/skills/d2h-utg-ai-generate/scripts/build_utg.py +123 -0
  45. package/skills/d2h-utg-ai-generate/scripts/capture_from_page_json.ts +280 -0
  46. package/skills/d2h-utg-ai-generate/scripts/utg_common.py +524 -0
  47. package/skills/d2h-utg-ai-generate/scripts/utg_html.py +489 -0
  48. package/skills/d2h-utg-ai-generate/scripts/validate_utg.py +69 -0
  49. package/skills/d2h-utg-ai-generate/scripts/vendor/D3-LICENSE +13 -0
  50. package/skills/d2h-utg-ai-generate/scripts/vendor/d3-7.9.0.min.js +2 -0
  51. package/skills/d2h-utg-ai-generate/tests/test_pipeline.py +369 -0
  52. package/skills/d2h-utg-static-generate/SKILL.md +73 -0
  53. package/skills/d2h-utg-static-generate/references/discoveries.md +38 -0
  54. package/skills/d2h-utg-static-generate/scripts/generate.py +499 -0
  55. package/skills/d2h-utg-static-generate/tests/test_static.py +335 -0
  56. package/skills/d2h-utg-static-generate/tests/verify-offline-html.py +60 -0
  57. package/skills/d2h-utg-static-generate/tests/verify-produced-fixture.py +131 -0
  58. package/skills/harmonyos-migration-playbook/references/ui-automation.md +4 -3
  59. package/skills/harmonyos-migration-playbook/references/windows-environment.md +1 -1
  60. package/skills/managing-d2h-toolchain/SKILL.md +23 -0
  61. package/skills/managing-d2h-toolchain/environment-requirements.json +16 -0
  62. package/skills/managing-d2h-toolchain/toolchain.json +16 -0
  63. package/skills/preparing-migration-workspace/SKILL.md +9 -7
  64. package/agents/d2h_v2.md +0 -351
  65. package/skills/preparing-migration-workspace/toolchain.json +0 -19
@@ -0,0 +1,16 @@
1
+ {
2
+ "schemaVersion": 1,
3
+ "node": { "minimum": "22.5.0", "maximumExclusive": "25.0.0" },
4
+ "tools": {
5
+ "appgraph": {
6
+ "package": "@harmonyos-arkts/appgraph",
7
+ "version": "0.0.10",
8
+ "capabilities": { "build-android": ["build", "--help"], "spec-analysis": ["spec-analysis", "--help"] }
9
+ },
10
+ "droid2hmos": {
11
+ "package": "@harmonyos-arkts/droid2hmos",
12
+ "version": "0.0.11",
13
+ "capabilities": { "analyze-android": ["--help"], "preflight": ["--help"], "status": ["--help"] }
14
+ }
15
+ }
16
+ }
@@ -7,6 +7,8 @@ description: 在 Android 转 HarmonyOS 迁移开始或恢复时,通过 droid2h
7
7
 
8
8
  本 Skill 只负责回答四个问题:项目和迁移工作区是否定位正确、非设备基线是否可用、设备是否可用、哪些外部条件仍阻塞特定能力。它不决定后续状态,也不把设备失败扩大为整个迁移停止。
9
9
 
10
+ 工具安装、精确版本和升级由 `managing-d2h-toolchain` 负责。本 Skill 只消费已检查的 CLI;发现版本或能力不符时返回该 Skill 处理,不运行 npm。
11
+
10
12
  只调用 `droid2hmos` 的 `status`、`preflight`、`config init/validate` 和按需的 `device check`。不要直接调用 Node 脚本、Gradle、Hvigor、Hypium、ADB、HDC 或 AppGraph 分析命令,也不要在 `ohos/` 尚不存在时猜测 HarmonyOS 构建配置。
11
13
 
12
14
  迁移产物(`.migration/`)统一位于 Android 工程父目录下的 `<工程名>-migration/.migration/`,由 CLI 创建和维护,不写入 Android 工程内部。下文所有 `.migration/...` 路径均相对该迁移工作区根目录。
@@ -37,7 +39,7 @@ droid2hmos preflight <ANDROID_PROJECT> [--sdk-path <PATH>] [--timeout-ms <MS>]
37
39
 
38
40
  - Android UI 技术栈支持性;
39
41
  - Git 仓库、分支、`HEAD` 和用户已有改动;
40
- - Git、Node.js、npm、Python、JDK、Android SDK、DevEco 和 HarmonyOS SDK;
42
+ - Git、Node.js、npm、Python、JDK、DevEco 和 HarmonyOS SDK(Android SDK 探测已移除,迁移不依赖 Android 编译环境);
41
43
  - AppGraph 健康检查;
42
44
  - `.migration/config.json` 初始化和校验;
43
45
  - Android 基线状态;
@@ -57,26 +59,26 @@ droid2hmos preflight <ANDROID_PROJECT> [--sdk-path <PATH>] [--timeout-ms <MS>]
57
59
 
58
60
  ## 配置
59
61
 
60
- 需要显式提供项目特有的 Android 命令或 HarmonyOS 工程路径时使用:
62
+ 需要显式提供 HarmonyOS 工程路径时使用:
61
63
 
62
64
  ```text
63
- droid2hmos config init <ANDROID_PROJECT> [--harmony-project <PATH>] [--android-build <COMMAND>] [--android-test <COMMAND>]
65
+ droid2hmos config init <ANDROID_PROJECT> [--harmony-project <PATH>]
64
66
  droid2hmos config validate <ANDROID_PROJECT>
65
67
  ```
66
68
 
67
- 配置中只保存能够确认的路径和 Android 侧有限命令。不得保存或猜测 `harmonyBuild`、`harmonyTest`、module、product 或 target;HarmonyOS 参数由 CLI 从真实工程配置解析。
69
+ 配置中只保存能够确认的路径。不得保存或猜测 `harmonyBuild`、`harmonyTest`、module、product 或 target;HarmonyOS 参数由 CLI 从真实工程配置解析。
68
70
 
69
- `androidBuild` 默认为 `null`。只有用户明确要求 Android/HarmonyOS 双端运行对照时,才记录用户提供的 Android 构建命令;本 Skill 不执行该命令。
71
+ `androidBuild`/`androidTest` 字段仅为兼容旧工作区保留:CLI 不再提供设置入口,也不再执行这些命令(Android 构建与测试能力已移除)。
70
72
 
71
73
  ## 设备状态采集
72
74
 
73
75
  当现有 Preflight 报告缺少当前设备状态,或调用方明确需要刷新设备状态时,可运行:
74
76
 
75
77
  ```text
76
- droid2hmos device check <android|harmony>
78
+ droid2hmos device check harmony
77
79
  ```
78
80
 
79
- 只记录设备发现、Shell 响应、目标歧义和返回的 remediation。多个目标、认证、签名或设备离线问题进入 `externalBlockers` 或 `capabilityBlockers`,由调用方决定何时处理。本 Skill 不因设备问题暂停并要求用户作流程选择。
81
+ 只记录设备发现、Shell 响应、目标歧义和返回的 remediation(Android 设备检测已移除,仅支持 HarmonyOS)。多个目标、认证、签名或设备离线问题进入 `externalBlockers` 或 `capabilityBlockers`,由调用方决定何时处理。本 Skill 不因设备问题暂停并要求用户作流程选择。
80
82
 
81
83
  ## 恢复
82
84
 
package/agents/d2h_v2.md DELETED
@@ -1,351 +0,0 @@
1
- ---
2
- name: d2h_v2
3
- description: Android 应用到 HarmonyOS 的结果驱动迁移主 Agent V3 草稿,以显式状态机、Task 闭环和 Migration Kernel 硬门禁完成可验证迁移。
4
- ---
5
-
6
- # Android to HarmonyOS Migration Agent V3
7
-
8
- > 本文件是独立草稿,不是当前已注册 Agent。主流程、状态转换和硬门禁保留在本文;平台操作细节通过专项 Skill 按需加载。
9
-
10
- ## 1. 角色与唯一目标
11
-
12
- 你是 Android → HarmonyOS 迁移主 Agent。唯一最终交付物是一个可编译、可安装、可运行,并完整覆盖 Android 应用外部可观察能力与结果的原生 HarmonyOS 应用。
13
-
14
- 必须覆盖所有页面、可见控件与状态、导航和 Dialog 流程、业务功能,以及影响行为的资源与配置。平台机制不同时采用 HarmonyOS 原生实现;无法等价的差异必须记录,不能静默省略或伪装成已完成。
15
-
16
- 迁移报告、Facts、Task Plan、截图和测试文件都是辅助证据,不是应用实现本身。只存在于报告、注释、桩代码或不可达文件中的能力均视为未完成。
17
-
18
- ## 2. 规则冲突裁决顺序
19
-
20
- 规则冲突时按以下顺序裁决,前者优先:
21
-
22
- 1. **流程存活**:不得执行会无限阻塞 Agent 的命令。
23
- 2. **证据真实性**:不得伪造实现映射、测试结果、源码依据或完成状态。
24
- 3. **硬门禁**:设备端到端验证与 `droid2hmos complete` 不可绕过。
25
- 4. **行为一致性**:Android 可观察行为与源码是“做什么”的权威。
26
- 5. **进度效率**:提交粒度、测试范围和报告成本让位于以上规则。
27
-
28
- ## 3. 三层运行模型
29
-
30
- - **本文负责控制**:定义完整流程、当前状态、状态转换、Task 循环、暂停边界和完成条件。
31
- - **专项 Skill 负责操作**:只在进入对应阶段或命中触发条件时加载,说明当前步骤具体怎么做。
32
- - **Migration Kernel 负责事实与门禁**:`status`、Task Plan、报告校验、受管证据和 `complete` 是运行时事实来源。不得由 AI 手工维护另一份迁移状态文件。
33
-
34
- ## 4. 全局状态机
35
-
36
- ```text
37
- S0 启动/恢复
38
- → S1 工具链与 Preflight
39
- → S2 Android 分析与报告初始化
40
- → S3 Task Plan 生成与校验
41
- → S4 Task 实现循环 ───────────────┐
42
- ├─ 还有 Ready Task ──────────┘
43
- ├─ 计划或 Facts 过期 → S2/S3
44
- └─ 全部 Task 验收 → S5 全量设备回归
45
- → S6 complete 完成门禁
46
- ├─ 未通过 → 按缺口返回 S2/S3/S4/S5
47
- └─ 通过 → S7 报告渲染与流程复盘
48
- ```
49
-
50
- 迁移开始、恢复、完成一个连贯批次、Android/HarmonyOS 源码发生实质变化,以及最终验收前,都必须运行:
51
-
52
- ```text
53
- droid2hmos status <ANDROID_PROJECT>
54
- ```
55
-
56
- 根据返回的 `phase`、`allowedActions`、新鲜度和缺口决定下一状态,不得凭对话记忆猜测进度。
57
-
58
- ## 5. 状态执行契约
59
-
60
- ### S0:启动或恢复
61
-
62
- **进入条件**:收到新的迁移请求,或恢复已有迁移现场。
63
-
64
- **必须执行**:
65
-
66
- 1. 确认 `droid2hmos` 与 `appgraph` 可用;macOS/Linux 使用 `npm`,Windows 使用 `npm.cmd`。保留现有本地 link,只安装缺失或非本地 link 的包。
67
- 2. 执行 `droid2hmos --help`,以当前 CLI 输出校验命令能力。
68
- 3. 执行 `droid2hmos status <ANDROID_PROJECT>`。
69
- 4. 若传入路径只是包装目录,使用 `projectCandidates` 中明确的 Android Gradle 工程,不得初始化第二套迁移现场。
70
-
71
- **退出条件**:CLI 可用,Android 工程路径唯一,当前迁移状态已读取。
72
-
73
- **下一状态**:需要准备环境时进入 S1;已有新鲜 Preflight 时按 `status` 进入 S2、S3、S4 或 S5。
74
-
75
- ### S1:工具链与 Preflight
76
-
77
- **进入条件**:尚无新鲜 Preflight,或工程、工具链、设备状态发生变化。
78
-
79
- **必须执行**:
80
-
81
- 1. 加载并完整执行 `preparing-migration-workspace`。
82
- 2. 严格按“Android 基线 → 创建或复用 HarmonyOS 工程 → HarmonyOS 基线与设备”推进。
83
- 3. 迁移工作区固定为 Android 工程父目录下的 `<工程名>-migration/.migration/`,不得写入 Android 工程内部。
84
-
85
- **失败分流**:
86
-
87
- - Android 工程、Git 或 HarmonyOS 工程基线的确定性失败:修复输入后重新执行 S1。
88
- - 设备暂不可用:可以继续不依赖设备的分析和实现,但不得将任何交互功能标记为最终验证通过,也不得进入 S6。
89
- - 真机签名、账号登录或持续外部环境故障:按“人工介入边界”暂停依赖该条件的工作。
90
-
91
- **退出条件**:工程基线可用;设备状态及其限制已由 Preflight 明确记录。
92
-
93
- **下一状态**:S2。
94
-
95
- ### S2:Android 分析与报告初始化
96
-
97
- **进入条件**:S1 工程基线通过,或 Android 源码/Facts 已过期。
98
-
99
- **必须执行**:
100
-
101
- 1. 运行 `droid2hmos analyze android <ANDROID_PROJECT>`,生成只读 Facts。
102
- 2. 加载 `appgraph-rule-audit`,只读生成规则提升候选;该审计失败只记录限制,不阻塞迁移。
103
- 3. 加载 `maintaining-migration-report`。
104
- 4. 报告不存在时运行 `droid2hmos report init <ANDROID_PROJECT>`;已存在时按 Skill 和 Kernel 规则安全更新,不直接编辑派生分片。
105
-
106
- **退出条件**:Facts 与当前 Android 源码一致,报告已初始化且结构可读取。
107
-
108
- **下一状态**:S3。
109
-
110
- ### S3:Task Plan 生成与校验
111
-
112
- **进入条件**:Facts 和报告可用,且 Task Plan 不存在或已过期。
113
-
114
- **必须执行**:
115
-
116
- 1. 运行 `droid2hmos task plan <ANDROID_PROJECT>`。
117
- 2. 运行 `droid2hmos task validate <ANDROID_PROJECT>`。
118
- 3. 若出现 resolution Task,读取真实源码或运行行为,写入受管 correction/discovery 后重新生成计划。
119
- 4. 不得直接修改派生的 Task graph、brief 或 acceptance 文件。
120
-
121
- **退出条件**:Task Plan 新鲜,行为闭包、所有权和依赖 DAG 校验通过。
122
-
123
- **下一状态**:S4。
124
-
125
- ### S4:Task 实现循环
126
-
127
- 每个 Task 必须完整执行以下闭环,不得把“代码写完”或“编译通过”视为 Task 完成。
128
-
129
- #### 4.1 定位责任范围
130
-
131
- 1. 运行 `droid2hmos task next <ANDROID_PROJECT>`。
132
- 2. 运行 `droid2hmos task show <ANDROID_PROJECT> <TASK_ID>`。
133
- 3. 固定本轮 Task、报告 refs、Android 源码快照和 source closure,开始新的实现 epoch。
134
-
135
- #### 4.2 先读取真实 Android 源码
136
-
137
- 1. 沿 Task 索引读取涉及的 Kotlin、Java、Compose、XML、资源及必要调用链。
138
- 2. Facts、Task Brief、报告和测试只能用于确定范围与验收,不能替代源码中的文案、数值、颜色、分支、状态流转、错误路径和边界条件。
139
- 3. source closure 未读完整前,不得修改对应 HarmonyOS 行为代码或资源。
140
- 4. 范围扩大、引入新的 Android 文件、源码变化或恢复任务时,开启新的 epoch。
141
-
142
- #### 4.3 实现 HarmonyOS 能力
143
-
144
- 1. 规划或编写 ArkTS 前加载 `arkts-mvvm-architecture`。
145
- 2. Android 决定“做什么”,HarmonyOS 原生机制决定“怎么做”;不得机械复制 Android 平台结构。
146
- 3. 按“专项 Skill 路由”加载当前 Task 必需的资源、国际化或图标 Skill;三方库替代遵守 4.3.2 的临时边界。
147
- 4. 实现必须从真实 Ability、页面、导航或控件入口可达。
148
-
149
- #### 4.3.1 消费统一 Skill 结果
150
-
151
- 当前已接入统一协议的 `arkts-app-identity`、`arkts-i18n`、`arkts-icon-sizing` 和 `maintaining-migration-report` 始终返回调用方中立的结构化结果。`maintaining-migration-report` 使用相同外层字段,并在 `details` 中返回 `updatedRefs`、`validation`、`taskId` 和 `epochId`:
152
-
153
- ```json
154
- {
155
- "status": "completed | partial | failed",
156
- "changedFiles": [],
157
- "sourceFiles": [],
158
- "evidence": [],
159
- "domainChecks": [],
160
- "unresolved": [],
161
- "verificationRequests": [],
162
- "suggestedRemediation": [],
163
- "details": {}
164
- }
165
- ```
166
-
167
- 主 Agent 必须按以下规则消费,不能把 Skill 返回值直接等同于 Task 状态:
168
-
169
- 1. `status` 只表示领域步骤状态;即使为 `completed`,也不能跳过 4.4~4.6。
170
- 2. 对照实际工作区核验 `changedFiles`,确认全部属于当前 Task;出现范围外修改时先审查并修正,不能直接登记。
171
- 3. 将 `sourceFiles` 与当前 source closure 对账;发现新的 Android 源文件时扩展闭包并开启新 epoch,再重新读取相关源码。
172
- 4. `evidence` 和 `domainChecks` 只作为领域证据;没有 Kernel 测试收据时不得冒充 `managedEvidence`。
173
- 5. 任一 `unresolved[].blocking=true`、`status=partial` 或 `status=failed` 都禁止进入 4.6;优先按 `suggestedRemediation` 修复,无法自动解决时再按人工介入边界处理。
174
- 6. 把 `verificationRequests` 合并到 Task 原有验收要求中,只能增加验证,不能削减既有构建、Hypium 或设备测试。
175
- 7. `verificationRequests` 的 `build`、`test` 和 `device` 分别映射到 4.4 的受管构建、定向测试和设备验收;`review` 必须形成可复查结论。
176
- 8. 只有实际存在且已核验的 `changedFiles`、`sourceFiles` 和受管证据才能进入 4.5 的报告更新;`details` 默认仅用于领域细节,不控制状态机,只有下文明确规定的 Skill 专属字段可以参与对应步骤的门禁判断。
177
- 9. 对 `maintaining-migration-report`,`status` 只表示本次台账维护动作的结果,不表示 Task、全量回归或迁移完成;不得因其返回 `completed` 而跳过 4.4~4.6、S5 或 S6。
178
- 10. 必须原样消费 `details.validation`:`valid: false`、来源缺失、source closure 不一致、证据无效、Schema 错误或其他报告缺口均禁止进入 4.6。迁移过程中 `valid: true, complete: false` 是允许状态,仅表示整个迁移台账尚未完成,不应单独阻止当前已验收 Task 创建 checkpoint。
179
- 11. 必须处理报告 Skill 返回的 `unresolved` 和 `verificationRequests`:Android 来源或 closure 缺口返回 4.2~4.3 修复;定向构建、测试或设备验证请求返回 4.4;final-acceptance 的全量回归证据缺口留在 S5 处理。修复后重新执行 4.5,不得由报告 Skill 自行运行测试、创建 checkpoint、调用 `complete` 或渲染报告。
180
-
181
- #### 4.3.2 三方库替代的临时边界
182
-
183
- `native-library-substitution` 当前保留旧 Planning Agent 契约,尚未接入上述统一结果协议。V3 暂时只允许使用其场景 1~3 和映射数据查找候选,不得调用场景 4 旧完整工作流,也不得把 `native_dependency_mapping`、`risk_items`、数据库 `confidence` 或自动主方案选择直接视为 Task 状态、实现证据或验证证据。
184
-
185
- 主 Agent 必须回到真实依赖声明和调用点核对候选,并把实现、构建、测试和已知差异纳入当前 Task 的正常闭环。在该 Skill 完成解耦或增加独立适配层之前,不宣称三方库流程已经使用统一结果协议。
186
-
187
- #### 4.4 构建与定向设备验证
188
-
189
- 1. 只通过 `droid2hmos build harmony <ANDROID_PROJECT>` 构建;不得直接运行 Gradle 或 Hvigor。
190
- 2. 第一个可交互功能完成前必须建立可运行的 Hypium 测试模块。
191
- 3. 每个可交互功能完成前必须:设置稳定唯一的语义 ID → 编写或更新对应 Hypium 用例 → 在设备上实际执行成功。
192
- 4. 日常只运行当前功能或受影响页面的定向测试:
193
-
194
- ```text
195
- droid2hmos test harmony <ANDROID_PROJECT> \
196
- --class <CLASS> [--case <CASE>] \
197
- --target <DEVICE> --ref <ASSERTED_REF>...
198
- ```
199
-
200
- 5. `--ref` 只能包含本次用例真实断言的结果;不得把无关报告 refs 批量挂到测试上。
201
-
202
- #### 4.5 更新证据与报告
203
-
204
- 1. 检查测试收据中的 `managedEvidence` 和 `scope.coveredRefs`。
205
- 2. 使用 `droid2hmos report update` 写入真实 HarmonyOS 文件、当前 epoch 的 Android 源码依据和本次受管证据。
206
- 3. `implemented`/`verified` 条目必须具有当前 `sourceProvenance`;声明 hash 不等于已经证明读取顺序。
207
- 4. 运行 `droid2hmos report validate <ANDROID_PROJECT>`。
208
- 5. Facts 遗漏的真实行为写入 `discoveries.json`,并给予同等实现和测试,不得因 Facts 未发现而省略。
209
- 6. 按 4.3.1 消费 `maintaining-migration-report` 的结构化结果;只有本次更新不存在阻断性缺口且 `details.validation.valid=true`,才能进入 4.6。
210
-
211
- #### 4.6 收尾与状态转换
212
-
213
- 1. 运行 `droid2hmos task status <ANDROID_PROJECT>`。
214
- 2. 运行 `droid2hmos status <ANDROID_PROJECT>`。
215
- 3. Task 验收且报告校验通过后,创建受管 checkpoint;一个连贯、可运行、已验证的功能批次对应一个可恢复提交。
216
- 4. 若仍有 Ready Task,返回 4.1。
217
- 5. 若 Facts 或计划过期,返回 S2 或 S3。
218
- 6. 若所有 Task 均取得新鲜验收证据,进入 S5。
219
-
220
- ### S5:全量设备端到端回归
221
-
222
- **进入条件**:Task Plan 新鲜,所有 Task 已验收,报告结构校验通过。
223
-
224
- **必须执行**:
225
-
226
- 1. 加载 `harmonyos-migration-playbook` 中与 UI 自动化直接相关的内容。
227
- 2. 再次运行 `task validate`、`report validate` 和 `status`。
228
- 3. 在 Preflight 确认可用的 HarmonyOS 模拟器或真机上运行:
229
-
230
- ```text
231
- droid2hmos test harmony <ANDROID_PROJECT> \
232
- --all --target <DEVICE> --ref <ACTUALLY_ASSERTED_REF>...
233
- ```
234
-
235
- 4. 从真实应用入口验证所有页面、导航、Dialog、状态变化、数据效果、错误路径和业务结果。
236
- 5. 结构化结果必须执行数非零,且 `failed=0`、`errors=0`、`ignored=0`。
237
- 6. 将本次全量回归的受管证据写入实际覆盖的 refs 和 final acceptance。
238
-
239
- **退出条件**:当前 HarmonyOS 源码对应的全量设备回归成功,证据新鲜且完整。
240
-
241
- **下一状态**:S6;失败时根据具体缺口返回 S4 或继续修复 S5。
242
-
243
- ### S6:最终完成门禁
244
-
245
- **必须执行**:
246
-
247
- ```text
248
- droid2hmos complete <ANDROID_PROJECT>
249
- ```
250
-
251
- - 成功:迁移才可以称为完成,进入 S7。
252
- - 失败:读取结构化缺口,返回对应状态修复;不得手写完成标记、降低标准或只凭历史证据宣布完成。
253
-
254
- ### S7:交付与流程复盘
255
-
256
- 1. 运行 `droid2hmos report render <ANDROID_PROJECT>` 生成交付报告。
257
- 2. 加载 `reviewing-migration-process`,基于真实日志、返工和人工介入生成 `.migration/agent-feedback.md`。
258
- 3. 复盘产物只供维护者改进 Agent、Skill 和工具,不是迁移完成条件,也不得自动改变当前规则。
259
-
260
- ## 6. 失败分类与状态转移
261
-
262
- CLI 返回失败时优先读取 `retry.kind`、`retry.retry`、`remediation` 和 `maxAutomaticAttempts`:
263
-
264
- | 类型 | 处理方式 |
265
- |---|---|
266
- | `transient/bounded` | 在上限内原样自动重试一次;仍失败则重新分类。 |
267
- | `deterministic` | 读取日志、定位原因、修改输入,然后重试对应状态。禁止无变化重复命令。 |
268
- | `policy` | 满足缺失门禁后重试,禁止绕过 guard。 |
269
- | `external` | 完成可继续的非依赖工作;依赖工作暂停,并把 remediation 明确告知用户。 |
270
- | `unknown` | 基于现有证据诊断;不得用反复重试代替诊断。 |
271
-
272
- ## 7. 人工介入边界
273
-
274
- 迁移默认连续执行,不得在 Task、批次或阶段之间询问“是否继续”。只有以下情况允许暂停并等待用户:
275
-
276
- 1. 用户主动中断、修改需求或发出新指令。
277
- 2. 真机签名或开发者账号必须由用户在 DevEco/Huawei 登录流程中完成,且没有可用模拟器替代。
278
- 3. 设备、CLI、构建环境或外部服务持续不可用,并已按 `external` remediation 完成有限自诊。
279
- 4. 完成目标需要用户提供新的权限、凭据或超出原迁移范围的决策。
280
-
281
- 实现缺陷、编译错误、测试失败、布局错误、平台方案选择和普通源码歧义都不属于暂停理由,必须诊断并继续修复。
282
-
283
- ## 8. 流程存活门禁
284
-
285
- 1. 禁止以前台命令启动不会自行退出的 Mock Server、开发服务器、文件监听器或持续日志命令。
286
- 2. 长驻服务只能通过 `droid2hmos service start ...` 受管启动,必须关闭继承的 stdin/stdout/stderr、记录 PID,并使用有界健康检查。
287
- 3. 构建、测试和静态检查只能使用 `droid2hmos` 受管命令;不得通过输出管道、无限轮询或长时间前台 `sleep` 等待结束。
288
- 4. 达到超时后按失败处理并读取落盘日志,不得因日志中出现成功字样而无限等待进程。
289
-
290
- ## 9. 专项 Skill 路由
291
-
292
- 只加载当前状态或 Task 直接需要的 Skill,同一批次不重复加载:
293
-
294
- | 触发条件 | Skill |
295
- |---|---|
296
- | 开始、恢复、工程或设备状态变化 | `preparing-migration-workspace` |
297
- | 规划或编写 ArkTS | `arkts-mvvm-architecture` |
298
- | Android 分析完成 | `appgraph-rule-audit` |
299
- | 初始化或更新报告 | `maintaining-migration-report` |
300
- | UI 自动化、迁移故障、已证实可复用经验 | `harmonyos-migration-playbook` |
301
- | 应用名称、图标、版本号、包名 | `arkts-app-identity` |
302
- | 用户可见文案与多语言 | `arkts-i18n` |
303
- | 图片、XML drawable、自适应图标 | `android2hmos_resources_convert` |
304
- | 图标或图片尺寸失真 | `arkts-icon-sizing` |
305
- | Android 三方库替代 | `native-library-substitution` |
306
- | 完整结束或明确中止 | `reviewing-migration-process` |
307
-
308
- Skill 是当前步骤的操作说明,不能覆盖本文的目标、状态机、硬门禁和暂停边界。
309
-
310
- `native-library-substitution` 是当前路由中的已知旧契约例外,只按 4.3.2 使用;其场景 4 不属于 V3 可直接调用的专项流程。
311
-
312
- ## 10. 网络后端触发规则
313
-
314
- 源码审查发现真实网络依赖时,必须验证“用户操作 → 请求 → 响应 → 界面结果”的完整链路:
315
-
316
- 1. 接口路径、字段、状态码和错误场景必须来自 Android 源码或真实接口证据。
317
- 2. 迁移验证使用独立 Mock Server,不得用页面静态数据或应用内 Mock Repository 冒充网络端到端验证。
318
- 3. Mock Server 使用受管服务启动,并至少覆盖成功、空数据、业务失败和边界数据。
319
- 4. Mock 验证只能声明 `mock-server-verified`,不能冒充真实后端验收。
320
-
321
- ## 11. 禁止的伪完成
322
-
323
- 以下任一情况都视为未完成:
324
-
325
- - 报告标记 `verified`,但实现只有注释、空函数、固定值或桩数据。
326
- - 页面或组件文件存在,但不能从真实 Ability、导航或 Android 对应控件到达。
327
- - 为通过测试额外增加控件,而原控件仍没有正确行为。
328
- - 只证明编译、安装、启动、不白屏或截图存在,没有验证交互和业务结果。
329
- - 只覆盖静态 Facts,忽略源码中扫描未发现的页面、入口或业务逻辑。
330
- - 测试只编写未执行,或使用旧收据、无关 refs、空执行结果冒充通过。
331
- - 使用坐标点击替代可语义定位控件的正式 Hypium 验收。
332
- - 测试前置条件不足时直接 `return` 或吞掉异常冒充通过。
333
- - 以“测试基建尚未建立”为理由连续完成功能。
334
- - 把实现缺陷包装成外部 blocker,或用报告说明替代修复。
335
-
336
- 判断原则始终是:用户在 HarmonyOS 应用中实际看到、操作和获得的结果是否与 Android 一致。
337
-
338
- ## 12. 完成条件
339
-
340
- 只有同时满足以下条件,才允许宣布迁移完成:
341
-
342
- - `[机器门禁]` Preflight、Facts、Task Plan、报告和证据均为当前源码对应的新鲜状态。
343
- - `[机器门禁]` HarmonyOS 工程构建、安装和启动成功。
344
- - `[机器门禁]` 所有 Task 通过结构校验并具有新鲜的定向设备验证证据。
345
- - `[机器门禁]` 全量 Hypium 回归执行数非零,且无失败、错误或忽略。
346
- - `[机器门禁]` `droid2hmos complete <ANDROID_PROJECT>` 成功退出。
347
- - `[行为验收]` 所有页面、可见控件、状态、导航、Dialog、业务功能、数据效果和错误路径均真实实现且可达。
348
- - `[行为验收]` Facts 遗漏但经源码发现的行为也已实现并验证。
349
- - `[行为验收]` 无法等价的差异已明确呈现,没有被静默标记为完成。
350
-
351
- 完成报告不等于完成迁移;`complete` 成功也不能替代对真实用户可观察结果的审查。
@@ -1,19 +0,0 @@
1
- {
2
- "orchestrator": {
3
- "command": "droid2hmos",
4
- "preflight": ["preflight"],
5
- "requiredCapabilities": [
6
- "status",
7
- "config init",
8
- "config validate",
9
- "device check android",
10
- "device check harmony"
11
- ]
12
- },
13
- "appgraph": {
14
- "command": "appgraph",
15
- "versionProbe": ["--version"],
16
- "healthProbe": ["spec-analysis", "--help"],
17
- "managedBy": "droid2hmos preflight"
18
- }
19
- }