@harmonyos-arkts/d2h 0.1.19 → 0.1.21

package/skills/d2h-architecture-plan/references/plan-contract.md

@@ -0,0 +1,51 @@
+# 规划交付：目录、归属与决策
+
+默认只写一份 `architecture-plan.md`，保留已有用户批注。目标是让开发者能判断采用哪套结构，并据此创建目录；不为呈现分析过程堆叠报告。
+
+## 1. 共用一次项目理解
+
+简述应用用途、原结构、目标范围及实际读取范围。已有明确的结合/不结合鸿蒙工程选择一并简记，后续同范围修订沿用；未答复只记默认 Android，不记为拒绝。未读取的目标工程不作为已核验的复用依据。
+
+把项目理解并入后面的归属表：源路径、职责/层次及必要证据。资源、配置、后台/外部入口和 Native/混合栈边界归入对应区域；事实、候选和未决分开。不另写长篇源码导读、完整阅读清单、文件统计或业务链报告。
+
+## 2. 推荐目录详列，另外两套对照
+
+共用上述源范围，提供 `android-mirror`、`harmony-practice`、`hybrid` 三套结构选项。默认详细展开推荐方案；用户已有选择时展开所选方案，不重新选型。详细方案保留：
+
+- **关键目录树**：展开全部拟议实际模块及主要职责/feature 目录，注明 HAP/HAR/HSP 或模块内目录。基础保留方案体现原模块/关键包族的相对层级；业务方案体现页面/页面组及共享区域。只列目录，不逐类造目录；同构 feature 的内部子目录模式可说明一次，无需在每处重复展开。选中创建时再从树和模式展开实际清单。
+- **主要决定与依赖**：说明本套保留/拆合/改名、装配与主要依赖方向，必要时用短表或依赖示意。保留的源边、目标新增/替代的边分别表述；目录不等于独立构建模块。
+- **收益、成本与风险**：围绕原作者定位、维护、平台边界及拆合成本简要说明，路径定位例子复用归属表。风险只写影响的边界/前置，不为此展开完整替代方案和接口设计。
+
+用一张源到详细方案目标的归属表覆盖主要模块/职责区域，合并职责、必要共享所有权及适配说明；混合区域列出保留与移出部分，避免粗目录双重认领。不另加相同粒度的模块表、状态表和页面交接表重复这些事实。已知职责有去向才算目录覆盖，不以文档长度证明完整。
+
+另外两套用紧凑对照说明模块/包族保留或重组、主要依赖变化、收益/代价；相同部分引用详细方案，只有结构差异难以表达时补局部树，不默认生成三份完整目录树和三列全量映射。用户明确要求三套完整目录时全部展开，但仍共用项目理解、映射和风险。选择另一套后依据差异展开其目录即可，除非边界出现新问题，不重新扫描源码。
+
+## 3. 融合方案的最小交接
+
+融合方案采用 [hybrid-design.md](hybrid-design.md) 的两层原则。详细展开 hybrid 时，把以下信息并入目录/归属表，足以支持后续细化，不额外生成逐页交接表或实施计划；仅作备选时概述与详细方案的差异即可：
+
+| 内容 | 本阶段粒度 |
+|---|---|
+| 基础保留与适配 | 原模块/包族→目标路径、保留部分、必须调整的边界与理由 |
+| 页面/页面组候选 | 源入口或页面族→目标 feature 与所属模块，已知共享依赖；不机械把 Activity/Fragment 个数当 feature 数量 |
+| 共享业务与协作 | 唯一目标所有者、主要消费者、装配/导航/数据协作方式；未明确的契约列为细化前置 |
+| 独立转换条件 | 已知共同修改区域及集成归属、最小能力前置，哪些候选可在条件满足后独立转换，哪些确需合组 |
+
+共享状态不复制；共享一个领域会话不自动证明页面应合组。不要求现在确定全部页面 ID、独占测试/资源文件、完整输入输出/错误契约或验收序列；这些细节在选定方案后的页面规划/实现中补齐。候选不是最终 Spec 身份，目录分开也不能证明当前已可并发执行。
+
+## 4. 推荐、复核与选型
+
+比较三套的维护定位、边界清晰度、平台适配与迁移成本，给基于当前证据的推荐及会改变推荐的条件。模块数量、目录命名和“最佳实践”标签不能替代论证；同构方案不为制造差异而拆库。
+
+交付前对照同一张范围/归属表检查：
+
+- 已知运行时模块、主要职责与资源/非 UI 入口都有去向；未排除用户业务，三套范围一致。
+- 树、映射、模块类型及主要依赖互相吻合，原包族保留承诺可定位，共享所有权唯一，无未解释的目标环或反向页面依赖。
+- 方案不夹带未验证的平台替代/进程合并/功能裁剪结论；目录待决与实现前置分开，未读取鸿蒙源码时没有伪称目标已实现。
+- 融合分层与页面候选有证据，已知共同写入点有归属；没有将未细化的契约或目录壳子记为已可开工。
+
+有矛盾时局部修订并补查相关证据，不重跑全仓分析。架构选择可以在保留实现风险的情况下完成；未知仍影响具体目录时明确条件分支或草案范围。
+
+默认交付 Markdown 即可，不生成 `source-inventory.json`、`source-baseline.json`、`plan-input.json` 等扫描/中转文件。映射确实过长才单独放链接的 `source-map.md`；用户指定其他产物或下游确需结构化契约时，只补实际需要的字段，不空置字段后宣称已校验。
+
+只请求规划时交付即可，不强求立即选型。用户选定后记录方案与修改意见，下游沿用实际目录及共享边界；创建时按 [directory-creation.md](directory-creation.md) 执行并记录实际结果，不同时落实三套，不把目录落地写成应用迁移完成。

package/skills/d2h-architecture-plan/references/source-review.md

