@harmonyos-arkts/d2h 0.1.19 → 0.1.21

package/contracts/workflow/plan.md

@@ -0,0 +1,119 @@
+# v2 计划数据契约
+
+编写或校验 pages.json 时读取；语义拆分与评分方法见 计划生产者的方法说明，派发、证据与修订事件见 [执行协议](execution.md)。
+
+程序路径：`d2h workflow`，Python 3 标准库，无额外运行依赖。它不读取源码推断功能、不自动执行命令或派发 agent，只校验 AI 明确写出的计划与证据。主 Agent 必须独立核验语义和原始工具结果。
+
+## 校验入口
+
+先写计划并评审波次，详细文档可以尚未生成。新计划设置 `spec_generation_policy=required-v1`，生成方按选定版本展开当前成员，详见 [生成契约](generation.md)。只校验规划时运行：
+
+```bash
+d2h workflow validate --planning-only --plan <pages.json> --features <features.json>
+```
+
+校验结构、来源版本、覆盖关系、依赖与批次预算后，仍需 AI 核验源码及语义。若任务只需计划校验，到此即可；初始化或更新执行状态再读取运行时协议。
+
+## 架构交接
+
+完整迁移按 [产物契约](artifacts.md) 在可选 inputs 中保存 featureAnalysis/architecturePlan/shellReceipt 的绝对路径；feature_source 仍引用版本化功能计划。allocation.owned_paths 沿用确认架构，页面正文保留共享边界与风险。运行时不自动验证这些扩展路径或架构归属，须由主 Agent 核验，不将其写成已有机器门禁。
+
+## 文件与计划示例
+
+features.json 新建使用 `d2h-feature-plan/v2`（兼容读取 v1，但不能宣称逐项全量覆盖），由调用方维护。保存内容哈希的方法为 Python `hashlib.sha256(json.dumps(data, sort_keys=True, ensure_ascii=False).encode()).hexdigest()`，即规范化 JSON 内容哈希，不是原始文件字节哈希；source revision 与文件绝对路径都要匹配。
+
+features.json v2 的可选 delivery 由上游维护分层映射及目标，跟随 feature revision/hash；不在 pages.json 复制一份选用范围。缺少配置时兼容旧行为，derive.delivery_progress.configured=false；分层累计、范围草稿和 Review 见 [交付与看板](delivery.md)。
+
+pages.json 示例（单 Spec，仅示范完整字段，不表示真实应用已实现）：
+
+```json
+{
+  "schema_version": "d2h-page-plan/v2",
+  "revision": 1,
+  "feature_source": {"path": "/abs/migration/.migration/feature-planning/features.json", "revision": 1, "sha256": "<canonical-content-hash>"},
+  "milestone": "home-skeleton",
+  "dispatch_mode": "page-batches",
+  "implementation_workers": 1,
+  "work_packet_policy": "required-v1",
+  "validation_policy": {"max_pending_specs": 3, "max_pending_hours": 4, "max_age_hours": 8},
+  "pages": [{"page_id": "login", "package": "page_login", "scope_complete": false}],
+  "specs": [{
+    "spec_id": "login-basic", "page_id": "login", "feature_refs": ["feature-login"], "milestone": "home-skeleton",
+    "scope_refs": [{"feature_id": "feature-login", "scope_id": "login-basic", "checks": ["login-basic/AUTH-01", "login-basic/AUTH-02"]}],
+    "scope": ["一个真实登录方式、必要会话和基本失败反馈"],
+    "implementation_brief": {
+      "behavior_notes": ["合法凭据建立会话并进入首页，失败不建立会话"],
+      "invariants": ["登录状态与实际鉴权结果一致"],
+      "known_pitfalls": ["页面局部变量不能替代共享会话存储"],
+      "open_questions": []
+    },
+    "evidence_refs": ["source:Login.submit", "user:basic-login"],
+    "requires": [],
+    "provides": [{"capability": "session.basic", "checks": ["login-basic/AUTH-01", "login-basic/AUTH-02"]}],
+    "checks": ["login-basic/AUTH-01", "login-basic/AUTH-02"],
+    "ratings": {"milestone": 5, "unlock": 5, "user_value": 5, "risk_reduction": 4, "feedback": 5},
+    "effort": {"low": 2, "expected": 4, "high": 8, "confidence": "low", "remaining_elapsed_hours": 6},
+    "allocation": {"recommended_workers": 1, "owned_paths": ["entry/src/main/ets/login/"], "rationale": "会话与导航紧密关联，先由单 worker 收敛"},
+    "testing": {
+      "risk_dimensions": {"impact": 3, "shared": 2, "uncertainty": 1, "dependency": 3},
+      "triggers": ["authentication"],
+      "immediate": ["login-basic/AUTH-01", "login-basic/AUTH-02"], "batch": [],
+      "latest_validation_point": "home-skeleton", "estimated_hours": 1,
+      "layers": [
+        {"check_id": "login-basic/AUTH-01", "layer": "device", "reason": "真实鉴权和导航"},
+        {"check_id": "login-basic/AUTH-02", "layer": "device", "reason": "实际失败不能建立有效会话"}
+      ]
+    }
+  }],
+  "rounds": [{
+    "round_id": "usable", "order": 1, "kind": "baseline", "milestone": "home-skeleton",
+    "goal": "真实登录与必要失败反馈可用", "rationale": "先打通核心入口",
+    "goal_checks": ["login-basic/AUTH-01", "login-basic/AUTH-02"]
+  }],
+  "page_batches": [{
+    "batch_id": "login-basic-pass", "page_id": "login", "round_id": "usable",
+    "spec_ids": ["login-basic"], "goal": "完成登录基础能力", "rationale": "会话与表单状态共享",
+    "max_specs": 3, "max_effort_hours": 6, "opportunistic_hours": 0
+  }],
+  "dispositions": [],
+  "retired_specs": []
+}
+```
+
+- 所有功能需要 spec 覆盖，或显式 disposition `{feature_id, reason}`；included 且阶段已分配、需求清晰的功能不能通过 disposition 隐藏。
+- spec 的 feature_refs 必须指向 included、无需澄清的功能；v2 功能的阶段授权按 scope_refs 对应范围项判定。未分配/延后/排除/待澄清功能留在清单和 disposition，不能被继承优先级强行拉入。
+- 检查 ID 全局唯一，建议 `<spec_id>/<check_id>`。checks 必须由 immediate 和 batch 不重叠地完整分区。provides 的契约检查属于 immediate；高风险全部即时。requires 引用唯一选定提供者，先校验用户顺序和能力依赖的组合 DAG。
+- `requested_before` 为功能级约束：前一功能的相关 Spec 完整验收后，才允许后一功能。若用户只希望基本能力提前，应先在上游准确缩小功能范围或拆分功能，而非默默弱化该约束。
+- 只执行当前 milestone 及其必要早期依赖，页面模式还限制在当前未交付轮次。有效优先级为自身与未完成目标继承值中的最高值，inherited_from 返回 spec_id；用户优先级不变。先比较有效优先级、剩余关键路径与共享解锁，同级优先同页连续开发，再比较收益/成本及稳定 batch_id。主 Agent 阅读 ready_batches 后选择，不把脚本候选当源码语义判决。
+- 日期采用带时区 ISO8601。测试积压数量、估计小时、等待年龄任一达到上限停止新 start。独立工作可在未触发背压时继续，消费者始终受即时能力约束；修复和验证不受新增实现背压阻止。
+
+## 轮次与页面批次
+
+轮次范围评估由计划生产方负责，按 调用方的轮次范围评估 记录目标、范围、最小前置、暂缓理由、成本风险及验收条件。复用已有 rounds.goal/rationale/goal_checks、page_batches、Spec.scope_refs 与页面 spec.md；不新增独立轮次真源，也不修改旧计划 schema。
+
+新增计划显式写 `dispatch_mode=page-batches`；省略时按既有 single-spec 行为兼容，不隐式改在途任务。rounds 与 page_batches 只能在页面模式使用，转换须保存旧基线、释放在途任务及批次后 reconcile。
+
+- 里程碑来自上游，round 是其内部的实现轮次，具有独立 goal 和目标路径 goal_checks，不能替代或改写用户范围。一个里程碑可以包含多轮，一个页面可在多轮出现。每个里程碑第一轮且仅一轮为 baseline；后续为任意多轮 incremental，completion 若存在只能在该里程碑最后。轮次 order 按数组连续且不能倒置里程碑顺序。
+- page_batch 恰好属于一轮和一个主页面；spec_ids 不重复且全部 Spec 恰好覆盖一次。各成员的 page_id 和 milestone 必须匹配；max_specs/max_effort_hours 限制完整计划批次，超限须拆分。rationale 记录真实状态、代码或测试准备复用依据，不能仅因名称相似合并。
+- 当前里程碑引用早期轮次时，补齐该轮完整成员、同里程碑更早轮次及其能力前置，不能只纳入半个轮次导致目标无法验收。这些成员须已由用户授权并显式列在计划中。
+- 内部依赖保留并逐项核验。不能依赖更晚轮次，也不能形成“页面 A 第一项→页面 B→页面 A 第二项”的批次收缩环；此时拆成不同访问批次。归拢不会把未验证能力变成 ready。
+- opportunistic_hours 为低优顺带项预算，默认建议 0。派发时先选最高有效优先级成员及其必要前置；仅当较低优成员总成本在预算内、且没有其他就绪页面更高优任务等待时一起领取。否则低优项留在原批次后续派发，不丢失需求。实际窗口的成员由 derive 固定建议，start_batch 必须完全匹配该建议，且只能选择就绪批次的最高有效优先级层。若外部更高优任务在领取后恢复，开始顺带项前应暂停并让出窗口。
+- active_batch 是独占的实际窗口；同一 worker 在其中逐 Spec start，实现和测试。一次领取多项不表示并发多个 worker。窗口外任务禁止 start，跨窗口 repair 也需先暂停现有窗口。成员或外部依赖中途受阻时显式 pause、pause_batch 保存进度，恢复后仅建议剩余成员。
+- derive 返回 current_round、rounds、page_batches、ready_batches、active_batch、pages、page_dispatch_metrics。ready 仅表示已领取窗口内当前能启动的 Spec；ready_specs 是当前轮次的观察值，不能绕过 start_batch 直接派发。无活动窗口时 ready 为空。
+- pages[].scope_complete 是 AI 核对全部约定页面范围的声明，为 true 时必须有 scope_evidence_refs（非空源码/清单范围依据）；它本身不是实现完成状态。输出 pages[page_id].baseline_verified 代表该页第一次访问范围在当前候选已验收，complete 还要求全量范围声明及该页所有后续 Spec 当前验收。page_pass 为局部批次序号，不能与全局 round.order 混淆。
+- round_accept 必须逐项 accepted 后执行目标路径。历史 delivered 保留经过核验的目标签名和不可变原始证据；current_accepted 还需当前候选全部成员及目标证据有效。候选变化不抹去历史交付，也不把新轮开发无条件退回首轮；但当前能力与验收不会复用旧 HAP PASS。显式 failed/invalidate 撤销受影响轮次和依赖消费者的可用历史证明，原事件仍保留。
+- 最终里程碑必须所有相关轮次 current_accepted 且完整 regression 通过。同一真实最终回归可以分别映射各轮目标和 Spec 检查，不宣称重复引用就是多次执行。HAP 和报告使用不可变证据路径，不能覆盖导致历史证明丢失。
+
+## 逐项范围映射与完成语义
+
+新功能清单使用 d2h-feature-plan/v2。每个 Spec 的 scope_refs 为非空数组，每项包含 feature_id、scope_id 和非空 checks（该 Spec 实际验收检查的子集）。每个 feature_ref 和每项 Spec check 均须被映射；一个已分配且授权 included 的范围项恰好由一个 Spec 负责。若一项需求必须由多个独立 Spec 分担，先在上游拆成可独立验收的范围项。依赖复用用 requires/provides，不重复认领同一范围。
+
+功能可跨里程碑；deferred/excluded/unresolved/unassigned 项不强制提前生成 Spec，但始终留在 feature_progress 中。缺失、重复认领、越阶段或越 checks 引用均拒绝。feature_progress.complete 仅当所有未排除项在当前候选验收通过；scope_coverage_accepted 是全清单范围门禁，不等于全应用最终回归。旧 v1 输出 scope_tracking=false、scope_coverage_accepted=false，不能凭 feature_refs 宣称全量完成。
+
+同页 spec.md 持续维护“范围项 → 轮次 → Spec → checks”表。基础 Spec 完成后保持 ID、范围和历史；完善功能新增增量 Spec，复用页面与已验证能力。仅需求变更才修订原 Spec，回归故障则 invalidate/repair。reconcile 对新增无关范围保留原 Spec；修改其实际范围、断言或映射会使受影响验收失效。页面 complete 还要求该页所引用功能的范围全部解决；跨页功能采取保守关联，不能只凭当前页面的已生成 Spec 声称完整。
+
+## 实施工作包
+
+页面文档按 完整行为规格及调用方模板 生成，保留页面共享上下文及独立 spec_id 章节。page_batches 是同轮同页的组织与派发分组，不合并成员验收身份；无需新增 generation_groups 或改变现有 schema。
+
+规划不编写详细 spec.md。新计划显式启用 work_packet_policy=required-v1 与 spec_generation_policy=required-v1；前者约束实施输入，后者对未生成/失效正文阻止派发。implementation_brief、testing.layers、shared_contracts 的字段与开工条件见 [派发契约](dispatch.md)。旧计划不隐式开启；升级须释放在途任务并 reconcile，策略变化会重新核验实施范围。接口回执只在执行账本维护。

