azmat1127/yingqing
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2f5b7304b044b847c6c2ca4de2095d45814cc2f6
yingqing/docs/agents_todo/平台套图Agent_协同引入实施方案.md
T

34 KiB
Raw Blame History

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

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

1. 结论先行

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

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

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

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

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

2.1 当前链路

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 复用，只新增平台领域目录：

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

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

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

前端：

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

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

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

{
  "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

{
  "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

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 模式必须取消当前“无商品图退到纯文生图”的静默降级：

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

可配置最小要求：

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

10.2 参考图角色

{
  "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。

接口：

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

PlatformRule/v1：

{
  "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

{
  "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() 应拆成纯函数：

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

13.1 ImageGenerationSpec/v1

{
  "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 分层

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

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

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

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

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

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

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

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

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

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

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

Agent 声明需求：

{
  "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() 拆出更细粒度服务：

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 至少增加：

{
  "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 质检分层

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

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

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

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

第 5 层：人工采用

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

17.2 ImageEvaluationReport/v1

{
  "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": "..."
  }
}

标准失败码建议：

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 设计

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。

动作：

{"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 映射

示例：

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. 预算策略

{
  "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：

{
  "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. 最终落地形态

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

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

Reference in New Issue View Git Blame Copy Permalink