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