@chengyu08/ipa-cli 0.1.11 → 0.2.0

package/README.md

@@ -29,6 +29,7 @@
 说明：
 
 - macOS 上如果系统提供 `codesign`、`otool`、`nm`、`xcrun assetutil`，分析结果会更完整
+- 可运行 `ipa-cli doctor` 检查这些增强工具是否可用；缺失时按输出中的安装建议处理
 - Linux / Windows 上缺少 Apple 专有工具时，会自动降级部分能力，但 CLI 仍可继续运行
 
 ## 安装方式
@@ -232,6 +233,7 @@ cp ./scripts/ipatool.env.example ./scripts/ipatool.env
 
 当前 CLI 提供以下命令：
 
+- `doctor`：检查本机 macOS 增强分析工具是否可用
 - `analyze`：分析单个 IPA 或指纹 JSON
 - `compare`：对比两个 IPA 或两个指纹 JSON
 - `scan`：把目标样本与本地基线库做 Top N 检索
@@ -255,6 +257,47 @@ cp ./scripts/ipatool.env.example ./scripts/ipatool.env
 
 ## 命令说明
 
+### `doctor`
+
+检查本机是否具备 macOS 增强分析工具。
+
+```bash
+ipa-cli doctor [--format panel|json] [--strict]
+```
+
+参数：
+
+- `--format`：输出格式，默认 `panel`
+- `--strict`：缺少任一增强工具时返回非零退出码，适合 CI 或发布前自检
+
+检查项：
+
+- `codesign`：读取签名信息与 entitlements
+- `otool`：读取 Mach-O 导入符号和二进制结构信号
+- `nm`：读取符号表，补充 Objective-C/Swift 符号信号
+- `xcrun assetutil`：解析 `Assets.car`，补充高级资源摘要
+
+示例：
+
+```bash
+ipa-cli doctor
+ipa-cli doctor --format json
+ipa-cli doctor --strict
+```
+
+如果有工具缺失，优先安装或修复 Xcode Command Line Tools：
+
+```bash
+xcode-select --install
+```
+
+如果仅 `xcrun assetutil` 缺失，通常需要安装完整 Xcode，并确认 Developer 目录指向 Xcode：
+
+```bash
+sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
+sudo xcodebuild -license accept
+```
+
 ### `analyze`
 
 分析单个 IPA 或单个指纹 JSON，并输出标准化结果。
@@ -275,6 +318,12 @@ ipa-cli analyze ./YourApp.ipa --format text
 ipa-cli analyze ./fingerprint.json --format panel
 ```
 
+Flutter 样本额外关注：
+
+- `resources.summary.flutter`：`flutter_assets` 规模、生成文件、Debug 三件套、AssetManifest / FontManifest / NativeAssetsManifest 标记
+- `resources.summary.flutter.appBinary*`：`Frameworks/App.framework/App` 的 AOT 摘要，包括体积、SHA-256、UUID、架构、字符串 token、runtime hint
+- 人类可读输出里会显示 `Flutter 资源` 摘要；如果样本包含 `App.framework/App`，还会显示 `AOT` 大小
+
 ### `compare`
 
 对比两个 IPA 或两个指纹 JSON，输出相似度报告和风险分类。
@@ -296,6 +345,16 @@ ipa-cli compare ./AppA.ipa ./AppB.ipa --format text
 ipa-cli compare ./a.json ./b.json --format panel
 ```
 
+Flutter 对比额外输出：
+
+- `metrics.flutter.appAotSimilarity`：`App.framework/App` 的 AOT 相似度
+- `metrics.flutter.appAotStringSimilarity`：AOT 字符串 token 相似度
+- `metrics.flutter.assetManifestSimilarity` / `fontManifestSimilarity` / `nativeAssetsSimilarity`
+- `metrics.flutter.leftManifestSource` / `rightManifestSource`：`bin|json|none`
+- `metrics.flutter.leftBuildState` / `rightBuildState`：`debug|release-like|mixed|unknown`
+
+人类可读格式会把这些信息显示为 `Flutter专项` 区块，便于区分“公共 Flutter 运行时相似”与“业务 AOT / 资源相似”。
+
 ### `scan`
 
 把目标样本与本地基线库做 Top N 检索。
