azmat1127/yingqing

Fork 0

Files

T

hh bfca22677c docs: 添加双 Agent 协同实施方案

2026-07-17 18:14:54 +08:00

16 KiB

Raw Blame History

视频项目—脚本 Agent TODO 代码实施计划

依据：06_视频项目脚本Agent_协同引入实施方案.md
原则：一步一确认、先解耦再新增、每步可测试可回滚、公共能力只建设一次。
本文件是实施清单，不代表已经修改代码。

1. 强制执行规则

每个 TODO 都执行以下闭环：

1. 用户发送“确认开始 Sxx”
2. 只实施 Sxx 明确列出的范围
3. 执行本步骤测试和回归
4. 汇报文件、行为变化、测试结果、遗留风险
5. 用户发送“确认完成 Sxx，进入 Syy”
6. 才允许开始下一步

禁止：

一次确认后连续实施多个步骤；
未经确认顺手重构下一步代码；
测试未通过就标记完成；
为 Agent 重写 AITask、计费、Provider、资产和脚本版本；
在新链路稳定前删除旧入口；
把计划状态、测试结果或用户确认伪造为已完成。

状态标记：

[ ] 未开始
[~] 已获开始确认，实施中
[?] 实施完成，等待用户验收
[x] 用户已验收
[!] 阻塞

2. 全局实施顺序

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 校验；
不改变旧脚本生成结果结构。

预计文件：

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，不改前端。

建议接口：

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。

预计目录：

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 循环。

预计目录：

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 流程：

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. 每步完成汇报模板

步骤：Sxx
状态：等待用户验收
本步改动文件：
行为变化：
数据库 migration：有/无
测试命令与结果：
未通过项：
遗留风险：
回滚方式：
未实施的下一步内容：
请确认：“确认完成 Sxx，进入 Syy”

5. 推荐首次执行

从 S00 开始。没有得到 确认开始 S00 前，不修改任何代码。

16 KiB Raw Blame History Unescape Escape

视频项目—脚本 Agent TODO 代码实施计划

1. 强制执行规则

2. 全局实施顺序

3. TODO 明细

[ ] S00：冻结业务口径和基线

[ ] S01：修正脚本输入契约

[ ] S02：拆出现有脚本生成内核

[ ] S03：建立公共 Agent 数据骨架

[ ] S04：公共工具协议与最小运行时

[ ] S05：脚本 ContextSnapshot 与 Brief

[ ] S06：确定性脚本校验器

[ ] S07：脚本生成工具接入 AITask

[ ] S08：脚本 Coordinator MVP

[ ] S09：Agent API、事件和恢复任务

[ ] S10：前端接入真实 Agent 状态

[ ] S11：Handoff、采用前检查和输入过期

[ ] S12：可选语义评审与一次定向修订

[ ] S13：完整回归、指标和灰度

[ ] S14：旧脚本编排退役评估

4. 每步完成汇报模板

5. 推荐首次执行

16 KiB

Raw Blame History