@harmonyos-arkts/d2h 0.0.0-stage → 0.1.0

package/skills/arkts-icon-sizing/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: arkts-icon-sizing
+description: >-
+  检测并修复 Android→HarmonyOS UI 迁移中，因丢失 `.width()/.height()` 而导致渲染尺寸错误或比例
+  失真的 ArkUI/HarmonyOS `Image` 组件。转换器保留了 `.objectFit()` 却丢掉了尺寸，使 `resources/base/media`
+  里的位图图标按**原始像素尺寸**渲染（通常大 3 倍，非方形的还会被拉伸）。当用户反馈图标/图片在鸿蒙页面
+  （主页、我的、弹窗、列表项——任何位置）上「太大 / 太小 / 被拉伸 / 被压扁 / 比例异常 / 图标变形 / 显示太大 /
+  icons look off」，或要求「统一检查/修复各页图标比例」，或刚做完 a2h / ArkUI UI 迁移（大量 Android ImageView
+  用了 wrap_content）时触发。内置「审计→测量→修复」三步流水线：用源位图的像素尺寸 ÷ 密度还原每个图标的正确
+  vp 尺寸，同时保留真实宽高比。即使用户只说“图标比例不对”而未说明原因也应使用。适用于 HarmonyOS 工程、Android→HarmonyOS 迁移和 CI。
+---
+
+# ArkUI 图标尺寸修复（Android→HarmonyOS 迁移修复）
+
+## 输入与统一结果
+
+输入包括 HarmonyOS 工程、当前请求允许修改的范围，以及可用的 Android `res/` 根。缺少 Android raster 来源时允许使用显式密度兜底，但必须在结果中标记假设。始终执行同一套审计、测量、修复和复审流程，不识别或修改外部编排状态。
+
+返回统一领域结果：
+
+```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": {"auditReport": "", "fixedCount": 0}
+}
+```
+
+`status` 只表示图标审计和修复的领域状态。动态源、无 raster 和密度兜底项写入 `unresolved`；构建与设备视觉核对写入 `verificationRequests`，不在本 Skill 内选择仓库级命令。
+
+## 问题与成因
+
+在 Android 中，`android:layout_width/height="wrap_content"` 的 `ImageView` 会按 drawable 的**标称 dp**
+尺寸渲染。一张只放在 `*-xxhdpi`（3 倍密度）目录的位图，磁盘上可能是 `90×90 px`，显示为 `30×30 dp`。
+
+Android→HarmonyOS UI 转换器常常复刻了 `ImageView` 的 `.objectFit(...)`，却**丢掉了 `.width()/.height()`**
+（因为 `wrap_content` 没有固定数值可抄）。位图被原样拷进 HarmonyOS 的 `resources/base/media`——而**该目录无密度
+限定符**——于是 ArkUI 按 `Image` 的**字面像素尺寸（当成 vp）**渲染。那张 `90×90 px` 的图标现在显示为 `90×90 vp`，
+即**大了 3 倍**。更糟的是，非方形图标（`45×23` 的电池、`44×26` 的箭头）在没有显式尺寸时保持原始像素框，一旦
+某根轴被布局约束触碰，宽高比就明显失真——这就是用户看到的「比例异常 / 图标变形」。
+
+修复办法是把每个欠约束的 `Image` 还原成它的**标称 vp 尺寸**：
+
+```
+标称 vp = 源位图像素 ÷ 源密度倍数
+```
+
+宽和高**分别独立**相除，这正是还原正确宽高比的关键。已经带显式 `.width()/.height()` 的图标是正常的——**不要**
+碰它们，也**不要**用「把位图挪进带密度限定的目录」这种全局手段去修（那会把本来正确的图标缩小）。缺陷只针对
+**那一部分丢了尺寸的 `Image`**。
+
+## 何时使用
+
+- 用户反馈图标/图片在鸿蒙页面上过大、过小、被拉伸或被压扁——尤其刚做完 a2h / ArkUI UI 迁移之后。
+- 用户要求「统一检查/修复图标比例」。
+- 做迁移 QA，想横扫每个页面排查这一类缺陷。
+
+不属于本 skill：文本截断（`arkts-text-truncation`）、大字体布局溢出（`arkts-large-font`）、深色模式图标变色
+（`arkts-dark-mode`）、生成全新 UI（`arkts-component-builder`）。那些是不同的问题。
+
+## 两种用法
+
+本 skill 有两条路径，共用同一套确定性逻辑：
+
+| 路径 | 入口 | 是否有人工审核 | 适用 |
+|---|---|---|---|
+| **A. 全自动（受控入口）** | `icon_autofix.py` | 无 | 请求范围已明确、Android 资源来源可靠时；CI / 无人值守批量修复 |
+| **B. 人工三步流** | `icon_audit.py` → `icon_dims.py` → `icon_fix.py` | 有（审 `icon_plan.json` 后再 `--apply`） | 人工 ad-hoc 排查，想逐步检查中间产物 |
+
+运行前先读取当前工作区状态并记录本次请求允许修改的文件。修复会就地改源文件，不得覆盖、暂存或回滚用户及其他工作的已有改动；需要恢复时只撤销本次脚本明确列出的修改。
+
+---
+
+## 用法 A：全自动（headless 单入口）
+
+```bash
+# 最佳：让 Android 源逐图决定密度（多模块 → 传所有 res 根）
+python <skill>/scripts/icon_autofix.py --apply \
+    --android-res <android>/app/src/main/res <android>/base/src/main/res \
+    --output-json icon_autofix.json
+
+# 无 Android 源 → 用工程单一密度桶兜底（默认 3 = xxhdpi）
+python <skill>/scripts/icon_autofix.py --apply --density 3 --output-json icon_autofix.json
+```
+
+一次跑完 `审计 → 测量 → 修复 --apply → 复审`，**无任何人工 gate**，只输出一个机读 JSON
+（`passed / scanned / fixed_count / fixed[] / dynamic_unresolved[] / no_raster_unresolved[] / residual_static[]`）。
+**从 HarmonyOS 工程根目录运行**（脚本自动发现 `*/src/main/ets` 与 `resources/base/media`）。
+
+**为什么无人工审核也安全：** 尺寸是 `像素 ÷ 密度` 的确定性计算；只动「无尺寸 / 单尺寸无 aspectRatio」的
+`Image`，绝不碰已带尺寸的；幂等（重复跑第二次 `fixed_count=0`）；输出的修改清单可用于逐项审阅和定向恢复。**建议传 `--android-res`
+以获得逐图精确密度**，缺省回退 `--density 3`。动态源图标 / 无 raster 的项**只记录、不修改**（见用法 B 第 4 步）。
+
+---
+
+## 用法 B：人工三步流
+
+三个脚本按序运行，通过两个 JSON 文件（`icon_report.json`、`icon_plan.json`）通信，每一步落盘前都可检查。
+
+### 1. 审计 — 找出每一个欠约束的 Image
+
+```bash
+python <skill>/scripts/icon_audit.py
+```
+
+自动发现 `*/src/main/ets` 根并写出 `icon_report.json`。它打印两份清单：**静态**欠约束图标
+（`$r('app.media.xxx')`，可自动修）与**动态源**图片（`Image(this.foo())`、三元、`@Builder` 参数——需手工解析，
+见下）。`ImageFit.Fill` 用法单列供人工复核：`Fill` 会拉伸填满，通常是**可拉伸背景图形**（`shape_*_bg` 弹窗横幅）
+的有意为之，除非真有图标用了 `Fill`，否则放着别动。
+
+被标记 = 修饰链**无 width 且无 height**（`NO-DIMS`）或**只有其中一个且无 `aspectRatio`**
+（`ONE-DIM-NO-ASPECT`）。`width('100%') + height('100%')` 视为有意的满铺，不标记。
+
+### 2. 测量 — 还原每个图标的正确 vp 尺寸
+
+```bash
+# 最佳：让 Android 源逐图决定密度（多模块 → 传所有 res 根）
+python <skill>/scripts/icon_dims.py --report icon_report.json \
+    --android-res <android>/app/src/main/res <android>/base/src/main/res
+
+# 无 Android 源 → 用工程单一密度桶兜底（默认 3 = xxhdpi）
+python <skill>/scripts/icon_dims.py --report icon_report.json --density 3
+```
+
+对每个被标记的静态图标，读取 HarmonyOS media 文件（webp/png/jpg/svg）的像素尺寸，除以密度倍数，写出
+`icon_plan.json`（`{icon: {w, h, px, density, src}}`）。
+
+**落地前务必审 `icon_plan.json`。** 核对 `src` 列是真实密度目录（如 `mipmap-xxhdpi`），且算出的 vp 尺寸对一个
+图标而言合理（小图标个/十位数，插图更大）。若大量图标显示 `assumed Nx`，说明没找到 Android 源——确认工程实际密度
+或补 `--android-res`。
+
+标为 **UNRESOLVED** 的图标没有 raster（属动态引用、纯 SVG `<shape>` 转换或矢量图）——手工处理（下一节）。
+
+### 3. 修复 — 插入尺寸（先 dry-run）
+
+```bash
+python <skill>/scripts/icon_fix.py --plan icon_plan.json --report icon_report.json          # 预览
+python <skill>/scripts/icon_fix.py --plan icon_plan.json --report icon_report.json --apply   # 落盘
+```
+
+逐处在 `Image(...)` 开头之后插入：
+- **NO-DIMS** → `.width(W)` `.height(H)`（还原的标称 vp；固定尺寸、真实比例）。
+- **ONE-DIM** → 仅 `.aspectRatio(W/H)`——保留有意的那一维（如满宽横幅的 `.width('100%')`），只修比例。
+
+它实时重扫，所以即使前面的插入移动了行号也安全。动态图片只报告，绝不自动改。
+
+### 4. 手工解析动态源图片
+
+审计/修复读不出 `Image(this.vipEditRes())` 或 `Image(cond ? $r('app.media.a') : $r('app.media.b'))` 的尺寸。
+对每一处：
+
+1. 读代码找出它能解析到的具体资源名（顺着方法/三元跟踪）。勾选类开关通常指向两张同尺寸资源。
+2. 查这些名字：`python <skill>/scripts/icon_dims.py --media <media_dir> --icons ic_a,ic_b`。
+3. 手工给 `Image(...)` 加 `.width(W).height(H)`（若已设一维则用 `.aspectRatio()`）。`@Builder tabItem(icon: Resource)`
+   会让所有调用方共享一个尺寸——在 Builder 的 `Image` 上设一次即可。
+
+### 5. 校验
+
+```bash
+python <skill>/scripts/icon_audit.py        # 静态被标记数应为 0
+```
+
+把构建请求和设备端 UI 核对请求写入 `verificationRequests`。静态审计通过只说明确定性脚本未发现残留静态项，不能证明工程可编译或视觉已经一致。审计结果只应剩下已记录的动态项、无 raster 项和 `Fill` 背景。
+
+## 决策规则与边界
+
+- **密度是逐图的，不是全局的。** 传了 `--android-res` 时 `icon_dims.py`/`icon_autofix.py` 读每个图标的真实源目录。
+  多数 app 只发一个桶（xxhdpi=3），但别假设——通过 `src` 列核实。倍数表：ldpi .75，mdpi 1，hdpi 1.5，xhdpi 2，
+  xxhdpi 3，xxxhdpi 4。
+- **方形 SVG 不会失真。** 方形 viewBox 的 `<shape>`/矢量图按标称 vp 渲染、比例正确——它不会「比例错」，只可能
+  「尺寸错」。若这种 SVG 渲染得过大（如 `100×100` viewBox 显示成 100vp，而本意是小图标），查 **Android drawable 的
+  `android:width/height`** 取本意 dp 并显式设上。否则优先级低。
+- **`shape_*_bg` 上的 `ImageFit.Fill`** 是可拉伸横幅背景——放着别动。只在真图标的盒子比例 ≠ 图标比例时才管 `Fill`。
+- **别碰已带尺寸的图标。** 重点就是欠约束的那部分；全局改资源密度会破坏本来正确的图标。
+- **多模块 Android 工程**把共享资源放在 `base`/`common` 模块——把每个 `*/src/main/res` 根都传给 `--android-res`，
+  密度查找才能找到它们。
+
+## 脚本
+
+| 脚本 | 职责 |
+|---|---|
+| `scripts/icon_audit.py` | 扫 `.ets` → `icon_report.json`（被标记静态 + 动态 + Fill）。导出 `discover_roots()` / `audit()`。 |
+| `scripts/icon_dims.py`  | `report` → `icon_plan.json`：标称 vp = media 像素 ÷ 源密度。导出 `build_plan()`；亦支持 `--icons` 临时查询。 |
+| `scripts/icon_fix.py`   | `report`+`plan` → 插入 `.width/.height`（NO-DIMS）或 `.aspectRatio`（ONE-DIM）。导出 `apply_fixes()`；默认 dry-run，`--apply` 落盘。 |
+| `scripts/icon_autofix.py` | **全自动单入口**：审计→测量→修复→复审一次跑完，输出单个 JSON；由调用方或 CI 在输入边界明确时调用。 |
+
+四者均为纯 Python 标准库（无依赖），支持 `--help`，从工程根运行时自动发现 ets 根与 `resources/base/media`。
+
+## 结果组装
+
+1. 将脚本 JSON 和复审报告写入 `evidence`。
+2. 将实际修改文件写入 `changedFiles`，Android raster 来源写入 `sourceFiles`。
+3. 将静态复审写入 `domainChecks`。
+4. 将动态源、无 raster 和密度兜底项写入 `unresolved`。
+5. 将构建和相关页面的设备视觉核对写入 `verificationRequests`。
+
+## 可选领域协作
+
+下列 Skill 存在时可以协作，但不改变本 Skill 的输入、流程或统一结果：
+
+- **android2hmos_resources_convert**：资源/资产侧转换（res/ → resources/、SVG 坐标/格式修复）；本 skill 修的是 `.ets` 消费侧。
+- **arkts-mvvm-architecture**：页面组件结构和 ArkTS/ArkUI 编码约束。
+- **harmonyos-migration-playbook**：设备 UI 自动化、截图和页面对照方式。
+
+本 Skill 不暂存或提交文件、不更新迁移报告、不创建 checkpoint、不调用 `complete`。调用方自行消费统一结果。

