@harmonyos-arkts/d2h 0.1.20 → 0.1.21

package/skills/d2h-app-solution/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: d2h-app-solution
+description: Extract an auditable inventory.json containing a one-to-four-level user-facing feature inventory from Android, HarmonyOS, iOS, Flutter, React Native, or web source repositories, including whether each feature should be developed, implementation status, MVP/core/full release stage, per-feature technology stack, SDK/SO dependencies, Android permissions, confidence, and source citations. Use for code-based function discovery, navigation reconstruction, platform coverage comparison, or migration planning.
+---
+
+# 提取应用功能清单
+
+从“用户能看到并操作什么”出发重建功能树。不要把目录树、类名列表或字符串资源列表直接当成功能清单。
+
+## 输入与默认值
+
+收集以下输入；只有缺失项会实质改变结果时才询问：
+
+- 一个或多个应用代码仓路径；为每个仓指定稳定的短 ID 和展示名。
+- 输出目录。
+- 可选的产品变体、登录态、账号态、首次启动态或目标语言。
+- 可选的参考清单。参考清单只定义粒度和命名风格，不得覆盖源码事实。
+
+默认分析可发布的主应用变体、首次启动与回访用户两个入口上下文、最多四级路径，并输出中文名称。
+
+由 `d2h` 完整迁移流程调用时，输出目录固定为 Android 工程同级 `<工程名>-migration/.migration/feature-analysis/`，机器事实源固定命名为 `inventory.json`；单仓 Android 输入使用稳定仓 ID `android`、平台 `android`，并在 `repositories[].revision` 记录当前提交或 `working-tree`。独立调用仍使用用户指定输出目录。
+
+## 核心约束
+
+1. 只收录用户可感知的页面、区域、控件、菜单、对话框、设置项和操作结果。
+2. 先证明入口可达，再证明控件可见，再证明交互与结果。仅有字符串、类名、资源或测试名称不能证明功能存在。
+3. 测试、文档、截图和注释只能补强源码证据，不能单独支撑“已实现”。
+4. 不把后端能力、工具模块、示例目录、UI catalog、debug 页面或未接入入口的页面默认列为正式功能。
+5. 不用“未搜到”直接判定“无”。只有完成同义词、路由、入口、交互、资源和调用链复核后，才标记 `absent`；否则标记 `uncertain`。
+6. 不为凑齐四级而虚构中间节点。路径可以在任意一级结束。
+7. 同一功能从不同父入口进入时保留不同路径；只有交互语义、目标和前置条件等价时才跨仓对齐。
+8. 版本阶段按用户价值链判定，不把代码复杂度或推测的历史发布时间当作版本依据。
+9. 技术栈、SDK/SO 和权限必须关联到具体功能实现；仓库级依赖、Manifest 权限或某类文件存在不能自动套用到所有功能。
+10. 开闭源属性必须有许可证、源码或权威依赖元数据证据；无法证明时写 `unknown`，不要按厂商或包名猜测。
+
+## 工作流
+
+### 1. 建立确定性证据索引
+
+运行扫描器；扫描器只生成检索种子，不直接决定最终功能。扫描结果必须写入系统临时工作目录，不能写入 `inventory.json` 所在交付目录：
+
+```bash
+EVIDENCE_DIR="$(mktemp -d)"
+python3 <skill-dir>/scripts/scan_repositories.py \
+  --repo android=/abs/path/to/android-app \
+  --repo harmony=/abs/path/to/harmony-app \
+  --output "$EVIDENCE_DIR"
+```
+
+读取临时目录中的 `scan-summary.json`、`candidate-files.tsv` 和 `technical-files.tsv`，再用 `rg` 定点追踪高分文件。`technical-files.tsv` 用于定位实现语言、构建依赖、原生库和权限线索；扫描结果仍只是检索种子。大仓库不要从所有业务类开始逐文件阅读。完成 `inventory.json` 校验后清理该临时目录；交付目录最终只能包含 `inventory.json`。
+
+### 2. 识别平台与正式入口
+
+按需读取 [framework-evidence.md](references/framework-evidence.md)。逐仓确认：
+
+- launcher/ability/application 入口和实际发布变体；
+- 首次启动、未登录、已登录、无账号、有账号、深链等入口上下文；
+- 主页面、导航壳、tab、drawer、toolbar 和路由宿主；
+- 被 feature flag、权限、账号状态、构建 flavor 或 mock 数据控制的分支。
+
+把 demo、preview、test、catalog、benchmark、sample 和未被正式入口引用的页面从主图隔离。
+
+### 3. 重建可达交互图
+
+从每个正式入口做有界遍历：
+
+1. 解析路由声明和目标页面。
+2. 解析可见文案、菜单标题、图标的 content description/无障碍标签。
+3. 关联点击、手势、提交、选择、tab 切换和菜单展开回调。
+4. 沿回调追到导航目标、对话框、状态变化或外部系统行为。
+5. 记录控制显示/可用性的条件。
+6. 对动态路由、反射、DI、服务端配置或运行时菜单保留 `uncertain`，不要猜测。
+
+每条候选至少保留：入口上下文、父路径、用户可见名称、触发方式、目标/效果、条件、源码位置和证据类型。
+
+### 4. 分析版本阶段与技术约束
+
+完整读取 [technical-analysis.md](references/technical-analysis.md)，逐功能补充：
+
+- `release_stage`：`mvp|core|full|uncertain`，并说明基于用户价值闭环的判定理由；
+- 每个仓实现实际使用的 `technology_stack`，混合实现保留多个技术栈；
+- `external_dependencies`：是否依赖第三方 SDK 或 SO、开闭源属性、用途、链接方式和证据；
+- `android_permissions`：是否依赖 Android 权限、权限名、申请类型、触发条件、用途和证据。
+
+依赖或权限标记为 `none` 时必须记录实际负向复核；无法排除传递依赖、动态加载、系统版本差异或插件注入时使用 `uncertain`。
+
+### 5. 投影为一至四级功能树
+
+完整读取 [hierarchy-rules.md](references/hierarchy-rules.md)，按用户路径而不是代码结构定级。关键规则：
+
+- 一级是正式入口上下文中的主要可见业务表面或首个流程页面。
+- 点击一级中的入口后出现的页面、菜单、弹窗或操作为二级，依次类推。
+- 打开“更多”“筛选”“设置”之类的真实容器会占一级；纯代码容器不占级。
+- 超过四级时，在保持用户语义的前提下折叠连续的导航壳，并在 `notes` 中记录原始完整路径。
+- 并列 tab、drawer 目标、列表条目和同屏快捷操作按实际入口分别建路径。
+
+### 6. 跨仓语义对齐
+
+先独立完成每个仓的功能树，再对齐。不要以某一仓的目录或命名强行套另一仓。
+
+- 名称不同但触发、目标、前置条件和效果等价：合并为同一路径。
+- 页面相似但只实现 UI/mock、缺少业务效果：标记 `mock` 或 `partial`。
+- 代码存在但入口不可达：标记 `unreachable`，不要写“有”。
+- 仅一仓存在：另一仓在完成负向复核后标记 `absent`；证据不足则 `uncertain`。
+- 产品新增功能可单独保留，不自动视为迁移错误。
+
+### 7. 写入规范化清单
+
+唯一交付物是 `inventory.json`，不得生成 `feature-inventory.md`、`feature-inventory.csv`、XLSX、分析报告或其他派生清单。完整读取 [inventory-schema.md](references/inventory-schema.md) 后按下列格式写入；详细字段枚举、证据约束和最小示例以该规范为准：
+
+```json
+{
+  "schema_version": "1.2",
+  "title": "应用功能清单",
+  "language": "zh-CN",
+  "max_depth": 4,
+  "repositories": [
+    {
+      "id": "android",
+      "label": "Android",
+      "path": "/absolute/repository/path",
+      "platform": "android",
+      "revision": "git commit or working-tree"
+    }
+  ],
+  "features": [
+    {
+      "entry_context": "returning_user",
+      "path": ["一级功能", "二级功能"],
+      "kind": "action",
+      "trigger": "用户如何触发",
+      "effect": "用户看到的结果",
+      "conditions": [],
+      "should_develop": true,
+      "release_stage": "mvp",
+      "release_rationale": "版本阶段判定依据",
+      "capability_key": "optional.stable_key",
+      "notes": "",
+      "implementations": {
+        "android": {
+          "status": "uncertain",
+          "confidence": "low",
+          "technology_stack": [],
+          "technology_evidence": [],
+          "external_dependencies": {
+            "status": "uncertain",
+            "items": [],
+            "negative_searches": [],
+            "notes": ""
+          },
+          "android_permissions": {
+            "status": "uncertain",
+            "items": [],
+            "negative_searches": [],
+            "notes": ""
+          },
+          "evidence": [],
+          "negative_searches": [],
+          "notes": ""
+        }
+      }
+    }
+  ],
+  "open_questions": [],
+  "excluded_candidates": []
+}
+```
+
+`features[].should_develop` 是必填布尔值：`true` 表示纳入 HarmonyOS 开发范围，`false` 表示明确不开发。它不表示任一源码仓是否已经实现；已有实现仍由 `implementations.<repo_id>.status` 表达。源码中发现且属于正式产品范围的功能默认写 `true`；只有用户明确排除时才能写 `false`，并在 `notes` 记录排除依据。不得根据实现难度、平台差异、依赖缺失或模型判断擅自写 `false`。
+
+每条实现状态都必须带置信度和源码证据；`absent` 必须带负向检索说明。
+
+运行校验：
+
+```bash
+python3 <skill-dir>/scripts/validate_inventory.py \
+  /abs/path/to/inventory.json
+```
+
+先修复所有 error，再逐条复核 warning。高置信“已实现”若缺少可见性与交互/路由两类独立证据，必须降级或补证据。
+
+## 最终质量门槛
+
+- 所有路径都从明确入口上下文可达，或被标记为 `unreachable/uncertain`。
+- 每个层级名称都是用户语言，不是裸路由名、类名或资源键。
+- `implemented/partial/mock` 至少有交互或路由证据；高置信项同时有可见性证据。
+- 不把测试、文档、注释或未使用字符串当作唯一实现证据。
+- 每个 `absent` 都有负向检索说明；无法排除动态行为时使用 `uncertain`。
+- 比较模式保留各仓独立状态、置信度、证据和备注。
+- 四级之外的折叠、同义词归并和产品差异都有审计说明。
+- 每条功能都有布尔型 `should_develop`；未获用户明确排除的正式功能不得标记为 `false`。
+- 每条功能都有版本阶段和判定理由；缺少产品定位时使用 `uncertain`。
+- 每个已实现/部分实现/mock 的仓实现都有功能级技术栈证据。
+- SDK/SO 依赖明确记录是否存在、开闭源属性与用途；`none` 有负向复核，无法证明开闭源时使用 `unknown`。
+- Android 实现逐功能说明权限依赖；Manifest 声明与运行时申请/受保护 API 调用没有混为一谈。
+
+
+功能清单是独立分析产物，只用 `should_develop` 记录用户明确的开发范围选择。开发轮次、执行进度和验收状态仍由调用方维护；本 Skill 不创建执行计划或运行状态。返回 `inventory.json` 路径、来源、未决项及需要补充的信息即可。

