@harmonyos-arkts/d2h 0.1.6 → 0.1.8

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

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

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

@@ -0,0 +1,7 @@
+interface:
+  display_name: "HarmonyOS Page Development Loop"
+  short_description: "按 spec.md 完成单页面受管开发、测试与提交闭环"
+  default_prompt: "Use $d2h-page-develop to serially implement ordered HarmonyOS page tasks from pages.json, batch_report.md, and spec.md in the current agent without delegating page work to subagents."
+
+policy:
+  allow_implicit_invocation: true

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

@@ -0,0 +1,206 @@
+---
+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.
+---
+
+# Page Spec generation
+
+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.
+
+## Inputs
+
+Resolve these paths before writing:
+
+- `migration_root`: workspace containing `.migration/`.
+- `spec_root`: `<migration_root>/.migration/spec`; require `index.json` and `facts/`.
+- `page_plan`: require `<migration_root>/.migration/utg/page.json`; this is the source-derived page and navigation plan produced by the UTG stage.
+- `android_root`: `.migration/config.json.androidProject`, unless explicitly supplied.
+- `harmony_root`: `.migration/config.json.harmonyProject`, resolved relative to `migration_root` when not absolute, unless explicitly supplied.
+- `legacy_tasks_root`: optional `<migration_root>/.migration/tasks`; use existing briefs, core facts, source context, and acceptance files only as read-only evidence from an older flow.
+- `output_root`: default `<migration_root>/.migration/page-specs`.
+
+Facts and legacy Task artifacts are indexes, not substitutes for Android source. Existing HarmonyOS files and tests are implementation evidence, not proof that a behavior is complete.
+
+## Output contract
+
+Each page unit contains only `spec.md`. `pages.json` and `batch_report.md` live at the output root:
+
+```text
+.migration/page-specs/
+├── pages.json
+├── batch_report.md
+├── page_0001_<name>-<id>/
+│   └── spec.md
+├── page_0002_<name>-<id>/
+│   └── spec.md
+└── ...
+```
+
+Directory names encode the AI-selected development order. Use a four-digit sequence and a stable unique suffix derived from the strongest page identity already present in Facts or `page.json`. Re-running against unchanged evidence must preserve existing directory names and order unless the evidence proves the previous boundary or dependency order was wrong.
+
+## Workflow
+
+### 1. Read the complete evidence index
+
+1. Read `.migration/spec/index.json`, `facts/app.json`, all `facts/pages/*.json`, `facts/interactions.json`, and `facts/unresolved.json`.
+2. Read `.migration/utg/page.json` completely. Use `pages[]` as the page/navigation index and consume each node's `node_id`, `kind`, `label`, `declared_at`, `required_state`, `expected`, `reachable`, `depth`, `ui_sequence`, `path_text`, `steps`, and `skip_reason` when present.
+3. Treat `page.json.source.utg` and `page.json.source.click_paths` as provenance links. Read those referenced UTG artifacts only when page boundaries, transitions, guards, or selectors need clarification.
+4. If legacy `.migration/tasks/` exists, read its package briefs and associated `core-facts.json`, `source-context.json`, and `acceptance.json` only to recover behavior refs and source closure. Never inherit its package boundary blindly and never execute its task commands.
+5. Read the current migration report to understand existing mappings and unresolved items, without treating report status as proof of implementation.
+6. Inspect HarmonyOS route registration, `.ets`/`.ts` components, shared state, resources, and tests to distinguish existing implementation from planned work.
+
+### 2. Determine page units with AI reasoning
+
+1. Start from `page.json.pages[]`, then join each page node to Facts surfaces, entries, controls, and interactions by stable ref, declared source, transition, and source behavior.
+2. Treat independently reachable pages, dialogs, sheets, and behaviorally distinct add/edit or selection modes as separate units when they have their own user-visible lifecycle or acceptance flow.
+3. Prefer exact ref or normalized identity matches between `page.json.pages[].node_id` and Facts surfaces. Then use labels, `declared_at`, parent relations, navigation steps, source symbols, controls, and Android source behavior.
+4. Never assign behavior from name similarity alone. Record ambiguous mappings in the owning Spec under “未决项与平台差异”.
+5. `capture=false`, an empty `expected`, or a `skip_reason` does not remove a source-proven page. Use those fields as evidence limitations and verify the page through Facts and Android source.
+6. Do not create a fake page for background-only capabilities. Assign startup, notification, widget, receiver, persistence, or other shared responsibilities to the earliest real page that requires them and list downstream consumers.
+7. Legacy page work packages may contain many unrelated surfaces. Split them by actual page lifecycle and behavior ownership rather than retaining the old aggregate.
+
+### 3. Decide development order
+
+Rate each dimension using an integer from 0 to 5, then calculate the score using the following formula:
+
+`page_score = enablement × 9 + ordinary_reachability × 6 + shallowness × 5`（满分 100，分数越高越优先）。
+
+- **Enablement (45%)** — use the highest evidence-backed enablement rating among the page's REQs. `5`: difficult to mock or bound, ambiguous in data ownership, and correctness-relevant across many features. `3`: reused across several features but cleanly isolatable. `1`: page-local. Repeated persistence keys, storage operations, data-flow hops, and consumers are evidence; a feature name is not.
+- **Ordinary reachability (30%)** — `5`: reachable in normal app state. `3`: needs a common business state such as existing data, login, or permission. `0`: first-launch only or reachable only after clearing/resetting app-global state. Use intermediate ratings where evidence supports them.
+- **Shallowness (25%)** — `5`: launch/main page; `4`: one page navigation; `3`: two; `2`: three; `1`: four or more. Derive depth from page boundaries in `page-path`, not click count. `__shared_capability__` uses neutral `3`.
+
+When ordering, first satisfy evidence-backed prerequisites so that data or state providers precede their consumers. Sort all remaining pages by page_score in descending order, breaking ties by the normalized stable page_id in ascending order. Finally, assign consecutive order values starting from 1. Prerequisites may override score-based ordering; no other arbitrary reordering is allowed.
+
+Write the ordered decisions to `<output_root>/pages.json` before creating page directories. Also write the ordinal, dependencies, and concise rationale into each Spec.
+
+Use schema `d2h-page-plan/v1`. Every `pages[]` item must contain:
+
+- consecutive one-based `order`;
+- stable `page_id`, `kind`, `package`, and `page_path`;
+- `spec_refs` and `req_refs` backed by Facts/source evidence;
+- integer `page_score`;
+- `decision_ledger.enablement.rating`, `ordinary_reachability.rating`, and `shallowness.rating`, with evidence and a concise calculation/rationale.
+
+`package` must exactly match `page_NNNN_<name>-<id>`. Every `page.json` node must be represented by a page item or by an explicit exclusion/unmatched entry with a reason. The AI authors and checks this plan; do not use it as a substitute for reading source.
+
+### 4. Verify source before writing
+
+1. Open every cited Android `sourceEvidence.file` at the cited symbol or line.
+2. Follow handlers, repositories, state transitions, navigation, persistence, error paths, and platform side effects far enough to establish the observable result.
+3. Use `page.json` navigation steps, selectors, guards, expected-arrival rules, required state, and depth to reconstruct the semantic arrival path. Source-derived reachability is planning evidence, not runtime confirmation.
+4. Translate selectors into semantic control names only when Facts, resources, or Android source support the mapping. Keep missing or ambiguous selectors explicitly unresolved.
+5. Verify every listed Android path exists under `android_root`. Verify every HarmonyOS path marked `existing` exists under `harmony_root`; otherwise mark it `planned`.
+
+### 5. Write only `spec.md`
+
+Use these headings in every page Spec:
+
+```markdown
+# <页面名称> 迁移 Spec
+
+## 页面范围
+
+- 页面标识：<稳定标识>
+- 页面类型：<page | dialog | sheet | mode | other>
+- Android 到达路径：<从真实入口开始的语义路径>
+- 负责范围：<本 Spec 负责的状态和行为>
+- 排除范围：<相邻但属于其他 Spec 的责任>
+
+## 开发顺序
+
+- 顺序：<NNNN>
+- 前置依赖：<无或其他页面标识/共享能力>
+- 排序理由：<基于前置依赖和页面评分的说明>
+
+## 页面功能
+
+- F-001：<用户动作及其可观察结果。>
+
+## UI 操作与验收
+
+### F-001
+
+1. <从真实应用入口进入当前页面。>
+2. <定位并操作具有语义名称的控件。>
+3. <断言可见状态、导航、数据效果或错误结果。>
+
+## Android 证据
+
+| 证据 | 路径 / Ref | 支持的结论 |
+|---|---|---|
+| Facts | <surface/entry/control/interaction ref> | <范围或行为> |
+| Android 源码 | <android_root 相对路径及符号/行> | <触发、分支和结果> |
+| UTG Page | `.migration/utg/page.json` 中的 <node_id> | <到达路径、深度、前置状态、导航步骤与证据限制> |
+
+## HarmonyOS 实现范围
+
+| 路径 | 状态 | 预期职责 / 校验点 |
+|---|---|---|
+| <harmony_root 相对路径> | existing 或 planned | <页面实现、共享影响和验收点> |
+
+## 未决项与平台差异
+
+- <没有时明确写“无”。>
+```
+
+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`
+
+After all page Specs are complete, generate `<output_root>/batch_report.md` from `pages.json` with the bundled renderer:
+
+```bash
+python scripts/build_batch_report.py \
+  --pages-plan <output_root>/pages.json \
+  --output-root <output_root>
+```
+
+The script requires every planned package to contain `spec.md`, never requires `ui-design.md`, and refuses to overwrite an existing report.
+
+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.
+
+Use these status values:
+
+- development: `pending | in_progress | implemented | blocked`;
+- build: `not_run | passed | failed | blocked`;
+- validation: `not_run | passed | failed | blocked`.
+
+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.
+
+## Quality gates
+
+- Every known source-proven page, dialog, sheet, and behaviorally distinct mode has exactly one `spec.md`, or its ownership is explicitly assigned to another Spec.
+- Every distinct interaction has a unique `F-xxx`, and feature IDs match UI operation/acceptance sections one-to-one.
+- Each feature states a user action and observable result, not an implementation instruction.
+- Navigation, state changes, persistence, destructive confirmation, external intents, cancellation, dismissal, and error behavior remain explicit.
+- Facts refs, `page.json` node IDs, Android source paths, and HarmonyOS paths are real and correctly classified.
+- 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.
+- A task is complete only when development is `implemented` and both build and validation are `passed` with current evidence.
+
+## Result
+
+Return:
+
+- the ordered page directory list and ordering rationale;
+- the number of generated, updated, and unchanged Specs;
+- the absolute `pages.json` path;
+- unreachable pages, capture-disabled nodes, and pages with incomplete arrival rules in `page.json`;
+- ambiguous mappings and unmatched Facts;
+- unresolved selector steps;
+- legacy aggregate packages that were split;
+- the absolute `batch_report.md` path;
+- the absolute `output_root`.

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

@@ -0,0 +1,227 @@
+#!/usr/bin/env python3
+"""Create the initial batch_report.md from a validated pages.json plan."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import sys
+import tempfile
+from datetime import datetime
+from pathlib import Path
+
+
+def sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            digest.update(chunk)
+    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")
+    return value
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--pages-plan", required=True, type=Path)
+    parser.add_argument("--output-root", required=True, type=Path)
+    args = parser.parse_args()
+
+    pages_plan = args.pages_plan.resolve()
+    output_root = args.output_root.resolve()
+    report_path = output_root / "batch_report.md"
+    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"
+        )
+
+    payload = json.loads(pages_plan.read_text(encoding="utf-8"))
+    if not isinstance(payload, dict) or payload.get("schema_version") != "d2h-page-plan/v1":
+        raise ValueError("pages plan must use schema d2h-page-plan/v1")
+    pages = payload.get("pages")
+    if not isinstance(pages, list) or not pages:
+        raise ValueError("pages plan must contain a non-empty pages array")
+
+    normalized: list[dict[str, object]] = []
+    seen_packages: set[str] = set()
+    seen_page_ids: set[str] = set()
+    for index, page in enumerate(pages):
+        if not isinstance(page, dict):
+            raise ValueError(f"pages[{index}] must be an object")
+        order = require_int(page.get("order"), f"pages[{index}].order")
+        if order != index + 1:
+            raise ValueError(f"pages[{index}].order must be {index + 1}")
+
+        package = page.get("package")
+        page_id = page.get("page_id")
+        if not isinstance(package, str) or not package:
+            raise ValueError(f"pages[{index}].package must be a non-empty string")
+        if Path(package).name != package or not package.startswith(f"page_{order:04d}_"):
+            raise ValueError(
+                f"pages[{index}].package must be a single directory named page_{order:04d}_<name>-<id>"
+            )
+        if package in seen_packages:
+            raise ValueError(f"duplicate package: {package}")
+        seen_packages.add(package)
+        if not isinstance(page_id, str) or not page_id:
+            raise ValueError(f"pages[{index}].page_id must be a non-empty string")
+        if page_id in seen_page_ids:
+            raise ValueError(f"duplicate page_id: {page_id}")
+        seen_page_ids.add(page_id)
+
+        spec_path = output_root / package / "spec.md"
+        if not spec_path.is_file():
+            raise FileNotFoundError(
+                f"all page specs must exist before batch report generation; missing {spec_path}"
+            )
+        package_files = sorted(path.name for path in spec_path.parent.iterdir() if path.is_file())
+        if package_files != ["spec.md"]:
+            raise ValueError(
+                f"page package must contain only spec.md: {spec_path.parent} contains {package_files}"
+            )
+
+        ledger = page.get("decision_ledger")
+        if not isinstance(ledger, dict):
+            raise ValueError(f"pages[{index}].decision_ledger must be an object")
+        dimensions: dict[str, int] = {}
+        for dimension in ("enablement", "ordinary_reachability", "shallowness"):
+            item = ledger.get(dimension)
+            if not isinstance(item, dict):
+                raise ValueError(f"pages[{index}].decision_ledger.{dimension} must be an object")
+            dimensions[dimension] = require_int(
+                item.get("rating"), f"pages[{index}].decision_ledger.{dimension}.rating"
+            )
+
+        normalized.append(
+            {
+                "order": order,
+                "task_id": f"PAGE-{order:04d}",
+                "page_id": page_id,
+                "kind": page.get("kind", "page"),
+                "page_score": require_int(page.get("page_score"), f"pages[{index}].page_score"),
+                "package": package,
+                "page_path": page.get("page_path", []),
+                **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`",
+                "- 实现文件：—",
+                "- 测试文件：—",
+                "- 代码提交 / 源码快照：—",
+                "- 构建证据：—",
+                "- 测试证据：—",
+                "- 最后更新：—",
+                "- 阻塞原因：—",
+                "",
+                "#### 执行记录",
+                "",
+                "- 尚未开始。",
+            ]
+        )
+
+    output_root.mkdir(parents=True, exist_ok=True)
+    report_text = "\n".join(lines) + "\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)
+    print(
+        json.dumps(
+            {
+                "ok": True,
+                "task_count": len(normalized),
+                "pages_plan": str(pages_plan),
+                "batch_report": str(report_path),
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except (FileNotFoundError, FileExistsError, ValueError, KeyError, json.JSONDecodeError) as error:
+        print(f"error: {error}", file=sys.stderr)
+        raise SystemExit(2)

package/skills/managing-d2h-toolchain/SKILL.md

@@ -1,23 +1,24 @@
 ---
 name: managing-d2h-toolchain
-description: 安装、检查或升级 D2H 所依赖的 AppGraph 与 droid2hmos CLI 时使用。统一读取 D2H 包内的精确版本锁，保留本地 npm link，并把安装结果交还迁移主流程；其他 Skill 不执行工具安装。
+description: 独立检查、安装或升级迁移所需的精确版本 AppGraph 与 droid2hmos CLI。
 ---
 
-# 管理 D2H 工具链
+# 管理迁移工具链
 
-本 Skill 是 AppGraph、droid2hmos 依赖声明、版本维护和安装的唯一流程入口。**依赖包、精确版本及命令能力只在本目录的 `toolchain.json` 声明**；`environment-requirements.json` 提供对应的主机检查边界。其他 Agent/Skill 不声明这些依赖或版本，也不执行 npm 安装或升级。`d2h` CLI 只解析本 Skill 的清单并实现确定性的探测、安装和校验；本 Skill 负责选择时机、目标 Agent 和失败分流。
+本 Skill 是迁移流程检查和维护 AppGraph、droid2hmos 的入口。`toolchain.json` 声明精确 npm 坐标及必需的命令能力；`environment-requirements.json` 声明主机环境约束。其他 Agent/Skill 只使用通过检查的 CLI，不自行选择版本或安装。以下脚本随 Skill 一起复制，直接由 Node.js 执行。
 
-## 选择 D2H 版本
+## 检查与安装
 
-- 已安装的 OpenCode/DevEco 定义读取配置根目录的 `.d2h-installation.json`；VS Code 定义读取扩展 `resources/opencode/plugin/d2h/.d2h-installation.json`。其中的 `packageVersion` 是本次调用 D2H CLI 的精确版本。
-- `d2h` 命令可用时先执行 `d2h --help`，确认支持 `install`、`upgrade`、`doctor`。需要通过 npx 调用时使用 `npx --yes @harmonyos-arkts/d2h@<packageVersion>`；Windows 使用 `npx.cmd`。不可用或记录缺失时，请调用方提供已批准的**精确 D2H 版本**完成首次安装，不猜测 `latest`。
-- 源码开发使用当前仓库构建出的 `node dist/bin/install-opencode.js`，不要把 npm 上同版本的旧包误当成本地源码。修改 D2H 依赖版本时只改包内 `skills/managing-d2h-toolchain/toolchain.json`，同时更新环境约束、兼容性测试和发布版本。
+在本 Skill 目录运行（Windows 可使用 `node.exe`）：
 
-## 检查与执行
+```sh
+node scripts/manage-toolchain.mjs check
+node scripts/manage-toolchain.mjs install
+```
 
-1. 确定目标 `--agent opencode|deveco|vscode`；VS Code 可通过 `--extension-dir` 指定扩展根目录。先运行 `d2h upgrade --check --agent <agent>` 只读预览，再运行 `d2h doctor --agent <agent>` 检查定义完整性、精确版本、命令能力与主机环境。
-2. 若缺少定义或受管 CLI，运行 `d2h install --agent <agent>`；已安装但需要应用当前锁定组合时运行 `d2h upgrade --agent <agent>`。默认保留开发者的 npm link；只有调用方明确指定 `--force` 时，才重新安装清单中的所有精确版本并替换全局 link，链接指向的源码目录保持不变。
-3. 安装后重新运行 `doctor`，核对 `.d2h-installation.json`、AppGraph/droid2hmos 的版本及能力，再把状态交给 `preparing-migration-workspace`。项目级 `droid2hmos preflight` 仍由准备 Skill 执行。
-4. 只想检查主机工具时使用 `d2h --check-env --output-dir <目录>`；读取生成的 JSON/Markdown 报告，不把 DevEco 登录、SDK 或设备缺失误判为需要升级 AppGraph/droid2hmos。
+1. 首先运行 `check`。脚本读取同目录 `toolchain.json`，分别调用 `appgraph --version`、`droid2hmos --version` 和清单中声明的命令能力探针，逐项报告指定版本、实际版本及能力。全部符合时退出码为 0；缺失或不符时退出码为 1。
+2. `check` 失败时运行 `install`。脚本只对缺失、版本或能力不符的工具执行 `npm install --global <精确坐标>@<精确版本>`，随后重新检查。已符合要求的工具不会重装。安装失败或安装后仍不符合要求时停止迁移并报告错误；不能静默使用其他版本。
+3. 已存在的全局 npm link 默认受保护。需要替换链接时，调用方须明确要求 `node scripts/manage-toolchain.mjs install --force`；它会重新安装清单中的全部精确版本。脚本不会修改链接指向的源码目录。
+4. 安装完成后再运行一次 `check`，通过后才交给 `preparing-migration-workspace`。项目级 `droid2hmos preflight` 仍由准备 Skill 执行。
 
-安装失败时保留命令输出和失败阶段。包不可达、版本不匹配、能力不符分别报告；不得把失败掩盖成“使用已安装版本继续”。不允许在其他 Skill 中直接执行 `npm install -g`、`npm update` 或以浮动版本重新安装这两个 CLI。
+首次使用本 Skill 时，要求 Node.js 22.5–24.x 和 npm 可用。工具已符合清单要求时，`check` 直接通过，`install` 不重复安装。修改依赖版本时只修改本目录的 `toolchain.json`，同步更新环境约束和测试。其他 Skill 不执行 `npm install -g`、`npm update` 或浮动版本安装。