@harmonyos-arkts/d2h 0.1.27 → 0.1.29

package/skills/d2h-architecture-plan/references/json-contract.md

@@ -1,111 +1,49 @@
-# 看板规划与选择回传契约
+# 最终方案 JSON：只读展示契约
 
-生成规划和接收选择时读取本文件。完整可解析示例见 [architecture-plan.example.json](architecture-plan.example.json)；它只演示小型单 HAP 的形状，不能代替当前工程分析。
+用户完成方案确认、处理影响目录的修改后，才生成 `architecture-plan.json`。看板只展示结果和展开/折叠目录，不进行选型、确认或选择回传。完整示例见 [architecture-plan.example.json](architecture-plan.example.json)，示例是小型邮件应用的已选单 HAP 结构。
 
-辅助脚本要求 Python 3.10+，只使用标准库。命令中的路径替换为实际绝对路径，路径含空格时按当前 shell 加引号。
+## 固定结构
 
-## 三部分展示内容
+默认位置：`<Android工程同级>/<工程名>-migration/.migration/architecture-plan/architecture-plan.json`。使用 UTF-8、标准 JSON，不含注释、代码围栏或占位内容。顶层只有三个字段：
 
-产物目录沿用 `<Android工程同级>/<工程名>-migration/.migration/architecture-plan/`。`architecture-plan.json` 是决策事实源，`architecture-plan.md` 是同步阅读视图；`architecture-selection.json` 保存看板或 question 工具得到的实际确认结果，作为目录实施的输入。JSON 使用 UTF-8，不能包含注释、代码围栏或省略号。
-
-JSON 的展示内容只围绕项目简介、原工程分析与风险、三套方案目录组织：
-
-| 对象 | 必填字段 | 可选字段 |
+| 字段 | 类型 | 含义 |
 |---|---|---|
-| `project` | `name`（项目名）、`summary`（用途、主要能力；部分迁移时说明本次范围） | 无 |
-| `androidAnalysis` | `summary`（架构概述）、`techStack`（四类技术概况对象）、`risks`（关键迁移风险数组） | 无 |
-| `androidAnalysis.techStack` | `language`（开发语言）、`ui`（界面实现）、`storage`（数据存储）、`network`（网络通信），均为简短字符串 | 无 |
-| `androidAnalysis.risks[]` | `title`（风险名称）、`impact`（对迁移的影响），均为简短字符串 | 无 |
-| `proposals[]` | `id`、`name`、`summary`（目录组织思路、主要取舍或限制）、`directoryTree`（嵌套目录树） | 无 |
-| 目录节点 | `name`、`path`、`description`（路径简介）、`children` | `kind`（模块类型；普通目录省略） |
-
-`proposals` 恰好三套，ID 分别为 `android-mirror`、`harmony-practice`、`hybrid`，每套均有自己的完整关键目录树。同构方案允许树相同，不制造无依据差异。
-
-`androidAnalysis` 固定使用上述字段，不增加可选分析集合。写作要求：
-
-- `summary` 用一到两句日常语言解释“代码如何组织、哪里明显影响迁移”，不重复项目用途，不罗列模块名、类名或阅读过程。
-- `techStack` 每类只写一条简短说明，只保留最能说明实现方式的信息。例如语言写“Kotlin、Java”，界面写“新页面使用 Compose，旧页面仍用 Android View”。不堆叠构建工具、架构缩写、库清单或把同一技术分散列多次；确知无相关能力时说明“无本地存储”等事实，未核实则写“本次未核验”，不猜技术名称。
-- `risks` 最多五项，按对迁移的影响合并同类问题。`title` 直接命名问题，`impact` 用一句话说明可能影响的功能或需要适配的部分，不展开源码论证、接口设计或长篇处置清单。没有已知风险时使用 `[]`，不能据此宣称已完成验证。
-- 移除源码目录清单 `structure` 和未决清单 `openQuestions`。影响迁移的技术未知并入相应风险的 `impact`；源码路径、证据、详细依赖和其他核验记录按需留在 Markdown，不塞入展示摘要。
-
-风险及其中尚待核验的事项均为只读展示内容。看板不为它们生成必答表单、确认按钮或风险已读勾选，不将非空数组视为选型/创建的阻塞条件。技术问题由 Agent 后续按需核查，用户不需要逐项处理。
-
-用户若希望改变分析或方案，通过对话提出意见，Agent 修改相应 JSON 字段并同步 Markdown。仅调整分析或风险说明时不清空有效选择；影响目录或实际授权范围时更新展示并按选型流程处理。实际创建缺少目标位置等必要输入时，独立询问该缺失信息，不把整份风险或未决清单交给用户作答。
+| `projectName` | 非空字符串 | 当前规划的项目名称 |
+| `directoryTree` | 目录节点对象 | 用户最终确认的一整套目录，根相对于实际鸿蒙目标根 |
+| `decisions` | 非空对象数组 | 最终方案的主要架构决定及依赖说明，包含理由、职责边界与必要装配 |
 