@@ -0,0 +1,50 @@
+# 源码阅读：以目录决定为边界
+
+默认分析 Android，鸿蒙源码的读取选择遵循 [SKILL.md](../SKILL.md)。目标是确定模块/包族如何保留、业务放进哪些 feature、共享职责归谁以及主要依赖怎样走；不以读懂全部业务为前置。
+
+## 1. 先建立结构地图
+
+优先定位下列结构证据，按需读相关片段；同一地图支撑三套方案。
+
+| 入口 | 获得足以规划目录的信息 |
+|---|---|
+| settings、模块构建声明、sourceSets/约定插件 | 实际应用与运行时模块、源码/资源根、内部声明依赖及传递导出；构建辅助项目不变成业务模块 |
+| Manifest、导航/页面注册、应用启动声明 | 主入口、主要页面族及外部/后台/跨进程入口；识别候选 feature，无需逐页验证可达性 |
+| 模块与主要包族目录、代表性声明/公开入口 | 区分基础依赖、页面业务、共享业务、应用装配；单模块也按内部职责区域划分 |
+| 装配/状态持有者/Repository 的声明与必要引用 | 影响拆合的共享状态、当前持有方与主要消费者，避免目标中重复所有权或反向依赖 |
+| 资源/配置根、平台包装入口及 Native/混合栈构建声明 | 这些职责放在哪里、谁消费；品牌/渠道等差异是否改变目录与装配 |
+
+先用轻量路径定位和定向搜索缩小阅读范围；这不要求为所有文件采集大小、时间戳、校验和或读取内容。大型上游库可从构建声明、包装入口和消费者确认职责，不逐文件阅读；资源按用途/来源族归属，不展开每条文案、图片或每份同构配置。
+
+已有功能清单或分析报告可帮助定位；对用于拆合、改名或改变依赖的关键结论核对源码，不重新逐项审计整份清单。已有扫描摘要可复用，庞大 JSON 只查询当前所需字段，不重建文件清单、快照、全量 import/调用图或专用分析器。
+
+地图覆盖已识别的运行时模块、主要业务/支撑区域与资源/配置/非 UI 入口，记录职责、源路径及归属线索。目录名只是线索：`lib/common/model`、无 UI 或多页复用不单独证明属于基础层。模糊区域暂记候选及影响，不通过统计所有类或页面数证明理解完整。
+
+## 2. 只有会改变边界的问题才扩读
+
+扩读前先明确要裁决的决定，例如“这个库能否留在基础层”“两页是否需要共同状态所有者”。从相关声明、装配或调用片段核对；问题解决后回到目录设计，不顺带遍历该业务的完整执行链。
+
+| 决定尚不清楚 | 定点核对 | 可以留给后续实现的内容 |
+|---|---|---|
+| 源模块/包族混合页面、业务与基础职责 | 页面注册、关键类型职责和调用方，确定保留与抽出的范围 | 每个类的逐一搬迁、逐控件行为 |
+| 共享状态影响页面拆分或模块依赖 | 谁创建/持有、主要读写方及公开协作；必要时查看生命周期约束 | 不改变所有者的完整初始化、失败、取消、恢复流程 |
+| 声明依赖与目标方向矛盾 | 相关导出、实际调用或事件/桥接，说明具体改向机制 | 全仓 import 解析、每条引用核对 |
+| 页面应拆开还是合组 | 相关路由与私有状态耦合，区分导航关联和共享业务依赖 | 完整页面/Spec 清单、精确任务顺序和独占文件清单 |
+| 后台、外部入口或独立进程改变装配 | 声明、调用入口和状态持有方，保留目标职责与限制 | 详细回调时序、权限和业务验收步骤 |
+| Native、SDK 或嵌入运行时改变拆包/可行性 | 构建/加载/包装边界、主要消费者、材料可得性；混合应用定位实际业务源码根 | 二进制逐一审计、移植设计、全部 SDK/API 替代调研 |
+| 配置/资源差异改变产品与模块组织 | 生效选择规则、资源族与消费者 | 品牌×渠道的逐项内容比较、精确资源转换 |
+| 用户已选择结合现有鸿蒙工程 | 所涉模块注册、公开入口和对应职责，确定复用影响 | 无关目标实现的全面审查 |
+
+平台可得性确实影响模块/运行时选择时才查对应官方资料，记录适用前提；不影响目录的 API 签名、Kit、资源格式与实施细节留到转换阶段。无法取得材料时说明未知与影响，不用连续检索猜结论；仅仓内缺少鸿蒙依赖不能证明没有鸿蒙版。
+
+不要凭静态搜索无引用就删除疑似旧页面、flavor 或后台能力；默认保留到相应区域并标记待核实，排除用户业务需有依据。Native/SDK 风险也不能自动变成裁剪或降级决定。默认不运行构建、设备采集或下载依赖。
+
+## 3. 何时停止阅读
+
+满足以下架构证据即可结束源码分析：
+
+- 已知运行时模块、主要职责区域、资源/配置与非页面入口有目标归属或明确的待决去向，三套使用同一范围。
+- 重要保留/拆合有源路径或代表符号支撑；主要依赖和影响边界的共享所有者可解释，混合区域不被多个目标整体认领。
+- 剩余未知按影响区分：只影响实现的留作转换前置；会改变目录的说明受影响分支和所需证据，不把它写成已确定结构。
+
+随后复核目录树、映射和主要依赖之间是否一致；只有发现新的边界矛盾才补读对应源码。用户明确要求深入某个问题时再扩展该部分，不默认追踪所有页面的结果、异常和生命周期，也不把架构规划写成完整迁移可行性审计。

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

@@ -27,8 +27,8 @@ version: 1.3.0
 
 | 环节 | 触发条件 | 查什么 |
 |------|----------|--------|
