@harmonyos-arkts/d2h 0.1.15 → 0.1.17

package/.claude-plugin/plugin.json

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

package/AGENTS.md

@@ -1,5 +1,5 @@
 # Android to HarmonyOS Migration
 
-处理迁移请求时，由当前正式主 Agent `agents/d2h_v2.md` 统一编排专项 Skill。`agents/android-to-hmos-00-orchestrator.md` 和 `agents/d2h.md` 仅保留旧名称兼容，不是规则真源。
+处理迁移请求时，由当前正式主 Agent `agents/d2h.md` 统一编排专项 Skill。`agents/android-to-hmos-00-orchestrator.md`仅保留旧名称兼容，不是规则真源。
 
 以真实 HarmonyOS 应用质量为目标，以 AppGraph facts 和迁移报告降低遗漏风险。不要恢复已废弃的旧 SPEC/PLAN/TASK 多 Agent 文档流程或静态转译器；当前使用的 Kernel Task Plan（`droid2hmos task plan/validate/next/show` 派生计划）属于 Migration Kernel 协议，不在此列。

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

@@ -72,6 +72,7 @@ description: Android 应用到 HarmonyOS 的结果驱动迁移主 Agent，以完
 
 - 图片/图形资源转换 skill：`android2hmos_resources_convert`（res/ 图片资产 → `media/`、XML drawable → SVG、自适应图标 → layered-image）。需要 Preflight 已创建或复用的 HarmonyOS 工程
 - 安卓/鸿蒙三方库映射关系 skill：`native-library-substitution`
+- 云侧权威知识查询 skill：`d2h-cloud-knowledge`。当当前实现的功能涉及不确定的 @kit.* Kit / @ohos.* 模块 API、ArkUI 组件行为或平台能力（相机/定位/文件/通知/蓝牙/分享/Web/后台任务等）、构建或测试失败指向 API 签名与行为、或需核验已选型 ohpm 库用法时加载。先查 `.migration/knowledge/kb_cache.json` 缓存，命中不重查；结论以文档 `title`/`uri` 引用回 spec 与迁移报告。本地文档、`harmonyos-migration-playbook` 已验证经验或其他专项 skill 能解决时不加载。
 
 Skill 是当前工作的操作说明，不替代本 Agent 的目标、判断和持续执行责任。读取一个 Skill 后只使用与当前阶段直接相关的内容。
 
@@ -109,7 +110,8 @@ Skill 是当前工作的操作说明，不替代本 Agent 的目标、判断和
    - App 名称、图标、版本号、包名等身份信息迁移 → `arkts-app-identity`；
    - 用户可见文案与多语言资源迁移 → `arkts-i18n`；
    - 图标/图片尺寸失真校准 → `arkts-icon-sizing`；
-   - Android 三方库依赖的鸿蒙替代映射 → `native-library-substitution`。
+   - Android 三方库依赖的鸿蒙替代映射 → `native-library-substitution`；
+   - 平台能力实现、不确定的 @kit.* Kit / @ohos.* 模块 API、ArkUI 组件行为，或构建/测试失败分诊需核对 API 权威签名、权限、错误码 → `d2h-cloud-knowledge`（先查 `.migration/knowledge/kb_cache.json`，结论回写缓存并在 spec/报告引用文档 uri）。
 7. 小步运行构建和应用验证，按以下分组规则建立与使用测试：
 
    **测试政策**

package/agents/d2h.md

@@ -1,6 +1,6 @@
 ---
 name: d2h
-description: Android 应用到 HarmonyOS 的 AI 驱动迁移主 Agent；按迁移场景加载专项 Skill，完成页面规划、逐页开发、受管验证和最终交付闭环。
+description: Android 应用到 HarmonyOS 的 AI 驱动迁移主 Agent；按迁移场景加载专项 Skill，完成页面规划、逐页开发、Forge 测试验收和最终交付闭环。
 ---
 
 # Android to HarmonyOS Migration Agent
@@ -11,16 +11,16 @@ description: Android 应用到 HarmonyOS 的 AI 驱动迁移主 Agent；按迁
 
 必须覆盖所有页面、可见控件和状态、导航与 Dialog 流程、业务功能，以及影响行为的资源和配置。Android 源码与真实运行行为决定“做什么”，HarmonyOS 原生机制决定“怎么做”。无法等价的差异必须明确记录，不能静默省略或伪装成完成。
 
-迁移由 AI 读取 Facts、`.migration/utg/page.json`、Android 源码、HarmonyOS 代码、迁移报告和受管执行证据后作出决策。禁止使用 Migration Kernel 的任务规划子命令或静态任务脚本代替 AI 进行页面拆分、任务选择和开发调度。
+迁移由 AI 读取 Facts、`.migration/utg/page.json`、页面 Spec、`batch_report.md`、Android 源码、HarmonyOS 代码和实际测试结果后作出决策。禁止使用 Migration Kernel 的任务规划子命令或静态任务脚本代替 AI 进行页面拆分、任务选择和开发调度。
 
 ## 产物边界
 
-- `.migration/spec/` 中的 Facts 是 AppGraph 从 Android 源码确定性提取的结构化事实基线，用于范围发现、实体与交互关联、报告初始化和遗漏检查。Facts 可能包含 unresolved 项或存在抽取遗漏，不能替代对 Android 源码及必要运行行为的阅读核验。
+- `.migration/spec/` 中的 Facts 是 AppGraph 从 Android 源码确定性提取的结构化事实基线，用于范围发现、实体与交互关联、源码定位和遗漏检查。Facts 可能包含 unresolved 项或存在抽取遗漏，不能替代对 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、测试文件和状态字段都是辅助证据，不是应用实现本身。只存在于文档、注释、桩代码或不可达文件中的能力均视为未完成。
+- `.migration/page-specs/batch_report.md` 是页面进度、实现与证据引用、差异和最终回归结论的统一账本。初始账本由 `d2h-page-spec-generate` 使用 `build_batch_report.py` 从 `pages.json` 生成；开发开始后由 AI 原位维护，不得重新生成并覆盖历史。
+- Spec、账本、测试文件和状态字段都是辅助证据，不是应用实现本身。只存在于文档、注释、桩代码或不可达文件中的能力均视为未完成。
 
 ## 场景与 Skill 路由
 
