V2-02 · 图片工坊 Prompt 2.0

CR-20260921-014 适用说明：此文保留原专题/候选证据。当前产品与开发范围以prd.md、frontend-contract.md及docs/current-development-alignment.md为准。旧AI卖点整理前置、套图页终止、旧模特Planner/姿势解析不进入现行流程；历史结果不代表新模特直接候选通过真实效果验收。

状态：Freddy 已确认 · 技术迁移契约冻结
确认日期：2026-08-21
专题范围：一期 10 接口到 Prompt 2.0 的兼容、规则解析、规划接入、确定性编译、Provider 适配、快照、回退和验证
成熟度：技术契约 Frozen；Planner 与 Prompt 仍为 Candidate，未完成真实 A/B，不代表生产可切换

1. 冻结依据与证据层级

本文件是 V2-02 独立专题结论，不直接修改共享 PRD、前端契约、知识库、原型、一期代码、main 或生产 Prompt。

2. 专题范围与不负责范围

3. V2-01 不得重定义的上游语义

1. 购买决策目标只在 ImageTypeDefinition 设计期固化；运行时不生成 decisionRole。
2. 套图预览不调用 Planner；最终点击生成后才冻结输入、规则解析、规划、校验和编译。
3. 用户选择图片生成模型；普通用户和普通前端不得指定 plannerKey。
4. 未命中的平台规则不得进入 RuleContext、Planner 上下文、Visual Plan 或最终 Prompt。
5. 单图 generationCount=1–5，每个结果独立规划、编译、调用、结果和重试。
6. 尺寸和比较事实缺失只阻断受影响单元。
7. 多角度缺少对应角度参考不阻断，也不因此触发专门后检或人工交付门禁；只执行普通商品图质量检查。
8. PASS / PASS_WITH_POSTCHECK / BLOCK 是唯一计划校验结果。
9. 三类 Planner 策略保持 Candidate；真实 A/B 前不得切换生产。

4. V2-02 核心技术决策

4.1 plannerKey 计算位置

冻结方案：由规划编排服务内部计算，不接受普通业务接口提交。

路由结果以 plannerStrategyRef 保存到 SuitePlan、ImageVisualPlan 和编译快照。用户选择的图片生成模型不得改变 Planner 策略。

4.2 图片模型与 Provider 路由

• V2 请求保留 selectedGenerationModelRef，来源为用户选择。
• 服务端用版本化 ModelCapabilityRegistry 解析 Provider、端点、图片数量、参考图、编辑、尺寸、质量、文字和输出格式能力。
• 未登记或与当前任务能力不兼容的模型返回结构化错误，不默认落入 OpenAI Provider。
• Provider 适配器只转换接口格式，不改变图片目标、事实、规则、Visual Plan 或最终 Prompt。
• 当前一期 DOUBAO_IMAGE_MODELS 中误登记的对话模型不得迁入 V2 能力注册表。

4.3 Prompt 契约版本

冻结传输字段：promptContractVersion。Python 内部可使用 prompt_contract_version，但必须通过 Schema alias 与传输字段唯一映射，不允许两个字段同时成为独立输入。

V1 暂时兼容 n=1–10；V2 只接受 generationCount=1–5。

4.4 single_long_page

V2 不承接 single_long_page 产品能力，不为其开发新版 Planner。当前只读阶段不删除一期代码；实际移除 V1 能力前必须先核对消费者，避免接口故障。

5. 一期代码事实与缺口

5.1 当前调用图

POST /llm/imageAgent/{scene}
→ Pydantic Request
→ build_prompt(request, scene)
→ model → Provider 路由
  ├─ Seedream: /images/generations
  └─ 其他模型: /images/generations 或 /images/edits
→ 可选 OSS
→ scene / data / model / prompt / available_actions

5.2 已复现缺口

6. 一期 10 接口迁移矩阵

7. 一期字段覆盖矩阵

7.1 共享字段

7.2 业务字段

8. 一期七层 Prompt 语义覆盖

七层语义必须逐层有来源、版本和回归断言；不能用“复用一期”代替契约。

9. 图片类型、平台、类目和模板作用矩阵

9.1 Amazon 商品主图不变量

amazonMainWhiteApplicable =
  normalizedPlatform == "amazon"
  AND imageTypeCode == "product_main"

当双重命中时，产品交互固定显示 Amazon 白底图，不提供 clean_scene 选择，也不允许应用冲突模板。后端保留不变量校验，防止旧客户端绕过交互。

当未双重命中时，Amazon 主图白底 Rule ID 和文本必须同时从以下对象中缺席：

