# 平台套图 Agent TODO 代码实施计划 > 依据：`07_平台套图Agent_协同引入实施方案.md` > 原则：一步一确认、公共运行时复用、先拆规则再编排、先人工采用再自动质检补图。 > 本文件是实施清单，不代表已经修改代码。 ## 1. 强制确认机制 每一步必须经过两次用户确认： ```text 开始前：“确认开始 Pxx” → 只实施 Pxx → 汇报代码、migration、测试、风险、回滚 完成后：“确认完成 Pxx，进入 Pyy” ``` 未收到完成确认，禁止实施下一步。禁止一次确认连续做多个步骤。 状态：`[ ] 未开始`、`[~] 实施中`、`[?] 待验收`、`[x] 已验收`、`[!] 阻塞`。 ## 2. 前置依赖 - [ ] 脚本计划 `S03` 的 AgentRun/AgentStep/AgentArtifact 已验收； - [ ] 脚本计划 `S04` 的工具协议、权限、预算、恢复已验收； - [ ] 若尚未建设，必须先单独确认实施 S03–S04； - [ ] 平台套图不得复制另一套 Agent 基础设施。 ## 3. 实施顺序 ```text P00 业务决策 → P01 抽离平台规则 → P02 抽离 PromptCompiler 和单图 Spec → P03 修正旧链路可追溯性 → P04 建套图领域版本 → P05 建 Context 与参考图硬门槛 → P06 建确定性 KitPlan → P07 建模型路由和生成工具 → P08 建 Coordinator MVP → P09 建 API 与前端采用 → P10 建确定性质检 → P11 接 OCR/视觉评估 → P12 接单槽定向补图 → P13 Handoff、回归和灰度 → P14 旧编排退役评估 ``` ## 4. TODO 明细 ### [ ] P00：确认平台套图首期口径 确认项： - [ ] MVP 首期只做 4 张，还是直接支持 4/8/12； - [ ] 各数量的必需槽位； - [ ] 平台规则版本和首期平台范围； - [ ] 无真实商品图必须阻塞； - [ ] 文字政策：no_text/minimal/short_labels； - [ ] 用户明确模型与自动路由规则； - [ ] 单图和整套预算； - [ ] 首期人工采用，不自动发布； - [ ] OCR/视觉评估放 MVP 后实施。 代码范围：无业务代码修改。 启动口令：`确认开始 P00` 完成口令：`确认完成 P00，进入 P01` --- ### [ ] P01：抽离平台规则服务 依赖：P00。 目标：只解耦，不改变旧 `mode=cover` 结果。 代码 TODO： - [ ] 从 `services.py` 封装 `_PLATFORM_NAMES`； - [ ] 封装 `_PLATFORM_COVER_BLOCKS`； - [ ] 封装 `_COVER_SLOTS`； - [ ] 封装低密度、背景、负面规则； - [ ] 新建 `PlatformRule/v1`； - [ ] 新建 `PlatformRuleProvider.get()`； - [ ] 记录 rule_version； - [ ] 旧提示词函数改为调用 Provider； - [ ] 不迁数据库、不改页面。 测试：十个平台映射、规则快照、未知平台、旧 prompt 等价。 完成标准：平台规则有单一读取接口，旧行为不变。 启动口令：`确认开始 P01` 完成口令：`确认完成 P01，进入 P02` --- ### [ ] P02：抽离 PromptCompiler 与单图 Spec 依赖：P01。 目标：让规划与 Worker 执行解耦。 代码 TODO： - [ ] `PlatformKitSlot/v1`； - [ ] `ImageGenerationSpec/v1` 公共 Schema； - [ ] `compile_platform_image_spec()` 纯函数； - [ ] 明确 references、roles、ratio、prompt、negative、rubric； - [ ] 编译结果不查库、不调用模型； - [ ] 从 `enqueue_standalone_images()` 拆 `enqueue_standalone_image_spec()`； - [ ] Worker 优先执行已编译 spec； - [ ] 旧 cover 请求通过 legacy adapter 生成相同 spec； - [ ] 不新增 Agent Coordinator。 测试：Prompt 黄金快照、ratio 尺寸、reference 顺序、旧 cover 回归、重复 spec 幂等。 完成标准：单张平台图可由完整 spec 独立提交。 启动口令：`确认开始 P02` 完成口令：`确认完成 P02，进入 P03` --- ### [ ] P03：修正旧链路可追溯性和禁止隐式问题 依赖：P02。 目标：先修数据基础，不启用 Agent。 代码 TODO： - [ ] Asset metadata 增加 platform_id、slot、attempt、rule_version； - [ ] AITask 保存最终模型、最终 prompt/spec； - [ ] 纯文本调用明确传 ratio/size； - [ ] Agent 模式预留 `allow_text_fallback=false`； - [ ] 旧模式保持兼容但记录 fallback_reason； - [ ] platform_id team/输入校验； - [ ] 前端展示实际模型； - [ ] 不删除旧批次。 测试：metadata、比例、模型追溯、旧资产序列化、轮询结果。 启动口令：`确认开始 P03` 完成口令：`确认完成 P03，进入 P04` --- ### [ ] P04：建立 PlatformKitVersion/Item 依赖：P03。 代码 TODO： - [ ] `PlatformKitVersion` 模型和状态； - [ ] `PlatformKitItem` 模型和状态； - [ ] product/platform/version/plan/hash/run 字段； - [ ] slot_id/order/goal/selected_asset/task/attempt/report； - [ ] 唯一约束和索引； - [ ] Serializer 和只读查询服务； - [ ] 采用事务服务； - [ ] migration 正反向验证； - [ ] 不改变 Asset 真相源。 测试：版本、槽位唯一、跨团队、采用事务、删除保护。 完成标准：能保存空计划和槽位，但尚不生成图片。 启动口令：`确认开始 P04` 完成口令：`确认完成 P04，进入 P05` --- ### [ ] P05：ContextSnapshot 与真实参考图硬门槛 依赖：P04。 代码 TODO： - [ ] `PlatformKitAgentRequest/v1`； - [ ] `PlatformKitContextSnapshot/v1`； - [ ] 商品和卖点 team 校验； - [ ] 真实上传图优先并排除 AI 图； - [ ] 用户选图需属于商品； - [ ] 保存 asset/file checksum； - [ ] `NO_REAL_PRODUCT_REFERENCE`； - [ ] 无图时 waiting_user 且不创建图片 AITask； - [ ] snapshot hash/stale 检查。 测试：无图、真实图、AI 图、跨团队、文件删除、商品修改。 完成标准：不给模型调用，也能得到完整 Context 或明确阻塞原因。 启动口令：`确认开始 P05` 完成口令：`确认完成 P05，进入 P06` --- ### [ ] P06：确定性 PlatformKitPlan MVP 依赖：P05。 目标：先不调用文本 Planner。 代码 TODO： - [ ] `PlatformKitPlan/v1`； - [ ] 按 P00 数量生成稳定 slot_id； - [ ] hero/scene/selling/detail/multi/promo 策略； - [ ] 卖点 ID 分配； - [ ] 每槽 goal/composition/text_policy/reference_roles/acceptance； - [ ] PlanValidator； - [ ] 必需槽位、数量、重复、卖点、文字、ratio 校验； - [ ] 8/12 张不得简单复制完全相同槽位； - [ ] 保存 plan/rule version。 测试：各数量、各平台、无卖点、多卖点、未知平台、重复槽位。 完成标准：规则即可生成可执行、可解释的套图计划。 启动口令：`确认开始 P06` 完成口令：`确认完成 P06，进入 P07` --- ### [ ] P07：模型能力路由和图片生成工具 依赖：P06。 代码 TODO： - [ ] `ModelRequirement`：multi_reference/count/ratio/quality； - [ ] 包装现有 `resolve_image_model()`； - [ ] 明确模型能力不满足时停止； - [ ] 禁止丢商品图后纯文降级； - [ ] `quote_image_spec.v1`； - [ ] `generate_image_spec.v1`； - [ ] 每槽一条 AITask； - [ ] spec/idempotency/run/kit/slot 写入任务； - [ ] 失败复用退款； - [ ] 实际模型返回前端。 测试：Seedream/GPT、多参考、比例不支持、余额不足、重复提交、Provider 失败。 启动口令：`确认开始 P07` 完成口令：`确认完成 P07，进入 P08` --- ### [ ] P08：PlatformKit Coordinator MVP 依赖：P07。 MVP 流程： ```text collect_context → plan → validate_plan → quote → persist_kit → compile_specs → bounded_fan_out → wait_tasks → bind_assets → waiting_human ``` 代码 TODO： - [ ] AgentRun(agent_type=platform_kit)； - [ ] 固定 DAG； - [ ] 同 Run 图片并发限制； - [ ] 部分失败不取消成功槽； - [ ] fan-in 和恢复； - [ ] Item 状态与 AITask 同步； - [ ] 取消后不创建新任务； - [ ] 暂不自动质检、暂不补图； - [ ] 不自动采用。 测试：正常、部分失败、断线恢复、重复 Worker、取消、预算不足。 启动口令：`确认开始 P08` 完成口令：`确认完成 P08，进入 P09` --- ### [ ] P09：API 和前端人工采用闭环 依赖：P08。 代码 TODO： - [ ] 创建 PlatformKit AgentRun API； - [ ] Run/Step/Kit 查询； - [ ] 补图前暂只支持手动 retry action； - [ ] 选择槽位候选； - [ ] 整套采用 API； - [ ] 前端输入/计划/槽位进度； - [ ] 实际模型与费用； - [ ] 刷新恢复； - [ ] feature flag； - [ ] legacy cover 入口仍可回退。 测试：team 权限、采用事务、页面恢复、前端 build、旧入口回归。 完成标准：MVP 可计划、生成、人工选择和采用。 启动口令：`确认开始 P09` 完成口令：`确认完成 P09，进入 P10` --- ### [ ] P10：确定性图片与整套质检 依赖：P09。 代码 TODO： - [ ] 文件可读、尺寸、ratio； - [ ] 文件重复/近重复基础检测； - [ ] 槽位齐全； - [ ] slot/order/count； - [ ] metadata/spec/asset 对齐； - [ ] 整套缺图和重复构图 warning； - [ ] `ImageEvaluationReport/v1` 基础结构； - [ ] issue code/severity/repairable； - [ ] 不调用视觉模型。 测试：每项规则正反样例。 启动口令：`确认开始 P10` 完成口令：`确认完成 P10，进入 P11` --- ### [ ] P11：OCR 与独立视觉评估 依赖：P10；用户单独确认评估模型和费用。 代码 TODO： - [ ] OCR Adapter； - [ ] 二维码、平台 Logo、乱码、价格和声明检查； - [ ] 视觉评估 Tool； - [ ] 商品身份、构图、平台适配、槽位目标维度； - [ ] 评估 AITask/费用； - [ ] rubric/model/threshold version； - [ ] 规则 + OCR + 视觉结果汇总； - [ ] 评估不可用时转 warning，不把图片删掉。 测试：mock OCR/VLM、错误码、超时、费用、低置信度。 启动口令：`确认开始 P11` 完成口令：`确认完成 P11，进入 P12` --- ### [ ] P12：单槽定向补图 依赖：P11。 代码 TODO： - [ ] issue code → RepairSpec； - [ ] 只修改相关 prompt 段； - [ ] 每槽最多 2 attempts； - [ ] 只补 error 且 repairable； - [ ] 超自动预算先确认； - [ ] 新候选不删除旧 Asset； - [ ] 补图后完整复检； - [ ] 第二次失败停止； - [ ] 前端展示修复原因和新增费用。 测试：变色、错字、裁切、重复构图、预算不足、达到上限。 启动口令：`确认开始 P12` 完成口令：`确认完成 P12，进入 P13` --- ### [ ] P13：Handoff、完整回归和灰度 依赖：P09；如启用质检补图则还依赖 P10–P12。 代码 TODO： - [ ] `PlatformKitHandoff/v1`； - [ ] AgentArtifact 关联 Kit/Item/Asset/报告； - [ ] adopt 前 snapshot hash； - [ ] 全流程集成测试； - [ ] 指标：首轮通过率、补图率、采用率、费用、耗时； - [ ] 团队 feature flag； - [ ] 发布和回滚说明； - [ ] legacy 继续保留。 灰度每一级都需用户确认。 启动口令：`确认开始 P13` 完成口令：`确认完成 P13，进入 P14` --- ### [ ] P14：旧平台套图编排退役评估 依赖：P13 稳定运行约定周期。 先评估：旧 API 调用、活动 batch、历史资产、Agent 指标、回滚能力。 允许删除：旧页面直接循环批次、`index % 6` 编排、旧 cover 薄适配。 禁止删除：平台规则、PromptCompiler、图片 Worker、AITask、Asset、Billing、Provider。 启动口令：`确认开始 P14 评估` 删除口令：`确认执行旧平台套图编排下线` 完成口令：`确认完成 P14` ## 5. 每步完成汇报模板 ```text 步骤：Pxx 状态：等待用户验收 本步改动文件： 数据库 migration： 行为变化： 测试命令与结果： 未通过项/风险： 回滚方式： 明确未实施的后续步骤： 请确认：“确认完成 Pxx，进入 Pyy” ``` ## 6. 推荐首次执行 先检查公共基础设施依赖，然后从 `P00` 开始。没有 `确认开始 P00` 不修改代码。