package/contracts/workflow/scope.md

@@ -0,0 +1,151 @@
+# 功能规划与下游交接
+
+## 输入与处理
+
+默认输出 `<migration_root>/.migration/feature-planning/features.json`；无迁移根时用用户指定目录。原始 `inventory.json`（兼容旧 feature-analysis.json）保留在 `.migration/feature-analysis/`，不复制成另一份可修改分析真源。原始分析只读，来源结构和字节绑定由公共工具核验；不调用分析生产者的私有校验程序。
+
+1. 读取用户提供的输入和已有计划。Facts 的 index、unresolved 和 UTG 是范围与证据线索；需要确认可见行为时继续读取对应源码，不能把抽取结果当作运行时验证。
+2. 按稳定引用识别相同功能；名称相似只作为候选。不同入口可以共享能力，但保留路径差异。若一个盘点条目对应多个规划功能或反之，通过 source_refs 显式表达映射。
+3. 将用户新增需求、范围修改、里程碑、优先级、顺序分别记录。优先级为 must/normal/later，默认 normal。交付优先采用用户明确选中的范围，恢复时保留仍有效的既有用户选择；无明确选择时按默认核心功能规划。AI 为核心范围及必要依赖安排阶段，未排期或待澄清项保持 unassigned，不伪装成用户已指定阶段。
+4. 保持 feature_id 稳定。重命名、排序不改变 ID；拆分或合并分配新 ID，通过 derived_from 保留来源。延后不删除功能，排除保留原因。
+5. 输出 features.json，运行校验，并交付简要的功能/阶段/优先级/顺序/未决项摘要。计划模式不要求 CSV、XLSX 或额外分析文件。
+
+用户要求“登录基本可用，首页优先”时，将基本登录和其余约定范围分别登记为稳定 scope_items；其余项明确延后；首页记录用户优先级。向下游传达最小前置切片建议，不在此创建 session.basic 或伪造登录已通过。下游负责推导和验证实际能力依赖。
+
+## 输出契约：d2h-feature-plan/v2
+
+```json
+{
+  "schema": "d2h-feature-plan/v2",
+  "revision": 1,
+  "sources": [
+    {
+      "source_id": "user-1",
+      "kind": "user",
+      "locator": "本轮用户需求",
+      "revision": "message-1"
+    }
+  ],
+  "milestones": [
+    {
+      "milestone_id": "home-skeleton",
+      "title": "首页雏形",
+      "acceptance": [
+        "真实登录后可使用首页主导航"
+      ]
+    }
+  ],
+  "features": [
+    {
+      "feature_id": "feature-login",
+      "title": "登录",
+      "origin": "user",
+      "source_refs": [
+        {
+          "source_id": "user-1",
+          "ref": "登录基本可用"
+        }
+      ],
+      "acceptance": [
+        "合法凭据登录后进入首页；失败不建立有效会话"
+      ],
+      "milestone": "home-skeleton",
+      "user_priority": "must",
+      "scope_status": "included",
+      "reason": "用户要求先打通基本登录",
+      "requested_before": [],
+      "derived_from": [],
+      "needs_clarification": false,
+      "scope_items": [
+        {
+          "scope_id": "login-basic",
+          "description": "一个真实登录方式、必要会话与基本失败反馈",
+          "status": "included",
+          "milestone": "home-skeleton",
+          "acceptance": [
+            "合法凭据登录后进入首页；失败不建立有效会话"
+          ]
+        },
+        {
+          "scope_id": "login-other-methods",
+          "description": "其他约定登录方式",
+          "status": "deferred",
+          "milestone": "unassigned",
+          "reason": "基础路径完成后再分配轮次",
+          "acceptance": [
+            "约定登录方式能建立真实会话"
+          ]
+        }
+      ]
+    }
+  ],
+  "changes": [
+    {
+      "revision": 1,
+      "actor": "user",
+      "feature_ids": [
+        "feature-login"
+      ],
+      "summary": "新增基本登录需求"
+    }
+  ],
+  "open_questions": []
+}
+```
+
+- sources.kind：facts / utg / inventory / source / user；locator 指向文件、目录或用户输入标识，revision 记录真实产物版本、提交或消息标识，不填推测值。
+- source_refs.ref 为 JSON Pointer、稳定事实 ID、源码符号或用户原始要求。source_id 必须存在；引用存在性与是否支持结论由 AI 阅读复核，校验脚本不证明语义正确。
+- origin：extracted / user / merged。extracted 至少有非 user 来源；user 至少有 user 来源；merged 两者均需。用户仅调整一个源码功能的优先级时，可保留 extracted，变更记入 changes，不伪造事实变化。
+- scope_status：included / deferred / excluded。deferred 与 excluded 必须有 reason；延后功能仍保留在全量清单。scope_items 是范围的唯一真源，不维护 required_scope/deferred_scope 的平行副本。
+- requested_before 表示显式用户顺序约束，不是源码能力依赖；禁止自身引用、未知 ID、环及跨里程碑约束。跨阶段先后通过 milestones 数组顺序表达；需要调整阶段时记录变更。
+- features 数组只是稳定展示顺序。用户明确排序时在同阶段按顺序建立相邻 requested_before，避免下游误把默认数组顺序当强约束。
+- milestone 必须引用已声明阶段或 unassigned；scope_items[].milestone 同样适用。未分配阶段的需求不得自动进入当前执行批次。
+- derived_from 可引用历史 ID，保留拆分合并关系；changes 追加记录，不覆盖既有历史。每次实际修改 revision 增一，无变化保持原 revision。
+- 本契约不包含实现完成状态、系统评分、worker_count 或测试通过字段，避免成为下游第二份执行账本。
+
+校验：
+
+```bash
+python3 <skill-dir>/scripts/validate_feature_plan.py /abs/path/features.json
+```
+
+更新已有计划时追加 `--previous /abs/path/previous-features.json`，校验版本递增、变更历史前缀及旧 ID 保留。拆分合并后的旧项保留并标 excluded，reason 写明被替代关系。
+
+## 下游交接与冲突
+
+交接绝对文件路径、schema 和 revision。下游保存消费的版本及 feature_refs，读取 scope_items、用户优先级和顺序约束，再推导增量 Spec。自动评分只能在用户约束内排序。
+
+若依赖与用户顺序冲突，下游反馈具体功能、证据、最小前置能力与建议；本模块根据授权修改计划并保留记录，下游不能静默改写。执行中固定派发版本，计划更新不得自动改写正在进行的任务。
+
+计划消费方读取 features.json 的路径、revision 和内容哈希，生成 v2 增量计划，由调用方派发实施能力。用户优先级不可机械换算成旧 page_score；旧 v1 计划需显式迁移并保留历史。当前实现限单实现 worker，能力即时门禁及验证队列由下游负责，不在本模块维护执行状态。
+
+## 稳定范围项与渐进完善
+
+- scope_items[].scope_id 在所属 feature 内唯一且稳定；重排、延期和改名不改变 ID。description、acceptance、status、milestone 描述需求与处置，不记录实现状态。status 为 included/deferred/excluded/unresolved，非 included 必须有 reason。
+- 功能 milestone 是默认规划归属；v2 中每项 scope_items.milestone 决定其实际交付阶段，同一功能可跨阶段。仅状态 included、阶段已分配且功能已授权、无需澄清的项进入 Spec。
+- 不能为赶基础路径删除已知范围。其余范围保留为 deferred 或 unassigned；未解决差异用 unresolved。重新排期时保持 scope_id，将对应项改为 included 并分配阶段，由下游新增增量 Spec。
+- 拆分范围时给新项分配 ID，保留旧项并以 excluded/reason 说明替代关系；旧范围 ID 不得删除。AI 核对需求是否穷尽、描述和断言是否相符，脚本只保证结构与映射完整。
+- 旧 v1 可继续读取，但不能宣称逐项全量覆盖。升级 v2 时先归档旧清单、计划和执行账本；由 AI 将 required_scope/deferred_scope 显式拆成 scope_items，保留 feature_id，revision 递增并记录变更，用 --previous 校验；下游同步 scope_refs 并 reconcile，旧验收不自动变成新范围的证据。
+
+范围项描述可识别的需求，不按按钮或每个校验条件机械拆分。多个紧密关联范围项可由下游一个 Spec 的多个 scope_refs 覆盖；上游保留需求完整性，下游依据交付、依赖和风险决定 Spec 粒度，未排期范围不提前展开实现细节。
+
+## 分层交付与看板草稿
+
+v2 可选 delivery；进入迁移交付规划时，用户明确选择优先，无明确选择则默认核心（target=core）。由 AI 按实际路径提出完整范围映射，将本次范围及必要依赖写为 included 并安排阶段，其他范围延期并保留原因；默认核心在 delivery.reason 与 changes（actor=ai）中说明，不伪造用户选择，不改 user_priority。仅分析/导出报告不自动启动交付规划。示例结构：
+
+```json
+{"delivery":{"target":"core","customized":false,"reason":"用户选择核心实现，其他范围后续排期","scope_layers":[{"feature_id":"feature-login","scope_id":"login-basic","layer":"mvp"},{"feature_id":"feature-login","scope_id":"login-other-methods","layer":"full"}]}}
+```
+
+交付目标与最低交付层独立：用户明确选择全量交付时 target=full，但每项 layer 仍按真实路径判定，不能批量设为 full。全量盘点只决定分析覆盖，不等于选择全量交付；进入迁移交付规划时仍按用户选择或默认核心确定目标。先识别项目最小可用闭环及必要共享能力，再区分核心增强和全量长尾；不得仅凭 P0/P1/P2、user_priority、页面次序或名称自动分层。对已有多功能应用，导出前核对 MVP 累计预设非空、核心预设包含 MVP 且确有可解释范围；小应用核心与 MVP 可以相同，不为凑层数创造功能。分层尚无依据时保留未知并说明，不造一个全 full 的已完成配置。
+
+分别检查三层累计数量、范围样例与必要依赖：依赖应在同层或更早层；无法裁决的跨层依赖保持未决，不擅自扩大授权。当前 target、scope_items 的纳入／延期状态及执行窗口不因生成最低层映射而自动改变。历史已配置错误时显式修订，保存基线及 revision/changes，再交下游 reconcile。
+
+target/layer 为 mvp/core/full；customized 为布尔值，reason 非空。所有未排除范围必须恰好映射一层，包含延期、未决和未分配项；排除旧项可保留原映射。MVP⊆核心⊆全量按最低层累计。customized=false 时，选用并已授权/分配的范围须与目标预设累计集合完全相同；包含未决项的全量预设不能自动授权，先澄清或以 customized=true 明确保留待解决项。customized=true 时按 scope_items 实际授权，预设名称只保留为调整来源。
+
+勾选/取消及优先级调整形成草稿，取消默认延期，明确排除另写依据。预设不覆盖手动优先级与 requested_before。修改 delivery 也递增 F revision 并追加 changes，旧清单保持兼容且不自动产生配置。首次功能基线归档至同目录 baseline-features.json，后续不覆盖。
+
+看板草稿不是保存成功的计划。接收 d2h-scope-change-request/v1 时先核对 feature/plan hash、候选与事件序号，再解释范围、依赖及优先级；跨范围最小前置与实际业务取舍交用户，不静默扩大。先更新并校验上游，再交规划能力返回修订结果，由调用方 reconcile；不能把用户草稿中的完成状态当成证据。详见 [交付与看板](delivery.md)。
+
+
+使用最小化/核心/全量预设（含无明确选择时的默认核心）时，交接前运行 `validate_feature_plan.py <features.json> --require-delivery`。该检查要求显式配置且三个累计预设非空，不能用“全部 full”配置充当完成分层；允许核心与 MVP 相同。不覆盖用户明确选择；结构校验不证明路径语义或依赖闭环，仍由 AI 核对。依据不足时先补齐核心范围与必要依赖，不让看板或运行时凭缺省字段自动猜选。

