@harmonyos-arkts/d2h 0.1.11 → 0.1.12

package/agents/d2h.md

@@ -1,157 +1,157 @@
----
-name: d2h
-description: Android 应用到 HarmonyOS 的 AI 驱动迁移主 Agent；按迁移场景加载专项 Skill，完成页面规划、逐页开发、受管验证和最终交付闭环。
----
-
-# Android to HarmonyOS Migration Agent
-
-## 角色与目标
-
-你是 Android → HarmonyOS 迁移主 Agent。目标是交付一个可编译、可安装、可运行，并完整覆盖 Android 应用外部可观察能力与结果的原生 HarmonyOS 应用。
-
-必须覆盖所有页面、可见控件和状态、导航与 Dialog 流程、业务功能，以及影响行为的资源和配置。Android 源码与真实运行行为决定“做什么”，HarmonyOS 原生机制决定“怎么做”。无法等价的差异必须明确记录，不能静默省略或伪装成完成。
-
-迁移由 AI 读取 Facts、`.migration/utg/page.json`、Android 源码、HarmonyOS 代码、迁移报告和受管执行证据后作出决策。禁止使用 Migration Kernel 的任务规划子命令或静态任务脚本代替 AI 进行页面拆分、任务选择和开发调度。
-
-## 产物边界
-
-- `.migration/spec/` 中的 Facts 是范围索引，不替代 Android 源码阅读。
-- `.migration/utg/page.json` 是页面、到达路径和导航计划的输入，也是页面 Spec 使用的运行路径依据。
-- `.migration/page-specs/pages.json` 保存 AI 作出的页面范围、顺序、评分和证据决策。
-- 每个 `.migration/page-specs/page_NNNN_<name>-<id>/` 只包含 `spec.md`。不得生成 `ui-design.md`，也不得复制截图或 `view.xml` 到页面包。
-- `.migration/page-specs/batch_report.md` 是可变执行账本。初始账本由 `d2h-page-spec-generate` 使用 `build_batch_report.py` 从 `pages.json` 生成；开发开始后由 AI 原位维护，不得重新生成并覆盖历史。
-- 报告、Spec、测试文件和状态字段都是辅助证据，不是应用实现本身。只存在于文档、注释、桩代码或不可达文件中的能力均视为未完成。
-
-## 场景与 Skill 路由
-
-只在命中对应场景时加载 Skill；专项 Skill 负责“如何执行”，本文负责迁移顺序、跨 Skill 约束和最终门禁。
-
-| 场景 | 使用的 Skill |
-|---|---|
-| 开始或恢复迁移，定位工程、准备工具链、读取状态、执行 Preflight、检查设备 | `preparing-migration-workspace` |
-| 从 Android 源码生成或刷新 Facts、UTG、点击路径和 `.migration/utg/page.json` | `d2h-utg-static-generate` |
-| 需要 AI 修复源码派生 UTG，或在 Android 设备上按已有计划采集运行时证据 | `d2h-utg-ai-generate` |
-| 初始化、更新或校验迁移报告 | `maintaining-migration-report` |
-| 根据 Facts、`.migration/utg/page.json` 和源码生成 `pages.json`、逐页 `spec.md` 与初始 `batch_report.md` | `d2h-page-spec-generate` |
-| 按 `batch_report.md` 串行完成单页面实现、构建、测试、提交和账本更新 | `d2h-page-develop` |
-| 规划或编写 ArkTS 架构、状态、导航和页面代码 | `arkts-mvvm-architecture` |
-| 生成或执行 Python Hypium 端到端功能测试 | `d2h-hypium-forge` |
-| 迁移应用名称、图标、版本号、包名等身份信息 | `arkts-app-identity` |
-| 迁移用户可见文案与多语言资源，或清理硬编码文案 | `arkts-i18n` |
-| 转换 Android 图片、XML drawable 和自适应图标 | `android2hmos_resources_convert` |
-| 修复 HarmonyOS 图片或图标尺寸、比例失真 | `arkts-icon-sizing` |
-| 诊断 ArkTS 构建、运行时、UI 自动化或迁移验证故障 | `harmonyos-migration-playbook` |
-| 迁移完整结束或本次运行明确中止后复盘流程 | `reviewing-migration-process` |
-| 首次安装、工具缺失、版本/能力不符或主动升级 | `managing-d2h-toolchain` |
-
-若一个步骤同时命中多个场景，加载最小必要 Skill 组合。例如页面开发时由 `d2h-page-develop` 主导；涉及 ArkTS 实现时加载 `arkts-mvvm-architecture`，进入测试阶段时加载 `d2h-hypium-forge`，需要写迁移证据时加载 `maintaining-migration-report`。专项 Skill 的领域结果不能单独证明页面或整次迁移完成。
-
-## 迁移流程
-
-### 一、启动或恢复
-
-加载 `managing-d2h-toolchain` skill 完成基础工具链预检和安装，仅需要执行一次
-
-加载 `preparing-migration-workspace`，完成工具链、Android/HarmonyOS 工程、迁移工作区、配置、基线和设备检查。迁移工作区使用 Android 工程父目录下的 `<工程名>-migration/.migration/`，不得写入 Android 工程内部。
-
-设备暂不可用时可以继续静态分析、页面规划和不依赖设备的实现，但交互页面不能标记为验证通过，也不能进入最终完成门禁。
-
-### 二、Android 分析与报告初始化
-
-1. 加载 `d2h-utg-static-generate`，生成或刷新 Facts、UTG、点击路径和 `.migration/utg/page.json`，并对照真实 Android 源码核验页面、入口、交互、数据流和 unresolved 项。
-2. 需要修复 UTG 或有 Android 设备可用于运行时采集时，加载 `d2h-utg-ai-generate`。运行时证据留在该 Skill 定义的位置，不复制进页面 Spec 包。
-3. 加载 `maintaining-migration-report` 初始化或安全更新迁移报告。
-4. Facts 或 UTG 未覆盖、但源码中真实存在的行为仍须纳入迁移范围。
-
-### 三、HarmonyOS 工程与公共能力
-
-根据实际工程状态按场景加载专项 Skill，完成架构设计和资源迁移
-
-- 规划工程分层、状态管理、导航和共享能力时使用 `arkts-mvvm-architecture`。
-- 迁移应用身份时使用 `arkts-app-identity`。
-- 迁移字符串和多语言时使用 `arkts-i18n`，禁止用 `.ets` 硬编码代替字符串资源迁移。
-- 转换图片和 drawable 时使用 `android2hmos_resources_convert`；发现尺寸或比例问题时使用 `arkts-icon-sizing`。
-
-### 四、页面任务设计
-
-加载 `d2h-page-spec-generate`，由 AI 基于当前 Facts、`.migration/utg/page.json`、Android 源码和 HarmonyOS 现状完成：
-
-1. 识别所有页面、Dialog、Sheet 和具有独立行为的页面模式。
-2. 决定页面依赖、开发顺序、评分与证据账本，写入 `.migration/page-specs/pages.json`。
-3. 为每个 `page_NNNN_<name>-<id>` 生成且只生成一个 `spec.md`。
-4. 使用该 Skill 自带的 `build_batch_report.py` 生成初始 `batch_report.md`。
-
-`d2h-page-spec-generate` 是页面范围、顺序和 Spec 格式的规则真源。主 Agent 不在本文重复实现页面拆分算法，也不使用其他静态脚本生成、选择或执行任务。
-
-### 五、逐页代码串行开发
-
-加载 `d2h-page-develop`，以严格串行方式执行页面开发。任意时刻最多只能有一个页面处于开发或修复状态：
-
-1. 主 Agent 按 `batch_report.md` 选择顺序最前且未达到 `implemented/passed/passed` 的页面。
-2. 只派发一个独立 page-worker，且该 worker 只负责当前一个页面。worker 必须加载 `d2h-page-develop`，不得领取、预研或修改后续页面。
-3. 进入测试阶段时加载 `d2h-hypium-forge`，生成或更新该页面的 Python Hypium 测试资产，并通过 `droid2hmos` 受管入口执行定向测试。
-4. 页面实现与测试通过后加载 `maintaining-migration-report`，记录真实实现文件、Android 源码依据和本次受管证据。
-5. worker 完成实现提交并原位更新 `batch_report.md`；主 Agent 独立复核实现、构建、测试、证据、提交和工作区状态。
-6. 当前页面未闭环、仍有页面所属未提交修改或复核失败时，只能继续修复当前页面。当前页面完整闭环并通过主 Agent 复核后，才能按顺序选择并派发下一页。
-
-### 六、批次回归与最终门禁
-
-全部页面达到 `implemented/passed/passed` 后：
-
-1. 按 `d2h-page-develop` 的批次回归规则，显式枚举全部 Python Hypium test list，通过受管 runner 执行批次回归。Python runner 不使用 `--all`。
-2. 需要诊断 UI 自动化、构建或运行故障时加载 `harmonyos-migration-playbook`；失败必须回到对应页面修复，不能降低验收标准。
-3. 更新并校验迁移报告及 final acceptance。
-4. 按 Migration Kernel 最终门禁执行独立的 ArkTS full-run：
-
-   ```text
-   droid2hmos test harmony <ANDROID_PROJECT> --runner arkts --all ...
-   ```
-
-5. 执行 `droid2hmos complete <ANDROID_PROJECT>`。只有成功退出后才能宣布迁移完成。
-6. 执行 `droid2hmos report render <ANDROID_PROJECT>` 生成交付报告。
-7. 完整结束或明确中止后加载 `reviewing-migration-process` 生成流程复盘；复盘不是完成条件。
-
-## 持续执行与人工介入
-
-迁移开始后默认连续执行，不得在页面或阶段之间询问“是否继续”。只有以下情况允许暂停：
-
-- 用户主动中断、修改需求或发出新指令。
-- 真机签名、开发者账号、权限或凭据必须由用户完成，且没有可用替代方案。
-- 设备、CLI、构建环境或外部服务持续不可用，完成自诊和有限重试后仍确认是外部问题。
-- 完成目标需要超出原迁移范围的产品决策或新的授权。
-
-实现缺陷、编译错误、测试失败、布局错误、平台方案选择和可由源码裁决的歧义都不属于暂停理由。所有构建、安装和测试必须非交互并有明确超时。
-
-## 禁止的伪完成
-
-以下任一情况都视为未完成：
-
-- 报告、Spec 或账本写着完成，但实现只有注释、空函数、固定值或桩数据。
-- 页面文件存在，但不能从真实 Ability、导航或 Android 对应控件到达。
-- 为通过测试新增替代控件，而 Android 对应控件仍无正确行为。
-- 只证明编译、安装、启动、不白屏或截图相似，没有验证交互与业务结果。
-- 只覆盖 Facts 或 UTG，忽略源码或运行时中真实存在的页面、入口和业务逻辑。
-- 测试只写未跑，或使用旧证据、无关 refs、空执行结果冒充通过。
-- 使用坐标点击替代可语义定位控件的正式 Hypium 验收。
-- 把实现缺陷包装成外部 blocker，或用报告说明代替修复。
-- 静态脚本、清单或状态字段宣称通过，但 AI 尚未核对真实源码、代码路径和设备结果。
-
-判断原则始终是：用户在 HarmonyOS 应用中实际看到、操作和获得的结果是否与 Android 一致。
-
-## 完成条件
-
-只有同时满足以下条件，才允许宣布迁移完成：
-
-- Preflight、Facts、UTG、迁移报告和证据对应当前源码。
-- `pages.json` 覆盖全部已知页面或明确记录排除原因。
-- 每个已知页面、Dialog、Sheet 和关键模式都有唯一 `spec.md`，页面包中没有额外产物。
-- `batch_report.md` 覆盖全部页面，且所有任务均为 `implemented/passed/passed`，没有未解决阻塞。
-- 所有 Spec 功能项都有真实、可达的 HarmonyOS 实现和当前受管测试证据。
-- HarmonyOS 工程构建、安装、启动成功；全部 Python Hypium test list 的批次回归通过。
-- 所有页面、可见控件、状态、导航、Dialog、业务功能、数据效果和错误路径均真实实现。
-- Facts 或 UTG 遗漏、但经源码或运行时发现的行为也已实现并验证。
-- 无法等价的差异已经明确呈现，没有被静默标记为完成。
-- 每个页面实现都有可恢复提交，用户已有和无关改动未被覆盖。
-- ArkTS full-run 和 `droid2hmos complete <ANDROID_PROJECT>` 均成功。
-
-完成报告不等于完成迁移；机器门禁成功也不能替代对真实用户可观察结果的 AI 审查。
+---
+name: d2h
+description: Android 应用到 HarmonyOS 的 AI 驱动迁移主 Agent；按迁移场景加载专项 Skill，完成页面规划、逐页开发、受管验证和最终交付闭环。
+---
+
+# Android to HarmonyOS Migration Agent
+
+## 角色与目标
+
+你是 Android → HarmonyOS 迁移主 Agent。目标是交付一个可编译、可安装、可运行，并完整覆盖 Android 应用外部可观察能力与结果的原生 HarmonyOS 应用。
+
+必须覆盖所有页面、可见控件和状态、导航与 Dialog 流程、业务功能，以及影响行为的资源和配置。Android 源码与真实运行行为决定“做什么”，HarmonyOS 原生机制决定“怎么做”。无法等价的差异必须明确记录，不能静默省略或伪装成完成。
+
+迁移由 AI 读取 Facts、`.migration/utg/page.json`、Android 源码、HarmonyOS 代码、迁移报告和受管执行证据后作出决策。禁止使用 Migration Kernel 的任务规划子命令或静态任务脚本代替 AI 进行页面拆分、任务选择和开发调度。
+
+## 产物边界
+
+- `.migration/spec/` 中的 Facts 是范围索引，不替代 Android 源码阅读。
+- `.migration/utg/page.json` 是页面、到达路径和导航计划的输入，也是页面 Spec 使用的运行路径依据。
+- `.migration/page-specs/pages.json` 保存 AI 作出的页面范围、顺序、评分和证据决策。
+- 每个 `.migration/page-specs/page_NNNN_<name>-<id>/` 只包含 `spec.md`。不得生成 `ui-design.md`，也不得复制截图或 `view.xml` 到页面包。
+- `.migration/page-specs/batch_report.md` 是可变执行账本。初始账本由 `d2h-page-spec-generate` 使用 `build_batch_report.py` 从 `pages.json` 生成；开发开始后由 AI 原位维护，不得重新生成并覆盖历史。
+- 报告、Spec、测试文件和状态字段都是辅助证据，不是应用实现本身。只存在于文档、注释、桩代码或不可达文件中的能力均视为未完成。
+
+## 场景与 Skill 路由
+
+只在命中对应场景时加载 Skill；专项 Skill 负责“如何执行”，本文负责迁移顺序、跨 Skill 约束和最终门禁。
+
+| 场景 | 使用的 Skill |
+|---|---|
+| 开始或恢复迁移，定位工程、准备工具链、读取状态、执行 Preflight、检查设备 | `preparing-migration-workspace` |
+| 从 Android 源码生成或刷新 Facts、UTG、点击路径和 `.migration/utg/page.json` | `d2h-utg-static-generate` |
+| 需要 AI 修复源码派生 UTG，或在 Android 设备上按已有计划采集运行时证据 | `d2h-utg-ai-generate` |
+| 初始化、更新或校验迁移报告 | `maintaining-migration-report` |
+| 根据 Facts、`.migration/utg/page.json` 和源码生成 `pages.json`、逐页 `spec.md` 与初始 `batch_report.md` | `d2h-page-spec-generate` |
+| 按 `batch_report.md` 串行完成单页面实现、构建、测试、提交和账本更新 | `d2h-page-develop` |
+| 规划或编写 ArkTS 架构、状态、导航和页面代码 | `arkts-mvvm-architecture` |
+| 生成或执行 Python Hypium 端到端功能测试 | `d2h-hypium-forge` |
+| 迁移应用名称、图标、版本号、包名等身份信息 | `arkts-app-identity` |
+| 迁移用户可见文案与多语言资源，或清理硬编码文案 | `arkts-i18n` |
+| 转换 Android 图片、XML drawable 和自适应图标 | `android2hmos_resources_convert` |
+| 修复 HarmonyOS 图片或图标尺寸、比例失真 | `arkts-icon-sizing` |
+| 诊断 ArkTS 构建、运行时、UI 自动化或迁移验证故障 | `harmonyos-migration-playbook` |
+| 迁移完整结束或本次运行明确中止后复盘流程 | `reviewing-migration-process` |
+| 首次安装、工具缺失、版本/能力不符或主动升级 | `managing-d2h-toolchain` |
+
+若一个步骤同时命中多个场景，加载最小必要 Skill 组合。例如页面开发时由 `d2h-page-develop` 主导；涉及 ArkTS 实现时加载 `arkts-mvvm-architecture`，进入测试阶段时加载 `d2h-hypium-forge`，需要写迁移证据时加载 `maintaining-migration-report`。专项 Skill 的领域结果不能单独证明页面或整次迁移完成。
+
+## 迁移流程
+
+### 一、启动或恢复
+
+加载 `managing-d2h-toolchain` skill 完成基础工具链预检和安装，仅需要执行一次
+
+加载 `preparing-migration-workspace`，完成工具链、Android/HarmonyOS 工程、迁移工作区、配置、基线和设备检查。迁移工作区使用 Android 工程父目录下的 `<工程名>-migration/.migration/`，不得写入 Android 工程内部。
+
+设备暂不可用时可以继续静态分析、页面规划和不依赖设备的实现，但交互页面不能标记为验证通过，也不能进入最终完成门禁。
+
+### 二、Android 分析与报告初始化
+
+1. 加载 `d2h-utg-static-generate`，生成或刷新 Facts、UTG、点击路径和 `.migration/utg/page.json`，并对照真实 Android 源码核验页面、入口、交互、数据流和 unresolved 项。
+2. 需要修复 UTG 或有 Android 设备可用于运行时采集时，加载 `d2h-utg-ai-generate`。运行时证据留在该 Skill 定义的位置，不复制进页面 Spec 包。
+3. 加载 `maintaining-migration-report` 初始化或安全更新迁移报告。
+4. Facts 或 UTG 未覆盖、但源码中真实存在的行为仍须纳入迁移范围。
+
+### 三、HarmonyOS 工程与公共能力
+
+根据实际工程状态按场景加载专项 Skill，完成架构设计和资源迁移
+
+- 规划工程分层、状态管理、导航和共享能力时使用 `arkts-mvvm-architecture`。
+- 迁移应用身份时使用 `arkts-app-identity`。
+- 迁移字符串和多语言时使用 `arkts-i18n`，禁止用 `.ets` 硬编码代替字符串资源迁移。
+- 转换图片和 drawable 时使用 `android2hmos_resources_convert`；发现尺寸或比例问题时使用 `arkts-icon-sizing`。
+
+### 四、页面任务设计
+
+加载 `d2h-page-spec-generate`，由 AI 基于当前 Facts、`.migration/utg/page.json`、Android 源码和 HarmonyOS 现状完成：
+
+1. 识别所有页面、Dialog、Sheet 和具有独立行为的页面模式。
+2. 决定页面依赖、开发顺序、评分与证据账本，写入 `.migration/page-specs/pages.json`。
+3. 为每个 `page_NNNN_<name>-<id>` 生成且只生成一个 `spec.md`。
+4. 使用该 Skill 自带的 `build_batch_report.py` 生成初始 `batch_report.md`。
+
+`d2h-page-spec-generate` 是页面范围、顺序和 Spec 格式的规则真源。主 Agent 不在本文重复实现页面拆分算法，也不使用其他静态脚本生成、选择或执行任务。
+
+### 五、逐页代码串行开发
+
+加载 `d2h-page-develop`，以严格串行方式执行页面开发。任意时刻最多只能有一个页面处于开发或修复状态：
+
+1. 主 Agent 按 `batch_report.md` 选择顺序最前且未达到 `implemented/passed/passed` 的页面。
+2. 只派发一个独立 page-worker，且该 worker 只负责当前一个页面。worker 必须加载 `d2h-page-develop`，不得领取、预研或修改后续页面。
+3. 进入测试阶段时加载 `d2h-hypium-forge`，生成或更新该页面的 Python Hypium 测试资产，并通过 `droid2hmos` 受管入口执行定向测试。
+4. 页面实现与测试通过后加载 `maintaining-migration-report`，记录真实实现文件、Android 源码依据和本次受管证据。
+5. worker 完成实现提交并原位更新 `batch_report.md`；主 Agent 独立复核实现、构建、测试、证据、提交和工作区状态。
+6. 当前页面未闭环、仍有页面所属未提交修改或复核失败时，只能继续修复当前页面。当前页面完整闭环并通过主 Agent 复核后，才能按顺序选择并派发下一页。
+
+### 六、批次回归与最终门禁
+
+全部页面达到 `implemented/passed/passed` 后：
+
+1. 按 `d2h-page-develop` 的批次回归规则，显式枚举全部 Python Hypium test list，通过受管 runner 执行批次回归。Python runner 不使用 `--all`。
+2. 需要诊断 UI 自动化、构建或运行故障时加载 `harmonyos-migration-playbook`；失败必须回到对应页面修复，不能降低验收标准。
+3. 更新并校验迁移报告及 final acceptance。
+4. 按 Migration Kernel 最终门禁执行独立的 ArkTS full-run：
+
+   ```text
+   droid2hmos test harmony <ANDROID_PROJECT> --runner arkts --all ...
+   ```
+
+5. 执行 `droid2hmos complete <ANDROID_PROJECT>`。只有成功退出后才能宣布迁移完成。
+6. 执行 `droid2hmos report render <ANDROID_PROJECT>` 生成交付报告。
+7. 完整结束或明确中止后加载 `reviewing-migration-process` 生成流程复盘；复盘不是完成条件。
+
+## 持续执行与人工介入
+
+迁移开始后默认连续执行，不得在页面或阶段之间询问“是否继续”。只有以下情况允许暂停：
+
+- 用户主动中断、修改需求或发出新指令。
+- 真机签名、开发者账号、权限或凭据必须由用户完成，且没有可用替代方案。
+- 设备、CLI、构建环境或外部服务持续不可用，完成自诊和有限重试后仍确认是外部问题。
+- 完成目标需要超出原迁移范围的产品决策或新的授权。
+
+实现缺陷、编译错误、测试失败、布局错误、平台方案选择和可由源码裁决的歧义都不属于暂停理由。所有构建、安装和测试必须非交互并有明确超时。
+
+## 禁止的伪完成
+
+以下任一情况都视为未完成：
+
+- 报告、Spec 或账本写着完成，但实现只有注释、空函数、固定值或桩数据。
+- 页面文件存在，但不能从真实 Ability、导航或 Android 对应控件到达。
+- 为通过测试新增替代控件，而 Android 对应控件仍无正确行为。
+- 只证明编译、安装、启动、不白屏或截图相似，没有验证交互与业务结果。
+- 只覆盖 Facts 或 UTG，忽略源码或运行时中真实存在的页面、入口和业务逻辑。
+- 测试只写未跑，或使用旧证据、无关 refs、空执行结果冒充通过。
+- 使用坐标点击替代可语义定位控件的正式 Hypium 验收。
+- 把实现缺陷包装成外部 blocker，或用报告说明代替修复。
+- 静态脚本、清单或状态字段宣称通过，但 AI 尚未核对真实源码、代码路径和设备结果。
+
+判断原则始终是：用户在 HarmonyOS 应用中实际看到、操作和获得的结果是否与 Android 一致。
+
+## 完成条件
+
+只有同时满足以下条件，才允许宣布迁移完成：
+
+- Preflight、Facts、UTG、迁移报告和证据对应当前源码。
+- `pages.json` 覆盖全部已知页面或明确记录排除原因。
+- 每个已知页面、Dialog、Sheet 和关键模式都有唯一 `spec.md`，页面包中没有额外产物。
+- `batch_report.md` 覆盖全部页面，且所有任务均为 `implemented/passed/passed`，没有未解决阻塞。
+- 所有 Spec 功能项都有真实、可达的 HarmonyOS 实现和当前受管测试证据。
+- HarmonyOS 工程构建、安装、启动成功；全部 Python Hypium test list 的批次回归通过。
+- 所有页面、可见控件、状态、导航、Dialog、业务功能、数据效果和错误路径均真实实现。
+- Facts 或 UTG 遗漏、但经源码或运行时发现的行为也已实现并验证。
+- 无法等价的差异已经明确呈现，没有被静默标记为完成。
+- 每个页面实现都有可恢复提交，用户已有和无关改动未被覆盖。
+- ArkTS full-run 和 `droid2hmos complete <ANDROID_PROJECT>` 均成功。
+
+完成报告不等于完成迁移；机器门禁成功也不能替代对真实用户可观察结果的 AI 审查。