-| 页面 spec 生成（`d2h-page-spec-generate`） | spec 标记了平台能力项（相机/定位/文件/通知/蓝牙/分享/Web/后台任务等） | 该能力对应 Kit/API 是否可用、是否受系统能力限制，写入 spec 依据 |
-| 页面实现前（`d2h-page-develop` 步骤 1-2） | 功能清单（F-xxx）中存在平台能力或不确定的 @kit.* Kit / @ohos.* 模块 API | API 签名、参数/返回值、所需权限、错误码、推荐用法与指南 |
+| 页面 spec 生成（`d2h-spec-plan`） | spec 标记了平台能力项（相机/定位/文件/通知/蓝牙/分享/Web/后台任务等） | 该能力对应 Kit/API 是否可用、是否受系统能力限制，写入 spec 依据 |
+| 页面实现前（`d2h-spec-develop` 步骤 1-2） | 功能清单（F-xxx）中存在平台能力或不确定的 @kit.* Kit / @ohos.* 模块 API | API 签名、参数/返回值、所需权限、错误码、推荐用法与指南 |
 | 页面实现中 | 不确定 ArkUI 组件/属性行为（如 Tabs、Swiper、手势、懒加载） | 开发指南与 FAQ 中的权威行为描述 |
 | 构建失败分诊 | 编译错误指向 @kit.* / @ohos.* API 签名、类型、import 模块名 | 核对该 API 的真实签名与起始版本，避免臆造签名反复试错 |
 | 测试失败分诊（`d2h-hypium-forge`） | 运行时行为与预期不符、错误码/权限弹窗原因不明 | API 行为约束、错误码含义、权限申请时序 |
@@ -36,10 +36,6 @@ version: 1.3.0
 
 优先级与边界（先走更合适的通道，本技能兜底权威依据）：
 
-- 本地工程文档能确定答案 → `deveco-cli docs`，不发起云侧查询。
-- 已验证的迁移失败教训 → `harmonyos-migration-playbook` 命中即用，不重查云侧。
-- 三方库**选型**（Android 库 → 鸿蒙库映射）→ `native-library-substitution`；本技能只负责所选库的**用法核验**。
-
 ## 从当前功能构造查询词
 
 查询词 = **Android 侧证据 + 期望行为 + HarmonyOS 术语**，两步走：
@@ -93,13 +89,15 @@ version: 1.3.0
 - `node kb_query.mjs doc "<parent1,parent2>"`：读取全文（getDocumentsById），输出全文条目的 `name`/`title`/`uri`/`content`，多个 `parent` 用英文逗号分隔。
 - 脚本固定 30 秒超时，自动完成请求、SSE 处理、JSON-RPC 解析、业务码校验与结构化输出；失败时输出错误摘要并以非零码退出（判定标准见「失败判定」）。
 
+> `searchDocuments` 返回的 `parent` 形如 `kms-rag://…/10-官方资源索引#0`，末尾 `#0` 是块（chunk）标识，**属于完整文档标识的一部分，必须原样保留**。`getDocumentsById` 需要这个带 `#块号` 的完整标识才能命中。任何把 `#0` 剥离、改写或当作 URL fragment 去掉的处理都会导致查不到结果；脚本对 `parent`/`name` 不做任何改写，Agent 复制 `parent`、写回 `kb_cache.json` 的 `docs[].parent`、以及 spec/报告引用时都必须使用含 `#0` 的原值。
+
 ## 搜索文档 searchDocuments
 
 通过脚本 `search` 模式调用，query 按「从当前功能构造查询词」组织。单个功能点最多 2 次 search（探索 1 次 + 精查 1 次）；两次仍无相关结果视为「知识库未覆盖」，改用本地文档或指南链接，不要继续换词重试。
 
 ## 读取全文 getDocumentsById
 
-根据摘要筛选真正相关的结果，按 `parent` 去重后通过脚本 `doc` 模式获取全文（单次 ≤3 篇）。全文条目包含 `name`、`title`、`uri`、`content`，返回顺序可能与传入顺序不同，**必须按 `name` 识别对应文档，不能依赖数组下标**。
+根据摘要筛选真正相关的结果，按 `parent` 去重后通过脚本 `doc` 模式获取全文（单次 ≤3 篇）。`parent` 含 `#<块号>` 片段（同一文档不同块是不同 `parent`），去重时按**完整 `parent`（含 `#0`）** 比对，不得剥离 `#0` 后合并，否则会把同一文档的不同块误并、或把完整标识改写成查不到的形态。全文条目包含 `name`、`title`、`uri`、`content`，返回顺序可能与传入顺序不同，**必须按 `name` 识别对应文档，不能依赖数组下标**。
 
 ## 解析响应与回流
 
@@ -121,6 +119,29 @@ version: 1.3.0
 
 失败时输出原始错误摘要与 HTTP 状态，检查 query / names 是否合法后最多重试一次；不要循环重试同一请求。知识库持续不可用时，退回本地文档通道并在分诊/报告记录「云侧知识库不可用」，不得阻塞页面主流程。
 
+## 典型案例：`parent` 的 `#块号` 被剥离导致查不到全文
+
+**现象**：`search` 拿到结果后，后期按 `parent` 查 `doc` 全文总是查不到。
+
+**实例**（NFC 知识库检索）：
+
+```json
+{
+  "parent": "kms-rag://app2harmony/app2harmony/nfc相关知识/10-官方资源索引#0",
+  "content": "鸿蒙侧见 鸿蒙/08-官方资源索引。"
+}
+```
+
+- ✅ 正确：把 `parent` **原样**（含 `#0`）传给 `doc` 查询 → 命中。
+- ❌ 错误：把 `#0` 当 URL fragment 去掉，用 `kms-rag://app2harmony/app2harmony/nfc相关知识/10-官方资源索引` 去查 → 查不到。
+
+**根因**：`parent` 末尾的 `#0` 是块（chunk）标识，属于完整文档标识的一部分，不是可省略的 URL 锚点；`getDocumentsById` 依赖它定位到具体块。
+
+**规避**：
+1. 复制 `parent` 时**逐字保留**，不做任何 `split('#')` / `replace(/#.*$/)` / URL 规范化处理。
+2. 写回 `kb_cache.json` 的 `docs[].parent`、以及 spec/报告引用的标识都用含 `#0` 的原值。
+3. `kb_query.mjs` 已对 `parent`/`name` 零改写，并在 `doc` 空结果时提示核对 `#块号` 是否被剥离——命中该提示时先检查传入标识是否少了 `#块号`。
+
 ## 注意事项
 
 - 只查询**当前功能点**所需资料，不批量拉取无关文档。

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