@@ -316,6 +375,15 @@ ipa-cli scan <input> [--library <dir>] [--top <count>]
 ipa-cli scan ./YourApp.ipa --library ./data/library --top 5
 ```
 
+如果目标或命中样本是 Flutter，Top1 explain 会额外展示：
+
+- `App AOT`
+- `AOT字符串`
+- `Flutter业务资源`
+- `AssetManifest`
+- `FontManifest`
+- `Native Assets`
+
 ### `smoke`
 
 执行端到端冒烟流程。
@@ -523,7 +591,10 @@ ipa-cli screenshots render ./screenshot.config.json --output ./screenshots --ove
     "subtitleColor": "#4B5563",
     "fontFamily": "Inter, Arial, sans-serif",
     "orientation": "portrait",
-    "deviceWidthRatio": 0.76
+    "deviceWidthRatio": 0.76,
+    "deviceFrame": {
+      "preset": "iphone-dark-01"
+    }
   },
   "targets": ["iphone-6.5"],
   "locales": ["zh-Hans"],
@@ -550,9 +621,12 @@ ipa-cli screenshots render ./screenshot.config.json --output ./screenshots --ove
 | `defaults.background` | 否 | 全局背景配置；兼容纯色字符串，也支持 `preset`、`solid`、`linear-gradient`、`image`、`raw-blur`、`stack` |
 | `defaults.titleColor` | 否 | 标题颜色，默认 `#111827` |
 | `defaults.subtitleColor` | 否 | 副标题颜色，默认 `#4B5563` |
+| `defaults.titleFontSize` | 否 | 标题字号，单位 px；不填时按画布宽度自动计算 |
+| `defaults.subtitleFontSize` | 否 | 副标题字号，单位 px；不填时按画布宽度自动计算 |
 | `defaults.fontFamily` | 否 | SVG 文本字体族，默认 `Inter, Arial, sans-serif` |
 | `defaults.orientation` | 否 | `portrait` 或 `landscape`，默认 `portrait` |
 | `defaults.deviceWidthRatio` | 否 | 设备截图宽度相对画布宽度的比例，范围 `0.35` 到 `0.95`，默认 `0.76` |
+| `defaults.deviceFrame` | 否 | 全局默认手机框配置；支持内置 `preset` 或自定义 `src` + `screen` |
 | `targets` | 是 | 要生成的设备槽位列表，例如 `["iphone-6.9", "ipad-13"]` |
 | `locales` | 是 | 要生成的语言列表，例如 `["zh-Hans", "en-US"]` |
 | `frames[].name` | 是 | 输出文件名；如果不以 `.png` 结尾，会自动补 `.png` |
@@ -565,26 +639,613 @@ ipa-cli screenshots render ./screenshot.config.json --output ./screenshots --ove
 | `frames[].background` | 否 | 覆盖全局背景配置 |
 | `frames[].titleColor` | 否 | 覆盖全局标题颜色 |
 | `frames[].subtitleColor` | 否 | 覆盖全局副标题颜色 |
+| `frames[].titleFontSize` | 否 | 覆盖单张图标题字号，单位 px |
+| `frames[].subtitleFontSize` | 否 | 覆盖单张图副标题字号，单位 px |
+| `frames[].deviceFrame` | 否 | 单张图覆盖手机框配置；可只写 `offsetY`、`scale` 等局部字段 |
 | `frames[].target` | 否 | 只对某个目标槽位生效 |
 | `frames[].locale` | 否 | 只对某个语言生效 |
 
