12 KiB
平台套图 Agent TODO 代码实施计划
依据：
07_平台套图Agent_协同引入实施方案.md
原则：一步一确认、公共运行时复用、先拆规则再编排、先人工采用再自动质检补图。
本文件是实施清单，不代表已经修改代码。
1. 强制确认机制
每一步必须经过两次用户确认：
开始前：“确认开始 Pxx”
→ 只实施 Pxx
→ 汇报代码、migration、测试、风险、回滚
完成后：“确认完成 Pxx，进入 Pyy”
未收到完成确认，禁止实施下一步。禁止一次确认连续做多个步骤。
状态：[ ] 未开始、[~] 实施中、[?] 待验收、[x] 已验收、[!] 阻塞。
2. 前置依赖
- 脚本计划
S03的 AgentRun/AgentStep/AgentArtifact 已验收； - 脚本计划
S04的工具协议、权限、预算、恢复已验收； - 若尚未建设，必须先单独确认实施 S03–S04；
- 平台套图不得复制另一套 Agent 基础设施。
3. 实施顺序
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 流程：
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. 每步完成汇报模板
步骤：Pxx
状态：等待用户验收
本步改动文件：
数据库 migration：
行为变化：
测试命令与结果：
未通过项/风险：
回滚方式：
明确未实施的后续步骤：
请确认：“确认完成 Pxx，进入 Pyy”
6. 推荐首次执行
先检查公共基础设施依赖，然后从 P00 开始。没有 确认开始 P00 不修改代码。