# 多模型与多模态制作

本文记录本轮已实现的接入方式、制作行为和恢复边界。独立应用 0.3.0 与 DSH 插件 0.6.0 分别构建和发布；两仓保留相同版本的媒体契约及测试样例，没有跨仓库运行依赖。

## 接入结构

| 内容 | 独立应用 | DSH 插件 |
| --- | --- | --- |
| 文本规划、场景代码、视觉检查 | 应用模型中心的 Chat Completions 连接与角色 | DSH 模型目录、会话与代理能力；工作台选择 DSH 模型 |
| 图片生成 | 应用模型中心的 Images 连接 | 插件模型中心的 Images 连接 |
| 视频生成 | 应用模型中心的媒体网关连接 | 插件模型中心的媒体网关连接 |
| 配音 | Speech 连接或原有本地／远程配音设置 | 插件 Speech 连接或原有本地／远程配音设置 |
| 持久生成任务 | 应用媒体任务服务 | ProjectHub 共享的插件媒体任务服务；DSH Jobs 包装进度观察 |

插件直接调用已配置的媒体服务，不要求修改 DSH 内核，也不要求独立应用或公共网关常驻运行。生图、生视频不会注册为伪聊天模型。厂商原生视频协议需要另写适配器；填写地址不能自动获得协议兼容性。

模型中心将连接、模型及角色分开保存：`ProviderConnection` 保存稳定 ID、协议、地址、认证方式、凭据引用、超时与并发上限；`ModelDefinition` 保存本地模型 ID、供应商模型名、输入／输出模态与参数；`RoleBinding` 分配导演、场景代码、视觉检查、图片、视频和配音角色。一个连接可配置多个模型，目录探测不可用时仍可手工填写。

独立应用的对话导演和工作台创作使用统一接入层。原有 `custom` 配置迁入默认连接，旧配置及 TTS 设置保留兼容读取，迁移失败不删除旧配置。插件文本继续由 DSH 管理，插件模型中心只配置媒体角色。

### 凭据和检查

- 独立应用桌面凭据使用 Electron safeStorage；浏览器开发模式仅存服务进程内存。安全存储不可用时不回退明文保存。
- 插件使用 DSH 凭据服务的插件专属引用。注册表只保存引用，每次提交、查询或取消重新取密钥，因此可轮换密钥；服务不可用时需要密钥的操作报错暂停，无密钥端点及手动制作仍可使用。
- 正在执行的任务保存连接与模型快照，地址或模型修改不会改变旧任务。被未结束任务引用的连接和模型不可删除，连接关键通信字段也受使用状态保护。
- 检查连接只验证配置、凭据或模型目录，不发起付费生成。界面区分配置检查与生成结果。目录查询失败也不等于真实生成一定失败。
- 密钥不进入工程、任务参数、模型提示或工程包。下载产物使用服务返回的 URL，不向该地址附加供应商认证头。

## 从工作台使用

在 **模型与素材生成 → 配置模型连接** 保存连接，再添加模型并分配角色。完成配置后，选择生成类型、模型、目标镜头和提示词；不选镜头时，采用结果仅加入素材库。

首批媒体操作为文生图、文生视频和图生视频。模型输入／输出模态及连接协议共同决定可用操作。图生视频只发送本轮明确选择并授权的工程图片，镜头任务进一步限制到该镜头使用或参考的资产；最多 3 张，总计 6 MiB，单边不超过 4096 像素，单图不超过 16777216 像素。发送前验证 PNG、JPEG 或 WebP 的实际数据，任务记录保存资产 ID 和内容哈希。

生成结果先成为候选素材。下载、实际媒体检查通过后显示为「待采用」，此时还没有覆盖工程。采用时通过工程写队列核对 `expectedRevision`；工程变化或镜头删除会保留候选结果并提示处理。明确选择当前版本采用，才将结果登记到工程；视频默认静音。

### 首批协议

| 能力 | 协议及请求 | 返回与恢复 |
| --- | --- | --- |
| 文本／视觉 | Chat Completions 兼容请求，普通 JSON 与 SSE | 使用模型角色路由；视觉检查发送实际选择的帧 |
| 文生图 | Images Generations 兼容请求 | URL 或 Base64；下载重试复用原结果 |
| 生视频 | 媒体网关 v1：提交、查单、按请求 ID 对账、可选取消 | 远程状态与本地下载／校验阶段分离 |
| 配音 | 原有本地语音或 Speech 兼容请求 | 合成音频进入工程音轨；工作流记录不确定提交 |

