@harmonyos-arkts/d2h 0.1.2 → 0.1.5

package/skills/preparing-migration-workspace/SKILL.md

@@ -1,124 +1,131 @@
 ---
 name: preparing-migration-workspace
-description: 在 Android 转 HarmonyOS 迁移开始或恢复时，通过 droid2hmos 执行统一 Preflight，并依据 CLI 返回结果和报告决定是否进入事实扫描与实现。也用于配置、Git checkpoint、构建测试、AppGraph 分析和设备检查。
+description: 在 Android 转 HarmonyOS 迁移开始或恢复时，通过 droid2hmos 读取状态、执行 Preflight、初始化或校验配置，并采集设备与外部环境就绪度。只负责工作区准备和能力分流；不调度分析、实现、构建、测试、回归或 Git checkpoint。
 ---
 
 # 准备迁移工作区
 
-本 Skill 只编排 `droid2hmos` 和独立的 `appgraph` CLI，不直接调用 Node 脚本、Gradle、Hvigor、Hypium、ADB 或 HDC。不要在 `ohos/` 尚不存在时猜测 HarmonyOS 构建配置。
+本 Skill 只负责回答四个问题：项目和迁移工作区是否定位正确、非设备基线是否可用、设备是否可用、哪些外部条件仍阻塞特定能力。它不决定后续状态，也不把设备失败扩大为整个迁移停止。
 
-迁移产物（`.migration/`）统一位于安卓工程父目录下的 `<工程名>-migration/.migration/`，由 CLI 自动创建和维护，不写入安卓工程内部。创建 `.migration/` 时 CLI 会自动在工作区根目录生成 `.gitignore`（内容 `.migration/`），防止迁移产物被上层 Git 仓库提交到远端。下文所有 `.migration/...` 路径均相对该工作区根目录。
+工具安装、精确版本和升级由 `managing-d2h-toolchain` 负责。本 Skill 只消费已检查的 CLI；发现版本或能力不符时返回该 Skill 处理，不运行 npm。
 
-开始或恢复时先获取只读事实快照：
+只调用 `droid2hmos` 的 `status`、`preflight`、`config init/validate` 和按需的 `device check`。不要直接调用 Node 脚本、Gradle、Hvigor、Hypium、ADB、HDC 或 AppGraph 分析命令，也不要在 `ohos/` 尚不存在时猜测 HarmonyOS 构建配置。
+
+迁移产物（`.migration/`）统一位于 Android 工程父目录下的 `<工程名>-migration/.migration/`，由 CLI 创建和维护，不写入 Android 工程内部。下文所有 `.migration/...` 路径均相对该迁移工作区根目录。
+
+## 输入与事实来源
+
+输入必须包含 Android Gradle 工程根目录。根目录应有 Gradle 标记，应用模块中应有 `AndroidManifest.xml`。
+
+开始或恢复时先获取只读快照：
 
 ```text
 droid2hmos status <ANDROID_PROJECT>
 ```
 
-使用 `completion.unmet` 识别缺口，使用 `allowedActions` 选择当前可安全调用的命令。`phase` 只解释当前现场，不是必须手工推进的状态；不得创建或编辑 `.migration/state.json`。
+以 CLI 返回的 `workspace`、`allowedActions`、`completion.unmet`、Preflight 检查项、`failedChecks` 和 `retry` 为机器事实。`phase` 只解释当前现场；不得创建或编辑 `.migration/state.json`。
 
-传入路径必须是 Android Gradle 工程根目录：根目录应有 Gradle 标记，并且应用模块中应有 `AndroidManifest.xml`。如果 `workspace.projectPresent=false` 且 `workspace.projectCandidates` 非空，说明传入的是包装目录；改用列出的明确候选工程，不得在包装目录初始化第二套 `.migration` 或 HarmonyOS 工程。
+如果 `workspace.projectPresent=false` 且 `workspace.projectCandidates` 非空，说明传入的是包装目录。改用列出的明确候选工程，不得在包装目录初始化第二套迁移工作区或 HarmonyOS 工程。
 
-## 首次执行
+## 首次准备
 
-运行统一门禁：
+运行统一预检：
 
 ```text
 droid2hmos preflight <ANDROID_PROJECT> [--sdk-path <PATH>] [--timeout-ms <MS>]
 ```
 
-`preflight` 负责选择检查项、判定检查项是否阻塞，并生成完整结果，包括：
+`preflight` 由 Kernel 选择并判定检查项，可能包含：
 
 - Android UI 技术栈支持性；
