@harmonyos-arkts/d2h 0.0.0-stage → 0.1.1

package/skills/appgraph-rule-audit/schemas/rule-opportunities.schema.json

@@ -0,0 +1,125 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://harmonyos-ai.dev/skills/appgraph-rule-audit/schemas/rule-opportunities.schema.json",
+  "title": "AppGraph rule improvement opportunities",
+  "type": "object",
+  "required": ["schemaVersion", "skillVersion", "source", "summary", "opportunities", "acceptedLimitations", "auditWarnings"],
+  "properties": {
+    "schemaVersion": { "const": "1.0.0" },
+    "skillVersion": { "const": "1.0.0" },
+    "source": {
+      "type": "object",
+      "required": ["project", "sourceRevision", "factsSha256", "appGraphVersion", "rulePacks"],
+      "properties": {
+        "project": { "type": "string", "minLength": 1 },
+        "sourceRevision": { "type": ["string", "null"] },
+        "factsSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "appGraphVersion": { "type": ["string", "null"] },
+        "rulePacks": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }
+      },
+      "additionalProperties": false
+    },
+    "summary": {
+      "type": "object",
+      "required": ["conclusion", "pages", "navigation", "hosts", "unresolved", "coverageWarnings"],
+      "properties": {
+        "conclusion": { "type": "string" },
+        "pages": { "type": "integer", "minimum": 0 },
+        "navigation": { "type": "integer", "minimum": 0 },
+        "hosts": { "type": "integer", "minimum": 0 },
+        "unresolved": { "type": "integer", "minimum": 0 },
+        "coverageWarnings": { "type": "integer", "minimum": 0 }
+      },
+      "additionalProperties": false
+    },
+    "opportunities": { "type": "array", "maxItems": 20, "items": { "$ref": "#/$defs/opportunity" } },
+    "acceptedLimitations": { "type": "array", "items": { "$ref": "#/$defs/limitation" } },
+    "auditWarnings": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+  },
+  "$defs": {
+    "level": { "enum": ["high", "medium", "low"] },
+    "evidence": {
+      "type": "object",
+      "required": ["role", "file", "line", "symbol", "entityRefs", "ruleIds", "observation"],
+      "properties": {
+        "role": { "enum": ["positive", "negative", "boundary", "ambiguous"] },
+        "file": { "type": "string", "minLength": 1 },
+        "line": { "type": ["integer", "null"], "minimum": 1 },
+        "symbol": { "type": ["string", "null"] },
+        "entityRefs": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+        "ruleIds": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+        "observation": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
+    "ratedReason": {
+      "type": "object",
+      "required": ["level", "reason"],
+      "properties": { "level": { "$ref": "#/$defs/level" }, "reason": { "type": "string", "minLength": 1 } },
+      "additionalProperties": false
+    },
+    "metricDelta": {
+      "type": "object",
+      "required": ["pages", "navigation", "hosts", "unresolved", "falsePositives"],
+      "properties": {
+        "pages": { "enum": ["increase", "decrease", "unchanged", "unknown"] },
+        "navigation": { "enum": ["increase", "decrease", "unchanged", "unknown"] },
+        "hosts": { "enum": ["increase", "decrease", "unchanged", "unknown"] },
+        "unresolved": { "enum": ["increase", "decrease", "unchanged", "unknown"] },
+        "falsePositives": { "enum": ["increase", "decrease", "unchanged", "unknown"] }
+      },
+      "additionalProperties": false
+    },
+    "opportunity": {
+      "type": "object",
+      "required": ["id", "priority", "category", "scope", "title", "frameworkIdentity", "observation", "rootCause", "expectedBehavior", "affectedEntities", "evidence", "proposal", "confidence", "generality", "risk", "testPlan", "expectedMetricDelta", "status"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]+$" },
+        "priority": { "enum": ["P0", "P1", "P2"] },
+        "category": { "enum": ["analyzer-gap", "judge-gap", "lift-gap", "spec-gap", "host-gap", "false-positive", "performance"] },
+        "scope": { "enum": ["builtin-generic", "framework-pack", "project-pack"] },
+        "title": { "type": "string", "minLength": 1 },
+        "frameworkIdentity": { "type": "string", "minLength": 1 },
+        "observation": { "type": "string", "minLength": 1 },
+        "rootCause": {
+          "type": "object",
+          "required": ["certainty", "description"],
+          "properties": { "certainty": { "enum": ["confirmed", "hypothesis"] }, "description": { "type": "string", "minLength": 1 } },
+          "additionalProperties": false
+        },
+        "expectedBehavior": { "type": "string", "minLength": 1 },
+        "affectedEntities": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+        "evidence": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/evidence" } },
+        "proposal": {
+          "type": "object",
+          "required": ["layer", "ruleShape", "likelyFilesOrRules"],
+          "properties": {
+            "layer": { "enum": ["Analyzer", "Judge", "Lift", "SPEC", "Host", "Performance"] },
+            "ruleShape": { "type": "string", "minLength": 1 },
+            "likelyFilesOrRules": { "type": "array", "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }
+          },
+          "additionalProperties": false
+        },
+        "confidence": { "$ref": "#/$defs/ratedReason" },
+        "generality": { "$ref": "#/$defs/ratedReason" },
+        "risk": { "$ref": "#/$defs/ratedReason" },
+        "testPlan": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } },
+        "expectedMetricDelta": { "$ref": "#/$defs/metricDelta" },
+        "status": { "const": "proposed" }
+      },
+      "additionalProperties": false
+    },
+    "limitation": {
+      "type": "object",
+      "required": ["id", "reason", "evidence", "requiredEvidence"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]+$" },
+        "reason": { "type": "string", "minLength": 1 },
+        "evidence": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/evidence" } },
+        "requiredEvidence": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}

package/skills/arkts-app-identity/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: arkts-app-identity
+description: >-
+  Android App 身份信息迁移到 HarmonyOS：App 名称（label）、图标（含 layered_image.json 分层自适应图标）、版本号（versionName/versionCode）、包名/厂商（app.json5 的 bundleName/vendor）。当用户需要迁移这些身份字段、或发现 app.json5 中 bundleName/vendor/versionName 仍是模板默认值时触发，从 AndroidManifest.xml / build.gradle 提取原值。即使只说"app 名字不对""图标没迁移""包名还是默认的"也应触发。不处理全量资源迁移（用 android2hmos_resources_convert）、运行时权限或深度链接。
+---
+
+# ArkTS App Identity — 应用身份迁移
+
+## 定位
+
+从当前 Android 源码提取 App 身份信息（名称、图标、版本号、包名），更新现有 HarmonyOS 工程。也可以在缺少 Android 源码时诊断模板值或按调用方提供的权威值修复，但必须标明缺失的源码依据。
+
+根据用户请求和当前工作区确定范围，没有固定 Plan、Stage 或 Task 编号。始终执行同一套身份提取、写入和审计流程，并返回统一领域结果；不识别或修改外部编排状态。
+
+```
+Android 项目 → [本 skill] → app.json5 + string.json + 图标资源
+```
+
+---
+
+## 输入
+
+| 项 | 内容 |
+|----|------|
+| **必须** | 要更新的 HarmonyOS 工程路径；未显式给出时可从当前工作区定位 |
+| **写入时至少一项** | Android 项目根路径，或调用方明确提供的权威身份值；仅诊断模板问题时可以缺省并返回依据缺口 |
+| **可选** | `scope`：`full`（默认）/ `dev-identity`（仅在签名或 AGC 外部依赖未满足时暂缓 bundleName/vendor，并返回未解决项） |
+
+自动定位以下文件：
+- `app/src/main/AndroidManifest.xml`（或扫描 `**/AndroidManifest.xml`）
+- `app/build.gradle` 或 `app/build.gradle.kts`
+- `**/res/values/strings.xml`（或 `common.gradle` 中的 `resValue`）
+- `**/res/mipmap-xxxhdpi/ic_launcher*.png`
+- `**/res/mipmap-anydpi-v26/ic_launcher.xml`（自适应图标定义）
+
+---
+
+## 输出
+
+| 文件 | 内容 | 说明 |
+|------|------|------|
+| `AppScope/app.json5` | bundleName, vendor, versionCode, versionName, icon, label | 更新已有文件，不覆盖无关字段 |
+| `AppScope/resources/base/element/string.json` | app_name 字段 | 更新 app_name 值 |
+| `AppScope/resources/base/media/foreground.png` | 前景图标 | 从 Android xxxhdpi 提取 |
+| `AppScope/resources/base/media/background.png` | 背景图标 | 从 Android xxxhdpi 提取 |
+| `AppScope/resources/base/media/layered_image.json` | 自适应图标配置 | 生成或验证 |
+| `entry/src/main/resources/base/media/startIcon.png` | 启动图标 | 复制 foreground 或 ic_launcher |
+| `entry/src/main/resources/base/element/string.json` | EntryAbility_label | 更新为 app_name |
+| 统一领域结果 | Android 原值、HarmonyOS 填充值、修改文件、未解决项和后续验证请求 | 返回调用方 |
+
+返回结果至少包含：
+
+```json
+{
+  "status": "completed | partial | failed",
+  "changedFiles": [],
+  "sourceFiles": [],
+  "evidence": [],
+  "domainChecks": [{"name": "", "status": "passed | failed", "evidence": []}],
+  "unresolved": [{"kind": "", "blocking": true, "location": "", "reason": ""}],
+  "verificationRequests": [{"type": "build | test | device | review", "scope": [], "reason": ""}],
+  "suggestedRemediation": [],
+  "details": {"mappings": []}
+}
+```
+
+`status` 只表示本 Skill 的领域工作状态，不表示工程已构建、设备已验证或迁移已完成。证据充分时直接完成确定性映射；源码缺失、多 flavor 无法确定或签名/AGC 存在真实分歧时写入 `unresolved`。需要构建、安装启动或设备核对应用身份时写入 `verificationRequests`，不在本 Skill 内决定如何执行。
+
+---
+
+## 核心映射规则
+
+```
+Android                            →  HarmonyOS
+──────────────────────────────────────────────────────
+applicationId                      →  bundleName
+  规则: 默认保持真实 applicationId；不得无证据改写包名前缀
+  例外: HarmonyOS 格式、签名或 AGC 约束不允许时，记录差异和外部依赖
+
+android:label / app_name (string)  →  app.json5 label ($string:app_name)
+  规则: 从 strings.xml 或 build.gradle resValue 解析真实值
+
+versionName                        →  versionName
+  规则: 保持一致
+
+versionCode                        →  versionCode
+  规则: 保持一致
+
+namespace / applicationId 的组织名   →  vendor
+  规则: 提取第二段 (com.example.app → example)
+
+mipmap-xxxhdpi/ic_launcher.png     →  foreground.png
+  规则: 优先 xxxhdpi，降级到 xxhdpi/xhdpi
+
+ic_launcher_background.png         →  background.png
+  规则: 优先 xxxhdpi，如不存在生成纯色 PNG
+
+adaptive-icon XML (ic_launcher.xml) →  layered_image.json
+  格式: { "layered-image": { "background": "$media:background", "foreground": "$media:foreground" } }
+```
+
+---
+
+## 工作流程
+
+### Step 1: 提取 Android 身份信息
+
+```
+1. Read AndroidManifest.xml
+   → 提取 android:label (通常是 @string/app_name)
+   → 提取 android:icon (通常是 @mipmap/ic_launcher)
+
+2. Read build.gradle / build.gradle.kts
+   → 提取 applicationId / namespace
+   → 提取 versionName, versionCode
+   → 检查 buildTypes 中的 resValue (动态 app_name)
+
+3. Read strings.xml (如果 label 是 @string 引用)
+   → 解析 app_name 的实际文本值
+   → 如果 build.gradle 有 resValue 覆盖，使用 release buildType 的值
+```
+
+### Step 2: 提取图标资源
+
+```
+4. 定位图标文件
+   优先级: mipmap-xxxhdpi > mipmap-xxhdpi > mipmap-xhdpi > mipmap-hdpi
+   文件: ic_launcher.png, ic_launcher_foreground.png, ic_launcher_background.png
+
+5. 检查自适应图标
+   文件: mipmap-anydpi-v26/ic_launcher.xml
+   如果存在:
+     → 解析 <foreground android:drawable="@xxx"/>
+     → 解析 <background android:drawable="@xxx"/>
+     → 定位对应的 PNG 文件
+```
+
+### Step 3: 生成 HarmonyOS 配置
+
+```
+6. 更新 AppScope/app.json5
+   仅更新以下字段（保留其他字段不变）:
+   - versionCode: 保持
+   - versionName: 保持
+   - icon: "$media:layered_image" (不变)
+   - label: "$string:app_name" (不变)
+   - bundleName: 从 applicationId 映射   ⚠️ 仅 scope=full
+   - vendor: 从 namespace 提取组织名     ⚠️ 仅 scope=full
+
+   > **scope=dev-identity**：仅当当前环境已有证据表明签名或 AGC 是外部依赖、且修改
+   > bundleName/vendor 会使当前可验证工程失效时使用。跳过的字段必须返回到 `unresolved`，
+   > 保持未完成状态；不得把模板值当作最终迁移结果。app_name、versionName、versionCode
+   > 和图标等不依赖签名的身份字段仍需正常迁移。
+
+7. 更新 AppScope/resources/base/element/string.json
+   更新 app_name 的 value 字段
+
+8. 复制图标文件
+   - foreground.png → AppScope/resources/base/media/foreground.png
+   - background.png → AppScope/resources/base/media/background.png
+   - ic_launcher.png → entry/src/main/resources/base/media/startIcon.png
+   - ic_launcher.png → entry/src/main/resources/base/media/ic_launcher.png (如存在)
+
+9. 生成/验证 layered_image.json
+   确保内容为:
+   {
+     "layered-image": {
+       "background": "$media:background",
+       "foreground": "$media:foreground"
+     }
+   }
+
+10. 更新 entry/src/main/resources/base/element/string.json
+    更新 EntryAbility_label 的 value 与 app_name 一致
+```
+
+### Step 4: 返回映射结果
+
+```
+11. 输出对照表:
+    | 字段 | Android 原值 | HarmonyOS 填充值 |
+    |------|-------------|-----------------|
+    | 应用名称 | AntennaPod | AntennaPod |
+    | 包名 | de.danoeh.antennapod | de.danoeh.antennapod |
+    | 版本号 | 3.11.0 | 3.11.0 |
+    | 版本码 | 3110095 | 3110095 |
+    | 厂商 | danoeh | danoeh |
+    | 图标 | mipmap-xxxhdpi/ic_launcher.png | foreground.png (XXkb) |
+
+    若 bundleName 因格式、签名或 AGC 约束不能直接采用，写入 unresolved；
+    普通可确定映射不询问用户。
+```
+
+---
+
+## 边界情况处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| 多模块项目，icon 在子模块 | 从 AndroidManifest.xml 追踪 icon 引用，跨模块定位 |
+| build.gradle.kts (Kotlin DSL) | 同时支持 Groovy 和 KTS 语法解析 |
+| 无 adaptive-icon (API < 26) | 只有单个 ic_launcher.png → 复制为 foreground.png，生成纯白 background.png |
+| app_name 在 build.gradle resValue 中动态定义 | 优先使用 release buildType 的 resValue |
+| 多 flavor 的 applicationId | 根据当前选择的构建变体和 Manifest/Gradle 合并结果选择；无法确定时返回 unresolved，不猜默认值 |
+| 调用方已提供身份摘要 | 只把摘要用于定位；有 Android 工程时仍读取当前 AndroidManifest、Gradle 和资源源码 |
+
+---
+
+## 可选领域协作
+
+下列能力存在时可以协作，但不改变本 Skill 的输入、流程或统一结果：
+
+| 协作对象 | 关系 |
+|---------|------|
+| `android2hmos_resources_convert` | 它处理全量资源，本 skill 只处理 app 级身份资源 |
+| `arkts-i18n` | app_name 等用户可见字符串的多语言资源由它校验 |
+
+本 Skill 不更新迁移报告、不创建 checkpoint、不调用 `complete`，也不暂存或提交工作区；所有外层动作只能由调用方根据统一结果决定。
+
+---
+
+## 触发 Prompt 示例
+
+```
+迁移 app 图标
+```
+
+```
+app 名字不对
+```
+
+```
+配置应用信息
+```
+
+```
+bundleName 还是默认的
+```