生视频网关接口、JSON Schema 和脱敏样例见 [媒体网关 v1](media-gateway-v1/README.md)。仓库内 `tests/media-gateway.ts` 是仅用于协议测试的本地网关，不随产品提供公共服务。协议测试不会调用真实计费服务。

## 持久媒体任务

每个任务保存稳定 taskId、clientRequestId、工程／镜头、起始版本、模型配置快照、输入哈希、远程 jobId、产物、用量与阶段时间。全局 `media-tasks/` 独立于工程目录；重启可枚举任务，运行请求及临时下载地址不写入可移植工程。

| 场景 | 实际行为 |
| --- | --- |
| 提交回执丢失 | 已先保存请求 ID。视频按请求 ID 对账，不盲目重发 POST；兼容生图无对账接口时保留「提交结果未知」，不自动重投 |
| 同一步骤恢复 | 工作流使用稳定 clientRequestId；调用返回与工作流记录之间中断也会找回原任务，同 ID 内容或工程范围不一致会拒绝 |
| 云端成功、下载失败 | 重试下载和校验；视频可重新查单获取更新后的签名 URL，不重新生成 |
| 断网、退出或禁用插件 | 保存本地状态并停止活动，不默认取消云端。服务恢复后查单；用户明确停止等待的任务保持暂停 |
| 停止等待 | 只暂停本地观察，远程状态另行显示 |
| 请求远端取消 | 尚未提交的本地排队任务可直接取消；已提交任务仅远端确认 `cancelled` 才显示云端已取消；未支持、请求失败或未取得 jobId 均不作此保证 |
| 工程版本变化 | 候选结果保留；采用使用当前工程版本，不静默覆盖 |
| 已完成或已采用 | 不再重新生成；采用回执通过工程中的任务来源记录保持幂等 |

媒体下载为流式写盘和 SHA-256 校验，默认单产物 512 MiB、单任务累计 1 GiB；服务选项可设置更低限额。默认最多同时观察 4 个任务，每个连接默认 2 个，连接并发上限可配置。候选文件采用前重新验证文件范围、哈希和真实媒体，客户端不能提交任意本地文件路径来替换任务产物。

### DSH 工具与任务

插件 `video_media` 提供生成、列表、状态、恢复、停止等待、采用和远端取消，只接受已配置连接／模型 ID 与工程资产 ID，不接受任意密钥、认证头或 URL。工具访问沿用工程及会话权限，子代理使用宿主委派关系确定工程范围。

从 DSH 工具生成时，先完成宿主 Job 准入，再提交远端，避免媒体已受理而宿主没有可见任务。DSH jobId 与持久媒体 taskId 分别记录。`job_kill` 仅停止该 Job 的等待；继续查询使用 taskId，远端取消使用工作台按钮或 `video_media.cancel`。插件重启不会恢复旧宿主 Job，但会恢复自己的媒体任务记录。

## 视频素材与工程 v2

本地 MP4、MOV、WebM、MKV 及服务返回的视频须经 ffprobe 检查，并由 FFmpeg 生成固定帧率 H.264 MP4 副本。工程保留原始文件与其 SHA-256，播放使用规范化副本及独立哈希；原件、副本、运行缓存分别保存。复制工程和独立应用备份同时包含原件与副本，缓存清理不能删除历史引用素材。

默认及硬上限为每份视频 512 MiB、60 分钟、8192 像素边长、120 FPS。环境设置 `maxVideoBytes` 可下调文件限额；原件与规范化副本分别检查，规范化后超过限额也会拒绝。浏览器内存导入视频限 32 MiB，较大文件通过可信桌面／宿主的本地绝对路径入口导入。代理可能比原件大，应为两份文件和处理临时文件预留空间。

每个镜头最多绑定一段主视频，可设置裁入、裁出、0.25–4 倍速度、`cover`／`contain` 和静音／保留原声。提取原声会建立可单独编辑的音频片段。镜头时长超过有效视频段时画面冻结在最后一帧，原声段结束后静音。代码场景可在视频上叠加字幕与图形；自定义代码的不透明全屏背景仍可能遮住视频，需要相应调整源码。

工程使用整数帧和有理数 FPS 定位源视频，预览与导出使用相同时间映射，解码完成后才捕帧；支持随机跳帧。音轨按片段裁剪、速度及工程位置混入最终音频。成片继续由本机浏览器与 FFmpeg 输出，不是云端整片渲染。

新工程保存为 schema v2，新程序读取 v1 并迁移，保留稳定 ID、源码、素材和本地版本历史。旧程序拒绝不支持的 v2，避免旧字段规则误写。独立应用 `.yingliu` 工程包升级为 v2，继续导入 v1；两端本轮不承诺完整工程包互通。

