@harmonyos-arkts/d2h 0.1.20 → 0.1.22

package/skills/d2h-product-family-migration/references/advanced/product-line-design.md

@@ -0,0 +1,40 @@
+# 产品装配与复用设计
+
+仅在目标涉及 UX、服务商或共享边界变化时读取。先核对 H₀ 的真实接口，抽取程度由本次差异决定。
+
+## 选择最小结构变化
+
+| 当前基线 | 合适的派生方式 |
+|---|---|
+| 已有多产品配置或薄入口 | 新增目标身份、资源和装配，调用原有实现 |
+| 单应用，已有稳定业务接口 | 复用接口，补目标配置或局部抽取 |
+| 高度耦合，仅需一次独立派生 | 在独立目标复用必要源码，记录来源和后续同步边界 |
+| 目标契约确实不同 | 保留可复用部分，为差异增加适配器、策略或业务实现 |
+
+独立副本不等于共享模块；服务商数量也不决定模块数量。模块拆分应解决真实依赖、变化频率或打包问题。
+
+## 按变化原因确定职责
+
+| 边界 | 负责什么 |
+|---|---|
+| 业务能力 | 实体、规则、状态转换、事务、取消、重试和错误结果 |
+| UX | 页面组织、交互状态、导航与呈现，调用业务能力 |
+| 服务商适配 | 认证、协议、字段/单位/错误映射及确有差异的策略 |
+| 平台适配 | 目标系统的网络、存储、设备、后台和原生库接口 |
+| 产品装配 | 选择身份、配置、UX、功能和适配实现 |
+
+相同后端可能有不同策略，不同协议也可能满足相同领域契约。从输入、状态变化、数据效果、失败与恢复判断能否共享，不依据页面名、类名或目录相似度。
+
+优先沿用现有分层。仅当真实差异要求时增加边界，不要求把所有层改造成新模块。
+
+## UX 与业务共享
+
+视觉差异先用资源或主题覆盖；流程变化再调整布局、导航或局部 ViewModel；页面树显著不同时可以独立 UX，仍调用共享用例。业务状态与持久化规则应有明确真源。
+
+检查每个目标任务是否有真实入口、调用链和结果呈现。配置宣称支持某能力，或能力已被编译，都不能证明用户能使用它。
+
+## 装配和数据作用域
+
+在目标装配处选择后端、策略和功能，减少业务内部按展示品牌分支。按实际系统确定账号、租户、环境或区域的命名空间；独立应用沙箱不能代替应用内账号隔离。
+
+若支持运行时切换上下文，核对旧请求、订阅、会话、缓存与待办的解绑或重绑定，避免旧结果写入新上下文。跨平台用户数据搬迁需独立的导出、同步或导入契约，不能假设可直接读取 Android 私有数据。

package/skills/d2h-product-family-migration/references/baseline-and-delta.md

@@ -0,0 +1,50 @@
+# 差异判定与记录
+
+在主流程步骤三使用。本文件定义判断依据和最少记录内容；字段可融入现有文档或账本，不要求机器格式。
+
+## 按行为和真实实现选择处置
+
+| 处置 | 判定依据 | 实施与验收重点 |
+|---|---|---|
+| `reuse` 复用 | H₀ 已有可达实现，契约符合 B₁，证据适用于当前上下文 | 绑定真实接口，验证 H₁ 装配和关键共享路径 |
+| `configure` 配置 | 差异是身份、资源或参数，现有实现已支持 | 核对实际消费者、目标身份和授权绑定 |
+| `ux` 交互 | 任务呈现或流程不同，底层业务契约满足 | 复用业务能力，验证新流程及返回、取消 |
+| `adapt` 适配 | 协议、服务商、平台或策略变化，领域契约可保持 | 验证字段、错误、状态、权限及数据作用域 |
+| `implement` 新增 | B₁ 新增所需行为，H₀ 不具备 | 补真实能力及可达入口，验证完整业务结果 |
+| `repair` 修复 | 目标与首款业务相同，但 H₀ 缺失、mock、不可达或语义错误 | 登记继承缺口；共享修复回归受影响产品 |
+| `exclude` 排除 | 有依据证明该功能不在目标范围 | 保持首款能力；若要求物理裁剪，另验构建和包内容 |
+| `investigate` 调查 | 任一侧证据不足，尚不能作出上述判断 | 写明待核实问题、依赖它的项和下一条取证路径 |
+
+一项可同时有多个维度，按可独立实施和验收的部分拆分；例如身份回调属于配置，响应结构变化属于适配。上游升级单独注明来源，不按品牌目录或文件名自动归类。
+
+## 复用索引
+
+每项能力保留：
+
+- 稳定业务标识及用户结果；A₀/B₁ 的语义依据和有效产品上下文。
+- H₀ 实际实现、公共接口、调用入口、装配及数据作用域。
+- 来源修订、工作区差异、影响结论的依赖与配置。
+- 已有用例及实际被测产物、环境、结果、已知缺口和适用产品。
+- 本次复核结论，以及还需验证的部分。
+
+缺少历史修订或旧索引时如实标注，从可读源码建立当前记录。只有依赖旧修订才能裁决的问题受阻；B₁ 与 H₀ 的直接契约对照可以继续。
+
+## 目标覆盖表
+
+| 内容 | 需要回答的问题 |
+|---|---|
+| 目标行为与范围 | 哪个产品、变体、前置状态、动作和用户结果？排除依据是什么？ |
+| Android 证据 | B₁ 的入口、配置消费者、处理器与效果在哪里？相对 A₀ 有何变化？ |
+| 鸿蒙证据 | H₀ 哪个真实接口满足它？缺项、失败或未知的依据是什么？ |
+| 处置与理由 | 为什么复用、配置、适配或开发？是否涉及版本漂移或继承缺口？ |
+| 实施位置与影响 | 复用和修改哪些真实文件？依赖什么？影响哪些已有产品？ |
+| 验收与结果 | 用什么断言验证目标及受影响首款？对应哪个当前产物和实际证据？ |
+| 状态与未决项 | 哪些已分析、已实现、已验证？哪些调查、失败或未执行？ |
+
+尚未创建的文件注明“拟新增”，不能作为已有实现证据。纯复用项可以只引用索引和目标验证，避免重复规格；已知目标任务仍须全部有处置。
+
+## 处置与结果分开
+
+`reuse` 表示实现选择，不表示 `passed`；`exclude` 表示范围选择，不表示包中已无代码。状态沿用宿主语义；独立记录可分别写分析、实现、构建、行为验证与用户确认，尚未执行记 `not-run`，不必另造状态机。
+
+提交号、文件哈希或目录 diff 可帮助确定需复核范围，但文件未变不证明依赖、配置、B₁ 行为和环境未变。测试生成数、文件行数或文档完成率不能代表目标行为覆盖。

