@harmonyos-arkts/d2h 0.1.21 → 0.1.22

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "android-to-hmos-migration",
   "description": "基于确定性 facts、迁移报告与端到端验证的 Android 到 HarmonyOS 迁移插件",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "license": "MIT",
   "keywords": [
     "android",

package/agents/d2h.md

@@ -102,14 +102,14 @@ description: Android 应用到 HarmonyOS 的 AI 驱动迁移主 Agent；按迁
 - 转换图片和 drawable 时使用 `android2hmos_resources_convert`；发现尺寸或比例问题时使用 `arkts-icon-sizing`。
 
 
-2. 加载 `d2h-spec-develop`，以严格串行方式执行 spec 开发。每次最多在一个 worker 中派发 3 个 spec 完成任务：
+2. 加载 `d2h-spec-develop`，以严格串行方式执行 spec 开发。每个独立 page-worker 负责 3 个 spec 页面的开发；剩余不足 3 个时按实际数量派发，同一时间只运行一个 page-worker：
 
-a. 主 Agent 按 `batch_report.json` 选择顺序最前且未达到 `implemented/passed/passed` 的页面。
-b. 只派发一个独立 page-worker，且该 worker 只负责当前一个页面。worker 必须加载 `d2h-spec-develop`，不得领取、预研或修改后续页面。
+a. 主 Agent 按 `batch_report.json` 选择顺序最前且未达到 `implemented/passed/passed` 的最多 3 个页面，作为当前 worker 的任务批次。
+b. 只派发一个独立 page-worker，由该 worker 按顺序逐页完成当前批次。worker 必须加载 `d2h-spec-develop`，同一时间只开发当前一个页面，不得提前预研或修改后续页面，也不得领取批次外页面。
 c. 进入测试阶段时加载 `d2h-hypium-forge`，生成或更新该页面的 Python Hypium 测试资产。先确认本次构建的 HAP 已安装到目标设备，再按该 Skill 执行当前页面及受影响功能的定向测试，保留实际结果、日志和必要截图。主 Agent 核对执行用例及其断言是否覆盖 Spec 功能项，不能仅凭进程退出码或汇总文案判定通过。
 d. 页面实现与测试通过后，在 `batch_report.json` 当前页面明细中记录真实实现文件、Android 源码依据、本次构建与 Forge 测试的实际结果及证据路径，以及差异或阻塞。未产出或未保存的结果、日志如实记录为缺失，不得填写假定存在的路径或据此标记通过。
 e. 主 Agent 完成当前页面的实现提交，原位更新 `batch_report.json`，并按 Skill 的页面完成清单复核实现、构建、测试、证据、提交和工作区状态。
-f. 前页面未闭环、仍有页面所属未提交修改或复核失败时，只能继续修复当前页面。当前页面完整闭环并通过主 Agent 复核后，才能按顺序选择并派发下一页。
+f. 前页面未闭环、仍有页面所属未提交修改或复核失败时，只能继续修复当前页面。当前页面完整闭环并通过主 Agent 复核后，同一 worker 才能继续批次内下一页；当前批次全部闭环后，主 Agent 才能选择下一批页面并派发新的 worker。
 
 若当前环境不支持独立 page-worker，必须明确报告该开发模式无法执行，不能静默改成主 Agent 批量开发。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harmonyos-arkts/d2h",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "Install Android-to-HarmonyOS migration agents and skills into OpenCode or DevEco Code",
   "type": "module",
   "bin": {

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

@@ -1,143 +1,41 @@
 ---
 name: d2h-spec-develop
-description: Implement fixed versioned incremental Specs in from-plan mode, or use the original ordered page-ledger flow in legacy-page mode. Implement ordered Android-to-HarmonyOS page tasks from pages.json, batch_report.json, and page-scoped spec.md files. Use during page development when a dedicated page-worker must complete one page through ArkTS implementation, managed build, Python Hypium tests, scoped commits, migration-report evidence, and in-place ledger updates before the next page starts.
+description: Implement assigned Android-to-HarmonyOS Specs with source-grounded code, managed build and test evidence, scoped commits, and implementation handoff. Use for page or incremental Spec development under the caller's dispatch.
 ---
 
-# Spec implementation modes
+# Spec 实施
 
-- `from-plan`: a v2 plan, fixed spec_ids/batch and detailed generated Specs are supplied. Follow [fixed implementation](references/worker-workflow.md) and public `d2h workflow contract dispatch`. Return scoped code, evidence and requests; do not select tasks, load other Skills, write execution/report ledgers or claim acceptance. Do not execute the legacy workflow below.
-- `legacy-page`: the original v1 pages.json and tasks[] ledger flow below. Preserve its serial page worker, implementation, actual evidence and ledger requirements.
+按调用方指派的 Spec 范围实施 HarmonyOS 页面与业务能力。worker 的创建、每批 Spec/页面数量、执行顺序和逐页复核由主 Agent 或调用方决定，本 Skill 不另设数量或调度限制。
 
-A supplied incremental v2 plan selects from-plan. Invalid/missing version bindings return needs-input, never silently fall back to legacy or mix ledger schemas.
 
-## Original page workflow (legacy-page only)
 
-# Page development loop
+输入包含增量 v2 计划时，按公共 `d2h workflow contract dispatch` 核对固定 spec_ids、计划/范围版本及批次绑定；绑定缺失或冲突时返回具体缺口。页面 Spec 输入按调用方给定的页面范围执行，不要求先生成 v2 计划。
 
-Implement and verify one ordered page task at a time. The parent agent selects and reviews the task; a dedicated page-worker owns exactly one page's complete loop.
+返回真实实现、证据和未解决请求，由调用方维护执行账本、阶段状态及报告并决定验收。
 
-## Inputs and boundaries
+# Spec 实施与结果交接
 
-- Use `.migration/page-specs/pages.json` as the immutable page order and `batch_report.json` 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.json` 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.
+只处理输入明确指派的 Spec。先核对计划/范围版本、Git 基线、允许路径和成员；存在冲突时返回具体缺口，不覆盖用户修改。派发数据字段见公共 `d2h workflow contract dispatch`，本 Skill 不要求任何规划技能先运行。
 
-## Parent-agent mode
+## 理解与实施
 
-1. Read `pages.json` and `batch_report.json`; 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. Dispatch exactly one page-worker with absolute paths, selected task ID, dispatch baseline, device target, and evidence directory. Do not run page-workers in parallel or give one worker multiple pages.
-5. Wait for the worker to complete the selected page. If it is incomplete or fails review, send the same page back for repair; do not select another page.
-6. Independently verify the resulting implementation, current managed build/test evidence, migration report, commits, batch ledger, and Git status.
-7. Only after the selected task is genuinely `implemented/passed/passed` may the parent select the next task.
-8. Only when the user explicitly requests it, enumerate every Python Hypium test list and run one managed batch regression. Append the batch evidence to `batch_report.json` and the migration report.
+1. 阅读页面 spec.md 中当前 spec_id/check 的完整行为、异常、操作、源码依据与实现范围，定向追踪 Android 入口、状态、数据副作用和导航。页面共享摘要用于定位，不能代替源码理解。
+2. 沿用已给定的目标模块、目录、资源规范和状态/生命周期边界。接口缺失、所有权不清或与实际代码冲突时，返回带源码定位的 requiredInputs / planChangeRequests，不自行改方案或扩大范围。
+3. 同一窗口沿用页面上下文，逐成员实施。提供者形成实际代码后返回真实符号、路径、参数/错误语义与生命周期说明，等待调用方确认当前能力再实施消费者；不能用规划签名猜接口。
+4. 实现真实可达的 UI、导航、业务状态、数据效果和要求的失败路径。每个 check 对应实际行为、稳定语义定位和结果断言；不得添加测试替代控件、固定成功值、吞错或不可达页面。
+5. 当前范围涉及平台 API、原生库、身份/资源/i18n 等未知问题时，返回领域请求：问题、来源、当前尝试、所需结论及消费者。调用方提供结论后继续，不在此加载其他技能。
 
-Use this worker prompt contract:
+## 构建、检查与提交
 
-```text
-Use $d2h-spec-develop in page-worker mode. Complete exactly <TASK_ID>.
-Migration root: <absolute path>
-Page package: <absolute path>
-Android root: <absolute path>
-HarmonyOS root: <absolute path>
-Repository root: <absolute path>
-Dispatch baseline: <HEAD and recorded Git status>
-Device target: <target>
-Evidence directory: <absolute task/run directory>
+- 依据输入项目配置运行已授权的 `droid2hmos build harmony <ANDROID_PROJECT>`，命令非交互且有超时，保留真实命令、退出状态、时间、日志、HAP 路径和哈希。
+- 已提供可执行测试资产且授权本次检查时，可直接运行受管 CLI，保留实际断言、设备、执行数、原始报告和 managedEvidence。缺少测试设计、资产、设备或需共享安装窗口时返回 verificationRequests，不能只写测试未跑却报告通过。
+- 即时契约和高风险检查必须有实际结果，缺口交调用方组织验证；低风险合批待测明确列出，不暗示已验收。静态检查/服务探针不能代替正式设备证据。
+- 修复本范围实现或检查缺陷，保留现有理解与原始失败证据。真实外部问题在诊断和有限重试后可返回 blocked；实现错误不能改写为平台差异。
+- 仅暂存当前实现、资源、必要共享修改和实际测试资产。构建及已要求的即时检查通过后创建或交回作用域提交；允许明确标注待合批验证的实现提交，不把它称为验收提交。残留本任务修改、用户文件及其他任务修改分别列明，不一并提交。
+- 实现提交与后续状态/证据记录分开，由调用方维护后者，避免提交 ID 自引用。当前候选变化后的旧 HAP/证据是否失效由公共运行时维护，不把旧结果绑定新代码。
 
-Own the complete page loop: read spec.md, UTG evidence and cited Android source;
-implement the page; run managed build; load $d2h-hypium-forge and execute the
-page tests through the managed Python runner; update the migration report;
-create scoped commits; and update batch_report.json in place. Do not start another page.
-```
+## 返回
 
-If independent page-worker execution is unavailable, return that the required mode cannot run. Do not silently implement multiple pages in the parent agent.
+逐 spec_id/check 返回：实际修改与可达行为、接口与消费者、提交/源码身份、构建和测试证据、未执行检查与原因、剩余缺口、请求及用户修改保留情况。耗时未知填 null，不编造节省比例。
 
-## Page-worker mode
-
-### 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 dispatch 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.json`.
-- 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. Before implementing platform capabilities or uncertain HarmonyOS APIs (`@kit.*` Kit imports or `@ohos.*` modules), and when build or test failures point to API signatures or behavior, load `d2h-cloud-knowledge`: check `.migration/knowledge/kb_cache.json` first, query only on cache miss, and record conclusions with doc `title`/`uri` back into the cache, the page spec evidence, and the migration report.
-- 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 only the current page's test lists (the `pageNNNN_*` lists owned by this task) through the managed entry point. Do not append regression lists from other pages.
-
-  ```text
-  droid2hmos test harmony <ANDROID_PROJECT> \
-    --runner python --hypium-project <HARMONY_PROJECT>/.hypium_forge \
-    --test-list <THIS_PAGE_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 selected `tasks[]` object in `batch_report.json`: states, evidence, files, implementation commit, differences, timestamp, blockers, and append-only history. Recalculate `summary` using the classification in `d2h-spec-generate` and update the report timestamp. Do not rerun `build_batch_report.py`.
-- Set `development/build/validation` to `implemented/passed/passed` only with current evidence. Check task/summary consistency and preserve all prior history; store batch regression evidence and review in `regression`.
-- Commit the ledger and immutable task evidence separately from the implementation commit. Do not create a self-referential commit field.
-
-## Parent verification
-
-Before accepting the worker result, independently 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.json` is valid JSON, its summary matches `tasks[]`, and the selected task 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.
-
-Review failure returns the same task for repair. The worker never selects or starts the next task.
-
-## Batch regression
-
-Run the batch regression only when the user explicitly requests it. During ordinary page development, run only the current page's test lists (see Step 4). The parent agent's final delivery gate in `agents/d2h.md` remains responsible for application-wide acceptance.
-
-When a batch regression is requested:
-
-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.json`, then update and validate the migration report.
-5. Treat this managed Python batch as the primary application-wide regression for the page-spec workflow. Run ArkTS `--all` only as supplemental coverage when the project maintains relevant ArkTS ohosTest assets; it is not a fixed completion gate for this workflow.
-
-## Worker result
-Return the task ID and page, final states, implementation and test files, managed build command/HAP/evidence, managed test command/evidence, implementation and ledger commit IDs, unrelated Git changes left untouched, and any genuine blocker or unresolved item.
+不选择下一个批次，不更新执行账本、阶段状态或任何报告。调用方独立核对实现、断言、当前候选、HAP 和设备身份后记录状态与决定验收。

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

@@ -1,7 +1,7 @@
 interface:
   display_name: "HarmonyOS Spec Development Loop"
-  short_description: "按 spec.md 完成单页面受管开发、测试与提交闭环"
-  default_prompt: "Use $d2h-spec-develop to serially implement ordered HarmonyOS page tasks from pages.json, batch_report.json, and spec.md in the current agent without delegating page work to subagents."
+  short_description: "按指派 Spec 完成鸿蒙实现、受管构建检查、作用域提交与证据交接"
+  default_prompt: "Use $d2h-spec-develop to implement the assigned HarmonyOS Specs and return scoped code, build and test evidence, commits, and unresolved requests."
 
 policy:
   allow_implicit_invocation: true