436 lines
12 KiB
Markdown
436 lines
12 KiB
Markdown
# 平台套图 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` 不修改代码。
|