-JSON 不再包含 `regions`、映射表、依赖图、共享所有者及逐方案收益/成本/风险数组。影响选型的方案取舍写入方案 `summary`，具体职责写入目录 `description`；必要的源到目标归属、依赖方向和共享边界由 Markdown 简记，不生成三份实现交接模型。
+不增加协议版本、修订号、规划/请求 ID。选定方案身份、实际用户回答、工程绝对路径、详细证据保存在 `architecture-plan.md`。JSON 表示规划结构，不表示目录已经创建或应用已经实现。
 
-Android/目标绝对路径、目标工程性质和结合范围属于执行上下文，沿用迁移配置、Preflight 与明确用户指令；按需记入现有 Markdown，不在看板 JSON 重复管理。
+### 目录节点
 
-## 推荐、选择与协议字段
-
-以下顶层字段全部保留，用于选型展示和回传校验，不要求看板把协议元数据作为分析内容展示：
-
-| 字段 | 类型与含义 |
-|---|---|
-| `planId` | 同一工程本次规划的稳定唯一标识，首次生成 UUID，修订沿用；不同工程不共用 |
-| `recommendedProposalId` | 模型推荐的一个方案 ID，不能作为用户授权 |
-| `recommendationReason` | 当前证据下的推荐理由及会改变推荐的条件 |
-| `selectedProposalId` | 用户最终选中的整套目录方案 ID；未选择为 `null`，不能预填推荐值 |
+| 字段 | 类型 | 规则 |
+|---|---|---|
+| `name` | 非空字符串 | 当前目录名；除根外等于 `path` 的最后一段 |
+| `path` | 非空字符串 | 完整的目标根相对路径，统一 `/`；根为 `.` |
+| `description` | 非空字符串 | 该路径的职责与边界，必要时说明保留或平台适配 |
+| `children` | 节点数组 | 直接子目录，叶子固定为 `[]` |
+| `kind` | 可选字符串 | 实际模块根填写 `HAP` / `HAR` / `HSP`；普通目录省略或为 `directory` |
 
-## 嵌套目录节点
+根节点 `name` 可用项目名，`kind` 为普通目录。每层必须真实嵌套，例如 `entry → src → main → ets`，不能把 `src/main/ets` 合并成一个子节点。模块源码树内的 feature、页面、共享目录均为普通目录，不嵌入另一个模块根；源码树外的模块分组路径不等于构建模块嵌套，实际注册与可用性仍需核对构建配置。
 
-`directoryTree` 是一个根节点，节点字段固定如下：
+树包含最终选定方案的实际模块和关键目录，至少有一个 HAP，并展开每个 HAP 的 `src/main` 生产目录及关键子目录，不能只标记一个空 HAP。实际源码根按目标工程类型确定，ArkTS 工程通常为 `src/main/ets`；结构校验不据此限制源码语言。按实际需要展示 `AppScope`、模块资源及其他职责目录，不要求列文件。路径必须唯一，不能有大小写冲突、绝对路径、上级跳转、反斜杠、通配符、占位符或 Windows 非法名称。路径顺序按阅读顺序组织。
 
-```json
-{
-  "name": "HarmonyOS",
-  "path": ".",
-  "description": "目标工程根目录；以下子节点均相对此根",
-  "children": [
-    {
-      "name": "entry",
-      "path": "entry",
-      "description": "应用 HAP，负责启动、装配及本例业务",
-      "kind": "HAP",
-      "children": []
-    }
-  ]
-}
-```
+### 主要决定与依赖 `decisions[]`
 
-上例仅解释节点形状；实际规划须展开源码根、主要 feature/包族及资源目录，不能只交付空 `entry`。规则：
+每项固定为 `title`、`description` 两个非空字符串。`title` 概括决定；`description` 简述保留/拆分/合并、模块类型、职责与共享所有权、依赖方向、装配或平台适配的最终安排及原因。只保留影响理解结构的主要决定，不罗列一般原则、全部风险或实现任务。
 
