InsightCut 审查修复交付说明
日期：2026-09-06。对应审查基准 34758208617baccb48115ab4bdbabb870ed170fb。
本次实现内容保护、生命周期协调、素材与字幕修正、维护防护和界面改进。修改保留在工作区，未提交、推送或发布。自动验证使用隔离数据库、临时媒体和假供应商；未迁移真实数据库，未清理现有素材，未打开或替换用户真实剪映草稿。
产品行为
- 用户仍可选择任意本机位置保存剪映草稿，包括其他磁盘。合法的外部图片、音频也可登记及下载；有效性依据实际文件内容与任务资产记录。
- 第一次使用原草稿名；同名默认另存
名称（2）、名称（3）。明确选择“备份后替换”时，先在目标磁盘暂存并校验，保留原目录备份，再发布新目录。结果提供实际位置和打开备份操作。 - 编辑按分镜、字段和编辑版本提交。刷新恢复提交队列；早期响应不能清掉后来修改。保存失败、冲突时保留文本，停止依赖保存的生成、重拆分和导出操作；提供重试及双方内容选择。
- 重拆分使用当前分镜全文，以换行连接原文本；初始全文独立保留。拆分前保存预案快照，工作台可恢复上次版本，恢复产生新版本，不清除历史素材。
- 失败、超时、取消保留已生成内容。删除时阻止新操作并等待写操作退出，页面显示“正在删除”，完成后旧操作不能重新写入。外部草稿及备份不随项目内部媒体删除。
- 维护清理仍是终端脚本，没有前端按钮，不自动执行删除。默认只读报告；服务持有维护锁时拒绝
--apply。
问题处理对照
| 编号 | 处理结果 | 主要实现与验证 |
|---|---|---|
| F03 | 编辑恢复、保存队列与冲突处理 | workspaceSaveQueue.js、workspacePendingStorage.js；旧响应、新编辑、刷新、同字段冲突、跨页面恢复；浏览器失败保存后刷新重试 |
| F04 | 当前全文、拆分快照与恢复 | database/reliability.py、SQLite 同事务版本更新；保存后重拆分、版本冲突、快照恢复测试 |
| F05 | 同名副本、备份替换、可恢复发布 | export/draft_publication.py；复制/预检失败、切换取消、重启恢复；完整链路验证副本和备份实际存在 |
| F09 | 项目写操作与删除协调 | task_runtime.py；生成、上传、素材选择、预览及导出登记；删除等待运行导出，拒绝新写入 |
| R01 | 导出状态持久化与恢复 | SQLite export_jobs；排队恢复、执行中重启转可重试失败、已完成文件存在性检查、发布日志恢复 |
| F12 / R02 | 有界执行与接口响应 | 普通/批量共享生成池 3，导出池 2，FFmpeg 全片渲染 1，试听池 2，其他文件 I/O 池 4，状态查询独立池 2；批量 50 项与并发取消 E2E |
| R03 | 超时巡检与外部进程退出 | 按阶段进度检查活跃令牌，超时请求取消；FFmpeg 可取消并回收子进程，探测/转码有超时；真实挂起子进程测试，无强杀 Python 线程 |
| F07 | 历史音频时长及参数快照 | 选择前实际 ffprobe，探测失败不切换；同步音色/TTS 参数，音频变化使字幕和预览指纹失效；新生成音频也保存真实时长 |
| F08 | 草稿重建使用任务字幕样式 | 所有重建传入任务快照；保留 SubtitleWriter，草稿构建及 AutoExporter 预检；重建草稿保留已有 MP4 预览记录 |
| F10 / F11 | 上传校验和不可变文件版本 | 单图 20 MiB/6400 万像素、批量 100 MiB/1–20 张；流式总量限制和实际解码；UUID 文件名、非不可变地址不长期缓存 |
| F15 | 按阶段检查配置 | 预案只检查生文/提示词，生产阶段再检查图片和实际音色 provider；单个及批量预案不因缺少图音凭证被提前阻断 |
| F16 | 图片导入等待确认 | 接口、数据库及第一次工作台读取均为待确认；独立目录保留上传图片，允许补文稿和配音 |
| F17 / R05 | 克隆音色状态及引用版本保护 | 常规更新不能写 ready；被引用音色换录音创建新记录，前端定位新记录，旧任务仍引用旧录音；试听失败保留参考文件 |
| F02 | 素材登记与下载校验完善 | 登记、单文件及两类素材包检查实际内容；个别无效文件跳过并附说明，全部无效返回失败；合法项目外素材正向测试 |
| F01 | 维护清理引用完整性与锁 | 草稿内部、历史资产、快照、导出结果、克隆文件均保护；数据库异常停止；不跟随外部符号链接；实际删除只在临时数据验证 |
| F06 / R06 | 旧入口输出隔离及恢复兼容 | CLI/GUI 每次独立工作目录；GUI 记忆用户草稿位置；恢复脚本事务内合并现有记录，保留选择及快照；占位模块明确未实现 |
| F14 | 项目资产后端分页检索 | 默认 40 项，全库搜索/筛选/稳定排序/计数；首屏不再逐项目请求全量分镜；85 个项目跨页验证、响应乱序保护 |
| F13 / R04 | 文件处理边界 | 媒体只读头部、保留 HEAD/Range；文档流式 20 MiB、DOCX 正文解压后 40 MiB；真实文本 PDF 测试，CI 安装 PDF 工具 |
| 其他观察 | 移动端、键盘与加载体验 | 四入口加“更多”、底栏安全区、当前阶段折叠展示、输入名称、弹窗焦点、纠正本地产品文案、路由延迟加载 |
| R05 | 配置原子保存 | 跨进程锁、同目录临时文件、flush/fsync/原子替换、版本冲突 409；故障保留旧配置 |
| E01 | Python 3.11 替代环境 | 新建 venv311/，保留 venv/；pytest 安全约束修正，安装工具修补，已安装依赖与 npm 审计；未重启真实服务 |
接口与数据兼容
API 基础路径仍为 /ai/native/video/kepu。
| 接口 | 约定 |
|---|---|
PUT /tasks/{id}/segments/{index} |
保留 expected_plan_version，冲突返回 409；更新全文与分镜在同一事务中 |
POST /tasks/{id}/plan/restore |
请求 expected_plan_version；恢复最近未恢复的拆分前快照，返回新的 plan_version |
GET /tasks/{id}/workspace |
增加 can_restore_plan；当前分镜为后续全文来源 |
POST /tasks/{id}/exports |
collision_policy=copy|backup_replace|error，默认 copy；显式旧 overwrite=true 映射备份替换，false 映射报冲突 |
| 原导出查询和取消接口 | 地址及主要状态保持；SQLite 为状态来源；重启中的执行标记可重试，结果丢失明确失败 |
POST /tasks/{id}/exports/{job}/reveal |
打开记录中的草稿目录；{"backup":true} 打开对应备份目录 |
GET /project-catalog |
page、limit、q、status、style、duration、sort；返回 items/total/page/limit/counts；旧任务列表保留 |
| 克隆参考录音替换 | 返回实际生效的 clone_id；调用方必须使用返回值，不能假定记录标识不变 |
| 配置保存 | 返回并接受 revision，旧版本冲突 409，失败可重新加载和重试 |
SQLite 增量迁移版本为 20260906_reliability，新增原始文稿字段、task_plan_revisions 和 export_jobs 及索引。迁移可重复执行，不删除旧字段，不移动媒体。迁移前通过 SQLite backup API 生成数据库旁的 <数据库文件名>.before-reliability.bak，已存在的备份不被覆盖。真实库尚未启动新版本，首次启动时才运行迁移。
内部草稿重建使用独立目录并复制必需素材，发布到外部磁盘时不依赖项目内部原图片/音频位置。外部根目录下 .insightcut/staging 暂存、.insightcut/backups 保留替换前目录、.insightcut/publications 保存切换日志。后端重启及下一次本地发布会先恢复未完成切换。
自动验收与边界
验收环境为 Python 3.11、新建依赖环境和现有 Node 项目依赖，所有数据库/媒体使用临时隔离目录。
- 后端全量测试：426 项通过；前端逻辑 139 项、组件 43 项通过；浏览器 E2E 7 项、真实后端批量 E2E 6 项通过。后端有一条第三方 anyio 别名弃用提示，无失败。
- 完整本地链路脚本：
ai-kepu-video-server/scripts/verify_local_flow.py。自动生成临时 SQLite 和有效 PNG/WAV，经真实分镜、草稿构建、SRT/VTT、FFmpeg、两类素材包和本地草稿发布。两段各 0.5 秒音频的字幕终点为 1 秒；ffprobe 验证实际音视频轨道。副本、备份目录和最终导出状态均检查。 - 路由拆分后入口 JS 为 320.77 kB（gzip 105.70 kB）。本机生产预览、模拟配置响应、Chromium 三个空浏览器上下文的首次内容绘制分别为 252/64/60 ms；首屏未加载工作台和设置页代码。这不是移动设备或真实供应商网络基准。
- 后端 Python 编译、前端生产构建、仓库资产检查、diff 空白检查；当前仓库没有独立 lint、类型检查或架构检查命令。
- Python 已安装环境及 npm 已知依赖漏洞审计零命中；这只反映审计当时的数据。
- Windows/macOS 路径规范化与草稿 JSON 兼容由自动用例覆盖；本机真实文件发布在 macOS 临时目录验证。
未验收：真实剪映客户端打开与实际剪辑回存、真实 Windows 文件系统发布、真实服务商生成质量。 没有调用付费服务或替代用户进行人工联调。磁盘满/复制失败使用故障注入，重启切换使用未完成日志恢复测试；未破坏真实磁盘或终止真实生产服务。无响应子进程使用临时 Python 进程注入，未对真实供应商做资源耗尽测试。
运行、备份恢复与回退
新版启动仍为后端 127.0.0.1:2002、前端 2001，CORS 仅允许这两个本机前端来源。项目说明采用 venv311/。新环境重建：
cd ai-kepu-video-server
python3.11 -m venv venv311
source venv311/bin/activate
python -m pip install 'pip>=26.2' 'setuptools>=83'
python -m pip install -r requirements-dev.txt
python -m uvicorn api_server:app --host 127.0.0.1 --port 2002 --reload
前端仍在 ai-kepu-video-web/frontend 运行 npm run dev。状态查询有独立的 2 个读取线程，导出 job 状态和取消不排队等待文件处理。全局执行上限目前固定在 src/api/work_limits.py，没有新增供用户设置的并发参数；批次自己的 1–10 并发（默认 3）和已有图音限流/重试配置仍有效。
维护报告命令为 python scripts/maintenance_report.py --dry-run。只有明确选择 --apply 才尝试删除，且要求后台服务已停止。不要将脚本指向剪映外部草稿或备份目录。日常生成、重试、恢复操作不触发维护删除。
回退顺序：
- 停止当前后端，让取消和文件写入安全退出；不在服务运行时替换 SQLite。
- 先用 SQLite backup API 给当前库再做一次一致备份，保留迁移后新增的内容。
local.db.before-reliability.bak只含迁移前状态，恢复它会回到迁移前时间点。 - 如确需数据库回退，通过 SQLite backup API 将选定备份恢复到当前库，保留全部媒体目录。不要在 SQLite 运行中直接覆盖数据库及 WAL 文件。
- 使用与旧代码相匹配的已验证环境启动。旧
venv/原样保留，但其 Python 3.9/依赖版本已知落后，不能把它直接当成新版代码的兼容环境；优先保留 Python 3.11 并还原对应旧依赖清单。 - 草稿回退：停止对该草稿的写入，在结果中打开备份位置；先给当前目录另存副本，再将选定备份复制回原名称。备份不会自动清理。日志尚未完成时先让后端执行恢复，不手动删除日志。
数据库一致复制可在停止服务后使用：
import sqlite3
from contextlib import closing
# 替换为实际选择的来源和目标；备份与恢复均使用相同 API。
with closing(sqlite3.connect('source.db')) as source:
with closing(sqlite3.connect('destination.db')) as destination:
source.backup(destination)
本轮没有新增 AI 视频生成、云端部署、自动垃圾清理或代码发布。