@harmonyos-arkts/d2h 0.1.19 → 0.1.21

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 必须能定位并阅读对应完整章节；裁剪上下文不足时回读该章节和相关共享契约，不根据分组摘要自行补造行为。

package/skills/{d2h-page-spec-generate → d2h-spec-generate}/scripts/build_batch_report.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Create the initial batch_report.md from a validated pages.json plan."""
+"""Create the initial batch_report.json from a validated pages.json plan."""
 
 from __future__ import annotations
 
@@ -21,10 +21,6 @@ def sha256(path: Path) -> str:
     return digest.hexdigest()
 
 
-def markdown_text(value: object) -> str:
-    return str(value).replace("|", "\\|").replace("\n", " ")
-
-
 def require_int(value: object, where: str) -> int:
     if not isinstance(value, int) or isinstance(value, bool):
         raise ValueError(f"{where} must be an integer")
@@ -39,13 +35,18 @@ def main() -> int:
 
     pages_plan = args.pages_plan.resolve()
     output_root = args.output_root.resolve()
-    report_path = output_root / "batch_report.md"
+    report_path = output_root / "batch_report.json"
     if not pages_plan.is_file():
         raise FileNotFoundError(f"missing page plan: {pages_plan}")
     if report_path.exists():
         raise FileExistsError(
             f"refusing to overwrite existing execution history: {report_path}; update it in place"
         )
+    legacy_report = output_root / "batch_report.md"
+    if legacy_report.exists():
+        raise FileExistsError(
+            f"existing Markdown ledger requires history-preserving migration: {legacy_report}"
+        )
 
     payload = json.loads(pages_plan.read_text(encoding="utf-8"))
     if not isinstance(payload, dict) or payload.get("schema_version") != "d2h-page-plan/v1":
@@ -113,97 +114,47 @@ def main() -> int:
                 "page_score": require_int(page.get("page_score"), f"pages[{index}].page_score"),
                 "package": package,
                 "page_path": page.get("page_path", []),
+                "dependencies": page.get("dependencies", []),
                 **dimensions,
             }
         )
 
     created_at = datetime.now().astimezone().isoformat(timespec="seconds")
     plan_link = Path(os.path.relpath(pages_plan, output_root)).as_posix()
-    lines = [
-        "# 页面开发批次执行记录",
-        "",
-        f"- 页面计划：[pages.json]({plan_link})",
-        f"- 页面计划 SHA-256：`{sha256(pages_plan)}`",
-        f"- 记录创建时间：`{created_at}`",
-        "- 更新规则：后续开发直接更新本文件；不要重新生成或覆盖已有执行历史。",
-        "",
-        "## 状态约定",
-        "",
-        "- 开发状态：`pending | in_progress | implemented | blocked`",
-        "- 构建状态：`not_run | passed | failed | blocked`",
-        "- 验证状态：`not_run | passed | failed | blocked`",
-        "- 完成条件：开发为 `implemented`，且构建、验证均为 `passed`。",
-        "",
-        "## 批次汇总",
-        "",
-        f"- 总任务：{len(normalized)}",
-        f"- 待开始：{len(normalized)}",
-        "- 进行中：0",
-        "- 已完成：0",
-        "- 阻塞：0",
-        "",
-        "## 执行队列",
-        "",
-        "| 任务 | 顺序 | 页面 | 类型 | 分数 | Spec | 开发 | 构建 | 验证 |",
-        "|---|---:|---|---|---:|---|---|---|---|",
-    ]
-    for page in normalized:
-        spec_link = f"./{page['package']}/spec.md"
-        lines.append(
-            "| {task} | {order} | {page_id} | {kind} | {score} | "
-            "[spec.md]({spec}) | `pending` | `not_run` | `not_run` |".format(
-                task=page["task_id"],
-                order=page["order"],
-                page_id=markdown_text(page["page_id"]),
-                kind=markdown_text(page["kind"]),
-                score=page["page_score"],
-                spec=spec_link,
-            )
-        )
-
-    lines.extend(["", "## 任务记录"])
-    for page in normalized:
-        page_path = page["page_path"]
-        path_text = (
-            " → ".join(markdown_text(value) for value in page_path)
-            if isinstance(page_path, list)
-            else "—"
-        )
-        spec_link = f"./{page['package']}/spec.md"
-        lines.extend(
-            [
-                "",
-                f"### {page['task_id']} · {markdown_text(page['page_id'])}",
-                "",
-                f"- 执行顺序：{page['order']}",
-                f"- 页面路径：{path_text or '—'}",
-                f"- 页面分数：{page['page_score']}（enablement={page['enablement']}，ordinary_reachability={page['ordinary_reachability']}，shallowness={page['shallowness']}）",
-                f"- 任务 Spec：[spec.md]({spec_link})",
-                "- 开发状态：`pending`",
-                "- 构建状态：`not_run`",
-                "- 验证状态：`not_run`",
-                "- 实现文件：—",
-                "- 测试文件：—",
-                "- 代码提交 / 源码快照：—",
-                "- 构建证据：—",
-                "- 测试证据：—",
-                "- 最后更新：—",
-                "- 阻塞原因：—",
-                "",
-                "#### 执行记录",
-                "",
-                "- 尚未开始。",
-            ]
-        )
+    report = {
+        "schema_version": "d2h-page-batch-report/v1",
+        "source": {"pages_plan": plan_link, "sha256": sha256(pages_plan)},
+        "created_at": created_at,
+        "updated_at": created_at,
+        "summary": {"total": len(normalized), "pending": len(normalized),
+                    "in_progress": 0, "completed": 0, "blocked": 0, "failed": 0},
+        "tasks": [
+            {**page, "spec": f"./{page['package']}/spec.md",
+             "development": "pending", "build": "not_run", "validation": "not_run",
+             "implementation_files": [], "test_files": [], "android_evidence": [],
+             "implementation_commit": None, "source_snapshot": None,
+             "build_evidence": [], "test_evidence": [], "differences": [],
+             "started_at": None, "ended_at": None, "updated_at": None,
+             "blockers": [], "history": []}
+            for page in normalized
+        ],
+        "regression": {"status": "not_run", "hap": None, "device": None,
+                       "evidence": [], "behavior_review": None, "unresolved": [],
+                       "updated_at": None, "history": []},
+    }
 
     output_root.mkdir(parents=True, exist_ok=True)
-    report_text = "\n".join(lines) + "\n"
+    report_text = json.dumps(report, ensure_ascii=False, indent=2) + "\n"
     with tempfile.NamedTemporaryFile(
         mode="w", encoding="utf-8", dir=output_root, prefix=".batch-report-", delete=False
     ) as stream:
         stream.write(report_text)
         temporary_path = Path(stream.name)
-    os.replace(temporary_path, report_path)
+    try:
+        # Publish atomically without replacing a ledger created by another process.
+        os.link(temporary_path, report_path)
+    finally:
+        temporary_path.unlink(missing_ok=True)
     print(
         json.dumps(
             {

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

@@ -0,0 +1,38 @@
+---
+name: d2h-spec-plan
+description: Plan reviewable incremental HarmonyOS scope, dependencies, waves and acceptance outlines from versioned scope and architecture. Revise after user adjustments or scope expansion. Returns a versioned plan and gaps; does not generate detailed spec.md, dispatch workers or maintain execution state.
+---
+
+# 增量 Spec 规划
+
+把明确的交付范围转为可评审、可调整的增量计划。先提出波次供用户调整，再按选定版本交给独立生成能力展开详细规格；已有明确授权时无需重复确认。消费的是产物和调用参数，不要求先运行指定技能，也不加载其他技能。缺少领域结论时返回请求，由调用方决定如何补齐。
+
+## 输入
+
+- 版本化 `features.json`：稳定功能/范围 ID、用户选择、优先级、里程碑、来源与版本。已有有效清单直接复用，不重新分析功能或改写授权。
+- Android 源码、现有实现及目标工程定位；Facts、UTG 到达/采集计划、架构上下文和既有证据按当前任务需要读取。UTG 的 `page.json` 不是业务页面或开发任务队列，不能逐节点转换成 Spec。
+- 修订时提供旧计划/Spec、范围差异和当前能力/在途摘要。执行账本可以提供只读线索，不由本 Skill 修改。
+
+需要字段定义或结构校验时使用公共工具 `d2h workflow contract plan`、`d2h workflow contract scope`、`d2h workflow validate --planning-only --plan <pages.json> --features <features.json>`。这是显式工具依赖；工具不可用时返回缺少的能力，不加载其他 Skill 或自行安装工具。
+
+## 按任务读取
+
+| 任务 | 本 Skill 的参考 |
+|---|---|
+| 初次规划、范围/依赖/批次组织变化 | [planning-method.md](references/planning-method.md) |
+| 接收目标目录、所有权与共享边界 | [architecture-handoff.md](references/architecture-handoff.md) |
+| 评估本轮范围、最小前置与验收 | [round-scope-assessment.md](references/round-scope-assessment.md) |
+| 细化实施工作包和共享接口约束 | [work-packets.md](references/work-packets.md) |
+
+## 输出与边界
+
+- `pages.json` v2：范围映射、Spec 身份、依赖、轮次、固定同页批次、实现位置、工作包、成本和测试安排。
+- 便于评审的波次摘要：目标、范围、前置、延期、估算与验收概要。摘要从 pages.json 派生，不成为第二份计划真源。
+- 新增 `spec_generation_policy=required-v1`。本 Skill 不写 spec.md 或 generation.json；生成任务的输入/输出见公共 `d2h workflow contract generation`。
+- 返回 `status`（planned / needs-input / needs-revision）、`artifacts`、`changes`、`unresolved` 与 `requests`。修订差异明确受影响/保留的 Spec、批次与范围；请求说明所需知识、接口、工程或验证结论及消费者，不指定下一项 Skill。
+
+调用方维护用户范围及交付目标。只在独立交付、解锁依赖、风险差异或跨轮延期需要时拆 Spec，按源码与真实行为归并页面；不从模块名、控件或 UTG 节点机械拆分。缺口阻止相应成员开工，不冒充已实现或已验收。
+
+版本变化保留稳定 ID 和历史；已有在途成员时先返回修订建议，由调用方处置派发与状态再应用。MVP 扩展到核心时复用仍有效的分析和架构，保留已完成 Spec、目录和历史，仅规划新增范围与受影响依赖；范围缺口返回调用方，不机械重跑前置阶段。
+
+规划不写 `execution.json`，不生成执行报告或看板，不选择 worker，不决定构建/测试时机的实际执行，不判定验收通过。

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "页面轮次与增量 Spec 规划"
+  short_description: "围绕目标组织页面轮次、同页开发批次、依赖和测试计划"
+  default_prompt: "Use $d2h-spec-plan to read the feature plan and source evidence, then author or revise a reviewable v2 wave plan, preserving user choices and completed scope. Return fixed IDs, dependencies and acceptance outlines; do not write detailed spec.md."

package/skills/d2h-spec-plan/references/architecture-handoff.md

@@ -0,0 +1,9 @@
+# 目标工程与架构上下文
+
+接收的是已给定的目标工程、模块/目录所有权、共享边界、关键链和风险，不要求该输入来自特定架构技能或特定回执文件。源码、现有工程、用户提供的结构、已确认方案均可作为来源；调用方在完整迁移中负责核对授权和来源新鲜度。
+
+把当前 Spec 的实际实现位置写入 allocation.owned_paths，页面共享背景引用归属、共享接口与风险依据。一个模块可以承接多个 Spec，模块依赖不能机械转换成 requires/provides。
+
+功能来源通过稳定 feature_id/scope_id 与来源引用关联，inventory 的数组位置或架构候选页名不是业务身份。UTG page.json 提供节点可达性和到达/采集依据，不等于最终业务页面清单。
+
+目标路径、所有权或必需共享契约缺失时返回 requiredInputs / unresolved；独立请求可以先形成带缺口的草案，不能假造确认或宣称可开工。架构边界变化返回受影响 Spec 和最小调整建议，由调用方决定修订与重新派发。

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

@@ -0,0 +1,13 @@
+# 计划产物契约
+
+`pages.json` v2 是稳定的产物协议，不属于某个计划生产者。字段与兼容规则由公共工具维护：
+
+```text
+d2h workflow contract plan
+d2h workflow contract scope
+d2h workflow validate --planning-only --plan <pages.json> --features <features.json>
+```
+
+本 Skill 输出轻量 Spec 条目、依赖、轮次/批次、已知工作包约束和验收概要；详细正文与生成绑定由独立生成能力维护。新计划开启 spec_generation_policy=required-v1。生成输入输出读取 d2h workflow contract generation。规划校验不要求页面目录或 spec.md 已存在，规划方法见 [planning-method.md](planning-method.md)。调用方执行事件、派发和生成报告；规划不创建执行状态。
+
+结构校验通过不代表源码理解、授权范围、架构归属或实际行为已通过人工复核。只使用已给定输入，不根据产物缺失猜测执行状态或强制运行特定生产技能。

package/skills/d2h-spec-plan/references/planning-method.md

@@ -0,0 +1,46 @@
+# 增量范围、页面轮次与评估方法
+
+创建计划或因新依赖、范围/归拢变化修订语义时读取本参考。仅执行状态更新不重做规划。写入机器可读计划时读取 [plan-contract.md](plan-contract.md)。
+
+## 输入与证据
+
+- migration_root、Android/HarmonyOS 工程绝对路径；默认从 `.migration/config.json` 解析。
+- `.migration/feature-planning/features.json`：schema、revision 和输入文件内容哈希。
+- `.migration/spec/index.json`、Facts、unresolved、`.migration/utg/page.json`；缺失的源码行为仍需记录。无源码的用户新增需求可引用用户来源，缺失证据保持未决。
+- 仍有效的架构上下文与已有工程记录：按 [架构交接](architecture-handoff.md) 核对所有者、目录和风险；不重新选方案。
+- 既有 pages.json、execution.json 和页面 spec.md；迁移报告和既有实现只提供线索，不能证明当前通过。
+
+## 规划工作
+
+1. 消费调用方提供的稳定功能/范围项及来源映射，不把 P0/P1/P2 当用户优先级或交付层。校验功能计划，读取当前阶段全部功能及用户顺序。功能的新增、排除、阶段和优先级由调用方维护，本技能不能静默修改。用户指定 MVP/核心/全量或局部范围时读取公共 `d2h workflow contract delivery`，先核对 delivery 与 scope_items 实际授权，不从优先级或轮次名称推断选用层。
+2. 核验页面、Dialog、Sheet、独立模式的正式入口和源码。页面作为归属索引；一页可包含多个稳定 spec_id，跨页增量指定唯一归属并保留引用。既有页面目录保持稳定；新目录用稳定 page_id 衍生，调整顺序不改路径。规划只登记稳定页面归属，不创建目录或 spec.md。功能与页面多对多；以 scope_id 关联行为、真实入口、源码和非页面副作用，未决映射不得猜测。
+3. 从核心用户路径拆出可独立验收增量，例如基本登录与其他登录方式分开。每个轻量 Spec 条目写 scope、排除/延后归属、验收概要与稳定 check_id、源证据、实现位置和已知共享约束，不展开全部操作及异常正文。按 scope_items 为每项授权范围建立唯一 scope_refs/checks 映射；保留全量功能覆盖，整项未生成 Spec 的功能在 dispositions 中记录，部分延后范围继续保留在清单；已授权且清晰的 included 功能必须有 Spec。具备独立交付/验收价值的成员优先保留身份并用 page_batches 分组，不能为减少数量合并成内容摘要。
+4. 递归展开 requires/provides 的最小能力闭包。边以源码和契约为据，已有能力通过有效证据复用；不将启动动画、找回密码等同页扩展自动提前。每项能力指定一个选定提供者，替代方案不全部强制实现。跨越用户范围、依赖未来阶段或冲突的显式顺序，先返回上游调整建议。拒绝组合依赖环。
+5. 对每个 Spec 给出五项 0–5 评分及证据：里程碑贡献 M、解锁 U、用户价值 V、风险消减 R、反馈 F。价值分 `6M+5U+4V+3R+2F`；优先指数除以含实现、测试、集成和预期返工的 worker 小时。记录 low/expected/high、置信度及剩余日历耗时（含必要验证等待），缺乏可靠估算时明确说明范围和不确定性。只评增量收益，不重复领取既有能力收益。
+6. 评估工作量、并行性、文件耦合、契约成熟度及验证资源，写 recommended_workers、owned_paths、rationale。本版本实际只有一个实现 worker，人数建议用于复盘，不自动开放并发。
+7. 设计测试时机：四项风险各 0–3（影响、共享、不确定性、依赖放大）。数据损失、鉴权、启动、共享契约或合计≥8，所有当前增量 checks 即时执行；其他 checks 分为 immediate 与 batch。提供给下游的能力契约必须属于 immediate。最晚验证点为该 Spec 所属里程碑，测试准备和执行成本计入估算。不为未实现的 deferred 功能提前编写完整测试。
+8. 按 [轮次范围评估](round-scope-assessment.md) 明确本轮目标、范围映射、必要前置、暂缓去向、成本风险和验收条件，复用 rounds.rationale 记录。为每个上游里程碑设计有明确目标与 goal_checks 的页面轮次：baseline 先完成真实基础可用路径，incremental 按优先级增强，completion（如有）完成约定范围。轮次可按需增减，不能擅自改变用户里程碑；新计划使用 `dispatch_mode=page-batches`。每轮只包含目标需要的页面；同一页面跨轮次保留结构与状态，不重新生成覆盖。
+9. AI 根据同页、状态/组件/文件耦合和测试准备复用决定 page_batches，写 goal、rationale、max_specs、max_effort_hours、opportunistic_hours（默认 0）。每个 Spec 恰好归属一个同页同轮批次，归拢不合并验收 ID 或绕过能力门禁。批次收缩后出现跨页交错依赖环时拆分页面访问，不能强行整页闭环。页面 scope_complete 仅表示已核对全部约定范围，true 时附 scope_evidence_refs；未分配后续范围时为 false，不能靠已生成 Spec 全通过就声称页面完善。
+10. 当前轮次只细化到可评审的目标、行为概要、不变量、实施所有权和检查层级。未知接口、平台结论与验收细节返回缺口，不用空数组伪装已核验。生成方若发现需补充工作包或依赖，返回 proposed_plan_updates，由计划维护者判断后按 revision 修订。
+11. 只写 pages.json v2 和派生评审摘要，开启 spec_generation_policy=required-v1，运行 planning-only 校验；将计划路径、revision/hash、选定 round/batch/spec_ids 交调用方。计划刷新后重新确定生成选择；不因用户改波次就重建已完成身份。需要执行账本、报告、详细规格或在途处置时交调用方处理。
+
+## 详细规格交接
+
+公共契约见 `d2h workflow contract generation`。已有有效详细 Spec 可复用；当前轮次只生成新增或受影响成员，远期保留验收概要。生成方消费选定计划，不重新排序、不修改范围、不初始化旧页面账本。发现来源、依赖或共享接口问题时向调用方返回修订请求，不直接调用规划能力。
+
+原生依赖先核对 Facts 的 native-libs.json，再以源码 JNI 入口、System.loadLibrary、CMake/ndk-build 和实际 .so/.a 证据复核。存在 C/C++ 依赖时返回原生依赖 domainRequests，记录源码重编/patch、JNI→NAPI 或闭源替代处置，明确负责 Spec 和共享能力消费者；Facts 未检出不能代替源码核验，缺失库或降级进入未决项，不静默丢弃。
+
+涉及平台能力或不确定 @kit/@ohos API 时返回 knowledgeRequests，列出待查 API、当前证据与期望结论，收到文档 title/uri 后引用到增量。不能从页面名称猜行为、从 source-derived 路径声称运行验证，或从已有代码自动推导完成。
+
+已有基础 Spec 验收后，后续完善读取原页面和功能剩余 scope_items，新增增量 Spec；不得将基础 Spec 扩成不断变化的整页任务。完整规则见 [plan-contract.md](plan-contract.md) 的“逐项范围映射与完成语义”。
+
+
+## 控制 Spec 粒度与重复分析
+
+Spec 按用户可观察行为划分，不按控件、文件或单条断言拆分。仅在可独立交付、需提前解锁下游、风险/验证时机不同或明确跨轮延期时拆开，并在 Spec 写明拆分理由。例如输入校验、按钮等待状态和基本失败反馈可共同属于“基础登录”，无需各建 Spec；独立登录方式或约定会话恢复可后续新增。
+
+- 同一阶段、共同交付且耦合紧密的新范围优先归入一个 Spec，一个 Spec 可以拥有多个 scope_refs 和 checks。有独立验收价值的 Spec 先考虑同页批次复用，不因数量多直接归并；确属同一闭环且尚未执行的过细 Spec 可在显式修订中归并，保留 retired_specs 和历史；已验收 Spec 不为降低数量而改写。
+- 已有多个有独立验收价值的 Spec，通过同页固定窗口由同一 worker 连续实施，复用理解与测试准备；仍遵守预算、优先级和能力门禁，不用合批抢跑未来轮次。
+- 估算包括上下文理解、重复分析、交接及测试成本，不只算写代码。没有实际收益的拆分不采用；不设置未经实测的最小时长或 token 阈值。
+- 远期未排期需求保留 scope_id、行为描述、验收目标和延期去向；到授权阶段再细化实现方案与测试资产。已排期 included 范围仍须有 Spec，不以渐进细化掩盖遗漏。
+- 计划给出页面共享上下文的证据与所有权；详细正文由生成方按固定范围展开。摘要与结构校验不证明当前运行通过。

package/skills/d2h-spec-plan/references/round-scope-assessment.md

@@ -0,0 +1,49 @@
+# 轮次范围评估与复评
+
+新建轮次，或新证据已影响目标可达性、范围选择、依赖、预算或验证窗口时读取。功能清单技能维护授权范围；本技能在这些约束内评估轮次；主 Agent 根据实际状态调度和触发复评。普通状态更新、单次可修复错误或候选变化本身不要求重做规划。
+
+## 评估输入
+
+固定本次 features.json 路径、revision/hash、delivery 及用户顺序；读取当前 pages.json、候选与事件序号、已有有效证据、未决问题和资源条件。分析报告的 P0/P1/P2、可行性、渠道/承载、SDK 与用户待办作为线索，不能替换用户优先级、授权或运行证据。
+
+旧计划无 delivery 或未接新分析报告时，保留可验证的既有用户选择并说明限制；无明确用户选择时交上游建立默认核心范围，不把旧 included 集合直接当作用户已选全量。涉及范围变化按版本协议修订，不改在途窗口；不为补评估强制重跑分析或重置账本。
+
+## 每轮需要回答的问题
+
+| 内容 | 交付要求 |
+|---|---|
+| 目标与边界 | 用户能完成什么路径，属于哪个里程碑及交付目标；本轮明确不包含什么 |
+| 本轮范围 | 列出 feature_id/scope_id、关联 Spec 和页面批次；解释选择理由，不只报 Spec 数量 |
+| 必要前置 | requires/provides 的最小能力闭包、提供者与当前证据；区分复用已验证能力、需本轮实现、外部缺口 |
+| 暂缓与未决 | 列出未进入本轮的相关范围、原因及后续轮次/上游处置；未授权或 unassigned 不强行排期 |
+| 成本与风险 | 实现/测试/集成/上下文成本、low/expected/high 与置信度；指出关键路径、资源等待和主要风险 |
+| 验收与结束条件 | 关联 goal_checks、各 Spec checks、验证层级和目标路径；成员 accepted 后仍须 round_accept，不用说明文字代替证据 |
+
+默认先寻找真实基础可用路径，如“启动 → 基本登录 → 主页面雏形”；无登录项目按实际入口组织。完整启动动画、其他登录方式等扩展不阻塞基础首页，除非源码证明其为必要前置。MVP/核心/全量是范围层级，baseline/incremental/completion 是里程碑内轮次，二者不能机械对应。
+
+不要为证明闭环而预支未知平台能力。必要能力超出授权范围、依赖未来阶段或与显式顺序冲突时，输出最小调整建议及证据，返回调用方更新范围产物；用户真正需要取舍时由主 Agent 询问。获准前不改范围、不生成越权派发。
+
+## 记录位置与一致性
+
+复用现有产物，不增加第二份轮次计划或执行账本：
+
+- pages.json 的 rounds[].goal、rationale、goal_checks 保存轮次目标、选择/暂缓依据和验收入口。rationale 简要注明评估所依据的功能版本及关键不确定性，不补造 schema 字段。
+- 本轮成员由 page_batches[].round_id/spec_ids 确定，范围由 Spec.scope_refs 确定，前置由 requires/provides 确定；同一范围不重复认领。
+- 受影响页面 spec.md 保持“范围项 → 轮次 → 批次 → Spec → checks”表，补本轮边界、暂缓去向、成本/风险与证据定位。跨页共用轮次引用同一 round_id；全局目标以 rounds 为准，避免各页分别作出冲突决策。
+- 工时估算由 Spec.effort 汇总，批次受 max_effort_hours 等预算约束；worker 工时、剩余日历耗时、实际派发跨度分开。不能直接把并行/等待工时相加当总用时，缺可靠数据就说明未知。
+- batch_report.json 与看板只读取同一计划和当前派生状态，不手写覆盖派生报告。评估说明不代表已开始、已交付或已验收。
+
+## 执行中复评
+
+主 Agent 在以下变化已影响轮次安排时交回本技能：
+
+1. 用户调整范围、交付目标、优先级或顺序；先由功能清单技能修订上游。
+2. 新源码/平台证据表明原行为不可行、能力提供者需更换或最小依赖闭包变化。
+3. SDK/SO、App ID、权限/签名配置、设备或测试资源缺口，使本轮目标无法按原条件验收。
+4. 实际实现、返工、测试或等待已使原预算/截止验证点失效，或已交付轮次出现影响后续目标的回归。
+
+先记录触发证据、受影响范围/Spec/轮次及当前固定版本，判断能否在原契约内修复。仅需正常修复或补证据时继续原计划；只有规划语义变化才修订。复评可以明确“保持原计划”，此时不为记录一次评估而虚增 revision 或重置执行。
+
+需要修订时返回 changes 与缺口；调用方按公共执行契约处理归档、在途任务/窗口及 reconcile。保留已验收 Spec、稳定 ID、旧 rationale 与历史证据；未来轮次只细化到范围、目标和风险，不提前展开完整实施工单。重排不自动扩大用户范围，也不隐式改变 worker 的固定派发版本。
+
+向用户说明：触发原因 → 保持/调整哪些范围 → 前置与成本影响 → 新的验收条件 → 需用户决定的取舍（如有）。