1. RuleContext / ResolvedRuleSnapshot 的 applied rules；
2. PlannerInvocation；
3. ImageVisualPlan / SuitePlan；
4. CompiledPromptSnapshot.finalPrompt。

Amazon 副图、使用场景、卖点、尺寸、编辑任务不得继承主图白底规则。

9.2 Shopee clean_scene

platform=shopee + imageType=product_main + resolvedBackgroundMode=clean_scene 时：

• 只包含当前 Shopee、通用、图片类型和模板规则；
• Amazon Rule ID/文本出现次数为0；
• 一期默认 background_mode=white 不进入任何 V2 对象；
• 不以“禁止 Amazon 白底”反向提示污染 Planner，上游未命中规则完全不进入上下文。

9.3 比较证据

允许来源仅为：

1. 可追溯商品系统事实；
2. 当前 Listing 中可追溯信息；
3. 用户输入或上传并绑定当前商品/任务的资料；
4. 用户明确确认的数据。

证据至少包含比较对象、条件/方法、指标或口径、结果/可成立结论、来源引用。普通营销描述不能自动升级为比较事实。缺失时仅 BLOCK effect_comparison，不编译、不调用 Provider，其他单元继续。

9.4 未知配件

包装清单只有名称或数量、没有可视引用时，可以使用已确认文字表达，不得生成未知外观。只有 visualRef 或可靠商品主体素材支持的实体才能进入 allowedEntities。

10. V2 运行时对象与快照链

完整追溯链：

ProductInputSnapshot
→ BlueprintSnapshot
→ ResolvedRuleSnapshot
→ SuitePlanSnapshot（套图）
→ ImageVisualPlanSnapshot
→ PlanValidationSnapshot
→ CompiledPromptSnapshot
→ ProviderRequestSnapshot
→ GenerationResultVersion
→ PostCheckResult

历史快照不可原地覆盖。输入、蓝图、规则、定义、计划或编译器变化均创建新版本。

11. 最小代码改造点

11.1 路由层

保留一期 10 个 URL。请求进入后先按 promptContractVersion 分流：

v1 → 现有 build_prompt / Provider 路径
v2-candidate → V2RequestAdapter → PlanningOrchestrator → Compiler → ExecutionHandoff

11.2 Schema 层

新增但不替换一期对象：

• V2ImageGenerationRequest
• V2ExecutionUnit
• V2GenerationVariant
• V2GenerationResponse
• 快照引用与结构化错误对象

V2 普通请求不包含 plannerKey，必须包含用户所选 selectedGenerationModelRef。

11.3 build_prompt 前插入链路

现有 builder 保持 V1 基线；V2 不直接调用一期 build_prompt(request, scene)：

请求兼容适配
→ 冻结输入/蓝图
→ 解析图片类型定义和规则
→ 事实充分性预检
→ 内部 Planner 路由
→ SuitePlan（套图）
→ 每单元/variant ImageVisualPlan
→ 计划校验
→ 确定性编译
→ 先持久化 CompiledPromptSnapshot
→ 再交给 Provider

11.4 单图多结果 fan-out

generationCount=N
→ 创建 N 个 variantId
→ N 个 ImageVisualPlan
→ N 个 PlanValidationSnapshot
→ N 个 CompiledPromptSnapshot
→ N 次独立 Provider 调用（每次单结果）
→ N 个 GenerationResultVersion

N=1 只有一个计划，不制造差异。N>1 使用合法差异轴，但不因抽象差异不足减少用户数量；近重复由结果检查只处理受影响结果。

12. V2 请求与响应契约

12.1 普通业务请求最小字段

{
  "promptContractVersion": "v2-candidate",
  "requestId": "request-xxx",
  "planningMode": "SINGLE",
  "productInputSnapshotRef": "input-xxx",
  "platformContext": {
    "platform": "Shopee",
    "site": "Malaysia",
    "language": "English",
    "purpose": "listing_image"
  },
  "executionUnits": [
    {
      "unitId": "unit-main",
      "imageTypeDefinitionRef": "product_main@version",
      "sellingPointRef": null,
      "templateConstraintRef": "slot-xxx"
    }
  ],
  "generationCount": 3,
  "selectedGenerationModelRef": "model-selected-by-user",
  "assetBindings": []
}

普通业务请求不得出现 plannerKey 或完整系统 Prompt。

12.2 普通 V2 响应