package/skills/d2h-product-family-migration/tests/markdown-cases.md

@@ -0,0 +1,76 @@
+# 行为评审案例
+
+用于维护本 skill 的通用合成案例，不描述真实项目或应用验收结果。评估时先给请求与原始输入，让评估者从 `SKILL.md` 按需阅读参考，完成答复后再对照文末审查要点。只用所给事实，不访问未提供的工程或设备，不生成应用文件。
+
+## 案例一：仅配置变化的规划
+
+请求：已有首款鸿蒙应用，请规划同源第二款，业务和页面保持一致，只改身份、品牌资源和认证回调。本次只要方案。
+
+原始输入：
+
+- A₀ 与 B₁ 的业务实现及依赖相同，有效变体已确定。
+- H₀ 有实际可达的共享业务接口；报告中的通过结果来自旧修订。
+- 当前工作区包含用户未提交的共享主题修复，构建配置内有本机签名秘密。
+- 目标身份已确定，目标平台的回调登记尚未完成，设备暂不可用。
+- 宿主要求合法的目标计划身份，尚未提供配置型任务的登记方式；没有授权独立实施。
+
+## 案例二：跨端入口与继承缺口
+
+请求：规划同源轻量产品，保留首款，复用现有鸿蒙业务，不重构整个家族。
+
+原始输入：
+
+- Android 为跨端应用，原生目录只是宿主。选定入口启用查询和编辑；导出只在其他入口挂载。
+- A₀ 历史修订未知；当前首款与目标的有效构建上下文已知。
+- 首款查询返回 `records:[{id,label}]`，目标返回 `items:[{key,title}],cursor`。游标后续用法未提供。
+- H₀ 实际查询实现解析 `response.records`，当前有真实可达入口；编辑接口仍返回固定成功，未持久化。
+- 目标与当前首款保存后都要求返回列表并显示真实修改；最新主机测试使用模拟数据，设备结果来自更旧产物。
+- Android 的公共依赖仍含导出库，鸿蒙对应依赖情况尚未知。
+
+## 案例三：选择功能与物理裁剪
+
+请求：目标只交付基础功能，要求可选功能及其专属 SDK 不进入安装包；判断目前能否验收。
+
+原始输入：
+
+- 目标菜单和导航已移除可选功能，运行时 flag 也为 false。
+- 基础与可选实现仍由同一聚合模块导出，目标构建实际依赖该聚合模块和专属 SDK。
+- 当前包比旧包小，但没有能识别实现归属的包分析结果；设备只测试了启动。
+- 首款仍需保留该可选功能。
+
+## 案例四：反馈中的真实页面
+
+请求：用户反馈上一步成功，但下一步无法输入，请给出定位与修复重验顺序。
+
+原始输入：
+
+- 当前控件树仍是原表单，没有目标输入控件。
+- 目标端成功处理调用 helper 同步 push 下一页，随后调用方 pop。
+- Android 成功处理器只打开下一页，相关 helper 与生命周期没有关闭原页的证据。
+- 另一条路径的输入控件另有状态回写缺陷，尚无证据说明用户已到达该页面。
+- 用户尚未测试任何修复后的产物。
+
+## 案例五：已具备依据的轻量实施
+
+请求：在已指定的目标目录派生第二款，采用现有架构继续实施，保留首款。
+
+原始输入：
+
+- 三方代码与有效上下文均可读，源码显示只有资源和装配参数差异，H₀ 接口真实且适用。
+- 输出位置、目标身份、共享改动范围、恢复方式及工具命令均已确定，没有额外宿主门禁。
+- 设备与构建环境可用，目标所需签名和服务登记已经就绪。
+- 尚未执行本次构建、目标功能验证及受影响首款回归；没有本次用户确认。
+
+## 审查要点
+
+仅在评估者完成答复后读取。检查判断与证据边界，不要求固定措辞、章节或字段名。
+
+| 案例 | 应体现的决策 |
+|---|---|
+| 一 | 交付配置型派生方式、真实变更范围、实施顺序和验收；保留当前主题修复；独立副本排除签名秘密；由宿主补登记方式；不制造页面重开发或伪造目标计划；规划阶段不创建工程；设备与登记缺口不阻止规划 |
+| 二 | 追到跨端业务与消费者；旧 A₀ 保持未知；查询协议需适配，游标用途待调查；编辑固定成功属于继承缺口修复；不把所有差异当产品新增；导出不在目标入口，物理打包另查；不由 Android 依赖推断鸿蒙依赖；历史或模拟测试不算当前目标通过 |
+| 三 | 尚不能验收物理裁剪；沿实际依赖解除回引或说明不可拆边界及范围决策；保留首款能力；目标构建图、包内容及所选功能结果仍待验证；不以菜单、flag 或包大小替代证据 |
+| 四 | 优先核对把新页立即弹出的导航链；返回栈预期依据 Android 实际行为；另一输入缺陷单独记录；先验页面保持与可操作，再验输入及最终效果；用户确认仍待取得 |
+| 五 | 信息充分时继续真实实施与验证，复用已有接口和测试；不增加无依据的确认、全家族重构、专用脚本或新配置框架；未经执行不先填通过；区分当前测试和用户确认，不将未要求的用户验收新增为完成门槛 |
+
+这些案例验证流程决策，不替代真实源码理解、构建、设备测试或用户验收。实际评审结果保存在维护任务中，不将一次评审的结论写成永久通过状态。

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

