64 lines
7.3 KiB
Markdown
64 lines
7.3 KiB
Markdown
# Agent Studio：SW Ads 图生视频接入
|
||
|
||
## 目标和已确认范围
|
||
|
||
用户已同意在 Agent Studio 中接入本机 `swads-image-to-video`，并明确不需要 CMS。暂停旧短剧剪辑 Skill 的排障；不删除原有代码、会话或素材。新流程不依赖 CMS 登录、剧名、字幕或旧剪辑器的参考/选段审核。
|
||
|
||
网页输入图片和动作要求，真实调用 H3，显示任务进度，最终播放、下载生成的有声 MP4。加载 SKILL.md 不算接入成功；必须验证真实提交、按原 job_id 收取结果和网页播放链路。
|
||
|
||
## 方案选择
|
||
|
||
1. **采用：受控 H3 工具接入。** 复用现有 Skill 目录、图片附件、审批、工具卡和本地视频 Range 响应模式，新增独立图生视频任务存储。不继承旧 CMS 编辑流水线。
|
||
2. 不采用直接开放全部 SW Ads MCP 工具：会扩大到素材审核、账户分配和投放，不符合本次范围。
|
||
3. 不采用多供应商自动切换：收费、时长与输入契约不同。首版不自动调用 Seedance 或其他付费提供商。
|
||
|
||
## 首版用户流程
|
||
|
||
1. 选择此 Skill，添加一张参考图片，填写动作、声音和目标时长。图片在本机接收后经现有附件校验，展示确认缩略图；同会话绑定，不能引用任意磁盘路径。
|
||
2. Agent 读取真实 Skill 及相关引用，生成简短提示词。页面展示精确参考图、提示词、H3 模式、尺寸和时长供本次确认。原先 CMS 素材的传输批准不复用到本次图片。
|
||
3. 本地参考图外传单独审批：明确上传到 SW Ads 存储，并形成 `review_pending`、未分配账户的参考素材记录。拒绝则不上传、不提交；默认不审核素材、不分配账户。
|
||
4. 服务端从当前 MCP 身份和明确返回的环境信息解析上传所需 tenant/platform；信息缺失或有歧义时阻断，不猜账户。按实际 upload_url 上传，按同一 upload_id/object_key 完成，按 import_status 获取 asset_id。
|
||
5. H3 生成提交单独审批。使用 `ref2va`；提交前保存请求和稳定幂等键，返回后立即保存 job_id。费用未知就如实提示，不宣称免费；不通过切换提供商绕过能力限制。
|
||
6. 工具卡和独立任务列表显示准备、上传中、入库中、待批准、提交中、排队、生成中、校验中、可预览、失败、提交状态未知。长任务不占用一次 LLM 对话，查询不重复提交。
|
||
7. 按返回任务的 MP4 artifact 收取成片，本地技术验证后提供受控播放器和下载。未完成视听检查时标为“生成预览／待检查”，不称最终广告审核通过。
|
||
|
||
## 真实能力约束
|
||
|
||
已现场发现 `video_h3_submit`、`video_job_status`、`creative_upload_from_url`、`creative_import_status`、`swads_whoami` 和 `video_h3_workers`。实现时通过同一 MCP 连接重新发现并核对 schema，仅允许上述范围内所需操作。
|
||
|
||
H3 当前是多参考图模式，1–9 张参考图，不保证首帧锁定，也不是原生视频延长。首版只做单图新生成，不提供原片续接、批量生成、自动选图或生成封面功能；这些不是本轮验收条件。原 Skill 所附本地验证脚本可以复用，不修改原 Skill。
|
||
|
||
默认竖屏 9:16、自然速度、有环境声。沿用此前 10 秒作为首个端到端验收的目标，而非声称 H3 已支持 10 秒：当前工具 schema 没有列出时长枚举，须验证实际支持。若 H3 不支持目标时长，明确报告限制，不自行改时长，不用减速、定格、循环或重复帧凑秒数，不自动多次生成或换付费模型。
|
||
|
||
## 实现边界
|
||
|
||
- `packages/harness`：受控 MCP 图生视频适配器、任务状态机、原子磁盘记录、参考图上传/收据绑定、H3 提交/查询和本地验证。原指标工具白名单保持隔离。
|
||
- `apps/server`：同源受限的图生视频任务列表、查询与注册 MP4 端点；只接受登记任务 ID，不接受任意 URL 或磁盘路径。既有附件在本次批准上传前复制到任务私有目录，保存哈希；删除聊天附件不破坏已批准任务。
|
||
- `apps/web`：Skill 使用入口、参数与审批提示、持久任务列表和生成卡片；展示真实状态、错误原因、播放器、下载和检查状态。任务列表不依赖恢复旧聊天历史。
|
||
- 原始 Skill 资源：显式清单复制 `SKILL.md`、三份 references 和 `scripts/media.py` 到受限快照。不给模型 shell 或任意网络访问。
|
||
- 密钥仅保留服务端运行环境，不进入模型上下文、网页、日志、任务 JSON 或仓库。私有上传回执保留于受限目录，不在 SSE 暴露签名上传地址或原图字节。
|
||
|
||
## 恢复与安全
|
||
|
||
独立任务目录保存 batch/id/revision、图片与输出哈希、原始请求、幂等键、upload_id、asset_id、job_id、时区时间、状态、检查报告。临时文件原子替换；同任务单写入者；重复点击不能产生重复生成。
|
||
|
||
刷新和后端重启后恢复任务列表，已取得 job_id 的只查旧任务。已写提交意图但未收到 job_id 的进入 `unknown_submission`：只有服务端确认支持按键查重/幂等才安全重试，否则要求人工核实，不盲重投。旧 revision 的迟到结果不得覆盖新 revision。
|
||
|
||
任务查询 30–60 秒节奏并退避，页面关闭不导致重复提交；后端恢复后可继续查询。生成拒绝、失败、超时和排队必须分开。首版不自动返修；用户可明确发起新修订，累计自动返修不能超过原 Skill 的两次上限。
|
||
|
||
参考上传只发送批准图片的实际字节至工具返回并验证的 HTTPS 地址。媒体下载仅限本任务 artifact 的已验证安全地址，限制大小和超时，禁止私网、localhost、凭据 URL 和未验证重定向；不开放通用代理。成片检查在本地受限进程执行，禁止 FFmpeg 自行联网。
|
||
|
||
删除旧任务、批量清理、最终成片再入库、账户分配和广告发布都不在本次授权内。
|
||
|
||
## 验证与完成标准
|
||
|
||
按 TDD 先写失败测试，再实现。覆盖：CMS 完全未调用；跨会话/任意路径拒绝；上传和生成审批拒绝无副作用；重复提交；入库未就绪；进程中断后未知提交；原 job 恢复；迟到 revision；错误或 HTML 假冒 MP4；私网/重定向拒绝；HTTP Range；页面真实状态和未默认批准。
|
||
|
||
先用明确标注的测试图片和伪造边界响应验证工程行为，不将其宣称为真实 H3 成片。之后使用用户提供或明确确认可发送的样图，页面批准后真实生成一条目标时长视频：核对返回 job_id、非零 MP4、实际时长、分辨率、帧率、完整解码和音轨，并实际观看、试听。生成模型不保证声音或人物一致，失败应如实展示，不能只凭音轨存在就称音频检查通过。
|
||
|
||
运行 lint、typecheck、全量测试、build 和网页端到端验收。只有真实目标时长视频在网页可播放、下载并验证一致时，才声明该目标已完成。若生成后端不支持时长或不可用，明确区分工程已接入与真实出片尚未完成。
|
||
|
||
## 评审状态
|
||
|
||
本文件是新增生成子系统的待确认设计，不代表代码或生成验证已经完成。用户确认后在当前已有工作树内按实现计划推进；不再询问此前已确认的“不用 CMS / 使用 H3 / 网页播放下载”范围。
|