1036 lines
34 KiB
Markdown
1036 lines
34 KiB
Markdown
# 平台套图 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 现有基础设施，不形成第二套平行系统。
|