@@ -0,0 +1,41 @@
+---
+name: d2h-spec-develop
+description: Implement assigned Android-to-HarmonyOS Specs with source-grounded code, managed build and test evidence, scoped commits, and implementation handoff. Use for page or incremental Spec development under the caller's dispatch.
+---
+
+# Spec 实施
+
+按调用方指派的 Spec 范围实施 HarmonyOS 页面与业务能力。worker 的创建、每批 Spec/页面数量、执行顺序和逐页复核由主 Agent 或调用方决定，本 Skill 不另设数量或调度限制。
+
+
+
+输入包含增量 v2 计划时，按公共 `d2h workflow contract dispatch` 核对固定 spec_ids、计划/范围版本及批次绑定；绑定缺失或冲突时返回具体缺口。页面 Spec 输入按调用方给定的页面范围执行，不要求先生成 v2 计划。
+
+返回真实实现、证据和未解决请求，由调用方维护执行账本、阶段状态及报告并决定验收。
+
+# Spec 实施与结果交接
+
+只处理输入明确指派的 Spec。先核对计划/范围版本、Git 基线、允许路径和成员；存在冲突时返回具体缺口，不覆盖用户修改。派发数据字段见公共 `d2h workflow contract dispatch`，本 Skill 不要求任何规划技能先运行。
+
+## 理解与实施
+
+1. 阅读页面 spec.md 中当前 spec_id/check 的完整行为、异常、操作、源码依据与实现范围，定向追踪 Android 入口、状态、数据副作用和导航。页面共享摘要用于定位，不能代替源码理解。
+2. 沿用已给定的目标模块、目录、资源规范和状态/生命周期边界。接口缺失、所有权不清或与实际代码冲突时，返回带源码定位的 requiredInputs / planChangeRequests，不自行改方案或扩大范围。
+3. 同一窗口沿用页面上下文，逐成员实施。提供者形成实际代码后返回真实符号、路径、参数/错误语义与生命周期说明，等待调用方确认当前能力再实施消费者；不能用规划签名猜接口。
+4. 实现真实可达的 UI、导航、业务状态、数据效果和要求的失败路径。每个 check 对应实际行为、稳定语义定位和结果断言；不得添加测试替代控件、固定成功值、吞错或不可达页面。
+5. 当前范围涉及平台 API、原生库、身份/资源/i18n 等未知问题时，返回领域请求：问题、来源、当前尝试、所需结论及消费者。调用方提供结论后继续，不在此加载其他技能。
+
+## 构建、检查与提交
+
+- 依据输入项目配置运行已授权的 `droid2hmos build harmony <ANDROID_PROJECT>`，命令非交互且有超时，保留真实命令、退出状态、时间、日志、HAP 路径和哈希。
+- 已提供可执行测试资产且授权本次检查时，可直接运行受管 CLI，保留实际断言、设备、执行数、原始报告和 managedEvidence。缺少测试设计、资产、设备或需共享安装窗口时返回 verificationRequests，不能只写测试未跑却报告通过。
+- 即时契约和高风险检查必须有实际结果，缺口交调用方组织验证；低风险合批待测明确列出，不暗示已验收。静态检查/服务探针不能代替正式设备证据。
+- 修复本范围实现或检查缺陷，保留现有理解与原始失败证据。真实外部问题在诊断和有限重试后可返回 blocked；实现错误不能改写为平台差异。
+- 仅暂存当前实现、资源、必要共享修改和实际测试资产。构建及已要求的即时检查通过后创建或交回作用域提交；允许明确标注待合批验证的实现提交，不把它称为验收提交。残留本任务修改、用户文件及其他任务修改分别列明，不一并提交。
+- 实现提交与后续状态/证据记录分开，由调用方维护后者，避免提交 ID 自引用。当前候选变化后的旧 HAP/证据是否失效由公共运行时维护，不把旧结果绑定新代码。
+
+## 返回
+
+逐 spec_id/check 返回：实际修改与可达行为、接口与消费者、提交/源码身份、构建和测试证据、未执行检查与原因、剩余缺口、请求及用户修改保留情况。耗时未知填 null，不编造节省比例。
+
+不选择下一个批次，不更新执行账本、阶段状态或任何报告。调用方独立核对实现、断言、当前候选、HAP 和设备身份后记录状态与决定验收。