-- Git 仓库、分支、`HEAD` 和工作区干净状态；
-- Git、Node.js 20-24、npm、Python 3.10+、JDK、Android SDK 和 DevEco 工具链；
-- `appgraph --version` 及迁移分析能力健康检查；
+- Git 仓库、分支、`HEAD` 和用户已有改动；
+- Git、Node.js、npm、Python、JDK、DevEco 和 HarmonyOS SDK（Android SDK 探测已移除，迁移不依赖 Android 编译环境）；
+- AppGraph 健康检查；
 - `.migration/config.json` 初始化和校验；
-- Android 基线状态及设备检查；
-- 已有 HarmonyOS 工程复用，或在目标为空时创建可编译工程壳；
-- HarmonyOS SDK 探测、应用 HAP 基线构建和必须通过的 HDC 设备检查；
+- Android 基线状态；
+- 已有 HarmonyOS 工程复用，或在空目标中创建工程壳；
+- Preflight 自身所需的基线构建和设备检查；
 - `.migration/preflight-report.json` 原子生成。
 
-已有 HarmonyOS 工程不得被覆盖。只想校验现有工程、不允许初始化工程壳时加 `--no-init-harmony`。命令失败后读取报告中的 `failedChecks`、`retry` 和对应日志；只有 `transient/bounded` 允许在给出的上限内原样重试，其余失败必须先改变输入或环境，不得绕过门禁继续事实扫描或实现。
-
-环境类门禁（`toolchain`、`devecocli-auth`、`appgraph`、`harmony-sdk`、`harmony-device`）只探测一次：它们依赖本机工具、华为账号授权或物理设备，原样重跑 `preflight` 不会自愈。这类失败会返回 `retry.kind=external` 且带 `remediation`；必须把 `remediation` 明确转述给用户、等待用户修改环境，不得在同一环境下连续重跑 `preflight`。其余（非环境类）失败在按 `retry` 指引改变输入后重跑。
-
-本 Skill 不单独定义或重算任何子检查门禁。命令成功且报告总体结果为 `passed` 时继续。
+这些是 Preflight 的内部门禁，不授权本 Skill 在预检后继续调度仓库级构建、测试或分析。已有 HarmonyOS 工程不得被覆盖；只校验现有工程且不允许初始化工程壳时使用 `--no-init-harmony`。
 
-## 语言资源基线清点
+命令失败时读取 `failedChecks`、`retry` 和对应日志：
 
-Preflight 通过后、进入事实扫描与批次规划前，对 Android 工程做一次只读语言清点（文件枚举，不涉及构建）：列出各应用模块 `src/*/res/` 下带语言/地区限定符的 `values-<locale>` 目录（如 `values-zh`、`values-en-rUS`、`values-b+es+419`；排除 `night`、`land`、`v<N>`、`sw<N>dp` 等非语言限定符），记录语言清单与数量。该清点结果是规划的强制输入：
+- `retry.kind=transient/bounded`：只在返回的上限内原样重试；
+- `retry.kind=external`：记录为外部阻塞项并返回具体 `remediation`，不要在环境未变化时连续重跑；
+- 其他失败：返回受影响能力和补救建议，不自行推断绕过方式。
 
-- 语言数 > 1：实现批次必须包含 i18n 资源迁移批次，该批次开始前加载 `arkts-i18n` skill，按其目录规范迁移全部语言；
-- 语言数 = 1：也须在写入首个字符串资源前加载 `arkts-i18n` 确认资源组织方式；
-- 任何情况下不得把用户可见文案硬编码进页面代码来替代字符串资源迁移。
+不要把 `preflight` 非零退出一概解释为“迁移不能继续”。例如 HarmonyOS 设备不可用只阻止设备测试、运行态验收和依赖设备的证据采集；当 `allowedActions` 仍允许时，源码阅读、静态分析和非设备实现可以继续。反之，工程定位、配置或必要工具链缺失可能使 `allowedNonDeviceWork=false`。最终分流必须忠实反映本次 CLI 快照。
 
-## 配置与测试
+## 配置
 
-需要显式提供项目特有的 Android 命令时，先运行：
+需要显式提供 HarmonyOS 工程路径时使用：
 
 ```text
-droid2hmos config init <ANDROID_PROJECT> [--harmony-project <PATH>] [--android-build <COMMAND>] [--android-test <COMMAND>]
+droid2hmos config init <ANDROID_PROJECT> [--harmony-project <PATH>]
 droid2hmos config validate <ANDROID_PROJECT>
 ```
 