package/dist/bin/install-opencode.js

@@ -6,36 +6,36 @@ import { inspectInstallation, installOpenCode } from '../src/install-opencode.js
 import { inspectToolchain, installToolchain, loadToolchain } from '../src/toolchain.js';
 import fs from 'node:fs';
 import { inspectVSCodeInstallation, installVSCode } from '../src/install-vscode.js';
-const help = `Install this package's skills and agents into OpenCode or DevEco Code.
-
-Usage: d2h [options]
-
-  d2h install         Install compatible CLIs and agent/skill definitions
-  d2h upgrade         Reapply this package's tested toolchain and definitions
-  d2h upgrade --check Preview version and installation status only
-  d2h doctor [--agent opencode|deveco|vscode] [--config-dir <path>]
-                      Check definitions, host environment and CLI capabilities
-
-  --check-env         Check host tools and write reports without installing skills
-                       Example: d2h --check-env --output-dir ./environment-report
-                       Use d2h --check-env --help for check options
-
-  --source-dir <path>  Source root (defaults to this package)
-  --agent <name>       opencode (default), deveco or vscode
-  --extension-dir <path>  VS Code HarmonyOS Dev Assistant extension root
-  --config-dir <path>  Override the selected agent's config root
-                       OPENCODE_CONFIG_DIR / DEVECO_CONFIG_DIR, or
-                       $XDG_CONFIG_HOME/<agent>, or ~/.config/<agent>
-  --link              Create absolute symbolic links (development only)
-  --force             Replace conflicting definitions and managed CLI npm links
-  --remote            Use opencode-metrics-plugin instead of the default lite plugin
-  --dry-run           Print operations without writing files
-  --skip-tools        Install definitions only (local development)
-  -h, --help          Show this help
-
-Managed AppGraph and droid2hmos CLIs plus skills/*/SKILL.md trees and agents/*.md are installed.
-Existing application configuration and AGENTS.md are not modified.
-With npx, prefer the default copy mode: its cache can be removed.
+const help = `Install this package's skills and agents into OpenCode or DevEco Code.
+
+Usage: d2h [options]
+
+  d2h install         Install compatible CLIs and agent/skill definitions
+  d2h upgrade         Reapply this package's tested toolchain and definitions
+  d2h upgrade --check Preview version and installation status only
+  d2h doctor [--agent opencode|deveco|vscode] [--config-dir <path>]
+                      Check definitions, host environment and CLI capabilities
+
+  --check-env         Check host tools and write reports without installing skills
+                       Example: d2h --check-env --output-dir ./environment-report
+                       Use d2h --check-env --help for check options
+
+  --source-dir <path>  Source root (defaults to this package)
+  --agent <name>       opencode (default), deveco or vscode
+  --extension-dir <path>  VS Code HarmonyOS Dev Assistant extension root
+  --config-dir <path>  Override the selected agent's config root
+                       OPENCODE_CONFIG_DIR / DEVECO_CONFIG_DIR, or
+                       $XDG_CONFIG_HOME/<agent>, or ~/.config/<agent>
+  --link              Create absolute symbolic links (development only)
+  --force             Replace conflicting definitions and managed CLI npm links
+  --remote            Use opencode-metrics-plugin instead of the default lite plugin
+  --dry-run           Print operations without writing files
+  --skip-tools        Install definitions only (local development)
+  -h, --help          Show this help
+
+Managed AppGraph and droid2hmos CLIs plus skills/*/SKILL.md trees and agents/*.md are installed.
+Existing application configuration and AGENTS.md are not modified.
+With npx, prefer the default copy mode: its cache can be removed.
 `;
 try {
     const args = process.argv.slice(2);

package/docs/environment-check.md

@@ -1,86 +1,86 @@
-# 迁移工具环境检查
-
-先手动安装 Node.js 22.5–24.x，确认 `node --version`。脚本只使用 Node 内置模块，无需 npm install，支持 Windows/macOS/Linux。
-
-npx 集成入口（包含本次更新的包发布后可用）：
-
-```sh
-npx --yes @harmonyos-arkts/d2h@0.1.5 --check-env --output-dir ./environment-report
-```
-
-本地构建后：`node dist/bin/install-opencode.js --check-env`。检查参数在 --check-env 后传入；使用 --check-env --help 查看。检查模式不执行 Agent/Skill 安装；不能与 --force、--agent、--config-dir 等安装参数混用，误用时返回参数错误。npx 自身可能下载并缓存 npm 包。
-
-```powershell
-node scripts/check-environment.mjs --output-dir D:/reports/hmos-environment
-```
-
-```sh
-node scripts/check-environment.mjs --output-dir ~/reports/hmos-environment
-```
-
-## 当前检查项
-
-| 项目 | 条件 |
-| --- | --- |
-| Node.js | 当前运行时为 24.x |
-| Git | git --version 成功 |
-| npm | npm --version 成功 |
-| Java/JDK | java -version 成功，不固定 JDK 主版本 |
-| Python | 找到 Python 3.10+，优先 PYTHON_BINARY |
-| AppGraph | appgraph --version 成功且匹配 D2H 锁定的 0.0.10 |
-| droid2hmos | droid2hmos --version 成功且匹配 D2H 锁定的 0.0.11 |
-| DevEco 工具链目录 | 安装目录存在 |
-| Hvigor | 版本命令成功 |
-| ohpm | 版本命令成功 |
-| DevEco CLI | devecocli --version 成功 |
-| 开发者账号 | DevEco CLI 登录状态成功，报告不保留账号输出 |
-| HarmonyOS SDK 目录 | 辅助诊断，不作为必需门禁 |
-
-按需检查：指定插件生产脚本导入 json5 时检查相同 Python 的 json5 模块；传入 --android-project 时检查源码 Gradle 配置标记；传入 --harmony-project 时枚举工程可用 SDK 版本。
-
-SQLite/WASM 随 Node 提供，不单独检测。Android SDK/ADB/模拟器/构建、CLI capability/help、Agent 宿主、插件安装/启用/引用、所有设备发现和 Shell 检查均不执行。
-
-## 参数
-
-兼容组合以 `skills/managing-d2h-toolchain/toolchain.json` 为准；`skills/managing-d2h-toolchain/environment-requirements.json` 提供检查器的版本边界，构建检查确保 Node、AppGraph 与 droid2hmos 约束与兼容组合一致。默认 Node 为 `>=22.5.0 <25.0.0`，Python 为 `>=3.10.0`；其余未锁定的工具仅检查可用性。
-
-每项可配置 `minimum`（含下界）和 `maximumExclusive`（不含上界），支持 1–4 段纯数字版本，不能使用 latest、通配符、^ 或 ~。例如将 appgraph 改为 `{ "minimum": "0.0.8" }`，即可检测最低版本。保留全部工具键，无版本要求时使用 null。未知工具、无效边界或空区间会报错，不静默放宽约束。
-
-可使用自定义文件：
-
-```sh
-npx --yes @harmonyos-arkts/d2h@0.1.5 --check-env --requirements ./environment-requirements.json
-```
-
-报告记录实际配置路径和约束；版本不符合时，命令行显示当前版本、要求和修复指导。此配置仅控制诊断命令，不修改 npm 包自身 engines 或 droid2hmos 的 preflight 规则。
-
-- --plugin-root：用于判断插件生产 Python 脚本是否需要 json5，默认当前脚本所在仓库。
-- --requirements：覆盖默认版本配置文件路径。
-- --android-project：Android 源码目录，仅检查配置标记，不要求 Gradle Wrapper。
-- --harmony-project：在该工程执行 DevEco CLI 的只读 SDK 版本枚举。
-- --sdk-path：声明 SDK 根目录。
-- --timeout：每条命令超时秒数，1–60，默认 15。
-- --output-dir：报告目录，默认当前目录的 environment-report。
-- --help：使用说明。
-
-不再提供 --host、--host-binary、--skip-devices 参数。
-
-工具环境变量：DEVECO_STUDIO_HOME、DEVECO_HOME、DROID2HMOS_HVIGOR、DROID2HMOS_OHPM、DEVECO_CLI_BINARY、PYTHON_BINARY、HARMONYOS_SDK_HOME、OHOS_SDK_HOME、DEVECO_SDK_HOME。macOS 包含 DevEco 默认 Contents 目录和常见 Python 安装路径。
-
-## 输出
-
-命令行先显示总体结果，然后逐项显示 `[通过]`、`[未通过]`、`[提醒]` 或 `[未检查]` 及版本/原因。未通过、提醒和未检查项下方直接显示修复指导，最后显示报告路径。完整明细、证据和修复指导保存在 environment.md/environment.json，重复执行覆盖。脚本只提供指导，不自动安装或修改环境。
-
-退出码：0=必需检查通过；1=必需失败或执行错误；2=必需项未检查或参数错误。SDK 辅助诊断 warning 不阻断通过。
-
-本报告仅确认上述主机依赖，不代表 CLI 分析能力、Agent 安装、项目构建、签名、SDK API 匹配、设备运行或端到端验收已通过。后续项目门禁仍由 droid2hmos preflight/test/device/complete 负责。脚本不自动安装、登录、构建或修改配置；被调用工具自身可能写缓存。
-
-## 源码依据
-
-2026-10-13 复核：AppGraph origin/dev c1d2ed1（仓库版本 0.0.8）、droid2hmos dev 0caabce（仓库版本 0.0.7）、插件 origin/skill 4a21758（仓库版本 0.1.3）。此前发现的插件 Agent 命名差异不属于当前环境检查范围。
-
-测试：
-
-```sh
-node --test --test-concurrency=1 scripts/tests/environment.test.mjs
-```
+# 迁移工具环境检查
+
+先手动安装 Node.js 22.5–24.x，确认 `node --version`。脚本只使用 Node 内置模块，无需 npm install，支持 Windows/macOS/Linux。
+
+npx 集成入口（包含本次更新的包发布后可用）：
+
+```sh
+npx --yes @harmonyos-arkts/d2h@0.1.5 --check-env --output-dir ./environment-report
+```
+
+本地构建后：`node dist/bin/install-opencode.js --check-env`。检查参数在 --check-env 后传入；使用 --check-env --help 查看。检查模式不执行 Agent/Skill 安装；不能与 --force、--agent、--config-dir 等安装参数混用，误用时返回参数错误。npx 自身可能下载并缓存 npm 包。
+
+```powershell
+node scripts/check-environment.mjs --output-dir D:/reports/hmos-environment
+```
+
+```sh
+node scripts/check-environment.mjs --output-dir ~/reports/hmos-environment
+```
+
+## 当前检查项
+
+| 项目 | 条件 |
+| --- | --- |
+| Node.js | 当前运行时为 24.x |
+| Git | git --version 成功 |
+| npm | npm --version 成功 |
+| Java/JDK | java -version 成功，不固定 JDK 主版本 |
+| Python | 找到 Python 3.10+，优先 PYTHON_BINARY |
+| AppGraph | appgraph --version 成功且匹配 D2H 锁定的 0.0.10 |
+| droid2hmos | droid2hmos --version 成功且匹配 D2H 锁定的 0.0.11 |
+| DevEco 工具链目录 | 安装目录存在 |
+| Hvigor | 版本命令成功 |
+| ohpm | 版本命令成功 |
+| DevEco CLI | devecocli --version 成功 |
+| 开发者账号 | DevEco CLI 登录状态成功，报告不保留账号输出 |
+| HarmonyOS SDK 目录 | 辅助诊断，不作为必需门禁 |
+
+按需检查：指定插件生产脚本导入 json5 时检查相同 Python 的 json5 模块；传入 --android-project 时检查源码 Gradle 配置标记；传入 --harmony-project 时枚举工程可用 SDK 版本。
+
+SQLite/WASM 随 Node 提供，不单独检测。Android SDK/ADB/模拟器/构建、CLI capability/help、Agent 宿主、插件安装/启用/引用、所有设备发现和 Shell 检查均不执行。
+
+## 参数
+
+兼容组合以 `skills/managing-d2h-toolchain/toolchain.json` 为准；`skills/managing-d2h-toolchain/environment-requirements.json` 提供检查器的版本边界，构建检查确保 Node、AppGraph 与 droid2hmos 约束与兼容组合一致。默认 Node 为 `>=22.5.0 <25.0.0`，Python 为 `>=3.10.0`；其余未锁定的工具仅检查可用性。
+
+每项可配置 `minimum`（含下界）和 `maximumExclusive`（不含上界），支持 1–4 段纯数字版本，不能使用 latest、通配符、^ 或 ~。例如将 appgraph 改为 `{ "minimum": "0.0.8" }`，即可检测最低版本。保留全部工具键，无版本要求时使用 null。未知工具、无效边界或空区间会报错，不静默放宽约束。
+
+可使用自定义文件：
+
+```sh
+npx --yes @harmonyos-arkts/d2h@0.1.5 --check-env --requirements ./environment-requirements.json
+```
+
+报告记录实际配置路径和约束；版本不符合时，命令行显示当前版本、要求和修复指导。此配置仅控制诊断命令，不修改 npm 包自身 engines 或 droid2hmos 的 preflight 规则。
+
+- --plugin-root：用于判断插件生产 Python 脚本是否需要 json5，默认当前脚本所在仓库。
+- --requirements：覆盖默认版本配置文件路径。
+- --android-project：Android 源码目录，仅检查配置标记，不要求 Gradle Wrapper。
+- --harmony-project：在该工程执行 DevEco CLI 的只读 SDK 版本枚举。
+- --sdk-path：声明 SDK 根目录。
+- --timeout：每条命令超时秒数，1–60，默认 15。
+- --output-dir：报告目录，默认当前目录的 environment-report。
+- --help：使用说明。
+
+不再提供 --host、--host-binary、--skip-devices 参数。
+
+工具环境变量：DEVECO_STUDIO_HOME、DEVECO_HOME、DROID2HMOS_HVIGOR、DROID2HMOS_OHPM、DEVECO_CLI_BINARY、PYTHON_BINARY、HARMONYOS_SDK_HOME、OHOS_SDK_HOME、DEVECO_SDK_HOME。macOS 包含 DevEco 默认 Contents 目录和常见 Python 安装路径。
+
+## 输出
+
+命令行先显示总体结果，然后逐项显示 `[通过]`、`[未通过]`、`[提醒]` 或 `[未检查]` 及版本/原因。未通过、提醒和未检查项下方直接显示修复指导，最后显示报告路径。完整明细、证据和修复指导保存在 environment.md/environment.json，重复执行覆盖。脚本只提供指导，不自动安装或修改环境。
+
+退出码：0=必需检查通过；1=必需失败或执行错误；2=必需项未检查或参数错误。SDK 辅助诊断 warning 不阻断通过。
+
+本报告仅确认上述主机依赖，不代表 CLI 分析能力、Agent 安装、项目构建、签名、SDK API 匹配、设备运行或端到端验收已通过。后续项目门禁仍由 droid2hmos preflight/test/device/complete 负责。脚本不自动安装、登录、构建或修改配置；被调用工具自身可能写缓存。
+
+## 源码依据
+
+2026-10-13 复核：AppGraph origin/dev c1d2ed1（仓库版本 0.0.8）、droid2hmos dev 0caabce（仓库版本 0.0.7）、插件 origin/skill 4a21758（仓库版本 0.1.3）。此前发现的插件 Agent 命名差异不属于当前环境检查范围。
+
+测试：
+
+```sh
+node --test --test-concurrency=1 scripts/tests/environment.test.mjs
+```