# 平台套图 Agent 协同引入实施方案

> 目标：在复用现有图片工作台、AITask、积分、Celery、Provider、Asset 和 TOS 的前提下，把当前“固定平台模板 + 按序批量生图”升级为能规划套图、选择参考素材、并行生成、逐图质检、定向补图并由用户采用的平台套图 Agent。  
> 架构原则：松耦合、高内聚、可复用、精简化、可扩展。  
> 代码基线审阅时间：2026-07-17。

## 1. 结论先行

平台套图 Agent 最适合做 AirShelf 的第一个视觉 Agent，但首期不应让多个视觉模型自由讨论。推荐采用：

```text
一个平台套图协调器
+ 确定性商品/平台上下文收集
+ 轻量套图规划节点
+ 参考图选择器
+ 提示词编译器
+ 现有图片生成工具
+ 独立视觉质检器
+ 失败槽位最多一次定向补图
+ 套图版本和人工采用
```

与当前链路相比，真正新增的 Agent 能力是：

1. 先形成完整套图计划，而不是按 index 固定轮换；
2. 检查真实商品参考图是否足够，不足时暂停而不是静默纯文生图；
3. 为每个槽位声明目标、参考图、构图、文字政策和验收规则；
4. 观察每张生成结果，结构化识别失败原因；
5. 只重试失败槽位，不整批重跑；
6. 保存套图版本、槽位关系和质检报告；
7. 用户确认后采用，不自动覆盖现有资产。

## 2. 当前代码基线与主要问题

### 2.1 当前链路

```text
ai-tools.tsx 选择商品、平台、张数、比例、模型、prompt
→ POST /api/ai/generate-image/ mode=cover
→ GenerateImageView
→ enqueue_standalone_images 创建 N 个 AITask
→ Celery run_standalone_image_task
→ 读取最多 3 张商品真实图
→ build_platform_cover_prompt_refs
→ index % 6 选择固定槽位
→ Seedream/GPT-Image 单张调用
→ Asset(category=platform_kit)
→ 前端轮询
```

### 2.2 当前缺口

1. 无真实商品参考图时会退到裸文生图，平台模板也可能没有进入最终 prompt；
2. 4/8/12 张是六槽位循环，不是针对商品和平台制定的内容计划；
3. 每张图彼此独立，不知道整套图是否重复或缺某类内容；
4. 生成成功只代表拿到图片，没有 OCR、商品一致性、平台规则和构图质检；
5. `Asset.metadata` 当前没有完整保存 platform_id、slot、plan、attempt；
6. 平台归属主要在 `AITask.request_payload`，资产脱离任务后可追溯性不足；
7. 页面选择的模型和最终 provider 在部分场景可能不完全一致；
8. 纯文本分支未明确把 ratio 对应尺寸传给 provider；
9. 批次只有 batch_id，不是可采用、可版本化的业务套图实体；
10. 重跑缺少基于失败原因的定向修复。

## 3. 改造边界

### 3.1 必须复用

| 能力 | 当前代码 | 新 Agent 用法 |
| --- | --- | --- |
| 商品与图片 | Product、ProductImage、cover_asset | 通过工具读取真实参考图和快照 |
| 平台规则 | `_PLATFORM_NAMES`、`_PLATFORM_COVER_BLOCKS` | 抽成版本化规则服务 |
| 槽位规则 | `_COVER_SLOTS` | 作为默认策略，不再直接由 index 决定 |
| 提示词基础 | `build_platform_cover_prompt_refs()` | 拆成可测试的 PromptCompiler |
| 图片模型路由 | `resolve_image_model()`、ModelConfig | 包装成 capability router |
| 单图任务 | `enqueue_standalone_images()`、`AITask` | 提供单槽位生成工具，保留计费 |
| Worker | `run_standalone_image_task()` | 继续负责 Provider、TOS、Asset 和退款 |
| 图片资产 | Asset、AssetFile | 保存每个槽位的候选图 |
| 会话/页面 | ImageConversation、ai-tools.tsx | 保留入口和历史，增加套图运行视图 |
| 异步基础 | Celery、轮询、僵尸回收 | 继续复用 |

### 3.2 本次不做

- 不自动发布到淘宝、抖音等外部平台；
- 不自动修改商品事实、价格和认证；
- 不无限生成到“满意为止”；
- 不把图片二进制或长 Base64 保存进 Agent 表；
- 不重新实现图片 Provider、资产库、积分和对象存储；
- 不让视觉 Agent 直接执行 ORM 或任意外部请求；
- 不用同一个生成模型无约束地给自己打高分；
- 首期不做跨平台营销效果预测。

## 4. 五项架构原则如何落地