-配置中只保存 Android 侧有限命令和能够确认的路径。不得保存或猜测 `harmonyBuild`、`harmonyTest`、module、product 或 target；HarmonyOS 参数由 CLI 从真实工程配置解析。
-
-`androidBuild` 默认为 null：迁移流程不编译 Android 工程，`analyze android` 是纯源码静态分析且不要求 APK。只有用户明确要求 Android/HarmonyOS 双端运行对照时，才通过 `--android-build` 显式配置构建命令；未配置时执行 `droid2hmos build android` 会返回引导提示而非自动探测。
-
-在首次 Preflight 之后需要针对性诊断或验证时使用：
-
-```text
-droid2hmos build <android|harmony|all> <ANDROID_PROJECT> [--timeout-ms <MS>]
-droid2hmos test android <ANDROID_PROJECT> [--task <TASK>] [--timeout-ms <MS>]
-droid2hmos test harmony <ANDROID_PROJECT> (--class <CLASS> [--case <CASE>] | --all) [--target <DEVICE>] [--case-timeout-ms <MS>] [--ref <REPORT_REF>...]
-```
+配置中只保存能够确认的路径。不得保存或猜测 `harmonyBuild`、`harmonyTest`、module、product 或 target；HarmonyOS 参数由 CLI 从真实工程配置解析。
 
-Android 测试只有在 `.migration/config.json` 已声明可执行的 `androidTest` 时运行。HarmonyOS 测试只有在已有 Hypium 测试资产时运行；没有测试资产时记录缺口，并在第一个可交互功能验收前建立。多个 HDC 目标可响应时必须显式传 `--target`，防止证据偶然落在另一台设备。`--case-timeout-ms` 控制单个 Hypium 用例超时，`--ref` 只声明该测试实际断言的报告项。CLI 会解析 Hypium 摘要：失败、错误、忽略、零执行或缺少摘要即使 HDC 退出码为零也视为失败。
+`androidBuild`/`androidTest` 字段仅为兼容旧工作区保留：CLI 不再提供设置入口，也不再执行这些命令（Android 构建与测试能力已移除）。
 
-Hvigor 返回成功但没有刷新输出时，CLI 只复用不早于各自构建输入的既有应用/ohosTest HAP；应用源码变化只要求应用 HAP 更新，不会强制无关的 ohosTest HAP 重打。产物比对应源码或构建配置旧时必须失败并要求修复构建，而不是安装过期包。
+## 设备状态采集
 
-## 分析与设备诊断
-
-Android 和 HarmonyOS 分析统一使用：
-
-```text
-droid2hmos analyze <android|harmony|all> <ANDROID_PROJECT>
-```
-
-CLI 负责调用 PATH 中的 `appgraph`，HarmonyOS 分析自动读取配置里的 SDK 路径。只有统一命令失败且需要定位工具缺陷时，才直接运行 `appgraph --version` 或查看其帮助；不得自行拼接内部分析参数作为正常工作流。
-
-需要单独复查设备时使用：
+当现有 Preflight 报告缺少当前设备状态，或调用方明确需要刷新设备状态时，可运行：
 
 ```text
-droid2hmos device check <android|harmony>
+droid2hmos device check harmony
 ```
 
-Android 设备缺失是可记录的增强项；HarmonyOS 设备必须可被发现且 Shell 可响应，否则停止需要设备证据的流程。
+只记录设备发现、Shell 响应、目标歧义和返回的 remediation（Android 设备检测已移除，仅支持 HarmonyOS）。多个目标、认证、签名或设备离线问题进入 `externalBlockers` 或 `capabilityBlockers`，由调用方决定何时处理。本 Skill 不因设备问题暂停并要求用户作流程选择。
 
-## 恢复执行与 Git checkpoint
+## 恢复
 
-恢复迁移时不得重新初始化已有 `ohos/`。先运行：
+恢复时不得重新初始化已有 `ohos/`。运行：
 
 ```text
 droid2hmos status <ANDROID_PROJECT>
-droid2hmos checkpoint status <ANDROID_PROJECT>
 droid2hmos config validate <ANDROID_PROJECT>
 ```
 
