@harmonyos-arkts/d2h 0.1.20 → 0.1.22

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 的固定派发版本。
+
+向用户说明：触发原因 → 保持/调整哪些范围 → 前置与成本影响 → 新的验收条件 → 需用户决定的取舍（如有）。

package/skills/d2h-spec-plan/references/work-packets.md

@@ -0,0 +1,61 @@
+# 自足工作包、共享状态与实际接口
+
+创建或细化当前轮次、处理开工缺口、设计跨 Spec 状态流时读取。计划字段归 pages.json；接口回执归 execution.json。context 裁剪输出，不另建可编辑工单真源。
+
+## 开工就绪
+
+新计划使用 `work_packet_policy: "required-v1"`。每个 Spec 提供：
+
+```json
+{
+  "implementation_brief": {
+    "behavior_notes": ["输入、状态转移、结果与必要失败路径"],
+    "invariants": ["本次行为不能破坏的约束"],
+    "known_pitfalls": ["从源码或实际失败确认的风险"],
+    "open_questions": []
+  },
+  "testing": {
+    "layers": [{"check_id": "login/basic", "layer": "device", "reason": "真实鉴权与导航"}]
+  }
+}
+```
+
+behavior_notes 非空；其余三个数组必须存在，无适用内容经核对后写 []。open_questions 只放阻止可靠实现的未决问题，非阻塞背景放 behavior_notes。testing.layers 唯一且完整覆盖本 Spec 的 checks；layer 为 static/logic/integration/device，reason 非空。可暂存不完整计划，但 derive.readiness_gaps 阻止相关成员进入窗口，不能夹带进同页批次。
+
+工作包复用 scope、evidence_refs、owned_paths、requires/provides 和 checks。AI 按任务补齐 UI 入口与路由参数、数据表/键/副作用、逻辑模块及目标文件；纯后台/算法能力不虚构页面。源码仍是行为细节依据，摘要用于定位与交接。远期延期需求不提前写大工单。
+
+## 跨 Spec 共享状态
+
+仅在多个 Spec 实际共享状态时写顶层 shared_contracts，不为每个功能强建基础设施。
+
+```json
+{
+  "state_id": "session",
+  "capability": "session.basic",
+  "producer_spec_id": "login-basic",
+  "consumer_spec_ids": ["home-basic"],
+  "channel": "SessionStore 单一状态通道",
+  "payload": "令牌、用户标识及匿名/有效/过期状态",
+  "initialization": "登录成功持久化；首页订阅并读取快照",
+  "lifecycle": "注销或过期清空并通知消费者",
+  "checks": ["login/persist-session", "home/observe-session"]
+}
+```
+
+producer 提供指定 capability，每个 consumer 必须 requires 它；checks 包含每个参与 Spec 的实际检查，不得越界。channel/payload/initialization/lifecycle 缺失时参与者不能开工。登录和首页 UI 都存在不能证明状态已传递；必须明确谁写、谁读、何时生效及失效，并用消费者断言覆盖状态变化。
+
+## 真实接口交接
+
+提供者实现并形成当前候选后，主 Agent 阅读代码核对实际导出符号、参数/返回及错误语义，以 interface 事件记录代码文件及哈希、symbols、summary、reviewer。运行时确认由调用方按公共 `d2h workflow contract execution` 执行；本 Skill 不记录事件。这不是预先编造的签名，也不是运行证据。提供者只有接口回执有效、当前构建和即时契约测试有效，才解锁消费者。
+
+candidate 或接口文件变化、failed/invalidate/repair 会撤销接口有效性。context 不交接过期接口；共享契约或工作包语义通过 reconcile 修订并重置相关成员，保留历史。程序检查文件身份，不解析符号真实性或证明实际调用关系，主 Agent 负责语义核验。
+
+## 分层验证与定向修复
+
+分层是选择验证成本的计划，不改变通过标准。当前正式 test evidence 仍只支持受管 Python 设备执行；静态检查、算法向量和服务探针可前置发现问题，但尚无 CLI 证据适配，不能用于正式 PASS。鉴权、启动、共享契约和其他高风险行为仍即时验证，低风险成员按窗口合批。
+
+只修复并重跑失败的准备步骤，避免重新提取已完成需求；同一候选可共享构建安装和真实结果。主 Agent 对高风险且缺证据的行为优先检查反例，如失效令牌、重复提交、返回后状态丢失，不为每项重复启动多轮主观评审。候选变化仍保守撤销旧验证，影响范围复用需后续 CLI 协同。
+
+## 与完整 Spec 的关系
+
+implementation_brief 是结构化计划/派发摘要，不替代详细行为、操作、证据与逐 check 断言。规划先提供已核验的概要及缺口；生成方按公共 `d2h workflow contract generation` 展开正文，缺少实施字段时提出修订建议。新策略额外核对逐成员生成绑定，但 readiness_gaps 仍不验证 Markdown 语义；AI/人工须审查。worker 根据固定 spec_id 补读详细文档，不根据摘要猜测。