| 原则 | 落地方式 | 禁止做法 |
| --- | --- | --- |
| 松耦合 | 协调器依赖工具和 `PlatformKitPlan` 契约；生成器、OCR、视觉评估可替换 | 在 Coordinator 中直接 import Seedream Provider |
| 高内聚 | 平台计划、槽位、规则、提示词、评估都在 platform_kit 领域模块 | 把视觉规则继续堆进通用 `services.py` |
| 可复用 | AgentRun/Step、预算、路由、工具、并发、事件与脚本 Agent 共用 | 平台套图复制一套 Agent 基础设施 |
| 精简化 | 固定 DAG，计划一次、每槽生成一次、失败槽最多补一次 | 首期上通用多 Agent 对话框架 |
| 可扩展 | 平台规则、计划、提示词、rubric 全部有版本 | 通过 if/else 隐式依赖页面文案 |

## 5. 推荐代码结构

公共 `apps/agents` 基础设施与脚本 Agent 复用，只新增平台领域目录：

```text
core/backend/apps/agents/
├─ models.py / runtime.py / registry.py / policies.py
├─ routing.py / permissions.py / events.py
├─ tools/
│  ├─ product.py
│  ├─ assets.py
│  ├─ models.py
│  ├─ billing.py
│  └─ image_generation.py
├─ schemas/
│  ├─ common.py
│  └─ platform_kit.py
└─ platform_kit/
   ├─ coordinator.py          # 固定 DAG/状态机
   ├─ context.py              # 商品、平台、参考图快照
   ├─ rules.py                # 从 services.py 抽出的平台规则
   ├─ planner.py              # 生成 PlatformKitPlan
   ├─ plan_validator.py       # 数量、平台、文字政策、槽位覆盖
   ├─ reference_selector.py   # 每槽参考图选择
   ├─ prompt_compiler.py      # PlanSlot → ImageGenerationSpec
   ├─ generator.py            # 调用受控单图工具
   ├─ evaluator.py            # OCR + 视觉评估 + 规则汇总
   ├─ repair.py               # issue_code → 定向补图 spec
   ├─ handoff.py              # 套图版本/结果交接
   └─ prompt_versions.py
```

平台套图是独立业务产物，建议在图片/资产领域增加：

```text
core/backend/apps/assets/
├─ models.py                  # PlatformKitVersion / PlatformKitItem
├─ serializers.py
└─ services/platform_kit.py   # 保存、采用、版本查询
```

前端：

```text
core/frontend/src/
├─ routes/ai-tools.tsx                    # 保留入口，接 AgentRun
└─ components/platform-kit-agent/
   ├─ kit-plan.tsx                        # 套图计划与槽位
   ├─ slot-card.tsx                       # 单槽进度/候选/问题
   ├─ evaluation-badge.tsx                # 质检状态
   ├─ repair-confirm.tsx                  # 补图报价和确认
   └─ kit-review.tsx                      # 整套采用
```

## 6. 为什么需要独立套图领域实体

AgentRun 表示“执行过程”，Asset 表示“单张图片”，两者都不适合作为一套平台图的长期业务真相源。建议新增：

### 6.1 PlatformKitVersion

```text
id
team_id
product_id
platform_id
version
status                  draft / ready / adopted / rejected
requested_count
ratio
plan_schema_version
plan_snapshot
platform_rule_version
product_snapshot_hash
agent_run_id
created_by_id
is_adopted
created_at/updated_at
```

### 6.2 PlatformKitItem

```text
id
kit_version_id
slot_id                 稳定业务 ID，例如 hero-01
slot_type               hero/scene/selling/detail/multi/promo/custom
order
goal
status                  planned/generating/evaluating/passed/
                        warning/failed/retrying/rejected
selected_asset_id       最终候选，可空
generation_task_id      当前 AITask，可空
attempt_count
prompt_snapshot
reference_snapshot
evaluation_report
created_at/updated_at
```

一个 Item 可通过 AgentArtifact 关联多个候选 Asset；`selected_asset_id` 指向最终保留图。这样可以：

- 精确知道整套图还缺哪个槽位；
- 只补失败项；
- 保留同槽位多个版本；
- 一键采用完整套图；
- 未来供商品详情页、导出、投放和分析直接消费；
- Agent 运行结束后仍保留业务结构。

## 7. 输入契约

### 7.1 `PlatformKitAgentRequest/v1`

```json
{
  "schema_version": "platform-kit-agent-request/v1",
  "product_id": "uuid",
  "platform_id": "douyin",
  "count": 4,
  "ratio": "1:1",
  "instruction": "整体真实自然，突出轻便和易清洗",
  "selected_selling_point_ids": ["uuid"],
  "reference_asset_ids": [],
  "text_policy": "minimal | no_text | short_labels",
  "model_policy": {
    "mode": "explicit | auto",
    "model_config_id": null,
    "quality": "production",
    "cost_ceiling_points": 120
  },
  "repair_policy": {
    "max_attempts_per_slot": 2,
    "auto_repair_below_points": 15
  },
  "idempotency_key": "uuid"
}
```

