InsightCut 分镜素材包导出修改方案

• 状态：待评审
• 日期：2026-08-16
• 版本：V1.0
• 涉及模块：导出中心、任务资产、分镜数据、文件打包

1. 背景与问题

InsightCut 当前提供两类主要交付结果：

1. 直接下载整片 MP4，用于查看、发布或交付成片。
2. 下载剪映草稿 ZIP，或直接写入本机剪映草稿目录，用于继续精修。

实际创作中还存在第三类需求：用户不需要已经合成的成片，也不准备继续使用剪映时间轴，只希望拿到按播放顺序整理好的原始分镜图片和逐段配音，方便交给其他剪辑软件、同事或后续自动化流程继续处理。

项目后端已经具备任务资产记录和素材 ZIP 下载接口，但当前导出中心没有把它作为正式交付模式呈现；现有打包逻辑还可能混入重新生成的历史版本，也缺少明确的分镜对应表、完整性状态和稳定的交付目录规范。

因此，本次增加第三种正式交付方式：分镜素材包。

2. 产品决策

2.1 三种交付方式并列

导出中心统一提供：

2.2 第一版采用的默认规则

• 浏览器不能直接下载一个裸文件夹，因此用户点击后下载 ZIP；解压后得到完整素材文件夹。
• 默认只导出每个分镜当前生效的图片与音频，不混入被替换、重新生成或未选中的历史版本。
• 图片和音频分开放置，但使用相同的三位序号建立一一对应关系，例如 images/003.png 对应 audio/003.wav。
• 按数值型 segment_index 升序排列，不按创建时间、数据库返回顺序或原文件名排序。
• 任务失败不阻止下载已有素材。只要存在至少一个可用的当前图片或音频，就允许生成“部分素材包”，并明确标出缺失项。
• 分镜清单、字幕和说明文件默认随包附带，不增加首版配置项。

3. 目标与非目标

3.1 目标

• 用户在导出中心能够一眼识别三种不同的交付用途。
• 一次点击即可获得结构清晰、顺序稳定的素材包。
• 相同序号的图片和音频可以直接配对，不需要用户再次改名或手工排序。
• 素材包反映预览页当前选中的有效素材，而不是素材历史全集。
• 已失败或素材不完整的任务仍可导出已经生成的内容。
• 不影响现有 MP4、剪映草稿和直接写入剪映的行为。

3.2 非目标

• 不在素材包内合并全部音频为单条音轨。
• 不统一转换图片或音频格式，首版保留当前有效文件的原始扩展名。
• 不把所有重新生成历史版本放进默认素材包。
• 不提供云端分享链接、跨设备传输或在线素材托管。
• 不在本次修改中增加素材剪辑、批量重命名或压缩质量配置。
• 不改变现有视频渲染、剪映草稿生成和模型调用流程。

4. 目标用户与关键场景

4.1 目标用户

• 使用 Premiere、Final Cut Pro、DaVinci Resolve 等其他剪辑软件的创作者。
• 需要把图片与配音交给剪辑同事的内容生产者。
• 希望归档原始生成资产，而不是只保存 MP4 的用户。
• 任务中途失败，但希望取走已经生成内容继续处理的用户。

4.2 关键场景

1. 完成视频后，用户下载全部当前分镜图片和逐段配音，在其他剪辑软件中重新搭建时间轴。
2. 用户替换或重新生成某张图片后再次下载，素材包只包含最新选中的图片。
3. 任务在第 8 个分镜后失败，用户下载当前已有的 8 张图片和 7 段音频，并从清单中看到缺失情况。
4. 用户将素材包交给其他人，对方仅通过文件编号与清单即可恢复正确播放顺序。

5. 用户流程

1. 用户从预览编辑页进入“导出中心”。
2. 页面展示 MP4 成片、分镜素材包、剪映草稿三种交付方式。
3. 分镜素材包卡片显示：
   • 当前图片数量；
   • 当前音频数量；
   • 分镜总数；
   • “素材完整”或“部分素材”状态。
4. 用户点击“下载素材包 ZIP”。
5. 后端基于点击时的任务快照，按 segment_index 重新校验当前文件并生成或复用 ZIP。
6. 浏览器开始下载 <项目名>_素材包.zip。
7. 用户解压后，可通过相同序号配对图片和音频；缺失项可在清单中查看。

6. 文件包规范

6.1 目录结构

<安全项目名>_素材包/
├── images/
│   ├── 001.png
│   ├── 002.jpg
│   └── 003.webp
├── audio/
│   ├── 001.wav
│   ├── 002.mp3
│   └── 003.wav
├── metadata/
│   ├── storyboard.csv
│   ├── manifest.json
│   └── subtitles.srt
└── README.txt