package/skills/d2h-utg-ai-generate/references/click-paths-schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://hometrans.local/schemas/click-paths-v2.json",
-  "title": "HomeTrans deterministic click paths",
+  "$id": "https://d2h.local/schemas/click-paths-v2.json",
+  "title": "d2h deterministic click paths",
   "type": "object",
   "required": ["root", "paths", "unreachable"],
   "properties": {

package/skills/d2h-utg-ai-generate/references/page-schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://hometrans.local/schemas/page-plan-v1.json",
-  "title": "HomeTrans UTG-directed runtime capture plan",
+  "$id": "https://d2h.local/schemas/page-plan-v1.json",
+  "title": "d2h UTG-directed runtime capture plan",
   "type": "object",
   "required": ["schema_version", "source", "summary", "pages"],
   "properties": {

package/skills/d2h-utg-ai-generate/references/utg-schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://hometrans.local/schemas/utg-v2.json",
-  "title": "HomeTrans source-derived UTG",
+  "$id": "https://d2h.local/schemas/utg-v2.json",
+  "title": "d2h source-derived UTG",
   "type": "object",
   "required": ["directed", "multigraph", "graph", "nodes", "links"],
   "properties": {

package/skills/d2h-utg-static-generate/SKILL.md

@@ -19,14 +19,14 @@ description: 迁移主流程的 Android 静态分析入口，在 Skill 内调用
    droid2hmos analyze android <android-source>
    ```
 
-2. 确认本次生成的 `<migration-workspace>/spec/index.json`、`spec/facts/` 和 `appgraph/app-graph.json` 存在，核对源码与分析结果。复用这份 AppGraph，不再执行第二次 `appgraph build`：
+2. 确认本次生成的 `<migration-workspace>/spec/index.json`、`spec/facts/`（含 `facts/native-libs.json` 原生库分片）和 `appgraph/app-graph.json` 存在，核对源码与分析结果。复用这份 AppGraph，不再执行第二次 `appgraph build`：
 
    ```bash
    python <skill>/scripts/generate.py --project-root <android-source> --workspace <migration-workspace>/utg --appgraph <migration-workspace>/appgraph/app-graph.json
    ```
 
 3. 按下文完成源码核验、独立 AI 修补和统一重建。已有 UTG 工作区需显式使用 `--force`；源码或 AppGraph 变化时重新核验旧修补，不能沿用过期指纹。
-4. 将 Facts 位置、受管分析结果、UTG 产物及未解析项交回主 Agent，由主 Agent 接续报告初始化与 Task Plan。UTG discoveries 不替代 Kernel 的 correction/review，也不替代受管分析证据。
+4. 将 Facts 位置、受管分析结果、UTG 产物及未解析项交回主 Agent，由主 Agent 接续报告初始化与 Task Plan。`facts/native-libs.json` 的 `present`/`usageCase`/`libraries`/`loadCalls` 原样转交（其处置归 `d2h-native-library-build`，本 Skill 不做 ELF/符号深检）。UTG discoveries 不替代 Kernel 的 correction/review，也不替代受管分析证据。
 
 Android 分析不运行 Gradle、不启用 `--resolve-dependencies`，不需要 APK 或 Android 设备。已有图缺失时报告分析产物不完整，不在主流程模式中静默切换到独立建图。
 

package/skills/managing-d2h-toolchain/environment-requirements.json

@@ -8,7 +8,7 @@
     "java": null,
     "python-json5": null,
     "appgraph": { "minimum": "0.0.11", "maximumExclusive": "0.0.12" },
-    "droid2hmos": { "minimum": "0.0.12", "maximumExclusive": "0.0.13" },
+    "droid2hmos": { "minimum": "0.0.17", "maximumExclusive": "0.0.18" },
     "hvigor": null,
     "ohpm": null,
     "devecocli": null

package/skills/managing-d2h-toolchain/toolchain.json

@@ -9,7 +9,7 @@
     },
     "droid2hmos": {
       "package": "@harmonyos-arkts/droid2hmos",
-      "version": "0.0.12",
+      "version": "0.0.17",
       "capabilities": { "analyze-android": ["--help"], "preflight": ["--help"], "status": ["--help"] }
     }
   }

package/skills/preparing-migration-workspace/SKILL.md

@@ -9,10 +9,38 @@ description: 在 Android 转 HarmonyOS 迁移开始或恢复时，通过 droid2h
 
 工具安装、精确版本和升级由 `managing-d2h-toolchain` 负责。本 Skill 只消费已检查的 CLI；发现版本或能力不符时返回该 Skill 处理，不运行 npm。
 
-只调用 `droid2hmos` 的 `status`、`preflight`、`config init/validate` 和按需的 `device check`。不要直接调用 Node 脚本、Gradle、Hvigor、Hypium、ADB、HDC 或 AppGraph 分析命令，也不要在 `ohos/` 尚不存在时猜测 HarmonyOS 构建配置。
+只调用 `droid2hmos` 的 `status`、`preflight`、`config init/validate`、`progress init/update` 和按需的 `device check`。不要直接调用 Node/Python 脚本、Gradle、Hvigor、Hypium、ADB、HDC 或 AppGraph 分析命令，也不要在 `ohos/` 尚不存在时猜测 HarmonyOS 构建配置。
 
 迁移产物（`.migration/`）统一位于 Android 工程父目录下的 `<工程名>-migration/.migration/`，由 CLI 创建和维护，不写入 Android 工程内部。下文所有 `.migration/...` 路径均相对该迁移工作区根目录。
 
+## 阶段进度文件
+
+CLI 确认迁移工作区且 `.migration/` 已存在后，立即初始化阶段进度文件：
+
+```text
+droid2hmos progress init <ANDROID_PROJECT>
+```
+
+该命令原子创建 `.migration/progress.json`；恢复迁移时若文件已存在，只校验结构并保留全部已有时间和状态，禁止覆盖重置。文件固定包含以下七个有序阶段：
+
+1. 初始化工程（`workspace-initialization`）
+2. 功能清单生成（`feature-inventory`）
+3. Android 工程分析（`android-analysis`）
+4. HarmonyOS 工程架构设计（`harmony-architecture`）
+5. spec 设计与生成（`spec-design-generation`）
+6. 代码转换（`code-conversion`）
+7. 测试与交付（`testing-delivery`）
+
+每个阶段记录 `status`、`startedAt`、`endedAt`、`completed`、`lastUpdatedAt`、`details` 和 `blockers`；顶层 `summary` 汇总总数及 `pending/in_progress/blocked/completed` 数量和当前阶段。所有时间使用带时区偏移的 ISO 8601。初始化时“初始化工程”为 `in_progress`，其余阶段为 `pending`。
+
+本 Skill 只更新“初始化工程”阶段。Preflight 和配置准备达到 `baselineReady=true` 时执行：
+
+```text
+droid2hmos progress update <ANDROID_PROJECT> --stage workspace-initialization --status completed --details "workspace, configuration, and non-device baseline are ready"
+```
+
+若工程定位、配置或必要工具链使 `allowedNonDeviceWork=false`，将该阶段更新为 `blocked` 并用 `--blocker` 原样记录 CLI 返回的阻塞原因；设备单独不可用不阻止初始化阶段完成。后续编排者在对应阶段开始、完成或受阻时用同一 `update` 命令更新 `progress.json`，不得直接手工改写、删除阶段或伪造时间。
+
 ## 输入与事实来源
 
 输入必须包含 Android Gradle 工程根目录。根目录应有 Gradle 标记，应用模块中应有 `AndroidManifest.xml`。
@@ -112,7 +140,7 @@ droid2hmos config validate <ANDROID_PROJECT>
   ],
   "allowedNonDeviceWork": true,
   "allowedActions": [],
-  "evidence": [".migration/preflight-report.json"],
+  "evidence": [".migration/preflight-report.json", ".migration/progress.json"],
   "suggestedRemediation": []
 }
 ```
@@ -128,4 +156,6 @@ droid2hmos config validate <ANDROID_PROJECT>
 - `evidence`：本次读取或生成的状态、配置和 Preflight 报告；
 - `suggestedRemediation`：CLI 给出的可执行补救，不臆造成功结论。
 
+结构化结果的 `evidence` 必须包含本次读取或初始化的 `.migration/progress.json`。
+
 本 Skill 不推进外部状态机、不更新迁移报告、不创建 checkpoint、不调用 `complete`，也不决定定向测试或全量回归。调用方根据上述结果决定下一步。