前端继续提供现有 4/8/12 快捷数量，但后端契约不应依赖页面文案；允许范围由策略配置决定。首期为降低复杂度可先只开放 4 张，稳定后再恢复 8/12 张的智能规划。

### 7.2 `PlatformKitContextSnapshot/v1`

```json
{
  "product": {
    "id": "...",
    "updated_at": "...",
    "title": "...",
    "brand": "...",
    "category": "...",
    "facts": ["..."],
    "selected_selling_points": ["..."],
    "reference_assets": [
      {
        "asset_id": "...",
        "url": "...",
        "source": "upload",
        "is_ai_generated": false,
        "view": "front",
        "width": 1600,
        "height": 1600,
        "checksum": "..."
      }
    ]
  },
  "platform": {
    "id": "douyin",
    "name": "抖音",
    "rule_version": "douyin/v1",
    "layout_policy": {},
    "forbidden": []
  },
  "generation": {
    "count": 4,
    "ratio": "1:1",
    "text_policy": "minimal"
  }
}
```

参考图必须冻结 asset_id、文件 URL、checksum 和来源。执行期间资产被替换或删除时，运行应停止/标记 stale，不能静默改用其他图。

## 8. 协作节点与职责

| 节点 | 类型 | 输入 | 输出 | 模型调用 |
| --- | --- | --- | --- | --- |
| PlatformKitCoordinator | 状态机 | AgentRun | 下一步骤和并发控制 | 否 |
| ContextCollector | 工具组合 | request | ContextSnapshot、缺失项 | 否 |
| ReferenceInspector | 规则/可选视觉 | 参考资产 | 可用性和角色 | 首期规则，可选视觉 |
| KitPlanner | 规划器 | 商品事实、平台规则 | PlatformKitPlan | 可规则或文本模型一次 |
| PlanValidator | 规则引擎 | Plan、规则 | 错误/警告 | 否 |
| ReferenceSelector | 规则引擎 | slot、候选图 | 每槽参考图列表 | 否 |
| PromptCompiler | 领域服务 | slot、上下文 | ImageGenerationSpec | 否 |
| ImageGenerator | 业务工具 | spec | AITask/Asset | 图片模型，每槽一次 |
| ImageEvaluator | OCR/视觉评估 | Asset、rubric | EvaluationReport | OCR + 可选视觉模型 |
| RepairPlanner | 规则引擎 | issue codes、原 spec | RepairSpec | 首期否 |
| KitPersister | 领域服务 | plan/items | PlatformKitVersion | 否 |
| HandoffBuilder | 领域服务 | adopted kit | PlatformKitHandoff | 否 |

节点之间只传结构化 ID 和小型 JSON；图片通过 Asset ID/URL 引用，不把图片内容塞进 AgentStep。

## 9. 固定协同 DAG

```mermaid
flowchart TD
    A[收集商品/平台/模型上下文] --> B{真实商品参考图足够?}
    B -- 否 --> C[等待用户补图]
    C --> A
    B -- 是 --> D[形成套图计划]
    D --> E[确定性校验计划]
    E -- 不通过 --> F[修正规划或等待用户]
    F --> D
    E -- 通过 --> G[报价与预算确认]
    G --> H[为每个槽位选择参考图并编译 spec]
    H --> I[受控并行生成各槽位]
    I --> J[逐图 OCR/视觉质检]
    J --> K{所有必需槽位可用?}
    K -- 是 --> L[保存 ready 套图版本]
    K -- 否且可修复/有预算 --> M[仅失败槽位生成 RepairSpec]
    M --> N[失败槽位补图一次]
    N --> J
    K -- 否且达上限 --> O[带问题进入人工审核]
    L --> P[用户采用/替换单槽]
    O --> P
    P --> Q[生成平台套图交接包]
```

这里不是自由循环：每个槽位默认 1 次生成，最多 1 次自动补图；到上限立即停止并展示问题。

## 10. 上下文和参考图策略

### 10.1 参考图硬门槛

平台套图的核心是商品真实一致性，因此 Agent 模式必须取消当前“无商品图退到纯文生图”的静默降级：

```text
无可用真实商品图
→ waiting_user
→ 提示上传正面/侧面/细节图
→ 不创建付费图片任务
```

可配置最小要求：

- 普通包装/单品：至少 1 张清晰正面图；
- 有背面信息：建议正反 2 张；
- 服装/立体商品：建议正面 + 侧面/细节；
- 参考图必须排除 AI 生成图或明确标记为低可信辅助图。

### 10.2 参考图角色

```json
{
  "asset_id": "...",
  "role": "identity_lock | detail_reference | angle_reference | style_reference",
  "priority": 1,
  "allowed_slots": ["hero", "detail"],
  "must_preserve": ["包装形状", "品牌文字", "主色", "Logo"]
}
```