package/skills/d2h-app-solution/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "应用功能清单提取"
+  short_description: "生成带开发标记、技术分析和源码证据的 inventory.json"
+  default_prompt: "使用 $d2h-app-solution 分析这些应用代码仓，仅生成 inventory.json；清单需包含是否开发标记、版本阶段、技术栈、SDK/SO 依赖、Android 权限、实现状态、置信度和源码证据。"

package/skills/d2h-app-solution/references/framework-evidence.md

@@ -0,0 +1,117 @@
+# 多平台证据路由
+
+## 目录
+
+1. 通用顺序
+2. Android
+3. HarmonyOS
+4. iOS
+5. Flutter
+6. React Native 与 Web
+7. 技术、依赖与权限证据
+8. 负向复核
+
+## 1. 通用顺序
+
+按“入口 → 路由声明 → 可见控件 → 交互回调 → 目标/效果 → 条件”追踪。优先读取发布源码与资源，再用 UI 测试、用户文档和截图补强。
+
+## 2. Android
+
+优先证据：
+
+- `AndroidManifest.xml` 的 MAIN/LAUNCHER Activity、activity alias、deep link。
+- Navigation XML 的 destination/action/deepLink。
+- Compose `NavHost`、`composable`、`navigation`、`navigate`。
+- `startActivity`、Fragment transaction、NavController 调用。
+- `res/menu`、preferences XML、layout 的可点击控件与 `android:title/text/contentDescription`。
+- `onClick`、`clickable`、`setOnClickListener`、菜单选择分发。
+- `res/values/strings.xml` 用于解析资源键，不能单独证明功能。
+
+注意 flavor、manifest merge、`android:enabled/visible`、feature flag、账号态和 legacy/compose 双实现。
+
+## 3. HarmonyOS
+
+优先证据：
+
+- `module.json5` 中 abilities、skills、srcEntry 与 exported。
+- `resources/base/profile/main_pages.json` 与 `windowStage.loadContent`。
+- `Navigation`、`NavDestination`、`NavPathStack.pushPath*`、`router.pushUrl/replaceUrl`。
+- `Tabs`、`TabContent`、`.onClick/.onChange/.onSubmit`。
+- `resources/*/element/string.json` 用于解析 `$r('app.string.*')`。
+- Want、系统 picker、分享、设置页等外部能力调用。
+
+注意 ArkTS 移植仓常保留大量未接线的 Activity/Fragment 同名类；只有正式 `@Entry`/Ability 页面和实际组件引用能证明 UI 可达。preview、catalog、mock 页面需单独标记。
+
+## 4. iOS
+
+优先证据：
+
+- `@main` App、`WindowGroup`、App/SceneDelegate、Info.plist scene 与 URL types。
+- SwiftUI `NavigationStack`、`NavigationLink`、`navigationDestination`、`sheet/fullScreenCover`、Button。
+- UIKit storyboard segue、`present`、`pushViewController`、target-action。
+- `Localizable.strings/.xcstrings` 与 accessibility label。
+
+注意 Storyboard/XIB 连接、Coordinator、URL scheme 和编译 target membership。
+
+## 5. Flutter
+
+优先证据：
+
+- `MaterialApp/CupertinoApp` 的 home、routes、onGenerateRoute。
+- `Navigator.push*`、GoRouter、AutoRoute、RouterDelegate。
+- `onTap/onPressed/onSelected/onSubmitted`、BottomNavigationBar、TabBar、Drawer。
+- ARB、本地化生成调用与 widget tests。
+
+注意生成路由、条件 import、flavor entrypoint 和 dead widget。
+
+## 6. React Native 与 Web
+
+优先证据：
+
+- NavigationContainer 和 stack/tab/drawer route 声明。
+- `navigation.navigate`、router push/replace、Link。
+- Pressable/Touchable/Button 与 `onPress/onClick/onSubmit`。
+- 路由文件系统、菜单配置、国际化资源和 feature flag。
+
+注意仅注册未挂载的 screen、Storybook、demo route、开发菜单和服务端下发导航。
+
+## 7. 技术、依赖与权限证据
+
+Android：
+
+- 技术栈：功能页面和效果调用所在的 `.kt/.java/.cpp` 文件、Compose/View/XML、JNI 桥接。
+- SDK：Gradle/version catalog、AAR/JAR、插件声明，以及对应 import/初始化/调用。
+- SO：`jniLibs/**/*.so`、CMake/ndkBuild、JNI 方法、`System.loadLibrary`/`ReLinker`。
+- 权限：Manifest `uses-permission`、Activity Result permission contract、`requestPermissions`、权限检查和受保护 API。
+
+iOS：
+
+- 技术栈：Swift/Objective-C/Objective-C++ 页面、Coordinator 与桥接头。
+- SDK/二进制：SPM、Podfile/Podfile.lock、framework/XCFramework、link phases、动态加载。
+- 权限/能力：Info.plist usage description、entitlements 与实际 API 调用；不写入 `android_permissions`，使用 `not-applicable`。
+
+Flutter / React Native：
+
+- 技术栈：Dart 或 JS/TS 页面加原生插件/桥接层；不能只标跨端框架而遗漏功能实际依赖的 Kotlin/Java/Swift/Objective-C/CPP 层。
+- SDK：`pubspec.yaml`、`package.json`、lockfile、plugin registration 与原生包管理配置。
+- 权限：Android 侧继续沿 Manifest、运行时申请和插件原生实现追踪到具体功能。
+
+Web/H5：
+
+- 技术栈：路由页面、组件和网络/浏览器 API 调用；原生 WebView 容器与 H5 内容分别记录。
+- SDK：包管理清单只能证明项目依赖；需结合 import/调用证明功能使用。
+- Android 权限通常 `not-applicable`；若 H5 在 Android WebView 中通过 JS bridge 调用原生受权限能力，则记录在承载该功能的 Android 实现中。
+
+## 8. 负向复核
+
+判定 `absent` 前至少完成：
+
+1. 用目标语言、英文、同义词、资源键和常见动词检索。
+2. 检索相关路由、页面类、菜单、设置项和回调。
+3. 从正式入口反向确认没有动态注册或条件分支。
+4. 检查生成代码、配置文件、feature flag、依赖模块与深链。
+5. 检查是否以图标/无障碍标签而非文本呈现。
+6. 记录检索项到 `negative_searches`；仍不能排除时标记 `uncertain`。
+
+SDK/SO 与权限的 `none` 还需分别完成 [technical-analysis.md](technical-analysis.md) 规定的构建声明、加载/调用链、Manifest 和运行时申请/API 复核。
+

