diff --git a/docs/agents_todo/平台套图Agent_TODO代码实施计划.md b/docs/agents_todo/平台套图Agent_TODO代码实施计划.md new file mode 100644 index 0000000..fbb8bdd --- /dev/null +++ b/docs/agents_todo/平台套图Agent_TODO代码实施计划.md @@ -0,0 +1,435 @@ +# 平台套图 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` 不修改代码。 diff --git a/docs/agents_todo/平台套图Agent_协同引入实施方案.md b/docs/agents_todo/平台套图Agent_协同引入实施方案.md new file mode 100644 index 0000000..bfc14cd --- /dev/null +++ b/docs/agents_todo/平台套图Agent_协同引入实施方案.md @@ -0,0 +1,1035 @@ +# 平台套图 Agent 协同引入实施方案 + +> 目标：在复用现有图片工作台、AITask、积分、Celery、Provider、Asset 和 TOS 的前提下，把当前“固定平台模板 + 按序批量生图”升级为能规划套图、选择参考素材、并行生成、逐图质检、定向补图并由用户采用的平台套图 Agent。 +> 架构原则：松耦合、高内聚、可复用、精简化、可扩展。 +> 代码基线审阅时间：2026-07-17。 + +## 1. 结论先行 + +平台套图 Agent 最适合做 AirShelf 的第一个视觉 Agent，但首期不应让多个视觉模型自由讨论。推荐采用： + +```text +一个平台套图协调器 ++ 确定性商品/平台上下文收集 ++ 轻量套图规划节点 ++ 参考图选择器 ++ 提示词编译器 ++ 现有图片生成工具 ++ 独立视觉质检器 ++ 失败槽位最多一次定向补图 ++ 套图版本和人工采用 +``` + +与当前链路相比，真正新增的 Agent 能力是： + +1. 先形成完整套图计划，而不是按 index 固定轮换； +2. 检查真实商品参考图是否足够，不足时暂停而不是静默纯文生图； +3. 为每个槽位声明目标、参考图、构图、文字政策和验收规则； +4. 观察每张生成结果，结构化识别失败原因； +5. 只重试失败槽位，不整批重跑； +6. 保存套图版本、槽位关系和质检报告； +7. 用户确认后采用，不自动覆盖现有资产。 + +## 2. 当前代码基线与主要问题 + +### 2.1 当前链路 + +```text +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 复用，只新增平台领域目录： + +```text +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 +``` + +平台套图是独立业务产物，建议在图片/资产领域增加： + +```text +core/backend/apps/assets/ +├─ models.py # PlatformKitVersion / PlatformKitItem +├─ serializers.py +└─ services/platform_kit.py # 保存、采用、版本查询 +``` + +前端： + +```text +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 + +```text +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 + +```text +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` + +```json +{ + "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` + +```json +{ + "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 + +```mermaid +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 模式必须取消当前“无商品图退到纯文生图”的静默降级： + +```text +无可用真实商品图 +→ waiting_user +→ 提示上传正面/侧面/细节图 +→ 不创建付费图片任务 +``` + +可配置最小要求： + +- 普通包装/单品：至少 1 张清晰正面图； +- 有背面信息：建议正反 2 张； +- 服装/立体商品：建议正面 + 侧面/细节； +- 参考图必须排除 AI 生成图或明确标记为低可信辅助图。 + +### 10.2 参考图角色 + +```json +{ + "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`。 + +接口： + +```python +class PlatformRuleProvider: + def get(self, platform_id: str, version: str | None = None) -> PlatformRule: + ... +``` + +`PlatformRule/v1`： + +```json +{ + "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` + +```json +{ + "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()` 应拆成纯函数： + +```python +compile_platform_image_spec( + context: PlatformKitContextSnapshot, + plan: PlatformKitPlan, + slot: PlatformKitSlot, + references: list[ReferenceSpec], + model_capabilities: ModelCapabilities, +) -> ImageGenerationSpec +``` + +### 13.1 `ImageGenerationSpec/v1` + +```json +{ + "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 分层 + +```text +[输入数据声明] +参考图是同一真实商品，只用于商品身份和细节事实。 + +[身份锁定] +形状、颜色、材质、包装、Logo、标签文字、结构不可改变。 + +[平台规则] +来自 PlatformRule/version。 + +[整套方向] +来自 PlatformKitPlan.global_constraints。 + +[本槽位目标] +slot.goal + composition + selling points。 + +[文字政策] +no_text/minimal/short_labels；文字只能来自事实快照。 + +[背景与构图] +主体比例、对比、镜头、光线。 + +[用户补充] +可影响创意，但不能覆盖事实和禁止项。 + +[负面约束] +平台禁用项、商品畸变、重复主体、乱码等。 +``` + +PromptCompiler 只做编译，不调用模型、不查数据库，便于单元测试和复用于补图。 + +## 14. 模型路由与禁止静默降级 + +Agent 声明需求： + +```json +{ + "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()` 拆出更细粒度服务： + +```python +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 至少增加： + +```json +{ + "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 质检分层 + +```text +第 1 层：确定性文件检查 +→ 文件可读、尺寸、比例、空图、重复文件 + +第 2 层：OCR/文字规则 +→ 乱码、虚假价格、平台 Logo、二维码、文字数量、已知品牌文字 + +第 3 层：视觉评估模型 +→ 商品身份、颜色/形状、Logo、主体完整、构图、槽位目标、平台风格 + +第 4 层：整套规则 +→ 槽位覆盖、重复度、视觉一致性、缺图 + +第 5 层：人工采用 +``` + +生成模型和视觉评估模型应尽量解耦；至少使用不同提示角色和确定性规则共同裁决，不能只相信“模型给自己 95 分”。 + +### 17.2 `ImageEvaluationReport/v1` + +```json +{ + "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": "..." + } +} +``` + +标准失败码建议： + +```text +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 设计 + +```http +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`。 + +动作： + +```json +{"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 映射 + +示例： + +```text +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. 预算策略 + +```json +{ + "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： + +```json +{ + "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. 最终落地形态 + +```text +用户选商品、平台、数量和目标 +→ Platform Kit Agent 冻结商品和真实参考图 +→ 检查素材是否足够 +→ 形成版本化套图计划 +→ 每槽选择参考图并编译生成 spec +→ 能力路由、报价、受控并行生成 +→ OCR + 视觉 + 整套规则质检 +→ 对失败槽位最多定向补图一次 +→ 保存 PlatformKitVersion 和候选 Asset +→ 用户逐槽确认或整套采用 +→ 输出可供导出/投放/项目导演读取的 Handoff +``` + +实现后，平台套图不再只是固定模板批量出图，而是一个能“规划—执行—观察—有限修复—交付”的受控视觉 Agent；同时所有付费生成、资产、计费和 Provider 仍沿用 AirShelf 现有基础设施，不形成第二套平行系统。 diff --git a/docs/agents_todo/视频项目脚本Agent_TODO代码实施计划.md b/docs/agents_todo/视频项目脚本Agent_TODO代码实施计划.md new file mode 100644 index 0000000..7ea7b71 --- /dev/null +++ b/docs/agents_todo/视频项目脚本Agent_TODO代码实施计划.md @@ -0,0 +1,567 @@ +# 视频项目—脚本 Agent TODO 代码实施计划 + +> 依据：`06_视频项目脚本Agent_协同引入实施方案.md` +> 原则：一步一确认、先解耦再新增、每步可测试可回滚、公共能力只建设一次。 +> 本文件是实施清单，不代表已经修改代码。 + +## 1. 强制执行规则 + +每个 TODO 都执行以下闭环： + +```text +1. 用户发送“确认开始 Sxx” +2. 只实施 Sxx 明确列出的范围 +3. 执行本步骤测试和回归 +4. 汇报文件、行为变化、测试结果、遗留风险 +5. 用户发送“确认完成 Sxx，进入 Syy” +6. 才允许开始下一步 +``` + +禁止： + +- 一次确认后连续实施多个步骤； +- 未经确认顺手重构下一步代码； +- 测试未通过就标记完成； +- 为 Agent 重写 AITask、计费、Provider、资产和脚本版本； +- 在新链路稳定前删除旧入口； +- 把计划状态、测试结果或用户确认伪造为已完成。 + +状态标记： + +```text +[ ] 未开始 +[~] 已获开始确认，实施中 +[?] 实施完成，等待用户验收 +[x] 用户已验收 +[!] 阻塞 +``` + +## 2. 全局实施顺序 + +```text +S00 口径确认 +→ S01 修正脚本输入契约 +→ S02 解耦现有脚本生成内核 +→ S03 建公共 Agent 数据骨架 +→ S04 建公共工具与最小运行时 +→ S05 建脚本 Snapshot/Brief +→ S06 建确定性校验器 +→ S07 接入生成工具 +→ S08 建脚本 Coordinator MVP +→ S09 建 API 与运行恢复 +→ S10 接前端真实状态 +→ S11 建 Handoff、采用前检查 +→ S12 可选评审与一次修订 +→ S13 灰度与完整回归 +→ S14 旧编排退役评估 +``` + +`S03–S04` 是三个 Agent 共用的基础设施。平台套图和模特上身图计划只能复用，不得复制。 + +## 3. TODO 明细 + +### [ ] S00：冻结业务口径和基线 + +目标：在写代码前确认唯一规则，避免 Agent 固化当前矛盾。 + +确认项： + +- [ ] 时长与镜数唯一口径：15/30/60 秒分别对应多少镜、每镜多长； +- [ ] `auto/theme/manual/revise/revise_segment` 的准确含义； +- [ ] “自带脚本”是原文进入模型整理，还是完全原样保存； +- [ ] 卖点必须使用真实 ID； +- [ ] 用户明确模型与自动路由的优先级； +- [ ] 首期是否启用语义评审； +- [ ] 单次生成、评审、修订的预算上限； +- [ ] 仍由用户采用脚本。 + +代码范围：无业务代码修改；只允许补充决策记录。 + +验收产物：一份经过用户确认的决策表，后续 Schema 和测试引用同一口径。 + +启动口令：`确认开始 S00` +完成口令：`确认完成 S00，进入 S01` + +--- + +### [ ] S01：修正脚本输入契约 + +依赖：S00 已验收。 + +目标：先解决卖点、时长、模式等数据问题，不引入 Agent。 + +代码 TODO： + +- [ ] 前端提交真实 `selected_selling_point_ids`； +- [ ] 后端按 team 和 product 校验卖点 ID； +- [ ] 保存卖点 ID、标题、内容快照； +- [ ] 建立唯一的 duration → shot_policy 转换函数； +- [ ] 明确 manual 模式，不再隐式落入 theme 分支； +- [ ] 为旧请求增加兼容适配和弃用日志； +- [ ] 补请求 Serializer/Schema 校验； +- [ ] 不改变旧脚本生成结果结构。 + +预计文件： + +```text +core/frontend/src/routes/pipeline.tsx +core/frontend/src/api.ts +core/frontend/src/types.ts +core/backend/apps/projects/views.py +core/backend/apps/ai/script_agent.py +core/backend/apps/projects/tests.py +core/backend/apps/ai/tests.py +``` + +测试： + +- [ ] 卖点跨商品/跨团队拒绝； +- [ ] 15/30/60 秒镜数一致； +- [ ] 五种模式请求分支正确； +- [ ] 旧请求仍可生成； +- [ ] 不新增重复计费。 + +完成标准：输入契约唯一，旧入口正常，所有相关测试通过。 + +启动口令：`确认开始 S01` +完成口令：`确认完成 S01，进入 S02` + +--- + +### [ ] S02：拆出现有脚本生成内核 + +依赖：S01 已验收。 + +目标：只做重构，不改变用户可见行为，为 Agent 工具复用做准备。 + +代码 TODO： + +- [ ] 从 `stream_script_agent()` 拆出上下文构建； +- [ ] 拆出 system/user messages 构建； +- [ ] 拆出单次 Provider 生成服务； +- [ ] 保留流式事件适配； +- [ ] 拆出 normalize/Schema 校验入口； +- [ ] 拆出未采用 ScriptVersion 保存服务； +- [ ] 旧 `script-agent-stream` 改为调用这些服务； +- [ ] 不新增 AgentRun，不改前端。 + +建议接口： + +```text +build_script_generation_context() +build_script_messages() +generate_script_once() +normalize_script_result() +save_script_candidate() +``` + +测试： + +- [ ] 重构前后同输入的 messages 等价； +- [ ] SSE 事件类型保持兼容； +- [ ] ScriptDraft、ScriptVersion、ScriptSegment 结构不变； +- [ ] 中断、失败、退款行为不变； +- [ ] 现有项目测试全过。 + +完成标准：旧入口只作为薄适配器，核心服务可独立测试。 + +启动口令：`确认开始 S02` +完成口令：`确认完成 S02，进入 S03` + +--- + +### [ ] S03：建立公共 Agent 数据骨架 + +依赖：S02 已验收。 + +目标：创建三个 Agent 共用的最小运行记录，不加入具体脚本逻辑。 + +代码 TODO： + +- [ ] 新建 `apps/agents` Django app； +- [ ] 新增 `AgentRun`； +- [ ] 新增 `AgentStep`； +- [ ] 新增 `AgentArtifact`； +- [ ] 状态、agent_type、step_type 使用枚举； +- [ ] 加 team/user/scope、预算、停止原因、lock_version； +- [ ] AgentStep 可关联 AITask； +- [ ] 添加必要索引和唯一约束； +- [ ] 注册 admin 只读审计视图； +- [ ] 生成并检查 migration。 + +预计目录： + +```text +core/backend/apps/agents/ +core/backend/airshelf/settings/ +``` + +测试： + +- [ ] 模型约束和状态默认值； +- [ ] team 隔离； +- [ ] `(team, idempotency_key)` 唯一； +- [ ] Step 顺序/幂等唯一； +- [ ] 删除策略不误删 AITask/业务产物； +- [ ] migration 可正向/反向执行。 + +完成标准：只增加通用审计模型，不影响现有业务接口。 + +启动口令：`确认开始 S03` +完成口令：`确认完成 S03，进入 S04` + +--- + +### [ ] S04：公共工具协议与最小运行时 + +依赖：S03 已验收。 + +目标：实现固定状态机所需的公共能力，不做通用自由 Agent 框架。 + +代码 TODO： + +- [ ] 定义 `AgentTool`、`ToolResult`、Schema 校验； +- [ ] 工具注册表； +- [ ] 只读/低风险写/付费/人工确认权限级别； +- [ ] AgentRun 状态迁移校验； +- [ ] Step 创建、开始、成功、失败幂等服务； +- [ ] 运行级预算与步骤上限； +- [ ] AITask 关联和费用汇总； +- [ ] 取消、恢复、stale 标记； +- [ ] 最小运行查询 Serializer； +- [ ] 不实现模型自由 tool-calling 循环。 + +预计目录： + +```text +core/backend/apps/agents/runtime.py +core/backend/apps/agents/registry.py +core/backend/apps/agents/policies.py +core/backend/apps/agents/permissions.py +core/backend/apps/agents/tools/base.py +core/backend/apps/agents/tests/ +``` + +测试： + +- [ ] 非法状态迁移拒绝； +- [ ] 重复执行同 Step 不产生副作用； +- [ ] 超预算停止； +- [ ] 取消后不创建新 Step； +- [ ] waiting_task 恢复使用原 AITask； +- [ ] 跨团队工具调用拒绝。 + +完成标准：可用假工具跑完一个固定 Run，未接任何业务 Agent。 + +启动口令：`确认开始 S04` +完成口令：`确认完成 S04，进入 S05` + +--- + +### [ ] S05：脚本 ContextSnapshot 与 Brief + +依赖：S04 已验收。 + +目标：建立脚本 Agent 稳定输入，不让 Coordinator 直接 ORM。 + +代码 TODO： + +- [ ] `ScriptAgentRequest/v1` Schema； +- [ ] `ScriptContextSnapshot/v1` Schema； +- [ ] `ScriptBrief/v1` Schema； +- [ ] `get_project_script_context.v1` 工具； +- [ ] `get_product_context.v1` 工具； +- [ ] `get_source_script.v1` 工具； +- [ ] 冻结 project/product/selling points/source script 版本； +- [ ] 规则构建 Brief； +- [ ] 返回结构化缺失项； +- [ ] 计算 snapshot hash。 + +测试： + +- [ ] auto/theme/manual/revise/segment snapshot； +- [ ] 商品、卖点和脚本 team 校验； +- [ ] 缺失字段返回固定错误码； +- [ ] 同输入 hash 稳定； +- [ ] 商品修改可检测 stale。 + +完成标准：不给模型调用，也能生成完整 Brief 或明确缺失项。 + +启动口令：`确认开始 S05` +完成口令：`确认完成 S05，进入 S06` + +--- + +### [ ] S06：确定性脚本校验器 + +依赖：S05 已验收。 + +目标：把能用代码判断的规则从提示词和模型自检中移出。 + +代码 TODO： + +- [ ] `ScriptValidationReport/v1`； +- [ ] JSON/字段类型检查； +- [ ] 镜数、总时长、单镜时长； +- [ ] 旁白字数； +- [ ] hook/pain/selling/cta 覆盖； +- [ ] 卖点覆盖； +- [ ] 实体与 `entity_refs`； +- [ ] 商品事实、价格、认证、功效来源； +- [ ] 禁止词和绝对化表达； +- [ ] revise_segment 越界修改； +- [ ] issue code、severity、repairable。 + +测试：每个规则至少一个通过样例和一个失败样例。 + +完成标准：输入草稿可稳定得到可审计报告，不调用模型。 + +启动口令：`确认开始 S06` +完成口令：`确认完成 S06，进入 S07` + +--- + +### [ ] S07：脚本生成工具接入 AITask + +依赖：S06 已验收。 + +目标：把 S02 生成内核包装成受控付费工具。 + +代码 TODO： + +- [ ] `quote_text_generation.v1`； +- [ ] `generate_script_draft.v1`； +- [ ] 能力需求与实际 ModelConfig 记录； +- [ ] 用户明确模型时校验，不静默替换； +- [ ] 自动模式仅在 policy 允许时路由； +- [ ] 每次模型调用创建/关联一条 AITask； +- [ ] ToolResult 只返回 Draft 和任务摘要； +- [ ] Provider 失败复用现有退款； +- [ ] 输入快照和 prompt version 进入 request_payload。 + +测试： + +- [ ] 明确模型/自动路由； +- [ ] 余额不足； +- [ ] Provider 失败； +- [ ] 契约异常； +- [ ] 重复工具执行不重复扣费。 + +完成标准：工具可独立生成 Draft，尚未自动保存和编排。 + +启动口令：`确认开始 S07` +完成口令：`确认完成 S07，进入 S08` + +--- + +### [ ] S08：脚本 Coordinator MVP + +依赖：S07 已验收。 + +目标：先实现最短闭环，不接语义评审和自动修订。 + +MVP 流程： + +```text +collect_context +→ build_brief +→ quote +→ generate_once +→ normalize +→ validate +→ save_candidate +→ waiting_human +``` + +代码 TODO： + +- [ ] 固定状态迁移； +- [ ] 每一步对应 AgentStep； +- [ ] 缺输入进入 waiting_user； +- [ ] 超预算进入 waiting_approval； +- [ ] AITask 执行时进入 waiting_task； +- [ ] 校验失败保存报告并进入 needs_review； +- [ ] 通过后保存未采用 ScriptVersion； +- [ ] Run 可取消、恢复； +- [ ] 不自动 adopt。 + +测试：正常、缺输入、余额不足、生成失败、校验失败、取消、恢复、重复调度。 + +完成标准：后端测试中能完整运行一次 Agent MVP。 + +启动口令：`确认开始 S08` +完成口令：`确认完成 S08，进入 S09` + +--- + +### [ ] S09：Agent API、事件和恢复任务 + +依赖：S08 已验收。 + +目标：提供稳定 API，前端断线不影响 Agent。 + +代码 TODO： + +- [ ] 创建 ScriptAgentRun API； +- [ ] Run/Steps 查询 API； +- [ ] actions API：补输入、批预算、取消、请求修改； +- [ ] 事件查询 `after=sequence`； +- [ ] 可选 SSE 仅投影数据库状态； +- [ ] Celery resume task； +- [ ] 活动 Run 扫描和僵尸恢复； +- [ ] 同项目同 Agent 活动运行限制； +- [ ] API team/permission 校验。 + +测试：断线重连、重复创建、并发 action、越权、恢复不重复调用模型。 + +完成标准：不依赖浏览器连接即可完成 Run。 + +启动口令：`确认开始 S09` +完成口令：`确认完成 S09，进入 S10` + +--- + +### [ ] S10：前端接入真实 Agent 状态 + +依赖：S09 已验收。 + +目标：在现有脚本页面灰度接入，不重做整页。 + +代码 TODO： + +- [ ] 新增 Agent API/types； +- [ ] 输入摘要卡； +- [ ] 真实计划和 Step 状态； +- [ ] 缺失信息补充卡； +- [ ] 预算确认卡； +- [ ] 校验报告； +- [ ] 候选脚本和采用入口； +- [ ] 页面刷新恢复 Run； +- [ ] feature flag 切换 Agent/legacy； +- [ ] 移除 Agent 模式下的硬编码假“自检完成”。 + +测试：组件状态、刷新恢复、错误展示、legacy 页面不受影响；执行前端 build。 + +完成标准：灰度用户可以完成 MVP，旧入口仍可回退。 + +启动口令：`确认开始 S10` +完成口令：`确认完成 S10，进入 S11` + +--- + +### [ ] S11：Handoff、采用前检查和输入过期 + +依赖：S10 已验收。 + +目标：让下游读取结构化交接，不依赖 Agent 对话。 + +代码 TODO： + +- [ ] `ScriptHandoff/v1`； +- [ ] required_assets/acceptance/open_questions； +- [ ] AgentArtifact 关联 ScriptVersion 和报告； +- [ ] ScriptVersion metadata 写 run/schema/hash 摘要； +- [ ] `check_script_adoptable.v1`； +- [ ] adopt 前比较 snapshot hash； +- [ ] stale 禁止采用； +- [ ] 采用仍调用现有业务服务。 + +测试：Handoff Schema、过期输入、采用事务、下游实体/资产需求读取。 + +完成标准：采用脚本有可追溯 Handoff，Agent 不直接推进下一阶段。 + +启动口令：`确认开始 S11` +完成口令：`确认完成 S11，进入 S12` + +--- + +### [ ] S12：可选语义评审与一次定向修订 + +依赖：S11 已验收；S00 已确认首期需要此能力。 + +目标：在 MVP 稳定后增加有限协作，不修改固定状态机边界。 + +代码 TODO： + +- [ ] `ScriptReviewReport/v1`； +- [ ] `review_script_semantics.v1`； +- [ ] 仅规则通过或指定 warning 时评审； +- [ ] `revise_script_draft.v1`； +- [ ] 只传结构化 issue； +- [ ] 自动修订最多一次； +- [ ] 修订后重新跑全部规则； +- [ ] 第二次仍失败进入 needs_review； +- [ ] 评审/修订分别报价和关联 AITask。 + +测试：跳过评审、评审通过、定向修订、预算不足、达到上限。 + +完成标准：绝不形成无限评审/修订循环。 + +启动口令：`确认开始 S12` +完成口令：`确认完成 S12，进入 S13` + +--- + +### [ ] S13：完整回归、指标和灰度 + +依赖：S11；如实施 S12 则还依赖 S12。 + +代码 TODO： + +- [ ] 全模式集成测试； +- [ ] 任务、退款、恢复、采用回归； +- [ ] 指标：契约通过率、事实错误率、卖点覆盖率、采用率、费用、耗时； +- [ ] feature flag 按团队灰度； +- [ ] 管理端能查询 Run/Step/AITask； +- [ ] Agent 出错允许用户主动回旧入口； +- [ ] 完成发布/回滚说明。 + +灰度闸门：先内部团队，再小比例客户，再逐步默认开启；每一级都需要用户确认。 + +启动口令：`确认开始 S13` +完成口令：`确认完成 S13，进入 S14` + +--- + +### [ ] S14：旧脚本编排退役评估 + +依赖：S13 已稳定运行至少一个约定观察周期。 + +本步骤默认只评估，不直接删除。 + +检查： + +- [ ] 是否还有客户端调用 `script-agent-stream`； +- [ ] 是否还有活动旧任务； +- [ ] Agent 成功率、费用、耗时、采用率达标； +- [ ] 历史任务和脚本可继续读取； +- [ ] 新生成内核已被工具复用； +- [ ] 回滚方案存在； +- [ ] 用户明确批准下线。 + +允许删除：旧前端入口、旧 SSE 编排薄壳、硬编码假步骤。 +禁止删除：生成内核、normalize、ScriptVersion、AITask、计费、Provider、采用服务。 + +启动口令：`确认开始 S14 评估` +删除口令：`确认执行旧脚本编排下线` +完成口令：`确认完成 S14` + +## 4. 每步完成汇报模板 + +```text +步骤：Sxx +状态：等待用户验收 +本步改动文件： +行为变化： +数据库 migration：有/无 +测试命令与结果： +未通过项： +遗留风险： +回滚方式： +未实施的下一步内容： +请确认：“确认完成 Sxx，进入 Syy” +``` + +## 5. 推荐首次执行 + +从 `S00` 开始。没有得到 `确认开始 S00` 前，不修改任何代码。 diff --git a/docs/agents_todo/视频项目脚本Agent_协同引入实施方案.md b/docs/agents_todo/视频项目脚本Agent_协同引入实施方案.md new file mode 100644 index 0000000..6cc0700 --- /dev/null +++ b/docs/agents_todo/视频项目脚本Agent_协同引入实施方案.md @@ -0,0 +1,792 @@ +# 视频项目—脚本 Agent 协同引入实施方案 + +> 目标：在不推翻现有视频项目、脚本版本、AITask、计费和人工采用流程的前提下，把当前“一次模型生成脚本”升级为可暂停、可恢复、可审计、可校验、可有限修订的脚本 Agent。 +> 架构原则：松耦合、高内聚、可复用、精简化、可扩展。 +> 代码基线审阅时间：2026-07-17。 + +## 1. 结论先行 + +脚本 Agent 不应等同于“把现有提示词再加长”，也不应一次引入多个可自由互相调用的 Agent。推荐方案是： + +```text +一个脚本领域协调器 ++ 一组职责单一的协作节点 ++ 一组受控业务工具 ++ 现有模型、任务、计费和脚本版本能力 ++ 确定性校验优先 ++ 最多一次语义评审、一次定向修订 ++ 用户最终采用 +``` + +协作节点包括：上下文收集、Brief 规划、脚本生成、规则校验、语义评审、定向修订、交接包构建。只有“生成、语义评审、语义修订”可能调用模型；数据读取、字段校验、时长镜数、卖点覆盖、禁用词和落库都由确定性代码完成。 + +这套设计能让脚本功能真正具备 Agent 的核心特征：读取状态、形成计划、调用受控工具、观察校验结果、在预算内决定是否修订、保存过程和等待用户确认。同时避免无限循环、模型乱选工具、重复扣费和错误自动采用。 + +## 2. 当前代码基线与改造边界 + +### 2.1 当前链路 + +```text +pipeline.tsx 组装 prompt/mode/model +→ POST /api/projects/{id}/script-agent-stream/ +→ projects/views.py::script_agent_stream +→ ai/script_agent.py::stream_script_agent +→ 固定 system + user messages +→ Provider 单次流式文本调用 +→ normalize_draft +→ ScriptVersion + ScriptSegment +→ SSE 返回草稿 +→ 用户调用 adopt-script +``` + +当前名称包含 `script_agent`，但核心仍是单次模型调用；没有独立运行状态、工具循环、校验决策、运行预算和恢复机制。 + +### 2.2 必须直接复用 + +| 能力 | 当前代码 | 新 Agent 用法 | +| --- | --- | --- | +| 商品、项目与阶段 | `apps/products`、`apps/projects` | 通过只读工具访问，不让 Agent 直接 ORM | +| 脚本模型调用 | `core/backend/apps/ai/script_agent.py` | 拆出纯生成服务，保留旧入口作回退 | +| 电商脚本 Skill | `script_agent.py` 当前 Skill 加载 | 作为可版本化领域提示模板 | +| 结构归一化 | `normalize_draft()` | 继续作为兼容层，不承担全部业务校验 | +| 脚本产物 | `ScriptVersion`、`ScriptSegment` | Agent 草稿仍落现有领域表 | +| 单次 AI 任务 | `AITask` | 每次生成/评审/修订各一条，不表示整个 Agent 运行 | +| 模型配置 | `ModelConfig`、Provider | 由模型路由器或用户明确选择 | +| 积分 | reserve/charge/release | 每个付费步骤继续走现有闭环 | +| 人工采用 | `adopt-script` | 首期保持，Agent 不自动推进阶段 | +| 前端流式展示 | `pipeline.tsx`、SSE | 改成 Agent 事件的展示层，不作为真实状态源 | + +### 2.3 本次不做 + +- 不让脚本 Agent 自动生成图片、故事板或视频； +- 不自动采用脚本； +- 不让模型直接访问数据库或任意 HTTP； +- 不保存或展示模型完整思维过程； +- 不重写 Provider、计费、脚本版本和项目阶段； +- 不做多个自由对话 Agent 的互调网络； +- 不允许无限评审、无限修订或静默换模型。 + +## 3. 五项架构原则如何落到代码 + +| 原则 | 落地方式 | 禁止做法 | +| --- | --- | --- | +| 松耦合 | Agent 只依赖工具协议和领域契约；Provider、ORM、计费藏在工具实现后 | 协调器直接查表、直接请求火山接口 | +| 高内聚 | 脚本规划、脚本校验、脚本交接全部放在 script 领域目录 | 把脚本规则继续堆进通用 `services.py` | +| 可复用 | Run/Step、预算、权限、事件、模型路由、工具注册为公共基础设施 | 为脚本单独复制任务、计费、SSE 框架 | +| 精简化 | 固定状态机；首期 1 次生成、可选 1 次评审、最多 1 次修订 | 首期引入通用图式编排器或自由循环 | +| 可扩展 | 契约带 `schema_version`，工具带版本，策略由 policy 配置 | 依赖自然语言隐式约定字段 | + +## 4. 推荐代码结构 + +建议新增独立 Django app `core/backend/apps/agents/`，公共运行能力与 AI Provider 分离： + +```text +core/backend/apps/agents/ +├─ apps.py +├─ models.py # AgentRun / AgentStep / AgentArtifact +├─ enums.py # agent_type、状态、step 类型 +├─ registry.py # Agent 与工具注册表 +├─ runtime.py # 状态机驱动、恢复、取消、步骤上限 +├─ policies.py # 预算、重试、审批策略 +├─ permissions.py # 工具权限和团队边界 +├─ events.py # 运行事件投影，不保存模型思维过程 +├─ routing.py # 能力需求 → ModelConfig +├─ schemas/ +│ ├─ common.py +│ └─ script.py # ScriptAgentRequest/Brief/Report/Handoff +├─ tools/ +│ ├─ base.py # ToolSpec、JSON Schema、执行结果 +│ ├─ project.py # 项目只读工具 +│ ├─ product.py # 商品上下文工具 +│ ├─ models.py # 模型能力与报价工具 +│ └─ script.py # 生成、保存、采用前检查 +├─ script/ +│ ├─ coordinator.py # 脚本 Agent 状态机 +│ ├─ context.py # 输入快照和缺失项 +│ ├─ brief.py # 确定性 Brief 构建 +│ ├─ generator.py # 调用现有 script_agent 纯生成能力 +│ ├─ validators.py # 确定性规则校验 +│ ├─ reviewer.py # 可选语义评审 +│ ├─ reviser.py # 定向修订，最多一次 +│ ├─ handoff.py # 下游结构化交接包 +│ └─ prompt_versions.py # 提示模板版本和兼容策略 +├─ tasks.py # Celery 恢复/继续 AgentRun +├─ serializers.py +├─ views.py +├─ urls.py +└─ tests/ + ├─ test_runtime.py + ├─ test_script_contracts.py + ├─ test_script_agent.py + └─ test_script_tools.py +``` + +前端建议： + +```text +core/frontend/src/ +├─ api.ts # AgentRun API +├─ types.ts # 运行与契约类型 +├─ routes/pipeline.tsx # 保留业务页面，替换提交适配器 +└─ components/agent-run/ + ├─ run-progress.tsx # 计划和步骤状态 + ├─ validation-report.tsx # 错误/警告/通过项 + ├─ approval-card.tsx # 报价、采用、继续修订 + └─ input-question-card.tsx # 澄清问题 +``` + +脚本业务规则不放进 `components/agent-run`；公共组件只渲染通用状态。 + +## 5. 公共 Agent 运行数据 + +### 5.1 AgentRun + +一个 `AgentRun` 表示一次完整脚本协作，不等于一次模型调用。 + +```text +id +team_id +created_by_id +agent_type script +scope_type project +scope_id project_id +goal 用户目标摘要 +status created/collecting/waiting_user/planning/ + waiting_approval/running/waiting_task/ + validating/needs_review/succeeded/failed/ + cancelled/budget_exhausted/stale +schema_version script-agent-request/v1 +input_snapshot 冻结后的输入 +policy_snapshot 本次预算和重试规则 +plan 简短结构化计划 +current_step +estimated_cost +actual_cost +stop_reason_code +stop_reason_message +lock_version 乐观锁，防并发继续 +started_at/completed_at +``` + +### 5.2 AgentStep + +```text +id +run_id +sequence +step_type collect/plan/tool/model/validate/review/ + revise/persist/approval/handoff +name +tool_name/tool_version +input_summary 脱敏、可审计输入 +output_summary 结构化摘要 +status +idempotency_key 同一运行内唯一 +ai_task_id 模型步骤关联现有 AITask +estimated_cost/actual_cost +attempt +error_code/error_message +started_at/completed_at +``` + +### 5.3 AgentArtifact + +Agent 不复制完整脚本，只引用现有产物： + +```text +run_id +step_id +artifact_type script_version / script_handoff / + validation_report / brief +object_type +object_id +version +summary +metadata +``` + +`ScriptVersion` 仍是脚本真相源；AgentArtifact 只是说明“哪个运行生成或检查了哪个版本”。 + +## 6. 输入契约 + +### 6.1 前端请求 `ScriptAgentRequest/v1` + +```json +{ + "schema_version": "script-agent-request/v1", + "project_id": "uuid", + "mode": "auto | theme | manual | revise | revise_segment", + "instruction": "用户补充主题或修改意见", + "source_script_version_id": null, + "target_segment_id": null, + "selected_selling_point_ids": ["uuid"], + "preferences": { + "style": "真实测评", + "character": "都市白领女性", + "duration_seconds": 30, + "aspect_ratio": "9:16" + }, + "model_policy": { + "mode": "explicit | auto", + "model_config_id": "可选", + "quality": "standard", + "cost_ceiling_points": 30 + }, + "idempotency_key": "前端生成的 UUID" +} +``` + +关键修正：卖点必须传真实 ID，不再把标题装进 `selling_point_ids`；后端读取 ID 后保存卖点标题和内容快照，保证后续商品修改不改变本次运行事实。 + +### 6.2 冻结输入 `ScriptContextSnapshot/v1` + +```json +{ + "project": { + "id": "...", + "updated_at": "...", + "current_stage": "script", + "product_id": "..." + }, + "product": { + "id": "...", + "updated_at": "...", + "title": "...", + "brand": "...", + "category": "...", + "description": "...", + "target_audience": "...", + "specs": {}, + "selected_selling_points": [ + {"id": "...", "title": "...", "content": "..."} + ] + }, + "creative": { + "mode": "theme", + "instruction": "早八通勤场景", + "style": "真实测评", + "character": "都市白领女性", + "duration_seconds": 30, + "aspect_ratio": "9:16", + "shot_policy": {"shot_count": 2, "shot_duration_seconds": 15} + }, + "source_script": null +} +``` + +运行期间只使用 snapshot；保存前再比较 project/product `updated_at`。发生关键变更则运行转 `stale`，禁止直接采用旧结果。 + +## 7. 协作角色与职责边界 + +| 协作节点 | 类型 | 输入 | 输出 | 是否调用模型 | +| --- | --- | --- | --- | --- | +| ScriptCoordinator | 状态机 | AgentRun | 下一合法步骤 | 否 | +| ContextCollector | 工具组合 | project_id、request | ContextSnapshot、缺失项 | 否 | +| BriefBuilder | 领域规则 | ContextSnapshot | ScriptBrief | 首期否 | +| ScriptGenerator | 生成器 | Brief、输出契约 | ScriptDraft | 是，最多 1 次 | +| ContractNormalizer | 兼容器 | 模型原始文本 | 规范化草稿 | 否 | +| ScriptValidator | 规则引擎 | Draft、Snapshot | ValidationReport | 否 | +| SemanticReviewer | 独立评审 | Draft、rubric | ReviewReport | 可选，最多 1 次 | +| ScriptReviser | 修订器 | Draft、可修复问题 | 新 Draft | 是，最多 1 次 | +| DraftPersister | 领域服务 | Draft、reports | ScriptVersion | 否 | +| HandoffBuilder | 领域服务 | ScriptVersion、reports | ScriptHandoff | 否 | + +这里的“协同”通过结构化产物完成，不传递长篇聊天历史，也不让节点自由决定调用任意下一节点。 + +## 8. Agent 状态机 + +```mermaid +stateDiagram-v2 + [*] --> Collecting + Collecting --> WaitingUser: 必填事实缺失或口径冲突 + WaitingUser --> Collecting: 用户补充 + Collecting --> Planning: 上下文完整 + Planning --> WaitingApproval: 超过自动预算或用户要求确认 + Planning --> Generating: 预算内 + WaitingApproval --> Generating: 用户批准 + Generating --> WaitingTask: AITask 在执行 + WaitingTask --> Validating: 生成完成 + Validating --> Persisting: 无错误且无需语义评审 + Validating --> Reviewing: 仅有语义风险 + Validating --> Revising: 存在可自动修复问题且未修订 + Reviewing --> Persisting: 通过或只有警告 + Reviewing --> Revising: 可修复且未修订 + Revising --> WaitingTask: 修订任务已提交 + Validating --> NeedsReview: 不可修复或已达上限 + Reviewing --> NeedsReview: 高风险或已达上限 + Persisting --> HumanReview + NeedsReview --> HumanReview + HumanReview --> Succeeded: 用户采用 + HumanReview --> Planning: 用户给出新修改意见 + HumanReview --> Cancelled: 用户放弃 + Succeeded --> [*] +``` + +每次恢复只根据数据库状态和最后成功步骤继续；SSE 断开不会取消后端运行。用户主动取消时，尚未提交的步骤停止；已提交 AITask 按现有任务能力取消或等待完成，但不得重复提交。 + +## 9. 工具接口设计 + +### 9.1 工具统一协议 + +```python +class AgentTool: + name: str + version: str + permission: str + input_schema: dict + output_schema: dict + + def execute(self, context, arguments) -> ToolResult: + ... +``` + +统一 `ToolResult`： + +```json +{ + "ok": true, + "data": {}, + "warnings": [], + "error": null, + "audit": {"source_versions": {}, "duration_ms": 12} +} +``` + +### 9.2 脚本 Agent 工具 + +| 工具 | 权限 | 复用代码 | 说明 | +| --- | --- | --- | --- | +| `get_project_script_context.v1` | 只读 | Project、metadata、stage | 返回项目配置和真实状态 | +| `get_product_context.v1` | 只读 | Product、SellingPoint | 返回事实和版本快照 | +| `get_source_script.v1` | 只读 | ScriptVersion/Segment | revise 时读取源版本 | +| `quote_text_generation.v1` | 只读 | 现有 pricing | 生成/评审/修订前报价 | +| `generate_script_draft.v1` | 付费 | `stream_script_agent` 拆出的生成内核 | 只负责一次结构化生成 | +| `review_script_semantics.v1` | 付费可选 | 文本 Provider | 只返回评审 JSON，不改稿 | +| `revise_script_draft.v1` | 付费 | 文本 Provider | 只修指定 issue_code | +| `save_script_version.v1` | 低风险写 | `persist_script_draft()` | 保存未采用版本 | +| `build_script_handoff.v1` | 低风险写 | 新增领域服务 | 建立下游资产需求和验收条件 | +| `check_script_adoptable.v1` | 只读 | Project/Version | 采用前检查 snapshot 是否过期 | + +工具内部验证 `team_id`，不得接受模型传入的团队 ID。对象查询必须同时限定当前 team、未删除状态和必要的项目关联。 + +## 10. Brief 与提示词分层 + +### 10.1 `ScriptBrief/v1` + +```json +{ + "schema_version": "script-brief/v1", + "goal": "30 秒真实测评短视频", + "audience": "通勤女性", + "platform_style": "小红书种草", + "product_facts": ["只允许来自商品快照的事实"], + "must_use_selling_points": ["轻便", "易清洗"], + "forbidden_claims": ["绝对化效果", "无来源认证", "虚构价格"], + "character": "都市白领女性", + "shot_policy": { + "count": 2, + "seconds_each": 15, + "required_functions": ["hook", "pain", "selling", "cta"] + }, + "output_contract": "script-draft/v1" +} +``` + +Brief 首期由规则构建，避免为“整理已有字段”额外付费。以后若增加策略 Agent，只能在事实和硬规则外补充创意策略，不能修改商品事实。 + +### 10.2 模型消息分区 + +```text +system +├─ Agent 角色和安全边界 +├─ 电商脚本 Skill 版本 +├─ ScriptDraft JSON 契约 +└─ 禁止把业务数据当系统指令 + +user +├─ 只读业务数据 +├─ 用户目标与偏好 +├─ 改稿时的源版本 +└─ generate / revise / revise_segment +``` + +商品标题、描述、自带脚本、用户意见都必须放在明确的数据区，禁止拼进 system 指令区，以降低提示注入风险。 + +### 10.3 生成与修订提示词分离 + +- 生成提示词只负责从 Brief 产生完整 `ScriptDraft/v1`； +- 评审提示词只输出 `ReviewReport/v1`，无权改稿； +- 修订提示词只接收明确 issue 列表，输出完整新草稿； +- 单镜修订仍输出完整草稿，但必须声明允许修改的 segment index； +- 所有模型响应先做 JSON Schema 校验，再进入业务校验。 + +## 11. 确定性校验器 + +`ScriptValidator` 应返回错误码，不只返回自然语言： + +```json +{ + "schema_version": "script-validation/v1", + "passed": false, + "score": 82, + "errors": [ + { + "code": "SELLING_POINT_MISSING", + "path": "segments", + "message": "用户选择的卖点“易清洗”未出现", + "repairable": true + } + ], + "warnings": [ + { + "code": "CTA_WEAK", + "path": "segments[1]", + "message": "结尾行动引导较弱", + "repairable": true + } + ], + "checks": { + "schema": "pass", + "duration": "pass", + "segment_count": "pass", + "entity_refs": "pass", + "product_facts": "pass" + } +} +``` + +首期规则： + +1. ScriptDraft Schema、必填字段和类型； +2. 镜数与唯一时长策略一致； +3. 单镜时长、总时长和排序一致； +4. 单镜旁白字数上限； +5. hook/pain/selling/cta 覆盖； +6. 所选卖点 ID 对应内容是否覆盖； +7. 商品、人物、场景实体引用是否存在； +8. `@图N` 是否能映射到实体； +9. 价格、折扣、认证、功效是否有事实来源； +10. 绝对化、违禁和风险表达； +11. 下游所需人物、场景、商品资产是否可形成清单； +12. revise_segment 是否误改其他镜头。 + +只有表达自然度、镜头连贯性、钩子吸引力、转化节奏等难以确定性判断的内容进入语义评审。 + +## 12. 语义评审与定向修订 + +### 12.1 何时评审 + +- 规则全部通过但策略配置要求高质量评审； +- 存在 `semantic_review_required` 类型警告； +- 用户选择 production 质量档； +- 不对所有普通运行强制增加一次模型费用。 + +### 12.2 `ScriptReviewReport/v1` + +```json +{ + "passed": true, + "dimensions": { + "hook": 4, + "continuity": 4, + "clarity": 5, + "conversion": 4, + "fact_safety": 5 + }, + "issues": [ + { + "code": "HOOK_TOO_GENERIC", + "segment_index": 0, + "severity": "warning", + "repair_instruction": "保留商品事实，只改写前两句为通勤冲突" + } + ] +} +``` + +评审器不能直接采用脚本，也不能自行调用修订。Coordinator 根据 policy、预算、问题是否可修复和剩余次数决定下一步。 + +### 12.3 修订边界 + +- 最多 1 次自动修订； +- 只传结构化 issue 和原草稿，不传冗长聊天记录； +- 修订后必须重新跑全部确定性规则； +- 不再递归进行第二次自动修订； +- 仍未通过则保存带报告的候选或进入 `needs_review`，交给用户。 + +## 13. 模型路由 + +Agent 声明能力，不直接写供应商名称： + +```json +{ + "capability": "text", + "requires": { + "structured_json": true, + "streaming": true, + "context_tokens_min": 16000 + }, + "preferences": { + "quality": "standard", + "cost_ceiling_points": 30 + } +} +``` + +首期兼容策略： + +- 用户明确选择豆包/Gemini：尊重选择，校验模型可用性； +- 用户选择“自动”：路由器按 capability、健康度、成本和历史契约通过率排序； +- 生成失败不自动跨模型重复扣费，除非错误明确属于可安全回退的 provider 暂时故障且 policy 允许； +- 连续结构失败最多改用一次严格 JSON 提示，不无限切换； +- 路由结果写入 AgentStep 和 AITask，页面展示实际模型。 + +## 14. 产物与下游交接 + +### 14.1 ScriptVersion + +通过或带可接受警告的草稿使用现有 `persist_script_draft()` 保存： + +- `ScriptVersion.is_adopted = false`； +- `ScriptSegment` 保存逐镜字段； +- metadata 保存 hook、tone、entities； +- 增加 `agent_run_id`、contract_version、validation_summary、source_snapshot_hash； +- 不自动改变项目阶段。 + +### 14.2 `ScriptHandoff/v1` + +```json +{ + "schema_version": "script-handoff/v1", + "project_id": "...", + "script_version_id": "...", + "goal": "30 秒真实测评", + "product_fact_snapshot_hash": "...", + "segments": [ + { + "index": 0, + "purpose": "hook+pain", + "duration_seconds": 15, + "entities": ["product_1", "person_1", "scene_1"], + "required_assets": [ + {"entity_id": "product_1", "kind": "product", "view": "front"}, + {"entity_id": "person_1", "kind": "person", "view": "portrait"} + ], + "acceptance": ["商品前 3 秒内露出", "人物形象跨镜一致"] + } + ], + "validation_report_id": "...", + "open_questions": [], + "user_approved": false +} +``` + +未来视觉资产 Agent、故事板 Agent 只读取这个交接包和已采用 ScriptVersion，不读取脚本 Agent 的聊天记录。 + +## 15. API 设计 + +建议新增： + +```http +POST /api/projects/{project_id}/script-agent-runs/ +GET /api/agent-runs/{run_id}/ +GET /api/agent-runs/{run_id}/steps/ +GET /api/agent-runs/{run_id}/events/?after={sequence} +POST /api/agent-runs/{run_id}/actions/ +``` + +`actions`： + +```json +{"action": "provide_input", "payload": {...}} +{"action": "approve_budget"} +{"action": "request_revision", "instruction": "..."} +{"action": "adopt_artifact", "artifact_id": "..."} +{"action": "cancel"} +``` + +SSE 可保留为： + +```http +GET /api/agent-runs/{run_id}/events/stream/?after={sequence} +``` + +但 SSE 只投影数据库状态；断线重连使用 `after` 续传。首期若不增加持久事件表，可用 AgentStep + Run 状态轮询实现，先保证恢复正确，再优化实时动画。 + +现有 `script-agent-stream` 保留为 feature flag 下的 legacy fallback，灰度稳定后再逐步下线。 + +## 16. 前端交互 + +保留当前脚本页面，不把整个页面改成聊天框。新增四类可验证卡片： + +1. **输入摘要**：商品、卖点、时长、风格、人物、主题； +2. **执行计划**：收集 → 生成 → 校验 → 可选修订 → 保存； +3. **校验报告**：错误、警告、通过项、实际模型和费用； +4. **候选脚本**：版本差异、请求修改、采用。 + +当前页面“思考、自检完成”等文字必须改成真实状态：只有对应 AgentStep 成功才显示完成；不能再用前端硬编码步骤制造已校验的假象。 + +## 17. 幂等、并发、恢复和取消 + +- 创建运行使用 `(team_id, idempotency_key)` 唯一约束； +- 每个步骤使用 `(run_id, step_name, attempt)` 唯一幂等键； +- Coordinator 更新使用 `select_for_update` 或 lock_version； +- 同一项目同一 agent_type 默认只允许一个活动运行； +- 付费步骤先创建 AgentStep，再创建/关联 AITask； +- `waiting_task` 恢复时查询原 AITask，不新建任务； +- Worker 崩溃后由恢复任务扫描活动 Run； +- 用户取消只阻止后续步骤，已完成产物仍保留审计； +- 用户修改商品/项目后，旧运行输入 hash 不一致则标记 stale； +- adopt 前再次执行 `check_script_adoptable`。 + +## 18. 预算和权限 + +默认 policy： + +```json +{ + "max_steps": 8, + "max_generation_calls": 1, + "max_review_calls": 1, + "max_revision_calls": 1, + "max_total_points": 60, + "auto_spend_points": 30, + "allow_model_fallback": false, + "require_human_adoption": true +} +``` + +权限分级： + +- 自动允许：读项目/商品、构建 Brief、规则校验、保存检查报告； +- 预算内允许：生成、可选评审、一次修订； +- 必须确认：超自动预算、采用脚本、改变项目阶段； +- 禁止：外部发布、删除用户版本、绕过团队权限。 + +## 19. 错误分类与降级 + +| 错误 | 处理 | +| --- | --- | +| `CONTEXT_MISSING` | waiting_user，列出缺失字段 | +| `INPUT_STALE` | 标记 stale，要求基于新数据重开/刷新 | +| `MODEL_UNAVAILABLE` | 若用户明确模型则停止；自动模式可重新报价候选 | +| `CONTRACT_INVALID` | 使用 normalize 兼容一次；仍失败则停止 | +| `VALIDATION_FAILED` | 可修复且有预算则修订一次，否则 needs_review | +| `BUDGET_EXCEEDED` | waiting_approval/budget_exhausted | +| `CLIENT_DISCONNECTED` | 后端继续，前端可恢复 | +| `PROVIDER_ERROR` | AITask 现有退款；Run 记录错误，不重复扣费 | + +旧生成入口始终可作为人工选择的回退，不由系统无提示自动切换。 + +## 20. 测试方案 + +### 20.1 单元测试 + +- Request/Snapshot/Brief/Draft/Handoff Schema； +- 卖点 ID 与快照； +- 时长、镜数、字数、实体、CTA、风险词校验； +- revise_segment 不得修改其他镜； +- 工具 team 权限； +- 路由和预算策略； +- 状态机所有合法/非法迁移； +- 幂等键和重复 Celery 投递。 + +### 20.2 集成测试 + +- auto/theme/manual/revise/revise_segment 五种模式； +- 生成 → 校验通过 → 保存未采用版本； +- 生成 → 校验失败 → 修订一次 → 通过； +- 修订后仍失败 → needs_review； +- SSE 断开后恢复； +- provider 失败退款； +- 项目中途修改导致 stale； +- 用户采用后现有 `adopt-script` 同步镜头数量； +- legacy 与 Agent 灰度并存。 + +### 20.3 验收指标 + +- ScriptDraft 一次契约通过率； +- 商品事实错误率； +- 所选卖点覆盖率； +- 规则一次通过率； +- 自动修订成功率； +- 用户直接采用率； +- 采用前修改次数； +- 单次运行平均调用数、积分、耗时； +- 下游缺失实体/资产比例； +- 用户拒绝原因分布。 + +## 21. 分阶段实施 + +### 阶段 A：公共最小运行时 + +- AgentRun、AgentStep、AgentArtifact； +- 固定状态机、幂等、恢复、取消； +- 工具注册、Schema、权限； +- 预算策略和 AITask 关联； +- 查询 API 和最小前端状态展示。 + +### 阶段 B：拆出现有脚本生成内核 + +- 把 `stream_script_agent()` 中上下文、提示词、模型调用、归一化、持久化拆成可独立测试服务； +- 旧 API 继续调用这些服务； +- 不改变现有业务结果。 + +### 阶段 C：脚本 Agent MVP + +- ContextSnapshot、Brief； +- 生成一次； +- 确定性校验； +- 保存候选和 Handoff； +- 人工采用； +- 不接语义评审和自动修订。 + +### 阶段 D：有限协同 + +- 可选语义评审； +- 最多一次定向修订； +- 报价和预算确认； +- 输入过期检查； +- 真实步骤 UI。 + +### 阶段 E：灰度与优化 + +- 团队 feature flag； +- 对照旧链路采用率、费用和失败率； +- 根据 issue 数据优化规则，不靠盲目加提示词； +- 稳定后供项目导演 Agent 通过 Handoff 调用。 + +## 22. 一人串行开发工作量参考 + +以下为现有代码可复用、使用编码工具辅助、需求口径已确认后的研发量，不包含大规模 UI 重做和生产数据迁移异常处理： + +| 工作 | 参考工期 | +| --- | ---: | +| 公共最小 AgentRun/Step/Artifact、状态机、工具协议 | 3–4 天 | +| 拆分现有脚本生成服务并保持旧接口兼容 | 1.5–2 天 | +| Snapshot、Brief、校验器、Handoff | 2–3 天 | +| Agent API、Celery 恢复、预算与幂等 | 2–3 天 | +| 前端真实步骤、报告、确认与恢复 | 2–3 天 | +| 语义评审和一次修订 | 1.5–2 天 | +| 单元/集成测试、灰度开关和修正 | 2–3 天 | + +合计约 **14–20 人天**。如果公共 Agent 基础设施已由平台套图或其他 Agent 建好，脚本领域自身约 **8–12 人天**。MVP 先不做语义评审与自动修订，可压缩到约 **9–13 人天（含公共最小运行时）**。 + +## 23. 最终落地形态 + +```text +用户配置脚本目标 +→ Script Agent 冻结项目和商品事实 +→ 规则构建 Brief +→ 报价和模型路由 +→ 生成完整 ScriptDraft +→ 确定性校验 +→ 可选独立语义评审 +→ 最多一次定向修订并重新校验 +→ 保存未采用 ScriptVersion +→ 生成 ScriptHandoff +→ 用户确认采用 +→ 下游视觉/故事板读取结构化交接包 +``` + +这不是把现有“脚本助手”换一个名称，而是补齐运行状态、工具边界、观察校验、有限决策、预算、恢复和交接能力。实现后，脚本节点才具备受控 Agent 的实质，同时仍保持现有 AirShelf 项目流水线的稳定边界。