6.2 排序与命名

• 展示序号为 segment_index + 1。
• 序号最少三位补零：001、002、010、100。
• 超过 999 个分镜时，位数自动扩展，所有文件仍保持等宽编号。
• 图片与音频保留原扩展名，不在打包阶段转码。
• 不把文案片段直接拼入文件名，避免跨系统非法字符、路径过长和隐私扩散。
• ZIP 内只使用相对路径和 / 分隔符，不写入用户本机绝对路径。

6.3 storyboard.csv

使用带 UTF-8 BOM 的 CSV，确保中文可直接由常见表格工具打开。字段至少包括：

6.4 manifest.json

机器可读清单，至少包含：

{
  "schema_version": 1,
  "task_id": "...",
  "project_name": "...",
  "generated_at": "...",
  "segment_count": 3,
  "image_count": 3,
  "audio_count": 2,
  "complete": false,
  "missing_image_orders": [],
  "missing_audio_orders": [3],
  "segments": []
}

segments 中逐项记录序号、文案、时长、包内路径及素材状态。该文件只保存必要的项目交付信息，不写 API Key、本地绝对路径、VoiceClone DataURL 或其他凭证。

6.5 README.txt

说明：

• images/001.* 与 audio/001.* 属于同一个分镜；
• 文件按编号升序使用；
• 缺失文件以 storyboard.csv 和 manifest.json 为准；
• 素材包不等同于剪映草稿，不包含可直接打开的剪映时间轴。

7. 功能需求

P0：首版必须完成

P0-1 导出中心增加第三种交付卡片

• 卡片名称：分镜素材包。
• 主按钮：下载素材包 ZIP。
• 描述文案：按播放顺序整理当前分镜图片和逐段配音，可用于其他剪辑软件或归档。
• 卡片展示当前图片数、音频数、总分镜数与完整性。
• 首版不增加复杂勾选项，减少下载前决策成本。

P0-2 当前生效素材规则

• 以 task_segments 中每个分镜当前的 image_path、audio_path 为主数据源。
• 预览页替换图片或重新配音后，下一次打包必须使用更新后的当前路径。
• task_assets 仅用于旧任务兼容和当前路径恢复，不得把同一分镜的历史候选素材全部写入默认包。
• 每个分镜最多写入一张当前图片和一段当前音频。

P0-3 完整包与部分包

• 所有分镜的图片与音频都存在：状态为“素材完整”。
• 任一分镜缺图片或音频：状态为“部分素材”，仍允许下载。
• 只有图片或只有音频时仍允许下载，缺失目录可以保留为空目录或由清单明确表示为空。
• 当前没有任何可用图片和音频时按钮禁用，文案显示“暂无可打包素材”。
• 不以任务是否 completed 作为素材包下载的唯一门槛。

P0-4 确定性与一致性

• 相同任务快照重复打包时，目录结构、编号和清单顺序保持一致。
• 打包前逐个校验文件实际存在且位于允许的本地媒体根目录。
• 数据库有路径但文件已丢失时不让整包失败；跳过该文件、记录缺失并返回部分包。
• 同一文件不得因资产记录重复而在包内出现多次。

P0-5 缓存与失效

• 可缓存同一任务快照生成的素材 ZIP，避免重复压缩。
• 下列任一项变化时必须使旧缓存失效：
  • 分镜增删或顺序变化；
  • 当前选中图片变化；
  • 当前音频变化或重新配音；
  • 分镜文案或时长变化；
  • 对应文件大小或修改时间变化。
• 重新下载不能返回修改前的旧素材。

P0-6 文件与安全约束

• 项目名必须经过跨平台文件名清洗，并处理空名称、重名和 Windows 保留名称。
• ZIP 内禁止绝对路径、.. 和目录穿越。
• 只允许打包任务已引用且位于项目允许根目录中的文件，不接受前端传入任意本地文件路径。
• 不在响应、日志、清单或文件名中输出敏感配置。
• 大包不得长期完整驻留内存；优先生成临时文件后流式返回，并使用原子重命名避免并发下载读到半成品。

P1：建议后续补充

• 在项目素材库提供“下载全部历史版本”，与导出中心的“当前生效素材包”明确区分。
• 显示预计包大小，并在磁盘空间不足时给出明确错误。
• 为素材包增加校验和文件，方便跨设备传输后验证完整性。
• 支持仅下载图片或仅下载音频，但不改变默认的一键完整包入口。

P2：暂不进入本次范围

• 合并全部分段音频为完整旁白音轨。
• 按指定规格批量转码图片或音频。
• 生成 Premiere、Final Cut Pro 或 DaVinci Resolve 的工程文件。
• 云端分享、协作审批和过期下载链接。