@@ -31,7 +31,6 @@ description: Android 应用到 HarmonyOS 的 AI 驱动迁移主 Agent；按迁
 | 开始或恢复迁移，定位工程、准备工具链、读取状态、执行 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` |
@@ -41,10 +40,15 @@ description: Android 应用到 HarmonyOS 的 AI 驱动迁移主 Agent；按迁
 | 转换 Android 图片、XML drawable 和自适应图标 | `android2hmos_resources_convert` |
 | 修复 HarmonyOS 图片或图标尺寸、比例失真 | `arkts-icon-sizing` |
 | 诊断 ArkTS 构建、运行时、UI 自动化或迁移验证故障 | `harmonyos-migration-playbook` |
+| 实现涉及不确定的 @kit.* Kit / @ohos.* 模块 API、ArkUI 组件行为或平台能力（相机/定位/文件/通知/蓝牙/分享/Web/后台任务等），构建/测试失败需核对 API 签名、权限、错误码，或核验已选型 ohpm 库用法 | `d2h-cloud-knowledge` |
 | 迁移完整结束或本次运行明确中止后复盘流程 | `reviewing-migration-process` |
 | 首次安装、工具缺失、版本/能力不符或主动升级 | `managing-d2h-toolchain` |
 
-若一个步骤同时命中多个场景，加载最小必要 Skill 组合。例如页面开发时由 `d2h-page-develop` 主导；涉及 ArkTS 实现时加载 `arkts-mvvm-architecture`，进入测试阶段时加载 `d2h-hypium-forge`，需要写迁移证据时加载 `maintaining-migration-report`。专项 Skill 的领域结果不能单独证明页面或整次迁移完成。
+若一个步骤同时命中多个场景，加载最小必要 Skill 组合。例如页面开发时由 `d2h-page-develop` 主导；涉及 ArkTS 实现时加载 `arkts-mvvm-architecture`，进入测试阶段时加载 `d2h-hypium-forge`。实现和测试证据由主 Agent 直接记录到 `batch_report.md`。专项 Skill 的领域结果不能单独证明页面或整次迁移完成。
+
+本流程的测试执行统一由 `d2h-hypium-forge` 负责，`batch_report.md` 记录其实际结果和证据路径，主 Agent 对照 Spec 和设备行为决定验收。
+
+加载 `d2h-cloud-knowledge` 时先查 `.migration/knowledge/kb_cache.json` 缓存，命中不重查；结论以文档 `title`/`uri` 引用回页面 Spec 与 `batch_report.md`。本地文档、`harmonyos-migration-playbook` 已验证经验或其他专项 Skill 能解决时不加载该 Skill。
 
 ## 迁移流程
 
@@ -56,12 +60,11 @@ description: Android 应用到 HarmonyOS 的 AI 驱动迁移主 Agent；按迁
 
 设备暂不可用时可以继续静态分析、页面规划和不依赖设备的实现，但交互页面不能标记为验证通过，也不能进入最终完成门禁。
 
-### 二、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 未覆盖、但源码中真实存在的行为仍须纳入迁移范围。
+3. Facts 或 UTG 未覆盖、但源码中真实存在的行为仍须纳入页面 Spec，并在 `batch_report.md` 中记录发现与处理情况。
 
 ### 三、HarmonyOS 工程与公共能力
 
@@ -85,22 +88,24 @@ description: Android 应用到 HarmonyOS 的 AI 驱动迁移主 Agent；按迁
 
 ### 五、逐页代码串行开发
 
-加载 `d2h-page-develop`，由当前主 Agent 以严格串行方式执行页面开发。任意时刻最多只能有一个页面处于开发或修复状态，页面实现、构建、测试、报告、提交和账本更新不得委派给独立 worker 或其他子 Agent：
+加载 `d2h-page-develop`，以严格串行方式执行页面开发。任意时刻最多只能有一个页面处于开发或修复状态，禁止并行开发多个页面，也禁止一次向 worker 派发多个页面：
 
 1. 主 Agent 按 `batch_report.md` 选择顺序最前且未达到 `implemented/passed/passed` 的页面。
-2. 主 Agent 只处理当前一个页面，不得领取、预研或修改后续页面，并负责执行 `d2h-page-develop` 定义的完整单页闭环。
-3. 进入测试阶段时加载 `d2h-hypium-forge`，生成或更新该页面的 Python Hypium 测试资产，并通过 `droid2hmos` 受管入口执行定向测试。
-4. 页面实现与测试通过后加载 `maintaining-migration-report`，记录真实实现文件、Android 源码依据和本次受管证据。
+2. 只派发一个独立 page-worker，且该 worker 只负责当前一个页面。worker 必须加载 `d2h-page-develop`，不得领取、预研或修改后续页面。
+3. 进入测试阶段时加载 `d2h-hypium-forge`，生成或更新该页面的 Python Hypium 测试资产。先确认本次构建的 HAP 已安装到目标设备，再按该 Skill 执行当前页面及受影响功能的定向测试，保留实际结果、日志和必要截图。主 Agent 核对执行用例及其断言是否覆盖 Spec 功能项，不能仅凭进程退出码或汇总文案判定通过。
+4. 页面实现与测试通过后，在 `batch_report.md` 当前页面明细中记录真实实现文件、Android 源码依据、本次构建与 Forge 测试的实际结果及证据路径，以及差异或阻塞。未产出或未保存的结果、日志如实记录为缺失，不得填写假定存在的路径或据此标记通过。
 5. 主 Agent 完成当前页面的实现提交，原位更新 `batch_report.md`，并按 Skill 的页面完成清单复核实现、构建、测试、证据、提交和工作区状态。
-6. 当前页面未闭环、仍有页面所属未提交修改或复核失败时，只能继续修复当前页面。当前页面完整闭环并通过复核后，才能按顺序选择下一页。
+6. 前页面未闭环、仍有页面所属未提交修改或复核失败时，只能继续修复当前页面。当前页面完整闭环并通过主 Agent 复核后，才能按顺序选择并派发下一页。
+
+若当前环境不支持独立 page-worker，必须明确报告该开发模式无法执行，不能静默改成主 Agent 批量开发。
 
 ### 六、批次回归与最终门禁
 
 全部页面达到 `implemented/passed/passed` 后：
 
-1. 按 `d2h-page-develop` 的批次回归规则，显式枚举全部 Python Hypium test list，通过受管 runner 执行批次回归。Python runner 不使用 `--all`。
+1. 加载 `d2h-hypium-forge`，在已安装当前 HAP 的目标设备上执行覆盖全部迁移范围内功能场景的完整 Python Hypium 回归，保留本次实际执行结果和日志。核对用例范围、执行数和各项状态；零执行、失败、错误或必测场景被跳过、未执行时均不能通过，历史 PASS 不能替代本次完整回归。
 2. 需要诊断 UI 自动化、构建或运行故障时加载 `harmonyos-migration-playbook`；失败必须回到对应页面修复，不能降低验收标准。
-3. 更新并校验迁移报告及 final acceptance。
+3. 主 Agent 对照各页 Spec、源码、实际实现和设备结果完成行为审查，将结论、被测 HAP 与设备、完整回归结果和实际证据路径、差异及未解决问题记录到 `batch_report.md` 的批次回归部分。直接核对账本队列、页面明细、汇总和引用证据的一致性，满足完成条件后才能宣布迁移完成。
 4. 完整结束或明确中止后加载 `reviewing-migration-process` 生成流程复盘；复盘不是完成条件。
 
 ## 持续执行与人工介入
@@ -119,14 +124,14 @@ description: Android 应用到 HarmonyOS 的 AI 驱动迁移主 Agent；按迁
 
 以下任一情况都视为未完成：
 
-- 报告、Spec 或账本写着完成，但实现只有注释、空函数、固定值或桩数据。
+- Spec 或账本写着完成，但实现只有注释、空函数、固定值或桩数据。
 - 页面文件存在，但不能从真实 Ability、导航或 Android 对应控件到达。
 - 为通过测试新增替代控件，而 Android 对应控件仍无正确行为。
 - 只证明编译、安装、启动、不白屏或截图相似，没有验证交互与业务结果。
 - 只覆盖 Facts 或 UTG，忽略源码或运行时中真实存在的页面、入口和业务逻辑。
 - 测试只写未跑，或使用旧证据、无关 refs、空执行结果冒充通过。
 - 使用坐标点击替代可语义定位控件的正式 Hypium 验收。
-- 把实现缺陷包装成外部 blocker，或用报告说明代替修复。
+- 把实现缺陷包装成外部 blocker，或用账本说明代替修复。
 - 静态脚本、清单或状态字段宣称通过，但 AI 尚未核对真实源码、代码路径和设备结果。
 
 判断原则始终是：用户在 HarmonyOS 应用中实际看到、操作和获得的结果是否与 Android 一致。
@@ -135,15 +140,16 @@ description: Android 应用到 HarmonyOS 的 AI 驱动迁移主 Agent；按迁
 
 只有同时满足以下条件，才允许宣布迁移完成：
 
-- Preflight、Facts、UTG、迁移报告和证据对应当前源码。
+- Preflight、Facts、UTG、页面 Spec、`batch_report.md` 和证据对应当前源码。
 - `pages.json` 覆盖全部已知页面或明确记录排除原因。
 - 每个已知页面、Dialog、Sheet 和关键模式都有唯一 `spec.md`，页面包中没有额外产物。
 - `batch_report.md` 覆盖全部页面，且所有任务均为 `implemented/passed/passed`，没有未解决阻塞。
-- 所有 Spec 功能项都有真实、可达的 HarmonyOS 实现和当前受管测试证据。
-- HarmonyOS 工程构建、安装、启动成功；全部 Python Hypium test list 的批次回归通过。
+- 所有 Spec 功能项都有真实、可达的 HarmonyOS 实现。
+- HarmonyOS 工程构建、安装、启动成功；当前 HAP 的 Forge 完整回归通过，没有失败、错误或必测场景未执行。
+- `batch_report.md` 已记录最终行为审查、完整回归结论及实际证据路径，队列、页面明细和汇总一致。
 - 所有页面、可见控件、状态、导航、Dialog、业务功能、数据效果和错误路径均真实实现。
 - Facts 或 UTG 遗漏、但经源码或运行时发现的行为也已实现并验证。
 - 无法等价的差异已经明确呈现，没有被静默标记为完成。
 - 每个页面实现都有可恢复提交，用户已有和无关改动未被覆盖。
 
-完成报告不等于完成迁移；机器门禁成功也不能替代对真实用户可观察结果的 AI 审查。
+账本状态、编译成功或测试汇总都不能替代对真实用户可观察结果的 AI 审查。

package/docs/environment-check.md

@@ -20,21 +20,38 @@ node scripts/check-environment.mjs --output-dir ~/reports/hmos-environment
 
 ## 当前检查项
 
+检查结果分为运行环境、鸿蒙工具链和迁移场景依赖三组。JSON 中保留原有检查 ID，并为每项增加 `category`；DevEco 项还记录安装类型、安装根目录和识别来源。
+
+### 运行环境
+
 | 项目 | 条件 |
 | --- | --- |
-| Node.js | 当前运行时为 24.x |
+| Node.js | 当前运行时满足配置的版本范围 |
 | Git | git --version 成功 |
 | npm | npm --version 成功 |
-| Java/JDK | java -version 成功，不固定 JDK 主版本 |
 | Python | 找到 Python 3.10+，优先 PYTHON_BINARY |
-| AppGraph | appgraph --version 成功且匹配 D2H 锁定的 0.0.11 |
-| droid2hmos | droid2hmos --version 成功且匹配 D2H 锁定的 0.0.12 |
-| DevEco 工具链目录 | 安装目录存在 |
+
+### 鸿蒙工具链
+
+DevEco Studio 或 HarmonyOS Command Line Tools 任一存在，即认为 DevEco 父项已安装。报告会区分 `studio`、`command-line-tools`、`studio-and-command-line-tools` 和 `missing`，并继续显示可用子工具的版本。
+
+| 项目 | 条件 |
+| --- | --- |
+| DevEco 工具链 | DevEco Studio 或 HarmonyOS Command Line Tools 安装目录存在 |
+| Java/JDK | 优先 JAVA_HOME 和 PATH，再检查 DevEco 内置 JBR/JDK；java -version 成功 |
 | Hvigor | 版本命令成功 |
 | ohpm | 版本命令成功 |
-| DevEco CLI | devecocli --version 成功 |
-| 开发者账号 | DevEco CLI 登录状态成功，报告不保留账号输出 |
 | HarmonyOS SDK 目录 | 辅助诊断，不作为必需门禁 |
+| DevEco CLI | devecocli --version 成功 |
+| 开发者账号 | DevEco CLI 登录状态成功；CLI 缺失时跳过，报告不保留账号输出 |
+
+### 迁移场景依赖
+
+| 项目 | 条件 |
+| --- | --- |
+| AppGraph | appgraph --version 成功且匹配 D2H 锁定的 0.0.11 |
+| droid2hmos | droid2hmos --version 成功且匹配 D2H 锁定的 0.0.12 |
+| Android 源码根目录 | 传入 --android-project 时包含 Gradle 配置标记 |
 
 按需检查：指定插件生产脚本导入 json5 时检查相同 Python 的 json5 模块；传入 --android-project 时检查源码 Gradle 配置标记；传入 --harmony-project 时枚举工程可用 SDK 版本。
 
@@ -65,11 +82,11 @@ npx --yes @harmonyos-arkts/d2h@0.1.5 --check-env --requirements ./environment-re
 
 不再提供 --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 安装路径。
+工具环境变量：DEVECO_STUDIO_HOME、DEVECO_HOME、JAVA_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，重复执行覆盖。脚本只提供指导，不自动安装或修改环境。
+命令行先显示总体结果，再按“运行环境”“鸿蒙工具链”“迁移场景依赖”分组显示 `[通过]`、`[未通过]`、`[提醒]` 或 `[未检查]` 及版本/原因。未通过、提醒和未检查项下方直接显示修复指导，最后显示报告路径。完整明细、证据、分类、DevEco 安装信息和修复指导保存在 environment.md/environment.json，重复执行覆盖。脚本只提供指导，不自动安装或修改环境。
 
 退出码：0=必需检查通过；1=必需失败或执行错误；2=必需项未检查或参数错误。SDK 辅助诊断 warning 不阻断通过。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harmonyos-arkts/d2h",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "Install Android-to-HarmonyOS migration agents and skills into OpenCode or DevEco Code",
   "type": "module",
   "bin": {

package/scripts/check-environment.mjs

@@ -8,6 +8,18 @@ import { parseArgs } from 'node:util';
 
 const DEFAULT_REQUIREMENTS = fileURLToPath(new URL('../skills/managing-d2h-toolchain/environment-requirements.json', import.meta.url));
 const VERSION_TOOLS = ['node', 'python', 'git', 'npm', 'java', 'python-json5', 'appgraph', 'droid2hmos', 'hvigor', 'ohpm', 'devecocli'];
+const CATEGORY_LABELS = {
+  runtime: '运行环境',
+  'harmony-toolchain': '鸿蒙工具链',
+  'migration-capabilities': '迁移场景依赖',
+};
+const CHECK_CATEGORIES = {
+  node: 'runtime', npm: 'runtime', git: 'runtime', python: 'runtime', 'python-json5': 'runtime',
+  deveco: 'harmony-toolchain', java: 'harmony-toolchain', hvigor: 'harmony-toolchain', ohpm: 'harmony-toolchain',
+  'harmony-sdk-location': 'harmony-toolchain', 'harmony-sdk-compatibility': 'harmony-toolchain',
+  devecocli: 'harmony-toolchain', 'devecocli-auth': 'harmony-toolchain',
+  appgraph: 'migration-capabilities', droid2hmos: 'migration-capabilities', 'android-source-root': 'migration-capabilities',
+};
 
 function versionParts(value) {
   if (typeof value !== 'string' || !/^\d+(?:\.\d+){0,3}$/.test(value)) throw new Error(`无效版本：${value}`);
@@ -169,9 +181,27 @@ export function pythonJson5Required(source) {
 }
 
 export function parseDevEcoJson(output) {
-  // DevEco CLI 1.3.3 appends its updater notice to stdout even with --format json.
-  // Strip only that known trailing line; unrelated malformed output still fails.
-  return JSON.parse(output.replace(/\r?\n\s*New version [\w.+-]+ available, run `devecocli update` to upgrade\s*$/, '').trim());
+  // DevEco CLI 会在 --format json 输出前后追加非 JSON 文本（如升级提示
+  // "New version 1.3.5 available, run `devecocli update` to upgrade"，措辞随版本变化）。
+  // 整体解析失败时回退提取最外层 JSON 值再解析；完全不含 JSON 才失败。
+  // 与 droid2hmos src/commands/deveco-cli.ts parseJson 保持同一策略。
+  const trimmed = String(output).trim();
+  try {
+    return JSON.parse(trimmed);
+  } catch (error) {
+    const start = trimmed.search(/[[{]/);
+    if (start >= 0) {
+      const close = trimmed[start] === '[' ? ']' : '}';
+      const end = trimmed.lastIndexOf(close);
+      if (end > start) {
+        try {
+          return JSON.parse(trimmed.slice(start, end + 1));
+        } catch { /* fall through */
+        }
+      }
+    }
+    throw error;
+  }
 }
 
 export async function collect(options, { runner = probe, env = process.env, platform = process.platform, home = os.homedir(), directoryFinder = firstDirectory, nodeVersion = process.version } = {}) {
@@ -179,24 +209,27 @@ export async function collect(options, { runner = probe, env = process.env, plat
   const requirements = loadRequirements(requirementsFile);
   const ruleFor = id => requirements.tools[id];
   const checks = [];
-  const add = (id, required, passed, summary, remediation = '', evidence = [], skipped = false) => {
-    checks.push({ id, required, status: skipped ? 'skipped' : passed ? 'passed' : required ? 'failed' : 'warning', summary,
-      remediation: passed ? '' : remediation, evidence });
+  const add = (id, required, passed, summary, remediation = '', evidence = [], skipped = false, details = {}) => {
+    checks.push({ id, category: CHECK_CATEGORIES[id] || 'migration-capabilities', required,
+      status: skipped ? 'skipped' : passed ? 'passed' : required ? 'failed' : 'warning', summary,
+      remediation: passed ? '' : remediation, evidence, ...details });
   };
   const tool = async (id, executable, params, remediation, predicate = () => true) => {
     const result = await runner(executable, params, options.timeout);
     const rule = ruleFor(id);
     const passed = result.ok && predicate(result.output) && meetsVersionRule(result.output, rule, id);
-    const summary = result.output.split(/\r?\n/)[0] || result.error || '命令未成功';
+    const missing = /(?:ENOENT|not found|无法找到|找不到)/i.test(`${result.error || ''}\n${result.output || ''}`);
+    const summary = missing ? `未找到 ${id}` : result.output.split(/\r?\n/)[0] || result.error || '命令未成功';
+    const version = result.output.match(/\d+\.\d+(?:\.\d+){0,2}/)?.[0];
     add(id, true, passed, `${summary}${rule ? `（要求 ${constraintLabel(rule)}）` : ''}`,
-      `${remediation}${rule ? ` 版本须满足 ${constraintLabel(rule)}。` : ''}`, [result]);
+      `${remediation}${rule ? ` 版本须满足 ${constraintLabel(rule)}。` : ''}`, [result], false,
+      { executable, ...(version ? { version } : {}) });
     return result;
   };
   add('node', true, meetsVersionRule(nodeVersion, ruleFor('node')), `${nodeVersion} (${process.execPath})（要求 ${constraintLabel(ruleFor('node'))}）`,
     `请安装满足 ${constraintLabel(ruleFor('node'))} 的 Node.js，然后重新运行脚本。`);
   await tool('git', 'git', ['--version'], '安装 Git 并将 git 加入 PATH。');
   await tool('npm', 'npm', ['--version'], '使用 Node.js 自带的 npm，检查 PATH。');
-  await tool('java', 'java', ['-version'], '安装项目 Gradle/DevEco 所需 JDK，设置 JAVA_HOME 和 PATH；本检查不限定 JDK 主版本。');
   // Python is a migration dependency, no longer a prerequisite to run this doctor.
   const candidates = [...new Set([env.PYTHON_BINARY, platform === 'win32' ? 'python' : 'python3', 'python',
     platform === 'darwin' ? '/opt/homebrew/bin/python3' : null, platform === 'darwin' ? '/usr/local/bin/python3' : null,
@@ -221,26 +254,66 @@ export async function collect(options, { runner = probe, env = process.env, plat
   for (const name of ['appgraph', 'droid2hmos']) {
     await tool(name, name, ['--version'], '运行 managing-d2h-toolchain Skill 中的 node scripts/manage-toolchain.mjs install 安装精确版本；本地 npm link 需由开发者显式管理。');
   }
-  const deveco = directoryFinder([env.DEVECO_STUDIO_HOME, env.DEVECO_HOME,
+  const studio = directoryFinder([env.DEVECO_STUDIO_HOME,
     platform === 'darwin' ? '/Applications/DevEco-Studio.app/Contents' : null,
     ...(platform === 'win32' ? ['C:/Program Files/Huawei/DevEco Studio', 'D:/Program Files/Huawei/DevEco Studio'] : [])]);
-  add('deveco', true, Boolean(deveco), deveco || '未找到 DevEco Studio', '安装 DevEco Studio，设置 DEVECO_STUDIO_HOME 为安装根目录（macOS 为 Contents）。');
-  for (const [id, variable, relative, fallback] of [
-    ['hvigor', 'DROID2HMOS_HVIGOR', 'tools/hvigor/bin/hvigorw.js', 'hvigorw'],
-    ['ohpm', 'DROID2HMOS_OHPM', 'tools/ohpm/bin/pm-cli.js', 'ohpm'],
-  ]) {
-    const bundled = deveco && path.join(deveco, relative);
-    await tool(id, env[variable] || (isFile(bundled) ? bundled : fallback), ['--version'], `安装 DevEco 配套工具；设置 ${variable} 为可执行文件或 JS 入口路径。`);
+  const commandLineTools = directoryFinder([env.DEVECO_HOME,
+    ...(platform === 'win32' ? ['C:/Huawei/command-line-tools', 'D:/HarmonyOS/command-line-tools'] : [])]);
+  const deveco = studio || commandLineTools;
+  const installationType = studio && commandLineTools ? 'studio-and-command-line-tools' : studio ? 'studio' : commandLineTools ? 'command-line-tools' : 'missing';
+  const installationLabel = { studio: 'DevEco Studio', 'command-line-tools': 'HarmonyOS Command Line Tools',
+    'studio-and-command-line-tools': 'DevEco Studio 和 HarmonyOS Command Line Tools' }[installationType];
+  add('deveco', true, Boolean(deveco), deveco ? `${installationLabel}：${[studio, commandLineTools].filter(Boolean).join('；')}` : '未找到 DevEco Studio 或 HarmonyOS Command Line Tools',
+    '安装 DevEco Studio 或 HarmonyOS Command Line Tools，并设置 DEVECO_STUDIO_HOME 或 DEVECO_HOME（macOS 的 DevEco Studio 根目录为 Contents）。',
+    [], false, { installation: { type: installationType, studioRoot: studio, commandLineToolsRoot: commandLineTools,
+      detectedBy: studio === env.DEVECO_STUDIO_HOME ? 'DEVECO_STUDIO_HOME' : commandLineTools === env.DEVECO_HOME ? 'DEVECO_HOME' : deveco ? 'default-location' : null } });
+  if (deveco) {
+    const javaCandidates = [...new Set([
+      env.JAVA_HOME && path.join(env.JAVA_HOME, 'bin', platform === 'win32' ? 'java.exe' : 'java'),
+      'java',
+      ...[studio, commandLineTools].filter(Boolean).flatMap(root => [
+        path.join(root, 'jbr', 'bin', platform === 'win32' ? 'java.exe' : 'java'),
+        path.join(root, 'jbr', 'Contents', 'Home', 'bin', 'java'),
+      ]).filter(isFile),
+    ].filter(Boolean))];
+    let javaResult = null;
+    let javaExecutable = null;
+    for (const candidate of javaCandidates) {
+      const result = await runner(candidate, ['-version'], options.timeout);
+      if (result.ok && meetsVersionRule(result.output, ruleFor('java'), 'java')) { javaResult = result; javaExecutable = candidate; break; }
+      javaResult ??= result;
+    }
+    const javaRule = ruleFor('java');
+    const javaVersion = javaResult?.output.match(/\d+\.\d+(?:\.\d+){0,2}/)?.[0];
+    add('java', true, Boolean(javaExecutable), javaExecutable ? `${javaResult.output.split(/\r?\n/)[0]} (${javaExecutable})` : '未找到可用的 Java/JDK',
+      `配置 JAVA_HOME，或检查 DevEco 内置 JBR/JDK${javaRule ? `；版本须满足 ${constraintLabel(javaRule)}` : ''}。`, javaResult ? [javaResult] : [], false,
+      { relatedTo: ['deveco', 'hvigor'], ...(javaExecutable ? { executable: javaExecutable } : {}), ...(javaVersion ? { version: javaVersion } : {}) });
+    for (const [id, variable, relative, fallback] of [
+      ['hvigor', 'DROID2HMOS_HVIGOR', 'tools/hvigor/bin/hvigorw.js', 'hvigorw'],
+      ['ohpm', 'DROID2HMOS_OHPM', 'tools/ohpm/bin/pm-cli.js', 'ohpm'],
+    ]) {
+      const bundled = [studio, commandLineTools].filter(Boolean).map(root => path.join(root, relative)).find(isFile);
+      await tool(id, env[variable] || bundled || fallback, ['--version'], `安装 DevEco 配套工具；设置 ${variable} 为可执行文件或 JS 入口路径。`);
+    }
+    const sdk = directoryFinder([options.sdkPath, env.HARMONYOS_SDK_HOME, env.OHOS_SDK_HOME, env.DEVECO_SDK_HOME, path.join(deveco, 'sdk')]);
+    add('harmony-sdk-location', false, Boolean(sdk), sdk || '未发现声明 SDK 根目录', '设置 HARMONYOS_SDK_HOME 或 --sdk-path；实际声明有效性由 droid2hmos preflight 检查。');
+  } else {
+    for (const id of ['java', 'hvigor', 'ohpm', 'harmony-sdk-location']) {
+      add(id, id !== 'harmony-sdk-location', false, '等待鸿蒙基础工具链配置', '', [], true,
+        id === 'java' ? { relatedTo: ['deveco', 'hvigor'] } : {});
+    }
   }
-  const sdk = directoryFinder([options.sdkPath, env.HARMONYOS_SDK_HOME, env.OHOS_SDK_HOME, env.DEVECO_SDK_HOME, deveco && path.join(deveco, 'sdk')]);
-  add('harmony-sdk-location', false, Boolean(sdk), sdk || '未发现声明 SDK 根目录', '设置 HARMONYOS_SDK_HOME 或 --sdk-path；实际声明有效性由 droid2hmos preflight 检查。');
   const cli = env.DEVECO_CLI_BINARY || 'devecocli';
-  await tool('devecocli', cli, ['--version'], '安装 npm install -g @deveco/deveco-cli。');
-  const auth = await runner(cli, ['auth', 'status'], options.timeout);
-  const loggedIn = auth.ok && /Current user:\s*[^\r\n]+/i.test(auth.output) && !/Not logged in/i.test(auth.output);
-  add('devecocli-auth', true, loggedIn, loggedIn ? '已登录' : '未登录或无法确认登录状态',
-    '运行 droid2hmos auth login <android-project>，在浏览器完成授权；不要并发登录。',
-    [{ command: auth.command, exitCode: auth.exitCode, error: auth.error }]);
+  const cliProbe = await tool('devecocli', cli, ['--version'], '安装 npm install -g @deveco/deveco-cli。');
+  if (cliProbe.ok) {
+    const auth = await runner(cli, ['auth', 'status'], options.timeout);
+    const loggedIn = auth.ok && /Current user:\s*[^\r\n]+/i.test(auth.output) && !/Not logged in/i.test(auth.output);
+    add('devecocli-auth', true, loggedIn, loggedIn ? '已登录' : '未登录或无法确认登录状态',
+      '运行 droid2hmos auth login <android-project>，在浏览器完成授权；不要并发登录。',
+      [{ command: auth.command, exitCode: auth.exitCode, error: auth.error }]);
+  } else {
+    add('devecocli-auth', true, false, '未检查：devecocli 不可用', '先安装 devecocli，再重新运行环境检查。', [], true);
+  }
   if (options.harmonyProject) {
     const project = path.resolve(options.harmonyProject);
     const versions = await runner(cli, ['check', 'compat', 'versions', '--format', 'json'], options.timeout, { cwd: project });
@@ -264,9 +337,11 @@ export async function collect(options, { runner = probe, env = process.env, plat
 
 export function markdown(report) {
   const escape = (value) => String(value).replaceAll('|', '\\|').replaceAll('\r', '').replaceAll('\n', '<br>');
-  return ['# Android → HarmonyOS 环境检查', '', `结果：**${report.result}**`, '', report.scope, '', `版本配置：${report.requirementsFile || ''}`, '',
+  const sections = Object.entries(CATEGORY_LABELS).flatMap(([category, label]) => ['', `## ${label}`, '',
     '| 检查 | 必需 | 状态 | 说明 |', '| --- | --- | --- | --- |',
