# Step 7：图片分析与分类

在生成新图片之前，先对每张原始图片进行深入分析，理解其用途和内容特征，从而为后续生成提供精准的策略指导。这一步不调用即梦 API，完全由 AI 基于已有数据和视觉能力完成。

## 前置读取

从任务目录读取以下文件：

1. **`meta.json`**：获取 `theme`（用户主题）
2. **`elements.json`**：仅筛选 `type: "image"` 和 `type: "slideshow"` 的元素
3. **`template-profile.json`**：仅读取以下字段：
   - `original_palette`：原模板色系特征（温度、饱和度、明度、对比）
   - `image_plan`：基于原模板推导出的图片调性约束文本
   - `layout_type`：排版类型（影响图片在构图中的角色定位）

这些信息用于在分析每张图片时同步记录"该图是否与原模板调性一致"，并作为 Step 8a 生成 prompt 时决定"延续原调性"还是"融入新主题"的依据。

---

从 elements 中筛选出所有 `type: "image"` 的元素，以及所有 `type: "slideshow"` 元素中 `assets` 数组里的每张图片，逐一进行分析和分类。

**处理顺序**：按元素在 `elements.json` 中出现的顺序处理，先独立 `image` 元素，再处理 `slideshow` 元素中的每张 `asset`。

> **轮播图片说明**：slideshow 元素的每张 asset 图片与普通 image 元素采用相同的分析流程。在后续展示和处理中，轮播图片以「轮播组件名称 > asset 标题」的格式标识其来源。

**⚠️ 并发限制**：图片视觉识别调用模型，存在并发限制，必须通过**子代理模式**逐张串行处理。主代理控制循环，每次仅启动一个子代理分析一张图片，等待其完全返回后再处理下一张。禁止并行启动多个子代理。

## Step 7.1：逐张分析（子代理模式）

对每张图片，使用**子代理**处理。子代理完成**一张图片的完整分析闭环**：三重信号收集 + 分类判定 + 结果返回。

### 子代理任务

> **子代理任务**：分析一张图片，返回分类结果。
>
> **输入参数**：
>
> - name: "{元素名称}"
> - width: {宽度}
> - height: {高度}
> - imageSrc: "{image.src URL}"
> - originalPalette: "{original_palette 摘要，如：中等饱和度/高明度/低对比/暖色温}"
>
> **参考数据**（内嵌到子代理指令中）：
>
> - 名称关键词表：
>   - 跳过：logo, Logo, LOGO, 品牌, 商标, brand, 二维码, qr, QR, qrcode, 扫码, 水印, watermark
>   - 背景：背景, bg, 底图, banner
>   - 人物：人物, 角色, 头像, 人像, avatar
>   - 装饰：装饰, 图标, icon, 插图, 分隔, 线条, 点缀
>   - 文字图：标题图, 文字, 书法, 艺术字
> - 尺寸规则：
>   - 大图：宽≥600 且 高≥400（或反之）→ 倾向背景（但透明背景除外，透明大图更可能是人物/装饰）
>   - 小图：任一边 < 200px → 倾向装饰/图标
>   - 极端比例：宽高比 > 3:1 或 < 1:3 → 可能是分隔条/装饰条
> - 分类优先级（从高到低，命中即停）：
>   1. **跳过保留**：name 匹配跳过关键词 OR 视觉为 logo/二维码/水印
>   2. **场景背景图**：name 匹配背景关键词 OR（大图 且 视觉为场景/纹理/渐变 且 **无透明背景**）
>   3. **人物/角色**：name 匹配人物关键词 OR 视觉主体为人物/角色 OR（**有透明背景** 且 视觉主体为人物/角色/卡通形象）
>   4. **文字类图片**：视觉主体为文字/书法/艺术字
>   5. **装饰/插图**：name 匹配装饰关键词 OR 小图 OR 视觉为小图形/图标 OR（**有透明背景** 且不属于以上）
>   6. **通用配图**：兜底
>
> **执行步骤**：
>
> 1. 从 name 匹配关键词表，记录名称信号
> 2. 从 width/height 判断尺寸信号
> 3. 查看 imageSrc 图片，识别以下特征：
>    - 图片主体内容（场景、人物、物体、文字、抽象图案等）
>    - **是否有透明背景**（重点检测）：URL 以 `.png` 结尾表示可能有 alpha 通道；视觉上背景呈棋盘格/无背景/主体"悬浮"；主体干净抠出无残留。**注意：大尺寸图片同样可能有透明背景**（如 750×1200 人物立绘 PNG）
>    - 是否为 logo 标识或二维码
>    - 整体风格（摄影、插画、扁平、卡通、水彩等）
>    - 主要颜色/色调
> 4. 综合三重信号，按分类优先级判定 category
> 5. 判断 tone_alignment（与 originalPalette 对比）：`aligned`（色调与模板主色系一致）或 `independent`（独立色系）
> 6. 判断 needs_transparent：透明背景图 或 人物/角色/装饰/文字类 → `true`；场景背景/跳过 → `false`
> 7. 返回结果
>
> **返回格式**（严格 JSON）：
>
> ```json
> {
>   "category": "场景背景图|人物/角色|文字类图片|装饰/插图|通用配图|跳过保留",
>   "visualDescription": "一句话描述原图内容和风格",
>   "toneAlignment": "aligned|independent",
>   "needsTransparent": true,
>   "hasTransparent": false,
>   "skip": false
> }
> ```