首期由元数据和用户选择确定角色；视觉识别成熟后可辅助判断角度和清晰度，但不能自动认定 AI 图为真实商品事实。

## 11. 平台规则服务

把当前 `services.py` 中以下常量迁移/封装为 `PlatformRuleProvider`：

- `_PLATFORM_NAMES`；
- `_PLATFORM_COVER_BLOCKS`；
- `_COVER_SLOTS`；
- `_COVER_LOW_DENSITY`；
- `_COVER_BG_CONTRAST`；
- `_COVER_NEGATIVE`。

接口：

```python
class PlatformRuleProvider:
    def get(self, platform_id: str, version: str | None = None) -> PlatformRule:
        ...
```

`PlatformRule/v1`：

```json
{
  "platform_id": "douyin",
  "version": "douyin/v1",
  "visual_tone": ["强视觉抓力", "短视频封面感"],
  "composition_rules": ["主体清晰", "信息密度低"],
  "text_policy": {"max_short_labels": 2, "allow_price": false},
  "required_checks": ["product_identity", "text_accuracy", "logo_safety"],
  "forbidden": ["二维码", "虚假价格", "平台 Logo", "绝对化功效"]
}
```

首期规则仍可存在 Python 配置中，但必须通过 Provider 接口读取并记录版本。以后迁数据库或管理后台，不影响 Planner/Compiler。

## 12. 套图规划契约

### 12.1 `PlatformKitPlan/v1`

```json
{
  "schema_version": "platform-kit-plan/v1",
  "platform_id": "douyin",
  "platform_rule_version": "douyin/v1",
  "product_snapshot_hash": "...",
  "creative_direction": "真实家庭场景，突出轻便和易清洗",
  "global_constraints": {
    "ratio": "1:1",
    "product_area_percent": [60, 80],
    "text_policy": "minimal",
    "identity_fields": ["shape", "color", "material", "logo", "label_text"]
  },
  "slots": [
    {
      "slot_id": "hero-01",
      "slot_type": "hero",
      "order": 1,
      "goal": "一眼看清商品并建立品牌记忆",
      "selling_point_ids": [],
      "composition": "正面主视觉，商品居中，背景简洁",
      "reference_roles": ["identity_lock"],
      "text_policy": "no_text",
      "acceptance": ["主体完整", "Logo 不变", "无多余商品"]
    },
    {
      "slot_id": "selling-01",
      "slot_type": "selling",
      "order": 2,
      "goal": "表达易清洗",
      "selling_point_ids": ["uuid"],
      "composition": "使用前后场景，但不做拼贴详情页",
      "reference_roles": ["identity_lock", "detail_reference"],
      "text_policy": "short_labels",
      "acceptance": ["只表达有事实来源的卖点"]
    }
  ]
}
```

### 12.2 Planner 的首期实现

为了精简和稳定，建议两级策略：

- **MVP：确定性 Planner。**根据数量、平台和卖点从可配置槽位模板中选取，避免 LLM 费用；
- **增强版：文本 Planner。**只负责创意方向和槽位组合，输出 Plan JSON；PlanValidator 必须检查并修正硬规则。

即使启用文本 Planner，也不能直接生成图片或更改商品事实。

### 12.3 PlanValidator

- platform_id 和规则版本有效；
- slot 数量等于请求 count；
- slot_id 唯一、order 连续；
- hero 等必需槽位存在；
- selling slot 使用的卖点 ID 来自快照；
- 文字政策不超过平台规则；
- ratio 被模型能力支持；
- 每个槽位有参考角色和 acceptance；
- 禁止多个槽位完全重复目标和构图；
- 8/12 张不得简单复制六槽位文本。

## 13. 提示词编译器

当前 `build_platform_cover_prompt_refs()` 应拆成纯函数：

```python
compile_platform_image_spec(
    context: PlatformKitContextSnapshot,
    plan: PlatformKitPlan,
    slot: PlatformKitSlot,
    references: list[ReferenceSpec],
    model_capabilities: ModelCapabilities,
) -> ImageGenerationSpec
```

### 13.1 `ImageGenerationSpec/v1`

```json
{
  "schema_version": "image-generation-spec/v1",
  "agent_run_id": "...",
  "kit_version_id": "...",
  "slot_id": "selling-01",
  "attempt": 1,
  "capability": {
    "multi_reference": true,
    "ratio": "1:1",
    "quality": "production"
  },
  "reference_asset_ids": ["...", "..."],
  "reference_roles": ["identity_lock", "detail_reference"],
  "prompt": "编译后的最终提示词",
  "negative_constraints": ["禁止二维码", "禁止虚假价格"],
  "acceptance_rubric": ["product_identity", "text_accuracy", "slot_goal"],
  "idempotency_key": "run:slot:attempt"
}
```