+字号字段速查：
+
+- `defaults.titleFontSize`：全局默认标题字号
+- `defaults.subtitleFontSize`：全局默认副标题字号
+- `frames[].titleFontSize`：覆盖单张图标题字号
+- `frames[].subtitleFontSize`：覆盖单张图副标题字号
+- 单位都是 `px`，值必须是正数
+- `frames[]` 里的字号设置优先级高于 `defaults`
+- `subtitle` 只有在 `layout: "device-with-title-subtitle"` 时显示，所以 `subtitleFontSize` 也只会在这个布局下生效
+- 如果这些字段都不填，渲染器会按画布宽度自动计算字号
+
+```json
+{
+  "defaults": {
+    "titleFontSize": 72,
+    "subtitleFontSize": 38
+  },
+  "frames": [
+    {
+      "name": "01_home",
+      "raw": "raw/{locale}/01_home.png",
+      "layout": "device-with-title-subtitle",
+      "title": "快速完成估价",
+      "subtitle": "关键流程清晰可见",
+      "titleFontSize": 84,
+      "subtitleFontSize": 44
+    }
+  ]
+}
+```
+
 布局类型：
 
 | layout | 画面效果 | 适合场景 | 注意事项 |
 | --- | --- | --- | --- |
 | `raw-fullscreen` | 原图直接铺满整个输出画布，不显示设备外框、标题或副标题 | 已经是完整营销图、KV 图、海报风页面图 | `rawFit: "cover"` 时只输出原图；`rawFit: "contain"` 时才会露出背景层 |