package/skills/d2h-spec-develop/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "HarmonyOS Spec Development Loop"
+  short_description: "按指派 Spec 完成鸿蒙实现、受管构建检查、作用域提交与证据交接"
+  default_prompt: "Use $d2h-spec-develop to implement the assigned HarmonyOS Specs and return scoped code, build and test evidence, commits, and unresolved requests."
+
+policy:
+  allow_implicit_invocation: true

package/skills/d2h-spec-develop/references/worker-workflow.md

@@ -0,0 +1,26 @@
+# Spec 实施与结果交接
+
+只处理输入明确指派的 Spec。先核对计划/范围版本、Git 基线、允许路径和成员；存在冲突时返回具体缺口，不覆盖用户修改。派发数据字段见公共 `d2h workflow contract dispatch`，本 Skill 不要求任何规划技能先运行。
+
+## 理解与实施
+
+1. 阅读页面 spec.md 中当前 spec_id/check 的完整行为、异常、操作、源码依据与实现范围，定向追踪 Android 入口、状态、数据副作用和导航。页面共享摘要用于定位，不能代替源码理解。
+2. 沿用已给定的目标模块、目录、资源规范和状态/生命周期边界。接口缺失、所有权不清或与实际代码冲突时，返回带源码定位的 requiredInputs / planChangeRequests，不自行改方案或扩大范围。
+3. 同一窗口沿用页面上下文，逐成员实施。提供者形成实际代码后返回真实符号、路径、参数/错误语义与生命周期说明，等待调用方确认当前能力再实施消费者；不能用规划签名猜接口。
+4. 实现真实可达的 UI、导航、业务状态、数据效果和要求的失败路径。每个 check 对应实际行为、稳定语义定位和结果断言；不得添加测试替代控件、固定成功值、吞错或不可达页面。
+5. 当前范围涉及平台 API、原生库、身份/资源/i18n 等未知问题时，返回领域请求：问题、来源、当前尝试、所需结论及消费者。调用方提供结论后继续，不在此加载其他技能。
+
+## 构建、检查与提交
+
+- 依据输入项目配置运行已授权的 `droid2hmos build harmony <ANDROID_PROJECT>`，命令非交互且有超时，保留真实命令、退出状态、时间、日志、HAP 路径和哈希。
+- 已提供可执行测试资产且授权本次检查时，可直接运行受管 CLI，保留实际断言、设备、执行数、原始报告和 managedEvidence。缺少测试设计、资产、设备或需共享安装窗口时返回 verificationRequests，不能只写测试未跑却报告通过。
+- 即时契约和高风险检查必须有实际结果，缺口交调用方组织验证；低风险合批待测明确列出，不暗示已验收。静态检查/服务探针不能代替正式设备证据。
+- 修复本范围实现或检查缺陷，保留现有理解与原始失败证据。真实外部问题在诊断和有限重试后可返回 blocked；实现错误不能改写为平台差异。
+- 仅暂存当前实现、资源、必要共享修改和实际测试资产。构建及已要求的即时检查通过后创建或交回作用域提交；允许明确标注待合批验证的实现提交，不把它称为验收提交。残留本任务修改、用户文件及其他任务修改分别列明，不一并提交。
+- 实现提交与后续状态/证据记录分开，由调用方维护后者，避免提交 ID 自引用。当前候选变化后的旧 HAP/证据是否失效由公共运行时维护，不把旧结果绑定新代码。
+
+## 返回
+
+逐 spec_id/check 返回：实际修改与可达行为、接口与消费者、提交/源码身份、构建和测试证据、未执行检查与原因、剩余缺口、请求及用户修改保留情况。耗时未知填 null，不编造节省比例。
+
+不选择下一个批次，不更新执行账本、阶段状态或任何报告。调用方独立核对实现、断言、当前候选、HAP 和设备身份后记录状态与决定验收。

package/skills/{d2h-page-spec-generate → d2h-spec-generate}/SKILL.md

@@ -1,10 +1,19 @@
 ---
-name: d2h-page-spec-generate
-description: Generate an AI-authored pages.json plan and page-scoped Android-to-HarmonyOS spec.md files from migration Facts, `.migration/utg/page.json`, source code, and existing HarmonyOS implementation, then build batch_report.md with the bundled renderer. Use when pages, dialogs, sheets, or page modes need evidence-backed development specifications and ordered execution records without copied UI artifacts.
+name: d2h-spec-generate
+description: Generate detailed Android-to-HarmonyOS spec.md from a selected versioned incremental plan, or use the original standalone page-plan/v1 mode. In from-plan mode preserve scope, IDs and waves and return revision requests; never write the input plan or execution ledger. Original standalone mode generates pages.json and initial batch_report.json from migration Facts, `.migration/utg/page.json`, source code, and existing HarmonyOS implementation, then build batch_report.json with the bundled renderer. Use when pages, dialogs, sheets, or page modes need evidence-backed development specifications and ordered execution records without copied UI artifacts.
 ---
 
 # Page Spec generation
 
