@harmonyos-arkts/d2h 0.1.20 → 0.1.21

package/skills/d2h-app-solution/references/inventory-schema.md

@@ -0,0 +1,305 @@
+# Inventory JSON 规范
+
+## 目录
+
+1. 顶层结构
+2. 功能路径
+3. 实现状态
+4. 版本阶段
+5. 技术栈、SDK/SO 与 Android 权限
+6. 证据
+7. 置信度
+8. 最小示例
+
+## 1. 顶层结构
+
+```json
+{
+  "schema_version": "1.2",
+  "title": "应用功能清单",
+  "language": "zh-CN",
+  "max_depth": 4,
+  "repositories": [],
+  "features": [],
+  "open_questions": [],
+  "excluded_candidates": []
+}
+```
+
+`repositories[]`：
+
+```json
+{
+  "id": "android",
+  "label": "Android",
+  "path": "/absolute/repository/path",
+  "platform": "android",
+  "revision": "git commit or working-tree"
+}
+```
+
+`id` 使用稳定 snake_case；`path` 必须是校验时可读的仓库绝对路径。
+
+## 2. 功能路径
+
+`features[]`：
+
+```json
+{
+  "entry_context": "returning_user",
+  "path": ["邮件详情", "更多操作", "显示标头"],
+  "kind": "action",
+  "trigger": "点击更多操作后选择显示标头",
+  "effect": "打开原始邮件标头页面",
+  "conditions": ["已打开一封邮件"],
+  "should_develop": true,
+  "release_stage": "core",
+  "release_rationale": "属于常用诊断能力，但不阻断邮件收发最小闭环",
+  "capability_key": "message.show_headers",
+  "notes": "",
+  "implementations": {}
+}
+```
+
+约束：
+
+- `path` 长度为 1–4，不能有空字符串。
+- 最后一个元素是当前功能名称；前面的元素是用户路径父级。
+- `entry_context` 必填。
+- `kind` 取 `screen|surface|tab|menu|dialog|action|setting|flow-step|external`。
+- `trigger` 描述用户操作；纯展示节点可写“进入页面后可见”。
+- `effect` 描述目标页面、状态变化或外部行为。
+- `should_develop` 为必填布尔值：`true` 表示纳入 HarmonyOS 开发范围，`false` 表示用户明确决定不开发。它与各仓已有实现状态无关；后者由 `implementations.<repo_id>.status` 表达。
+- 正式产品范围内的源码功能默认使用 `true`。只有用户明确排除时才能使用 `false`，并在 `notes` 中记录排除依据；不能因实现困难、平台差异、依赖缺失或静态证据不足擅自排除。
+- `release_stage` 取 `mvp|core|full|uncertain`；表示产品能力分层，不等同于实际历史版本。
+- `release_rationale` 必填，说明其对最小用户价值闭环、主流使用或扩展体验的作用。
+- `capability_key` 可选，仅用于跨入口能力去重和跨仓对齐。
+
+## 3. 实现状态
+
+`implementations` 必须包含每个仓 ID：
+
+```json
+{
+  "android": {
+    "status": "implemented",
+    "confidence": "high",
+    "technology_stack": ["kotlin"],
+    "technology_evidence": [],
+    "external_dependencies": {
+      "status": "none",
+      "items": [],
+      "negative_searches": ["Gradle/AAR 依赖声明", "import、SDK 调用与 native 加载链"],
+      "notes": ""
+    },
+    "android_permissions": {
+      "status": "none",
+      "items": [],
+      "negative_searches": ["AndroidManifest 权限声明", "运行时申请、权限检查与受保护 API 调用"],
+      "notes": ""
+    },
+    "evidence": [],
+    "negative_searches": [],
+    "notes": ""
+  }
+}
+```
+
+状态：
+
+- `implemented`：正式入口可达，交互和主要效果已接线。
+- `partial`：只实现部分路径、条件或效果。
+- `mock`：UI/路由存在，但使用静态演示数据、空回调、占位页或仅 toast 模拟效果。
+- `unreachable`：代码存在，但没有从分析范围内正式入口到达的路径。
+- `absent`：完成系统性负向复核后确认未实现。
+- `uncertain`：动态行为、生成代码、配置或证据缺口导致无法确认。
+- `not-applicable`：该功能对该仓/产品变体不适用。
+
+`absent` 必须填写 `negative_searches`，记录实际检索的同义词、资源键、路由、类名和入口链，不接受“未发现”这类空泛说明。
+
+## 4. 版本阶段
+
+- `mvp`：完成主要用户价值闭环不可缺少。
+- `core`：不阻断最小闭环，但显著影响常用流程、信任、留存、效率或异常处理。
+- `full`：扩展体验、生态、运营、个性化或低频辅助能力。
+- `uncertain`：缺少产品定位或路线图，无法可靠判定。
+
+版本阶段属于对齐后的功能路径，同一功能在不同仓共享。不得用代码量或实现难度代替产品价值判断。
+
+## 5. 技术栈、SDK/SO 与 Android 权限
+
+`technology_stack` 是非空去重数组，允许：`java|kotlin|cpp|react-native|flutter|h5|swift|objective-c|arkts|javascript|typescript|other|unknown`。`implemented|partial|mock|unreachable` 必须填写；`absent|not-applicable` 可为空。
+
+`technology_evidence` 使用与普通证据相同的引用结构，类型通常为 `tech_stack`、`route_declaration`、`ui_interaction` 或 `effect`。仅凭仓库中存在某种语言文件，不足以把该语言归到每个功能。
+
+`external_dependencies`：
+
+依赖信息只保留为以下结构化 JSON 字段，不另外拼接成人类可读展示字符串。使用 `unknown` 时必须在同级 `notes` 中写明具体待核实字段和仓库内证据缺口。
+
+```json
+{
+  "status": "present",
+  "items": [
+    {
+      "name": "示例支付 SDK",
+      "kind": "sdk",
+      "provenance": "closed-source",
+      "linkage": "direct",
+      "required": true,
+      "purpose": "发起支付并接收结果",
+      "evidence": []
+    }
+  ],
+  "negative_searches": [],
+  "notes": ""
+}
+```
+
+- `status`：`present|none|uncertain|not-applicable`。
+- `kind`：`sdk|so`。
+- `provenance`：`open-source|closed-source|mixed|unknown`。
+- `linkage`：`direct|transitive|dynamic|unknown`。
+- `none` 至少记录两项负向复核；`present` 至少有一个带证据的 item。
+- `present` 的 item 必须同时给出依赖声明/本地库证据与功能调用/桥接/加载证据；只有构建声明不能证明功能使用它。
+- 已存在的功能实现不能使用 `not-applicable`；确认不依赖时使用 `none`，无法静态闭合时使用 `uncertain`。
+
+`android_permissions`：
+
+```json
+{
+  "status": "present",
+  "items": [
+    {
+      "name": "android.permission.CAMERA",
+      "requirement": "runtime",
+      "required_when": "用户选择拍照上传凭证",
+      "purpose": "调用相机采集图片",
+      "evidence": []
+    }
+  ],
+  "negative_searches": [],
+  "notes": ""
+}
+```
+
+- `status`：`present|none|uncertain|not-applicable`。
+- `requirement`：`install-time|runtime|special|conditional|unknown`。
+- Android 仓的 `none` 至少记录 Manifest 与运行时申请/API 调用两类负向复核。
+- 非 Android 仓通常使用 `not-applicable`；Android 功能未实现时也可使用 `not-applicable`。
+- `present` 的 item 必须包含运行时申请/检查或受保护 API 调用证据；只有 Manifest 声明不能证明该功能依赖权限。
+
+## 6. 证据
+
+`evidence[]`：
+
+```json
+{
+  "type": "ui_label",
+  "path": "app/src/main/res/menu/message.xml",
+  "line_start": 42,
+  "line_end": 45,
+  "symbol": "show_headers",
+  "summary": "更多菜单声明“显示标头”入口"
+}
+```
+
+允许类型：
+
+- `entry`：launcher、ability、正式页面清单或启动加载。
+- `route_declaration`：路由或目标声明。
+- `navigation_call`：实际跳转调用。
+- `ui_label`：运行时可见文案或无障碍标签。
+- `ui_interaction`：点击、手势、选择、提交等回调。
+- `menu_item`：菜单或设置条目。
+- `visibility_condition`：显示/启用条件。
+- `effect`：业务调用、状态更新、持久化或外部行为。
+- `tech_stack`：实现语言、跨端框架、WebView/H5 承载或桥接证据。
+- `dependency_declaration`：构建系统中的 SDK/AAR/JAR/package/framework 依赖声明。
+- `native_library`：SO、JNI、CMake/ndkBuild、`System.loadLibrary`、framework/XCFramework 或动态加载证据。
+- `permission_declaration`：Manifest、Info.plist 或平台配置中的权限/能力声明。
+- `permission_request`：运行时权限申请、检查或受保护 API 调用。
+- `test` / `doc`：仅作补强的测试或文档证据。
+
+路径必须相对对应仓库根目录，行号从 1 开始。引用尽量控制在最小连续范围。
+
+## 7. 置信度
+
+- `high`：正式入口可达；名称有可见性证据；触发与目标/效果有独立证据；不存在未解释的 mock/flag 分支。
+- `medium`：主链成立，但有一项依赖合理推断、动态配置或间接调用。
+- `low`：只有部分静态线索，或存在明显冲突；通常配合 `uncertain/partial/unreachable`。
+
+字符串、测试、文档或注释单独出现时不得给 `high`。
+
+## 8. 最小示例
+
+```json
+{
+  "schema_version": "1.2",
+  "title": "示例功能清单",
+  "language": "zh-CN",
+  "max_depth": 4,
+  "repositories": [
+    {
+      "id": "app",
+      "label": "应用仓",
+      "path": "/abs/app",
+      "platform": "android",
+      "revision": "working-tree"
+    }
+  ],
+  "features": [
+    {
+      "entry_context": "returning_user",
+      "path": ["首页", "搜索"],
+      "kind": "action",
+      "trigger": "点击搜索图标",
+      "effect": "打开搜索界面",
+      "conditions": [],
+      "should_develop": true,
+      "release_stage": "core",
+      "release_rationale": "搜索显著提升主流商品发现效率，但不阻断基础浏览闭环",
+      "notes": "",
+      "implementations": {
+        "app": {
+          "status": "implemented",
+          "confidence": "medium",
+          "technology_stack": ["kotlin"],
+          "technology_evidence": [
+            {
+              "type": "tech_stack",
+              "path": "src/Home.kt",
+              "line_start": 1,
+              "summary": "Kotlin Compose 页面实现"
+            }
+          ],
+          "external_dependencies": {
+            "status": "none",
+            "items": [],
+            "negative_searches": ["Gradle/AAR 依赖声明", "import、SDK 调用与 native 加载链"],
+            "notes": ""
+          },
+          "android_permissions": {
+            "status": "none",
+            "items": [],
+            "negative_searches": ["AndroidManifest 权限声明", "运行时申请、权限检查与受保护 API 调用"],
+            "notes": ""
+          },
+          "evidence": [
+            {
+              "type": "ui_interaction",
+              "path": "src/Home.kt",
+              "line_start": 10,
+              "summary": "搜索按钮回调"
+            }
+          ],
+          "negative_searches": [],
+          "notes": "需补充目标页面可见文案证据"
+        }
+      }
+    }
+  ],
+  "open_questions": [],
+  "excluded_candidates": []
+}
+```
+

