# 视频项目—脚本 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` 前，不修改任何代码。