+## Select a mode before writing
+
+- `legacy-page`: original standalone flow below, for no supplied incremental plan or an explicitly selected v1 page flow. Preserve its existing evidence, content and ledger rules.
+- `from-plan`: caller supplies a v2 plan and selected revision/hash plus round/batch/spec IDs. Read [plan consumption](references/from-plan.md) and the public `d2h workflow contract generation`. Only this reference governs writes; do not run legacy steps 2–3 or 6, reorder the plan, require all UTG nodes as tasks, create a v1 plan/ledger, or load another Skill.
+
+A supplied v2 plan always selects from-plan. Missing/invalid bindings or inputs return needs-input/needs-revision, never silently fall back to legacy-page. The input artifact, not the producer Skill, is the dependency. Reuse the original source verification, seven core sections, exception behavior and acceptance requirements in either mode.
+
+## Original standalone flow (legacy-page only)
+
 Generate one implementation-ready `spec.md` for every Android page, dialog, sheet, and behaviorally distinct page mode. The AI determines page boundaries, evidence mapping, dependencies, and development order by reading the actual migration workspace and source code.
 
 Do not invoke task-planning, graph-generation, migration, or page-validation scripts. Do not modify Android source, HarmonyOS source, `.migration/spec/`, `.migration/utg/`, `.migration/tasks/`, or the migration report.
@@ -25,12 +34,12 @@ Facts are the deterministic structured evidence baseline extracted from Android
 
 ## Output contract
 
-Each page unit contains only `spec.md`. `pages.json` and `batch_report.md` live at the output root:
+Each page unit contains only `spec.md`. `pages.json` and `batch_report.json` live at the output root:
 
 ```text
 .migration/page-specs/
 ├── pages.json
-├── batch_report.md
+├── batch_report.json
 ├── page_0001_<name>-<id>/
 │   └── spec.md
 ├── page_0002_<name>-<id>/
@@ -148,9 +157,9 @@ Use these headings in every page Spec:
 
 When a page has no independent interaction, write one display/reachability feature and acceptance sequence instead of leaving the feature sections empty.
 
-### 6. Generate `batch_report.md`
+### 6. Generate `batch_report.json`
 
-After all page Specs are complete, generate `<output_root>/batch_report.md` from `pages.json` with the bundled renderer:
+After all page Specs are complete, generate `<output_root>/batch_report.json` from `pages.json` with the bundled renderer:
 
 ```bash
 python scripts/build_batch_report.py \
@@ -164,9 +173,11 @@ The report must contain:
 
 - the source `pages.json` path and SHA-256;
 - generation timestamp and ordered page count;
-- one queue row per page with stable task ID `PAGE-NNNN`, page identity, relative `spec.md` link, development status, build status, validation status, and blocker;
-- one detail section per task with dependencies, implementation files, test files, implementation commit or source snapshot, build evidence, test evidence, last update, blocker, and chronological execution notes;
-- summary counts that exactly match the queue and detail sections.
+- `schema_version: d2h-page-batch-report/v1`, `source`, `created_at`, and `updated_at`;
+- one ordered `tasks[]` object per page with stable `task_id` (`PAGE-NNNN`), page identity, `spec` relative path, dependencies, scores, `development`, `build`, and `validation`;
+- each task's `implementation_files`, `test_files`, `android_evidence`, `implementation_commit`, `source_snapshot`, `build_evidence`, `test_evidence`, `differences`, `started_at`, `ended_at`, `updated_at`, `blockers`, and append-only `history`;
+- `summary` counts derived from `tasks[]`: classify each task once, in order: `blocked` if any state is blocked, `failed` if build/validation failed, `completed` if implemented/passed/passed, `pending` if pending/not_run/not_run, otherwise `in_progress`; counts sum to `total`;
+- `regression` with status, tested HAP/device, evidence, behavior review, unresolved items, timestamp, and append-only history. Empty values use `null` or `[]`, never Markdown placeholders.
 
 Use these status values:
 
@@ -176,7 +187,7 @@ Use these status values:
 
 Initial generation uses `pending`, `not_run`, and `not_run`, with empty implementation, test, evidence, commit/snapshot, timestamp, and blocker fields. Do not infer completion from existing HarmonyOS files or local test artifacts.
 
-Once development has started, never rerun the renderer or overwrite `batch_report.md`. Update the existing queue row, detail section, counts, and notes in place while preserving execution history. If `pages.json`, the Spec set, or order no longer matches an existing report, stop and report the mismatch for AI reconciliation instead of silently resetting statuses.
+Once development has started, never rerun the renderer or overwrite `batch_report.json`. Update the owning `tasks[]` object, summary, timestamps, and history in place. If the plan, Spec set, or order no longer matches, reconcile the mismatch without resetting statuses. An existing Markdown ledger must be explicitly migrated with all statuses, evidence and history preserved; changing its extension is insufficient, and the initializer refuses to replace it.
 
 ## Quality gates
 