package/skills/d2h-app-solution/references/technical-analysis.md

@@ -0,0 +1,101 @@
+# 版本阶段、技术栈、SDK/SO 与权限分析
+
+## 目录
+
+1. 版本阶段
+2. 技术栈
+3. SDK 与 SO 依赖
+4. Android 权限
+5. 证据与置信边界
+
+## 1. 版本阶段
+
+`release_stage` 表示功能在产品能力分层中的建议归属，不等同于 Git 历史中的真实首发版本。除非版本文档、标签或提交记录明确证明，否则不要声称某功能“在某版本首次上线”。
+
+- `mvp`：形成产品最小可用闭环不可缺少的入口、操作或结果。移除后，目标用户无法完成主要价值路径。例如电商应用的商品浏览、购物车、下单和最基本登录。
+- `core`：不阻断最小闭环，但显著影响主流使用、信任、留存、效率或常见异常处理。例如搜索、地址管理、订单状态、退款和核心设置。
+- `full`：扩展体验、生态入口、运营能力、个性化、低频辅助功能或高级能力。例如贡献者页面、主题颜色、社区入口和非必要第三方登录。
+- `uncertain`：缺少产品定位、目标用户或路线图，无法可靠归类。
+
+每条功能填写 `release_stage` 和 `release_rationale`。判定以用户价值链为依据，不按代码复杂度、文件数量或开发成本分类。跨仓对齐后的同一功能共享版本阶段；平台特有功能可独立分类。
+
+## 2. 技术栈
+
+技术栈记录功能的实际实现语言或运行表面，而不是整个仓库使用过的所有语言。允许值：
+
+- `java`
+- `kotlin`
+- `cpp`
+- `react-native`
+- `flutter`
+- `h5`
+- `swift`
+- `objective-c`
+- `arkts`
+- `javascript`
+- `typescript`
+- `other`
+- `unknown`
+
+逐功能沿入口、页面、桥接层和主要效果调用记录 `technology_stack`。混合实现保留多个值，例如 `kotlin + cpp`、`react-native + kotlin`、`kotlin + h5`。WebView 只有在该功能的主要交互内容由 Web 页面承载时才标记 `h5`；仅打开一个外部网页时，不把原生入口本身改判为 H5。
+
+`technology_evidence` 优先引用实现文件、构建配置、桥接注册或 WebView 加载位置。仅凭仓库存在某种文件后缀，不能把该语言归到所有功能。
+
+## 3. SDK 与 SO 依赖
+
+使用 `external_dependencies.status` 表示功能是否依赖第三方 SDK 或原生动态库：
+
+- `present`：已证明存在直接或传递依赖，且功能路径会使用它。
+- `none`：完成构建依赖、导入/调用、JNI/动态加载和本地库目录复核后，未发现该功能依赖。
+- `uncertain`：依赖由插件、远端配置、动态加载、闭源 AAR/XCFramework 或构建产物引入，无法确认。
+- `not-applicable`：该实现不存在或该项不适用。
+
+`items[]` 字段：
+
+- `name`：可识别的 SDK、包、AAR、framework 或 SO 名称。
+- `kind`：`sdk` 或 `so`。
+- `provenance`：`open-source|closed-source|mixed|unknown`。只有许可证、官方说明或仓库源码能证明开闭源属性；不要根据厂商名猜测。
+- `linkage`：`direct|transitive|dynamic|unknown`。
+- `required`：该功能主路径是否必须依赖此项。
+- `purpose`：该依赖在功能中的作用。
+- `evidence`：构建声明、import/调用、桥接、`System.loadLibrary`、`dlopen`、打包配置或实际库文件证据。
+
+`present` 必须同时建立“依赖被引入”和“功能确实调用/桥接/加载它”两段证据。已存在的功能实现不得使用 `not-applicable`；确认无依赖用 `none`，无法静态闭合用 `uncertain`。
+
+在 `inventory.json` 中分别写入依赖类型、开闭源属性、主流程必要性、链接方式和用途，不得压缩为依赖字段顺序解释的单个字符串。字段为 `unknown` 时，在同级 `notes` 中写明待核实内容和仓库内证据缺口。
+
+Android 优先检查 Gradle version catalog、`dependencies`、AAR/JAR、`jniLibs`、CMake/ndkBuild、JNI 注册与 `System.loadLibrary`。iOS 检查 SPM、CocoaPods、XCFramework/framework 与链接配置。RN/Flutter 同时检查 JS/Dart 包和原生插件层。
+
+`none` 必须填写 `negative_searches`，至少记录依赖声明与调用/加载链两类复核；无法排除传递或动态依赖时使用 `uncertain`。
+
+## 4. Android 权限
+
+使用 `android_permissions.status`：
+
+- `present`：功能会读取受权限保护的资源或调用需要权限的 API。
+- `none`：复核 Manifest、运行时申请、相关 API 与库调用后，确认无需 Android 权限。
+- `uncertain`：权限可能由依赖库、系统 picker、不同 API 级别或动态模块引入。
+- `not-applicable`：非 Android 实现或功能未实现。
+
+`items[]` 字段：
+
+- `name`：完整权限名，例如 `android.permission.CAMERA`。
+- `requirement`：`install-time|runtime|special|conditional|unknown`。
+- `required_when`：触发权限的用户条件或 Android 版本条件。
+- `purpose`：权限在功能中的用途。
+- `evidence`：Manifest 声明、运行时申请、权限检查和受保护 API 调用。
+
+`present` 至少要有运行时申请/检查或受保护 API 调用证据；只有 Manifest 声明时不能直接判为该功能依赖权限。
+
+Manifest 中声明权限不等于每个功能都依赖该权限。必须把权限申请或受保护 API 调用关联到具体用户路径。使用系统 Photo Picker、SAF、分享面板等不要求应用权限的系统能力时，按实际 API 判定，不要因为“选图/选文件”字样自动标记存储权限。
+
+`none` 必须填写 `negative_searches`，至少覆盖 Manifest/配置与运行时申请/API 调用；仅有 Manifest 声明而找不到功能调用链时标记 `uncertain`。
+
+## 5. 证据与置信边界
+
+- 技术属性证据与功能实现证据分开记录，但都必须使用仓库相对路径和精确行号。
+- 构建文件只能证明依赖被打包，不能单独证明某功能实际使用该依赖；还需 import、调用或桥接证据。
+- 二进制文件存在只能证明可能被打包。无法追到加载与功能调用时使用 `uncertain`。
+- 许可证文件可证明开源属性；营销页、包名印象或厂商声誉不能。
+- 权限声明只能证明应用请求过权限；功能级依赖还需权限检查、请求或受保护 API 调用。
+- 动态特性、反射、服务端下发、Web 容器和插件体系无法静态闭合时，明确记录待确认原因。