### 13.2 最终 prompt 分层

```text
[输入数据声明]
参考图是同一真实商品，只用于商品身份和细节事实。

[身份锁定]
形状、颜色、材质、包装、Logo、标签文字、结构不可改变。

[平台规则]
来自 PlatformRule/version。

[整套方向]
来自 PlatformKitPlan.global_constraints。

[本槽位目标]
slot.goal + composition + selling points。

[文字政策]
no_text/minimal/short_labels；文字只能来自事实快照。

[背景与构图]
主体比例、对比、镜头、光线。

[用户补充]
可影响创意，但不能覆盖事实和禁止项。

[负面约束]
平台禁用项、商品畸变、重复主体、乱码等。
```

PromptCompiler 只做编译，不调用模型、不查数据库，便于单元测试和复用于补图。

## 14. 模型路由与禁止静默降级

Agent 声明需求：

```json
{
  "capability": "image",
  "requires": {
    "multi_reference": true,
    "reference_count": 3,
    "ratio": "1:1",
    "image_edit_or_reference_generation": true
  },
  "preferences": {
    "quality": "production",
    "cost_ceiling_points_per_image": 20
  }
}
```

路由器：

1. 读取启用的 ModelConfig；
2. 过滤不支持参考图、数量、比例的模型；
3. 检查团队权限、余额、并发和 provider 健康；
4. 用户明确模型时验证能力，不满足则报错；
5. 自动模式按质量、历史通过率、延迟和价格排序；
6. 返回实际模型、调用方式、预计费用和决策摘要。

严格禁止：

- 需要真实商品参考却回退纯文生图；
- ratio 不支持时静默用默认比例；
- 用户明确选模型却无提示切换；
- 多参考接口失败后丢掉部分参考图继续生成；
- 高质量档静默降为低能力模型仍标记成功。

## 15. 生成工具适配

建议在不破坏现有 API 的前提下，从 `enqueue_standalone_images()` 拆出更细粒度服务：

```python
enqueue_standalone_image_spec(
    team,
    user,
    spec: ImageGenerationSpec,
    model_config,
) -> AITask
```

它继续复用：

- quote/reserve；
- AITask；
- Celery `generate_standalone_image_task`；
- Provider 调用；
- TOS；
- Asset/AssetFile；
- 成功扣费与失败退款；
- 僵尸任务回收。

Worker 读取已经编译好的 prompt 和 reference_asset_ids，不再在执行时根据 mode/index 重新猜平台槽位。这样规划与执行解耦，重试可以精确复现输入。

输出 Asset metadata 至少增加：

```json
{
  "mode": "cover",
  "product_id": "...",
  "platform_id": "douyin",
  "batch_id": "...",
  "agent_run_id": "...",
  "kit_version_id": "...",
  "slot_id": "selling-01",
  "slot_type": "selling",
  "attempt": 1,
  "plan_version": "platform-kit-plan/v1",
  "platform_rule_version": "douyin/v1"
}
```

## 16. 并发策略

平台套图内部可以并行，但必须受控：

- 先为整套完成报价和预算确认；
- 每个槽位一个 AITask；
- 同一 Run 最大图片并发建议 2–3；
- 同团队仍受全局图片并发限制；
- 计划、参考选择和 PromptCompiler 完成后才 fan-out；
- fan-in 等待所有必需槽位达到终态；
- 某槽失败不取消其他成功槽；
- 恢复时查询原 task_id，不重复 enqueue；
- 补图只创建失败槽的新 attempt。

## 17. 视觉质检协同

### 17.1 质检分层

```text
第 1 层：确定性文件检查
→ 文件可读、尺寸、比例、空图、重复文件

第 2 层：OCR/文字规则
→ 乱码、虚假价格、平台 Logo、二维码、文字数量、已知品牌文字

第 3 层：视觉评估模型
→ 商品身份、颜色/形状、Logo、主体完整、构图、槽位目标、平台风格

第 4 层：整套规则
→ 槽位覆盖、重复度、视觉一致性、缺图

第 5 层：人工采用
```

生成模型和视觉评估模型应尽量解耦；至少使用不同提示角色和确定性规则共同裁决，不能只相信“模型给自己 95 分”。

### 17.2 `ImageEvaluationReport/v1`

```json
{
  "schema_version": "image-evaluation/v1",
  "asset_id": "...",
  "slot_id": "selling-01",
  "passed": false,
  "score": 68,
  "dimensions": {
    "product_identity": 2,
    "composition": 4,
    "text_accuracy": 5,
    "platform_fit": 4,
    "slot_goal": 3
  },
  "issues": [
    {
      "code": "PRODUCT_COLOR_CHANGED",
      "severity": "error",
      "repairable": true,
      "evidence": "商品主体由浅蓝变为深蓝",
      "repair_hint": "强化参考图1颜色锁定，禁止改变主色"
    }
  ],
  "evaluator": {
    "rules_version": "platform-kit-rubric/v1",
    "model_config_id": "可选",
    "ocr_engine": "..."
  }
}
```