-然后只重跑快照显示为缺失或因源码指纹变化而失效的 `build`、`test`、`device check` 或 `analyze`。如果工具链、AppGraph、工程壳或基础环境可能变化，则重新运行完整 `preflight`。`.migration/` 运行态文件不会让重复 Preflight 自己判定工作区变脏；已有配置中尚未纳入 Git 的 HarmonyOS 目录可作为上次预检生成物忽略，但首次运行前就存在的未跟踪 `ohos/` 和该目录内已有的 tracked 变更仍然阻塞，不能借此隐藏用户改动。
-
-完成一个经验证的迁移单元后，只提交明确列出的文件：
-
-```text
-droid2hmos checkpoint create <ANDROID_PROJECT> --message <MESSAGE> --include <PATH> [--include <PATH>...]
+仅当工具链、配置、工程壳或设备环境可能变化，或 CLI 明确要求刷新 Preflight 时，重新运行 `preflight`。不要在这里检查或创建 checkpoint，也不要补跑 `analyze`、`build`、`test` 或全量回归；这些属于调用方根据当前工作单元和状态决定的后续动作。
+
+不得处理、覆盖、提交或删除用户已有改动。
+
+## 结构化结果
+
+始终返回同一就绪度结构：
+
+```json
+{
+  "baselineReady": true,
+  "deviceReady": false,
+  "externalBlockers": [],
+  "capabilityBlockers": [
+    {
+      "capability": "device-validation",
+      "check": "harmony-device",
+      "reason": "no responsive target",
+      "remediation": "connect or start one HarmonyOS target"
+    }
+  ],
+  "allowedNonDeviceWork": true,
+  "allowedActions": [],
+  "evidence": [".migration/preflight-report.json"],
+  "suggestedRemediation": []
+}
 ```
 
-仅在调用者明确要求纳入全部相关变更时使用 `--all`。即使使用 `--all`，`.migration/` 运行态和证据归档也不会进入提交。不得处理、覆盖或删除用户已有改动；生成的 AppGraph、命令日志和预检日志不进入检查点。显式路径暂存失败时命令会撤销本次新加入暂存区的文件，并保留调用前已经暂存的内容。
-
-## 继续条件
+字段语义：
 
-- `droid2hmos preflight` 成功退出；
-- `.migration/preflight-report.json` 已生成且总体结果为 `passed`。
+- `baselineReady`：工程定位、迁移配置和非设备基础能力是否足以支持 CLI 明确允许的后续工作；不能仅用 Preflight 总体退出码代替；
+- `deviceReady`：当前 HarmonyOS 目标是否满足设备类工作要求；
+- `externalBlockers`：需要用户、账号、签名、物理设备或外部环境变化的阻塞项；
+- `capabilityBlockers`：按能力说明阻塞范围，不能写成笼统的“迁移停止”；
+- `allowedNonDeviceWork`：当前是否仍可继续源码阅读、静态分析或非设备实现；
+- `allowedActions`：原样返回 CLI 快照中的允许动作；
+- `evidence`：本次读取或生成的状态、配置和 Preflight 报告；
+- `suggestedRemediation`：CLI 给出的可执行补救，不臆造成功结论。
 
-各检查项的 `required`、`status` 和最终阻塞关系以本次 CLI 输出及报告为唯一依据，Skill 不重复推导通过条件。
+本 Skill 不推进外部状态机、不更新迁移报告、不创建 checkpoint、不调用 `complete`，也不决定定向测试或全量回归。调用方根据上述结果决定下一步。

package/skills/preparing-migration-workspace/toolchain.json

@@ -1,43 +0,0 @@
-{
-  "orchestrator": {
-    "command": "droid2hmos",
-    "preflight": ["preflight"],
-    "requiredCapabilities": [
-      "status",
-      "complete",
-      "config init",
-      "config validate",
-      "checkpoint status",
-      "checkpoint create",
-      "build android",
-      "build harmony",
-      "test android",
-      "test harmony",
-      "device check android",
-      "device check harmony",
-      "analyze android",
-      "analyze harmony",
-      "evidence capture",
-      "evidence flow",
-      "evidence compare",
-      "report init",
-      "report update",
-      "report validate",
-      "report render",
-      "mock init",
-      "service start",
-      "service status",
-      "service stop",
-      "logs list",
-      "logs show",
-      "logs failures",
-      "logs stats"
-    ]
-  },
-  "appgraph": {
-    "command": "appgraph",
-    "versionProbe": ["--version"],
-    "healthProbe": ["spec-analysis", "--help"],
-    "managedBy": "droid2hmos preflight"
-  }
-}