agent/docs/superpowers/specs/2026-09-10-short-drama-web-design.md

Short Drama Editor 网页接入设计

日期：2026-09-10。用户已同意“网页选剧 → 分析与剪辑方案 → 确认后渲染 → 预览审核 → 下载”的范围。本文件是实现前设计，不代表能力已上线。

1. 目标与边界

在既有 Agent Studio Mini 中调用原始 swads-short-drama-editor，提供可观察、可取消、可审核的授权英文短剧剪辑任务。原始 Skill、CMS 素材、已交付版本保持不变。保留现有 Drama Minis 报表流程。

不是仅注册 Skill 名称，也不把模拟素材、模型描述或机器检查通过当成真实成片验收。首版是本机单用户工具，不新增公网部署、广告投放、SWADS 上传、配音或合成镜头。

2. 已核对的基础条件

• 既有后端已有 Skill 只读快照、工具白名单、审批、Session/SSE 和受限报告下载。
• 现有 swads 连接只映射身份、指标目录、指标查询；没有网页 CMS 取片能力。swads token 不等于 CMS 管理员凭证。
• 最初 Qwen 连接在项目中声明为 text-only；2026-09-14 已实测同一网关的 Responses 双图识别成功，当前网页会话启用图片后也通过上传及识别测试。无需额外视觉模型，但 CMS 抽帧/证据绑定流程仍未实现；不能仅打开 supportsImages 开关就视为该流程已完成。
• bundled Python 已实测为 3.12.14，可用于 Skill 所需 audioop；当前 PATH 与已检查的 bundled bin 中未发现 FFmpeg/FFprobe。安装或指定媒体运行时需先确认可用来源。
• 2026-09-14 用户提供 https://swave.pencil-stub.com/。已从本机 /Users/wenxinduan/codex-outputs/Short 核对到同一项目：.ops/README.md 中 CMS 为 /swave/，后端为 /swave-api/。Supabase 为 shorts-sg（lmcysqgfhoxppwuorsmu），已只读核对 drama、episode、episode_source、subtitle_track 表结构。不得搜索或抽取浏览器存储中的凭证。

3. 方案选择

推荐在现有 Fastify 后端增加受控视频任务服务和媒体 worker，复用现有 Chat、Skills、事件和审批。只注册固定业务工具，不开放通用 shell。

仅导入 Skill 目录不足以实现取片、研究、视觉分析与渲染。把任意 shell 交给模型会扩大文件和网络权限，且难以绑定审核结果。这两种方式均不作为实现目标。

4. 用户流程

1. Skills 新增该 Skill 的“使用”入口，返回 Chat；状态区显示 CMS、媒体运行时、画面理解、参考研究分别是否可用。
2. 用户指定剧名或精确 drama_id、目标市场、用途和数量。同名剧必须先确认，不自动选择；不默认下载所有剧集。
3. 从已配置 CMS 读取完整剧集目录、简介、标签和字幕信息，验证首/中/尾集 HLS 访问。审批显示选定剧集、下载范围和预计磁盘量；凭证及签名 URL 不进入模型、事件或产物。
4. 通过字幕和代表帧建立跨开头/中段/后段的证据，生成新的 analysis_id，固定 drama_id/fetched_at 并执行原始 v2 验证器。视觉证据缺失时阻塞，不用字幕冒充观片。
5. 诊断 PASS 后才创建策略和研究参考。参考须具备短剧营销来源、完整可分析视频、捕获时间、证据链接及 A/B 等级；搜索摘要不能代替来源。三轮无合格参考即阻塞；Tier C 单独请求明确授权。
6. 页面展示剪辑策略、选段、预期长度、参考证据和不揭示的信息。用户批准的对象是不可变计划版本及摘要哈希，而不是无限制的渲染权限。
7. 固定 worker 校验全部门槛后运行原始 render_exact.py，再运行 QA。聊天请求可结束，渲染任务独立继续；页面显示进度并可取消。
8. 机器检查通过后产生 REVIEW 视频。页面展示视频、全片联系表、转场条、字幕风险帧与审核清单。用户需完整带声试听并确认画面、字幕、故事因果和结尾，登记审核人和时间。
9. 只有同一版本的机器检查和人工检查都 PASS，才可导出正式版本；待审视频允许以明确 REVIEW 标识下载。归档旧版本，不覆盖源片和已审成片。

5. 后端职责与接口

Skill 与工具

扩展显式资源清单，复制本 Skill 的引用、schema 和确定性脚本到只读快照，记录哈希。测试 fixture、缓存和历史报告不作为真实输入。所有相对引用必须完整可读。

业务工具负责能力检查、CMS 目录、授权素材准备、画面证据、诊断校验、参考证据、计划提交、渲染提交与状态读取。下载、将素材发往视觉服务、Tier C、渲染分别审批。模型不得调用人工审核通过接口，也不得伪造 PASS 文件。

CMS 连接器

独立接口提供 list/search drama、exact drama inventory、subtitles、签名播放。具体实现以用户指定 CMS 的真实代码或已验证接口为依据；只读目录并按管理员播放路径取源，绝不使用付费观看接口判断缺片。