{
  "generationResult": [],
  "snapshotId": "compiled-or-execution-snapshot-id",
  "executionSummary": {},
  "validationStatus": "PASS",
  "model": "user-selected-model",
  "variantId": "variant-001",
  "availableActions": []
}

完整 Prompt 不作为首屏核心业务响应，但必须保存在 CompiledPromptSnapshot 并按权限追溯。

12.3 结构化错误

最低错误类别：

• CONTRACT_VERSION_UNSUPPORTED
• MODEL_NOT_REGISTERED
• MODEL_CAPABILITY_MISMATCH
• IMAGE_TYPE_DEFINITION_NOT_FOUND
• PLANNER_ROUTE_FAILED
• PLANNER_OUTPUT_INVALID
• RULE_RESOLUTION_FAILED
• EVIDENCE_MISSING
• PLAN_BLOCKED
• PROMPT_COMPILE_FAILED
• PROVIDER_REQUEST_FAILED
• PROVIDER_RESULT_UNKNOWN

错误必须包含 requestId / unitId / variantId / retryable / stage / snapshotRefs / message；不得用重试掩盖事实或规则 BLOCK。

13. 前端消费契约

设计语言复用现有 Ant Design X，不新增视觉规范，不把图片工坊设计成聊天页。

13.1 结果优先

普通运营首屏看到：

• 图片结果；
• 图片类型；
• 绑定卖点；
• 校验状态；
• 用户所选模型；
• Variant；
• 业务执行摘要。

不在结果卡片首屏展示大段完整 Prompt。

13.2 右侧生成详情

点击“查看生成详情”在当前页面打开 Drawer/Panel，不跳离图片工坊。执行链参考 Ant Design X ThoughtChain 的状态表达，但展示业务可审计阶段，不展示模型私有思维：

商品输入快照
→ 规则解析
→ Visual Plan
→ PASS / PASS_WITH_POSTCHECK / BLOCK
→ Prompt 编译
→ Provider 调用
→ Post Check

13.3 信息权限

V1 暂时保留当前完整 Prompt 响应；V2 完整 Prompt 默认折叠，不删除、不丢失追溯能力。

14. 回退

当前 V2 candidate 规划/编译版本不可用
→ 最后一个真实验证通过且兼容当前契约的 V2 版本
→ 受保护的一期 V1 编译路径
→ 仍不可用则返回结构化失败，不调用空 Prompt

回退必须保存：触发阶段、失败版本、实际使用版本、原因、输入快照、兼容映射、Provider attempt 和结果。回退不允许修改历史任务，也不允许在响应中伪装成原版本成功。

15. 自动回归

16. 同输入真实 A/B 门禁

真实 A/B 必须同时固定：

• ProductInputSnapshot；
• BlueprintSnapshot；
• 素材和授权；
• 用户选择的图片模型；
• Provider、尺寸、质量和其他真实调用参数；
• 重试规则和样本保留方式。

唯一实验变量是 V1/V2 Prompt 规划与编译分支。每次调用分别保存 Prompt、请求、结果、失败、重试和评审记录。

评审至少覆盖：商品身份/事实一致性、图片类型任务完成度、平台规则污染、未知实体、文字/OCR、电商可用性、视觉质量、近重复、失败率和人工修订量。

以下均不能单独作为质量通过：

• Prompt 字符数下降；
• Hash 或 Schema 通过；
• 示例和 Mock 通过；
• 单次成功出图；
• 静态自动回归通过。

A/B 样本量、质量阈值、成本阈值、失败率阈值和生产授权由后续专项/总控决定，本文件不编造。

17. 开发拆分

18. 与共享文档的冲突清单

等待 00 总控同步，不由 V2-02 直接修改：

1. 共享文档仍写预览阶段调用套图总导演；冻结语义为预览不调用 Planner。
2. 共享规范仍使用 ready/blocked/needs_review；冻结契约为三态。
3. 共享规范仍要求多角度参考不足人工核对；冻结语义为正常生成和普通质量检查。
4. 共享规范仍把未命中 Amazon 规则以反向禁止文本传入 Shopee Planner；冻结语义为完全不进入上下文。
5. 共享规范仍可能要求差异不足时阻断 N；冻结语义为按用户数量执行，近重复在结果阶段处理。
6. 一期默认 white、n=1–10、自由素材角色和未知模型默认 Provider 与 V2 契约冲突。

19. 验收与最终状态

V2-02 技术迁移契约至此完整冻结，可供后续开发拆分、V2-03 执行契约和 00 总控整合消费。任何实现不得以接口便利、模型能力或 Prompt 长度为理由重新解释 V2-01/V2-02 已冻结语义。