标准失败码建议：

```text
PRODUCT_IDENTITY_MISMATCH
PRODUCT_COLOR_CHANGED
PRODUCT_SHAPE_CHANGED
LOGO_OR_LABEL_CHANGED
EXTRA_PRODUCT
PRODUCT_CROPPED
TEXT_GARBLED
UNSUPPORTED_CLAIM
QR_OR_PLATFORM_LOGO
WRONG_RATIO
SLOT_GOAL_MISSED
PLATFORM_RULE_VIOLATION
DUPLICATE_COMPOSITION
LOW_VISUAL_QUALITY
```

## 18. 定向补图

`RepairPlanner` 根据 issue_code 修改 spec，而不是让模型笼统“重新生成更好”：

| issue_code | 修复动作 |
| --- | --- |
| PRODUCT_COLOR_CHANGED | 提升 identity reference 优先级，加入精确颜色锁定 |
| LOGO_OR_LABEL_CHANGED | 强化标签不可重绘；必要时改为 no_text 场景 |
| EXTRA_PRODUCT | 明确单主体、禁止复制 |
| PRODUCT_CROPPED | 调整商品占比和安全边距 |
| TEXT_GARBLED | 删除生成文字或只允许短事实标签 |
| WRONG_RATIO | 修正 size，并要求 provider 能力确认 |
| SLOT_GOAL_MISSED | 保持商品锁定，只改构图和槽位描述 |
| DUPLICATE_COMPOSITION | 指定不同镜头/场景，保留整套方向 |

补图规则：

- 默认每槽最多 2 个 attempt；
- 仅错误级问题触发自动补图，警告可交给用户；
- 自动补图费用低于阈值才执行，否则 waiting_approval；
- 新图必须重新完整质检；
- 原图不删除，作为候选和审计保留；
- 第二次仍失败则停止，不递归。

## 19. 整套质检与采用

单图通过后还需检查：

- 必需槽位是否齐全；
- 是否有多个槽位构图高度重复；
- 商品颜色、包装和 Logo 是否跨图一致；
- 平台规则和全局文字政策是否统一；
- 每个选定卖点是否至少有一个槽位承接；
- 整套比例、视觉方向和数量是否一致。

用户可：

- 采用整套；
- 替换某槽候选；
- 手动保留带 warning 的图；
- 请求单槽补图；
- 拒绝整个版本。

采用通过 `assets/services/platform_kit.py` 完成事务：旧版本取消 adopted，新版本 adopted，Item 的 selected_asset 固定。Agent 无权直接更新这些字段。

## 20. API 设计

```http
POST /api/platform-kit-agent-runs/
GET  /api/agent-runs/{run_id}/
GET  /api/agent-runs/{run_id}/steps/
GET  /api/platform-kits/{kit_version_id}/
POST /api/agent-runs/{run_id}/actions/
POST /api/platform-kits/{kit_version_id}/adopt/
```

创建请求使用 `PlatformKitAgentRequest/v1`。

动作：

```json
{"action": "provide_references", "asset_ids": ["..."]}
{"action": "approve_budget"}
{"action": "approve_repair", "slot_ids": ["selling-01"]}
{"action": "retry_slot", "slot_id": "hero-01", "instruction": "..."}
{"action": "select_candidate", "slot_id": "hero-01", "asset_id": "..."}
{"action": "cancel"}
```

旧 `/api/ai/generate-image/ mode=cover` 保留为普通批量生成回退；Agent 入口使用独立 API，避免给旧请求强加复杂状态。

## 21. 前端交互

不把平台套图页改成纯聊天。推荐三栏/三阶段信息：

1. **输入与计划**：商品、平台、参考图、卖点、套图方向、槽位列表、报价；
2. **执行过程**：每槽计划 → 生成 → 质检 → 补图的真实状态；
3. **结果审核**：每槽候选、问题证据、费用、整套采用。

必须展示：

- 实际调用模型，不只展示用户初始选择；
- 参考图不足时明确阻塞；
- 每张图属于哪个槽位；
- 失败是生成失败还是质检失败；
- 补图只补哪张、预计增加多少积分；
- warning 图由用户决定是否采用。

## 22. AgentRun/AgentStep 映射

示例：