package/dist/bin/install-opencode.js

@@ -1,4 +1,12 @@
 #!/usr/bin/env node
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import os from 'node:os';
@@ -6,14 +14,17 @@ import { inspectInstallation, installOpenCode } from '../src/install-opencode.js
 import { inspectToolchain, installToolchain, loadToolchain } from '../src/toolchain.js';
 import fs from 'node:fs';
 import { inspectVSCodeInstallation, installVSCode } from '../src/install-vscode.js';
-const help = `Install this package's skills and agents into OpenCode or DevEco Code.
+import { codexConfigRoot, inspectCodexInstallation, installCodex } from '../src/install-codex.js';
+import { runWorkflow } from '../src/workflow.js';
+const help = `Install this package's skills and agents into OpenCode, DevEco Code or Codex.
 
 Usage: d2h [options]
 
   d2h install         Install compatible CLIs and agent/skill definitions
   d2h upgrade         Reapply this package's tested toolchain and definitions
   d2h upgrade --check Preview version and installation status only
-  d2h doctor [--agent opencode|deveco|vscode] [--config-dir <path>]
+  d2h workflow       Validate artifacts, record execution and generate reports
+  d2h doctor [--agent opencode|deveco|vscode|codex] [--config-dir <path>]
                       Check definitions, host environment and CLI capabilities
 
   --check-env         Check host tools and write reports without installing skills