package/skills/arkts-icon-sizing/scripts/icon_audit.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""第 1/3 步 —— 审计 ArkUI (.ets) 中欠约束尺寸的 Image() 组件。
+
+成因
+  Android UI 迁移到 HarmonyOS/ArkUI 时，转换器常保留 `.objectFit(...)` 却
+  丢掉用了 `android:layout_width/height="wrap_content"` 的 ImageView 的
+  `.width()/.height()`。位图被拷进 `resources/base/media`（无密度限定符），
+  于是 HarmonyOS 按其原始像素尺寸当作 vp 渲染 —— 图标被放大（按源密度倍数，
+  如 xxhdpi = 3 倍），非方形图标还会比例失真。
+
+会标记什么（一个 Image 的修饰链满足）
+  - 既无 width 又无 height 且无 size()        -> kind = NO-DIMS
+  - 恰好只有 width/height 之一，且无 aspectRatio -> kind = ONE-DIM-NO-ASPECT
+  （width('100%') + height('100%') = 满铺，视为有意为之。）
+  同时列出 ImageFit.Fill 用法（可能拉伸）供人工复核。
+
+输出
+  打印摘要并写出 JSON 报告（默认 icon_report.json），供 icon_dims.py /
+  icon_fix.py / icon_autofix.py 消费。
+
+用法
+  python icon_audit.py                         # 自动发现 */src/main/ets 根
+  python icon_audit.py --roots entry/src/main/ets/pages entry/.../components
+  python icon_audit.py --json icon_report.json
+"""
+import os, re, json, argparse
+
+
+def discover_roots():
+    """找出每一个 */src/main/ets 目录（entry + 任意 HSP/HAR 模块）。"""
+    roots, skip = [], {'node_modules', 'oh_modules', 'build', '.git', '.hvigor', '.idea'}
+    for base, dirs, _ in os.walk('.'):
+        dirs[:] = [d for d in dirs if d not in skip]
+        if base.replace('\\', '/').endswith('src/main/ets'):
+            roots.append(base)
+    return sorted(set(roots))
+
+
+def chain_window(lines, i):
+    """第 i 行 Image 的修饰链 = 紧随其后、缩进更深的那些行。"""
+    base = len(lines[i]) - len(lines[i].lstrip())
+    out, j = [], i + 1
+    while j < len(lines):
+        ln = lines[j]
+        if ln.strip() == '':
+            j += 1
+            continue
+        if (len(ln) - len(ln.lstrip())) <= base:
+            break
+        out.append(ln)
+        j += 1
+    return '\n'.join(out)
+
+
+def audit(roots):
+    flagged, fill_used, full_bleed, scanned = [], [], 0, 0
+    for root in roots:
+        for dp, _, files in os.walk(root):
+            for fn in files:
+                if not fn.endswith('.ets'):
+                    continue
+                path = os.path.join(dp, fn).replace('\\', '/')
+                lines = open(path, encoding='utf-8').read().split('\n')
+                for i, ln in enumerate(lines):
+                    st = ln.lstrip()
+                    # 跳过注释行，避免被注释掉的 Image()/ImageView 引用误命中
+                    if st.startswith('*') or st.startswith('//') or st.startswith('/*'):
+                        continue
+                    code = ln.split('//')[0]
+                    if not re.search(r'\bImage\(', code):
+                        continue
+                    scanned += 1
+                    win = chain_window(lines, i)
+                    has_w, has_h = '.width(' in win, '.height(' in win
+                    has_size = '.size(' in win
+                    has_aspect = '.aspectRatio(' in win
+                    has_weight = '.layoutWeight(' in win
+                    w100, h100 = ".width('100%')" in win, ".height('100%')" in win
+                    fitm = re.search(r'ImageFit\.(\w+)', win)
+                    fit = fitm.group(1) if fitm else None
+                    iconm = re.search(r"(?:app|sys)\.media\.([A-Za-z0-9_]+)", code)
+                    icon = iconm.group(1) if iconm else None
+                    if 'ImageFit.Fill' in win:
+                        fill_used.append({'file': path, 'line': i + 1, 'icon': icon})
+                    if w100 and h100:
+                        full_bleed += 1
+                        continue
+                    ok = has_size or (has_w and has_h) or \
+                        ((has_w ^ has_h) and (has_aspect or has_weight))
+                    if ok:
+                        continue
+                    flagged.append({
+                        'file': path, 'line': i + 1, 'icon': icon,
+                        'dynamic': icon is None,
+                        'kind': 'NO-DIMS' if not (has_w or has_h) else 'ONE-DIM-NO-ASPECT',
+                        'fit': fit, 'expr': code.strip()[:60],
+                    })
+    return {'scanned': scanned, 'flagged': flagged,
+            'fill': fill_used, 'full_bleed_count': full_bleed}
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument('--roots', nargs='*', help='要扫描的 ets 目录（默认：自动发现 */src/main/ets）')
+    ap.add_argument('--json', default='icon_report.json', help='报告输出路径')
+    a = ap.parse_args()
+    roots = a.roots or discover_roots()
+    if not roots:
+        print('未找到 ets 根。请从 HarmonyOS 工程根运行，或用 --roots 指定。')
+        return
+    print('扫描根目录：')
+    for r in roots:
+        print('  ' + r)
+    rep = audit(roots)
+    print(f'\n== 扫描 {rep["scanned"]} 个 Image() | 标记 {len(rep["flagged"])} '
+          f'| Fill {len(rep["fill"])} | 满铺 {rep["full_bleed_count"]} ==\n')
+    stat = [f for f in rep['flagged'] if not f['dynamic']]
+    dyn = [f for f in rep['flagged'] if f['dynamic']]
+    print(f'-- 欠约束的静态图标（{len(stat)}）--')
+    for f in sorted(stat, key=lambda x: (x['file'], x['line'])):
+        print(f"  [{f['kind']:18}] fit={f['fit'] or '-':8} {os.path.basename(f['file'])}:{f['line']}  {f['icon']}")
+    print(f'\n-- 动态源图片（{len(dyn)}）-> 手工解析资源（见 SKILL.md）--')
+    for f in sorted(dyn, key=lambda x: (x['file'], x['line'])):
+        print(f"  {os.path.basename(f['file'])}:{f['line']}  {f['expr']}")
+    json.dump(rep, open(a.json, 'w', encoding='utf-8'), ensure_ascii=False, indent=2)
+    print(f'\n已写出 {a.json}  ->  下一步：python icon_dims.py --report {a.json}')
+
+
+if __name__ == '__main__':
+    main()

package/skills/arkts-icon-sizing/scripts/icon_autofix.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""全自动单入口 —— 一次跑完 审计→测量→修复→复审，输出单个机读 JSON，无任何人工 gate。
+
+由调用方或 CI 在输入边界明确时调用；也可直接使用 --apply。
+
+为什么无人工审核也安全：
+  尺寸 = 像素 ÷ 密度 是确定性计算；只动「无尺寸 / 单尺寸无 aspectRatio」的 Image，
+  绝不碰已带尺寸的；幂等（重复跑第二次 fixed_count=0）；调用者负责保护已有工作区改动。
+  动态源图片 / 无 raster 项只记录、不修改，由调用方判断其是否阻塞当前请求。
+
+用法
+  python icon_autofix.py --apply --output-json icon_autofix.json
+  python icon_autofix.py --apply --android-res <a>/app/src/main/res <a>/base/src/main/res \
+      --output-json icon_autofix.json
+  python icon_autofix.py --apply --density 3 --output-json icon_autofix.json   # 无 Android 源
+"""
+import os, json, argparse
+import sys
+from pathlib import Path
+
+# 允许从本脚本目录直接 import 同级模块
+sys.path.insert(0, str(Path(__file__).parent))
+from icon_audit import discover_roots, audit
+from icon_dims import find_media_dir, build_plan
+from icon_fix import apply_fixes
+
+
+def autofix(android_res, density, apply=True):
+    """审计→测量→修复→复审，返回结构化结果 dict。"""
+    roots = discover_roots()
+    if not roots:
+        return {'passed': True, 'skipped': True, 'reason': '未找到 */src/main/ets 根'}
+    report = audit(roots)
+    media = find_media_dir()
+    names = sorted({f['icon'] for f in report['flagged'] if f.get('icon')})
+    if media:
+        plan, no_raster = build_plan(names, media, android_res, density)
+    else:
+        plan, no_raster = {}, names
+    applied, dynamic = apply_fixes(plan, report, apply=apply)
+    # 复审：验证收敛。有 raster 却仍被标记的静态图标 = 异常
+    report2 = audit(roots)
+    residual = [f for f in report2['flagged']
+                if not f['dynamic'] and f.get('icon') in plan]
+    return {
+        'passed': True,                       # 自愈永不阻断；执行异常时由外层 main 置 False
+        'media': media,
+        'scanned': report['scanned'],
+        'flagged_before': len(report['flagged']),
+        'flagged_after': len(report2['flagged']),
+        'fixed_count': len(applied),
+        'fixed': applied,
+        'dynamic_unresolved': dynamic,        # Image(this.foo()) / 三元等，记录不修
+        'no_raster_unresolved': no_raster,    # 纯 svg shape / 矢量图，记录不修
+        'fill_for_review': report.get('fill', []),
+        'residual_static': [{'file': f['file'], 'line': f['line'], 'icon': f['icon']} for f in residual],
+        'density_source': ('android-res' if android_res else f'fallback {density}x'),
+    }
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument('--project-root', default='.', help='HarmonyOS 工程根（脚本会 chdir 到此）')
+    ap.add_argument('--android-res', nargs='*', default=[], help='Android res 根，用于逐图密度（缺省回退 --density）')
+    ap.add_argument('--density', type=float, default=3.0, help='回退密度倍数（默认 3 = xxhdpi）')
+    ap.add_argument('--apply', action='store_true', help='落盘（默认 dry-run，仅计算）')
+    ap.add_argument('--output-json', required=True, help='结果 JSON 输出路径')
+    a = ap.parse_args()
+
+    out_path = Path(a.output_json).resolve()      # chdir 前先解析为绝对路径
+    android_res = [str(Path(r).resolve()) for r in a.android_res] or None
+    if a.project_root and a.project_root != '.':
+        os.chdir(a.project_root)
+
+    try:
+        out = autofix(android_res, a.density, apply=a.apply)
+    except Exception as e:
+        out = {'passed': False, 'error': str(e)}
+
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(json.dumps(out, ensure_ascii=False, indent=2), encoding='utf-8')
+    brief = {k: out.get(k) for k in ('passed', 'fixed_count', 'dynamic_unresolved', 'density_source', 'skipped', 'error')}
+    print(json.dumps({k: v for k, v in brief.items() if v is not None}, ensure_ascii=False))
+
+
+if __name__ == '__main__':
+    main()