CMS 凭证留在服务端内存或用户指定的密钥管理设施。固定目标主机和重定向策略；限制媒体协议、清单递归、字节数、时长与超时。HLS 列表及分片下载在受控连接层完成，渲染器仅接触本地批准素材。

模型与参考研究

沿用现有模型设置进行文本推理；视觉步骤必须使用已实际验证的图像输入连接并取得素材传输授权。不可静默更换供应商、模型或复用其他服务凭证。

Web 应用不能继承当前 Codex 会话的浏览器或搜索工具。研究服务必须单独配置并验证；未配置则显示所缺能力。允许用户提供可访问的参考及直接证据，但不自动将其标记为合格或绕过原始评分门槛。

媒体 worker

只执行固定 Python 3.12 脚本与已解析的 FFmpeg/FFprobe，不拼接 shell。子进程使用最小环境，不继承 CMS、模型或 swads 密钥。脚本需能在 Python 隔离启动时导入其受信任同目录 common 等模块。

所有模型指定的素材引用先解析成已批准 source ID，再由服务端生成本地路径；拒绝任意路径、符号链接、远程 URL、跨剧引用与写入原片。脚本输出也需要路径和大小校验。

首版全局最多一个重型媒体任务。每个任务有磁盘、媒体时长、运行时间和子进程数量上限；清单完整性不等于授权无限量下载。取消必须终止整个任务子进程树，而不仅是父 Python；清理仅针对该任务的精确临时目录。

任务与下载

VideoJob 使用独立 UUID、Session 所属关系、固定 drama_id 和不可变版本号。状态包括 waiting_input、preparing、analyzing、awaiting_plan_approval、rendering、machine_qa、review_required、approved、blocked、failed、cancelled。每次转移由服务端验证。

元数据原子持久化到项目内专用 runtime 目录，不复用重置 Session 时删除的临时报告目录。进程重启后将中断的运行标记为 interrupted/failed，绝不假装自动恢复。新 Session 只经显式恢复动作接管既有任务。

新增本机任务 API：列出/创建、读取状态、取消、读取审核资料、提交人工审核、导出。接口校验 task ID、版本及所属关系；下载只接受注册 artifact ID，不接受文件路径。视频预览支持受限 Range，JSON/审核文件下载为 attachment，禁止缓存。

本机导出遵守 Skill 的日期 → 剧名 → 素材结构；默认目的地是用户素材目录。确认路径及写权限后才复制，并校验字节和 SHA-256。没有目的地权限时保留项目内 REVIEW/已审文件并提供下载，不擅自写入其他目录。

6. 必须保留的校验

• 诊断 v2 PASS；drama_id、analysis_id、fetched_at 与全流程一致。
• 策略、参考评分、hook-map、recipe、matches、continuity、字幕、QA 等必需产物齐全；禁止模型只写 pass: true 就绕过校验器。
• 原始音频、1.00x、精确 24fps 边界；1080×1920、H.264/AAC、48kHz 双声道、最长 300 秒。
• 只用目标剧素材，保留动作/反应和 withheld_information，比较历次交付的故事线与选段，不把换字幕当新故事。
• 机器 PASS 与人工带声审核分别记录。媒体、计划或字幕哈希改变后旧审批与 QA 失效。
• 本地 PASS 不是平台批准。SWADS 上传本次不实现；未来单独授权并验证真实上传发起器及任务状态后再接入。

7. 验收与完成定义

先写失败测试再实现，覆盖目录/资源、未配置状态、路径逃逸、跨剧绑定、伪造 PASS、拒绝/超时审批、版本变更、任务取消及进程退出、重启中断、Range/下载边界和人工审核门槛。

运行原始 Skill 验证器测试与明确标记的合成媒体流水线测试；它们只证明技术链路，不算真实剪辑验收。保留原有日报自动化回归，运行 typecheck、lint、test、build。

网页端最终验收需要一部用户指定的授权英文剧、可用 CMS 和视觉/参考研究连接：选剧、完整目录检查、真实分析、方案审批、渲染、REVIEW 预览和下载。只有用户或获授权的真实审阅完成后才验证正式导出。缺任何一环，交付时逐项标明未验证，不宣称端到端可剪辑。

8. 实现前需要的输入

CMS 入口和本机源码已定位，不再要求用户重复提供。backend/app/routers/cms_playback.py 确认专用签名接口为 GET /api/v1/cms/playback/{episode_id}，字幕为同路径下 /subtitles/{locale}.vtt；生产完整前缀为 https://swave.pencil-stub.com/swave-api。它们依赖有效 Supabase 用户会话及后端管理员判定，不能用 swads token 或匿名 key 替代。

还需通过受支持的登录/授权流程配置 Agent Studio 自己的 CMS 会话，不能抽取另一浏览器的登录存储；然后确认视觉与参考研究连接并执行实际取片验收。源码接口已确认不等于线上授权取片已验证。不得因缺少这些条件而退化成假素材演示并标记完成。