@@ -21,11 +32,12 @@ Usage: d2h [options]
                        Use d2h --check-env --help for check options
 
   --source-dir <path>  Source root (defaults to this package)
-  --agent <name>       opencode (default), deveco or vscode
+  --agent <name>       opencode (default), deveco, vscode or codex
   --extension-dir <path>  VS Code HarmonyOS Dev Assistant extension root
   --config-dir <path>  Override the selected agent's config root
                        OPENCODE_CONFIG_DIR / DEVECO_CONFIG_DIR, or
                        $XDG_CONFIG_HOME/<agent>, or ~/.config/<agent>
+                       Codex: ~/.agents (skills under skills/; --config-dir overrides)
   --link              Create absolute symbolic links (development only)
   --force             Replace conflicting definitions and managed CLI npm links
   --remote            Use opencode-metrics-plugin instead of the default lite plugin
@@ -40,7 +52,10 @@ With npx, prefer the default copy mode: its cache can be removed.
 try {
     const args = process.argv.slice(2);
     const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
-    if (args[0] === 'doctor') {
+    if (args[0] === 'workflow') {
+        process.exitCode = runWorkflow(packageRoot, args.slice(1));
+    }
+    else if (args[0] === 'doctor') {
         let agent = 'opencode';
         let configDir;
         let extensionDir;
@@ -60,10 +75,10 @@ try {
             else
                 throw new Error(`unknown doctor option: ${arg}`);
         }
-        if (!['opencode', 'deveco', 'vscode'].includes(agent))
+        if (!['opencode', 'deveco', 'vscode', 'codex'].includes(agent))
             throw new Error(`unsupported agent: ${agent}`);
-        configDir ??= process.env[agent === 'deveco' ? 'DEVECO_CONFIG_DIR' : 'OPENCODE_CONFIG_DIR'] || path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), agent);
-        const installation = agent === 'vscode' ? inspectVSCodeInstallation(extensionDir) : inspectInstallation(configDir);
+        configDir ??= agent === 'codex' ? codexConfigRoot() : process.env[agent === 'deveco' ? 'DEVECO_CONFIG_DIR' : 'OPENCODE_CONFIG_DIR'] || path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), agent);
+        const installation = agent === 'vscode' ? inspectVSCodeInstallation(extensionDir) : agent === 'codex' ? inspectCodexInstallation(configDir) : inspectInstallation(configDir);
         const packageVersion = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8')).version;
         const definitionsMatch = installation.status === 'passed' && installation.packageVersion === packageVersion &&
             (agent === 'vscode' || ('agent' in installation && installation.agent === agent));