**⚠️ 串行约束**：必须等待当前子代理完全返回结果后，才能启动下一个子代理。

### 子代理返回后

子代理返回后，主代理**立即执行**以下操作：

1. **如果成功**（返回了有效 JSON）：
   - 基于元素的 `width` 和 `height` 计算原始宽高比，化简为最简整数比（如 750×1200 → `"5:8"`），记为 `ratio`
   - 将子代理返回的结果 + 计算得到的 `ratio` 一起暂存到内存中的结果数组
   - 向用户反馈：`✅ [{当前序号}/{总数}] {元素名称} → {分类}（{一句话描述}）`

2. **如果失败**（子代理报错或返回格式异常）：
   - 使用兜底分类：`category: "通用配图"`，`skip: false`
   - 向用户反馈：`⚠️ [{当前序号}/{总数}] {元素名称} → 分析失败，兜底为"通用配图"`

3. 如果后续还有未处理的图片：`🔄 正在分析下一张：{下一张元素名称}...`

## Step 7.2：汇总校验

所有子代理返回后，主代理对结果进行一致性检查：

- 确认每张图片都有有效的 `category`
- 确认每张图片都有有效的 `ratio`（从 width/height 计算得到的最简整数比，如 `"5:8"`、`"1:1"`、`"3:4"` 等）
- 校验 `hasTransparent` 与分类的逻辑一致性（见下方指引）
- 统计各分类数量，向用户反馈：`✅ 图片分析完成！跳过 X 张，待生成 Y 张。`

> **透明背景分类指引**：有透明背景的图片应优先被识别为人物/角色或装饰/插图，而非场景背景图。透明背景是一个强信号，表明该图片的设计意图是叠加在其他元素之上使用，而不是作为全覆盖的场景背景。即使图片尺寸较大（如 750×1200），只要有透明背景，就不应被归类为场景背景图。如果发现不一致，主代理应自动修正分类。

同时确认每张图片都记录了以下字段：

- `visualDescription`：一句话概括原图内容和风格，供 Step 8 生成 prompt 时参考
- `toneAlignment`：与 `template_profile.original_palette` 的关系
  - `aligned`：该图色调与模板主色系一致（饱和度/明度/色温接近），在 Step 8 应延续原调性
  - `independent`：该图是独立色系元素（如强调色点缀、与主色对比），在 Step 8 可融入新主题
- `needsTransparent`：如果原图有透明背景（`hasTransparent=true`），或者分类为人物/角色、装饰/插图、文字类图片，则设为 `true`；如果分类为场景背景图或跳过保留，则设为 `false`

## Step 7.3：展示分析报告

将所有图片的分析结果汇总为表格，展示给用户：

| #   | 元素名称          | 尺寸      | 是否透明 | 分类        | 原图内容描述       | 处理方式              |
| --- | ----------------- | --------- | -------- | ----------- | ------------------ | --------------------- |
| 1   | 背景图            | 750×1200  | ❌       | 🖼️ 场景背景 | 淡绿色渐变自然风景 | ✅ 重新生成           |
| 2   | 公司logo          | 120×120   | ✅       | 🏷️ Logo     | 企业标志           | ⏭️ 跳过（保留原图）   |
| 3   | 花朵装饰          | 80×80     | ✅       | 🎨 装饰元素 | 水彩花朵小图标     | ✅ 重新生成（需透明） |
| 4   | 二维码            | 200×200   | ❌       | 📱 二维码   | 微信二维码         | ⏭️ 跳过（保留原图）   |
| 5   | 人物插画          | 750×1200  | ✅       | 👤 人物角色 | 卡通人物立绘       | ✅ 重新生成（需透明） |
| 6   | 轮播图 > 高山.jpg | 1170×1800 | ❌       | 🖼️ 场景背景 | 高山风景照片       | ✅ 重新生成           |
| 7   | 轮播图 > 草地.jpg | 1170×1800 | ❌       | 🖼️ 场景背景 | 绿色草地风光       | ✅ 重新生成           |

> ⏸️ **交互点**：展示图片分析与分类结果表格，等待用户确认。用户可以：
>
> - 调整某张图片的分类（如将"通用配图"改为"场景背景"）
> - 将某些图片标记为"跳过"或取消跳过
> - 调整某张图片的"需要透明"标记（如取消不需要透明背景的图片的标记，或为遗漏的图片添加标记）
> - 确认后继续
>
> **必须等到用户确认后才能继续执行 Step 8a。**

## 后置写入

用户确认后，将分类结果写入任务目录的 `image-classifications.json`：

```json
{
  "summary": { "total": 7, "toGenerate": 5, "toSkip": 2 },
  "images": [
    {
      "elementId": "元素ID",
      "assetId": null,
      "name": "元素名称",
      "source": "image",
      "slideshowElementId": null,
      "width": 750,
      "height": 1200,
      "ratio": "5:8",
      "category": "场景背景图",
      "visualDescription": "淡绿色渐变自然风景",
      "toneAlignment": "aligned",
      "needsTransparent": false,
      "hasTransparent": false,
      "skip": false
    }
  ]
}
```

其中 `source` 为 `"image"` 或 `"slideshow"`，slideshow 内的 asset 需额外填写 `assetId` 和 `slideshowElementId`。

同时更新 `meta.json` 的 `currentStep` 为 `"07"`。