-| `device-with-title` | 顶部显示一段标题，下方展示带圆角和阴影的设备截图 | 单卖点页、功能页、流程页 | 即使传了 `subtitle`，当前也不会显示 |
-| `device-with-title-subtitle` | 顶部显示标题和副标题，下方展示带圆角和阴影的设备截图 | 首页、详情页、需要两级文案的场景 | 这是默认布局；不填 `subtitle` 时会只显示标题区 |
+| `device-with-title` | 顶部显示一段标题，下方展示带手机框的设备截图 | 单卖点页、功能页、流程页 | 即使传了 `subtitle`，当前也不会显示 |
+| `device-with-title-subtitle` | 顶部显示标题和副标题，下方展示带手机框的设备截图 | 首页、详情页、需要两级文案的场景 | 这是默认布局；不填 `subtitle` 时会只显示标题区 |
+
+配置写法示例：
+
+##### 手机框展示
+
+默认配置会启用内置 `iphone-dark-01` 手机框。原始截图会进入手机屏幕区域，按屏幕圆角裁剪，再叠加手机外框。
+
+```json
+{
+  "defaults": {
+    "deviceFrame": {
+      "preset": "iphone-dark-01"
+    }
+  },
+  "frames": [
+    {
+      "name": "01_home",
+      "raw": "raw/{locale}/01_home.png",
+      "title": "快速完成估价",
+      "deviceFrame": {
+        "offsetY": -80,
+        "scale": 0.96
+      }
+    }
+  ]
+}
+```
+
+内置 `preset` 当前支持 `iphone-dark-01` 和 `iphone-dark-02`。如果使用自定义手机框，需要提供 `src` 和以手机框原图像素为准的 `screen` 开窗区域。
+
+##### 全局纯色背景
+
+如果所有截图都使用同一个纯色背景，可以只配置 `defaults.background`。纯色字符串是最短写法，适合浅灰、白色或品牌主色背景。
+
+```json
+{
+  "version": 1,
+  "platform": "ios",
+  "defaults": {
+    "background": "#F5F7FA",
+    "titleColor": "#111827",
+    "subtitleColor": "#4B5563"
+  },
+  "targets": ["iphone-6.5"],
+  "locales": ["zh-Hans"],
+  "frames": [
+    {
+      "name": "01_home",
+      "raw": "raw/{locale}/01_home.png",
+      "title": "快速完成估价",
+      "subtitle": "关键流程清晰可见"
+    }
+  ]
+}
+```
+
+如果希望结构更统一，也可以把纯色写成对象：
+
+```json
+{
+  "defaults": {
+    "background": {
+      "type": "solid",
+      "color": "#0F172A"
+    },
+    "titleColor": "#FFFFFF",
+    "subtitleColor": "#CBD5E1"
+  }
+}
+```
+
+##### 全局渐变背景
+
+`linear-gradient` 适合给整套上架图统一品牌氛围。`angle` 表示渐变角度，`stops` 按 `offset` 从 `0` 到 `1` 配置颜色节点。
+
+```json
+{
+  "version": 1,
+  "platform": "ios",
+  "defaults": {
+    "background": {
+      "type": "linear-gradient",
+      "angle": 180,
+      "stops": [
+        { "offset": 0, "color": "#EEF2FF" },
+        { "offset": 0.52, "color": "#DBEAFE" },
+        { "offset": 1, "color": "#F8FAFC" }
+      ]
+    },
+    "titleColor": "#172554",
+    "subtitleColor": "#475569",
+    "orientation": "portrait",
+    "deviceWidthRatio": 0.76
+  },
+  "targets": ["iphone-6.5"],
+  "locales": ["zh-Hans"],
+  "frames": [
+    {
+      "name": "01_home",
+      "raw": "raw/{locale}/01_home.png",
+      "title": "快速完成估价",
+      "subtitle": "核心流程一眼看清",
+      "layout": "device-with-title-subtitle"
+    },
+    {
+      "name": "02_detail",
+      "raw": "raw/{locale}/02_detail.png",
+      "title": "详情信息完整展示",
+      "subtitle": "关键数据层级清晰",
+      "layout": "device-with-title-subtitle"
+    }
+  ]
+}
+```
+
+单张图也可以覆盖全局渐变。下面示例中，`01_home` 使用蓝紫渐变，`02_detail` 使用默认背景。
+
+```json
+{
+  "defaults": {
+    "background": "#F8FAFC"
+  },
+  "targets": ["iphone-6.5"],
+  "locales": ["zh-Hans"],
+  "frames": [
+    {
+      "name": "01_home",
+      "raw": "raw/{locale}/01_home.png",
+      "title": "快速完成估价",
+      "background": {
+        "type": "linear-gradient",
+        "angle": 145,
+        "stops": [
+          { "offset": 0, "color": "#312E81" },
+          { "offset": 0.55, "color": "#2563EB" },
+          { "offset": 1, "color": "#38BDF8" }
+        ]
+      },
+      "titleColor": "#FFFFFF",
+      "subtitleColor": "#DBEAFE"
+    },
+    {
+      "name": "02_detail",
+      "raw": "raw/{locale}/02_detail.png",
+      "title": "详情信息完整展示"
+    }
+  ]
+}
+```
+
+##### 图片背景
+
+`image` 背景适合使用品牌纹理、活动海报、插画或运营底图。`src` 相对 `screenshot.config.json` 所在目录解析，不是相对当前 shell 目录。
+
+推荐目录结构：
+
+```text
+screenshots-workspace/
+  screenshot.config.json
+  backgrounds/
+    hero.png
+    zh-Hans/
+      iphone-6.5/
+        01_home.png
+  raw/
+    zh-Hans/
+      01_home.png
+```
+
+固定使用一张背景图时，可以这样配置：
+
+```json
+{
+  "defaults": {
+    "background": {
+      "type": "image",
+      "src": "backgrounds/hero.png",
+      "fit": "cover",
+      "position": "center",
+      "overlay": {
+        "color": "#020617",
+        "opacity": 0.18
+      }
+    },
+    "titleColor": "#FFFFFF",
+    "subtitleColor": "#E2E8F0"
+  },
+  "targets": ["iphone-6.5"],
+  "locales": ["zh-Hans"],
+  "frames": [
+    {
+      "name": "01_home",
+      "raw": "raw/{locale}/01_home.png",
+      "title": "首页体验全面升级",
+      "subtitle": "核心入口更清晰"
+    }
+  ]
+}
+```
 
-背景配置可以写在 `defaults.background`、`defaults.backgroundPresets.<name>` 或 `frames[].background`。`frames[].background` 优先级最高；如果只想引用预设，也可以使用 `frames[].backgroundPreset`。当前支持的背景类型包括：
+如果每个语言、设备或页面都需要不同背景图，可以在 `src` 里使用 `{locale}`、`{target}`、`{frame}` 占位符。`{frame}` 使用当前 `frames[].name`。
 