package/skills/d2h-app-solution/references/hierarchy-rules.md

@@ -0,0 +1,88 @@
+# 功能树层级规则
+
+## 目录
+
+1. 定级基准
+2. 节点类型
+3. 容器与点击深度
+4. 多入口与多状态
+5. 四级折叠
+6. 命名与去重
+7. 常见误判
+
+## 1. 定级基准
+
+层级表达用户从正式入口看到并继续操作的路径，不表达代码包、技术模块、数据模型或调用栈。
+
+- 一级：入口上下文中的主要业务表面、可见区域或首个流程页面，例如“邮件列表”“首页顶部栏”“首次启动欢迎页”。
+- 二级：用户从一级中的控件、条目或动作打开/触发的目标。
+- 三级：从二级继续操作得到的目标。
+- 四级：从三级继续操作得到的目标。
+
+路径可以在任意层结束。一个行为若在同屏完成，也仍可作为父表面下的子功能，例如“邮件列表 > 下拉刷新”。
+
+## 2. 节点类型
+
+使用以下 `kind`：
+
+- `screen`：整页或主要页面。
+- `surface`：toolbar、drawer、主列表、详情区等主要业务表面。
+- `tab`：用户可切换的 tab。
+- `menu`：用户必须先打开的菜单、筛选器或操作面板。
+- `dialog`：对话框、sheet、popover。
+- `action`：删除、发送、刷新、收藏、分享等操作。
+- `setting`：可见设置项。
+- `flow-step`：注册、添加账号、支付等向导步骤。
+- `external`：打开浏览器、系统设置、分享面板等外部目标。
+
+## 3. 容器与点击深度
+
+- 真实可见或可打开的业务容器占一级：`邮件详情 > 更多操作 > 显示标头`。
+- 纯技术容器不占级：Activity、Fragment、Composable、ViewModel、NavHost、Ability。
+- toolbar 上直接可点的“删除”不需要虚构“toolbar 操作”父级。
+- overflow、context menu、drawer、筛选 sheet 若必须先打开，则容器本身占一级。
+- 自动跳转的加载页、路由代理和透明 Activity 默认不占级；若用户能看到并理解为流程步骤，则保留。
+- tab 本身是用户可见入口时作为节点；tab 内默认可见内容通常放在 tab 下一级。
+- 列表中同类数据条目只抽象一次，例如“邮件条目”，不要把每条样例数据列成功能。
+
+## 4. 多入口与多状态
+
+使用 `entry_context` 区分：
+
+- `first_launch`：首次启动/引导。
+- `returning_user`：回访用户正常入口。
+- `signed_out` / `signed_in`：未登录/已登录。
+- `empty_state` / `populated_state`：无数据/有数据。
+- `deep_link`：外部链接入口。
+- 项目特有上下文可用稳定 snake_case 名称。
+
+同一功能从不同父入口进入时保留不同路径，例如“列表 > 单项更多 > 删除”和“详情 > 删除”。仅在最终清单明确要求能力去重时，才增加共享 `capability_key`，但不删除入口路径。
+
+## 5. 四级折叠
+
+真实路径超过四级时：
+
+1. 保留用户能说出名称的业务节点。
+2. 优先折叠无独立业务语义的连续导航壳、重复列表容器和纯选择中间页。
+3. 不折叠会改变前置条件、触发方式或操作结果的节点。
+4. 在 `notes` 写入 `完整路径：A > B > C > D > E` 和折叠理由。
+5. 无法无损折叠时，保留前四级并把余下步骤写入 `effect`，同时降低置信度或加入待确认项。
+
+## 6. 命名与去重
+
+- 优先使用目标语言的运行时可见文案。
+- 图标无文字时使用 content description、accessibility label、测试语义标签或紧邻设计语义；仍不明确时用“图标动作（待确认）”。
+- 资源键、路由常量和类名只帮助定位，不直接作为最终名称。
+- 同一路径下同名但条件或结果不同的动作应区分，例如“删除（移入回收站）”与“永久删除”。
+- 跨仓对齐需同时比较入口、触发、目标、条件和效果，不能只做字符串相似度匹配。
+
+## 7. 常见误判
+
+- 字符串资源中存在“导出”不等于存在导出入口。
+- Manifest 注册 Activity 不等于用户可达。
+- 页面类存在不等于发布变体包含该页面。
+- preview、catalog、sample 和截图展示不等于正式功能。
+- 单元测试覆盖服务方法不等于 UI 功能已接线。
+- TODO、注释描述和 mock toast 不等于业务效果已实现。
+- 权限、通知渠道、后台服务属于支撑能力；只有存在用户入口或可感知行为时才进入主清单。
+