-- 根 `path` 固定为 `.`，其余 `name` 是一个目录段，与 `path` 最后一级一致。
-- `path` 是目标根相对路径，统一 `/`，不以 `/` 结尾；每个子节点是父目录的直接下一层。例如 `entry` → `entry/src` → `entry/src/main`，不能跳级或把 `src/main` 当节点名。
-- 节点必须有非空简介和 `children` 数组，叶子为 `[]`。看板以 `proposal.id + ':' + node.path` 为节点键，以 `children.length` 判断展开/折叠；折叠状态由界面维护，不写回规划。
-- `kind` 省略时表示普通 `directory`；实际拟议构建模块根须标 `HAP`、`HAR` 或 `HSP`，不标其 `src/main` 或普通 feature。根节点只能是普通目录，模块不能嵌套；目录存在不等于已注册模块。
-- 每套应用方案至少包含一个 HAP，并展开该 HAP 的 `src/main/ets` 源码根；空树或只标记一个空 HAP 不算可落地目录规划。
-- 不出现绝对子路径、反斜杠、空路径段、`.`/`..` 段（根除外）、Windows 非法目录名、大小写重名、通配符或目录模式占位符。相同路径可出现在不同方案内。
-- 三套方案无需列逐类目录和全量文件，但拟创建的关键目录必须逐节点可见。创建前仍需核对实际目标、链接和用户文件；静态路径校验不替代实际文件系统检查。
+已确认的范围决定可说明其对目录的影响；技术未知写清保留的边界与后续核验前置，不能借此声称已验证、擅自删功能或要求用户逐项答题。
 
-## 统一确认记录与下一步读取
+依赖说明写在相关决定的 `description` 中，也可单列“依赖方向与装配”这一决定：用实际目录名/路径说明谁使用谁的公开能力、谁创建和提供共享实例，区分源中保留与目标新增/替代的依赖。不再生成独立 `dependencies` 数组，也不向决定对象增加关系字段。修订已有四字段 JSON 时，先合并有效依赖说明，再移除旧数组，不丢弃当前仍适用的决定。
 
-选型、确认落盘和目录实施的统一流程见 [selection-flow.md](selection-flow.md)，两个入口都必须遵守。主规划只用 `selectedProposalId` 展示当前选择，不嵌套完整回传对象；确认细节单独保存在同目录的 `architecture-selection.json`。
+提及的目标路径须与树一致，交付时人工复核；不机械展开全部 import、不以父子目录关系或任务先后充数、不用通配符和“products(entry)”别名。运行时回调与代码依赖方向分开解释，未核验的协作前置如实标明。
 
-在已说明“确定后创建或复用基础工程并补齐目录”的交互中，看板“确定”与 OpenCode question 回答都生成同一种记录：
+## 校验与交接
 