@@ -188,8 +199,8 @@ Once development has started, never rerun the renderer or overwrite `batch_repor
 - Existing HarmonyOS code or tests never cause a feature to be marked complete without current build and executed test evidence.
 - Uncertainty remains explicit. Do not invent control names, outcomes, source mappings, runtime captures, or implementation status.
 - Each `page_NNNN_<name>-<id>/` directory contains exactly one file named `spec.md`.
-- `output_root` contains only `pages.json`, `batch_report.md`, and page directories; it contains no copied UI evidence, UI design, or generated validation artifact.
-- Every page directory has exactly one queue row and one detail section in `batch_report.md`; task IDs, order, links, statuses, and counts agree.
+- `output_root` contains only `pages.json`, `batch_report.json`, and page directories; it contains no copied UI evidence, UI design, or generated validation artifact.
+- Every page directory has exactly one `tasks[]` object in valid `batch_report.json`; task IDs, order, Spec paths, states, and summary counts agree.
 - A task is complete only when development is `implemented` and both build and validation are `passed` with current evidence.
 
 ## Result
@@ -203,5 +214,5 @@ Return:
 - ambiguous mappings and unmatched Facts;
 - unresolved selector steps;
 - legacy aggregate packages that were split;
-- the absolute `batch_report.md` path;
+- the absolute `batch_report.json` path;
 - the absolute `output_root`.

package/skills/d2h-spec-generate/assets/spec-template.md

@@ -0,0 +1,109 @@
+# <页面名称> 迁移 Spec
+
+## 文档基线与轮次对照
+
+- 页面：`<page_id>`；目录：`<package>`
+- 功能来源：`<features.json 绝对路径>`；revision：`<revision>`；内容哈希：`<feature_hash>`
+- 计划来源：`<pages.json 绝对路径>`；revision：`<revision>`
+- Android / HarmonyOS 根目录：`<android_root>` / `<harmony_root>`
+- 源码依据版本：`<真实提交/来源标识>`；适用交付目标：`<已授权目标或未配置>`
+
+| feature_id / scope_id | 里程碑 / round_id | batch_id | spec_id | checks | 范围去向及原因 |
+|---|---|---|---|---|---|
+| `<feature>/<scope>` | `<milestone>/<round>` | `<batch>` | `<spec>` | `<真实 check_id>` | `<本轮/后续轮/延期/未决/排除及理由>` |
+
+> 成员和边界与 pages.json、features.json 保持一致。延期/未决未分配项不虚构 batch_id 或 spec_id。此文档不保存运行中完成状态，当前验收读取 execution.json 的派生结果。
+
+## 页面范围
+
+- 页面标识：`<page_id>`；类型：`<page/dialog/sheet/mode/other>`
+- Android 到达路径：`<从真实入口开始，说明前置状态、导航、参数及适用渠道>`
+- HarmonyOS 正式入口：`<已核验入口，或明确标记为 planned 的设计入口>`
+- 负责范围：`<当前页面负责的状态、行为与 scope_refs>`
+- 排除范围：`<相邻责任与实际归属；排除本 Spec 不等于排除用户需求>`
+- 页面结构与共享状态：`<容器、状态来源、初始化、生命周期、跨轮次保留部分>`
+
+## 开发顺序
+
+- 所属轮次与目标：`<round_id/goal>`；目标路径检查：`<goal_checks>`
+- 前置能力：`<requires/provides、负责 Spec 及消费者>`
+- 分组依据与预算：`<同轮同页的代码/状态/测试准备复用，实际 max_specs/max_effort_hours>`
+- 选择理由：`<用户约束、必要前置、风险与增量价值；不以页名或编号替代依据>`
+- 暂缓范围与去向：`<关联 scope_id、后续轮次或上游处置、原因>`
+
+## 页面功能
+
+| feature_id / scope_id | 条件与触发 | 可观察结果 | 本轮/后续及负责 spec_id |
+|---|---|---|---|
+| `<feature>/<scope>` | `<适用条件 → 用户动作或外部触发>` | `<界面、导航、数据或平台结果>` | `<本轮负责者或明确延期去向>` |
+
+> 保留已知页面行为和约定范围，不因选择 MVP 删除全量长尾。每个已授权且已分配范围有唯一负责 Spec。共享背景可以引用本页章节，逐 Spec 的行为与断言不能仅写“同上”或“完善页面”。
+
+## UI 操作与验收
+
+### Spec: `<spec_id>`
+
+#### 目标与范围
+
+- feature_refs / scope_refs：`<稳定 ID 与具体范围>`
+- 轮次 / 批次：`<round_id>` / `<batch_id>`
+- 目标、负责与明确排除：`<独立可交付结果，以及不夹带的后续范围>`
+- 拆分理由：`<独立交付、能力解锁、风险/验证差异或跨轮延期；不为凑数量拆分>`
+
+#### 行为与数据契约
+
+- 前置状态、入口及输入：`<可复现的到达路径、路由参数、输入边界>`
+- 正常路径：`<触发 → 处理中状态 → 结果 → 后续导航/数据效果>`
+- 必要分支：`<适用的空、错误、重复操作、权限拒绝、取消返回、恢复等；不适用时写明理由>`
+- 数据与副作用：`<读写对象、持久化键/表、初始化、生命周期及共享消费者>`
+- 不变量：`<必须持续成立的约束>`
+- requires / provides：`<能力约束与负责 Spec；设计接口和实际接口回执分开>`
+- 已知风险与坑：`<源码或真实失败依据；无已知项经核对后注明>`
+
+#### 检查: `<check_id>`
+
+- 对应范围：`<feature_id/scope_id>`；验证层级：`<static/logic/integration/device>`
+- 时机：`<immediate/batch>`；最晚验证点与理由：`<与计划一致>`
+- 场景与前置：`<状态、数据、权限、网络或设备条件>`
+1. 从 `<真实应用入口或能力输入>` 到达 `<目标状态>`。
+2. 对 `<有源码依据的语义控件/接口>` 执行 `<动作或输入>`。
+3. 断言 `<明确可观察状态、导航、数据、副作用或错误结果>`。
+- 源码/用户依据：`<对应证据表的引用；source-derived 路径不算设备通过>`
+
+> 按实际 checks 重复检查小节，覆盖当前 Spec 的每个检查。纯展示行为给出到达与可见断言；非 UI Spec 写输入、调用、输出与副作用，不虚构页面控件。静态/逻辑前置检查不冒充当前候选的正式设备 PASS。
+
+#### 实施与开工缺口
+
+- HarmonyOS 目标路径与职责：`<引用下方实现表，并说明本 Spec 改动边界>`
+- 工作量：`<复用 Spec.effort 的 low/expected/high、置信度与不确定性>`
+- 评分依据：`<与 Spec.ratings 一致的里程碑贡献、解锁、用户价值、风险消减和反馈理由>`
+- 分工与路径所有权：`<allocation.recommended_workers、owned_paths 及理由；当前实际仍单 worker>`
+- 阻止可靠实施的问题：`<implementation_brief.open_questions 与外部条件；核对后无则写无>`
+- 本次不实施的后续完善：`<scope_id、去向、原因>`
+
+> 同页有多个独立 Spec 时，按稳定 spec_id 重复上述完整章节。后续未临近轮次可只记录已知范围、前置、验收目标和待细化内容，并明确“未细化、不可派发”；接近执行前补完整，不能用摘要代替当前潜在派发成员的实施规格。
+
+## Android 证据
+
+| 证据 | 路径 / Ref | 支持的行为、分支与 Spec/check |
+|---|---|---|
+| Android 源码 | `<android_root 相对路径、符号/行>` | `<触发、状态转移、持久化、异常或平台结果>` |
+| Facts（有则引用） | `<真实 surface/entry/control/interaction/native-libs ref>` | `<支持的范围及覆盖限制>` |
+| UTG（有则引用） | `<真实 page.json node_id>` | `<正式到达路径、前置、guard 与来源限制>` |
+| 用户新增需求（适用时） | `<用户消息或记录标识>` | `<来源码外授权行为，不伪装 extracted 事实>` |
+
+## HarmonyOS 实现范围
+
+| 相对路径 | 状态 | 负责 Spec | 预期职责 / 校验点 |
+|---|---|---|---|
+| `<harmony_root 下的真实或规划路径>` | `<existing/planned>` | `<spec_id>` | `<UI、逻辑、数据、共享影响与验收定位>` |
+
+> existing 路径须核对存在；新设计路径标 planned。计划中的接口、代码或文件不作为已实现证明。
+
+## 未决项与平台差异
+
+| 范围 / Spec | 问题、依据及影响 | 阻止什么 | 处置 / 负责方 / 后续去向 |
+|---|---|---|---|
+| `<scope_id/spec_id>` | `<真实未知项或差异>` | `<开工、能力解锁、验证或交付>` | `<需确认/需配置/方案/延期，不虚构结论>` |
+
+核对后确无未决项时明确写“无”。涉及原生库时说明源码重编/patch、JNI→NAPI、闭源替代或明确差异，并引用负责 Spec 与消费者；缺失产物不能用静默 stub 掩盖。

package/skills/d2h-spec-generate/references/from-plan.md

@@ -0,0 +1,19 @@
+# 消费已有增量计划生成规格
+
+仅用于 mode=from-plan，不执行独立旧页面流程的全量拆分、评分排序和账本初始化。结构与生命周期见公共 `d2h workflow contract generation`、`contract plan`、`contract dispatch`，不读取生产者 Skill 的私有资源。
+
+## 核对输入与生成选择
+
+读取计划/功能清单、明确 revision/hash 和选定 spec_ids，核对所属 round/batch、scope_refs/checks、requires/provides、目标文件所有权及当前执行摘要。缺失选择或身份变化返回 needs-input/needs-revision，不默认全量生成。AI 逐项核对 scope_id 到行为、页面和非页面入口的证据；UTG 节点只提供到达/采集线索，不逐节点生成任务。
+
+已有有效分析与架构直接复用，仅对当前范围补读源码。需要平台知识、原生依赖或架构结论时返回 requests，说明证据、缺口和受影响 Spec，由调用方选择能力；不加载其他 Skill。用户新增需求记录用户来源，不伪造 Android 实现证据。
+
+## 复用原有内容质量
+
+沿用独立模式第 4 步的源码核验、导航/状态/持久化/取消和异常覆盖、真实路径核对；用 [完整内容要求](spec-content.md) 和 [正式模板](../assets/spec-template.md) 展开当前成员。保留七个核心章节与逐项操作、预期可观察结果、源码和平台依据；不以分组摘要替代成员。正式模板的目录、顺序和依赖从输入计划读取，不执行旧 page_score 公式，不把未选登录方式等整页扩展夹带进来。
+
+仅修改所选成员块和必要共享背景。同页追加新成员时保留原内容、独立 spec_id 和验收状态；未来成员可没有文件或明确待细化，不能拿占位内容登记为完整。使用公共契约规定的成员边界，保证全部 check_id 及对应断言出现在其块内。当前页面的公共章节保留原七章布局，放在所有成员块之外（可在成员之后），逐成员的具体来源/目标实现定位写在该成员块内。
+
+生成中发现规划边界、前置能力、检查层级或 implementation_brief 不足时，返回 proposed_plan_updates 和证据。计划维护者应用后增加 revision，调用方重新选定版本，再完成绑定。生成方不能修改 pages.json、features.json、execution.json、旧批次报告或实际工程代码。
+
+返回 status、mode、输入绑定、generated/updated/reused 的 spec_ids、绝对产物路径、unresolved/requests、建议修订；已复用规格仍核对逐成员绑定。确认结构与正文完整后，使用公共 generation 命令记录明确成员，得到 generation.json；它是文件绑定，不是用户授权或运行通过。发现现有页面不符合本模式边界，先保留备份并返回显式迁移请求，不能覆盖旧文档或旧账本。

package/skills/d2h-spec-generate/references/spec-content.md

@@ -0,0 +1,34 @@
+# 完整 Spec 模板与按组细化
+
+生成新页面文档、细化当前轮次或审查实施内容时读取 [spec-template.md](../assets/spec-template.md)。模板恢复原页面 Spec 中已使用的七个核心章节：页面范围、开发顺序、页面功能、UI 操作与验收、Android 证据、HarmonyOS 实现范围、未决项与平台差异；在此基础上增加当前增量流程的稳定范围、轮次、批次及逐 spec_id 内容。
+
+这次复用原模板的内容要求，不恢复旧的固定 page_score 排序、带序号目录、逐页全量实现或手写 batch_report 状态。pages.json、features.json 和 execution.json 的职责不变；模板不改变计划 schema，也不证明实际应用已经验收。
+
+## 生成组织
+
+1. 从选定计划读取完整功能范围去向、稳定 spec_id、依赖、轮次与同轮同页的 page_batches，不重新决定或改写计划。优先通过分组复用上下文，不以减少 Spec 数量或压缩文档为目标。
+2. 每页目录仍只有一份 spec.md；from-plan 模式的七个公共章节保留原布局并置于所有成员块之外，各成员的来源与实现细节保留在自己的稳定块内；页面共用入口、状态与证据写一次，当前轮次的每个 Spec 使用 `### Spec: <spec_id>` 稳定标题，逐项写清范围、行为、异常、数据、副作用及检查。一个文件含多个 Spec 不等于合成一个执行/验收单元。
+3. 按计划组细化当前轮次潜在派发成员，包括组内尚待提供者解锁的消费者。未知契约保留开工问题，不臆造接口。组内成员分别完整，不用组摘要替代。
+4. 远期内容保留真实已知的范围、前置、验收目标、延期去向与待细化内容，不提前扩成完整实施工单。已授权范围仍须符合 scope_refs 覆盖要求；到达轮次前补齐内容与工作包。
+5. 一个组可以包含一个或多个 Spec，数量按行为、复用、依赖、风险和预算决定。归拢不能抹去独立验收身份，紧密关联的同一闭环也不机械按控件拆分。不同页面或轮次保持不同 batch_id。
+
+## 写入前核验（延续原生成要求）
+
+- 打开引用的 Android 源码到符号/行，沿事件处理、数据层、状态转移、导航、持久化及失败处理核对可观察结果。用户新增行为标明用户来源，不伪造源码证据。
+- 有 UTG 时核对真实入口、参数、前置状态、guard 和预期到达；有 Facts 时核对范围与覆盖限制。两者不能代替源码理解或实际运行证据。
+- UI 控件的语义名称来自源码/资源/事实；未知定位保持未决，不能为了可测试而发明控件。非 UI 能力按输入/输出及副作用描述。
+- 核对 Android 路径真实存在，HarmonyOS existing 路径真实存在；规划文件标 planned。原生、权限或平台差异按实际领域技能核验，不把规划 API 或签名当当前实际接口。
+- 用户显式跳过扫描时不强制重建 Facts/UTG；复用已有材料并定向核对必要局部证据，注明已知缺口。没有可靠依据时生成待澄清内容，不冒充完整分析或可派发规格。
+
+## 派发前内容审查
+
+主 Agent 对照固定计划版本、功能范围和原始证据，核对当前成员：
+
+- 每个范围有唯一负责 Spec，文档与 scope_refs、轮次/批次成员一致；未选范围有去向，没有被“合并”隐去。
+- 每个 check 都有可执行场景、入口/输入、操作、明确断言及验证层级/时机。断言不能只写“正常”“成功”或“符合预期”。
+- 正常与必要失败分支、数据读写与共享生命周期、HarmonyOS 路径、契约边界及阻塞问题足以可靠实施；背景可引用，核心行为不能仅写“同上”。
+- 同页修订只更新受影响 Spec 章节，保留其他成员、已验收身份和历史。补解释文字不自动撤销验收；改范围、checks 或共享契约按语义修订和 reconcile 处理。
+
+内容缺失时主 Agent 返回具体 spec_id/check_id 和待补内容，不派发该成员。现有 readiness_gaps 校验工作包字段与接口等结构约束，并不解析 Markdown、证明章节语义完整；不能因为模板标题存在或程序通过就省略此审查。若后续需要程序化内容门禁，应另行设计显式策略，不能假装当前已有。
+
+实际派发仍由 derive/context/start_batch 决定并固定窗口，组内逐 Spec 执行、逐项验收。worker 必须能定位并阅读对应完整章节；裁剪上下文不足时回读该章节和相关共享契约，不根据分组摘要自行补造行为。