@harmonyos-arkts/d2h 0.1.19 → 0.1.21

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

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

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

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

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

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

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

@@ -1,132 +1,143 @@
----
-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 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.
----
-
-# Page development loop
-
-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
-
-- 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.
-
-## Parent-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. 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. 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.
-
-Use this worker prompt contract:
-
-```text
-Use $d2h-page-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>
-
-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.md 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.
-
-## 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.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. 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 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.
-
-## 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.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.
-
-Review failure returns the same task for repair. The worker never selects or starts 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. 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.
+---
+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.
+---
+
+# Spec implementation modes
+
+- `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.
+
+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
+
+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
+
+- 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.
+
+## 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.
+
+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>
+
+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.
+
+## 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.

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

@@ -0,0 +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."
+
+policy:
+  allow_implicit_invocation: true

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

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