-    ...report.checks.map((c) => `| ${c.id} | ${c.required ? '是' : '否'} | ${c.status} | ${escape(c.summary)} |`),
+    ...report.checks.filter(c => c.category === category).map((c) => `| ${c.id} | ${c.required ? '是' : '否'} | ${c.status} | ${escape(c.summary)} |`)]);
+  return ['# Android → HarmonyOS 环境检查', '', `结果：**${report.result}**`, '', report.scope, '', `版本配置：${report.requirementsFile || ''}`,
+    ...sections,
     '', '## 修复指导', '', ...report.checks.filter((c) => c.remediation).map((c) => `- **${c.id}**：${c.remediation}`), '',
     '修复后重新运行本脚本。主机检查通过后，运行 `droid2hmos preflight <android-project>` 验证真实项目门禁；该命令可能初始化工程并执行构建。', ''].join('\n');
 }
@@ -305,10 +380,13 @@ export async function main(argv = process.argv.slice(2)) {
   const resultLabel = { passed: '通过', failed: '未通过', incomplete: '未完成' }[report.result];
   console.log(`环境检查：${resultLabel}（通过 ${passed}，失败 ${failures.length}${warnings ? `，提醒 ${warnings}` : ''}${skipped ? `，未检查 ${skipped}` : ''}）`);
   const statusLabels = { passed: '通过', failed: '未通过', warning: '提醒', skipped: '未检查' };
-  for (const check of report.checks) {
-    console.log(`[${statusLabels[check.status] || check.status}] ${check.id}：${check.summary}`);
-    if (check.status !== 'passed' && check.remediation) {
-      console.log(`  修复：${check.remediation}`);
+  for (const [category, label] of Object.entries(CATEGORY_LABELS)) {
+    console.log(`\n${label}`);
+    for (const check of report.checks.filter(item => item.category === category)) {
+      console.log(`[${statusLabels[check.status] || check.status}] ${check.id}：${check.summary}`);
+      if (check.status !== 'passed' && check.remediation) {
+        console.log(`  修复：${check.remediation}`);
+      }
     }
   }
   console.log(`详细报告：${path.join(options.outputDir, 'environment.md')}`);

package/skills/d2h-cloud-knowledge/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: d2h-cloud-knowledge
+description: >-
+  D2h 迁移过程中的华为开发者云侧知识库查询技能。在 Android 转 HarmonyOS 迁移的各环节，
+  根据当前正在实现的功能（平台能力、HarmonyOS API（@kit.* Kit 导入或 @ohos.* 模块）、ArkUI 组件行为、
+  三方库用法）主动查询权威依据，
+  提升转换质量与效率。适用于：页面 spec 生成时的能力可行性核对、页面实现前的 API 签名/参数/权限/
+  错误码核对、构建与测试失败分诊中涉及的 API 行为确认、三方库（ohpm）用法与注意事项核验、
+  系统能力支持范围确认。查询词从当前 Android 功能语义（类名/能力/行为）构造。
+  无需注册 MCP 服务或初始化握手；先查本地缓存，未命中先搜索摘要，信息不足再取全文；
+  结论以文档 title/uri 引用回 spec 与迁移报告。本地文档或其他专项 skill 能解决时不使用本技能。
+version: 1.3.0
+---
+# 云侧知识库查询（HarmonyOS Developer Knowledge）
+
+在 D2h 迁移过程中，当当前实现的功能涉及不确定的 HarmonyOS API、平台能力或三方库用法时，通过 Shell 用 Node.js `fetch` 直接发送 HTTP POST 查询华为开发者知识库，**无需注册 MCP 服务或执行初始化握手**。
+
+## 目标
+
+1. 把云侧查询绑定到**当前正在迁移的功能**：从 Android 源码证据（类名、权限、行为）构造查询词，获取权威实现依据，而不是凭印象写 API。
+2. 控制成本：先查本地缓存（`kb_cache.json`），未命中先搜摘要（`content`），确实相关再取全文；单功能点预算 ≤2 次 search、≤3 篇全文。
+3. 结论可追溯：以文档 `title`/`uri` 引用回页面 spec、迁移报告或失败分诊记录；同一主题查询一次、跨页面复用。
+
+## 迁移流程中的触发时机
+
+在 D2h 主流程的以下环节，命中即按需加载本技能（同一功能不重复查询）：
+
+| 环节 | 触发条件 | 查什么 |
+|------|----------|--------|
+| 页面 spec 生成（`d2h-page-spec-generate`） | spec 标记了平台能力项（相机/定位/文件/通知/蓝牙/分享/Web/后台任务等） | 该能力对应 Kit/API 是否可用、是否受系统能力限制，写入 spec 依据 |
+| 页面实现前（`d2h-page-develop` 步骤 1-2） | 功能清单（F-xxx）中存在平台能力或不确定的 @kit.* Kit / @ohos.* 模块 API | API 签名、参数/返回值、所需权限、错误码、推荐用法与指南 |
+| 页面实现中 | 不确定 ArkUI 组件/属性行为（如 Tabs、Swiper、手势、懒加载） | 开发指南与 FAQ 中的权威行为描述 |
+| 构建失败分诊 | 编译错误指向 @kit.* / @ohos.* API 签名、类型、import 模块名 | 核对该 API 的真实签名与起始版本，避免臆造签名反复试错 |
+| 测试失败分诊（`d2h-hypium-forge`） | 运行时行为与预期不符、错误码/权限弹窗原因不明 | API 行为约束、错误码含义、权限申请时序 |
+| 三方库替换后核验（`native-library-substitution` 已选型） | 已确定替代库，需要确认用法 | 所选 ohpm 库的开发指南、已知限制、实践样例 |
+
+优先级与边界（先走更合适的通道，本技能兜底权威依据）：
+
+- 本地工程文档能确定答案 → `deveco-cli docs`，不发起云侧查询。
+- 已验证的迁移失败教训 → `harmonyos-migration-playbook` 命中即用，不重查云侧。
+- 三方库**选型**（Android 库 → 鸿蒙库映射）→ `native-library-substitution`；本技能只负责所选库的**用法核验**。
+
+## 从当前功能构造查询词
+
+查询词 = **Android 侧证据 + 期望行为 + HarmonyOS 术语**，两步走：
+
+1. 探索（尚不知对应 API）：用「开发场景 + 想实现的行为」，可带 Android 类名提高召回，例如 `选择文件并读取内容 ContentResolver`、`后台下载续传 WorkManager`。
+2. 精查（已知 Kit/模块/API/权限/错误码）：把它直接放进 query；Kit 名与 @ohos 模块名均可作精查词，官方文档两种写法都会出现，组合使用召回更好，例如 `FilePicker DocumentViewPicker`、`CameraKit @ohos.multimedia.camera photoAccessHelper 拍照`。
+
+常用 Android → HarmonyOS 术语对照（用于构造查询词和对照检索结果，**不作为实现结论，结论以检索到的文档为准**）：
+
+| Android 侧 | HarmonyOS 检索词 |
+|------------|------------------|
+| Activity / Fragment | UIAbility / Navigation |
+| SharedPreferences | @ohos.data.preferences |
+| ContentProvider / ContentResolver | DataShare / FilePicker |
+| CameraX / Camera2 | CameraKit @ohos.multimedia.camera |
+| FusedLocationProvider | LocationKit geoLocationManager |
+| Notification / NotificationChannel | NotificationKit @ohos.notification |
+| WebView | Web 组件 @ohos.web.webview |
+| Bitmap / Canvas | PixelMap / Canvas @ohos.graphics.drawing |
+| OkHttp / Retrofit | @ohos.net.http / Remote Communication Kit rcp |
+| Glide / Coil | ImageKnife（ohpm） |
+| WorkManager / JobScheduler | BackgroundTasksKit 后台任务 |
+| RecyclerView / DiffUtil | List / Grid / LazyForEach |
+
+## 知识缓存（跨页面复用）
+
+维护 `.migration/knowledge/kb_cache.json`（工作缓存，非受管证据；建议随页面 ledger 一并提交以便跨会话复用）。顶层为 `topics` 对象，按功能 slug 作 key（如 `file-picker`、`camera-capture`），每个条目包含字段：
+
+- `query`：产生该结论的查询词；`date`：查询日期。
+- `conclusion`：结论摘要（API/Kit、支持范围、权限、关键约束）。
+- `docs[]`：引用文档列表，每项含 `parent`、`title`、`uri`。
+- `usedBy[]`：使用该结论的页面/任务 ID 列表。
+
+规则：
+
+- 实现前先按主题查缓存（key 用功能 slug，如 `file-picker`、`camera-capture`）；命中直接复用结论与文档引用，不重查。
+- 未命中才发起云侧查询；拿到结论后立即写入缓存，并在 `usedBy` 登记当前页面/任务。
+- 缓存中的结论仅是摘要；实现时仍以 `docs` 里的全文为准，摘要与全文冲突时更新缓存。
+
+## 请求基础
+
+- 请求地址：`https://connect-api.cloud.huawei.com/api/developerknowledge/mcp`（本技能唯一域名）
+- 每次请求超时：**30 秒**。
+- 固定请求头：`x-gray-flag: 1`、`Content-Type: application/json`、`Accept: application/json, text/event-stream`、`sceneName: app2harmony`（D2h 应用转换场景专用标识，脚本内已内置）。
+
+## 通用请求脚本
+
+脚本已随本技能打包为 `skills/d2h-cloud-knowledge/kb_query.mjs`（OpenCode 安装后位于 `~/.config/opencode/skills/d2h-cloud-knowledge/kb_query.mjs`）。首次使用时复制到 `<MIGRATION_ROOT>/.migration/knowledge/` 后一直复用，不要手抄重写，也不要绕过脚本手写 curl/JSON-RPC：
+
+- `node kb_query.mjs search "<query>"`：摘要检索（searchDocuments），输出每条结果的 `parent`（文档标识）与 `content`（摘要）。
+- `node kb_query.mjs doc "<parent1,parent2>"`：读取全文（getDocumentsById），输出全文条目的 `name`/`title`/`uri`/`content`，多个 `parent` 用英文逗号分隔。
+- 脚本固定 30 秒超时，自动完成请求、SSE 处理、JSON-RPC 解析、业务码校验与结构化输出；失败时输出错误摘要并以非零码退出（判定标准见「失败判定」）。
+
+## 搜索文档 searchDocuments
+
+通过脚本 `search` 模式调用，query 按「从当前功能构造查询词」组织。单个功能点最多 2 次 search（探索 1 次 + 精查 1 次）；两次仍无相关结果视为「知识库未覆盖」，改用本地文档或指南链接，不要继续换词重试。
+
+## 读取全文 getDocumentsById
+
+根据摘要筛选真正相关的结果，按 `parent` 去重后通过脚本 `doc` 模式获取全文（单次 ≤3 篇）。全文条目包含 `name`、`title`、`uri`、`content`，返回顺序可能与传入顺序不同，**必须按 `name` 识别对应文档，不能依赖数组下标**。
+
+## 解析响应与回流
+
+响应解析（SSE 提取、JSON-RPC 解包、业务码校验）已封装在 `kb_query.mjs` 中，脚本输出即结构化结果，直接使用即可，无需再手动解析。拿到结果后按以下方式回流（让查询真正改善转换效果）：
+
+- 实现依据：按文档核对 API 签名、权限、版本后落地 ArkTS 代码。
+- spec / 迁移报告：在依据、差异（differences）或发现（discoveries）处引用文档 `title` + `uri`，让结论可复核。
+- 失败分诊：在分诊记录中注明「依据 <uri>」，避免同一 API 问题反复查询。
+- 更新 `kb_cache.json`（见「知识缓存」）。
+
+## 失败判定
+
+以下任一情况均视为调用失败，不得当作空结果继续：
+
+- HTTP 状态非成功（非 2xx）。
+- 外层 JSON-RPC 带顶层 `error` 字段。
+- `result.isError: true`。
+- 业务结果 `code` 非 `0` / `"0"`。
+
+失败时输出原始错误摘要与 HTTP 状态，检查 query / names 是否合法后最多重试一次；不要循环重试同一请求。知识库持续不可用时，退回本地文档通道并在分诊/报告记录「云侧知识库不可用」，不得阻塞页面主流程。
+
+## 注意事项
+
+- 只查询**当前功能点**所需资料，不批量拉取无关文档。
+- 全文请求按 `parent` 去重，避免重复请求同一文档；缓存命中时不发起请求。
+- 响应中的 `content` 为 Markdown 正文，直接引用时保留关键代码与注意事项，不要臆造摘要之外的内容。
+- 本技能是只读查询，不修改任何工程文件（`.migration/knowledge/` 下的查询脚本与缓存除外）。

package/skills/d2h-cloud-knowledge/kb_query.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// 云侧知识库查询脚本（d2h-cloud-knowledge 技能配套）。
+// 用法：
+//   node kb_query.mjs search "FilePicker DocumentViewPicker"
+//   node kb_query.mjs doc "alliance/document/cn/harmonyos-guides/select-user-file,alliance/document/cn/other"
+// sceneName 固定为 app2harmony（D2h 应用转换场景）
+const KB_URL = 'https://connect-api.cloud.huawei.com/api/developerknowledge/mcp';
+const HEADERS = {
+  'x-gray-flag': '1',
+  'Content-Type': 'application/json',
+  'Accept': 'application/json, text/event-stream',
+  'sceneName': 'app2harmony',
+};
+
+async function callKb(name, args) {
+  const resp = await fetch(KB_URL, {
+    method: 'POST',
+    headers: HEADERS,
+    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name, arguments: args } }),
+    signal: AbortSignal.timeout(30000),
+  });
+  if (!resp.ok) throw new Error(`HTTP ${resp.status} ${resp.statusText}`);
+  const raw = await resp.text();
+  // 若返回 SSE，提取 data: 内容；否则按 JSON 解析
+  const dataLines = raw.split('\n').map((l) => l.trim()).filter((l) => l.startsWith('data:'));
+  const payloads = dataLines.length ? dataLines.map((l) => JSON.parse(l.slice(5).trim())) : [JSON.parse(raw)];
+  const outer = payloads.find((p) => p && (p.result || p.error)) || payloads[0];
+  if (outer.error) throw new Error(`JSON-RPC error: ${JSON.stringify(outer.error)}`);
+  if (outer.result && outer.result.isError) throw new Error(`result.isError: ${JSON.stringify(outer.result)}`);
+  const text = (outer.result && outer.result.content || []).find((c) => c.type === 'text');
+  if (!text || !text.text) throw new Error('响应中缺少 type=text 内容');
+  const biz = JSON.parse(text.text);
+  if (biz.code !== 0 && String(biz.code) !== '0') throw new Error(`业务错误 code=${biz.code} message=${biz.message}`);
+  return biz.resultList || [];
+}
+
+const [mode, arg] = process.argv.slice(2);
+(async () => {
+  if (mode === 'search') {
+    const list = await callKb('searchDocuments', { SearchDocumentsReq: { query: arg } });
+    for (const item of list) {
+      console.log(JSON.stringify({ parent: item.parent, content: item.content }, null, 2));
+      console.log('---');
+    }
+  } else if (mode === 'doc') {
+    const names = arg.split(',').map((s) => s.trim()).filter(Boolean);
+    const list = await callKb('getDocumentsById', { GetDocumentsByIdRequest: { names } });
+    for (const doc of list) {
+      console.log(JSON.stringify({ name: doc.name, title: doc.title, uri: doc.uri, content: doc.content }, null, 2));
+      console.log('---');
+    }
+  } else {
+    throw new Error('用法: node kb_query.mjs search "<query>" | doc "<parent1,parent2>"');
+  }
+})().catch((e) => { console.error('调用失败:', e.message); process.exit(1); });