-```json
-{
-  "requestId": "97c333d3-9e02-43d2-8c27-e8202789e02c",
-  "planId": "c9c093cf-94ec-4b49-b919-a89c82eef0d1",
-  "selectedProposalId": "hybrid",
-  "action": "select-and-create",
-  "source": "question",
-  "notes": ""
-}
+```text
+python <本Skill目录>/scripts/architecture_plan.py validate <产物目录>/architecture-plan.json
 ```
 
-| 字段 | 规则 |
-|---|---|
-| `requestId` | 每次用户确认生成唯一值，重试沿用原值和内容 |
-| `planId` | 用户正在查看的规划身份，必须匹配主规划 |
-| `selectedProposalId` | 用户实际选择的整套方案 ID，必须在三套方案中 |
-| `action` | `select-and-create` 表示确认并创建；用户只要求记录选择时为 `select` |
-| `source` | 看板为 `dashboard`；OpenCode question 工具为 `question`；已有明确对话指令为 `conversation` |
-| `notes` | 真实修改意见，可为空；要求改变目录时先处理修改，不能按旧目录执行 |
-
-以上字段全部必填；记录不接受自带目录、目标根或推荐值。source 是来源记录，不是身份认证，Agent 必须基于实际用户操作/回答，不能自行伪造选择。仅分析文本调整保留有效确认，目录或实际授权范围变化则按统一流程清理原确认。
-
-`apply-selection` 从独立请求文件读取用户提交，校验后才保存确认文件、更新主规划的选择字段；看板和文件工具不得用新请求直接覆盖已确认文件。目录实施入口执行 `read-selection`，重新核对两文件的 planId/方案 ID、动作及原始意见，再读取规划内该方案的目录树；不能仅凭 question 返回值或看板选中效果开始创建。写入失败或读取不一致时不进入实施。记录先写、规划后写，不是跨文件原子事务；显式恢复和重复提交规则见统一流程。
+Python 3.10+，标准库。校验器只读文件，检查字段、类型、目录层级/路径/模块；返回退出码 0 和 `status: valid`，失败返回非零和错误说明。它不解析决定中的自然语言依赖，不判断用户是否已确认、实际目标目录是否存在、决定是否正确或代码是否实现。
 
-实际目标根仍由迁移配置、Preflight 和明确上下文核对，不由回传提供。看板服务和会话通知由外部适配方提供，本 Skill 不提供 HTTP 端点或监听服务。风险仅作展示，不增加确认表单。
+按主流程在用户回答后生成 JSON 和 Markdown；JSON 先在临时文件中生成、校验，再替换正式文件，失败不把临时数据交给看板。调用方交接 JSON 路径即可，看板的加载/刷新由外部适配实现。本 Skill 不提供选择端点、回传协议、监听服务或自动唤醒。

package/skills/d2h-architecture-plan/references/layout-reference.md

@@ -1,6 +1,6 @@
 # 架构选择与目录参考
 
-先决定职责、状态所有权、协作和演进边界，再决定目录。以下给出判断方法及可选目录示例；名称、分层与模块数量由当前工程职责和维护需求决定。
+先决定职责、状态所有权、协作和演进边界，再决定目录。以下给出选型原则与目录职责参考；名称、分层与模块数量由当前工程职责和维护需求决定。
 
 这些决定使用结构地图与必要的边界证据即可，不要求先验证全部业务行为。共享结论在三套方案间复用；本参考用于选择结构，阅读深度与停止条件见 [source-review.md](source-review.md)。
 
@@ -17,15 +17,38 @@
 
 新工程也评价原作者的维护便利性：哪些业务名和包族能沿用、变化后从哪里找页面/状态/数据、常见修改需跨多少模块、故障怎样回溯源码。可读性来自职责与一致命名，不来自把所有Java包原样堆进ArkTS，也不来自一律改成陌生名字。
 
+### HAP、HAR、HSP 怎么选
+
+先确定业务职责，再决定是否需要独立构建模块。这里的 `feature` 指业务目录，不等于 `type: feature` 的 HAP；`features`、`commons` 等目录名也不决定包类型。
+
+| 组织方式 | 采用条件 | 对目录设计的影响 |
+|---|---|---|
+| HAP 内的普通目录 | 页面/业务只服务当前产品，单独拆库没有明显收益 | 在产品 HAP 的源码根内按业务分组，不额外创建模块 |
+| HAP | 需要应用安装/部署边界：entry 承载产品主入口，feature HAP 承载有独立部署或按需安装要求的功能 | 明确入口、设备和安装要求；不能让产品 HAP 直接 import 另一个 HAP 的接口/组件，跨 HAP 通过 Ability 等机制协作 |
+| HAR | 需要封装供 HAP/HSP 引用的代码、页面、组件或资源，或者发布可复用库 | 编译时合入引用模块，不独立安装；多个 HAP/HSP 引用同一 HAR 可能重复打包，单个产品引用业务 HAR 也可以成立 |
+| HSP | 同一应用内多个 HAP/HSP 需要在运行时共享代码/资源，或有明确的按需加载/元服务分包需求，收益足以抵偿部署与配置成本 | 单独产出共享包，核对真实消费者、加载需求、包大小和部署约束；不能仅因多个页面共用状态就建 HSP |
+
+以下边界会影响选型，按当前目标 SDK 核验，不照搬旧对照表：
+
+- HAR 可以包含页面，由宿主通过 Navigation 等方式打开，但不能在 HAR 的配置中声明 `pages`；HAR 自身资源不引用 `AppScope`。因此“包含业务页面”不是改为 HAP 的理由。
+- Ability 声明有版本条件：当前官方资料中，HAR/HSP 从 API 14 支持声明 UIAbility、从 API 18 支持声明部分 ExtensionAbility，仍有入口能力等限制。不能把“库模块一律不能声明 Ability”写成永久规则。
+- HSP 的运行时共享以宿主应用为边界；集成态 HSP 可以供不同应用工程复用，但会按各宿主重新集成和签名，不是不同应用共用一个运行实例。多个品牌/产品若产出不同应用，不能因为同处一个工程就当成应用内多 HAP 共享状态。
+- HAR/HSP 之间不支持循环依赖，也不自动传递依赖。引用下层库的能力时核对实际依赖和公开导出，不靠目录层级或 Gradle 的传递规则推断目标可编译。
+- HAP/HSP 的安装需满足签名、应用身份与版本等一致性规则；不要把这些规则误写成 HAR 库版本必须等于宿主版本。普通应用内 HSP 可与依赖它的 HAP 一起部署，不把“手工先装 HSP 再装 HAP”定为所有项目的固定流程。
+
+在主要决定中简记实际采用的模块类型及理由，并说明引用或跨 HAP 协作方式。代码/资源共享不保证业务状态只有一个实例，仍需说明由谁创建和提供；跨进程状态另按通信与存储方式设计。
+
 ## 2. 三套方案如何区别
 
 | 方案 | 目录/边界约束 | 必须解释 |
 |---|---|---|
 | android-mirror | 运行时源模块一对一对照，保留源模块名、相对布局、关键包族与内部模块声明依赖；构建辅助项目不变成目标业务库 | 外部SDK/API保留能力与消费者对照，不照搬AndroidX等包坐标；Ability/资源/语言及运行时必要适配；源技术债、环或不可行的边不能伪装成鸿蒙可实施结构 |
 | harmony-practice | 依据目标职责重组，按消费者、数据所有权与平台边界选择目录和模块粒度；允许单HAP或适当模块化 | 具体收益、消费者和数据流；新增命名、拆合及平台适配成本，不以“最佳实践”替代论证 |
-| hybrid | 基础依赖层优先保留原模块名、包族及合理依赖；业务层按页面或紧密页面组组织 feature，应用壳负责装配 | 基础保留与适配例外、页面边界及共享业务所有者；详细展开时按 [hybrid-design.md](hybrid-design.md) 设计，不能仅改变第二套顶层名字 |
+| hybrid | 基础依赖层优先保留原模块名、包族及合理依赖；业务层按页面或紧密页面组组织 feature，应用壳负责装配 | 基础保留与适配例外、页面边界及共享业务所有者；按 [hybrid-design.md](hybrid-design.md) 设计，不能仅改变第二套顶层名字 |
+
+依据实际收益和维护代价判断推荐哪一套。
 
-简单应用三套可以有相同模块数甚至相同树；说明相同决定与缺少额外拆分收益的原因。推荐可为任一套，依据实际收益和维护代价判断。
+对于简单应用，三套目录可以有相同模块数甚至相同树；说明相同决定与缺少额外拆分收益的原因。
 
 融合方案的两个层次是迁移职责划分，不强制增加两个顶层目录或独立构建模块。下节是通用目录字典；融合方案的原包族保留、页面粒度与共享边界以 [hybrid-design.md](hybrid-design.md) 为准。
 
@@ -35,7 +58,7 @@
 
 多技术栈对照应同时保留Android宿主与实际业务源码的定位线索；不把Dart/JS业务当作新的Gradle模块，也不声称照搬源目录就保留了运行时。用户明确目标设备或范围优先；未知设备支持列为前提，不通过删功能制造可行性。
 
-## 3. 可选目录组织示例
+## 3. 通用目录职责
 
 项目可按应用装配、业务职责与共享能力组织目录，也可保留已有且合理的结构。以下名称用于示意，按实际职责选取：
 
@@ -45,30 +68,11 @@
 | 业务职责 | features / 业务域 | 该域实际存在的页面/状态、规则、数据访问及私有组件 | 保持域内所有权，独立模块按实际收益拆分 |
 | 共享能力 | commons / core | 有真实跨域消费者的展示、数据/契约或平台设施 | 明确所有权和依赖方向，按职责决定合并或拆分 |
 
-一种模块化组织示意，按实际需要选取其中的职责和目录；单模块或其他合理结构无需改成此树：
-
-```text
-<HarmonyOS>/
-├── AppScope/                         # 工程基础配置
-├── products/<产品>/src/main/
-│   ├── ets/{entryability,navigation,composition}/
-│   └── resources/
-├── features/<业务>/src/main/
-│   ├── ets/pages/
-│   ├── ets/state/                    # 或viewmodel，依所选状态模式
-│   ├── ets/data/                     # 专属Repository/数据源
-│   ├── ets/components/               # 业务私有UI，有需要才设
-│   ├── ets/domain/                   # 仅规则复杂/复用时
-│   └── resources/
-└── commons/<实际共享能力>/src/main/
-    ├── ets/                          # 如ui、会话数据、网络或协议
-    ├── cpp/                          # 有实际Native构建需求时
-    └── resources/
-```
+融合方案的具体目录示例见 [hybrid-design.md](hybrid-design.md)，展示基础包族保留、页面拆分与共享业务归属。
 
 单模块同样可在 `entry/src/main/ets/<业务>/` 内组织页面、状态和数据；选择products目录也不强制独立features库。业务代码通过清晰接口与平台能力协作，不将Android Activity/Service逐个等同为UIAbility/ExtensionAbility。
 
-组件按职责与消费者确定归属：域内私有组件留本域，跨域通用展示可放共享UI或独立组件目录；顶层 `components` 与其他命名均按当前结构和维护收益选择。完整业务能力的复用仍需说明其状态、数据与协作边界。数据/协议模块不反向依赖共享UI，应用装配保持独立职责。
+组件按职责与消费者确定归属：域内私有组件留本域，跨域通用展示可放共享UI或独立组件目录；完整业务能力的复用仍需说明其状态、数据与协作边界。数据/协议模块不反向依赖共享UI，应用装配保持独立职责。
 
 对工程实际存在的资源、配置、持久化结构、本地能力或跨运行时依赖，分别说明目标归属；配置差异仅在影响本次迁移时展开。共享能力是否合库，按消费者、上游升级、构建和生命周期决定。
 
@@ -79,5 +83,4 @@
 - [Android架构指南](https://developer.android.com/topic/architecture)：关注职责分离、数据驱动和状态来源，UI/数据及可选领域层是职责划分。
 - [Android架构建议](https://developer.android.com/topic/architecture/recommendations)：数据通过Repository访问，Domain/UseCase按复杂度及复用需求引入。
 - [Android模块化模式](https://developer.android.com/topic/modularization/patterns)：按业务和共享数据职责组织，模块数量与粒度适应项目。
-- [HarmonyOS官方应用规划](https://developer.huawei.com/consumer/cn/app/planning/)：结合产品、基础特性与公共能力组织应用。
-- [HarmonyOS开发路径](https://developer.huawei.com/consumer/en/app/knowledge-map)：模块化及HAR/HSP等目标平台机制；选用时核对实际设备与SDK约束。
+- 包类型及限制：[官方 HAP 文档源码](https://developer.huawei.com/consumer/cn/doc/doccenter-getting-started/hap-package)、[HAR](https://developer.huawei.com/consumer/cn/doc/doccenter-getting-started/har-package)、[HSP](https://developer.huawei.com/consumer/cn/doc/doccenter-getting-started/in-app-hsp)。

package/skills/d2h-architecture-plan/references/plan-contract.md

@@ -1,54 +1,47 @@
-# 规划交付：目录、归属与决策
+# 规划产物：三套对照与最终方案
 
-默认交付 `architecture-plan.json` 和 `architecture-plan.md`。前者是看板决策事实源，字段与回传遵循 [json-contract.md](json-contract.md)；后者是从同一规划同步的阅读视图，供现有调用方交接，保留已有用户批注。目标是让开发者能在看板判断采用哪套结构，并据此创建目录。
+用户按 [SKILL.md](../SKILL.md) 完成选型后，`architecture-plan.md` 留存分析、三套对照及真实回答，`architecture-plan.json` 展示最终方案。本文件规定交付内容；JSON 字段见 [json-contract.md](json-contract.md)，交互顺序只按主流程执行。
 
-## 1. 共用一次项目理解
+## 1. 项目理解与共用范围
 
-简述应用用途、原结构、目标范围及实际读取范围。已定位鸿蒙目标时，简记实际目标根、模板壳/已有业务/性质未明的判断及证据；模板壳仅作为落地基础。已有明确的结合/不结合鸿蒙业务实现选择一并简记，后续同范围修订沿用；未答复只记默认 Android，不记为拒绝。基础工程可复用与业务能力已实现分开表述，未读取的目标业务不作为已核验的能力复用依据。
+在 Markdown 简述项目用途、原结构、迁移范围和实际读取范围。用必要的源路径、代表符号或行号支撑影响拆合的结论；声明依赖与实际调用、已核验事实与推断分开，不伪称运行验证。
 
-JSON 的 `project` 只保存项目名和简介；部分迁移时在简介中注明本次范围。`androidAnalysis` 固定为架构概述 `summary`、四类技术概况 `techStack`、最多五项的迁移风险 `risks`，具体类型与写法见 JSON 契约。概述只解释组织方式和主要耦合，技术按语言/界面/存储/网络各一句说明，风险只写名称与迁移影响。资源、配置、后台/外部入口和 Native/混合栈边界只保留影响迁移的结论，不在 JSON 罗列源码目录、类名、工具库清单或独立未决项。工程路径、目标性质、是否结合业务实现及源码/依赖核验细节按需记入本 Markdown，配置已有值直接引用，不重复维护。
+已定位鸿蒙目标时，记录实际目标根、模板壳/已有业务/性质未明的判断及依据，以及用户是否选择结合业务实现。模板壳仅作落地基础；未读取的目标业务不作已实现能力依据。路径与配置已有值直接引用，不重复维护。
 
-## 2. 三套嵌套目录与归属
+原工程分析只保留解释目录决定所需的信息：主要职责、装配、共享数据/状态所有权、非 UI 入口和平台边界。风险合并同类，只写对迁移的影响与核验前置；不堆叠技术名词或工具库清单。这些分析留在 Markdown，不导入最终展示 JSON。
 
-共用上述源范围，在 `proposals` 提供 `android-mirror`、`harmony-practice`、`hybrid` 三套结构选项。每套 JSON 只有 `id/name/summary/directoryTree`，便于看板独立展开与比较；用户已有选择时沿用，不重新选型。信息组织如下：
+## 2. 留存三套目录及比较
 
-- **关键目录树**：展开全部拟议实际模块及主要职责/feature 目录。基础保留方案体现原模块/关键包族的相对层级；业务方案体现页面/页面组及共享区域。每个节点包含 `name/path/description/children`，实际模块根用 `kind` 标注 HAP/HAR/HSP，普通目录省略；叶子也给 `children: []`。关键目录逐项嵌套列出，不能使用 `{pages,state}`、`<业务>`、省略号或“同推荐方案”等占位；无需列逐类目录或全量文件。
-- **方案说明**：在 `summary` 简述目录组织思路及影响选型的取舍/限制，具体职责放在对应目录的 `description`。不为每套生成收益/成本/风险数组或实现交接模型。
-- **必要交接**：源到目标归属、主要依赖方向与共享所有权只在 Markdown 按需简记，优先围绕推荐/已选方案，不维护三套完整关系图；保留的源边与目标新增/替代边区分，目录不等于独立构建模块。
+共用同一范围，比较 `android-mirror`、`harmony-practice`、`hybrid`。最终 Markdown 详列三套目录结构与职责、主要差异和取舍，并标明推荐和实际选择；JSON 只保留已选方案的一棵树。同构方案允许结构相同，不制造无依据差异。
 
-用目录简介及必要的 Markdown 归属说明核对已知职责有去向。混合区域说明保留与移出部分，共享能力有唯一所有者，不让同一粗目录被整体认领多次。不要求机器映射表、职责 ID 或相同粒度的多份交接表。
+推荐须解释维护定位、边界、平台适配和迁移成本，以及会改变推荐的条件。不能仅凭模块数量、命名或“最佳实践”标签判断。融合设计按 [hybrid-design.md](hybrid-design.md)：基础依赖保留可追溯包族，业务按页面/页面组及共享所有者组织。
 
-Markdown 可详列推荐/已选方案，另两套保留紧凑对照并链接 JSON；该展示压缩不改变 JSON 中三套树的完整性。同构方案允许树相同，不制造无依据差异。选择另一套后直接使用其树，除非边界出现新问题，不重新扫描源码。
+用关键目录与必要归属说明核对已知职责有去向；源区域混合职责时说明保留和移出部分，共享数据/状态只认一个所有者。简记必要的依赖方向、装配、导航和共同修改归属，不生成全量调用图、机器映射表或逐页实施计划。页面候选不等于最终 Spec，也不代表当前可以并发开发。
 
-## 3. 融合方案的最小交接
+## 3. 确认后的最终方案
 
-融合方案采用 [hybrid-design.md](hybrid-design.md) 的两层原则。目录简介反映职责边界，以下必要交接在 Markdown 中按需简记，足以支持后续细化，不新增 JSON 关系集合或逐页实施计划：
+在 Markdown 记录实际选定方案、回答来源（question 或对话）与回答要点、用户修订与范围决定、实际目标根以及是否授权创建/复用。合并已回答的问题，不能让前文旧待决、旧树与后文确认矛盾。技术未知仍可保留为实施前置，不伪造用户结论。
 
-| 内容 | 本阶段粒度 |
-|---|---|
-| 基础保留与适配 | 原模块/包族→目标路径、保留部分、必须调整的边界与理由 |
-| 页面/页面组候选 | 源入口或页面族→目标 feature 与所属模块，已知共享依赖；不机械把 Activity/Fragment 个数当 feature 数量 |
-| 共享业务与协作 | 唯一目标所有者、主要消费者、装配/导航/数据协作方式；未明确的契约列为细化前置 |
-| 独立转换条件 | 已知共同修改区域及集成归属、最小能力前置，哪些候选可在条件满足后独立转换，哪些确需合组 |
+Markdown 中明确标记最终方案及其目录归属；选中非推荐方案时也以实际选择生成 JSON，不让推荐树充当最终树。只规划且目标未定位时注明未知，不因此阻止目录方案交付或额外询问目标位置。
 
-共享状态不复制；共享一个领域会话不自动证明页面应合组。不要求现在确定全部页面 ID、独占测试/资源文件、完整输入输出/错误契约或验收序列；这些细节在选定方案后的页面规划/实现中补齐。候选不是最终 Spec 身份，目录分开也不能证明当前已可并发执行。
+生成 JSON 前，形成唯一、可落地的最终结构：
 
-## 4. 推荐、复核与选型
+- 将职责示意路径统一为确认后的实际路径，例如复用 `entry` 就以它作为产品模块路径；不把二选一、别名或未采用的替代路径一起输出。不再采用的方案在 Markdown 中标明对照或历史。
+- 模块类型、模块数量与实际树一致，按 [layout-reference.md](layout-reference.md) 说明 HAP/HAR/HSP 的实际选型理由。普通职责目录不自动成为独立模块；必要的模板适配应在主要决定中说明，不能为了套用模板改变业务范围。
+- 已确认的功能保留、拆分、排除及共享归属反映在树和说明中；不因静态无引用、平台未知或示例中的取舍自动裁剪当前项目。
+- 完整列出选定方案的实际模块、源码根和关键职责/feature 目录。每层独立嵌套，每条路径有简介；不用 `{pages,state}`、省略号、“同上”或不确定路径替代。无需生成逐类目录或文件清单。
 
-比较三套的维护定位、边界清晰度、平台适配与迁移成本，给基于当前证据的推荐及会改变推荐的条件。模块数量、目录命名和“最佳实践”标签不能替代论证；同构方案不为制造差异而拆库。
+JSON 的 `decisions` 摘录最终方案的主要决定，例如保留包族、拆分巨石 UI、模块类型、共享状态唯一所有者、产品壳与装配、公开契约及平台适配边界。少量关键代码依赖也在决定的说明中表达，指出谁使用谁的能力、如何装配；提及的目标目录须与树一致，不把目录包含关系或实施先后当代码依赖。具体字段只在 JSON 契约定义。
 
-交付前对照共用范围与目录职责检查：
+## 4. 复核与交接
 
-- 已知运行时模块、主要职责与资源/非 UI 入口都有去向；未排除用户业务，三套范围一致。
-- 树、必要归属说明、模块类型及主要依赖互相吻合，原包族保留承诺可定位，共享所有权唯一，无未解释的目标环或反向页面依赖。
-- 方案不夹带未验证的平台替代/进程合并/功能裁剪结论；目录待决与实现前置分开，未读取鸿蒙源码时没有伪称目标已实现。
-- 空模板的目录、模块数量和默认参数未被当成架构约束；已建基础工程的复用安排与所选目录一致，必须调整的配置或路径假设有交接说明。
-- 融合分层与页面候选有证据，已知共同写入点有归属；没有将未细化的契约或目录壳子记为已可开工。
+交付前复核：
 
-有矛盾时局部修订并补查相关证据，不重跑全仓分析。架构选择可以在保留实现风险的情况下完成；未知仍影响具体目录时明确条件分支或草案范围。
+- 本次已知运行时职责、资源/配置和外部/后台入口都有去向；三套比较范围一致，没有未经授权删减业务。
+- 最终树、Markdown 归属、模块类型/数量、主要决定和依赖一致；源包族保留承诺可定位，共享所有权唯一，实际 HAR/HSP 模块依赖无环，基础能力不反向依赖页面。
+- 未把未验证的平台替代、进程合并、功能裁剪或目录壳子写成已经实现；不将旧 Preflight 结果当作新布局已构建通过。
+- 当前用户回答已处理，选型和创建授权各有实际依据；不以 JSON 校验替代确认，不把已回答项继续当待决询问。
 
-风险和未决项以分析结论展示，不要求用户回答或确认，不构成默认暂停条件。Agent 可继续相关技术核查；用户主动通过对话提出调整时，再更新 JSON 和同步阅读视图。仅说明文字的修改保留有效选择，涉及目录或授权范围的变化按选型流程处理。
+校验最终 JSON 后，向调用方交接 JSON/Markdown 路径、实际目标根和必要前置。有创建授权时按 [directory-creation.md](directory-creation.md) 落地并附 `shell-receipt.json`；否则交付已选方案即可。看板读取最终 JSON 展示，不增加选择或确认步骤。
 
-按 [json-contract.md](json-contract.md) 校验 JSON 后同步 Markdown：包含规划身份、JSON 链接、项目及原结构摘要、推荐与实际选择、关键归属/依赖/共享边界及风险。不维护第二份独立选型状态；已有 Markdown 方案首次转为 JSON 时沿用真实事实与用户确认，不凭旧标题推断选择或创建授权。不生成 `source-inventory.json`、`source-baseline.json`、`plan-input.json` 等扫描/中转文件。
-
-只请求规划时交付即可，不强求立即选型。用户选定后按 [selection-flow.md](selection-flow.md) 将看板或 question 的确认统一保存到 `architecture-selection.json`，规划只更新 `selectedProposalId`。下一步重新读取两份 JSON，`select-and-create` 确认一致后按 [directory-creation.md](directory-creation.md) 继续并记录实际结果。不同时落实三套，不把目录落地写成应用迁移完成。
+已有规划转为 JSON 时先阅读真实回答与当前结论，不凭“推荐”标题推断用户选择；格式转换规则见 JSON 契约。

package/skills/d2h-architecture-plan/references/source-review.md

@@ -49,7 +49,7 @@
 | 配置/资源差异改变产品与模块组织 | 生效选择规则、资源族与消费者 | 品牌×渠道的逐项内容比较、精确资源转换 |
 | 用户已选择结合现有鸿蒙工程 | 所涉模块注册、公开入口和对应职责，确定复用影响 | 无关目标实现的全面审查 |
 
-平台可得性确实影响模块/运行时选择时才查对应官方资料，记录适用前提；不影响目录的 API 签名、Kit、资源格式与实施细节留到转换阶段。无法取得材料时说明未知与影响，不用连续检索猜结论；仅仓内缺少鸿蒙依赖不能证明没有鸿蒙版。
+当某项能力、第三方库或运行环境在鸿蒙上的支持情况会影响目录或模块设计时，查阅对应官方资料；其他实现细节留到迁移开发阶段核验。
 
 不要凭静态搜索无引用就删除疑似旧页面、flavor 或后台能力；默认保留到相应区域并标记待核实，排除用户业务需有依据。Native/SDK 风险也不能自动变成裁剪或降级决定。默认不运行构建、设备采集或下载依赖。