@@ -35,6 +35,11 @@ async function callKb(name, args) {
 }
 
 const [mode, arg] = process.argv.slice(2);
+
+// 注意：searchDocuments 返回的 parent 形如 `kms-rag://…/10-官方资源索引#0`，
+// 末尾 `#0` 是块（chunk）标识，属于完整文档标识的一部分。
+// getDocumentsById 需要这个带 `#块号` 的完整标识，原样传入即可；
+// 剥离 `#0` 会导致查不到结果，因此这里对 parent 不做任何改写。
 (async () => {
   if (mode === 'search') {
     const list = await callKb('searchDocuments', { SearchDocumentsReq: { query: arg } });
@@ -45,6 +50,9 @@ const [mode, arg] = process.argv.slice(2);
   } else if (mode === 'doc') {
     const names = arg.split(',').map((s) => s.trim()).filter(Boolean);
     const list = await callKb('getDocumentsById', { GetDocumentsByIdRequest: { names } });
+    if (list.length === 0) {
+      console.error('未返回任何文档。若 names 来自 search 结果，请确认 parent 的 `#<块号>` 片段被原样保留（如 `…#0`）——剥离/改写会导致查不到。');
+    }
     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('---');

package/skills/d2h-dashboard/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: d2h-dashboard
+description: 迁移实时看板：启动本地看板服务器实时查看整个转换流程。progress.json 就绪后由主 Agent 自动启动并打开网页；用户要求“看板”“dashboard”“查看迁移进度/转换流程”“实时看板”时亦触发。本 Skill 只负责启动/复用/停止服务器并把 URL 交给用户，看板能力由 npm 包 d2h-dashboard 决定。
+---
+
+# 迁移实时看板（d2h-dashboard）
+
+服务器与前端全部由 npm 包 `d2h-dashboard` 提供，本 Skill 不内嵌资产，`npx` 一条命令完整启动（服务器 + 前端同进程）：
+
+```bash
+npx --yes d2h-dashboard@latest --dataDir <项目>/.migration [--port 8080] [--host 127.0.0.1]
+```
+
+- `--dataDir` 必填，指向迁移工作区 `.migration`；`--port` 默认 8080，占用自动 +1 重试至 8090；`--host` 默认 `127.0.0.1`。
+- 启动链：npx 拉包并执行 bin → `node …/server/serve.mjs` 常驻，同时托管前端与 `/api/data/*`。
+- 成功后 stdout 固定两行，实际 URL 以第二行为准：`[dashboard] dataDir=<绝对路径>`、`[dashboard] http://<host>:<实际端口>`。
+- 健康检查：`GET /api/data/manifest` 返回 200 且 `root` 等于传入 dataDir（绝对路径规范化比较）。
+
+## 自动启动（迁移会话内）
+
+- `.migration/progress.json` 出现（`progress init` 后）或恢复会话已存在 → 自动启动看板并用默认浏览器打开 URL，不等用户请求；每轮会话执行一次，复用实例不重复启动、不重复打开。
+- 启动或打开失败只记录不阻塞迁移，下次阶段更新重试一次。
+
+## 后台启动与打开浏览器
+
+常驻进程必须后台启动（非交互、明确超时）：
+
+```bash
+# bash
+nohup npx --yes d2h-dashboard@latest --dataDir "$DATA_DIR" > /tmp/d2h-dashboard.log 2>&1 &
+```
+
+```powershell
+# Windows PowerShell 5.1：npx 必须用 npx.cmd（npx.ps1 被执行策略拦截）；
+# 重定向交给脱离的 cmd，禁止 Start-Process -RedirectStandardOutput——会卡死会话（已实测）
+$log = "$env:TEMP\d2h-dashboard.log"
+$arg = "/c npx.cmd --yes d2h-dashboard@latest --dataDir `"$dataDir`" > `"$log`" 2> `"$log.err`""
+Start-Process -FilePath cmd.exe -ArgumentList $arg -WindowStyle Hidden | Out-Null
+Start-Sleep -Seconds 2; Get-Content $log -ErrorAction SilentlyContinue
+```
+
+打开浏览器（Windows 必须 `cmd /c start`，`Start-Process "http://…"` 静默不弹窗，已实测）：
+
+```powershell
+cmd /c start "" "http://127.0.0.1:<port>"     # Windows
+```
+
+```bash
+open "http://…"        # macOS
+xdg-open "http://…"    # Linux
+```
+
+## 复用与停止
+
+- **复用**：启动前探测 8080–8090 `GET /api/data/manifest`（1s 超时），`root` == 目标 dataDir 且 `GET /` 返回 200 才复用该 URL；仅 root 匹配但 `GET /` 非 200 属损坏实例（如资产被删/版本切换残留），按停止规则杀掉后重新启动。root 不匹配跳过（其他流程的服务器）。服务器常驻，会话结束不回收，残留进程属预期。
+- **停止**：仅用户显式要求（「关闭看板」「关闭 XX 项目看板」）才执行，且必须 root 归属校验通过：Windows `Get-NetTCPConnection -LocalPort <port> -State Listen | ForEach-Object { Stop-Process -Id $_.OwningProcess }`（杀 node 真实 PID，cmd 包装 PID 无效）；bash `kill <pid>`。未找到 → 报告未在运行；root 不匹配 → 跳过并说明属于其他流程。

package/skills/d2h-product-family-migration/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: d2h-product-family-migration
+description: 已有可检查的鸿蒙实现时，通过首款 Android、鸿蒙基线与目标 Android 的三方对照，复用真实能力并迁移同源产品或变体的配置、UX、服务商及功能差异。用于第二款及后续产品的增量分析、规划和实施。
+---
+
+# 同源产品增量迁移到鸿蒙
+
+以已有鸿蒙实现为起点，只开发目标需要的差异与基线缺口，同时核对目标的完整行为覆盖。UX 指页面与交互流程。复用的是实际代码与业务契约；每项结论都要能回到源码或执行证据。
+
+本 skill 由 AI 阅读源码、追踪调用与配置、判断差异并实施修改，不附带脚本，不要求专用 CLI、固定 JSON 格式或其他 skill。检索、版本比较、构建和测试使用当前工程已有工具；工具输出为判断提供证据。
+
+## 先确定本次做到哪里
+
+| 用户请求 | 交付边界 |
+|---|---|
+| 理解或分析 | 解释基线、目标关系、可复用能力、差异与未知；默认在答复中交付 |
+| 规划 | 给出有依据的目标覆盖、派生方案、实施顺序和验收条件；默认不创建应用或运行构建，另有验证授权时按其范围处理 |
+| 实施或修复 | 在约定范围内修改真实工程、执行可用验证、处理失败并交付当前结果 |
+
+从现场先查可得信息；只对会改变目标、变更边界或验收结论的缺失信息补问用户。沿以下步骤推进已授权工作，编码与测试可按依赖迭代，无需逐步等待确认。
+
+## 步骤一：固定来源、目标和修改范围
+
+用以下记号区分四个对象，同仓时也分别记录产品上下文：
+
+| 对象 | 需要确定的信息 |
+|---|---|
+| 首款 Android A₀ | 首次迁移的源码、修订、应用模块和有效变体 |
+| 鸿蒙基线 H₀ | 可检查的实际代码、修订及未提交修改、产品配置和已知验证结果 |
+| 目标 Android B₁ | 目标源码、修订、有效变体及本次选定范围 |
+| 目标鸿蒙 H₁ | 输出位置、身份、功能、UX、服务商和允许修改范围 |
+
+从构建声明确认模块、flavor/build type、源集覆盖和依赖的有效组合；一个品牌目录未必是可构建产品。若 Android 只是跨端或 Web 宿主，继续追到实际承载页面、状态与业务的源码。
+
+保留用户已有修改；Android 源工程只读，分析资料使用约定的迁移工作区。实施前确定 H₁ 的输出边界和 H₀ 的恢复方式。
+
+**本步输出：** 来源与目标上下文、任务边界、待确认事项。A₀ 历史修订无法恢复时标未知，仍可直接对照 B₁ 与 H₀；缺少 H₀ 时可继续 Android 差异分析，实际复用前须取得基线。
+
+## 步骤二：核验已有鸿蒙能力
+
+沿目标核心用户任务阅读 H₀ 的入口、导航、业务接口、状态、数据访问和产品装配。优先核实已有索引与测试，只补缺失或失效的证据。
+
+为可复用能力记录：对应 Android 行为、鸿蒙真实实现与调用入口、公开契约、当前验证和已知缺口。报告中的“完成”、同名类或文件存在，都不能单独证明能力可用。
+
+实施任务使用现有命令做与目标相关的最小基线检查；分析、规划沿用可核验记录，并列出后续验证要求。区分历史测试、当前静态判断和当前执行结果。基线缺陷只在目标依赖或本次改动影响时处理。
+
+**本步输出：** 可追溯的复用索引及质量边界。没有旧索引时从实际代码补最小条目，不先重做全仓文档。
+
+## 步骤三：建立完整目标覆盖与三方差异
+
+从 B₁ 在选定范围内的实际入口（包含适用的外部或后台入口）列出用户任务、关键状态、错误与恢复路径，再逐项回答：
+
+1. B₁ 相对 A₀ 的用户可观察行为变了什么？
+2. H₀ 是否真正满足 B₁ 需要的契约，目标装配能否调用？
+
+同时检查构建选择、配置消费者、资源、依赖、协议和数据作用域。目录相同不保证行为相同，目录新增也不证明功能启用。A₀ 较旧时，将上游共同升级与产品专属变化分开记录。
+
+按 [差异判定与记录](references/baseline-and-delta.md) 归类为复用、配置、UX、适配、新增、修复、排除或调查。纯复用项保留简洁映射；差异项展开源码依据、改动范围、依赖及验收。证据不足时保持调查状态。
+
+**本步输出：** 每项已知目标行为都有处置的覆盖表，包括 H₀ 的继承缺口。分析任务据此交付；规划任务还需完成下一步的派生决策。
+
+## 步骤四：选择最小派生方式并实施
+
+按 H₀ 的实际结构选择：已有多产品能力时新增目标装配；接口可复用时补配置或局部抽取；高度耦合且仅需独立派生时复用可追溯源码。保留已验证架构与工具版本，记录共享改动影响的产品。
+
+规划任务写明选择理由、装配边界、实施依赖顺序、目标及首款验收条件后交付。以下修改与执行只在实施范围内进行。
+
+从当前工作区取用需要的源码、资源和构建信息，记录未提交差异；独立副本排除凭据、本机签名秘密和缓存，保留经核实属于真实依赖的预编译库。目标身份、回调、签名和服务注册分别核验，避免覆盖首款配置。
+
+先使目标身份与入口可构建，再跑通一条调用 H₀ 能力的完整路径；之后按依赖实施差异。配置集中在装配处，UX 调用已有业务契约，协议或策略差异放到适配边界。需要共享边界判断时读 [产品装配与复用设计](references/advanced/product-line-design.md)。
+
+资源追到实际消费模块及主题、语言等有效覆盖；保留源文案的语义，避免全局品牌替换。功能裁剪读 [组合与产物验证](references/advanced/packaging-and-verification.md)；平台能力不确定时读 [平台验证探针](references/advanced/platform-probes.md)。这些场景不要求另建配置框架。
+
+**本步输出：** 真实文件、装配入口和目标行为的对应关系，以及当前构建结果。桩、mock、固定返回或不可达代码保留为缺口。
+
+## 步骤五：验证目标、首款及反馈
+
+| 验证对象 | 必须回答的问题 |
+|---|---|
+| 目标完整范围 | 复用与新增任务是否可达，输入、状态和最终业务效果是否正确？ |
+| 本次差异 | 身份、资源、UX、服务绑定、错误、返回和数据隔离是否符合 B₁？ |
+| 受影响首款 | 共享修改是否保持原有契约？首款既存故障与本次回归是否区分？ |
+| 产物 | 当前目标是否正确？要求排除的功能及专属依赖是否确实未被打包？ |
+
+按变更影响选择测试，复用适用用例；H₁ 的装配、关键共享路径与所有差异仍需当前验证。共享代码变化时，在受影响首款的当前构建上回归；引用历史结果时说明适用依据。每次结果关联源码、有效配置、产物、环境和实际执行证据。
+
+失败时按 [行为验证与反馈闭环](references/advanced/behavioral-verification.md) 确认实际页面和状态，从 B₁ 源码确定预期，再修复、重验失败链并回归影响路径。构建、主机测试、设备验证和用户确认分别记录。
+
+**本步输出：** 实际结果、失败归属及未验证项。设备或外部账号不足只阻塞依赖它的验证；未执行记 `not-run`，不能写通过。用户验收在范围内时，反馈与重验也须关联当前产物。
+
+## 步骤六：交付并更新复用索引
+
+沿用已有等价记录，或使用 [增量记录模板](assets/incremental-plan.template.md) 组织交付；小型任务可在同一份记录中合并章节，无需额外建库或生成全量页面规格。
+
+交付说明本次范围、真实变更、当前证据、未决项及影响。将核验后的能力、适用产品和已知缺口更新到复用索引；新增产品专属能力保留其归属，下一款再选择合适基线。项目路径、业务常量与一次性修复留在项目记录中。
+
+**完成判断：** 分析或规划须给出可评审结论及未知；实施须有真实实现，并按约定范围完成当前验证。未跑的必需验证或未解决的目标缺陷保持未完成；约定的用户验收尚未完成时，保留该项待验状态。
+
+## 与宿主流程配合
+
+宿主已有调度、计划或验收协议时，按 [宿主交接](references/advanced/existing-skill-integration.md) 传递差异与证据，保留其状态所有权。本 skill 的记录不自动证明满足宿主门禁。
+
+维护本 skill 时，可用 [行为评审案例](tests/markdown-cases.md) 检查决策质量；案例不是迁移任务的必经步骤，也不证明应用验收通过。

package/skills/d2h-product-family-migration/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "同源应用增量转鸿蒙"
+  short_description: "三方对照已有实现与目标行为，复用能力并增量迁移同源产品的配置、UX 与功能"

package/skills/d2h-product-family-migration/assets/incremental-plan.template.md

@@ -0,0 +1,55 @@
+# 同源产品增量迁移记录
+
+填写本次事实，缺少证据写“未知”或“未执行”；已有等价记录可沿用。按任务规模合并或省略不适用章节，不把模板字段当作已取得的证据。
+
+## 范围与输入
+
+| 对象 | 路径、修订、有效产品上下文及证据 |
+|---|---|
+| 首款 Android A₀ | 首次迁移来源；历史修订未知时注明 |
+| 鸿蒙基线 H₀ | 实际实现、当前修改、构建/依赖及已知质量 |
+| 目标 Android B₁ | 本次选定模块、变体与功能范围 |
+| 目标鸿蒙 H₁ | 输出位置、身份、UX、服务商和功能选择 |
+
+本次请求是分析、规划还是实施：
+
+允许修改范围、首款保护方式、资料位置及适用宿主协议：
+
+## 基线与复用索引
+
+| 能力 / 用户结果 | Android 语义依据 | H₀ 真实实现、契约与装配 | 适用产品、已有验证与缺口 | 本次复核 / 待验范围 |
+|---|---|---|---|---|
+
+## 目标覆盖与差异
+
+| ID / 目标行为 | A₀→B₁ 变化及源码依据 | H₀ 证据 / 缺口 | 处置与理由 | 复用 / 修改位置 | 依赖及影响产品 | 验收与当前状态 |
+|---|---|---|---|---|---|---|
+
+复用项也保留映射；排除项写范围依据；拟新增文件注明“拟新增”。上游版本变化与产品差异分开，证据不足项写待调查问题和取证路径。
+
+## 派生方式与实施顺序
+
+记录选择的最小结构变化、目标入口与共享能力调用，按依赖列出差异及受影响首款回归。仅在需要功能裁剪时说明实际构建依赖和最小打包边界。
+
+## 验证结果
+
+| 对象 / 断言 | 当前源码、有效配置与产物标识 | 实际命令 / 环境 | 结果 | 证据或未执行原因 |
+|---|---|---|---|---|
+| 基线相关检查 | | | not-run | |
+| 目标共享路径与完整范围 | | | not-run | |
+| 目标特有差异 | | | not-run | |
+| 受影响首款回归 | | | not-run | |
+| 要求的打包包含 / 排除 | | | not-run | |
+
+不适用的项说明原因；历史证据与当前结果分开记录。
+
+## 反馈与重验
+
+用户测试在范围内时记录当前产物的反馈；没有结果时保持待验。
+
+| 反馈 / 产物 | 实际页面、前置与动作 | 期望及依据 / 实际结果 | 原因与实际修复 | 重验、影响回归与用户确认 |
+|---|---|---|---|---|
+
+## 交付与后续复用
+
+写明已分析、已实现、已验证的范围，未决项及用户影响。更新可复用能力、适用产品和来源，不将产品专属能力归给原基线。流程经验只保留有证据支持的通用判断。

package/skills/d2h-product-family-migration/references/advanced/behavioral-verification.md

@@ -0,0 +1,59 @@
+# 行为验证与用户反馈闭环
+
+本文件用于目标路径验收、用户反馈复现和修复审查。它不规定测试框架、脚本语言或固定用例数；使用当前工程实际支持的工具。检查范围由目标任务、差异与变更影响决定。
+
+## 1. 先确认实际现场
+
+一条失败反馈最少需要：被测产品/产物、前置状态、入口与动作、期望结果、实际结果。路径或状态不明时先查看当前界面、控件树、可用日志与调用链，再向用户补问最关键的缺失信息。不要要求用户提供密码、验证码等与定位无关的秘密。
+
+用户描述的任务名未必等于正在显示的页面。先判断：
+
+| 实际现象 | 优先核对 |
+|---|---|
+| 前一步请求成功，仍停在原页面 | 响应分流、导航栈、路由注册、目标条件与立即返回/关闭 |
+| 目标页出现，控件无法操作 | 可点击/可编辑状态、遮挡层、焦点、键盘与输入控件的真实范围 |
+| 可以输入，显示为空或随后清空 | 控件值、观察状态、回调回写、格式化/过滤及重绘 |
+| 交互正常，业务结果错误 | 参数、身份/服务绑定、状态机、错误与异步结果归属 |
+| 业务成功，返回/重启后结果丢失 | 导航返回契约、保存时机、持久化、账号/租户作用域与恢复 |
+
+上表是定位顺序，不是自动归因。收到外部消息或服务端成功，只证明该步骤；不能证明后续页面已可达、输入可用或任务已完成。
+
+## 2. 从 Android 证据确定预期
+
+从目标有效变体沿当前入口阅读处理器、被调 helper、状态持有者和实际消费者。必要时核对 Manifest、源集替换、生命周期、异步回调及运行行为。
+
+尤其区分：
+
+- 声明了候选项、具备底层实现，以及当前产品真正展示的选项。
+- 请求已发出、请求成功、状态已保存，以及 UI 已迁移到可操作的下一状态。
+- 打开新页面、替换当前页、清空历史，以及返回后恢复原输入。
+- 公开方法名暗示的意图，与 helper/生命周期实际执行的行为。
+
+未看到关闭或替换当前页的证据时，不把 Android 的“启动目标页”推断为“启动并关闭原页”。有返回结果的流程同时核对结果交接与表单保留。目标端使用适合其平台的实现，但用户可观察的返回与数据结果应保留。
+
+## 3. 按任务效果选择断言
+
+| 任务类型 | 有意义的验证 | 不足以证明完成 |
+|---|---|---|
+| 身份与资源 | 当前包身份、实际呈现、语言/主题、图像比例及受影响模块 | 配置字段存在、只看入口图标 |
+| 输入与编辑 | 聚焦后正常输入、删除/修改、适用时粘贴与过滤、提交读取真实输入 | TextInput 文件存在、回调单测通过 |
+| 多步骤流程 | 每一步的状态变化、目标页停留且可操作、返回与取消、最终业务效果 | 前一步成功、短暂出现目标页 |
+| 异步提交 | 正确参数、等待/防重复、服务结果、失败重试与离开后结果归属 | 仅请求函数被调用或界面显示成功 |
+| 数据保存 | 返回/重启后的真实结果、账号/环境切换隔离 | 内存值变化、固定样例结果 |
+| 可选功能排除 | 实际构建图和包内容，结合不可达入口核验 | 隐藏按钮、运行时 flag=false |
+
+并非每个控件都机械套用所有输入方式；选择当前契约支持且可能受变更影响的场景。共享能力可复用已有测试，但目标装配与关键路径仍需当前产物验证。
+
+## 4. 修复与重验
+
+1. 用当前证据确定失败归属，登记为产品差异、装配、继承缺陷、测试资产或外部条件。没有证据的保留调查，不先假定是平台限制。
+2. 将期望结果逐项关联到 Android 依据，再编写或更新回归断言。若后续源码推翻了原假设，同时纠正 Spec/测试预期，不能强迫实现满足错误测试。
+3. 能复现时保留修复前的失败；执行最小修复，保留未影响的产品与功能。不要通过替代控件、测试入口或假业务结果制造通过。
+4. 先重验原失败链，再验证受影响的返回、错误、持久化和共享契约。构建、主机测试、设备验证与用户确认分别记录，不能相互替代。
+5. 绑定本次源码与产物保存结果。失败未重验、必需设备验证未跑或约定的用户验收未完成时保留相应待验状态；功能验收停止时明确剩余项。
+
+## 5. 将反馈用于 Skill 改进
+
+把流程失误归纳为可迁移的判断，例如“先确认真实页面再归因”“沿实际消费者判定范围”“核验返回栈契约”“输入需验证完整值链”。说明适用条件和证据边界。
+
+品牌值、具体控件 ID、项目路径、私有协议与一次性修复脚本留在项目记录。一个项目的失败不意味着所有 Android 应用都需要同一个依赖、架构、测试入口或文件格式。新增规则应改善同类判断，避免重复已有流程或扩大任务范围。

package/skills/d2h-product-family-migration/references/advanced/existing-skill-integration.md

@@ -0,0 +1,30 @@
+# 宿主流程交接
+
+仅在本 skill 由已有迁移流程编排时读取。宿主指调用本 skill 的主 Agent、工具链或项目工作流；本文件不要求具体 skill、CLI、账本版本或目录布局。
+
+## 先读当前契约
+
+从宿主当前指令和实际配置确认：任务范围、执行模式、计划身份、允许修改的位置、调度规则、状态所有权及完成门槛。只读与本次任务有关的规范，不按历史名称推断协议。
+
+## 交接内容
+
+| 交给宿主什么 | 如何避免重复或状态混淆 |
+|---|---|
+| A₀/H₀/B₁/H₁ 与有效产品上下文 | 分开来源修订、目标身份和未提交修改 |
+| 复用索引与完整目标覆盖 | 沿用可核验的已有事实；复用项仅补映射和目标验证 |
+| 差异、前置与变更影响 | 对接合法目标任务，保留原产品契约和调度边界 |
+| 当前实现、产物及执行证据 | 引用实际结果；宿主按自己的协议更新状态 |
+
+宿主记录容纳不了这些信息时，在增量记录中建立关联，不擅自扩展受管 schema，也不重置已有执行历史。首款的任务 ID、计划绑定或通过记录不能冒充新目标的合法状态。
+
+## 配置型任务与缺失输入
+
+没有页面变化时，由宿主确定配置或资源变更的登记方式并提供合法输入；不为填满页面队列制造重开发任务。
+
+若强制协议所需的目标计划、绑定或执行环境缺失，明确缺什么、由谁补齐、影响哪些后续动作；继续独立可做的分析。只有宿主允许独立执行时，才按本 skill 的增量记录实施，且如实说明未满足的宿主门槛。
+
+平台实验和局部验证仍遵守宿主的调度规则。新记录不扩大外部操作权限，已有授权也不因换一种记录格式而失效。
+
+## 加载边界
+
+技能内容可由用户显式调用或由支持它的宿主发现。目录存在不证明安装、路由或自动加载已配置；这些变更只在用户要求接入时处理。

package/skills/d2h-product-family-migration/references/advanced/packaging-and-verification.md

@@ -0,0 +1,43 @@
+# 功能组合与产物验证
+
+仅在目标涉及功能选择或构建期裁剪时读取。复用真实构建配置和装配方式；不要求额外组合清单、解析器或代码生成器。
+
+## 先明确排除要求
+
+| 要求 | 足够支持该结论的证据 |
+|---|---|
+| 入口隐藏 | 当前产品无相应菜单、路由或其他可达入口 |
+| 运行时禁用 | 相关执行受有效策略限制，实现可能仍在包中 |
+| 构建期排除 | 当前构建图排除实现及专属依赖，最终包检查与其一致 |
+
+从用户目标确定需要哪一层。只有要求物理裁剪时才作包内容排除承诺。
+
+## 沿真实依赖核对组合
+
+从当前目标选择的功能、UX 和适配器出发，追踪代码 import、模块依赖、传递 SDK、资源、权限、原生库与初始化链，检查：
+
+1. 所选功能的前置完整，没有冲突或循环；未选功能不会被共享聚合模块重新引入。
+2. UX 所需能力确实存在，目标用户任务有可操作入口。
+3. 所需业务和平台接口绑定正确，未选功能不会带入专属适配器。
+4. 身份、资源、权限、初始化和构建目标来自同一个有效产品上下文。
+
+声明为“共享”的模块也须检查内容归属。如果所需与排除功能被封装在同一不可拆库中，说明最小共同打包单元及影响；必要的拆分属于实施范围决策，不能靠改标签宣称裁剪。
+
+## 验证实际产物
+
+使用当前工程支持的构建、依赖导出和产物分析工具，记录实际命令与限制，不臆造通用解包命令。
+
+| 层次 | 核对内容 |
+|---|---|
+| 源码与配置 | 所选实现、入口和依赖确实按目标生效 |
+| 实际构建图 | 有效源集、模块、三方 SDK、原生库及传递依赖 |
+| 当前产物 | 身份、模块、权限、资源、代码及库的实际归属 |
+| 当前运行 | 所选功能可用，排除功能无入口、深链或后台激活路径 |
+
+所选能力存在与未选专属资产排除分别留证。包大小减少、搜索不到类名或运行时 flag 关闭都不足以单独证明物理裁剪；优化、混淆和共享字节码可能改变表象。工具不能识别的部分保留未验证。
+
+## 多组合验证
+
+只验证本次承诺交付的组合；每个交付组合核对实际构建、身份和关键选择/排除。按真实差异覆盖不同 UX、服务商、权限及强交互功能，等价测试可说明依据后复用，不默认穷举所有潜在组合。
+
+在同一增量记录中关联组合、源码修订、产物标识和构建/包检查/运行结果，无需额外创建覆盖矩阵文件。当前目标通过不外推为整个家族所有组合通过。

package/skills/d2h-product-family-migration/references/advanced/platform-probes.md

@@ -0,0 +1,26 @@
+# 平台验证探针
+
+仅在某项目标能力的鸿蒙可行性尚不确定时读取。以当前 SDK、工具、设备和服务证据核实能力，不预设特定业务或第三方方案。
+
+## 先把不确定性写成可验证问题
+
+记录 Android 实际契约、H₀ 已有实现、仍未知的条件和失败影响。查阅与目标版本匹配的官方资料及现有代码，选择能裁决该问题的最小实验。
+
+| 边界 | 要核验的行为 |
+|---|---|
+| UI、生命周期与导航 | 冷/热入口、状态恢复、返回栈、弹层、结果交接与取消 |
+| 网络与认证 | 协议格式、流式/字节语义、证书、错误、超时、回调注册及令牌刷新 |
+| 存储与状态 | schema、事务、迁移、排序、重启恢复、账号/环境隔离 |
+| 系统与设备能力 | 权限拒绝/撤销、进程回收、后台调度、重启、服务地区与设备限制 |
+| 外部应用与服务 | 深链、导入导出、授权和远端结果，外部依赖不可用时的行为 |
+| 原生库 | 来源、目标 ABI、系统依赖、加载链及接口重写或重编需求 |
+
+只取与当前差异相关的行。相同 API 名称、CPU 架构或 SDK 品牌不证明契约兼容；Android 的注册与二进制也不能直接当作鸿蒙授权或可用实现。
+
+## 让实验回答实际问题
+
+优先在 H₀ 的实际边界做最小纵向验证：目标端调用、真实平台/服务行为、结果回到业务契约。探针范围应足以裁决风险，不先重写整项功能；实验代码与正式接入分别标明。
+
+保存版本、环境、输入条件、实际结果和结论边界。宿主机或模拟实现通过只能支持相应层级；依赖设备、服务注册或系统调度的问题仍需对应证据。
+
+若平台无法等价满足，说明差异、可用替代及用户影响；改变产品行为或超出原范围的方案交由用户决定。无依据时保留调查状态，继续不依赖该结论的工作。