@harmonyos-arkts/d2h 0.1.20 → 0.1.22

package/skills/d2h-app-solution/scripts/validate_inventory.py

@@ -0,0 +1,337 @@
+#!/usr/bin/env python3
+"""Validate hierarchy, repository coverage, confidence, and source citations."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+from pathlib import Path
+
+
+STATUSES = {"implemented", "partial", "mock", "unreachable", "absent", "uncertain", "not-applicable"}
+CONFIDENCES = {"high", "medium", "low"}
+KINDS = {"screen", "surface", "tab", "menu", "dialog", "action", "setting", "flow-step", "external"}
+EVIDENCE_TYPES = {"entry", "route_declaration", "navigation_call", "ui_label", "ui_interaction", "menu_item", "visibility_condition", "effect", "test", "doc"}
+EVIDENCE_TYPES |= {"tech_stack", "dependency_declaration", "native_library", "permission_declaration", "permission_request"}
+VISIBLE_TYPES = {"ui_label", "menu_item"}
+ACTION_TYPES = {"navigation_call", "ui_interaction", "route_declaration", "effect"}
+RELEASE_STAGES = {"mvp", "core", "full", "uncertain"}
+TECHNOLOGIES = {"java", "kotlin", "cpp", "react-native", "flutter", "h5", "swift", "objective-c", "arkts", "javascript", "typescript", "other", "unknown"}
+TECHNICAL_STATUSES = {"present", "none", "uncertain", "not-applicable"}
+DEPENDENCY_KINDS = {"sdk", "so"}
+PROVENANCE = {"open-source", "closed-source", "mixed", "unknown"}
+LINKAGES = {"direct", "transitive", "dynamic", "unknown"}
+PERMISSION_REQUIREMENTS = {"install-time", "runtime", "special", "conditional", "unknown"}
+
+
+def validate_citations(items: object, label: str, repo_id: str, repo_map: dict[str, Path], line_counts: dict[Path, int], errors: list[str]) -> set[str]:
+    if not isinstance(items, list):
+        errors.append(f"{label} must be an array")
+        return set()
+    types: set[str] = set()
+    for evidence_index, citation in enumerate(items):
+        citation_label = f"{label}[{evidence_index}]"
+        if not isinstance(citation, dict):
+            errors.append(f"{citation_label} must be an object")
+            continue
+        evidence_type = citation.get("type")
+        if evidence_type not in EVIDENCE_TYPES:
+            errors.append(f"{citation_label}.type invalid: {evidence_type}")
+        else:
+            types.add(evidence_type)
+        rel = citation.get("path")
+        line_start = citation.get("line_start")
+        if not isinstance(rel, str) or not rel or Path(rel).is_absolute() or ".." in Path(rel).parts:
+            errors.append(f"{citation_label}.path must be repository-relative")
+            continue
+        repo_root = repo_map.get(repo_id)
+        source = repo_root / rel if repo_root else Path(rel)
+        if not source.is_file():
+            errors.append(f"{citation_label} source not found: {source}")
+            continue
+        if not isinstance(line_start, int) or line_start < 1:
+            errors.append(f"{citation_label}.line_start must be >= 1")
+        else:
+            if source not in line_counts:
+                try:
+                    line_counts[source] = sum(1 for _ in source.open("rb"))
+                except OSError:
+                    line_counts[source] = 0
+            if line_start > line_counts[source]:
+                errors.append(f"{citation_label}.line_start exceeds file length")
+        line_end = citation.get("line_end", line_start)
+        if not isinstance(line_end, int) or isinstance(line_start, int) and line_end < line_start:
+            errors.append(f"{citation_label}.line_end must be >= line_start")
+        if not isinstance(citation.get("summary"), str) or not citation["summary"].strip():
+            errors.append(f"{citation_label}.summary is required")
+    return types
+
+
+def validate_negative_searches(value: object, label: str, errors: list[str]) -> list[str]:
+    if not isinstance(value, list):
+        errors.append(f"{label} must be an array")
+        return []
+    searches = [item.strip() for item in value if isinstance(item, str) and item.strip()]
+    if len(searches) < 2:
+        errors.append(f"{label} requires at least two concrete searches")
+    return searches
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("inventory", type=Path)
+    parser.add_argument("--strict", action="store_true", help="fail when warnings exist")
+    args = parser.parse_args()
+    data = json.loads(args.inventory.read_text(encoding="utf-8"))
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    if data.get("schema_version") != "1.2":
+        errors.append("schema_version must be '1.2'")
+    max_depth = data.get("max_depth")
+    if max_depth != 4:
+        errors.append("max_depth must be 4")
+
+    repos = data.get("repositories")
+    if not isinstance(repos, list) or not repos:
+        errors.append("repositories must be a non-empty array")
+        repos = []
+    repo_map: dict[str, Path] = {}
+    repo_platforms: dict[str, str] = {}
+    for index, repo in enumerate(repos):
+        label = f"repositories[{index}]"
+        repo_id = repo.get("id") if isinstance(repo, dict) else None
+        if not isinstance(repo_id, str) or not re.fullmatch(r"[a-z][a-z0-9_]*", repo_id):
+            errors.append(f"{label}.id must be stable snake_case")
+            continue
+        if repo_id in repo_map:
+            errors.append(f"duplicate repository id: {repo_id}")
+        path = Path(str(repo.get("path", ""))).expanduser()
+        if not path.is_absolute() or not path.is_dir():
+            errors.append(f"{label}.path must be an existing absolute directory: {path}")
+        repo_map[repo_id] = path
+        repo_platforms[repo_id] = str(repo.get("platform", "")).lower()
+
+    features = data.get("features")
+    if not isinstance(features, list):
+        errors.append("features must be an array")
+        features = []
+    seen: set[tuple[str, tuple[str, ...]]] = set()
+    line_counts: dict[Path, int] = {}
+
+    for index, feature in enumerate(features):
+        label = f"features[{index}]"
+        if not isinstance(feature, dict):
+            errors.append(f"{label} must be an object")
+            continue
+        context = feature.get("entry_context")
+        if not isinstance(context, str) or not context.strip():
+            errors.append(f"{label}.entry_context is required")
+        path_parts = feature.get("path")
+        if not isinstance(path_parts, list) or not 1 <= len(path_parts) <= 4 or any(not isinstance(part, str) or not part.strip() for part in path_parts):
+            errors.append(f"{label}.path must contain 1-4 non-empty strings")
+            continue
+        dedupe_key = (str(context), tuple(part.strip() for part in path_parts))
+        if dedupe_key in seen:
+            errors.append(f"duplicate path in context {context}: {' > '.join(path_parts)}")
+        seen.add(dedupe_key)
+        if feature.get("kind") not in KINDS:
+            errors.append(f"{label}.kind must be one of {sorted(KINDS)}")
+        if not isinstance(feature.get("trigger"), str) or not feature["trigger"].strip():
+            errors.append(f"{label}.trigger is required")
+        if not isinstance(feature.get("effect"), str) or not feature["effect"].strip():
+            warnings.append(f"{label}.effect is empty")
+        if not isinstance(feature.get("should_develop"), bool):
+            errors.append(f"{label}.should_develop must be boolean")
+        elif feature["should_develop"] is False and (not isinstance(feature.get("notes"), str) or not feature["notes"].strip()):
+            errors.append(f"{label}.notes must explain why should_develop is false")
+        if feature.get("release_stage") not in RELEASE_STAGES:
+            errors.append(f"{label}.release_stage must be one of {sorted(RELEASE_STAGES)}")
+        if not isinstance(feature.get("release_rationale"), str) or not feature["release_rationale"].strip():
+            errors.append(f"{label}.release_rationale is required")
+
+        implementations = feature.get("implementations")
+        if not isinstance(implementations, dict):
+            errors.append(f"{label}.implementations must be an object")
+            continue
+        missing = sorted(set(repo_map) - set(implementations))
+        extra = sorted(set(implementations) - set(repo_map))
+        if missing:
+            errors.append(f"{label} missing repository statuses: {missing}")
+        if extra:
+            errors.append(f"{label} has unknown repository statuses: {extra}")
+
+        for repo_id, impl in implementations.items():
+            impl_label = f"{label}.implementations.{repo_id}"
+            if not isinstance(impl, dict):
+                errors.append(f"{impl_label} must be an object")
+                continue
+            status = impl.get("status")
+            confidence = impl.get("confidence")
+            if status not in STATUSES:
+                errors.append(f"{impl_label}.status invalid: {status}")
+            if confidence not in CONFIDENCES:
+                errors.append(f"{impl_label}.confidence invalid: {confidence}")
+            technology_stack = impl.get("technology_stack")
+            if not isinstance(technology_stack, list) or any(item not in TECHNOLOGIES for item in technology_stack):
+                errors.append(f"{impl_label}.technology_stack must contain only {sorted(TECHNOLOGIES)}")
+                technology_stack = []
+            elif len(technology_stack) != len(set(technology_stack)):
+                errors.append(f"{impl_label}.technology_stack must not contain duplicates")
+            if status in {"implemented", "partial", "mock", "unreachable"} and not technology_stack:
+                errors.append(f"{impl_label}.technology_stack is required for status {status}")
+            technology_types = validate_citations(impl.get("technology_evidence", []), f"{impl_label}.technology_evidence", repo_id, repo_map, line_counts, errors)
+            if status in {"implemented", "partial", "mock", "unreachable"} and "tech_stack" not in technology_types:
+                errors.append(f"{impl_label}.technology_evidence needs tech_stack evidence")
+
+            external = impl.get("external_dependencies")
+            if not isinstance(external, dict):
+                errors.append(f"{impl_label}.external_dependencies must be an object")
+            else:
+                external_status = external.get("status")
+                if external_status not in TECHNICAL_STATUSES:
+                    errors.append(f"{impl_label}.external_dependencies.status invalid: {external_status}")
+                if status in {"implemented", "partial", "mock", "unreachable"} and external_status == "not-applicable":
+                    errors.append(f"{impl_label}.external_dependencies cannot be not-applicable for an existing implementation")
+                items = external.get("items", [])
+                if not isinstance(items, list):
+                    errors.append(f"{impl_label}.external_dependencies.items must be an array")
+                    items = []
+                if external_status == "present" and not items:
+                    errors.append(f"{impl_label}.external_dependencies present requires items")
+                if external_status in {"none", "not-applicable"} and items:
+                    errors.append(f"{impl_label}.external_dependencies {external_status} must not contain items")
+                if external_status == "none":
+                    validate_negative_searches(external.get("negative_searches"), f"{impl_label}.external_dependencies.negative_searches", errors)
+                for item_index, item in enumerate(items):
+                    item_label = f"{impl_label}.external_dependencies.items[{item_index}]"
+                    if not isinstance(item, dict):
+                        errors.append(f"{item_label} must be an object")
+                        continue
+                    if not isinstance(item.get("name"), str) or not item["name"].strip():
+                        errors.append(f"{item_label}.name is required")
+                    if item.get("kind") not in DEPENDENCY_KINDS:
+                        errors.append(f"{item_label}.kind invalid: {item.get('kind')}")
+                    if item.get("provenance") not in PROVENANCE:
+                        errors.append(f"{item_label}.provenance invalid: {item.get('provenance')}")
+                    if item.get("linkage") not in LINKAGES:
+                        errors.append(f"{item_label}.linkage invalid: {item.get('linkage')}")
+                    if not isinstance(item.get("required"), bool):
+                        errors.append(f"{item_label}.required must be boolean")
+                    if not isinstance(item.get("purpose"), str) or not item["purpose"].strip():
+                        errors.append(f"{item_label}.purpose is required")
+                    dependency_types = validate_citations(item.get("evidence", []), f"{item_label}.evidence", repo_id, repo_map, line_counts, errors)
+                    if not dependency_types & {"dependency_declaration", "native_library"}:
+                        errors.append(f"{item_label}.evidence needs dependency declaration or native-library evidence")
+                    if not dependency_types & {"effect", "native_library"}:
+                        errors.append(f"{item_label}.evidence needs feature usage, bridge, call, or load evidence")
+
+            permissions = impl.get("android_permissions")
+            if not isinstance(permissions, dict):
+                errors.append(f"{impl_label}.android_permissions must be an object")
+            else:
+                permission_status = permissions.get("status")
+                if permission_status not in TECHNICAL_STATUSES:
+                    errors.append(f"{impl_label}.android_permissions.status invalid: {permission_status}")
+                if repo_platforms.get(repo_id) != "android" and permission_status != "not-applicable":
+                    errors.append(f"{impl_label}.android_permissions must be not-applicable for non-Android repositories")
+                if repo_platforms.get(repo_id) == "android" and status in {"implemented", "partial", "mock", "unreachable"} and permission_status == "not-applicable":
+                    errors.append(f"{impl_label}.android_permissions cannot be not-applicable for an Android implementation")
+                permission_items = permissions.get("items", [])
+                if not isinstance(permission_items, list):
+                    errors.append(f"{impl_label}.android_permissions.items must be an array")
+                    permission_items = []
+                if permission_status == "present" and not permission_items:
+                    errors.append(f"{impl_label}.android_permissions present requires items")
+                if permission_status in {"none", "not-applicable"} and permission_items:
+                    errors.append(f"{impl_label}.android_permissions {permission_status} must not contain items")
+                if permission_status == "none":
+                    validate_negative_searches(permissions.get("negative_searches"), f"{impl_label}.android_permissions.negative_searches", errors)
+                for item_index, item in enumerate(permission_items):
+                    item_label = f"{impl_label}.android_permissions.items[{item_index}]"
+                    if not isinstance(item, dict):
+                        errors.append(f"{item_label} must be an object")
+                        continue
+                    if not isinstance(item.get("name"), str) or not item["name"].strip():
+                        errors.append(f"{item_label}.name is required")
+                    if item.get("requirement") not in PERMISSION_REQUIREMENTS:
+                        errors.append(f"{item_label}.requirement invalid: {item.get('requirement')}")
+                    if not isinstance(item.get("required_when"), str) or not item["required_when"].strip():
+                        errors.append(f"{item_label}.required_when is required")
+                    if not isinstance(item.get("purpose"), str) or not item["purpose"].strip():
+                        errors.append(f"{item_label}.purpose is required")
+                    permission_types = validate_citations(item.get("evidence", []), f"{item_label}.evidence", repo_id, repo_map, line_counts, errors)
+                    if not permission_types & {"permission_request", "effect"}:
+                        errors.append(f"{item_label}.evidence needs a permission request/check or protected API usage")
+            evidence = impl.get("evidence", [])
+            if not isinstance(evidence, list):
+                errors.append(f"{impl_label}.evidence must be an array")
+                evidence = []
+            types: set[str] = set()
+            production_types: set[str] = set()
+            for evidence_index, citation in enumerate(evidence):
+                citation_label = f"{impl_label}.evidence[{evidence_index}]"
+                if not isinstance(citation, dict):
+                    errors.append(f"{citation_label} must be an object")
+                    continue
+                evidence_type = citation.get("type")
+                if evidence_type not in EVIDENCE_TYPES:
+                    errors.append(f"{citation_label}.type invalid: {evidence_type}")
+                else:
+                    types.add(evidence_type)
+                    if evidence_type not in {"test", "doc"}:
+                        production_types.add(evidence_type)
+                rel = citation.get("path")
+                line_start = citation.get("line_start")
+                if not isinstance(rel, str) or not rel or Path(rel).is_absolute() or ".." in Path(rel).parts:
+                    errors.append(f"{citation_label}.path must be repository-relative")
+                    continue
+                repo_root = repo_map.get(repo_id)
+                source = repo_root / rel if repo_root else Path(rel)
+                if not source.is_file():
+                    errors.append(f"{citation_label} source not found: {source}")
+                    continue
+                if not isinstance(line_start, int) or line_start < 1:
+                    errors.append(f"{citation_label}.line_start must be >= 1")
+                else:
+                    if source not in line_counts:
+                        try:
+                            line_counts[source] = sum(1 for _ in source.open("rb"))
+                        except OSError:
+                            line_counts[source] = 0
+                    if line_start > line_counts[source]:
+                        errors.append(f"{citation_label}.line_start exceeds file length")
+                line_end = citation.get("line_end", line_start)
+                if not isinstance(line_end, int) or isinstance(line_start, int) and line_end < line_start:
+                    errors.append(f"{citation_label}.line_end must be >= line_start")
+                if not isinstance(citation.get("summary"), str) or not citation["summary"].strip():
+                    errors.append(f"{citation_label}.summary is required")
+
+            if status in {"implemented", "partial", "mock"} and not (types & ACTION_TYPES):
+                errors.append(f"{impl_label} needs interaction, route, navigation, or effect evidence")
+            if status in {"implemented", "partial", "mock", "unreachable"} and not production_types:
+                errors.append(f"{impl_label} cannot rely only on test/doc evidence")
+            if status == "implemented" and confidence == "high":
+                if not (types & VISIBLE_TYPES):
+                    warnings.append(f"{impl_label} high confidence lacks visible label/menu evidence")
+                if len(production_types & ACTION_TYPES) < 1 or len(production_types) < 2:
+                    warnings.append(f"{impl_label} high confidence has fewer than two production evidence classes")
+            if status == "absent":
+                searches = impl.get("negative_searches")
+                if not isinstance(searches, list) or len([item for item in searches if isinstance(item, str) and item.strip()]) < 2:
+                    errors.append(f"{impl_label} absent requires at least two concrete negative_searches")
+                if confidence == "high" and len(searches or []) < 4:
+                    warnings.append(f"{impl_label} high-confidence absence should document broader negative searches")
+
+    for message in errors:
+        print(f"ERROR: {message}")
+    for message in warnings:
+        print(f"WARNING: {message}")
+    print(json.dumps({"features": len(features), "repositories": len(repo_map), "errors": len(errors), "warnings": len(warnings)}, ensure_ascii=False))
+    return 1 if errors or args.strict and warnings else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+

package/skills/d2h-architecture-plan/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: d2h-architecture-plan
+description: >-
+  用于 Android 转 HarmonyOS 的架构评估、目录规划和方案选型。默认读取 Android 源码，交付原结构对照、鸿蒙优选、融合三套结构选项，详列推荐方案目录；
+  用户确认方案并要求创建时，可落地基础工程与关键目录。
+---
+
+# Android 源码 → 鸿蒙架构与目录规划
+
+基于 Android 工程结构与必要源码，为迁移确定职责归属、依赖方向和可落地的鸿蒙目录，兼顾原开发者维护便利性。默认做目录级架构分析，不开展完整业务理解、逐页行为分析或实现级迁移设计。
+
+## 输入与边界
+
+- 必需输入只有 Android 源码根目录，可独立执行。按用户范围识别实际应用、运行时模块、技术栈和目标设备；源码缺失或目标能力未知时标明影响。
+- 默认只读取 Android 工程源码及其相关资源、构建声明；不自动读取同级、嵌套或配置中指向的鸿蒙工程源码，也不为寻找鸿蒙参考实现扩大扫描范围。
+- 仅当已有上下文明确表明存在鸿蒙工程，且用户尚未决定是否结合时，询问一次：“是否结合现有鸿蒙工程进行架构规划？默认仅分析 Android 工程。”仅提供新工程的输出路径不触发询问，配置中的目标路径也不能单独证明已有鸿蒙工程或用户选择结合。
+- 用户明确要求结合/复用指定鸿蒙工程时，按约定范围读取；明确选择不结合时，只分析 Android。同一工程、同一任务范围内沿用已有明确选择，不重复询问；用户改变选择时据此调整。尚未答复期间可继续 Android 侧分析，不读取鸿蒙源码，也不把沉默记为用户拒绝。
+- 已有功能清单、Facts、规划可作导航线索，用当前源码核验。
+- 默认只交付架构 Markdown；不生成持久化的全量文件清单、源码快照、import/调用图或扫描基线。已有大型扫描产物按问题查询，不整体读入或为更新规划重新生成。
+- 源工程只读；默认在同级 `<工程名>-migration/.migration/architecture-plan/` 交付。已有文件先阅读，保留用户批注，修订时同步受影响部分。
+- 分析分支和目录组织依据本次读取范围内的工程事实与迁移目标确定，参考示例按实际需要选用。未读取的鸿蒙工程不作已核验的复用或实现依据。
+
+## 架构规划
+
+1. 按 [source-review.md](references/source-review.md) 从构建声明、入口/导航和主要源码目录建立结构地图，识别基础依赖、页面业务、共享业务及装配。仅当证据不足会改变拆合、归属或依赖方向时，定点读取相关源码；边界可解释后停止扩读。
+2. 按 [layout-reference.md](references/layout-reference.md) 设计原结构对照 `android-mirror`、鸿蒙优选 `harmony-practice`、融合 `hybrid`，共用范围地图；已有选定方案时只修订它及受影响的对照。融合结构以基础依赖保留原模块/包族、业务按 feature 承载页面为原则，需要详细展开时读 [hybrid-design.md](references/hybrid-design.md)，不展开逐页实施计划。
+3. 按 [plan-contract.md](references/plan-contract.md) 详细展开推荐方案的关键目录、归属与主要依赖，另两套给结构差异对照；已有选定方案则围绕它展开。用户明确要求三套完整目录时再全部展开，共享事实仍只写一次。复核目录/归属/依赖一致性，不重复业务链或完整分析报告。
+
+本 Skill 交付架构与转换交接设计；并行候选表示具备独立转换的架构条件，实际派发、开发和验收由调用方的执行流程决定。
+
+## 选型与可选落地
+
+只请求分析/规划时，交付推荐和可选方案即完成本次规划，不为结束任务强求用户立即选型。用户选定后按意见修订、复核并记录最终方案。**创建或搬迁前须有对当前方案的实际确认及创建要求**；已有“采用推荐并创建”的明确授权则直接按授权执行。
+
+需要落地时才读 [directory-creation.md](references/directory-creation.md)，使用本机 DevEco CLI 和普通文件工具创建选中方案的基础工程与目录。不生成业务实现，不构建或运行应用。

package/skills/d2h-architecture-plan/references/directory-creation.md

@@ -0,0 +1,43 @@
+# 用户确认后的目录落地
+
+仅在用户要求创建/搬迁且已确认当前方案时读取。本阶段使用普通文件工具与本机 DevEco CLI。只创建基础工程和关键目录，不实现业务、不构建或运行应用。
+
+## 1. 固定实际选择与目标
+
+- 记录用户选择的方案ID、当前规划文件、修改意见和创建要求；明确推荐委托同样有效，不能自动把模型推荐当用户授权。
+- 从选中方案推导目录清单，核对路径位于目标根内，无绝对子路径、上级跳转、大小写冲突或模块嵌套。不得跟随链接写入源/参考工程或目标根之外。
+- 先检查目标实际状态和已有工程；保留用户文件。新增目录通常可直接执行；重用、移动或覆盖存在冲突的内容先查清，未授权覆盖则停止该动作并说明具体冲突。
+- 目标设备/SDK与方案一致；未知设备能力不以默认phone掩盖，也不把所有Android设备名直接写入鸿蒙配置。
+
+## 2. 创建或复用基础工程
+
+新工程先定位本机DevEco CLI，阅读其帮助核对当前create命令、应用名、bundle、设备和输出路径等参数；不把Android构建文件复制成鸿蒙配置。需要用户身份信息时只询问缺少的实际值。
+
+已有工程先核对根构建配置、注册模块及本地依赖，确认可承载所选目录。保留CLI模板和用户文件。需要把模板entry放到选中产品路径时，先核对目标无冲突，再同步根注册srcPath及相关本地路径；无法确认安全时不移动，报告差异与必要改法。
+
+创建/复用授权所需的目标配置核对、目录冲突检查与创建结果验证，不等于选择结合鸿蒙源码进行架构分析。若还需阅读现有业务实现来判断复用或调整架构，先按 [SKILL.md](../SKILL.md) 询问是否结合，已有明确选择则按其范围执行。
+
+CLI不可用或不支持目标设备时，保留已完成规划，给出实际错误及未完成创建项；普通空目录不能冒充可用鸿蒙基础工程。不要为本阶段无限安装/重试工具或索要与创建无关的凭据。
+
+## 3. 补齐选中目录
+
+只创建选中方案的实际模块/关键子目录。模板之外不生成业务文件、空实现、额外模块配置或提前注册所有HAR/HSP；这些目录须明确标注为待下游配置的目录壳子。
+
+选中原本仅作差异对照的方案时，先据已确认的结构差异补齐它的目录树。规划使用共用 feature 子目录模式时，从关键树与模式展开本次实际清单，按实际职责选取子目录即可；不为展开或创建壳子重做业务分析。若发现归属冲突或影响实际布局的待决，局部澄清该边界后再创建受影响目录。
+
+选中融合方案时从已确认映射创建基础包族与页面 feature 目录，保留逻辑目录和实际模块的区别；单 HAP 的 feature 目录落在实际源码根内，资源服从所属模块规则，不套用独立库的 `src/main`。共享契约和集成所有权随规划交接，不以生成接口桩或复制共享状态充当完成前置。
+
+命令成功后检查目标根基础配置、注册产品路径及关键目录确实存在，设备配置与选择一致，已有文件没有被覆盖；若执行中用户修改规划，先核对影响，不能按旧目录继续宣称完整。
+
+## 4. 保存实际记录并交接
+
+在规划产物目录写 `shell-receipt.json`，记录可核验的实际创建结果：
+
+- `status`：complete / partial / blocked，按真实创建结果填写。
+- `planFile`、`proposalId`、`target`：当前规划、选中方案和实际目标根。
+- `confirmation`：实际用户选择/推荐委托及对应修订，未确认不得执行创建。
+- `baseProject`：新建或复用、实际注册产品路径、设备类型及使用的CLI/命令/日志位置。
+- `createdDirectories`、`existingDirectories`、`directoryOnlyModules`：分别记录新增、已存在和未注册的模块目录。
+- `verification`、`remainingIssues`：实际检查结果、路径/配置差异和未完成项，不编造日志或检查。
+
+创建完成只表示基础工程和所选目录壳子已落地。交接最终规划、receipt与未解决风险；其他两套保留为对照。模型生成的记录不能替代目标文件/目录和用户授权证据。

package/skills/d2h-architecture-plan/references/hybrid-design.md

@@ -0,0 +1,84 @@
+# 融合方案：基础保留结构，业务按页面组织
+
+设计或修订 `hybrid` 时读取。目标是让原开发者沿原模块/包族定位基础能力，让后续转换能按页面分工。先分类与核对主要依赖，再画目录；两个层次是迁移职责，不等同于两个物理模块。阅读深度按 [source-review.md](source-review.md) 控制，以下约束用于确定边界，不要求在此完成实现设计。
+
+## 1. 按职责划分两层
+
+| 归属 | 判断依据 | 组织原则 |
+|---|---|---|
+| 基础依赖层 | 网络传输、通用存储、日志、基础协议、平台/Native/三方包装等支撑能力；有实际消费者，不决定页面流程 | 优先保留原模块名、包族的相对层级与合理依赖；保留业务无关的通用 UI 时仍需替换 Android 展示实现，数据/协议不依赖 UI |
+| 业务层的页面 feature | 页面/紧密页面组的展示、状态、交互规则、私有数据访问和资源 | 按目标职责内聚，采用 ArkUI 页面、ViewModel/等效状态管理及数据访问分离；不强制为简单页面增设 Domain/UseCase |
+| 业务层的共享业务 | 多页共同使用的业务规则、Repository、会话或任务状态，有唯一业务所有者 | 放在所属业务域的共享区域，提供稳定公开能力；不能仅因无 UI 或多页复用就归入基础依赖 |
+| 业务侧应用装配 | Ability、启动、导航容器、依赖注入与设备/产品配置 | 产品壳装配基础实现、共享业务与页面；不承接全应用业务状态，不新增一套与两层竞争的业务归属 |
+
+按真实职责分类，不按 Gradle 模块、Activity 类名或 `common/lib` 名字整包贴标签。原依赖库中含页面则把页面抽入 feature；原 app 包中的通用网络/存储可归基础层；源码中的领域模型/业务 Repository 按语义与所有者归业务域。后台、外部入口及非页面业务也要保留所有者与生命周期，不能因按页面组织而遗漏。
+
+## 2. 基础依赖：保留定位，显式适配
+
+以实际源码根为锚点，把原模块/包族映射到目标。默认保留有维护价值的模块名与源码根以下的相对目录；已有多层模块路径保留必要的定位关系。语言根从 `java/kotlin` 变为 `ets` 等目标变化单列，不在目标中嵌套一份 Android 工程。
+
+例如 `infra/src/main/java/com/acme/infra/net/` 可映射到 `commons/infra/src/main/ets/com/acme/infra/net/`。源文件的主要职责只认领一次；混合文件按符号/职责说明页面、共享业务或适配内容的去向，不让同一粗路径同时代表“整体保留”和“全部抽走”。
+
+保留的是可追溯结构与合理协作，不是 Android 实现机制：Android API、资源格式、JNI/运行时和 SDK 坐标按目标承接方式替换。原结构中反向依赖页面、应用单例、环或业务混杂的部分需要最小拆分/改向，逐项记录原路径、保留部分、调整部分、目标所有者、消费者与理由。未确认的 SDK/Native/运行时能力记录受影响边界和验证前置，不能凭保留目录认定可直接转换。
+
+不要为了套 `core/network/storage/model` 模板再次打散已清晰的原包族；也不要为了保留路径把对页面/应用单例的依赖、展示状态或业务策略留在基础层。平台适配所需上下文由装配按生命周期提供，避免基础能力持有页面实例。跨层拆分成本明显超过收益时说明替代边界及仍受耦合限制的页面。
+
+## 3. 业务层：feature 是转换边界
+
+依据主要页面族与代表入口规划 feature 候选，不要求先穷举全部页面。优先让可独立转换的页面有明确目录；强共享私有状态或不可拆生命周期的页面可组成紧密页面组，说明原因。多页共用领域会话可通过共享所有者承接，不因此把整个业务域合成不可并行的一组。Activity/Fragment 个数及追求并行度不单独决定拆分；Dialog/Sheet/页面模式按已知职责归属，具体页面清单留待后续细化。
+
+每个 feature 内聚页面、ViewModel/等效状态、私有数据访问、组件和资源；按真实复杂度选目录，保留原业务名及源码映射便于定位。共享会话、缓存、任务队列等由一个领域所有者维护，页面只保留展示投影；导航传必要标识/值或约定结果，不传其他页面的 ViewModel、组件实例或可变状态。
+
+`feature` 是职责与目录边界，不是“一页一个 HAR/HSP”。先确定页面归属，再按部署、运行时共享和构建成本决定哪些目录构成 HAP/HAR/HSP。不同 HAR 中重复打包或初始化同一状态不能当作进程级单例；需共享状态时说明实际实例如何由装配创建、提供、持有与释放。
+
+下面仅示意已存在 `infra` 基础包、商品列表/详情共享业务及独立设置页的工程。树只列目录，名字和包粒度从实际源码确定；`commons`、`features` 分别可承载两层，`products` 承载业务侧装配。
+
+```text
+<HarmonyOS>/
+├── AppScope/
+├── products/<产品>/src/main/         # HAP 示例
+│   ├── ets/{entryability,navigation,composition}/
+│   └── resources/
+├── commons/infra/src/main/            # 基础 HAR 示例
+│   ├── ets/com/acme/infra/            # 原基础包族相对层级
+│   │   ├── net/
+│   │   └── store/
+│   └── resources/                    # 原基础能力实际拥有的资源
+└── features/
+    ├── catalog/src/main/             # 业务 HAR 示例，含两个页面 feature
+    │   ├── ets/
+    │   │   ├── list/{pages,viewmodel,data,components}/
+    │   │   ├── detail/{pages,viewmodel,data}/
+    │   │   └── shared/{model,repository,state}/
+    │   └── resources/                # 同模块资源，划分页面命名与集成归属
+    └── settings/src/main/            # 另一业务 HAR 示例
+        ├── ets/{pages,viewmodel}/
+        └── resources/
+```
+
+上例列表/详情共享一个业务 HAR，页面 feature 是其内部独立目录。实际工程可以合入产品 HAP，也可在独立演进收益足够时拆库；目录树需标注实际模块及源码根，不把业务域分组自动变成构建模块。共享状态实例仍按装配契约提供，不由 HAR 名称保证唯一性。
+
+单 HAP 可在 `entry/src/main/ets/` 下使用 `foundation/<原包族>/`、`features/<业务>/<页面>/`、必要的 `features/<业务>/shared/` 和装配目录；资源按目标模块规则放置并划分命名/写入所有权。模块内目录也能定义页面转换边界，不能虚构每页独立的资源根或构建能力。
+
+## 4. 依赖与共享契约
+
+说明代码依赖与运行时调用各自如何闭合：
+
+- 产品壳装配页面、共享业务与基础实现；页面使用本域共享业务的公开能力和基础能力，基础能力之间保留已核验的无环依赖，基础层不反向依赖 feature 或产品壳。
+- feature 不直接导入其他页面的内部页面、状态、组件或数据实现。跨 feature 导航使用约定路由/参数/结果；数据、事件与回调另给实际契约及所有者，不能用“走路由”解释全部协作。
+- 共享业务按消费者与领域归属放置，必要时形成独立共享业务能力，其依赖保持无环；跨域协作不因缺少目录就全部放进全局 `commons`。
+- 平台实现需要业务回调时，在合适的消费者/契约边界定义所需能力，由产品装配注入实现；说明谁定义、谁实现、谁装配及如何取得实例。只有真实跨边界交互才引入契约，不为每个类造接口。
+
+在架构稿中简记关键共享能力、目标所有者、主要消费者及协作/装配方式，未明确的契约列为后续细化前置。只有输入输出、错误或生命周期约束会改变拆合与所有权时才展开；不要求完整契约设计，不预定接口文件，也不把规划能力写成已实现。
+
+导航可参考 [HarmonyOS 应用规划](https://developer.huawei.com/consumer/cn/app/planning/) 中的分层、模块化和 Navigation 设计，以及 [Navigation 跨包路由](https://developer.huawei.com/consumer/cn/doc/doccenter-capabilities/arkts-navigation-cross-package) 的模块解耦机制（核查日期：2026-10-29）。两层融合、原包族保留及按页面分工是本 Skill 的迁移设计选择；不将一页一模块作为平台要求。具体路由与打包机制按实际 SDK/设备核实，不仅凭目录选定。
+
+## 5. 从分层到独立页面转换的交接
+
+本阶段交接“源入口/页面族 → feature 目录 → 共享依赖/所有者”及会影响分工的已知前置，复用归属表即可。转换建议按消费者说明最小基础/共享前置，再列可独立转换的页面候选和集成区域；不要求全部基础库先迁完，无关页面不被不相关的 Native/SDK 风险阻塞。
+
+路由、资源聚合、公共导出、构建配置与装配等已知共同修改区域指定集成归属；页面私有目录与共享区域分开。共享修改先回所有者，精确的独占文件、测试资产、完整契约与验收条件由后续页面规划/实现确定，不作为架构稿交付前置。
+
+并行建议附条件：契约明确、实现前置满足、写入范围不冲突且共同修改有集成归属；仅导航关联不自动形成实现顺序。条件未核验时写候选或待细化，强耦合已证实才要求合组/串行；规划契约与空目录不能证明已可开工。集成仍需验证真实能力和跨页协作。
+
+已有稳定 ID 可沿用，没有则以源入口关联候选，不造页面/Spec 身份、账本或任务协议。实际派发、工作区隔离、构建/设备资源协调与验收由执行方决定，架构目录不自动开放并发。

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

@@ -0,0 +1,83 @@
+# 架构选择与目录参考
+
+先决定职责、状态所有权、协作和演进边界，再决定目录。以下给出判断方法及可选目录示例；名称、分层与模块数量由当前工程职责和维护需求决定。
+
+这些决定使用结构地图与必要的边界证据即可，不要求先验证全部业务行为。共享结论在三套方案间复用；本参考用于选择结构，阅读深度与停止条件见 [source-review.md](source-review.md)。
+
+## 1. 选择适合工程的方法
+
+| 判断 | 决策原则 |
+|---|---|
+| 原架构是否健康 | 有清晰边界与状态来源时保留其有效思想；MVC/MVP/MVVM/MVI名称本身不决定质量 |
+| UI、规则与数据如何协作 | 通常先分离展示/状态和数据访问，评估单向数据流、MVVM或等效状态模式；复杂/复用规则需要时加Domain/UseCase，不强制完整Clean分层 |
+| 什么时候拆模块 | 职责内聚、真实跨域复用、独立演进/上游升级、平台边界或隔离收益足以抵偿契约、配置和定位成本时再拆 |
+| 什么时候共享 | 先确认实际消费者与稳定契约；域内复用留本域，跨域共享分别界定展示、数据/契约与平台设施的所有权 |
+| 如何控制依赖 | 应用入口负责装配，业务通过公开契约协作，基础设施不感知页面；消除目标环和反向UI依赖，接口方向按所选架构解释 |
+| 如何打包 | HAP/HAR/HSP按实际部署、共享及运行需求选择；目录分层不等于独立库，不因采用规范目录就增加HAP或每层建HAR |
+
+新工程也评价原作者的维护便利性：哪些业务名和包族能沿用、变化后从哪里找页面/状态/数据、常见修改需跨多少模块、故障怎样回溯源码。可读性来自职责与一致命名，不来自把所有Java包原样堆进ArkTS，也不来自一律改成陌生名字。
+
+## 2. 三套方案如何区别
+
+| 方案 | 目录/边界约束 | 必须解释 |
+|---|---|---|
+| android-mirror | 运行时源模块一对一对照，保留源模块名、相对布局、关键包族与内部模块声明依赖；构建辅助项目不变成目标业务库 | 外部SDK/API保留能力与消费者对照，不照搬AndroidX等包坐标；Ability/资源/语言及运行时必要适配；源技术债、环或不可行的边不能伪装成鸿蒙可实施结构 |
+| harmony-practice | 依据目标职责重组，按消费者、数据所有权与平台边界选择目录和模块粒度；允许单HAP或适当模块化 | 具体收益、消费者和数据流；新增命名、拆合及平台适配成本，不以“最佳实践”替代论证 |
+| hybrid | 基础依赖层优先保留原模块名、包族及合理依赖；业务层按页面或紧密页面组组织 feature，应用壳负责装配 | 基础保留与适配例外、页面边界及共享业务所有者；详细展开时按 [hybrid-design.md](hybrid-design.md) 设计，不能仅改变第二套顶层名字 |
+
+简单应用三套可以有相同模块数甚至相同树；说明相同决定与缺少额外拆分收益的原因。推荐可为任一套，依据实际收益和维护代价判断。
+
+融合方案的两个层次是迁移职责划分，不强制增加两个顶层目录或独立构建模块。下节是通用目录字典；融合方案的原包族保留、页面粒度与共享边界以 [hybrid-design.md](hybrid-design.md) 为准。
+
+对照方案也保留模块内部主要目录/包族的相对层级，参照各实际源码根（如Java/Kotlin根、Dart/JS业务根），包括原有扁平组织；不主动新增pages/state/data等分组来重构源包。鸿蒙必需的入口、资源格式或Native桥接新增目录逐项标明适配理由；模板目录命名惯例不等于平台强制结构。纯职责重分层留给另外两套。未知实现只在已有职责归属中标待证，不为未知类细分一串目录。
+
+源声明依赖与实际调用不一致时，两者分开记录。对照方案保留源模块及原有边，目标必须补边或替代的地方显式标为适配/修复，不能冒充源已声明的事实或偷偷拆合；证据不足时保留待决，不以“严格对照”宣布不可实施的图已就绪。
+
+多技术栈对照应同时保留Android宿主与实际业务源码的定位线索；不把Dart/JS业务当作新的Gradle模块，也不声称照搬源目录就保留了运行时。用户明确目标设备或范围优先；未知设备支持列为前提，不通过删功能制造可行性。
+
+## 3. 可选目录组织示例
+
+项目可按应用装配、业务职责与共享能力组织目录，也可保留已有且合理的结构。以下名称用于示意，按实际职责选取：
+
+| 职责 | 名称示例 | 放什么 | 边界 |
+|---|---|---|---|
+| 应用装配 | products / app / entry | Ability、启动与依赖装配、应用级导航、当前目标的运行配置 | 业务状态和共享数据各有所有者 |
+| 业务职责 | 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/
+```
+
+单模块同样可在 `entry/src/main/ets/<业务>/` 内组织页面、状态和数据；选择products目录也不强制独立features库。业务代码通过清晰接口与平台能力协作，不将Android Activity/Service逐个等同为UIAbility/ExtensionAbility。
+
+组件按职责与消费者确定归属：域内私有组件留本域，跨域通用展示可放共享UI或独立组件目录；顶层 `components` 与其他命名均按当前结构和维护收益选择。完整业务能力的复用仍需说明其状态、数据与协作边界。数据/协议模块不反向依赖共享UI，应用装配保持独立职责。
+
+对工程实际存在的资源、配置、持久化结构、本地能力或跨运行时依赖，分别说明目标归属；配置差异仅在影响本次迁移时展开。共享能力是否合库，按消费者、上游升级、构建和生命周期决定。
+
+## 4. 依据与适用边界
+
+以下一手资料提供原则，具体SDK/API/设备能力在当前决策需要时查最新文档；不将Android打包/API机制直接复制成鸿蒙方案。
+
+- [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约束。