package/skills/arkts-icon-sizing/scripts/icon_dims.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""第 2/3 步 —— 还原每个被标记图标的正确 vp 尺寸。
+
+公式
+  HarmonyOS 中 `resources/base/media`（无密度限定符）里的位图按其字面像素尺寸
+  当作 vp 渲染。源位图来自某个 Android 密度桶（如 drawable-xxhdpi /
+  mipmap-xxhdpi = 3 倍）。因此图标被设计显示的尺寸是：
+        标称 vp = 源像素 / 源密度倍数
+  我们从 HarmonyOS media 文件读像素尺寸，从 Android 源目录名取倍数。宽和高
+  分别独立相除，所以真实宽高比得以保留（这正是修复「失真 / 比例错」的关键）。
+
+倍数从何而来
+  1. 给了 --android-res 时，由图标的源目录（如 mipmap-xxhdpi）决定。Android
+     工程可能多模块 —— 把每个 res 根都传进来（如 app/src/main/res 与
+     base/src/main/res）。
+  2. 否则回退到 --density（默认 3.0 = xxhdpi，现代 app 最常见的单一桶）。输出
+     会标出 assumed 项，便于人工核对。
+
+输出
+  打印表格并写出 icon_plan.json {icon: {w,h,px,density,src}}。
+  找不到 raster 的图标（动态引用、纯 SVG shape、矢量图）列为 UNRESOLVED 供手工处理。
+
+用法
+  python icon_dims.py --report icon_report.json \
+      --media entry/src/main/resources/base/media \
+      --android-res /path/app/src/main/res /path/base/src/main/res
+  python icon_dims.py --report icon_report.json --density 3      # 无 Android 源
+  python icon_dims.py --media .../media --icons ic_a,ic_b        # 临时查询
+"""
+import os, re, json, struct, glob, argparse
+
+DENSITY = {'ldpi': 0.75, 'mdpi': 1.0, 'tvdpi': 1.33, 'hdpi': 1.5,
+           'xhdpi': 2.0, 'xxhdpi': 3.0, 'xxxhdpi': 4.0}
+
+
+def webp_size(p):
+    d = open(p, 'rb').read(40)
+    if d[:4] != b'RIFF' or d[8:12] != b'WEBP':
+        return None
+    f = d[12:16]
+    if f == b'VP8 ':
+        return struct.unpack('<H', d[26:28])[0] & 0x3fff, struct.unpack('<H', d[28:30])[0] & 0x3fff
+    if f == b'VP8L':
+        b = d[21:25]
+        v = b[0] | b[1] << 8 | b[2] << 16 | b[3] << 24
+        return (v & 0x3fff) + 1, ((v >> 14) & 0x3fff) + 1
+    if f == b'VP8X':
+        return (d[24] | d[25] << 8 | d[26] << 16) + 1, (d[27] | d[28] << 8 | d[29] << 16) + 1
+    return None
+
+
+def png_size(p):
+    d = open(p, 'rb').read(24)
+    return struct.unpack('>II', d[16:24])
+
+
+def svg_size(p):
+    h = open(p, encoding='utf-8', errors='ignore').read(400)
+    m = re.search(r'width="([0-9.]+)"[^>]*height="([0-9.]+)"', h)
+    if m:
+        return float(m.group(1)), float(m.group(2))
+    m = re.search(r'viewBox="[\d.]+ [\d.]+ ([\d.]+) ([\d.]+)"', h)
+    return (float(m.group(1)), float(m.group(2))) if m else None
+
+
+def media_size(media_dir, name):
+    for ext, fn in (('.webp', webp_size), ('.png', png_size), ('.jpg', png_size), ('.svg', svg_size)):
+        p = os.path.join(media_dir, name + ext)
+        if os.path.exists(p):
+            try:
+                return fn(p), ext
+            except Exception:
+                return None, ext
+    return None, None
+
+
+def src_multiplier(res_roots, name):
+    best = None
+    for root in res_roots:
+        for hit in glob.glob(f'{root}/*/{name}.*'):
+            folder = os.path.basename(os.path.dirname(hit))
+            for k, v in DENSITY.items():
+                if folder.endswith('-' + k) or folder.endswith(k):
+                    if best is None or v > best[0]:
+                        best = (v, folder)
+    return best
+
+
+def find_media_dir():
+    # 排除非工程目录（skill 模板 / 依赖 / 构建产物 / 隐藏目录），避免 os.walk 误入
+    # .claude/skills/.../template/AppScope/resources/base/media 等 fixture。
+    skip = {'.git', '.hvigor', '.idea', '.claude', '.cxt',
+            'oh_modules', 'node_modules', 'build', 'template'}
+    candidates = []
+    for base, dirs, _ in os.walk('.'):
+        dirs[:] = [d for d in dirs if d not in skip and not d.startswith('.')]
+        if base.replace('\\', '/').endswith('resources/base/media'):
+            candidates.append(base)
+    if not candidates:
+        return None
+    # 优先工程模块媒体（*/src/main/resources/base/media）而非 app 级 AppScope 或其它
+    for c in candidates:
+        if '/src/main/resources/' in c.replace('\\', '/'):
+            return c
+    return candidates[0]
+
+
+def build_plan(names, media, android_res, density):
+    """对一组图标名，逐个 媒体像素 ÷ 源密度 算出标称 vp，返回 (plan, unresolved)。
+
+    被 icon_dims.main() 与 icon_autofix.py 共用。
+      names       : 图标名列表（不含扩展名）
+      media       : HarmonyOS base/media 目录
+      android_res : Android res 根列表（空/None → 用 density 回退）
+      density     : 回退密度倍数
+    返回 plan = {icon: {w,h,px,density,src,ext}}；unresolved = 找不到 raster 的图标名列表。
+    """
+    plan, unresolved = {}, []
+    for ic in names:
+        sz, ext = media_size(media, ic)
+        if sz is None:
+            unresolved.append(ic)
+            continue
+        mult = src_multiplier(android_res, ic) if android_res else None
+        m = mult[0] if mult else density
+        src = mult[1] if mult else f'assumed {density}x'
+        w, h = sz
+        vw, vh = max(1, round(w / m)), max(1, round(h / m))
+        plan[ic] = {'w': vw, 'h': vh, 'px': [round(w), round(h)], 'density': m, 'src': src, 'ext': ext}
+    return plan, unresolved
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument('--report', default='icon_report.json')
+    ap.add_argument('--media', help='HarmonyOS base/media 目录（默认：自动发现）')
+    ap.add_argument('--android-res', nargs='*', default=[], help='用于密度查找的 Android res 根')
+    ap.add_argument('--density', type=float, default=3.0, help='回退密度倍数（默认 3 = xxhdpi）')
+    ap.add_argument('--icons', help='逗号分隔的图标名，临时查询（替代 --report）')
+    ap.add_argument('--json', default='icon_plan.json')
+    a = ap.parse_args()
+
+    media = a.media or find_media_dir()
+    if not media:
+        print('未找到 resources/base/media —— 请用 --media 指定。')
+        return
+
+    if a.icons:
+        names = [n.strip() for n in a.icons.split(',') if n.strip()]
+    else:
+        rep = json.load(open(a.report, encoding='utf-8'))
+        names = sorted({f['icon'] for f in rep['flagged'] if f.get('icon')})
+
+    print(f"media: {media}")
+    print(f"密度来源: {a.android_res or f'回退 {a.density}x'}\n")
+    print(f"{'图标':40} {'像素':12} {'密度':16} {'-> vp (w x h)'}")
+    print('-' * 86)
+    plan, unresolved = build_plan(names, media, a.android_res or None, a.density)
+    for ic in names:
+        if ic in plan:
+            p = plan[ic]
+            px = f"{p['px'][0]}x{p['px'][1]}"
+            print(f"{ic:40} {px:12} {p['src']:16} -> {p['w']} x {p['h']}")
+        else:
+            label = '(无 raster)'
+            blank = ''
+            print(f"{ic:40} {label:12} {blank:16} -> 手工处理（动态 / svg shape / 矢量图）")
+
+    json.dump(plan, open(a.json, 'w', encoding='utf-8'), ensure_ascii=False, indent=2)
+    print(f'\n已写出 {a.json}（{len(plan)} 个图标）。')
+    if unresolved:
+        print(f'UNRESOLVED（{len(unresolved)}）—— 手工解析资源后，用 --icons <名字> 重跑来测尺寸：'
+              f'{", ".join(unresolved)}')
+    print(f'请审核 icon_plan.json，然后：python icon_fix.py --plan {a.json} --report {a.report}（加 --apply 落盘）')
+
+
+if __name__ == '__main__':
+    main()