8. UX 与页面布局

8.1 推荐布局

桌面端采用两层布局：

• 第一行：MP4 成片 与 分镜素材包 两张轻量交付卡片并列。
• 第二行：剪映草稿 独占整行，保留目录选择、Mac/Windows 和直接写入等复杂配置。

这样既让三种交付方式处于同一层级，又避免把剪映路径配置压缩进过窄的三列卡片。

平板与手机端按 MP4 → 分镜素材包 → 剪映草稿 单列排列，主按钮保持完整宽度。

8.2 状态设计

8.3 文案边界

• 使用“素材包”或“分镜素材包”，不称为“工程文件”或“剪映草稿”。
• 明确“当前素材”，避免用户误以为包含所有生成历史。
• 部分包必须告诉用户“仍可下载已有内容”，不能只显示失败状态。

9. 数据、API 与技术方案

9.1 现有能力

• 任务分镜已经保存当前 image_path、audio_path、文案、时长和素材状态。
• task_assets 已保存生成、重新生成、上传、选择和字幕等资产记录。
• 已存在 GET /ai/native/video/kepu/tasks/{task_id}/assets/download，能够生成素材 ZIP。
• 前端已经定义 getAssetsDownloadUrl(taskId, type)，但导出中心尚未使用。

9.2 API 修改建议

扩展导出状态

在 GET /tasks/{task_id}/export-state 的 outputs 下增加：

{
  "materials": {
    "available": true,
    "complete": false,
    "segment_count": 10,
    "image_count": 10,
    "audio_count": 8,
    "missing_image_orders": [],
    "missing_audio_orders": [4, 9],
    "snapshot_key": "..."
  }
}

如果任务尚无 MP4 或剪映草稿，但已经有分镜素材，接口仍应返回素材包状态，而不是因为草稿路径缺失整体返回 404。

这要求移除当前导出状态接口对 task.result.draft_path 的整体前置依赖：MP4 和剪映可以分别返回不可用，但素材包状态仍直接由 task_segments 计算。

新增素材包导出目标

现有素材下载接口保留为“素材库历史批量下载”，不直接改变它的产品语义。异步导出框架新增独立目标：

POST /tasks/{task_id}/exports
Content-Type: application/json

{
  "target": "materials"
}

• materials 与现有 mp4、draft、draft_local 并列。
• 后端基于点击时的 task_segments 快照生成 ZIP，任务状态通过现有导出任务查询接口轮询。
• 任务完成后，结果返回素材数量、缺失数量、snapshot_key 与下载地址。
• 前端完成轮询后自动触发浏览器下载，同时保留“再次下载”按钮，从用户视角仍是一次点击完成打包与下载。
• 素材包导出不得要求任务已有 task.result 或 draft_path。

新增正式素材包下载地址

建议增加只负责返回已完成正式交付包的下载地址：

GET /tasks/{task_id}/download-materials?snapshot_key=<snapshot_key>

• 下载地址只读取后端生成并校验完成的 ZIP，不接收任意素材路径。
• snapshot_key 与当前包不匹配时返回“素材已变化，请重新打包”，不能静默下载旧包。
• 现有 /assets/download?type=all 继续服务素材历史集合，避免把“当前交付包”和“全部历史素材”混成同一能力。

响应：

• 200 application/zip：完整包或部分包均可返回。
• 404：任务不存在。
• 409：任务存在但没有任何可打包的当前素材。
• 500：打包过程异常；错误信息不得包含敏感路径或凭证。

9.3 后端结构建议

• 将素材选择、快照计算、清单构建和 ZIP 写入从路由中拆到独立的 asset_package 服务，避免继续扩大 routes.py。
• 路由负责鉴权边界、参数校验和响应；服务负责确定性打包。
• 生成到不依赖剪映草稿路径的任务专属目录，例如 data/media/{task_id}/exports/；失败任务没有 task.result 时也必须可用。
• 先写安全临时文件，完成后原子替换目标 ZIP；不得继续使用 BytesIO 将整个大包长期放在进程内存中。
• 任务删除流程应继续清理素材包缓存，不增加孤立文件。
• 首版无需新增数据库表或迁移；快照信息可写入包内 manifest 或同目录 sidecar 文件。

9.4 前端修改建议

• ExportPage 增加 materials 任务状态和第三张交付卡片，并沿用现有导出轮询机制。
• 打包完成后使用正确的后端 API_BASE 触发下载；不能直接打开当前未拼接 API 域名的相对素材地址。
• 导出页标题说明更新为：生成成片、下载按分镜整理的素材包，或继续使用剪映草稿精修。
• 状态条增加“分镜素材”指标，并调整为桌面四列、窄屏单列。
• 下载素材包失败不能影响 MP4 和剪映卡片的可用状态。
• 动态打包状态使用 aria-live 告知屏幕阅读器，按钮在打包中禁用以避免重复任务。