@@ -72,7 +87,7 @@ try {
         for (const item of results)
             console.log(`${item.status}: ${item.package} expected ${item.expectedVersion}, installed ${item.installedVersion ?? 'missing'}; capabilities ${JSON.stringify(item.capabilities)}`);
         const checkerUrl = new URL('../../scripts/check-environment.mjs', import.meta.url);
-        const { main } = await import(checkerUrl.href);
+        const { main } = await import(__rewriteRelativeImportExtension(checkerUrl.href));
         const environmentExit = await main([]);
         if (environmentExit !== 0 || !definitionsMatch || results.some(item => item.status !== 'passed'))
             process.exitCode = 1;
@@ -81,7 +96,7 @@ try {
         if (args.filter(arg => arg === '--check-env').length !== 1)
             throw new Error('--check-env may only be specified once');
         const checkerUrl = new URL('../../scripts/check-environment.mjs', import.meta.url);
-        const { main } = await import(checkerUrl.href);
+        const { main } = await import(__rewriteRelativeImportExtension(checkerUrl.href));
         process.exitCode = await main(args.filter(arg => arg !== '--check-env'));
     }
     else {
@@ -127,16 +142,18 @@ try {
                 throw new Error(`unknown option: ${arg}`);
             }
         }
-        if (!options.agent || !['opencode', 'deveco', 'vscode'].includes(options.agent)) {
-            throw new Error(`unsupported agent: ${options.agent}; choose opencode, deveco or vscode`);
+        if (!options.agent || !['opencode', 'deveco', 'vscode', 'codex'].includes(options.agent)) {
+            throw new Error(`unsupported agent: ${options.agent}; choose opencode, deveco, vscode or codex`);
         }
+        if (options.agent === 'codex' && remote)
+            throw new Error('--remote is not supported by Codex');
         if (options.agent !== 'vscode' && extensionDir)
             throw new Error('--extension-dir requires --agent vscode');
         if (options.agent === 'vscode' && options.configDir)
             throw new Error('--config-dir is not used for VS Code; use --extension-dir');
-        options.configDir ??= process.env[options.agent === 'deveco' ? 'DEVECO_CONFIG_DIR' : 'OPENCODE_CONFIG_DIR'] || path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), options.agent);
+        options.configDir ??= options.agent === 'codex' ? codexConfigRoot() : process.env[options.agent === 'deveco' ? 'DEVECO_CONFIG_DIR' : 'OPENCODE_CONFIG_DIR'] || path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), options.agent);
         if (checkOnly) {
-            const installation = options.agent === 'vscode' ? inspectVSCodeInstallation(extensionDir) : inspectInstallation(options.configDir);
+            const installation = options.agent === 'vscode' ? inspectVSCodeInstallation(extensionDir) : options.agent === 'codex' ? inspectCodexInstallation(options.configDir) : inspectInstallation(options.configDir);
             console.log(`definitions ${installation.status}: ${installation.summary}`);
             for (const item of inspectToolchain(packageRoot))
                 console.log(`${item.status}: ${item.package} expected ${item.expectedVersion}, installed ${item.installedVersion ?? 'missing'}`);
@@ -148,18 +165,20 @@ try {
         if (!checkOnly) {
             if (options.agent === 'vscode')
                 installVSCode({ sourceDir: options.sourceDir, extensionDir, remote, dryRun: options.dryRun });
+            else if (options.agent === 'codex')
+                installCodex({ ...options, remote });
             else
                 installOpenCode({ ...options, remote });
             if (!options.dryRun) {
                 const target = options.agent === 'vscode' ? 'VS Code HarmonyOS Dev Assistant' :
-                    options.agent === 'deveco' ? 'DevEco Code' : 'OpenCode';
+                    options.agent === 'deveco' ? 'DevEco Code' : options.agent === 'codex' ? 'Codex' : 'OpenCode';
                 const packageVersion = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8')).version;
                 console.log('\n============================================================');
                 console.log(`[D2H] Installation successful / 安装成功`);
                 console.log(`Target / 目标: ${target}`);
                 console.log(`Version / 版本: ${packageVersion}`);
                 console.log('Agent: d2h');
-                console.log(`Next / 下一步: restart ${target}, then select the d2h Agent.`);
+                console.log(options.agent === 'codex' ? 'Next / 下一步: start a new Codex conversation and invoke $d2h.' : `Next / 下一步: restart ${target}, then select the d2h Agent.`);
                 console.log('============================================================');
             }
         }

package/dist/src/install-codex.js

@@ -0,0 +1,131 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { stat, digest, sameTree, contains, resolvedLocation } from './install-opencode.js';
+export function codexConfigRoot() {
+    return path.join(os.homedir(), '.agents');
+}
+// Keep the orchestration prompt as an explicitly invokable skill: custom agents
+// are subagents in Codex, whereas D2H needs to drive the main conversation.
+function definitions(sourceRoot) {
+    const skills = path.join(sourceRoot, 'skills');
+    const entries = fs.readdirSync(skills).sort()
+        .filter(name => fs.existsSync(path.join(skills, name, 'SKILL.md')))
+        .map(name => ({ name, source: path.join(skills, name) }));
+    if (!entries.length)
+        throw new Error(`no skills found under ${skills}`);
+    if (entries.some(entry => entry.name === 'd2h'))
+        throw new Error('reserved Codex orchestration skill: d2h');
+    const prompt = fs.readFileSync(path.join(sourceRoot, 'agents', 'd2h.md'), 'utf8');
+    if (!/^---\r?\n[\s\S]*?\r?\n---\r?\n/.test(prompt))
+        throw new Error('d2h agent front matter missing');
+    return [...entries, { name: 'd2h', content: prompt }];
+}
+export function inspectCodexInstallation(configDir = codexConfigRoot()) {
+    const root = path.resolve(configDir);
+    const receipt = path.join(root, '.d2h-codex-installation.json');
+    if (!fs.existsSync(receipt))
+        return { status: 'missing', summary: `installation record missing: ${receipt}` };
+    const record = JSON.parse(fs.readFileSync(receipt, 'utf8'));
+    if (record.schemaVersion !== 1 || record.agent !== 'codex' || !Array.isArray(record.entries) || !record.entries.length) {
+        throw new Error(`invalid installation record: ${receipt}`);
+    }
+    const changed = record.entries.filter(entry => {
+        if (!/^[a-zA-Z0-9_-][a-zA-Z0-9_.-]*$/.test(entry.name))
+            throw new Error(`invalid installation entry: ${entry.name}`);
+        const target = path.join(root, 'skills', entry.name);
+        return !stat(target) || digest(target) !== entry.digest;
+    });
+    return { status: changed.length ? 'failed' : 'passed', agent: 'codex', packageVersion: record.packageVersion,
+        summary: changed.length ? `changed or missing: ${changed.map(entry => entry.name).join(', ')}` : `${record.entries.length} installed skills verified` };
+}
+export function installCodex({ sourceDir, configDir = codexConfigRoot(), link = false, force = false, dryRun = false, remote = false, log = console.log }) {
+    if (remote)
+        throw new Error('--remote metrics plugins are not supported by Codex');
+    if (!configDir || ['.', '..'].includes(configDir))
+        throw new Error(`unsafe Codex config directory: ${configDir}`);
+    const sourceRoot = fs.realpathSync(path.resolve(sourceDir));
+    const root = resolvedLocation(path.resolve(configDir));
+    if (root === path.parse(root).root || root === fs.realpathSync(os.homedir()) ||
+        contains(sourceRoot, root) || contains(root, sourceRoot))
+        throw new Error(`unsafe Codex config directory: ${configDir}`);
+    const skillsRoot = path.join(root, 'skills');
+    if (stat(skillsRoot)?.isSymbolicLink())
+        throw new Error(`refusing linked installation directory: ${skillsRoot}`);
+    const receipt = path.join(root, '.d2h-codex-installation.json');
+    if (stat(receipt)?.isSymbolicLink())
+        throw new Error(`refusing linked installation record: ${receipt}`);
+    const entries = definitions(sourceRoot).map(entry => {
+        const target = path.join(skillsRoot, entry.name);
+        const existing = stat(target);
+        const unchanged = entry.source ? (link && existing?.isSymbolicLink()
+            ? path.resolve(path.dirname(target), fs.readlinkSync(target)) === entry.source
+            : !link && sameTree(entry.source, target))
+            : existing?.isDirectory() && !existing.isSymbolicLink() &&
+                fs.readdirSync(target).length === 1 && fs.existsSync(path.join(target, 'SKILL.md')) &&
+                fs.readFileSync(path.join(target, 'SKILL.md'), 'utf8') === entry.content;
+        if (!unchanged && existing && !force)
+            throw new Error(`skill '${entry.name}' already exists at ${target}; rerun with --force`);
+        return { ...entry, target, unchanged };
+    });
+    if (dryRun) {
+        for (const entry of entries)
+            log(`would install Codex skill: ${entry.name} -> ${entry.target}`);
+        return { skills: entries.length, configRoot: root };
+    }
+    fs.mkdirSync(skillsRoot, { recursive: true });
+    if (!contains(root, fs.realpathSync(skillsRoot)))
+        throw new Error(`installation escaped config directory: ${skillsRoot}`);
+    for (const entry of entries) {
+        if (entry.unchanged) {
+            log(`unchanged Codex skill: ${entry.name}`);
+            continue;
+        }
+        const staging = fs.mkdtempSync(path.join(skillsRoot, '.d2h-install-'));
+        const staged = path.join(staging, 'new');
+        const backup = path.join(staging, 'backup');
+        try {
+            if (entry.source) {
+                if (link)
+                    fs.symlinkSync(entry.source, staged, process.platform === 'win32' ? 'junction' : 'dir');
+                else
+                    fs.cpSync(entry.source, staged, { recursive: true });
+            }
+            else {
+                fs.mkdirSync(staged);
+                fs.writeFileSync(path.join(staged, 'SKILL.md'), entry.content);
+            }
+            if (stat(entry.target))
+                fs.renameSync(entry.target, backup);
+            try {
+                fs.renameSync(staged, entry.target);
+            }
+            catch (error) {
+                if (stat(backup))
+                    fs.renameSync(backup, entry.target);
+                throw error;
+            }
+        }
+        finally {
+            if (stat(backup) && !stat(entry.target))
+                log(`installation backup retained: ${backup}`);
+            else
+                fs.rmSync(staging, { recursive: true, force: true });
+        }
+        log(`installed Codex skill: ${entry.target}`);
+    }
+    const packageFile = path.join(sourceRoot, 'package.json');
+    const packageVersion = fs.existsSync(packageFile) ? JSON.parse(fs.readFileSync(packageFile, 'utf8')).version : 'source';
+    const temporary = `${receipt}.${process.pid}.tmp`;
+    try {
+        fs.writeFileSync(temporary, JSON.stringify({ schemaVersion: 1, agent: 'codex', packageVersion,
+            entries: entries.map(entry => ({ name: entry.name, digest: digest(entry.target) })) }, null, 2) + '\n');
+        fs.renameSync(temporary, receipt);
+    }
+    finally {
+        if (fs.existsSync(temporary))
+            fs.rmSync(temporary);
+    }
+    log(`Codex installation complete: ${entries.length} skill(s). Start a new conversation and invoke $d2h.`);
+    return { skills: entries.length, configRoot: root };
+}

package/dist/src/install-opencode.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import os from 'node:os';
 import crypto from 'node:crypto';
 import { updateMetricsPlugin } from './metrics-plugin.js';
-function stat(file) {
+export function stat(file) {
     try {
         return fs.lstatSync(file);
     }
@@ -13,7 +13,7 @@ function stat(file) {
         throw error;
     }
 }
-function sameTree(source, destination) {
+export function sameTree(source, destination) {
     const left = stat(source);
     const right = stat(destination);
     if (!left || !right)
@@ -30,7 +30,7 @@ function sameTree(source, destination) {
     }
     return left.isFile() && right.isFile() && fs.readFileSync(source).equals(fs.readFileSync(destination));
 }
-function digest(file) {
+export function digest(file) {
     const info = fs.lstatSync(file);
     const hash = crypto.createHash('sha256');
     if (info.isSymbolicLink())
@@ -125,12 +125,12 @@ export function inspectInstallation(configDir) {
     return { status: changed.length ? 'failed' : 'passed', packageVersion: value.packageVersion, agent: value.agent,
         summary: changed.length ? `changed or missing: ${changed.join(', ')}` : `${value.entries.length} installed definitions verified` };
 }
-function contains(parent, child) {
+export function contains(parent, child) {
     const relative = path.relative(parent, child);
     return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
 }
 // Resolve existing ancestors too, including a config directory beneath a junction.
-function resolvedLocation(directory) {
+export function resolvedLocation(directory) {
     if (fs.existsSync(directory))
         return fs.realpathSync(directory);
     const parent = path.dirname(directory);