feat: expand AI workflow support and refresh docs

docs/AI智能套图方案v2.md

@@ -0,0 +1,405 @@
+# AI 智能套图方案 v2
+
+> 基于 v1 实践反馈的完整升级方案
+
+---
+
+## 1. 核心问题
+
+v1 方案对所有裁片都采用「逐片 crop → refine → place」的流程，存在以下问题：
+
+| 问题 | 影响 |
+|------|------|
+| 全身花型衣服每片单独生成，花型不连贯 | 效果差 |
+| 每片调用一次 AI，5 片衣服 = 5+ 次 API | 慢、贵 |
+| 左右袖花型不一致（AI 每次生成不同） | 效果差 |
+| AI 容易陷入 identify → preview 循环 | 流程卡住 |
+| 渐变花型无法正确还原 | 效果差 |
+
+---
+
+## 2. 服装花型分类
+
+### 2.1 按花型覆盖方式分
+
+| 模式 | 英文标识 | 说明 | 示例 |
+|------|---------|------|------|
+| **全身花型** | `all_over` | 所有裁片来自同一块面料 | 碎花连衣裙、格子衬衫、渐变花T |
+| **局部印花** | `placement` | 各部位独立处理 | 卡通卫衣（前片印花+袖子纯色） |
+| **纯色拼接** | `color_block` | 全部纯色，无花型 | 撞色 POLO 衫 |
+
+### 2.2 按花型特征分（全身花型的子分类）
+
+| 特征 | 说明 | 生图策略 |
+|------|------|---------|
+| **均匀铺满** | 碎花、波点、小格子 | 生成一个重复单元 → PS 图案填充 |
+| **大面积图案** | 大花、大格纹 | 生成一张大尺寸面料图 → 覆盖裁片 |
+| **渐变过渡** | 上深下浅、色彩渐变 | 生成一张带渐变的面料图 |
+| **方向性** | 条纹、斜纹 | 需要指定花型方向 |
+
+---
+
+## 3. 升级后的套图流程
+
+### 3.1 总流程
+
+```
+用户上传成衣图 + 点击"帮我套图"
+        │
+        ▼
+  ┌─────────────────┐
+  │  阶段 0: 智能分析  │  ← 新增
+  │  判断花型模式      │
+  │  all_over / placement / color_block
+  └────────┬────────┘
+           │
+     ┌─────┼──────┐
+     ▼     ▼      ▼
+  all_over  placement  color_block
+     │       │          │
+     ▼       ▼          ▼
+  阶段 1A   阶段 1B    直接填色
+  生成面料图 逐片生成    (不需要 AI 生图)
+     │       │
+     ▼       ▼
+   用户确认预览
+     │
+     ▼
+  阶段 2: 正式套图
+```
+
+### 3.2 all_over 模式（全身花型）
+
+```
+1. identify_pieces
+   → 返回 pattern_mode: "all_over"
+   → 返回花型描述（渐变方向、花型元素、色彩等）
+
+2. 生成面料图（1 次 AI 调用）
+   → 提示词包含：面料类型、花型方向、元素、色彩、密度
+   → 输出一张高清矩形面料图
+
+3. 预览：将面料图覆盖到所有裁片上
+   → 用户确认
+
+4. 正式套图：
+   → 同一张面料图 place 到每个裁片
+   → 每片只调整位置/缩放 + 剪切蒙版
+   → 左右袖：同一张图，右袖水平翻转
+   → 不需要 refine（已经是干净的面料图）
+```
+
+### 3.3 placement 模式（局部印花）
+
+```
+沿用 v1 的逻辑，但优化：
+1. identify_pieces
+   → 返回 pattern_mode: "placement"
+   → 每片的 type: solid / fill_pattern / theme_pattern / mixed_pattern
+
+2. 生成预览（1 次 AI 调用）
+
+3. 用户确认后，逐片处理：
+   → solid: PS 填色
+   → theme_pattern: 先放主题(白底+正片叠底) 再填底色
+   → fill_pattern: crop → refine → place
+   → mixed_pattern: 两层（花型底 + 主题白底）
+
+优化点：
+   → 左右对称片只处理一片，另一片复制+翻转
+   → 相同类型的片复用同一次 AI 结果
+```
+
+### 3.4 color_block 模式（纯色拼接）
+
+```
+最简单：
+1. identify_pieces → 所有片都是 solid + color
+2. 不需要生成预览
+3. 直接 PS 填色
+```
+
+---
+
+## 4. 提示词改进
+
+### 4.1 identify_pieces 提示词（新增 pattern_mode）
+
+```
+任务1 不变（识别裁片部位）
+
+任务2 改进：
+分析成衣的花型覆盖模式 pattern_mode：
+
+- "all_over"：所有裁片来自同一块面料（碎花/格子/渐变等整体花型）
+  → 需要额外描述：
+    - fabric_type: 数码印花/提花/梭织/针织
+    - pattern_direction: 均匀/上下渐变/左右渐变/斜向
+    - pattern_elements: 花朵/几何/条纹/格子/...
+    - color_transition: 从XX色渐变到XX色 / 无渐变
+    - density: 密集/稀疏/上密下疏/...
+
+- "placement"：各裁片独立（有的印花有的纯色）
+  → 每片单独分析 type
+
+- "color_block"：全部纯色拼接
+  → 每片给出 color
+
+输出 JSON 新增 pattern_mode 和 fabric_info 字段
+```
+
+### 4.2 全身花型的生图提示词
+
+```
+请根据这件成衣照片，生成一张高清面料花型平铺图。
+
+要求：
+1. 输出一张大的矩形花型图（不是裁片形状，而是一块平铺的面料）
+2. 面料类型：{fabric_type}
+3. 花型元素：{pattern_elements}
+4. 花型方向：{pattern_direction}
+5. 色彩过渡：{color_transition}
+6. 花型密度：{density}
+7. 去掉所有服装褶皱/阴影效果，呈现平铺面料的样子
+8. 图案要清晰、颜色准确、可以用于裁片套图
+9. 宽高比: {aspect_ratio}
+```
+
+### 4.3 局部印花的生图提示词（分 type 优化）
+
+| type | 提示词重点 |
+|------|-----------|
+| fill_pattern | 花型铺满矩形，保持连续无接缝 |
+| theme_pattern | 主题图案居中，纯白底(#FFF) |
+| mixed_fill | 只保留底纹，去掉主题图案 |
+| mixed_theme | 只保留主题图案，纯白底 |
+
+---
+
+## 5. 不可见部位的智能推理
+
+### 5.1 问题
+
+成衣照片通常只拍正面，**后片、内衬、侧面**等部位看不到。AI 不能瞎猜，需要根据前面的信息来推理。
+
+### 5.2 推理规则
+
+| 前片情况 | 后片推理 | 理由 |
+|---------|---------|------|
+| **全身花型**（碎花/格子/条纹） | 后片 = **同花型** | 同一块面料裁的，花型一样 |
+| **前片有大面积主题印花**（卡通/Logo） | 后片 = **纯色**（用底色） | 99% 的衣服背面不印主图 |
+| **前片纯色** | 后片 = **同色纯色** | 一样的颜色 |
+| **渐变花型** | 后片 = **同花型或纯色** | 看具体款式，需要让用户确认 |
+| **前片拼接**（上下不同花型） | 后片 = **取上半部分花型或底色** | 常见做法 |
+
+### 5.3 identify_pieces 输出新增字段
+
+```json
+{
+  "analysis": [
+    {
+      "layer": "组 4", "piece": "后片",
+      "type": "all_over",
+      "visible": false,
+      "inferred_from": "组 3",
+      "inference_reason": "全身花型面料，后片花型与前片相同",
+      "confidence": "high"
+    },
+    {
+      "layer": "组 4", "piece": "后片",
+      "type": "solid",
+      "visible": false,
+      "color": "#F5E6D0",
+      "inferred_from": "组 3",
+      "inference_reason": "前片为局部卡通印花，后片通常为底色纯色",
+      "confidence": "medium"
+    }
+  ]
+}
+```
+
+新增字段：
+- `visible`: 该部位在成衣照片中是否可见（false = AI 推理的）
+- `inferred_from`: 推理依据（哪个裁片）
+- `inference_reason`: 推理理由（中文，展示给用户）
+- `confidence`: 推理置信度（high/medium/low）
+
+### 5.4 用户确认环节
+
+当存在 `visible: false` 的裁片时，AI 应该**明确告诉用户**：
+
+```
+✅ 可见部位分析完成：
+- 组 1 左袖：黑底白花（主题图案）
+- 组 2 右袖：同左袖（镜像）
+- 组 3 前片：上半黑底大花 + 下半灰白格纹
+- 组 5 领口：纯黑色
+
+⚠️ 以下部位在照片中不可见，我根据经验推测：
+- 组 4 后片：推测与前片相同花型（全身印花面料）
+  → 如果后片其实是纯色，请告诉我
+
+请确认后我开始套图。
+```
+
+### 5.5 提示词中的推理指引
+
+```
+如果某个裁片在成衣照片中看不到（如后片、内衬）：
+1. 设置 visible: false
+2. 根据以下规则推理：
+   - 全身花型(all_over)：不可见部位使用相同花型
+   - 局部印花(placement)：不可见部位通常为底色纯色(solid)
+   - 纯色拼接(color_block)：不可见部位使用相同或相近颜色
+3. 给出推理理由和置信度
+4. 置信度为 low 时，必须让用户确认
+```
+
+---
+
+## 6. 镜像与复用优化
+
+### 5.1 左右对称片
+
+```
+识别到左袖+右袖时：
+→ 只生成左袖的花型
+→ 右袖 = 左袖的水平翻转（JSX flip）
+→ 省一次 AI 调用
+```
+
+### 5.2 前后片
+
+```
+如果前后片花型相同（all_over 模式下通常如此）：
+→ 同一张面料图 place 两次（不同位置）
+→ 不需要分别生成
+```
+
+### 5.3 相同纯色片
+
+```
+v1 已有颜色归一化（RGB 距离 < 40 视为相同）
+→ 保持
+```
+
+---
+
+## 6. System Prompt 优化
+
+### 6.1 防止 AI 循环调用
+
+```
+## 严格禁止
+- ❌ 预览生成后不要再次调用 identify_pieces
+- ❌ 不要在同一次对话中多次生成预览（除非用户明确要求重新生成）
+- ❌ 不要自作主张修改分析结果后重新执行（应该告诉用户发现的问题，让用户决定）
+
+## 流程纪律
+- 每个工具最多调用 1 次（除非上次失败）
+- identify_pieces → generate_preview → 等用户确认 → extract_and_apply_all_pieces
+- 这 4 步是固定顺序，不要跳步、不要回头
+```
+
+### 6.2 自我纠错的正确方式
+
+```
+如果在生成预览后发现分析可能有误：
+→ ✅ 告诉用户："我注意到袖口颜色可能判断有误，您要我重新分析吗？"
+→ ❌ 不要自己偷偷重新调用 identify_pieces
+```
+
+---
+
+## 7. identify_pieces 输出格式（v2）
+
+```json
+{
+  "pattern_mode": "all_over",
+  "fabric_info": {
+    "fabric_type": "数码印花",
+    "pattern_direction": "上下渐变",
+    "pattern_elements": "白色百合花朵",
+    "color_transition": "从黑色渐变到灰白格纹",
+    "density": "上部花朵密集，下部稀疏"
+  },
+  "mapping": {
+    "组 1": "左袖",
+    "组 2": "右袖",
+    "组 3": "领口",
+    "组 4": "前片",
+    "组 5": "后片"
+  },
+  "analysis": [
+    {"layer": "组 1", "piece": "左袖", "type": "all_over", "description": "黑底白花渐变"},
+    {"layer": "组 2", "piece": "右袖", "type": "all_over", "mirror_of": "组 1"},
+    {"layer": "组 3", "piece": "领口", "type": "solid", "color": "#000000"},
+    {"layer": "组 4", "piece": "前片", "type": "all_over", "description": "上半黑底花+下半灰白格纹"},
+    {"layer": "组 5", "piece": "后片", "type": "all_over", "description": "同前片"}
+  ],
+  "symmetric_pairs": [["组 1", "组 2"]],
+  "base_color": "#1A1A1A"
+}
+```
+
+新增字段：
+- `pattern_mode`: all_over / placement / color_block
+- `fabric_info`: 面料花型详细描述（仅 all_over 模式）
+- `mirror_of`: 标记镜像片（省一次 AI 调用）
+- `symmetric_pairs`: 对称片配对
+
+---
+
+## 8. 前端流程变化
+
+### 8.1 all_over 模式
+
+```
+extract_and_apply_all_pieces 新逻辑：
+
+1. 调用 AI 生成一张面料图（用 fabric_info 构建提示词）
+2. 下载面料图 → 保存临时文件
+3. 遍历每个裁片：
+   a. 纯色片 → PS 填色
+   b. all_over 片 → place 同一张面料图 + 缩放 + 剪切蒙版
+   c. mirror_of 片 → 复制已套好的图层 + 水平翻转
+4. 清除标签
+```
+
+### 8.2 placement 模式
+
+```
+保持 v1 逻辑 + 镜像优化：
+
+1. 遍历裁片，按 type 处理
+2. 遇到 mirror_of 片时，跳过 AI，复制+翻转
+3. 其余逻辑不变
+```
+
+---
+
+## 9. 实现优先级
+
+| 优先级 | 改动 | 预计工作量 |
+|--------|------|-----------|
+| **P0** | System Prompt 防循环 | 小（改提示词） |
+| **P0** | identify 返回 pattern_mode | 小（改提示词+解析） |
+| **P1** | all_over 模式生成面料图 | 中（新的生图逻辑） |
+| **P1** | all_over 模式一图套多片 | 中（改 extract 逻辑） |
+| **P2** | 镜像片优化（左右袖复用） | 小（JSX 复制+翻转） |
+| **P2** | placement 模式提示词细化 | 小 |
+| **P3** | 花型重复单元 → PS 图案填充 | 大（需要新的 JSX） |
+| **P3** | 前后片花型对齐 | 大 |
+
+---
+
+## 10. 对比总结
+
+| | v1（现在） | v2（升级后） |
+|---|---|---|
+| 花型模式识别 | 无，统一处理 | 自动判断 all_over/placement/color_block |
+| 全身花型 | 逐片生成（效果差） | 一张面料图覆盖所有片 |
+| AI 调用次数 | 每片 1-2 次 | all_over: 仅 1 次 |
+| 左右对称 | 分别生成（可能不一致） | 一次生成+镜像翻转 |
+| 流程稳定性 | AI 可能循环调用 | 严格单向流程 |
+| 渐变花型 | 无法正确还原 | 保留面料完整渐变 |