10. 变更条件与兼容规则

11. 验收标准

1. 导出中心可同时看到 MP4、分镜素材包、剪映草稿三种交付方式，三者用途文案不混淆。
2. 一个包含 12 个完整分镜的任务下载后，images/ 和 audio/ 均按 001 至 012 排列，同号文件对应同一分镜。
3. 第 3 个分镜重新选择图片后再次下载，包内 images/003.* 为当前图片，旧图片不在默认包中。
4. 第 4 个分镜缺少音频时仍能下载；包内没有 audio/004.*，清单明确标记第 4 段音频缺失，页面显示“部分素材”。
5. 失败任务只要保留至少一个当前图片或音频，就能够下载已有素材。
6. 完全没有图片和音频的任务不能触发空 ZIP 下载，页面显示“暂无可打包素材”。
7. 分镜顺序变化后，所有编号、CSV、JSON 和 SRT 顺序同步变化。
8. 同一任务存在多个重新生成历史素材时，每个分镜默认最多导出一张当前图片和一段当前音频。
9. ZIP 内不存在绝对路径、上级目录引用、API Key、DataURL 或其他凭证。
10. 大文件打包不会要求把整个 ZIP 长期保存在进程内存中；并发下载不会获得半成品。
11. 原有 MP4 下载、草稿 ZIP 下载和写入本机剪映流程保持可用，相关回归测试通过。
12. 桌面、平板和手机宽度下，三种交付方式均可读、可操作，剪映路径字段不会被第三张卡片挤压失真。

12. 测试重点

• 数值排序：重点覆盖索引 0、1、9、10、99、100。
• 当前素材选择：生成、重新生成、上传替换和重新配音后的快照。
• 完整、仅图片、仅音频、部分缺失、无素材五类任务。
• PNG/JPG/WEBP 与 WAV/MP3/M4A 等不同扩展名。
• 中文项目名、特殊字符、同名项目和超长项目名。
• 当前文件和历史资产指向同一路径时的去重。
• ZIP 路径穿越与不受信任本地路径拦截。
• 大素材包、并发点击、缓存复用和缓存失效。
• 失败任务资产保留与导出。
• MP4 和剪映草稿导出回归。

13. 成功指标与观测

首版不预设未经验证的数值目标。上线后至少记录以下本地事件或日志统计，以便评估：

• 素材包下载发起、成功和失败次数。
• 完整包与部分包的数量分布。
• 打包耗时、包大小和缓存命中情况。
• 缺失图片、缺失音频和非法路径的失败原因分布。
• 新能力上线前后 MP4 与剪映草稿导出的错误率是否发生回归。

日志不得包含完整敏感本地路径、凭证或音频 DataURL。

14. 风险、依赖与发布顺序

14.1 主要风险

• 直接按 task_assets 全量打包会混入历史素材，必须明确以当前分镜路径为主。
• 当前素材 ZIP 使用内存缓冲，大项目可能造成内存峰值，需要改为临时文件或流式方案。
• 旧任务路径信息不完整，需保留安全的兼容恢复逻辑和部分包能力。
• 浏览器下载只能交付 ZIP，页面必须提前解释“解压后得到文件夹”。
• 图片或音频变化后若缓存未失效，用户会拿到旧文件，这是必须覆盖的 P0 测试。

14.2 依赖

• 现有本地 SQLite 中的 task_segments 和 task_assets。
• 现有本地媒体目录与项目删除清理逻辑。
• Python 标准库 ZIP 能力；首版不需要新增第三方服务。

14.3 推荐发布顺序

1. 抽离并测试素材包构建服务，完成当前素材选择、排序、清单、安全和部分包逻辑。
2. 扩展导出状态与素材下载 API，补充 API 测试。
3. 在导出中心加入第三种交付卡片、状态和响应式布局。
4. 回归 MP4、剪映草稿、失败资产保留与项目删除。
5. 更新 README 中的产品能力和导出说明。

15. 待确认项

以下为本方案的推荐默认值，评审时可一次确认：

1. 默认包只包含每个分镜当前选中的图片和音频，不包含历史版本。
2. storyboard.csv、manifest.json、subtitles.srt 和 README.txt 默认随包附带，不提供首版开关。
3. 第三种模式名称使用“分镜素材包”，下载按钮使用“下载素材包 ZIP”。
4. 失败或生成中的任务允许下载点击时已有的部分素材，并明确标记缺失项。