```text
AgentRun(platform_kit)
├─ Step 1 collect_context
├─ Step 2 inspect_references
├─ Step 3 plan_kit
├─ Step 4 validate_plan
├─ Step 5 quote
├─ Step 6 persist_kit_version
├─ Step 7 generate_slot:hero-01       → AITask A
├─ Step 8 generate_slot:selling-01    → AITask B
├─ Step 9 evaluate_slot:hero-01       → 可关联评估 AITask C
├─ Step 10 evaluate_slot:selling-01   → 可关联评估 AITask D
├─ Step 11 repair_slot:selling-01     → AITask E
├─ Step 12 evaluate_repair
├─ Step 13 validate_kit
└─ Step 14 human_review/handoff
```

图片套图的步骤数随槽位变化，因此公共 policy 不能沿用脚本 Agent 固定的 8 步；平台 Agent 应设置“协调步骤上限 + 每槽尝试上限 + 总任务上限”。

## 23. 预算策略

```json
{
  "max_coordination_steps": 20,
  "max_slots": 12,
  "max_attempts_per_slot": 2,
  "max_planner_calls": 1,
  "max_evaluator_calls_per_asset": 1,
  "max_total_image_tasks": 24,
  "max_total_points": 300,
  "auto_repair_points_per_slot": 15,
  "require_human_adoption": true
}
```

报价至少拆分显示：

- 套图规划费用；
- 首轮生成预计费用；
- 视觉评估预计费用；
- 自动补图最大预留费用；
- 总预算上限。

未使用的补图预算不预先扣成实际费用；每个 AITask 仍单独 reserve/charge/release。

## 24. 幂等、恢复与一致性

- `(team_id, idempotency_key)` 防重复创建运行；
- `slot_id + attempt` 形成图片任务幂等键；
- PlatformKitItem 记录当前 task_id，恢复时不重建；
- Coordinator 使用数据库锁更新 Run/Item；
- fan-out 任务独立成功/失败，fan-in 只读取终态；
- Asset 创建后通过事务写回 Item 和 AgentArtifact；
- 用户中途删除参考图，未开始槽位停止，运行标记 stale；
- 商品关键字段变化后，采用前提示重新验证；
- 用户取消后不再创建新任务，已在 provider 执行的任务按现有机制处理；
- 质检 Worker 重复投递不能重复收费或重复生成补图。

## 25. 权限与安全

- 所有商品、参考资产、模型、套图版本必须限定当前 team；
- 用户 prompt、商品描述和资产名称属于数据区，不能覆盖平台规则和工具权限；
- Planner 输出中的卖点 ID 必须存在于 Snapshot；
- OCR 发现价格、认证、功效时必须能映射商品事实，否则标错；
- Agent 不能发布外部平台；
- Agent 不能删除用户资产；
- 采用必须由有权限的用户触发；
- 日志只保存 URL/ID 和摘要，不保存敏感图片二进制；
- Provider 错误对用户返回标准错误码，详细响应保留在受限 AITask 中。

## 26. 错误分类与降级

| 错误 | 状态与处理 |
| --- | --- |
| `NO_REAL_PRODUCT_REFERENCE` | waiting_user，不生成 |
| `REFERENCE_NOT_READY` | waiting_user/waiting_task |
| `PLAN_INVALID` | 规则 Planner 重建一次或人工修改 |
| `MODEL_CAPABILITY_MISMATCH` | waiting_user/approval，禁止纯文降级 |
| `BUDGET_EXCEEDED` | waiting_approval/budget_exhausted |
| `GENERATION_FAILED` | 单槽失败；按 provider 错误决定是否允许一次重试 |
| `EVALUATION_FAILED` | 保留图片，标 warning，允许人工审核 |
| `QUALITY_REJECTED` | 生成 RepairSpec 或停止 |
| `INPUT_STALE` | 禁止采用，要求刷新计划 |
| `PARTIAL_SUCCESS` | 展示成功槽位和缺失槽位，不整批作废 |

普通批量生图入口可作为用户主动选择的回退，但 Agent 不会无提示切换过去。

## 27. 测试方案

### 27.1 单元测试

- PlatformKitRequest/Context/Plan/Spec/Report Schema；
- 平台 ID 映射和规则版本；
- 参考图真实来源筛选与角色；
- 计划数量、必需槽位、卖点、文字政策；
- PromptCompiler 快照测试；
- ratio → provider size；
- 模型能力过滤和禁止降级；
- issue_code → RepairSpec；
- 整套重复度和槽位覆盖规则；
- 工具团队权限和幂等。

### 27.2 集成测试

- 参考图不足 → waiting_user，零图片费用；
- 4/8/12 槽位计划正确且不简单复制；
- Seedream/GPT-Image 不同 capability 路由；
- 多槽 fan-out 和部分失败；
- 质检通过直接 ready；
- 单槽失败只补该槽；
- 补图达到上限停止；
- provider 失败退款；
- 浏览器断开后恢复；
- 重复 Celery 投递不重复生成/扣费；
- 采用事务和旧版本取消采用；
- Asset metadata/platform/slot 可追溯；
- legacy cover 模式不受新 Agent 影响。