独立应用工程包保存当前工程、简报、源码、素材及生成来源，不保存完整撤销历史、对话、导出文件、运行任务或凭据；导入创建新的工程 ID。桌面采用流式 ZIP 写入、读取和哈希，默认媒体单文件 512 MiB、元数据单文件 24 MiB、包及展开总量小于 4 GiB、最多 256 条目；接口 `limits.fileBytes`／`limits.totalBytes` 可逐次下调硬上限。浏览器传输包限 64 MiB。插件继续通过复制整个工程目录（包括 `.studio/`）搬运影片；基目录中的连接、任务及会话映射单独留在原安装。

## 固定协作流程

**协作制作** 使用导演、画面制作、可选配音、可选候选关键帧检查和工程合并的固定流程。它有独立任务记录，分镜图仍表示影片播放顺序，没有变成通用工作流编辑器。

1. 导演输出结构化镜头计划。已有工程保持所选镜头 ID；空工程先通过一个独立事务建立分镜和默认源码，这个初始版本会保留，即使后续生成失败。
2. 按选定路径生成代码、图片或视频，并可并行制作配音。图片／视频路径保留已有代码供继续叠加编辑，不同时隐式重写每个镜头源码。最多 2 个工作单元并发，媒体请求还受模型连接并发上限约束。
3. 下载及实际媒体校验完成后，在工程写队列外暂存不可变素材。所有选定镜头的候选画面、配音和源码就绪后，构建不可变候选快照；启用视觉检查时，先捕获候选镜头中间帧、最多 3 帧，发送给视觉模型并记录帧号与哈希。捕帧或审片执行失败时不提交候选结果，可重试检查；空工程已经建立的初始分镜仍保留。只检查这些画面，不代表观看整片，源码检查不算视觉验收。
4. 候选结果完成检查后，一次 CAS 提交为工程版本。生成或审片期间的用户修改触发「待采用」；明确采用基于当前工程重新构建候选，启用视觉检查时重新审片，再按最新 revision 提交。目标镜头已删除时不自动重建，也不以旧候选帧证据确认新的合并内容。
5. 工程仍可手工编辑、撤销重做、预览和导出。恢复流程复用已完成步骤及已经提交的工程来源记录，不重复采用素材。

上传授权绑定本次工作流：参考图片来自明确选中的资产，关键帧检查另需同轮允许上传，不能自动扩大为整个资产库。关键帧从同一份不可变候选工程、源码和素材快照捕获，避免混合不同版本；最终提交仍核对主工程 expectedRevision。

流程重启后显示暂停，用户选择继续；已完成代码、素材和配音复用。明确失败／取消的媒体步骤可通过用户重试创建新尝试；提交结果未知的任务先对账。同步配音若提交后中断且没有资产回执，无法确认是否计费，流程不自动重复合成，应核对供应商记录后明确新建制作。

工作流支持任务数量上限。当前没有可靠的全流程预报价，设置金额上限会在调用任何导演、媒体或配音模型前暂停，不声称能保证未知费用。总费用显示未知；供应商提供同币种费用时可记录媒体小计，不把该小计当整片总费用。媒体记录包含生成、下载耗时和字节数；工作流记录步骤及模型调用耗时。响应速度、人工返修率、成片质量和实际成本收益仍需真实服务对比，不能从多模型接入本身推导。

## 验证和后续扩展

两仓使用同一组版本化 Schema、请求／响应样例及本地协议测试。媒体任务测试覆盖 URL／Base64、认证隔离、图片授权、能力限制、丢失提交、重启对账、稳定请求 ID、下载重试、密钥轮换、并发、暂停与取消、版本冲突和文件篡改。视频测试使用本地真实媒体检查裁剪、帧率、跳帧、音画及原件保存，不能用假网关产物推断视频编码质量。

可在各仓库运行：

```sh
npm run typecheck
node --import tsx --test tests/media-tasks.test.ts tests/workflows.test.ts
npm test
npm run build
```

完整验收状态以本仓库验收记录为准。本轮本地协议、媒体、类型检查或构建结果，不等同真实供应商生成成功、成片质量、原生桌面或新增跨平台验收。历史截图和平台记录保留原版事实。真实服务验收须用户配置服务后分别记录「协议通过」「生成成功」「成片质量」。

后续适配器可追加厂商原生图片／视频协议、可靠取消和用量报价。完整预算控制、更丰富的多视频轨道与剪辑、通用工作流画布及跨仓库工程包互通，不属于当前已实现能力；无需为现有能力新增公共常驻网关。