-- 纯色字符串：`"#F5F7FA"`
-- `solid`：显式声明纯色背景，例如 `{ "type": "solid", "color": "#0F172A" }`
-- `linear-gradient`：线性渐变背景，适合品牌色过渡和浅色氛围底
-- `image`：把本地图片铺成背景，`src` 相对配置文件目录解析，支持 `{locale}`、`{target}`、`{frame}` 占位符
-- `raw-blur`：把当前 frame 的 `raw` 原图拉伸、模糊后当作背景
-- `stack`：按顺序叠加多层背景，每层可写 `opacity` 和 `blend`
-- `preset`：引用 `defaults.backgroundPresets` 里定义的背景预设
+```json
+{
+  "defaults": {
+    "background": {
+      "type": "image",
+      "src": "backgrounds/{locale}/{target}/{frame}.png",
+      "fit": "cover",
+      "position": "center",
+      "overlay": {
+        "color": "#111827",
+        "opacity": 0.2
+      }
+    },
+    "titleColor": "#FFFFFF",
+    "subtitleColor": "#F8FAFC"
+  },
+  "targets": ["iphone-6.9", "iphone-6.5"],
+  "locales": ["zh-Hans", "en-US"],
+  "frames": [
+    {
+      "name": "01_home",
+      "raw": "raw/{locale}/01_home.png",
+      "title": "快速完成估价",
+      "subtitle": "关键流程清晰可见"
+    }
+  ]
+}
+```
+
+##### 原图模糊背景
+
+`raw-blur` 会把当前 frame 的 `raw` 原图拉伸、模糊后作为背景。它适合没有额外设计素材，但希望背景色调和截图内容自然一致的场景。
+
+```json
+{
+  "defaults": {
+    "background": {
+      "type": "raw-blur",
+      "blur": 28,
+      "overlay": {
+        "color": "#020617",
+        "opacity": 0.22
+      }
+    },
+    "titleColor": "#FFFFFF",
+    "subtitleColor": "#E5E7EB"
+  },
+  "targets": ["iphone-6.5"],
+  "locales": ["zh-Hans"],
+  "frames": [
+    {
+      "name": "01_home",
+      "raw": "raw/{locale}/01_home.png",
+      "title": "首页信息一眼看清",
+      "subtitle": "背景自动取自当前页面截图"
+    }
+  ]
+}
+```
+
+##### 多层背景 stack
+
+`stack` 会从下到上叠加背景层。它适合把渐变、图片纹理、遮罩组合在一起，做出更稳定的品牌视觉。
+
+```json
+{
+  "defaults": {
+    "background": {
+      "type": "stack",
+      "layers": [
+        {
+          "type": "linear-gradient",
+          "angle": 180,
+          "stops": [
+            { "offset": 0, "color": "#EFF6FF" },
+            { "offset": 1, "color": "#DBEAFE" }
+          ]
+        },
+        {
+          "type": "image",
+          "src": "backgrounds/noise.png",
+          "fit": "cover",
+          "opacity": 0.12,
+          "blend": "overlay"
+        },
+        {
+          "type": "solid",
+          "color": "#FFFFFF",
+          "opacity": 0.08
+        }
+      ]
+    },
+    "titleColor": "#0F172A",
+    "subtitleColor": "#475569"
+  },
+  "targets": ["iphone-6.5"],
+  "locales": ["zh-Hans"],
+  "frames": [
+    {
+      "name": "01_home",
+      "raw": "raw/{locale}/01_home.png",
+      "title": "首页信息一眼看清",
+      "subtitle": "柔和渐变叠加纹理背景"
+    }
+  ]
+}
+```
+
+`blend` 当前支持 `over`、`multiply`、`screen`、`overlay`、`darken`、`lighten`、`soft-light`、`hard-light`。如果只是轻微叠加纹理，通常使用 `overlay` 并把 `opacity` 控制在 `0.08` 到 `0.18` 之间。
+
+##### 背景预设 preset
+
+如果多张图需要复用同一套背景，不建议在每个 frame 里复制长配置。可以先在 `defaults.backgroundPresets` 定义预设，再通过 `defaults.backgroundPreset` 或 `frames[].backgroundPreset` 引用。
+
+```json
+{
+  "version": 1,
+  "platform": "ios",
+  "defaults": {
+    "backgroundPresets": {
+      "blue-soft": {
+        "type": "linear-gradient",
+        "angle": 180,
+        "stops": [
+          { "offset": 0, "color": "#EFF6FF" },
+          { "offset": 1, "color": "#DBEAFE" }
+        ]
+      },
+      "dark-poster": {
+        "type": "image",
+        "src": "backgrounds/dark-poster.png",
+        "fit": "cover",
+        "overlay": {
+          "color": "#020617",
+          "opacity": 0.32
+        }
+      }
+    },
+    "backgroundPreset": "blue-soft",
+    "titleColor": "#0F172A",
+    "subtitleColor": "#475569"
+  },
+  "targets": ["iphone-6.5"],
+  "locales": ["zh-Hans"],
+  "frames": [
+    {
+      "name": "01_home",
+      "raw": "raw/{locale}/01_home.png",
+      "title": "快速完成估价",
+      "subtitle": "使用默认 blue-soft 背景"
+    },
+    {
+      "name": "02_detail",
+      "raw": "raw/{locale}/02_detail.png",
+      "title": "详情信息完整展示",
+      "subtitle": "单张图切换为 dark-poster 背景",
+      "backgroundPreset": "dark-poster",
+      "titleColor": "#FFFFFF",
+      "subtitleColor": "#E2E8F0"
+    }
+  ]
+}
+```
+
+也可以使用对象形式引用预设：
+
+```json
+{
+  "frames": [
+    {
+      "name": "01_home",
+      "raw": "raw/{locale}/01_home.png",
+      "background": {
+        "type": "preset",
+        "name": "blue-soft"
+      }
+    }
+  ]
+}
+```
+
+##### 多语言和多设备配置
+
+`targets` 和 `locales` 会做笛卡尔组合。下面配置会输出 `2 个设备 × 2 个语言 × 2 个页面 = 8 张图`。
+
+```json
+{
+  "version": 1,
+  "platform": "ios",
+  "defaults": {
+    "backgroundPreset": "blue-soft",
+    "backgroundPresets": {
+      "blue-soft": {
+        "type": "linear-gradient",
+        "angle": 180,
+        "stops": [
+          { "offset": 0, "color": "#F8FAFC" },
+          { "offset": 1, "color": "#DBEAFE" }
+        ]
+      }
+    }
+  },
+  "targets": ["iphone-6.9", "iphone-6.5"],
+  "locales": ["zh-Hans", "en-US"],
+  "frames": [
+    {
+      "name": "01_home",
+      "raw": "raw/{locale}/01_home.png",
+      "title": "快速完成估价",
+      "subtitle": "关键流程清晰可见"
+    },
+    {
+      "name": "02_detail",
+      "raw": "raw/{locale}/{target}/02_detail.png",
+      "title": "详情信息完整展示",
+      "subtitle": "不同设备可使用不同原图"
+    }
+  ]
+}
+```
+
+对应的原图目录可以这样组织：
+
+```text
+raw/
+  zh-Hans/
+    01_home.png
+    iphone-6.9/
+      02_detail.png
+    iphone-6.5/
+      02_detail.png
+  en-US/
+    01_home.png
+    iphone-6.9/
+      02_detail.png
+    iphone-6.5/
+      02_detail.png
+```
+
+##### 单张图只对指定语言或设备生效
+
+`frames[].target` 和 `frames[].locale` 可以限制某一张图只在指定组合下输出。下面示例中，`03_ipad_dashboard` 只会输出 iPad 图，`04_cn_campaign` 只会输出中文图。
+
+```json
+{
+  "targets": ["iphone-6.5", "ipad-13"],
+  "locales": ["zh-Hans", "en-US"],
+  "frames": [
+    {
+      "name": "01_home",
+      "raw": "raw/{locale}/01_home.png",
+      "title": "快速完成估价"
+    },
+    {
+      "name": "03_ipad_dashboard",
+      "raw": "raw/{locale}/ipad-dashboard.png",
+      "title": "大屏数据总览",
+      "target": "ipad-13"
+    },
+    {
+      "name": "04_cn_campaign",
+      "raw": "raw/zh-Hans/campaign.png",
+      "title": "中文专属活动页",
+      "locale": "zh-Hans",
+      "background": {
+        "type": "linear-gradient",
+        "angle": 135,
+        "stops": [
+          { "offset": 0, "color": "#FEF3C7" },
+          { "offset": 1, "color": "#F97316" }
+        ]
+      }
+    }
+  ]
+}
+```
+
+##### 完整示例
+
+下面是一份可以直接保存为 `screenshot.config.json` 的完整示例。它同时包含多设备、多语言、背景预设、图片背景、渐变背景和单张图覆盖配置。
+
+```json
+{
+  "version": 1,
+  "platform": "ios",
+  "defaults": {
+    "backgroundPresets": {
+      "soft-brand": {
+        "type": "stack",
+        "layers": [
+          {
+            "type": "linear-gradient",
+            "angle": 180,
+            "stops": [
+              { "offset": 0, "color": "#F8FAFC" },
+              { "offset": 0.5, "color": "#E0F2FE" },
+              { "offset": 1, "color": "#DBEAFE" }
+            ]
+          },
+          {
+            "type": "image",
+            "src": "backgrounds/noise.png",
+            "fit": "cover",
+            "opacity": 0.1,
+            "blend": "overlay"
+          }
+        ]
+      },
+      "poster": {
+        "type": "image",
+        "src": "backgrounds/{locale}/{frame}.png",
+        "fit": "cover",
+        "position": "center",
+        "overlay": {
+          "color": "#020617",
+          "opacity": 0.24
+        }
+      }
+    },
+    "backgroundPreset": "soft-brand",
+    "titleColor": "#0F172A",
+    "subtitleColor": "#475569",
+    "fontFamily": "Inter, Arial, sans-serif",
+    "orientation": "portrait",
+    "deviceWidthRatio": 0.76
+  },
+  "targets": ["iphone-6.9", "iphone-6.5"],
+  "locales": ["zh-Hans", "en-US"],
+  "frames": [
+    {
+      "name": "01_home",
+      "raw": "raw/{locale}/01_home.png",
+      "title": "快速完成估价",
+      "subtitle": "关键流程清晰可见",
+      "layout": "device-with-title-subtitle"
+    },
+    {
+      "name": "02_detail",
+      "raw": "raw/{locale}/{target}/02_detail.png",
+      "title": "详情信息完整展示",
+      "subtitle": "不同设备使用不同原图",
+      "layout": "device-with-title-subtitle"
+    },
+    {
+      "name": "03_story",
+      "raw": "raw/{locale}/03_story.png",
+      "title": "品牌故事完整呈现",
+      "subtitle": "这一页使用图片背景预设",
+      "backgroundPreset": "poster",
+      "titleColor": "#FFFFFF",
+      "subtitleColor": "#E2E8F0"
+    },
+    {
+      "name": "04_fullscreen",
+      "raw": "raw/{locale}/04_fullscreen.png",
+      "layout": "raw-fullscreen",
+      "rawFit": "cover"
+    }
+  ]
+}
+```
 
 尺寸和输出规则：
 
@@ -985,7 +1646,7 @@ ipa-cli assets manifest . --scope children --output ./assets-manifest.json
 能力说明如下：
 
 - 跨平台稳定可用：IPA 解包、`Info.plist` 解析、资源扫描、指纹 JSON 分析、相似度对比、图片哈希检测
-- macOS 上信号更完整：如果系统提供 `codesign`、`otool`、`nm`、`xcrun assetutil`，会补充 entitlements、Mach-O 高级信号、`Assets.car` 高级摘要
+- macOS 上信号更完整：如果系统提供 `codesign`、`otool`、`nm`、`xcrun assetutil`，会补充 entitlements、Mach-O 高级信号、`Assets.car` 高级摘要；可用 `ipa-cli doctor` 自检并查看安装建议
 - Linux / Windows 为受控降级：缺少 Apple 专有工具时，CLI 会标记相关能力为降级，但不会因为这些工具缺失而整体失败
 
 ## 当前边界