### 27.3 评估数据集

至少准备覆盖：

- 不同颜色和包装文字商品；
- 透明、反光、纯白、纯黑商品；
- 服装、食品、家居、数码等品类；
- 商品图只有正面/多角度/低清晰度；
- 有 Logo、密集标签、易乱码包装；
- 十个平台规则；
- no_text/minimal/short_labels 三种文字政策；
- 常见失败：变色、变形、重复商品、裁切、错字、二维码、虚假价格。

### 27.4 验收指标

- 首轮整套通过率；
- 商品身份一致性通过率；
- OCR 错字/乱码率；
- 平台规则通过率；
- 单槽补图成功率；
- 平均每槽生成次数；
- 用户整套直接采用率；
- 用户替换单槽比例；
- 每套平均积分、耗时；
- 失败原因分布；
- 无真实图误生成率必须为 0。

## 28. 分阶段实施

### 阶段 A：复用公共 Agent 基础设施

- AgentRun/Step/Artifact、工具注册、预算、恢复、取消；
- 若脚本 Agent 已完成，平台套图直接复用，不重复建设。

### 阶段 B：领域解耦但保持旧行为

- 抽出 PlatformRuleProvider；
- 抽出 PromptCompiler；
- 拆出单图 spec enqueue；
- 增加 platform/slot/ratio metadata；
- 旧 cover API 继续使用默认 Plan 适配器，结果不变。

### 阶段 C：平台套图 Agent MVP

- PlatformKitVersion/Item；
- 真实参考图硬门槛；
- 确定性套图 Plan；
- 按槽位受控并行生成；
- 人工逐槽/整套采用；
- 暂不做模型视觉质检和自动补图。

### 阶段 D：视觉质检和定向补图

- OCR；
- 视觉评估模型；
- 结构化 issue codes；
- 最多一次定向补图；
- 整套一致性检查；
- 补图报价和人工确认。

### 阶段 E：智能规划和灰度优化

- 可选文本 KitPlanner；
- 基于历史采用数据优化槽位策略；
- 多平台计划复用；
- 与项目导演/脚本 Handoff 协同；
- 仍不自动外部发布。

## 29. 一人串行开发工作量参考

以下基于现有生图、资产、计费和 Worker 可复用，使用编码工具辅助，且不包含自研 OCR/视觉模型训练：

| 工作 | 参考工期 |
| --- | ---: |
| 公共 Agent 基础设施 | 3–4 天 |
| 平台规则/PromptCompiler/单图 spec 解耦 | 2–3 天 |
| PlatformKitVersion/Item 与 API | 2–3 天 |
| 确定性 Planner、参考图门槛和能力路由 | 2–3 天 |
| 前端槽位计划、进度、候选和采用 | 3–4 天 |
| OCR/视觉评估与结构化报告 | 3–5 天 |
| 定向补图、预算、幂等与恢复 | 2–3 天 |
| 测试数据、集成测试和灰度修正 | 3–4 天 |

合计约 **20–29 人天**。如果公共 Agent 基础设施已由脚本 Agent 建好，平台套图自身约 **16–25 人天**。只做 MVP（确定性计划 + 按槽位生成 + 人工采用，不含视觉质检和自动补图）约 **11–16 人天**，公共基础设施已存在时约 **8–12 人天**。

## 30. 与脚本 Agent 的协同边界

平台套图 Agent 不直接读取脚本 Agent 聊天记录。未来视频项目需要平台宣发图时，只接收结构化 Handoff：

```json
{
  "source": "script_handoff/v1",
  "project_id": "...",
  "script_version_id": "...",
  "product_id": "...",
  "must_show_selling_point_ids": ["..."],
  "visual_direction": "真实通勤场景",
  "forbidden_claims": ["..."],
  "approved": true
}
```

平台套图 Agent 再基于平台规则和商品真实图形成自己的 `PlatformKitPlan`。两者通过版本化业务契约协同，不互相调用内部函数，这正是松耦合。

## 31. 最终落地形态

```text
用户选商品、平台、数量和目标
→ Platform Kit Agent 冻结商品和真实参考图
→ 检查素材是否足够
→ 形成版本化套图计划
→ 每槽选择参考图并编译生成 spec
→ 能力路由、报价、受控并行生成
→ OCR + 视觉 + 整套规则质检
→ 对失败槽位最多定向补图一次
→ 保存 PlatformKitVersion 和候选 Asset
→ 用户逐槽确认或整套采用
→ 输出可供导出/投放/项目导演读取的 Handoff
```

实现后，平台套图不再只是固定模板批量出图，而是一个能“规划—执行—观察—有限修复—交付”的受控视觉 Agent；同时所有付费生成、资产、计费和 Provider 仍沿用 AirShelf 现有基础设施，不形成第二套平行系统。