package/skills/d2h-page-develop/SKILL.md

@@ -1,112 +1,132 @@
----
-name: d2h-page-develop
-description: Implement ordered Android-to-HarmonyOS page tasks from pages.json, batch_report.md, and page-scoped spec.md files. Use during page development when the current agent must complete each page serially through ArkTS implementation, managed build, Python Hypium tests, scoped commits, migration-report evidence, and in-place ledger updates before starting the next page. Do not delegate page work to subagents.
----
-
-# Page development loop
-
-Implement and verify one ordered page task at a time in the current agent. Own each page's complete loop and do not delegate page implementation, build, testing, reporting, commits, or ledger updates to subagents.
-
-## Inputs and boundaries
-
-- Use `.migration/page-specs/pages.json` as the immutable page order and `batch_report.md` as the mutable execution ledger.
-- Use the selected page package's `spec.md` as the authority for page scope, behavior, acceptance sequences, Android evidence, and expected HarmonyOS files.
-- Read `.migration/utg/page.json` when the Spec references a UTG node or the arrival path needs clarification. Read cited Android source before implementing behavior.
-- Do not require or generate `ui-design.md`, copied screenshots, copied `view.xml`, or any other page-package artifact. Each `page_NNNN_<name>-<id>/` directory continues to contain only `spec.md`.
-- Do not regenerate `pages.json`, page Specs, or `batch_report.md` during ordinary development. Correct an owning artifact only when current source proves it wrong, record the reason, and preserve execution history.
-- Use `droid2hmos` managed build and test entry points. Do not use task-planning commands or static scripts to choose or execute page work.
-- Preserve unrelated user changes. Never reset, discard, or include them in a page commit.
-
-## Single-agent mode
-
-1. Read `pages.json` and `batch_report.md`; use AI judgment to verify their task IDs, order, links, counts, and current states agree.
-2. Select the earliest ordered page whose development/build/validation states are not `implemented/passed/passed` and whose declared dependencies are satisfied.
-3. Resolve the page package, Android root, HarmonyOS root, repository root, current `HEAD`, Git status, device target, and task evidence directory.
-4. Record the current `HEAD` and Git status as the task baseline, then execute the selected page through the complete per-page loop below.
-5. Verify the resulting implementation, current managed build/test evidence, migration report, commits, batch ledger, and Git status.
-6. If the page is incomplete or fails verification, repair the same page; do not select another page.
-7. Only after the selected task is genuinely `implemented/passed/passed` may the current agent select the next task.
-8. After all tasks are complete, explicitly enumerate every Python Hypium test list and run one managed batch regression. Append the batch evidence to `batch_report.md` and the migration report.
-
-## Per-page execution
-
-### 1. Claim and understand the page
-
-- Confirm the task is the earliest incomplete eligible row and no other task is `in_progress`.
-- Compare the checkout with the recorded task baseline. Preserve and avoid unrelated dirty files; if ownership conflicts with a build-affecting file, return the exact conflict instead of overwriting it.
-- Mark only the selected task `in_progress` in the working copy of `batch_report.md`.
-- Read the complete `spec.md`, the referenced `.migration/utg/page.json` node, every cited Fact, and every cited Android source file. Follow handlers, state transitions, repositories, navigation, persistence, error paths, and platform side effects far enough to establish the observable result.
-- Inspect the HarmonyOS architecture, routes, resources, shared components, tests, and current implementation. Load `arkts-mvvm-architecture` before planning or writing ArkTS.
-- Build a private checklist mapping every `F-xxx` to reachable code, a stable semantic locator, an executed test assertion, and an observable result. Do not create another planning file.
-- Resume valid existing work for this same task instead of duplicating it.
-
-### 2. Implement
-
-- Implement all page-scoped UI, navigation, overlays, state transitions, persistence/data effects, error paths, resources, and required shared integration.
-- Use the Android source and observable behavior for functional truth. Use HarmonyOS-native architecture and components for the target implementation.
-- Give tested interactive elements stable, unique semantic locators. Do not add controls solely to make testing easier.
-- Load the applicable domain Skill for identity, i18n, drawable conversion, icon sizing, or third-party substitution when the page touches that domain.
-- Keep shared changes limited to capabilities this page actually needs and record downstream consumers.
-- Do not leave stubs, fixed success values, swallowed errors, unreachable pages, placeholder controls, or TODO implementations.
-
-### 3. Managed build
-
-- Run a fresh, non-interactive, bounded build through `droid2hmos build harmony <ANDROID_PROJECT>` using the resolved project configuration.
-- Save the exact command, exit status, timestamps, relevant log, produced HAP path, and HAP SHA-256 in the task evidence directory.
-- Treat compilation errors caused or exposed by the implementation as work to fix. Repeat edit/build until the managed build passes.
-- An older HAP, static analysis result, direct Hvigor run, or previous log is not current build evidence.
-
-### 4. Managed page tests
-
-- Load `d2h-hypium-forge`. Add or update executable Python Hypium tests for every `F-xxx`, with paired `.py` and `.json` test-list assets and stable semantic locators.
-- Cover navigation or overlay lifecycle, state changes, data effects, and error behavior required by the Spec. Assertions must prove the declared result, not merely that a page or button exists.
-- Run the affected lists through the managed entry point:
-
-  ```text
-  droid2hmos test harmony <ANDROID_PROJECT> \
-    --runner python --hypium-project <HARMONY_PROJECT>/.hypium_forge \
-    --test-list <AFFECTED_LIST> --target <DEVICE> \
-    --ref <ACTUALLY_ASSERTED_REF>...
-  ```
-
-- Save the exact command, result, native report/log, device target, timestamps, hashes, and returned `managedEvidence` in the task evidence directory.
-- A written-but-unexecuted test, screenshot-only check, coordinate-only replay, direct local runner, old log, or zero-test result is not a pass.
-- Fix implementation or test defects and repeat managed build/test until both pass. Only a persistent external environment, signing, or device failure may become `blocked`, after bounded retries with diagnostics recorded.
-
-### 5. Report and commit
-
-- Load `maintaining-migration-report` while evidence is fresh. Record real HarmonyOS files, Android source provenance, current managed evidence, differences, and source-proven discoveries; run report validation.
-- Inspect Git status and diff. Stage only the selected page's implementation, resources, tests, necessary shared files, and a source-proven correction to this page's `spec.md` when required. Do not include unrelated changes.
-- Create a scoped implementation commit only after the managed build and page tests pass. Record its commit ID.
-- If build-affecting page changes remain after the commit, correct the commit and rerun build/test so the evidence proves the committed tree.
-- Update the existing `batch_report.md` queue row, detail section, counts, evidence, files, implementation commit, timestamp, blocker, and chronological notes in place. Do not rerun `build_batch_report.py`.
-- Set `implemented/passed/passed` only when all three states are supported by current evidence. Use AI inspection to confirm queue/detail/count consistency and preserve all prior history.
-- Commit the ledger and immutable task evidence separately from the implementation commit. Do not create a self-referential commit field.
-
-## Page completion verification
-
-Before marking the page complete, confirm:
-
-- every `F-xxx` has reachable implementation, a stable locator, and an actually executed assertion;
-- the page is reachable from the real app entry without a test-only route or replacement control;
-- build logs, HAP hash, test reports, managed evidence, and migration-report refs correspond to the implementation commit;
-- `batch_report.md` is internally consistent and the selected row is `implemented/passed/passed`;
-- both scoped commits exist and no uncommitted change owned by the page remains;
-- user changes and other pages were not reset or included;
-- no implementation defect was reclassified as a platform difference or external blocker.
-
-If verification fails, repair the same task before selecting or starting the next task.
-
-## Batch regression
-
-After every page task is complete:
-
-1. Enumerate every current Python Hypium test list explicitly; the Python runner does not use `--all`.
-2. Run one managed command with all required `--test-list` values on the qualified device, using only refs actually asserted by the batch.
-3. Require non-zero execution with no failures, errors, or ignored tests.
-4. Append the managed batch evidence and timestamp to `batch_report.md`, then update and validate the migration report.
-5. Treat this managed Python batch as the primary application-wide regression for the page-spec workflow. Run ArkTS `--all` only as supplemental coverage when the project maintains relevant ArkTS ohosTest assets; it is not a fixed completion gate for this workflow.
-
-## Final result
-
-Return each task ID and page, final states, implementation and test files, managed build command/HAP/evidence, managed test command/evidence, implementation and ledger commit IDs, batch regression evidence, unrelated Git changes left untouched, and any genuine blocker or unresolved item.
+---
+name: d2h-page-develop
+description: Implement ordered Android-to-HarmonyOS page tasks from pages.json, batch_report.md, and page-scoped spec.md files. Use during page development when a dedicated page-worker must complete one page through ArkTS implementation, managed build, Python Hypium tests, scoped commits, migration-report evidence, and in-place ledger updates before the next page starts.
+---
+
+# Page development loop
+
+Implement and verify one ordered page task at a time. The parent agent selects and reviews the task; a dedicated page-worker owns exactly one page's complete loop.
+
+## Inputs and boundaries
+
+- Use `.migration/page-specs/pages.json` as the immutable page order and `batch_report.md` as the mutable execution ledger.
+- Use the selected page package's `spec.md` as the authority for page scope, behavior, acceptance sequences, Android evidence, and expected HarmonyOS files.
+- Read `.migration/utg/page.json` when the Spec references a UTG node or the arrival path needs clarification. Read cited Android source before implementing behavior.
+- Do not require or generate `ui-design.md`, copied screenshots, copied `view.xml`, or any other page-package artifact. Each `page_NNNN_<name>-<id>/` directory continues to contain only `spec.md`.
+- Do not regenerate `pages.json`, page Specs, or `batch_report.md` during ordinary development. Correct an owning artifact only when current source proves it wrong, record the reason, and preserve execution history.
+- Use `droid2hmos` managed build and test entry points. Do not use task-planning commands or static scripts to choose or execute page work.
+- Preserve unrelated user changes. Never reset, discard, or include them in a page commit.
+
+## Parent-agent mode
+
+1. Read `pages.json` and `batch_report.md`; use AI judgment to verify their task IDs, order, links, counts, and current states agree.
+2. Select the earliest ordered page whose development/build/validation states are not `implemented/passed/passed` and whose declared dependencies are satisfied.
+3. Resolve the page package, Android root, HarmonyOS root, repository root, current `HEAD`, Git status, device target, and task evidence directory.
+4. Dispatch exactly one page-worker with absolute paths, selected task ID, dispatch baseline, device target, and evidence directory. Do not run page-workers in parallel or give one worker multiple pages.
+5. Wait for the worker to complete the selected page. If it is incomplete or fails review, send the same page back for repair; do not select another page.
+6. Independently verify the resulting implementation, current managed build/test evidence, migration report, commits, batch ledger, and Git status.
+7. Only after the selected task is genuinely `implemented/passed/passed` may the parent select the next task.
+8. After all tasks are complete, explicitly enumerate every Python Hypium test list and run one managed batch regression. Append the batch evidence to `batch_report.md` and the migration report.
+
+Use this worker prompt contract:
+
+```text
+Use $d2h-page-develop in page-worker mode. Complete exactly <TASK_ID>.
+Migration root: <absolute path>
+Page package: <absolute path>
+Android root: <absolute path>
+HarmonyOS root: <absolute path>
+Repository root: <absolute path>
+Dispatch baseline: <HEAD and recorded Git status>
+Device target: <target>
+Evidence directory: <absolute task/run directory>
+
+Own the complete page loop: read spec.md, UTG evidence and cited Android source;
+implement the page; run managed build; load $d2h-hypium-forge and execute the
+page tests through the managed Python runner; update the migration report;
+create scoped commits; and update batch_report.md in place. Do not start another page.
+```
+
+If independent page-worker execution is unavailable, return that the required mode cannot run. Do not silently implement multiple pages in the parent agent.
+
+## Page-worker mode
+
+### 1. Claim and understand the page
+
+- Confirm the task is the earliest incomplete eligible row and no other task is `in_progress`.
+- Compare the checkout with the dispatch baseline. Preserve and avoid unrelated dirty files; if ownership conflicts with a build-affecting file, return the exact conflict instead of overwriting it.
+- Mark only the selected task `in_progress` in the working copy of `batch_report.md`.
+- Read the complete `spec.md`, the referenced `.migration/utg/page.json` node, every cited Fact, and every cited Android source file. Follow handlers, state transitions, repositories, navigation, persistence, error paths, and platform side effects far enough to establish the observable result.
+- Inspect the HarmonyOS architecture, routes, resources, shared components, tests, and current implementation. Load `arkts-mvvm-architecture` before planning or writing ArkTS.
+- Build a private checklist mapping every `F-xxx` to reachable code, a stable semantic locator, an executed test assertion, and an observable result. Do not create another planning file.
+- Resume valid existing work for this same task instead of duplicating it.
+
+### 2. Implement
+
+- Implement all page-scoped UI, navigation, overlays, state transitions, persistence/data effects, error paths, resources, and required shared integration.
+- Use the Android source and observable behavior for functional truth. Use HarmonyOS-native architecture and components for the target implementation.
+- Give tested interactive elements stable, unique semantic locators. Do not add controls solely to make testing easier.
+- Load the applicable domain Skill for identity, i18n, drawable conversion, icon sizing, or third-party substitution when the page touches that domain. Before implementing platform capabilities or uncertain HarmonyOS APIs (`@kit.*` Kit imports or `@ohos.*` modules), and when build or test failures point to API signatures or behavior, load `d2h-cloud-knowledge`: check `.migration/knowledge/kb_cache.json` first, query only on cache miss, and record conclusions with doc `title`/`uri` back into the cache, the page spec evidence, and the migration report.
+- Keep shared changes limited to capabilities this page actually needs and record downstream consumers.
+- Do not leave stubs, fixed success values, swallowed errors, unreachable pages, placeholder controls, or TODO implementations.
+
+### 3. Managed build
+
+- Run a fresh, non-interactive, bounded build through `droid2hmos build harmony <ANDROID_PROJECT>` using the resolved project configuration.
+- Save the exact command, exit status, timestamps, relevant log, produced HAP path, and HAP SHA-256 in the task evidence directory.
+- Treat compilation errors caused or exposed by the implementation as work to fix. Repeat edit/build until the managed build passes.
+- An older HAP, static analysis result, direct Hvigor run, or previous log is not current build evidence.
+
+### 4. Managed page tests
+
+- Load `d2h-hypium-forge`. Add or update executable Python Hypium tests for every `F-xxx`, with paired `.py` and `.json` test-list assets and stable semantic locators.
+- Cover navigation or overlay lifecycle, state changes, data effects, and error behavior required by the Spec. Assertions must prove the declared result, not merely that a page or button exists.
+- Run the affected lists through the managed entry point:
+
+  ```text
+  droid2hmos test harmony <ANDROID_PROJECT> \
+    --runner python --hypium-project <HARMONY_PROJECT>/.hypium_forge \
+    --test-list <AFFECTED_LIST> --target <DEVICE> \
+    --ref <ACTUALLY_ASSERTED_REF>...
+  ```
+
+- Save the exact command, result, native report/log, device target, timestamps, hashes, and returned `managedEvidence` in the task evidence directory.
+- A written-but-unexecuted test, screenshot-only check, coordinate-only replay, direct local runner, old log, or zero-test result is not a pass.
+- Fix implementation or test defects and repeat managed build/test until both pass. Only a persistent external environment, signing, or device failure may become `blocked`, after bounded retries with diagnostics recorded.
+
+### 5. Report and commit
+
+- Load `maintaining-migration-report` while evidence is fresh. Record real HarmonyOS files, Android source provenance, current managed evidence, differences, and source-proven discoveries; run report validation.
+- Inspect Git status and diff. Stage only the selected page's implementation, resources, tests, necessary shared files, and a source-proven correction to this page's `spec.md` when required. Do not include unrelated changes.
+- Create a scoped implementation commit only after the managed build and page tests pass. Record its commit ID.
+- If build-affecting page changes remain after the commit, correct the commit and rerun build/test so the evidence proves the committed tree.
+- Update the existing `batch_report.md` queue row, detail section, counts, evidence, files, implementation commit, timestamp, blocker, and chronological notes in place. Do not rerun `build_batch_report.py`.
+- Set `implemented/passed/passed` only when all three states are supported by current evidence. Use AI inspection to confirm queue/detail/count consistency and preserve all prior history.
+- Commit the ledger and immutable task evidence separately from the implementation commit. Do not create a self-referential commit field.
+
+## Parent verification
+
+Before accepting the worker result, independently confirm:
+
+- every `F-xxx` has reachable implementation, a stable locator, and an actually executed assertion;
+- the page is reachable from the real app entry without a test-only route or replacement control;
+- build logs, HAP hash, test reports, managed evidence, and migration-report refs correspond to the implementation commit;
+- `batch_report.md` is internally consistent and the selected row is `implemented/passed/passed`;
+- both scoped commits exist and no uncommitted change owned by the page remains;
+- user changes and other pages were not reset or included;
+- no implementation defect was reclassified as a platform difference or external blocker.
+
+Review failure returns the same task for repair. The worker never selects or starts the next task.
+
+## Batch regression
+
+After every page task is complete:
+
+1. Enumerate every current Python Hypium test list explicitly; the Python runner does not use `--all`.
+2. Run one managed command with all required `--test-list` values on the qualified device, using only refs actually asserted by the batch.
+3. Require non-zero execution with no failures, errors, or ignored tests.
+4. Append the managed batch evidence and timestamp to `batch_report.md`, then update and validate the migration report.
+5. Treat this managed Python batch as the primary application-wide regression for the page-spec workflow. Run ArkTS `--all` only as supplemental coverage when the project maintains relevant ArkTS ohosTest assets; it is not a fixed completion gate for this workflow.
+
+## Worker result
+Return the task ID and page, final states, implementation and test files, managed build command/HAP/evidence, managed test command/evidence, implementation and ledger commit IDs, unrelated Git changes left untouched, and any genuine blocker or unresolved item.

package/skills/d2h-page-spec-generate/SKILL.md

@@ -92,6 +92,7 @@ Use schema `d2h-page-plan/v1`. Every `pages[]` item must contain:
 3. Use `page.json` navigation steps, selectors, guards, expected-arrival rules, required state, and depth to reconstruct the semantic arrival path. Source-derived reachability is planning evidence, not runtime confirmation.
 4. Translate selectors into semantic control names only when Facts, resources, or Android source support the mapping. Keep missing or ambiguous selectors explicitly unresolved.
 5. Verify every listed Android path exists under `android_root`. Verify every HarmonyOS path marked `existing` exists under `harmony_root`; otherwise mark it `planned`.
+6. When page features touch platform capabilities (camera, location, files, notifications, Bluetooth, share, Web, background tasks, etc.) or uncertain HarmonyOS APIs (`@kit.*` Kit imports or `@ohos.*` modules), load `d2h-cloud-knowledge` to confirm the corresponding Kit/API availability and system-capability limits before writing: check `.migration/knowledge/kb_cache.json` first, query only on cache miss, cite the doc `title`/`uri` in「未决项与平台差异」or the supporting feature item, and record the topic in the cache with this page as `usedBy`.
 
 ### 5. Write only `spec.md`