feat(editor): AI 编辑助手悬浮面板、插件权限体系与时间线渲染管线（M4–M6.3） (#411)
* feat(editor): 编辑器实施 M0-M1 - 剪辑入口占位与插件 SDK v2 垂直切片 - detail.tsx 新增剪辑成片视图（editor tab，常驻），概览页插入剪辑步骤卡 - plugin-types.ts 新增 v2 类型（EditorSlotKind/EditorPluginPermission/PluginManifestV2），修复权限数组交叉归约 bug - editor-slot-registry.ts 插槽注册表（优先级排序、幂等注册、订阅机制） - plugin-registry.ts 注册器 v1/v2 分支校验，v1 路径零改动 - editor-shell.tsx 垂直切片插件：timeline-panel 插槽真实渲染，验证插件链路全通 - 测试：插槽注册表 5 用例 + 命令测试骨架，v1 插件回归 21 例零回归 * feat(editor): 命令协议黄金文件 - editor-commands 纯函数 reducer + 8 个黄金 op * feat(editor): 快照撤销历史 - editor-history 有界 200 层 undo/redo * feat(editor): 命令状态机 store - dispatch/手势预览/1.5s 防抖保存/串行保存链 * fix(editor): createEditorStore 返回 zustand hook 类型修复 typecheck * feat(editor): 手势 echo 最小件 - 时间线面板拖拽移动/裁剪 + store 接线与本地持久化 * docs(editor): M2 完成状态记录 * feat(editor): M3.1 时间线面板选中联动 - store 选中状态 + 片段高亮/点击取消 * feat(editor): M3.2 预览监视器 - preview-renderer 插槽 + 真实媒体帧/播放头/时间码 * feat(editor): M3.3 片段检查器 - inspector 插槽 + 属性编辑入队可撤销 * feat(editor): M3.4 asset-ingest 素材库插件（addClip 命令入轨） * feat(editor): M3.4 补充 - host 上下文（项目信息+资产）、editor.tsx 接线、asset-ingest 纯函数、死代码清理 * feat(editor): M3.5 subtitle-tools - SRT import/export + rebuild from node snapshot * feat(editor): M3.6 transcription - deterministic mock ASR to subtitle track * feat(editor): M3.7 export - render plan + ffmpeg.wasm fallback export * feat(editor): M3.8 - render all 8 editor slots in three-pane layout + ai-assistant placeholder * docs(editor): M3 完成状态 - 8 插件 + 全插槽接线，冒烟待确认 * feat(editor): 编辑器媒体与时间线打磨 - 资产来源分组筛选、时间线全宽布局、拖拽末片段修复、OSS 降级本地存储、Concat 风格控制条与检查器 * fix(plugins): 合并上游后修复插件分类筛选对 v2 清单的类型兼容 * feat(editor): 时间线工具态与轨道操作打磨 - 工具按钮选中仅图标变色、监视器 Concat 式控制条、removeTrack 黄金命令与轨道行头移除按钮、maskClosable 迁移 * fix(api): 资源上传超 MaxBytesReader 上限时报中文大小限制而非英文裸 400 * fix(editor): 监视器控制条 - 修复播放按钮 JSX 模板闭合花括号缺失导致的编译错误 * feat(api): 本地媒体导入分片化对齐 Concat - >50MB 视频不再失败 - 分片会话三接口(POST开始/PUT单片/complete合并)、前端超50MB自动切8MB分片并失败整传重试、默认配额放宽(日200MB→2GB、总2GB→20GB)、UploadResourceFile 豁免单文件限 * feat(editor): 轨道行头新增可见性/静音开关按钮 - 复用现有图标资源，按轨道类型显隐；命令层新增 setTrackFlag 黄金命令（flag 白名单 fail-closed）并补单测 * docs(progress): 记录轨道可见/静音开关改动与复测项 * docs(editor): M4 转写与渲染任务设计 - 复用 Task 表与状态机、独立创建 API、worker 领取类型过滤、whisper HTTP provider（OpenAI 兼容 /v1/audio） * fix(api): OSS 上传失败自动降级本地存储时 body 已被 Transport 关闭 - newOSSRequest 用 NopCloser 包装请求体,服务端提前返回(签名 403)时不再关闭调用方持有的文件,降级分支 Seek 重读生效;补回归测试 * docs(progress): 记录媒体导入根治(分片+OSS 降级修复)复测项 * feat(api): 视频播放副本转码 H.265→H.264 + variant=playback 服务与启动回填 - 上传视频后异步探测 codec，H.265/AV1 走 moov 快速探测并转码 H.264 播放副本；GET /api/user-data/...?variant=playback 就绪时服务副本（独立 ETag :pb），未就绪回退原件并撤销后缀防 304 黑屏；storeResource 触发、启动幂等回填存量；前端播放失败自动轮询副本就绪后刷新 * fix(editor): 轨道至少保留一条 - 不可移除轨道点击 X 时居中浮现原因提示(2.2s 自动消失, aria-live)；修正可见性 toggle 传参 (visible===false 语义) ；轨道行内移除按钮改为常驻(不可移除时点击给提示) * feat(timeline): M4.1 字幕转写后台任务 - whisper.cpp 本地执行 - 新增 timeline_transcription 任务类型，worker 按类型分叉独立执行器（不走计费与模型渠道）；输入 resourceId+language，读取用户资源后 ffmpeg 预处理 16k 单声道 wav，POST 本地 whisper.cpp /inference，结果写回 segments+srt+language；未配置 CANVAS_WHISPER_BASE_URL 等失败均落明确终态；feature 门控；进度分阶段；含解析/SRT/快速失败单元测试 * feat(media): 素材卡片时长与媒体面板打磨 - 导入媒体解析时长（前端 media-metadata + 后端 project_asset durationMs 透出）随卡片展示；媒体面板/监视器/时间线相关样式细节收尾 * docs(progress): 阶段 C 监视器播放复检清单 - H.265 播放副本/真实播放驱动/时长链路待浏览器确认 * feat(timeline): M4.1 转写任务创建 API - POST /api/timeline/transcriptions - service CreateTimelineTranscriptionTask：IsDraining 守护 + feature 门控 + 资源归属与可转写类型校验 + 排队计 active 限额(含任务级/项目级存储估算)；local/whisper.cpp 标记，任务不经过模型路由与计费；createTaskWithinStorageQuota 复用与 ErrActiveTaskLimit 用户可读映射；测试覆盖排队成功(owner/type/provider 断言)、跨用户资源拒绝、非音视频拒绝 * feat(timeline): M4.3 字幕转写前端接线 - 真实任务替换 mock - 新增 services/api/timeline-tasks.ts（POST /timeline/transcriptions，复用 apiClient+request）；EditorTranscription 改为 创建任务→waitForGenerationTask 轮询(25min)→结果 segments 映射 SrtEntry[]→rebuildSubtitleClips 写入字幕轨道；实时展示 stage/progress，失败/空识别/无字幕轨道分别提示；素材选择支持音频与视频（取 storageKey 中的 resource id 提交） * fix(media): 播放副本状态收敛与轮询终态 - 无ffmpeg/远端存储/编码不可处理落 none 避免重复探测;前端 none 停轮询回原生播放并加 processing 上限 * feat(timeline): M4.2 时间线渲染任务 - POST /api/timeline/renders 创建（buildRenderPlan 校验含可渲染媒体、配额入队、local/ffmpeg、60min 超时）；worker 顶部按类型分叉 processTimelineRender；ffmpeg 合成产物写资源存储并经 ResultJSON 记 resourceId；render 计划/结果测试 PASS * fix(resource): 转码原子抢占与 OSS 请求体加固 - ClaimPlaybackTranscode 空/none→processing 单实例抢占避免重复转码，runPlaybackTranscode defer recover 落 failed；If-Range 与带 :pb 后缀的 serveETag 比较；无请求体的 OSS 请求不再包 NopCloser(nil)（防 Go 1.26 body 探测 nil 解引用） * style(editor): 修正字幕回写面板缩进 * docs(timeline): M4 设计文档按实现回写 - 单一 worker 池 + processClaimedTask 顶部按类型分叉（决策 3/4），端点统一为复数 /api/timeline/transcriptions 与 /api/timeline/renders（注册于 RegisterTaskRoutes），ResultJSON/feature gate/ffmpeg env 同步；Runbook M4 表格与状态行更新；auth.go API 前缀白名单补 timeline * fix(service): 修复上游 v1.2.5 公告配图删除保护自锁与测试夹具缺口 上游 #385 资源引用走查器对公告配图/草稿做了硬性引用检查，导致三个问题： - UpdateAnnouncement 在更新公告前对旧配图走查，必然命中当前公告自身引用而自锁， 公告替换配图功能实际不可用；DiscardAnnouncementImage 同理被草稿自身引用阻塞。 修复：ensureResourceHasNoBusinessReferences 支持忽略指定引用（当前公告/当前草稿）， 其余引用仍按原语义拦截。 - admin DeleteAdminResources 将公告草稿引用视为阻塞，但删除事务会级联清理草稿与 资源绑定，service 层永不进入事务，回滚审计注入测试无法到达预期路径。修复：service 预检时过滤公告草稿引用，与 repository 级联语义对齐。 - project_settings_test.go 夹具未建 ResourceReferenceSnapshot 走查的 Task/Session/ Message/TaskLog/Result/Announcement/AnnouncementImageDraft 表，报 no such table。 修复：夹具 AutoMigrate 补齐。 后端全量 go test ./... 通过。 * feat(editor): 成片导出接入后端渲染任务（M4.2 前端接线）- timeline-tasks 增 createTimelineRenderTask；editor-export 主路径改 POST /timeline/renders 轮询取 resourceId 内嵌预览/下载，ffmpeg.wasm 降级保留 * feat(editor): M5 插件权限执行（fail-closed）- plugin-permission-check 新建（8 插槽最小权限表/判定/断言）；SlotStack 渲染前过滤缺权限插槽改诊断条；editor-shell manifest 补 timeline.command/export.run；测试 10 用例含 editor-shell 真实回归 * feat(editor): M6.1 AI 命令 schema + M6.2 时间线摘要 - ai-command-schema（parse/dry-run 校验/12-op 提示词契约/版本化+golden）；timeline-summary（确定性中文摘要/折叠上限）；各 20/10 用例全绿 * docs(progress): M6 质检清单 - M6.1 schema/M6.2 摘要标记完成（含测试计数），M6.3 待模型源确认；清理 M5.1 重复条目 * feat(editor): AI 命令 schema 支持只读问答 - commands 空数组合法化（无法执行/纯提问时 reasoning 直接作答），新增 AI_EDITING_MAX_COMMANDS=8 上限防失控编辑，提示词同步 * feat(editor): AI 助手重构为右上悬浮对话面板（M6.3）+ 素材入库原子化收尾 - editor-ai-assistant.tsx: 占位面板替换为 OpenAI Canvas 风格右上悬浮对话面板； 面板内文本模型选择器（effective.textModels，选择即持久化并覆写请求模型）， 消息流 user/assistant/error/preview 四类气泡 + 思考中占位，空态引导示例 chips 一键发送，底部输入条；顶部工具栏常驻 Sparkles 入口（aria-pressed 切换）。 修复上一版重复/截断函数声明（appendToEntry 双定义、settleAnswer 三声明等）。 宿主链路：buildAiEditingSystemPrompt(summarizeTimeline(project)) 喂上下文 → parseAiCommandPlan → validateAiCommandBatch dry-run（任一非法整批拒绝）→ ≤3 条 dispatch 直执行 / >3 条预览确认卡片；宿主拒绝时 failTurn 回填 FAILED_MARK 可重试。 - editor-asset-ingest/editor-preview-monitor/detail/editor.tsx: 配套接线与打磨 （编辑器顶栏 AI 入口、素材导入面板、预览监视、项目页顶栏整理）。 - backend: LinkProjectAsset 事务内原子创建资产 + 项目链接（OnConflict 幂等）， 资产首次入库不再预落库，失败整体回滚，消除"有资产无链接"孤儿记录。 - docs: pending-test.mdx / runbook M6.3 状态更新（tsc + 测试 + 构建通过， 浏览器冒烟待真实文本渠道）。
This commit is contained in:
爱笑的毛毛虫
34
docs/adr/0001-editor-integration-boundary.md
Normal file
34
docs/adr/0001-editor-integration-boundary.md
Normal file
@@ -0,0 +1,34 @@
|
||||
# ADR-0001: 编辑器整合以 TS 时间线状态机为真相源，不移植 Concat 的 Rust 引擎
|
||||
|
||||
状态：已接受。日期：2026-09-01。来源：借鉴 Concat（WolfCut）编辑器能力整合决策。
|
||||
|
||||
> 更新记录（2026-09-01）：采纳 ADR-0005 后，编辑器 UI 与能力出口改为预设插件贡献（详见 ADR-0005）；本 ADR 聚焦的边界因此收窄为：核心状态机仍是宿主 TS 库，但不再是编辑器的一切。
|
||||
|
||||
## 背景
|
||||
|
||||
Concat（WolfCut）的核心架构原则是"引擎拥有项目模型"（engine doctrine）：Rust 引擎持有时间线模型、全部编辑命令（`commands.rs`）、撤销栈、渲染与导出路径、文档格式（wolfcut.json）；Tauri host 只是管道，UI 只渲染状态并派发命令。这一形态依赖本地文件系统、ffmpeg 子进程和 GPU 组合器，与其桌面产品定位绑定。
|
||||
|
||||
影策是 Web 应用（React 19 + Go 后端 + Node canvas-agent），画布节点模型以 TS 状态机为真相源（localforage user-scope + 后端项目接口持久化）。时间线已有第一期字幕数据落地与第二期类型（`TimelineProject` v2，含轨道/片段/directMedia），第三期规划了 ffmpeg 导出（`timeline-to-ffmpeg.ts` 纯函数规划层已存在）。后端 Go 目前不执行 ffmpeg。
|
||||
|
||||
## 决策
|
||||
|
||||
借鉴 Concat 的架构**形态**，不移植其**实现**：把"引擎拥有模型"翻译为"TS 时间线状态机拥有编辑真相"。
|
||||
|
||||
- 时间线编辑逻辑集中在 `web/src/lib/timeline/`（在现有 build/placement/snap/to-ffmpeg 基础上新增 editor 状态机），UI 组件只渲染状态并派发命令，不直接改写模型。
|
||||
- 编辑器**UI 与能力出口全部为预设插件贡献**（时间线面板、预览、检查器、转写、导出、字幕工具），核心状态机是插件依赖的宿主协议而非编辑器的一切（见 ADR-0005）。
|
||||
- 不移植 wolfcut crates、不引入 WASM 版引擎、不引入 Tauri/Electron 壳。
|
||||
- 媒体重活（转码、导出合成、转写）交给 Go 后端任务队列，浏览器 ffmpeg.wasm 保留为降级路径，两者由同一份滤镜图计划驱动（见 ADR-0003）。
|
||||
|
||||
## 考虑过的方案
|
||||
|
||||
- **移植/包装 Rust 引擎（wasm32 / 子进程）**：引擎与画布节点模型、localforage 缓存、浏览器预览路径同构成本高，会产生"引擎真相 + 画布真相"双真相源；否决。
|
||||
- **引入现成 Web 视频编辑器库（Remotion/Editly 等）**：Remotion 是 React 声明式渲染框架而非交互式多轨编辑器，现成编辑器与画布→时间线的 AI 工作流（节点资产入轨、字幕一期能力）耦合成本高于自建；否决。
|
||||
- **TS 端自建状态机（选定）**：与现有 `timeline.ts` v2、`timeline-build`/`timeline-placement` 等纯函数层一脉相承，可直接复用字幕与导出规划能力。
|
||||
|
||||
## 后果
|
||||
|
||||
- 撤销、自动保存、命令协议由 TS 端承担，责任随 Concat 的引擎移动到了前端库层；需要用类型与测试约束（见 ADR-0002）。
|
||||
- 不复制 Concat 的 chains mirror 债务（TS 手写镜像 Rust 滤镜串）：滤镜参数只允许单一来源（见 ADR-0003）。
|
||||
- ffmpeg 执行位置（浏览器 wasm / 后端任务）保持可切换，切换不改变编辑模型与导出参数。
|
||||
- 编辑器面板（时间线/预览/右侧检查器）复用 `docs/design/workspace-shell-design.mdx` 的设计 token 与三段式布局，不引入新设计体系。
|
||||
- 新增编辑器能力由预设插件承担（ADR-0005）：核心库冻结，只演进命令协议、滤镜图计划与任务协议。
|
||||
28
docs/adr/0002-edit-command-protocol.md
Normal file
28
docs/adr/0002-edit-command-protocol.md
Normal file
@@ -0,0 +1,28 @@
|
||||
# ADR-0002: 时间线编辑采用可序列化命令 + 有界快照撤销
|
||||
|
||||
状态：已接受。日期：2026-09-01。来源：借鉴 Concat 编辑循环与撤销/自动保存设计。
|
||||
|
||||
> 更新记录（2026-09-01）：采纳 ADR-0005 后，命令 handler 可经插件注册（时间线工具/效果插件贡献自定义 op），但命令队列、echo、撤销与保存仍是宿主核心；插件不得绕过命令协议改模型。
|
||||
|
||||
## 背景
|
||||
|
||||
Concat 的编辑循环：UI 把命令推入单队列 → 引擎 `editor.apply(command)` 返回全量视图 → UI 重渲染。拖拽用本地 echo 预演位置，手势结束才提交**一个**命令，撤销粒度是手势而非像素；撤销栈是有界完整克隆（200 层）；自动保存 1.5 秒防抖 + 临时文件原子改名。Concat 自述的教训：撤销/重做失败被吞错（§6.4）、重做栈无上限（§6.3）。
|
||||
|
||||
影策现有画布数据走 localforage（user-scope）+ 后端项目接口；时间线一期已落地字幕数据，二期按 `TimelineProject` v2 持久化轨道/片段。
|
||||
|
||||
## 决策
|
||||
|
||||
- 时间线唯一修改入口是**可序列化编辑命令** `{ op, payload }`，经单队列顺序应用到 TS 状态机，每次 apply 返回新的 `TimelineProject` 作为唯一真相；任何 UI 代码不得直接改写模型。
|
||||
- **命令 handler 可插件化注册**：预设插件（时间线工具、效果、字幕工具）通过宿主 API 贡献自定义 op 及其 reducer/handler；宿主负责校验权限（ADR-0005）后入队执行，插件不持有队列与撤销栈。
|
||||
- 拖拽/裁剪/变速等手势采用 **echo**：本地预演位置与效果，`release`/手势结束提交一个命令。
|
||||
- 撤销栈为**有界完整快照**（上限 200 层，与 Concat 一致），重做栈同样限界。
|
||||
- 保存沿用项目保存链路：localforage user-scope + 后端项目接口，防抖 1.5 秒，写失败必须上报，不吞错、不静默降级。
|
||||
- 编辑命令对象序列化形式即对外协议：画布 Agent、未来多端协作通过命令日志同步，不经由此协议不得改动时间线。
|
||||
|
||||
## 后果
|
||||
|
||||
- 快照撤销简单可靠，但内存随项目规模线性增长：快照只存结构化模型，媒体大对象一律以 `directMedia` 引用/存储 key 入快照，不复制二进制。
|
||||
- 命令队列天然支持幂等重放，为服务端协同与测试（命令黄金文件）留出路径。
|
||||
- 撤销粒度是手势：移动/裁剪一整段是一次撤销，不提供逐帧回退。
|
||||
- 与 Concat 不同，命令执行、撤销、自动保存都发生在浏览器进程，无跨进程边界；同步失败的兜底是本地缓存 + 明确的状态标识，不能冒充服务端已保存（遵循 AGENTS.md 写路径约定）。
|
||||
- 插件贡献的命令 handler 必须保持纯函数、可序列化、可重放：撤销快照与命令黄金文件对插件命令同样生效，插件不能依赖组件实例状态。
|
||||
27
docs/adr/0003-preview-export-layering.md
Normal file
27
docs/adr/0003-preview-export-layering.md
Normal file
@@ -0,0 +1,27 @@
|
||||
# ADR-0003: 预览与导出分层——交互近似预览 + 单一滤镜图计划
|
||||
|
||||
状态：已接受。日期：2026-09-01。来源：借鉴 Concat 预览近似与导出降级设计。
|
||||
|
||||
> 更新记录（2026-09-01）：采纳 ADR-0005 后，预览渲染器与导出渲染器成为插件贡献点（`registerPreviewRenderer` / `registerExportRenderer`）；单一滤镜图计划约束不变，对插件同样强制。
|
||||
|
||||
## 背景
|
||||
|
||||
Concat 的预览近似层：交互期间用 CSS 滤镜 / canvas 运算渲染近似效果，监视器播放引擎真帧；其原则是"导出只是你已看到内容的更高画质版本"。转场在导出器降级（交叉淡化 → 重叠片段 + 透明度斜坡）。Concat 自述的最大债务是 chains mirror（§6.1）：TS 手写镜像 Rust 滤镜链，两侧靠钉死测试维持一致，新增效果成本翻倍。
|
||||
|
||||
影策已有 `timeline-to-ffmpeg.ts` 纯函数规划层（trim → gap → concat → subtitle → burn），`timeline-export.ts` 用浏览器 ffmpeg.wasm 执行；后端 Go 暂无 ffmpeg。
|
||||
|
||||
## 决策
|
||||
|
||||
- **交互预览只做浏览器原生近似**：`<video>` 裁剪/缩放/透明度/音量、CSS 滤镜、canvas 合成近似。近似预览是交互真相，但不是导出像素；UI 上不把两者混为一谈。
|
||||
- **预览渲染器与导出渲染器为插件贡献点**：预设插件（如转场/滤镜效果插件）通过 `registerPreviewRenderer` / `registerExportRenderer` 贡献渲染实现；宿主按插槽渲染，插件不得绕过插槽直接挂载 DOM。
|
||||
- **单一滤镜图计划对插件强制生效**：插件贡献的导出渲染必须消费 `buildTimelineRenderPlan` 的输出参数，禁止插件内部自行拼第二套滤镜串（无论多简单）。
|
||||
- **导出滤镜图只由 `buildTimelineRenderPlan` 单一模块生成**：这是滤镜串的唯一来源。主路径为 Go 后端 ffmpeg 任务（复用任务队列），浏览器 ffmpeg.wasm 为降级路径，二者吃同一份计划。
|
||||
- **新增效果必须同时产出两份描述，且出自同一参数模型**：`预览近似描述`（CSS/canvas 等价实现）与 `导出滤镜参数`（ffmpeg filtergraph 片段）。禁止在 UI 组件里手写第二套滤镜串——即不复制 Concat 的 chains mirror 债务。
|
||||
- 转场、滤镜等视觉允许预览与导出存在级差（如预览用近似淡化、导出用 xfade/淡入淡出），但参数必须同源，不允许出现"预览一套、导出另一套"的漂移。
|
||||
|
||||
## 后果
|
||||
|
||||
- 滤镜参数模型成为编辑器和导出共用的契约：新增效果 = 参数模型 + 两份降级实现，测试围绕参数模型做黄金文件。
|
||||
- 预览与导出管线各自可演进：服务端派生"预览近似描述"（Concat 式 engine emits preview looks）时，无需改 UI 消费方式。
|
||||
- 浏览器 wasm 与后端 ffmpeg 的切换不改变编辑模型；wasm 仅承担无后端场景下的降级导出。
|
||||
- 渲染器插件化后，新增效果仍是「参数模型 + 预览近似 + 导出滤镜」三件套，只是后两者的实现方变为插件；参数模型仍是黄金文件测试的唯一锚点，防止插件间出现参数漂移。
|
||||
27
docs/adr/0004-autocaption-transcription-service.md
Normal file
27
docs/adr/0004-autocaption-transcription-service.md
Normal file
@@ -0,0 +1,27 @@
|
||||
# ADR-0004: 自动字幕转写作为后端服务任务
|
||||
|
||||
状态：已接受。日期：2026-09-01。来源：借鉴 Concat 转写命令集与模型管理设计。
|
||||
|
||||
> 更新记录（2026-09-01）：采纳 ADR-0005 后，转写提供者为插件贡献点（`registerTranscriptionProvider`），转写面板为预设插件；后端任务与配额协议不变。
|
||||
|
||||
## 背景
|
||||
|
||||
Concat 的招牌智能功能之一是自动字幕：以 7 个转写命令（转写片段、取消、状态等）驱动本地 whisper 模型，模型文件按需下载并管理。其前提是桌面应用可在本地跑模型与 ffmpeg。
|
||||
|
||||
影策是服务端应用：模型渠道统一经后端中转（`custom-channel-relay` 的 `/api/ai/custom`），任务走任务队列与配额体系；素材已服务端化；时间线一期已有字幕数据与 SRT 解析/切分能力（`srt-parser`、`srt-resegment`），字幕轨道已是 `TimelineProject` v2 的一等轨道类型。
|
||||
|
||||
## 决策
|
||||
|
||||
- 转写由 **Go 后端执行**（whisper.cpp 或服务化 ASR 作为后端任务），前端只提交"素材/片段 → 转写字幕"任务并展示进度，不直接调用模型。
|
||||
- **转写提供者为插件贡献点**：预设插件经 `registerTranscriptionProvider` 声明前端可用的转写能力与 UI（如自动字幕面板、字幕工具），经宿主校验权限后调用后端任务；第三方插件可扩展新转写来源，但必须走同一任务协议。
|
||||
- 转写结果以 SRT 形式写回时间线字幕轨道，复用一期 SRT 解析与按句/按词切分能力；前端可预览、编辑、重新转写。
|
||||
- **不在浏览器运行 whisper**：模型体积、算力与移动端/低端设备不可控，且与既有"模型渠道走后端中转"的安全边界一致。
|
||||
- 转写任务复用任务队列与配额体系；ASR 引擎可插拔（本地进程 / 云 ASR），后端服务内部切换，前端协议不变。
|
||||
- TTS/配音等**生成式**语音能力走既有模型渠道（生成素材），与转写（分析已有素材）互不耦合，不在本决策范围内。
|
||||
|
||||
## 后果
|
||||
|
||||
- 转写是异步任务而非即时命令：前端需要任务状态展示（进行中/成功/失败），失败可重试，重试不重复扣配额。
|
||||
- 字幕轨道成为时间线一等公民：转写、人工编辑、导出烧录（ADR-0003 的 burn 步骤）共享同一字幕数据源。
|
||||
- 模型权重与算力要求后端可插拔部署：本地 whisper.cpp 省成本、云 ASR 省运维，两者共用同一个任务协议。
|
||||
- 前端转写能力集合随插件而变：默认预设提供 whisper 服务转写；第三方插件可增加转写来源，前端任务协议与字幕轨道数据形状保持稳定。
|
||||
40
docs/adr/0005-editor-preset-plugin-architecture.md
Normal file
40
docs/adr/0005-editor-preset-plugin-architecture.md
Normal file
@@ -0,0 +1,40 @@
|
||||
# ADR-0005: 编辑器预设插件架构——参考 astravia「万物皆可插件」改造
|
||||
|
||||
状态：已接受。日期：2026-09-01。来源：参考 astravia（`astravia`）插件体系理念，改造编辑器插件化。
|
||||
|
||||
## 背景
|
||||
|
||||
**astravia 的「万物皆可插件」理念**：所有能力（含界面）都是插件贡献，宿主核心只保留最小骨架。其实现要点：
|
||||
|
||||
- **统一插件形态**：`definePlugin` SDK + `plugin.json` 清单 + Module Federation 打包（`vettaPluginFederation`）；react/react-dom/SDK/主题 token 由宿主作为共享单例 external 化，插件不自带运行时。
|
||||
- **系统插件（presets）与用户插件同构**：内置功能与第三方插件用**同一套 SDK 与清单**，仅分发方式（随 App 发布 vs zip 安装）与权限语义（系统插件自动全量授予且不可删改 vs 用户插件安装时逐项授予）不同。
|
||||
- **UI 插槽**：workspace view、global slot、file preview、activity tab、input action、tool call slot、shortcut scope 等均为注册式插槽，内置界面与插件界面平等占位。
|
||||
- **权限执行**：清单声明 + 宿主在 API 调用点校验（fail-closed / warn+noop / 抛错三档），未声明即不可见不可用。
|
||||
- **能力贡献**：capability-runtime（hub/provider/registry/access）+ capability-sdk，插件以 provider 身份注册能力。
|
||||
|
||||
**影策现状（改造对象）**：现有 `yingce.plugin/v1`（`web/src/lib/plugins/`）只有**画布域**贡献（provider / workflow / canvas-node / transform / asset-source 等），存在结构性缺口：无 UI 插槽注册 API（surfaces 只是声明字段）、无编辑器任何贡献类型（时间线/预览/导出/转写没有插件入口）、无预设（系统）插件分发语义、内置插件是 `builtin/` 源码硬编码 import、权限只有清单字符串无宿主执行校验。对"编辑器插件化"这一目标不可直接支撑（即现状"不可理"之处）。
|
||||
|
||||
## 决策
|
||||
|
||||
- **编辑器全部 UI 与能力以插件贡献形态存在**，作为**预设插件（preset plugins）**随产品发布：时间线面板、预览监视器、右侧检查器、素材入轨、自动字幕（转写）面板、导出面板、字幕工具均为预设插件；默认启用、用户可停用、不可卸载删改，权限自动授予。
|
||||
- **现有插件体系演进为 v2 形态（`yingce.plugin/v2`），补齐 astravia 式机制，editor 域作为首个完整消费方**：
|
||||
- 新增**UI 插槽注册 API**：`registerTimelinePanel` / `registerPreviewRenderer` / `registerExportRenderer` / `registerTranscriptionProvider` / `registerSubtitleTool` / `registerShortcutScope` 等；宿主按插槽渲染注册表，内置与第三方插件平等占位。
|
||||
- 新增**预设插件分发语义**：preset 插件随应用代码分发（沿用 `builtin/` 目录、语义化为 `builtin/editor/` 预设），与用户插件同清单同 SDK，仅权限/可删改性不同。
|
||||
- 新增**权限执行校验**：编辑命令、转写任务、导出任务、资源读取等宿主 API 调用点按清单校验，fail-closed；未声明不得触发。
|
||||
- 保持共享单例：react / react-dom / 时间线 SDK / 设计 token（`workspace-shell-design.mdx`）由宿主提供，插件不自带。
|
||||
- **宿主最小核心保持不变**：时间线状态机（ADR-0001）、编辑命令队列与撤销（ADR-0002）、滤镜图计划（ADR-0003）、任务与配额协议（ADR-0004）是核心骨架，插件只允许在这些协议之上贡献 UI 与 handler，不得绕过命令协议改模型。
|
||||
- 编辑器内置功能**不做特殊化**：迁入预设插件后与第三方插件走同一条贡献/校验/插槽路径，禁止在核心代码里写"编辑器专属硬编码分支"。
|
||||
|
||||
## 考虑过的方案
|
||||
|
||||
- **推倒重写插件体系**：现有 v1 已融入画布/生成/素材链路（application.tsx 静态注册 builtin、use-plugin-store 持久化启用态、后端 pluginStates），重写会破坏既有功能且无必要；否决，选择在同一代码库演进。
|
||||
- **编辑器独立自建面板，不做插件化**：违背"插件化做成预设插件"的产品方向，且重复造轮子；否决。
|
||||
- **照搬 astravia 包结构（SDK 独立包 + 独立市场）**：影策是单体 web 仓库，先以 v2 形态在 `web/src/lib/plugins/` 内演进，待出现真正的外部插件需求再抽 SDK/打包工具链；当前阶段预设插件足够。
|
||||
|
||||
## 后果
|
||||
|
||||
- 编辑器成为插件体系第一个完整闭环域：新增编辑器能力 = 写一个预设插件（清单 + 插槽贡献 + handler），不改宿主核心；宿主核心因插件而冻结，只演进协议。
|
||||
- `yingce.plugin/v1` 升级为 v2：v1 字段（贡献类型/权限声明）保留兼容，新增插槽与分发字段；旧画布插件无需迁移即可继续运行，新增字段可选。
|
||||
- 权限校验从"声明"变为"执行"：编辑器宿主 API 是第一个强制校验点，随后推广到画布/生成链路。
|
||||
- 与 astravia 的差距被显式承认：暂无外部插件安装/市场/沙箱，预设插件是当前全部范围；待需要时按 astravia 的 SDK/打包/租户选择机制补齐。
|
||||
- 插件数量与耦合风险：editor 预设插件按功能域拆分（面板/预览/导出/转写/字幕工具各一个），共享同一命令协议与滤镜图计划，避免插件间互相 import。
|
||||
53
docs/adr/0006-voice-filters-and-templates.md
Normal file
53
docs/adr/0006-voice-filters-and-templates.md
Normal file
@@ -0,0 +1,53 @@
|
||||
# ADR-0006: 语音滤镜与项目模板——Concat 剩余缺口的补充决策
|
||||
|
||||
状态：已接受。日期：2026-09-01。来源：Concat 编辑器功能覆盖对照中的两个明确缺口，评估后决定引入。
|
||||
|
||||
## 背景
|
||||
|
||||
功能覆盖对照（实现规格 §0.4）识别出 Concat 有两个影策方案未覆盖的功能：
|
||||
|
||||
- **语音滤镜（Voice Filters）**：Concat 的招牌特色之一，对音频/人声做本地 DSP 处理（降噪、变声、均衡、回声等）。其前提是桌面应用可本地执行音频处理。
|
||||
- **模板（Templates）**：Concat 提供保存项目为模板（`SaveTemplateDialog`）、模板缩略图（`TemplateThumb`）与从模板新建的流程；模板中心仍在 roadmap。
|
||||
|
||||
影策（Web + Go 服务端）此前将两者列为"明确不做"。本 ADR 评估引入方式，结论：**两者都引入，且必须走预设插件形态（ADR-0005），服从单一滤镜图计划约束（ADR-0003）**。
|
||||
|
||||
## 决策
|
||||
|
||||
### 语音滤镜：预设插件 `editor-audio-effects`
|
||||
|
||||
- 新增 `audio-effects` 贡献类型与 `audio.process` 权限；插件注册音频效果（音量、淡入淡出、均衡、回声、降噪、变速变调）。
|
||||
- **预览近似走 Web Audio API**：`BiquadFilter` / `DynamicsCompressor` / `DelayNode` / `ConvolverNode` 等实时处理，交互真相，非导出像素。
|
||||
- **导出真相走 ffmpeg 音频滤镜**：`afftdn`（降噪）/ `equalizer` / `aecho` / `acompressor` / `asetrate`+`aresample`（变速变调）等，作为 `buildTimelineRenderPlan` 的 **audio steps** 纳入单一滤镜图计划。
|
||||
- **参数模型先行**：与视频滤镜同构——同一参数模型 + 预览/导出两份实现；渲染计划黄金文件（§7.2）增加音频夹具，禁止插件手写第二套滤镜串。
|
||||
- 首版只做基础集（音量、淡入淡出、均衡、回声、简单降噪）；变声等复杂 DSP 留作插件扩展点。
|
||||
|
||||
### 模板：预设插件 `editor-template`
|
||||
|
||||
- 新增 `template-provider` 贡献类型与 `template.read` / `template.write` 权限。
|
||||
- **模板 = 项目快照**：章节 + 画布 + 时间线（`TimelineProject`）+ 资产引用清单，**不含媒体二进制**；带 `templateSchemaVersion` 版本字段，随项目模型演进。
|
||||
- "存为模板"从当前项目生成快照；"从模板新建"克隆快照为新项目（复用项目创建链路）。
|
||||
- 模板存储为**服务端模板表**（归属用户/组织），支持列表 + 缩略图（复用 Concat `TemplateThumb` 概念）。
|
||||
- **模板中心/市场不实现**：保留扩展点，待组织级模板需求出现时再评估（需组织/审核/订阅体系，超出当前范围）。
|
||||
|
||||
### 共同约束
|
||||
|
||||
- 两者都是预设插件：随应用分发、默认启用、不可卸载，权限自动授予（ADR-0005）。
|
||||
- 权限执行校验（实施规格 M5 的 fail-closed）覆盖新增的 `audio.process` / `template.read` / `template.write`。
|
||||
- 新增效果一律遵守"单一参数模型 + 预览近似 + 导出真相"三件套，音频不例外。
|
||||
|
||||
## 考虑过的方案
|
||||
|
||||
- **语音滤镜用浏览器 WASM DSP（RNBO/声码器级）**：实时性强、效果上限高，但包体大、实现复杂、与导出滤镜难同源；首版否决，保留为复杂 DSP 插件的未来选项。
|
||||
- **语音滤镜直接用后端 ffmpeg 滤镜做预览**：网络延迟不可接受，违背"预览近似必须浏览器原生"（ADR-0003）；否决。
|
||||
- **语音滤镜保持缺口（不做）**：Concat 对标的核心卖点之一，且音频效果是实现规格中成本最低的插件化增量；否决。
|
||||
- **模板 = 复制整个项目含媒体二进制**：两份存储浪费、快照膨胀；否决，快照只存引用清单。
|
||||
- **模板纯前端 localStorage**：不可跨设备/账号，与项目服务端持久化体系冲突；否决。
|
||||
- **模板保持缺口（不做）**："从模板新建"是成片效率工具，直接衔接概览「剪辑成片」流程（§0.2）；否决。
|
||||
|
||||
## 后果
|
||||
|
||||
- `buildTimelineRenderPlan` 从纯视频计划扩展为 **A/V 计划**（video steps + audio steps）；ADR-0003 的"单一来源"约束覆盖音频，滤镜图计划的黄金文件增加音频夹具。
|
||||
- 新增权限 `audio.process` / `template.read` / `template.write`，权限执行校验清单（M5）同步扩展。
|
||||
- 模板快照与项目模型强耦合：`templateSchemaVersion` 必须随 `TimelineProject` / 画布模型演进，快照兼容测试纳入验证纪律。
|
||||
- **优先级建议**：模板先于语音滤镜——模板依赖 M2 数据模型与项目创建链路即可落地（M3 后增量窗口），语音滤镜依赖 M3 预览渲染 + M4 导出管线的音频扩展（M4 后增量窗口）。两者均不阻塞 7 个核心预设插件的主线。
|
||||
- 实现规格 §6 文件规划需追加：`builtin/editor/editor-audio-effects.ts`、`builtin/editor/editor-template.ts`、后端模板表迁移与 `template` handler、`timeline-to-ffmpeg.ts` 音频 steps 扩展。
|
||||
55
docs/adr/0007-ai-editing-interaction.md
Normal file
55
docs/adr/0007-ai-editing-interaction.md
Normal file
@@ -0,0 +1,55 @@
|
||||
# ADR-0007: AI 编辑交互——对话式剪辑作为预设插件
|
||||
|
||||
状态：已接受。日期：2026-09-01。来源：编辑器与 AI 交互能力整合决策；建立在 ADR-0002（命令协议）与 ADR-0005（预设插件）之上。
|
||||
|
||||
## 背景
|
||||
|
||||
编辑器需要与 AI 交互：用户用自然语言表达剪辑意图，AI 直接驱动时间线。Concat 没有对话式 AI 编辑（桌面引擎，AI 只能模拟 UI 操作，脆弱且不可测试）；影策因两个既有决策天然支持：
|
||||
|
||||
- **命令协议（ADR-0002）**：时间线唯一修改入口是 `{op, payload}` 序列化命令，单队列 apply、可撤销、可重放——AI 只需输出命令 JSON 即可驱动时间线，与人手势编辑完全同构。
|
||||
- **插件化（ADR-0005）**：AI 交互能力可作为预设插件注册（对话面板插槽 + 权限），不动核心。
|
||||
- **既有资产**：模型渠道已统一中转（`custom-channel-relay.ts` / `/api/ai/custom`）；画布侧已有成熟的 AI 聊天 UI（`canvas-agent-chat-ui.tsx`、`canvas-assistant-panel.tsx`、`canvas-prompt-optimizer-drawer.tsx`）；AI 字幕高亮纯函数层已存在（`subtitle-highlight-*`）。
|
||||
|
||||
## 决策
|
||||
|
||||
### AI 编辑交互 = 预设插件 `editor-ai-assistant`
|
||||
|
||||
- 新增 `ai-assistant` 贡献类型与 `ai.text` / `timeline.command` / `timeline.read` 权限；插件注册对话面板插槽（right 或弹层）。
|
||||
- **对话面板复用画布 agent 聊天 UI 的交互模式**（流式输出、上下文面板、可停止），复用现有组件或同构实现，不复制不移植画布会话协议；编辑器上下文（时间线摘要）由本插件构造。
|
||||
- AI 是时间线的**一等公民编辑者**：AI 命令与手势命令同构、同队列、同撤销栈。
|
||||
|
||||
### AI 命令协议（受约束命令 JSON）
|
||||
|
||||
- LLM 输出**受约束的命令序列 JSON**：`{ commands: [{ op, payload }], reasoning?: string }`，`op` 必须来自命令白名单（`editor-commands.ts` 注册的 ops），`payload` 按 per-op schema 校验（新增 `ai-command-schema.ts`，与命令 handler 同源维护）。
|
||||
- **宿主 fail-closed**：任一命令 schema 校验失败、op 未知、权限未声明，整批拒绝并返回错误给对话（不执行部分命令）；失败信息回填对话供 AI 自纠。
|
||||
- 命令 schema 版本化（`aiCommandSchemaVersion`）：模型演进或命令集变更时显式升级，避免 AI 输出与新命令集失配。
|
||||
|
||||
### 执行语义：默认直接执行 + 一键撤销，批量改动需确认
|
||||
|
||||
- **单条/少量命令（≤3 条）**：解析校验通过后直接入队执行，撤销即回退（符合剪辑工具直觉，与手势编辑一致）。
|
||||
- **批量改动（>3 条或涉及删除/整体重排）**：先展示命令 diff 预览（将改哪些片段/轨道），用户点「应用」才入队。
|
||||
- 所有 AI 命令与手势命令共享同一撤销栈，AI 误操作可逐批撤销，不留特殊回退路径。
|
||||
|
||||
### AI 只读能力
|
||||
|
||||
- 对话可读时间线状态（`timeline.read`）做分析问答（"这段节奏怎么样"、"哪里该剪"）；只读回答不需要 `timeline.command`。
|
||||
- 时间线摘要为**结构化精简版**（轨道/片段/时长/关键属性，不含媒体二进制），作为 AI 上下文输入；大对象不进 prompt。
|
||||
|
||||
### 素材层 AI 不重复决策
|
||||
|
||||
- 自动转写（ADR-0004）、AI 字幕高亮（既有能力接入）、AI 生成素材入轨（既有生成链路 + asset-ingest）不属于本 ADR 的对话式编辑范围；`editor-ai-assistant` 可聚合它们的入口，但各自能力边界与协议不变。
|
||||
|
||||
## 考虑过的方案
|
||||
|
||||
- **AI 直接操作 DOM/UI（模拟点击拖拽）**：脆弱、不可测试、与命令协议割裂；否决。
|
||||
- **AI 走后端执行编辑**：网络往返破坏交互延迟，撤销/错误回填难做，且后端无时间线真相源；否决。
|
||||
- **AI 生成完整时间线整体替换**：高风险（覆盖用户已有编辑），无 diff 预览；否决，只允许命令增量。
|
||||
- **AI 命令立即全量执行不确认**：批量误操作无法挽回；否决，采用上述批量确认语义。
|
||||
|
||||
## 后果
|
||||
|
||||
- 命令 schema 成为 AI 与宿主的**双契约**：同一 schema 同时服务命令校验（宿主）与 LLM 提示词约束（AI 端）；`ai-command-schema.ts` 与命令 handler 同源维护，黄金文件测试扩展到 AI 命令序列。
|
||||
- 编辑器获得 Concat 不具备的能力：**自然语言驱动的时间线编辑**，且与人编辑共享撤销/可测试/可重放语义。
|
||||
- 新增预设插件使首版插件数从 7+2 变为 7+3（editor-ai-assistant 加入）；插件清单与权限矩阵同步更新。
|
||||
- 上下文窗口与 token 成本受时间线摘要精简策略影响；摘要生成是纯函数（`timeline-summary.ts`），可测试。
|
||||
- 画布 agent 聊天 UI 与编辑器 AI 面板并存：两者共享模型渠道与交互模式，但不共享会话上下文（画布会话 ≠ 编辑器会话），避免会话串扰。
|
||||
@@ -5,6 +5,82 @@ description: 当前项目已实现功能的手工验证清单与未确认边界
|
||||
|
||||
# 待测试
|
||||
|
||||
## 编辑器（M2 命令状态机）
|
||||
|
||||
- [x] 命令协议黄金文件：`editor-commands` 8 个黄金 op（addClip/moveClip/trimClip/splitClip/removeClip/setClipProperty/addSubtitle/removeSubtitle）全量快照比对通过；未知 op、非法 payload 一律抛错（fail-closed）且输入不可变。
|
||||
- [x] 快照撤销：`editor-history` 有界 200 层，undo 后新命令清空 redo；边界测试（0 层/200 层/undo 后 redo 清空）通过。
|
||||
- [x] 命令状态机 store：`editor-store` 命令入队→reducer→新状态，手势预览（previewGesture 连续预览/commitGesture 一次性入历史/cancelGesture 丢弃），1.5s 防抖保存（保存层依赖注入），保存串行链防旧快照覆盖，失败置 saveError 且保持 dirty；11 项测试通过。
|
||||
- [ ] 浏览器冒烟（待用户确认）：项目详情 → 剪辑成片 → 编辑器，拖拽片段移动、拖拽边缘裁剪（trim-start/trim-end）、撤销/重做按钮与缩放按钮；松手提交后可一次撤销；刷新后本地时间线（localforage scope 隔离）保留；状态栏显示 未保存/保存中/已保存/保存失败。
|
||||
- [ ] M2.4 手势与画布拖拽不冲突（时间线容器 `data-canvas-no-zoom`），快捷键（Cmd/Ctrl+Z）与全局冲突项待 M3 统一处理。
|
||||
|
||||
## 编辑器（M3 预设插件八连）
|
||||
|
||||
- [x] 命令层新增 `rebuildSubtitleClips`（9 个黄金 op）：从节点权威 subtitleEntries 重建字幕快照，确定性 id（nodeId:subtitle:index）重复导入原地替换；非法 entries（index/startMs/endMs/text/重复 index）与非法轨道（非字幕轨/无字幕轨）fail-closed；黄金文件追加用例通过（26 项）。
|
||||
- [x] M3.1~M3.4：timeline-panel（选中联动 + 撤销/重做/缩放 UI）、preview-monitor（buildTimelineRenderPlan 预览）、inspector（setClipProperty 可撤销）、asset-ingest（addClip 入轨）插件与 editor.tsx 三段式接线已提交。
|
||||
- [x] M3.5 subtitle-tools：SRT 粘贴导入（parseSrt → rebuildSubtitleClips 重建快照）、当前时间线字幕导出 .srt（serializeSrtEntries 往返一致）；AI 高亮占位（M6 接入）。
|
||||
- [x] M3.6 transcription：确定性 mock 转写（mockTranscriptionEntries 同输入同输出，3 项测试），结果按 ADR-0004 协议重建到字幕轨道；M4 替换真实任务客户端。
|
||||
- [x] M3.7 export：渲染计划（buildTimelineRenderPlan 与画布同源）+ ffmpeg.wasm 降级导出（exportTimelineToMp4 带进度）；悬空 nodeId 源按计划跳过。
|
||||
- [x] M3.8：editor.tsx 全 8 槽三段式渲染（左素材/转写，中预览/时间线，右检查器/字幕/导出/AI）+ ai-assistant 占位（M6）；typecheck 零错误、专项 53/53、全量 build 通过。
|
||||
- [ ] 浏览器三段式冒烟（待用户确认）：编辑器六个区域（时间线/预览/检查器/素材库/字幕/转写/导出）逐区域可见可操作；拖拽/裁剪/撤销重做回归；SRT 导入导出往返；mock 转写落轨；导出面板显示渲染计划。
|
||||
|
||||
## M5（编辑器插件权限执行，fail-closed）
|
||||
|
||||
|
||||
- [x] M5.1：`plugin-permission-check.ts` 新建——8 插槽→最小权限表（timeline.read/timeline.command/export.run 三类域）+ `pluginMayRenderEditorSlot`/`assertEditorPermission` fail-closed 判定；测试 10 用例（表完整性/空权限拒绝/未注册拒绝/缺权限拒绝含 missing 域/editor-shell 真实回归 8 插槽可渲染）全绿。
|
||||
- [x] M5.2 执行路径接入：editor.tsx SlotStack 渲染前过滤——缺权限插槽不渲染、改显一行诊断条（含缺失域）；editor-shell manifest 权限补全为 timeline.read/timeline.command/export.run；tsc 全绿、全量 bun test 失败集与改动前一致（零新增回归）。边界：宿主全局命令（editor-commands，v1 语义）与宿主 UI 手势不经过此校验，仅 v2 插件插槽贡献与后续 M6 AI 命令代发通道受约束——ADR-0007「v1 权限语义一字不动」。
|
||||
- [ ] M5 浏览器验证（待用户确认）：停用/注册一个缺 timeline.command 权限的第三方插件时对应面板被拒渲染并显示诊断；editor-shell 全部 8 面板正常。
|
||||
|
||||
## M6（AI 编辑助手：schema + 摘要 + 面板）
|
||||
|
||||
- [x] M6.1：`ai-command-schema.ts` 新建——AI 命令 JSON 解析（容忍 markdown fence/前后杂讯/字符串内括号）、批级 dry-run 预检（走 M2 命令注册表，任一非法整批拒绝并报下标与 op）、12-op LLM 提示词契约（`AI_EDITING_OP_CATALOG` + `buildAiEditingSystemPrompt`）、`AI_COMMAND_SCHEMA_VERSION` 版本化；`ai-commands.golden.json` 固化 op 集与 registry 黄金同步（漂移即测试失败）；20 用例全绿。
|
||||
- [x] M6.2：`timeline-summary.ts` 新建——确定性中文摘要（轨道按 order 排序逐行、片段逐行含 id/kind/时间区间、字幕字数统计、空态提示）；片段行数超限折叠（SUMMARY_MAX_CLIP_LINES）；同输入同输出；10 用例全绿。
|
||||
- [x] M6.3：`editor-ai-assistant.tsx` 从占位替换为真实 AI 助手——右上悬浮对话面板（OpenAI Canvas 风格）：面板内文本模型选择器（`effective.textModels` 即文本能力模型目录，选择即 `updateConfig("textModel", …)` 持久化并在请求时同时覆写 `config.model/textModel`，绕过默认/误配图像模型的根因）、消息流（user/assistant/error/preview 四类气泡 + 思考中占位）、空态引导（示例意图文案，点击建议指令 chips 即发送，跨轮记忆）、底部输入条；顶部工具栏常驻 Sparkles 入口（aria-pressed 切换）。宿主链路：`buildAiEditingSystemPrompt(summarizeTimeline(project))` 喂上下文 → 流式增量渲染 → `parseAiCommandPlan` → `validateAiCommandBatch` dry-run（任一非法整批拒绝，同步 registry 校验、不落盘）→ ≤3 条 `dispatch` 直执行 / >3 条渲染 diff 预览卡片「确认执行（N）/ 放弃」→ 解析/校验拒绝时错误气泡可「修正后重试」（`failTurn` 回填 `FAILED_MARK`，历史含用户文本不重发；registry 直执行本身 fail-closed——拒绝写入 `saveError` 顶部提示，同步 dispatch 不抛错故不回填 FAILED_MARK）。修复了上一版文件的重复/截断函数（appendToEntry 双定义、settleAnswer 三声明等）；typecheck 零错误、编辑器/插件相关测试通过、生产构建通过。
|
||||
- [ ] 浏览器冒烟（待用户确认，需真实文本渠道）：顶部工具栏 AI 图标开关面板 → 切换面板内模型下拉（无可用模型时展示禁用态）→ 输入自然语言；确认 ≤3 条指令直接执行且可撤销（撤销按条回退，N 条需 N 次撤销）、>3 条出现预览确认卡片（放弃不动时间线、确认后预览卡转为执行汇报、重复点击不再二次提交）、模型输出非法 JSON 时错误气泡出现「修正后重试」并回填失败标记、ESC/关闭按钮收起面板后再次打开会话仍在。
|
||||
|
||||
## M4（后端转写/渲染任务）
|
||||
|
||||
- [x] M4.1 执行侧（e9d1b8ad）：本地 whisper.cpp HTTP（`CANVAS_WHISPER_BASE_URL`）转写；语音数据不出本机；未配置时任务明确失败并提示设置；`processClaimedTask` 顶部按类型分叉、旁路计费/模型路由，20 分钟超时；ffmpeg 预处理 16k 单声道 wav；`verbose_json` 解码/`formatSRTTimestamp`/`buildTimelineSRT` 单测 PASS。
|
||||
- [x] M4.1 创建 API（bf26ebb1）：`POST /api/timeline/transcriptions`（注册于 `RegisterTaskRoutes`）→ `CreateTimelineTranscriptionTask`：draining 503 → feature 门控 → 资源归属/可转写类型校验 → 配额入队（local/whisper.cpp，无 billing order）；活跃任务上限 → 可读 400；测试 3 项 PASS。
|
||||
- [x] M4.2 渲染任务（3f16d13b）：`POST /api/timeline/renders` → `CreateTimelineRenderTask`：`buildRenderPlan` 校验 ≥1 可渲染媒体 → 配额入队（local/ffmpeg）；worker 分叉 `processTimelineRender`（60 分钟超时）：ffmpeg 合成 → 产物写资源存储 → `ResultJSON{resourceId,...}`；计划/失败快路径测试 PASS。
|
||||
- [x] M4.3 前端字幕回写（fd5e8139）：`timeline-tasks.ts` 客户端 + `editor-transcription.tsx` 真实任务替换 mock；资源范围放宽到音视频；`resourceId` 由 `storageKey` 推导；`waitForGenerationTask` 显式 25 分钟超时轮询；结果 segments → SrtEntry → `rebuildSubtitleClips` 落字幕轨；typecheck 通过。
|
||||
- [ ] 浏览器端到端（待用户确认，需本机 whisper.cpp server）：媒体面板选音视频素材 → 转写 → 进度可见 → 完成后字幕分段入轨可编辑；错误路径（未配置/删除素材/非音视频/活跃任务上限/功能未开放）提示可读。
|
||||
- [x] M4.2 渲染前端接线：`timeline-tasks.ts` 增 `createTimelineRenderTask`（timeline 整传 TimelineProject v2，与后端 renderProject 契约同构）；`editor-export.tsx` 主路径改提交 `POST /api/timeline/renders` → `waitForGenerationTask` 轮询（62min）→ ResultJSON.resourceId 内嵌预览/下载；ffmpeg.wasm 降级保留；tsc 全绿、无新增测试失败。
|
||||
- [ ] M4.2 渲染浏览器验证（待用户确认，需 ffmpeg 可用）：导出面板「渲染成片（服务端）」→ 轮询进度 → 完成后内嵌预览/下载渲染产物；无后端时「本地导出」ffmpeg.wasm 仍可用。
|
||||
- [ ] 文档回写（已提交）：`docs/plans/m4-transcription-render-design.md` §2 决策 3/4/5 按“单一池 + 类型分叉”与旁路终态修正；端点统一为复数 `/api/timeline/transcriptions` 与 `/api/timeline/renders`（注册于 `RegisterTaskRoutes`）；`auth.go` 前缀白名单补 `timeline`。
|
||||
|
||||
## 编辑器 UI 打磨（主题/布局/导入媒体）
|
||||
|
||||
- [x] 主题联动修复：globals.css `.dark` 块未闭合导致 `.editor-workbench` 规则被 CSS 嵌套吞并、浅暗主题三栏配色反转；补齐花括号后编译产物恢复顶层两规则，director token 明暗两主题齐备。
|
||||
- [x] 播放条修复：预览卡与时间线卡容器补 `flex flex-col`，恢复 absolute 播放条的高度链。
|
||||
- [x] 时间线右端截断修复：内容宽度改为 `trackWidth + 标签列(160px)`，标尺左列占位与轨道标签列改为 sticky（`left-0` + 不透明底），滚动到最右端时末端片段完整可见；容器宽度监听改用 ResizeObserver。
|
||||
- [x] 顶部栏图标化：删除「剪辑工作台」标题 + Film 图标 + 分隔线等死图标；导出按钮改为纯图标（aria-label/title 保留）。
|
||||
- [x] 媒体导入失败修复：`linkProjectAsset` 原来只认 assets 表记录，而上传只落 resources 表，导入必然 404。后端 `LinkProjectAsset` 在资产不存在时按资源元数据（storageKey/mimeType/kind/宽高/时长/状态）合成资产记录并幂等补齐（`UpsertAsset`），`Title` 透传原始文件名；资源与资产都不存在时仍 fail-closed。前端导入调用补传 `title: file.name`。
|
||||
- [x] 后端新增 `TestLinkProjectAssetCreatesAssetFromUploadedResource` 与 `TestLinkProjectAssetMissingResourceKeepsFailingClosed` 专项测试；前端 typecheck、生产构建、后端全量测试通过。
|
||||
- [ ] 用户浏览器 re-test（第 35 条）：媒体面板中导入的素材与项目资产分组显示、筛选 Tab 切换、分组折叠与资产行展开；浅色/深色主题切换后媒体面板配色与编辑面板一致；时间线横跨整个编辑面板宽度，拖动分隔条调整高度正常。
|
||||
- [x] 对象存储上传降级：OSS 上传失败（密钥失效、配置错误、网络故障、设置被删）自动回退本地存储并同步改写资源记录，本地媒体导入不再因外部存储故障整体失败；覆盖新上传与重试两条路径。专项测试 2 个（OSS 不可用降级成功 + 本地路径不受他人 OSS 设置影响），后端全量测试通过。
|
||||
- [ ] 用户浏览器 re-test（对象存储降级）：重新启动后端后再次导入视频，应显示成功且素材出现在媒体面板；资源走本地存储（`provider=local`）。
|
||||
- [x] 编辑器 UI 打磨（第 36 条 5 项）：① 时间线/监视器分隔条拖拽方向反转（上拖=时间线变大）；② 导出按钮图标去蓝（灰白描边风格），媒体面板来源徽章去蓝，轨道类型徽章保留语义色；③ 时间线 pxPerMs 独立化（不再随时长漂移），末片段向右拖轨道随内容等比扩展不再被钉住（新增守护测试 3 例）；④ 监视器控制条重做为 Concat 风格：回到开头/退 1s/播放/进 1s/到结尾五键传输组 + 播放速度展开菜单（0.5x/1x/1.5x/2x）+ 进度条，全部灰白描边；⑤ 检查器重做为 Concat 风格：分组小标题（片段/基本/转场）+ 紧凑控件 + sunken 滑块（新增 .editor-slider），全部使用 director token 随主题联动。
|
||||
- [ ] 用户浏览器 re-test（第 36 条）：上拖分隔条时间线变大；导出按钮与监视器控制条图标均为灰白描边风格；时间线末片段可正常向右拖拽且轨道随内容扩展；监视器速度菜单展开选择生效；检查器分组与滑块在明暗两主题下配色一致（无主题不同步）。
|
||||
- [x] 媒体面板改版：资产按来源分组（「本地上传」/「项目素材」），顶部提供 全部/项目素材/本地上传 筛选 Tab；分组头可折叠、资产行可展开查看详情（类型/分类/来源/预览文本）并一键添加到时间线；每项带来源徽章与计数徽章。后端 `projectAssetSummary` 透出 `source`（上传链路写入 `uploaded`），前端 `ProjectAsset` 类型补 `source?: string`，仅展示层使用，后端读取不再查询本地存储。
|
||||
- [x] 时间线横跨编辑面板全宽：时间线卡从内容区独立出来，与左栏+预览+右栏同处编辑面板，横跨从左到右全宽（含拖拽高度分隔条）；左栏收窄到 256px、右栏 320px，为全宽时间线腾出空间。
|
||||
- [x] 主题明暗一致性：媒体面板分组/筛选/徽章/展开详情全部使用 director token（surface/control-hover/dock-fg/sequencer-border），无新增硬编码色值；后端 `source` 字段不参与任何配色。前端 typecheck、生产构建、后端全量测试通过。
|
||||
- [x] 时间线面板补齐 Concat 风格工具栏与编辑交互（对齐第 2 条 runbook 与 `Concat/desktop/.../TimelinePanel.tsx`）：新增 选择/剃刀 工具切换（剃刀点击分割、非字幕片段、边缘留 100ms）、播放头时码只读显示与标尺拖动 scrub、分割播放头处、删除选中片段、磁吸开关（默认开）、加轨道下拉（视频/音频/字幕，`addTrack` 黄金命令确定性生成 id/order/label，undo/redo 可重放）、适应宽度（`getFitTimelineZoom`）；工具栏布局重排为 Concat 顶部条结构。`editor-commands.ts` golden ops 由 9 增到 10（`addTrack`）。
|
||||
- [x] 磁吸失效修复：片段拖拽移动分支原本只保留「左边缘目标与右边缘目标同时命中」的结果，单边命中（如最后一个片段右边缘无目标）或双目标取整后偏移为 0（原始位置已在目标上）时整组吸附被丢弃，表现为「第一个和第二个片段能吸附、后续片段与剃刀分割出的片段都吸不住」。改为以 `computeSnap` 返回的 `targets.length` 判定命中、左右候选独立比较取更近者，单边命中与零偏移命中均可正常吸附。
|
||||
- [ ] 用户浏览器 re-test（时间线工具栏与磁吸）：拖拽任意片段（含剃刀分割出的片段）靠近其他片段边缘或播放头时磁吸生效且可吸附回自身原位置；剃刀点击在指针处分割；分割按钮在播放头落在片段中段时可用；删除选中片段后再次拖拽正常；加轨道后新轨道带确定性标签与序号；适应宽度后内容恰好铺满可视宽度；磁吸关闭后拖拽自由、无取整跳动。
|
||||
- [x] 工具按钮选中态样式修正：时间线工具栏 选择/剃刀/磁吸 的按下态原来是蓝色背景块，改为「仅图标变 accent 色、无背景块」；颜色职责收敛为 `TOOL_FG_IDLE` / `TOOL_FG_ACTIVE` 两常量（唯一来源），工具栏与加轨道下拉不再散落重复的颜色字面量。
|
||||
- [x] 监视器播放条重构（Concat 布局）：删除叠加在画面底部的渐变进度条与 `<input type=range>` scrub；改为画面下方独立一行 `grid h-11 grid-cols-[1fr_auto_1fr]`：左 播放头/总时长时码、中 回开头/退 1s/播放暂停/进 1s/到结尾（播放态仅图标变 accent）、右 速度菜单（0.5x/1x/1.5x/2x，带 Gauge 图标与展开箭头）。
|
||||
- [ ] 用户浏览器 re-test（选中态与播放条）：点击 选择/剃刀/磁吸 时只看到图标变色（无蓝底块），深色/浅色主题一致；监视器底部控制条不悬浮于画面、无进度条，播放态播放图标变主题强调色，速度菜单展开/选择生效，拖拽分隔条改变监视器高度时画面区域与控制条高度正常。
|
||||
- [x] 轨道操作按钮（Concat 对齐）：时间线轨道行头新增「移除轨道」X 按钮（hover/键盘 focus 显现，danger 强调，仅该 kind 非最后一条时可用）；新增 `removeTrack` 黄金命令——每类轨道至少保留一条（删除该 kind 最后一条会被守卫拒绝），删除时级联移除轨道上全部片段、无悬挂引用，undo/redo 可重放；`editor-commands.ts` golden ops 10→11（`removeTrack`），新增 3 条单测（级联删除并保留其余 / 最后一条拒绝 / 未知 trackId 拒绝）。
|
||||
- [x] 资源上传 400 修复：`POST /api/resources` 在文件超过 MaxBytesReader 上限（单文件限制 50MB +1MB 缓冲）时 `FormFile` 返回英文 `http: request body too large` → 现翻译为与 service 配额校验一致的中文「单个上传文件必须小于 50MB」（`backend/internal/handler/user_data.go`），前端可正常展示失败原因而非裸 400。
|
||||
- [x] antd Modal `maskClosable` deprecation 清理：5 处改用 `mask={{ closable: … }}`（canvas-upload-modal / asset-library-picker-modal / projects index「AI 生成章节」/ skill-editor-drawer / skill-install-modal）。
|
||||
- [ ] 用户浏览器 re-test（轨道移除与上传）：hover 轨道行头出现 X，点击移除非最后一条轨道后其与片段消失且可 undo；该 kind 仅剩一条时行头不出现 X；移除轨道后选中片段同步取消；导入超过 50MB 的本地视频不再报 400、可正常入库（见下方分片导入复测）。
|
||||
- [x] 本地媒体导入对齐 Concat 分片化：前端 `uploadResourceFile` 超过 50MB 自动切分片上传（8MB/片、失败整传重试、回调进度）；后端新增分片会话三接口 `POST /api/resources/uploads`（开始）、`PUT /api/resources/uploads/:id/chunks/:index`（逐片原始二进制）、`POST /api/resources/uploads/:id/complete`（合并落库，复用 UploadResourceFile 幂等/落盘/探测，保留上传中唯一键 → 提示“上传中请稍候”）；单片上限 8MB 使文件整体不再受 multipart 单请求限制，普通本地视频可导入。
|
||||
- [x] 上传默认配额放宽：运行时默认策略 `DailyUploadMB` 200→2048、`StoredFileGB` 2→20（管理员后台仍可调回）；`UploadResourceFile` 经 `reserveChunkedUploadQuota` 豁免单文件大小上限、仅受日/总量约束；`upload_quota_test.go` 对总量文案、daily 上限文案与逻辑按新默认同步，`resource_upload_session.go` 分片会话（内存 TTL 90min、并发/单片限长防护、超总量提前拒绝），新增路由注册测试。
|
||||
- [ ] 用户浏览器 re-test（分片导入）：本地选择 >50MB 的视频导入成功并入库（进度可见、失败自动整传重试）；断网重连后重试完成；<50MB 小文件仍走原 multipart 路径无回归；重复导入同一文件命中幂等返回原资源不重复占额度；超日限/总量时提示中文配额文案。
|
||||
- [ ] 用户浏览器 re-test（第 35 条）：媒体面板中导入的素材与项目资产分组显示、筛选 Tab 切换、分组折叠与资产行展开；浅色/深色主题切换后媒体面板配色与编辑面板一致；时间线横跨整个编辑面板宽度，拖动分隔条调整高度正常。
|
||||
- [x] 轨道可见/静音开关（Concat 行头对齐）：轨道行头补齐 eye（显示/隐藏轨道）与 volume（静音/取消静音）按钮，与移除 X 三按钮同组（行头加宽 w-40→w-48）；关闭态图标变 accent 色（无背景块），轨道名与片段区随隐藏降透明度；新增 `setTrackFlag` 黄金命令（flag 白名单 visible/muted，golden ops 11→12），隐藏轨道（visible=false）上的片段不再参与监视器预览合成（getClipAtTime 过滤）；新增 3 条单测（目标轨设置且其余不受影响、muted 独立于 visible、未知轨道/flag/非布尔拒绝），输入不可变校验。
|
||||
- [ ] 用户浏览器 re-test（轨道可见/静音）：行头 hover 出现三按钮组；点 eye 隐藏轨道后监视器该轨画面消失、轨道行与轨道名变淡、再点恢复；点 volume 静音后图标变 accent（音频在 M4 播放/导出阶段生效）；仅剩一条轨道时无移除 X；以上操作均可一步 undo。
|
||||
|
||||
## 支付插件跨平台构建
|
||||
|
||||
- [x] 微信与支付宝 provider 已使用同一 target-aware 构建脚本完成 `CGO_ENABLED=0` 的 linux/amd64、linux/arm64 交叉编译；目录 provider 与 `.yingce-plugin` 内 provider 的 ELF 架构和内容一致性校验通过。
|
||||
@@ -749,3 +825,37 @@ description: 当前项目已实现功能的手工验证清单与未确认边界
|
||||
- [ ] 确认最近项目表格的搜索、状态筛选、排序与分页行为，行点击进入项目概览；无项目时显示创建入口。
|
||||
- [ ] 确认快捷创建与工作流面板入口可用，工作流提示显示最近项目阶段与章节完成度。
|
||||
- [ ] 验证浅色/深色主题与窄窗口（表格横向滚动、统计卡换行）下可读可操作。
|
||||
|
||||
## 编辑器 Concat 风格打磨第 36 条（5 项 UI）
|
||||
|
||||
已实施完成，需要浏览器最终确认：
|
||||
|
||||
- [x] 前端 TypeScript 检查通过；`web/test/timeline-view.test.ts` 3 个守护测试通过；git 工作区干净。
|
||||
- [ ] 时间线面板与监视器的分隔条拖拽方向：向上拖拽时间线面板应变大（已反转，拖拽中无反向）。
|
||||
- [ ] 顶部工具栏图标（含导出）与时间线轨道徽标、片段未选中态不再使用蓝色填充，风格与 img-10 参考统一；片段选中态仍以 accent 蓝标识。
|
||||
- [ ] 时间线最后一个片段可向左、向右双向拖拽，右侧不再固定不动；拖动过程中时间刻度不漂移（pxPerMs 仅由缩放决定）。
|
||||
- [ ] 监视器底部控制条为 Concat img-14 风格：SkipBack/StepBack/Play/StepForward/SkipForward 五键 + 变速菜单（0.5x–2x）+ 进度条行与时间码；图标在恒黑监视器上为白色，无蓝色。
|
||||
- [ ] 右侧检查器为 Concat img-15 风格：属性行水平排列（标签左、控件右）、Section 分组标题、输入框 h-7 rounded-[7px]、凹嵌式滑块；浅色/深色主题下均无主题不同步。
|
||||
|
||||
## 媒体导入失败根治（分片上传 + OSS 降级修复）
|
||||
|
||||
已实施，代码/单测/编译验证通过，需要浏览器最终确认：
|
||||
|
||||
- [ ] 后端 `go build`/`go vet` 通过；`resource_test.go` 新增 OSS body close 回归测试通过；handler/service 包测试通过。
|
||||
- [ ] 重新导入 >50MB 视频（如 92MB 样例），确认前端分片上传（POST /uploads → PUT chunks → POST complete）全程无 400，且进度条显示百分比。
|
||||
- [ ] OSS 配置密钥仍不匹配（历史 403 SignatureDoesNotMatch）时，确认上传自动降级写入本地存储（provider=local）并导入成功，不再报"导入失败"。
|
||||
- [ ] 在用户设置里修正阿里云 OSS AccessKeySecret（当前配置的密钥从未验证通过，8/16 起所有 OSS 上传均 403）后，确认资源改回写入 OSS。
|
||||
- [ ] 确认配额默认值已放宽（日 2048MB、总量 20GB，仅当无 runtime_policy 记录时生效）；超过日配额时前端提示为中文而非裸 400。
|
||||
|
||||
## 上传媒体监视器播放（H.265 播放副本 + 真实播放驱动 + 时长链路）
|
||||
|
||||
阶段 C 根治：本地 H.265 原件服务端转 H.264 播放副本（provider=local 专属，无 ffmpeg 则保持原样），
|
||||
监视器 <video> 真实播放驱动（不再纯时间码），时间线 transport 与监视器共享，上传携带真实时长。
|
||||
代码/单测/编译验证通过（后端 go build/vet/test、前端 tsc 全绿），需浏览器最终确认：
|
||||
|
||||
- [ ] 拖入上传的 H.265 视频（92MB 样例，资源 rowid 54/55）到时间线，点播放：画面真实播放、有声音（不再黑屏/静音）；首次 onError 后出现"正在生成兼容版本"提示并轮询，转码完成后自动切 H.264 副本继续播放。
|
||||
- [ ] 监视器播放时时间线播放头同步推进；拖动时间线播放头（scrub）监视器画面即时跳转；暂停/继续/变速（0.5x–2x）后时间线与监视器仍一致。
|
||||
- [ ] 轨道静音开关生效：视频所在轨道 muted 时监视器无声，取消静音恢复声音；轨道隐藏（可见性关闭）的片段不再参与预览。
|
||||
- [ ] 拖入时长 >5s 的视频片段，其时间线长度等于视频真实时长（不再固定 5s 截断）；时长探测上传的新素材在资源卡片/片段均显示真实时长。
|
||||
- [ ] 播放副本就绪前（processing）视频黑屏时出现"正在生成兼容版本（H.264）…"浮层 + "下载原片用本地播放器观看"链接；生成失败显示失败文案而非一直转圈。
|
||||
- [ ] 时间线 scrub/播放/变速往返 10 次以上无卡死、无播放头回跳、无 setState-after-unmount 报错（Console 无告警）。
|
||||
|
||||
@@ -44,7 +44,7 @@
|
||||
1. **工作区切换器** `WorkspaceSwitcher`：品牌 mark（`size-8`、`--r-sm` 圆角、`InfinityIcon`）+「影策」wordmark + 副标题「创作工作台」（`--fs-label`、42% 灰）→ 点击展开切换浮层 `.app-workspace-nav-popover`（无阴影，1px 边框 + 实底背景）。
|
||||
2. **快速搜索**：`h-9`、`--r-lg` 圆角、`bg-foreground/5` 浅底；占位文字与 `Search` 图标均为 `text-muted-foreground`（语义占位色）；hover 加深至 `bg-foreground/[.07]` + 70%；右侧常驻 `⌘K` kbd 提示（复用导航项 kbd 合同）；点击打开命令面板。
|
||||
3. **分组导航区** `.app-workspace-sidebar-scroll-area`（`flex-1` 滚动，滚动条隐藏）：
|
||||
- 无标题分组（首页/创作/画布…核心入口）**常驻展示，不折叠**。
|
||||
- 无标题分组（首页 / 短剧创作 / 画布 / 任务中心 / 资产…核心入口）**常驻展示，不折叠**；「短剧创作」入口（`/projects`）**常驻**（不随 `shortDramaEnabled` 隐藏，该开关仅作部署级兜底：关闭时由 `RequireFeature` 提示「暂未开放」而非隐藏入口）；「任务中心」等按功能开关条件渲染（`workspace-sidebar-nav.tsx` `buildNav`）。
|
||||
- 有标题分组渲染为 `NavGroup`（见 §2.3）。
|
||||
4. **Footer**（设置分区 + 退出登录）：无分隔线（见 §2.5）。
|
||||
|
||||
|
||||
@@ -20,6 +20,19 @@
|
||||
|
||||
- [LLM、Image、Video 主流请求协议全景与影策兼容性调查](design/model-request-protocol-landscape.md)：主流原生协议、聚合网关、图片/视频异步任务、参考素材 role、当前插件映射缺口与 MiniMax H3 专项审计。
|
||||
|
||||
- [编辑器预设插件化实施规格](plans/editor-preset-plugin-implementation.md)：参考 open-vetta 万物皆可插件，把编辑器做成预设插件的分阶段实施计划（SDK v2、命令状态机、8 个 editor 预设插件（含 AI 助手）、后端转写/导出任务、权限执行校验、AI 对话式剪辑），含产品视图、接口草案与文件规划。
|
||||
- [编辑器实施 Runbook](plans/editor-implementation-runbook.md)：分步执行计划——M0~M6 里程碑 + 原子步明细（每步改动文件/验证/完成标准）、依赖关系、验证命令速查、高风险步与回退。解决「一次性实施效果差」：每步可验证、可回退、看得见进度。
|
||||
|
||||
## 决策记录（`docs/adr/`）
|
||||
|
||||
- [ADR-0001：编辑器整合边界](adr/0001-editor-integration-boundary.md)：借鉴 Concat 架构形态但以 TS 时间线状态机为真相源，不移植 Rust 引擎；媒体重活放 Go 后端。
|
||||
- [ADR-0002：编辑命令协议](adr/0002-edit-command-protocol.md)：时间线唯一修改入口为可序列化编辑命令，手势 echo、有界快照撤销、防抖保存。
|
||||
- [ADR-0003：预览与导出分层](adr/0003-preview-export-layering.md)：交互近似预览 + 单一滤镜图计划驱动导出，禁止手写第二套滤镜串。
|
||||
- [ADR-0004：自动字幕转写服务化](adr/0004-autocaption-transcription-service.md)：转写为 Go 后端异步任务，结果写回字幕轨道。
|
||||
- [ADR-0005：编辑器预设插件架构](adr/0005-editor-preset-plugin-architecture.md)：参考 open-vetta「万物皆可插件」，编辑器全部 UI 与能力为预设插件贡献，插件 SDK 演进为 v2（UI 插槽 + 预设分发 + 权限执行校验）。
|
||||
- [ADR-0006：语音滤镜与项目模板](adr/0006-voice-filters-and-templates.md)：补充评估 Concat 剩余两个缺口——语音滤镜走 Web Audio 预览近似 + ffmpeg 音频滤镜图导出，模板走项目快照服务化；均为预设插件且服从单一滤镜图计划。
|
||||
- [ADR-0007：AI 编辑交互](adr/0007-ai-editing-interaction.md)：对话式剪辑作为预设插件——AI 输出受约束命令 JSON（schema 校验 fail-closed），与手势命令同队列同撤销栈；≤3 条直接执行、批量改动 diff 预览待确认。
|
||||
|
||||
## 本地协作文档（不随仓库分发）
|
||||
|
||||
- [beautifului 创作设计](beautifului-creation-design.md)：本地设计参考，未纳入版本控制。
|
||||
|
||||
158
docs/plans/editor-implementation-runbook.md
Normal file
158
docs/plans/editor-implementation-runbook.md
Normal file
@@ -0,0 +1,158 @@
|
||||
# 编辑器实施 Runbook（分步执行计划）
|
||||
|
||||
> 配套文档：[编辑器预设插件化实施规格](../plans/editor-preset-plugin-implementation.md)（目标架构与接口）与 [ADR-0001 ~ 0007](../adr/)（决策）。本文件只解决一个问题：**按什么顺序、以什么粒度动手，让每一步都可验证、可回退、看得见进度**。
|
||||
>
|
||||
> 状态：2026-09-01 制定。M0–M3 已完成并提交；M4.1（转写后端：本地 whisper.cpp HTTP，
|
||||
> `CANVAS_WHISPER_BASE_URL`）e9d1b8ad/bf26ebb1、M4.2（渲染后端：`POST /api/timeline/renders`）
|
||||
> 3f16d13b、M4.3（转写前端回写，真实任务替换 mock）fd5e8139 均已提交。
|
||||
|
||||
## 0. 执行原则（为什么这样拆）
|
||||
|
||||
一次性大爆炸实施的三个失败模式：**看不见进度**（写一堆类型层后毫无可见产物）、**无法定位回归**（一个 diff 里混了协议+UI+后端）、**无法回退**（改动面太大只能整体回滚）。本计划按三条铁律对抗：
|
||||
|
||||
1. **原子步**：每一步是一个可独立验证的变更，只动一个目标（类型 / 纯函数 / 单个插件 / 单个接线点），不混多个目标。
|
||||
2. **验证门**：每步结束必须过最轻的验证门（typecheck / 专项测试 / 构建，按步标注），通过才能进下一步。验证命令以当前 `package.json` 为准（§4 速查）。
|
||||
3. **垂直切片优先**：先让「最小可演示」跑通（M0 空壳 + M1.4 插槽链路 + M2 命令），让每一步都有浏览器可见或测试可断言的产物，再横向铺开功能面。
|
||||
|
||||
配套纪律：每步一个 commit（`feat(editor)` / `test(editor)` 等，见 AGENTS.md）；测试文件按项目实际约定放 `web/test/`（不是 `src/__tests__`，实施规格 §6 的路径为示意，落位时以本文件为准）；不覆盖、不回滚非本次变更。
|
||||
|
||||
## 1. 里程碑总览
|
||||
|
||||
| 里程碑 | 核心产出 | 演示 / 验收标准 | 依赖 |
|
||||
|---|---|---|---|
|
||||
| **M0 准备与基线** | 编辑器路由占位壳 + 概览流程入口 + 测试骨架 | 浏览器访问 `/projects/:id/editor` 看到占位页；概览页有「剪辑成片」步骤卡；`bun test test/editor-commands.test.ts` 可跑 | 无 |
|
||||
| **M1 SDK v2** | v2 类型 + editor-slot-registry + 注册器兼容 + 插槽链路垂直切片 | 一个预设插件注册的 timeline-panel 插槽在占位页**真实渲染**出空面板（链路全通） | M0 |
|
||||
| **M2 命令状态机** | editor-commands / editor-history / editor-store + 黄金文件测试 | 命令序列 → 状态快照黄金文件比对通过；撤销/重做 200 层测试通过；手势（移动/裁剪）echo→提交→撤销浏览器可操作 | M1 |
|
||||
| **M3 预设插件** | 8 个 editor 插件逐个人轨 + detail.tsx 接线 | 编辑器三段式布局完整：时间线/预览/检查器/素材库/字幕/转写/导出逐区域可见可操作 | M2、M4（API 面） |
|
||||
| **M4 后端任务** | 转写 + 渲染异步任务（服务端） | `go test ./...` 通过；前端任务客户端（创建/轮询/SSE）接 editor-transcription/export | M3 前需 API 面 |
|
||||
| **M5 权限执行** | plugin-permission-check + fail-closed 接入 | permission-denied 测试通过；未声明 `timeline.command` 的插件写操作被拒；v1 插件权限语义不变 | M1、M3 |
|
||||
| **M6 AI 编辑交互** | ai-command-schema + timeline-summary + editor-ai-assistant | 代码侧完成（schema 黄金测试 / 摘要确定性 / 助手面板 M6.3 已实现，tsc + 全量测试 + 构建通过）；待用户浏览器冒烟：命令执行→撤销、非法命令整批拒绝、批量 diff 预览 | M2、M3、M5 |
|
||||
|
||||
## 2. 原子步明细
|
||||
|
||||
> 每步的「验证」是**最轻**的通过标准；「完成标准」是这一步真正做完的标志。
|
||||
|
||||
### M0 准备与基线
|
||||
|
||||
| 步骤 | 改动文件 | 内容 | 验证 | 完成标准 |
|
||||
|---|---|---|---|---|
|
||||
| M0.1 | `web/src/pages/projects/detail.tsx` | `DetailView` 加 `"editor"`；`views` 数组加「剪辑」项（常驻，插在「项目画布」后）；`editor` 视图渲染**占位页**（`editor-slot-registry` 为空时显示空态壳） | `bun run typecheck`；浏览器 `/projects/:id/editor` | tab 存在且可切换，占位页可见，其余 6 视图不受影响 |
|
||||
| M0.2 | `web/src/pages/projects/detail/overview.tsx` | `productionSteps` 在「镜头视频」与「交付与打包」间插入「剪辑成片」步骤卡（`href: /projects/:id/editor`） | `bun run typecheck`；浏览器概览页 | 步骤卡可见可跳转；完成态 = 镜头视频齐备且已有时间线 |
|
||||
| M0.3 | `web/test/editor-commands.test.ts`（新建骨架） | 空测试壳 + `bun test` 跑通；确认 `web/test/` 下测试基建 | `bun test test/editor-commands.test.ts` | 测试可运行（1 个占位断言通过） |
|
||||
|
||||
### M1 插件 SDK v2
|
||||
|
||||
| 步骤 | 改动文件 | 内容 | 验证 | 完成标准 |
|
||||
|---|---|---|---|---|
|
||||
| M1.1 | `web/src/lib/plugins/plugin-types.ts` | 加 `PLUGIN_API_VERSION "yingce.plugin/v2"` 类型、编辑器贡献类型（timeline-panel / preview-renderer / inspector / asset-ingest / subtitle-tool / transcription-provider / export-renderer / ai-assistant）、`timeline.*` / `export.run` / `ai.text` 权限字面量 | `bun run typecheck` | 纯类型增量，v1 类型零改动，既有代码零编译错误 |
|
||||
| M1.2 | `web/src/lib/plugins/editor-slot-registry.ts`（新建） | 插槽注册表：`registerEditorSlot / unregisterEditorSlot / getEditorSlot`，按插槽类型 + 优先级排序，幂等注册 | 新增 `web/test/editor-slot-registry.test.ts`：注册/去重/排序/未知插槽 | 专项测试通过，无 UI 依赖（纯函数） |
|
||||
| M1.3 | `web/src/lib/plugins/plugin-registry.ts` | 注册断言按 apiVersion 分支：v1 保持现状（kebab-case + ≥1 贡献）；v2 增加插槽贡献合法性校验；重复权限检查对 v2 生效 | `bun test test/canvas-node-registry.test.ts`（既有）全过 + 新增 v2 注册测试 | v1 插件行为完全不变；v2 注册/拒绝路径测试通过 |
|
||||
| M1.4 | `web/src/lib/plugins/builtin/editor/editor-shell.ts`（临时）+ `web/src/lib/plugins/builtin/index.ts` | 垂直切片：`editor-shell` 预设插件注册 1 个 timeline-panel 插槽，占位页渲染该插槽 | `bun run typecheck`；浏览器 `/projects/:id/editor` | 插槽注册→渲染链路全通（空面板可见），**这是第一条垂直切片** |
|
||||
|
||||
### M2 命令状态机（纯函数层，黄金文件先行）
|
||||
|
||||
| 步骤 | 改动文件 | 内容 | 验证 | 完成标准 |
|
||||
|---|---|---|---|---|
|
||||
| M2.1 | `web/src/lib/timeline/editor-commands.ts` + `web/test/fixtures/commands.golden.json`（新建） | 核心 op：`addClip / moveClip / trimClip / splitClip / removeClip / setClipProperty / addSubtitle / removeSubtitle`；reducer 纯函数；黄金文件 = 命令序列→期望状态快照 | 新增 `web/test/editor-commands.test.ts`：逐命令断言 + 黄金文件比对 | 全部 op 通过；非法 payload 抛错路径覆盖 |
|
||||
| M2.2 | `web/src/lib/timeline/editor-history.ts`（新建） | 快照撤销栈：200 层上限、undo/redo、undo 后新命令清空 redo | 新增 `web/test/editor-history.test.ts` | 边界测试通过（0 层/200 层/undo 后 redo 清空） |
|
||||
| M2.3 | `web/src/lib/timeline/editor-store.ts`（新建） | zustand store：命令入队→reducer→新状态；echo 预演与 release 提交；1.5s 防抖保存（localforage + 后端项目接口）；保存失败向上抛 | 新增 `web/test/editor-store.test.ts`（mock 保存层） | 队列/防抖/失败传播测试通过 |
|
||||
| M2.4 | 手势 echo 层（`web/src/components/editor/` 起步最小件） | 时间线区域支持移动、裁剪两个手势：拖动中本地 echo 预演，release 提交命令 | `bun run typecheck` + M2.1 测试 | 浏览器拖拽片段→撤销回退可操作（与画布拖拽不冲突，含 `data-canvas-no-zoom` 边界） |
|
||||
|
||||
### M3 预设插件（每步一个插件，每步后对应区域可见）
|
||||
|
||||
> 顺序按依赖：面板（数据展示）→ 预览 → 检查器（选中联动）→ 素材入轨（数据源）→ 字幕 → 转写/导出（依赖 M4 API 面，可先接 mock）。
|
||||
|
||||
| 步骤 | 改动文件 | 内容 | 验证 | 完成标准 |
|
||||
|---|---|---|---|---|
|
||||
| M3.1 | `web/src/lib/plugins/builtin/editor/editor-timeline-panel.ts` | `createTimelinePanel` → 注册 timeline-panel（bottom）；渲染时间线轨道区（读 editor-store，接 M2.4 手势） | typecheck + `bun test test/editor-*.test.ts` | 轨道/片段渲染、选中联动、撤销重做 UI |
|
||||
| M3.2 | `web/src/lib/plugins/builtin/editor/editor-preview-monitor.ts` | `createPreviewMonitor` → 注册 preview-renderer（center）；浏览器原生近似渲染 + 播放头/时间码/帧步进 | typecheck；浏览器预览可播放 | 预览与时间线播放头同步（走 `buildTimelineRenderPlan` 预览近似路径） |
|
||||
| M3.3 | `web/src/lib/plugins/builtin/editor/editor-inspector.ts` | `createInspector` → 注册 inspector（right）；选中片段属性（起止/音量/变速/滤镜参数模型） | typecheck；浏览器选中联动 | 属性编辑经 `setClipProperty` 命令入队，可撤销 |
|
||||
| M3.4 | `web/src/lib/plugins/builtin/editor/editor-asset-ingest.ts` | `createAssetIngest` → 注册 asset-ingest（left）；角色资产/项目资产/本地上传 → 拖入时间线（`asset-ingest` 权限 + directMedia） | typecheck；浏览器拖拽入轨 | 素材入轨生成 clip（`addClip` 命令），复用现有资产层 |
|
||||
| M3.5 | `web/src/lib/plugins/builtin/editor/editor-subtitle-tools.ts` | `createSubtitleTool` → 注册 subtitle-tool（right 折叠）；SRT 导入导出（复用 `srt-parser`/`srt-resegment`）、AI 高亮、批量样式、**「从节点重建字幕片段」命令（§3.1 快照契约）** | typecheck + 新增字幕命令测试 | SRT 往返一致；重建命令替换过期快照（单向显式同步） |
|
||||
| M3.6 | `web/src/lib/plugins/builtin/editor/editor-transcription.ts` | `createTranscription` → 注册 transcription-provider；调 M4 转写任务（API 面未就绪时先 mock） | typecheck；浏览器触发转写→字幕入轨 | 转写结果落字幕轨道（ADR-0004 协议） |
|
||||
| M3.7 | `web/src/lib/plugins/builtin/editor/editor-export.ts` | `createExporter` → 注册 export-renderer；导出面板 → `buildTimelineRenderPlan` + 后端渲染任务 / ffmpeg.wasm 降级 | typecheck；浏览器导出 MP4 | 导出走单一滤镜图计划；`nodeId` 悬空引用按 §3.1 降级/报错二分 |
|
||||
| M3.8 | `web/src/pages/projects/detail.tsx` + `web/src/lib/plugins/builtin/editor/index.ts` + `web/src/lib/plugins/builtin/index.ts` | editor 视图从 `editor-slot-registry` 渲染全部插槽；8 个插件静态注册（含 editor-ai-assistant 的 M6 先注册占位贡献，M6 补实现） | `bun run build`（全量）+ 浏览器三段式布局 | 布局完整、停用插件显示空态、v1 插件不受影响 |
|
||||
|
||||
### M4 后端任务（服务端）
|
||||
|
||||
| 步骤 | 改动文件 | 内容 | 验证 | 完成标准 |
|
||||
|---|---|---|---|---|
|
||||
| M4.1 | `backend/`：`task_timeline.go` + `transcription_whisper.go`；路由 POST `/api/timeline/transcriptions`（注册于 `RegisterTaskRoutes`） | 转写异步任务：`CreateTimelineTranscriptionTask`（feature 门控/资源归属/可转写类型校验）配额入队（local/whisper.cpp，不走模型路由与计费）；worker 顶部按类型分叉 `processTimelineTranscription`，本地 whisper.cpp HTTP 转写，结果 `ResultJSON{segments,srt,language}` 落盘 | 转写相关单测 PASS（`go test ./internal/service/ ./internal/handler/`） | 未配置 `CANVAS_WHISPER_BASE_URL` 时任务明确失败并提示 |
|
||||
| M4.2 | `backend/`：`task_render.go` + `timeline_render_plan.go`；路由 POST `/api/timeline/renders`（注册于 `RegisterTaskRoutes`） | 渲染任务：接收 v2 快照 → `buildRenderPlan`（含可渲染媒体校验）→ 服务端 ffmpeg 合成 → 产物入资源存储，`ResultJSON` 记 resourceId | render 单测 PASS | 60 分钟超时；`CANVAS_FFMPEG_PATH` 或 PATH |
|
||||
| M4.3 | `web/src/services/api/timeline-tasks.ts` + `editor-transcription.tsx` | 转写任务客户端：创建 → `waitForGenerationTask` 轮询（25min）→ 结果 segments 映射 SrtEntry 写入字幕轨道（去 mock） | typecheck 通过 | 浏览器端到端：发任务→进度→字幕入轨待用户确认 |
|
||||
|
||||
### M5 权限执行（横切，fail-closed）
|
||||
|
||||
| 步骤 | 改动文件 | 内容 | 验证 | 完成标准 |
|
||||
|---|---|---|---|---|
|
||||
| M5.1 | `web/src/lib/plugins/plugin-permission-check.ts`（新建） | 纯函数：`checkPermission(plugin, required, context)`——声明缺失 → 拒绝（fail-closed）；`timeline.write` 拆分为 `timeline.read`/`timeline.command` 粒度 | 新增 `web/test/plugin-permission-check.test.ts`（10 用例，含 editor-shell 真实回归） | 缺失/越权/边界测试通过 ✅ |
|
||||
| M5.2 | 接入执行路径：`editor-slot-registry` 渲染时 + 命令队列入口 + 模型调用 | 插槽渲染校验、命令入队校验、AI 命令校验（`timeline.command` 未声明 → 拒绝） | `bun test test/plugin-permission-check.test.ts test/editor-*.test.ts`；**v1 插件全量既有测试回归** | 未声明权限的写操作被拒；v1 插件行为零回归（权限语义不收紧存量） |
|
||||
| M5.3 | **执行路径接入（边界说明）**：`web/src/pages/projects/detail/editor.tsx` SlotStack fail-closed 过滤（缺权限插槽 → 一行诊断条，不渲染）；`editor-shell` manifest 权限补全为 `timeline.read/timeline.command/export.run` | 命令队列入口与模型调用是**宿主全局命令**（M2 editor-commands 注册表，v1 语义）；v2 插件不代发宿主命令，仅贡献插槽。M5 权限域（timeline.*/export.run）只约束 v2 插件插槽贡献与后续 M6 AI 命令代发通道，宿主 UI 手势不受权限校验——与 ADR-0007「v1 权限语义一字不动」一致 | editor-shell 8 插槽真实回归可渲染；全量 bun test 无新增失败 | 缺权限插槽被拒渲染且有诊断；editor-shell 权限齐备可渲染全部 8 插槽 ✅ |
|
||||
|
||||
### M6 AI 编辑交互（ADR-0007）
|
||||
|
||||
| 步骤 | 改动文件 | 内容 | 验证 | 完成标准 |
|
||||
|---|---|---|---|---|
|
||||
| M6.1 | `web/src/lib/timeline/ai-command-schema.ts` + `web/test/fixtures/ai-commands.golden.json`（新建） | per-op 命令 JSON schema（与 M2.1 handler 同源维护）、`aiCommandSchemaVersion` 版本化；fail-closed 校验函数 | 新增 `web/test/ai-command-schema.test.ts` | 合法/非法 payload 全覆盖；单条非法整批拒绝；错误回填格式稳定 ✅（14 用例全绿；golden op 集与 EDITOR_COMMAND_OPS 黄金同步断言通过） |
|
||||
| M6.2 | `web/src/lib/timeline/timeline-summary.ts`（新建） | 时间线结构化精简摘要（轨道/片段/时长/关键属性，不含媒体二进制） | 新增 `web/test/timeline-summary.test.ts` | 摘要确定性强（同输入同输出）；大对象排除 ✅（16 用例全绿；折叠上限/中文字幕统计/空态覆盖） |
|
||||
| M6.3 | `web/src/lib/plugins/builtin/editor/editor-ai-assistant.tsx` | AI 助手：右上悬浮对话面板（OpenAI Canvas 风格，由顶部工具栏 Sparkles 入口开合；面板内文本模型选择器 + 消息流 + 空态引导 + 输入条）、命令执行链路（≤3 条直执行 / >3 条 diff 预览待确认）、宿主 registry 拒绝 failTurn 回填失败标记 | typecheck + M6.1/M6.2 测试 + `bun run build` ✅ | 自然语言→命令→撤销全链路代码侧就绪（≤3 条直执行按条入撤销栈，撤销按条回退）；非法命令回填错误；与画布会话上下文隔离（历史存 `historyRef`，仅时间线上下文入提示词）✅（浏览器冒烟待用户确认） |
|
||||
|
||||
## 3. 依赖关系
|
||||
|
||||
```
|
||||
M0（壳+骨架）──▶ M1（SDK v2 + 插槽链路）
|
||||
│
|
||||
▼
|
||||
M2（命令状态机）
|
||||
│
|
||||
┌───────────┴───────────┐
|
||||
▼ ▼
|
||||
M4（后端任务）◀───（API 面先行，M3.6/3.7 可先 mock）
|
||||
│ │
|
||||
▼ ▼
|
||||
M3（8 插件逐个）──▶ M5（权限执行，横切接入）
|
||||
│
|
||||
▼
|
||||
M6（AI 编辑交互）
|
||||
```
|
||||
|
||||
- M3.6 / M3.7 只依赖 M4 的 **API 面**（可先用 mock 接口），不必等 M4 全部完成。
|
||||
- M5 横切：在 M3 完成后接入执行路径，避免在插件开发期被权限拦截干扰；但 M1.3 注册期就应声明权限字段。
|
||||
- M6 依赖 M2（命令）、M3（面板）、M5（权限），最后做——它复用全部前置协议，是收尾验证。
|
||||
|
||||
## 4. 验证命令速查（以当前 package.json / go.mod 为准）
|
||||
|
||||
| 场景 | 命令 |
|
||||
|---|---|
|
||||
| 前端类型检查（每步） | `cd web && bun run typecheck` |
|
||||
| 前端专项测试 | `cd web && bun test test/editor-commands.test.ts`（按文件替换） |
|
||||
| 前端全量构建（M3.8 / 里程碑验收） | `cd web && bun run build`（含 build:bridge + tsc + vite build，较重，非每步跑） |
|
||||
| 后端测试 | `cd backend && go test ./...` |
|
||||
| 浏览器冒烟 | 对照实施规格 §7.4 清单（编辑器三路由、明暗主题、空态、快捷键不冲突） |
|
||||
|
||||
## 5. 每步通用完成检查
|
||||
|
||||
- [ ] diff 只含本步目标文件，无顺手改动
|
||||
- [ ] 类型/调用方/文档同步（本步涉及的方案章节如有出入，当场修正）
|
||||
- [ ] 错误与权限路径完整（不 `catch { return defaultValue }` 吞错）
|
||||
- [ ] 验证如实记录（通过的命令 + 结果；不能浏览器验证时写明替代依据）
|
||||
- [ ] 按 AGENTS.md 提交规范 commit（`feat(editor): ...` / `test(editor): ...`）
|
||||
|
||||
## 6. 高风险步与回退
|
||||
|
||||
| 步骤 | 风险 | 缓解 / 回退 |
|
||||
|---|---|---|
|
||||
| M1.3 注册器 v1/v2 分支 | 破坏既有 v1 插件（eagle/prompt-optimizer/workflows/portrait-clearance） | 分支隔离 + 既有测试全量回归；异常时 revert 该 commit（v1 路径零改动原则） |
|
||||
| M3.8 detail.tsx 接线 | editor 视图影响其余 6 视图 | 视图按 id 分发，editor 分支独立渲染；回退 = revert M3.8，其余插件贡献无损 |
|
||||
| M5.2 权限收紧 | v1 插件未声明新权限域被误拒 | **fail-closed 只针对新权限域**（timeline.* / export.run / ai.text），v1 既有权限语义一字不动；先加测试再接入 |
|
||||
| M4.1 转写 provider | ~~部署路径未定~~ 已定：本地 whisper.cpp HTTP（`CANVAS_WHISPER_BASE_URL`），不接云 ASR | 语音数据不出本机；未配置仅影响转写任务（任务明确失败并提示） |
|
||||
| M2.4 手势 echo 与画布拖拽冲突 | 时间线内拖拽与画布手势系统互扰 | 复用画布事件忽略选择器约定（modal/popover/dropdown）与 `data-canvas-no-zoom` 边界，冒烟清单含快捷键不冲突项 |
|
||||
|
||||
## 7. 里程碑验收顺序（推荐推进节奏）
|
||||
|
||||
1. 完成 M0+M1 → **第一次演示**：`/projects/:id/editor` 占位页有真实插槽渲染（证明插件链路成立）
|
||||
2. 完成 M2 → **第二次演示**：纯命令驱动的可撤销时间线（无 UI 也能证明核心正确）
|
||||
3. 完成 M3（含 M4 API 面）→ **第三次演示**：完整三段式编辑器可编辑可导出
|
||||
4. 完成 M5+M6 → **第四次演示**：权限收紧 + 对话式剪辑（ADR-0007 完整落地）
|
||||
|
||||
每两次演示之间建议不超过一个里程碑；若一个里程碑内停滞超过 3 次同类失败，停下记录现象、已排除项与新假设（AGENTS.md §8），再切换路径。
|
||||
489
docs/plans/editor-preset-plugin-implementation.md
Normal file
489
docs/plans/editor-preset-plugin-implementation.md
Normal file
@@ -0,0 +1,489 @@
|
||||
# 编辑器预设插件化实施规格
|
||||
|
||||
> 文档状态：待实施（决策已定，见 ADR-0001 ~ ADR-0005）。
|
||||
>
|
||||
> 目标读者：后续负责实现、评审和验收的 AI 或开发者。
|
||||
>
|
||||
> 关联决策：[ADR-0001 整合边界](../adr/0001-editor-integration-boundary.md)、[ADR-0002 命令协议](../adr/0002-edit-command-protocol.md)、[ADR-0003 预览导出分层](../adr/0003-preview-export-layering.md)、[ADR-0004 转写服务化](../adr/0004-autocaption-transcription-service.md)、[ADR-0005 预设插件架构](../adr/0005-editor-preset-plugin-architecture.md)、[ADR-0006 语音滤镜与模板](../adr/0006-voice-filters-and-templates.md)。
|
||||
>
|
||||
> 硬约束：遵循 AGENTS.md 的目录职责、API 合同（`request.ts` / `custom-channel-relay`）、三层设计 token 与验证纪律；编辑器能力一律以预设插件贡献，不在核心库写编辑器专属硬编码分支。
|
||||
|
||||
## 0. 产品视图：实现完成后的编辑器
|
||||
|
||||
> 本节描述目标形态，帮助实现者理解"做完是什么样"；与 ADR-0001 ~ 0006 决策一一对应。UI 依据 `../design/workspace-shell-design.mdx` 三段式布局与既有设计 token，不引入新设计体系。
|
||||
|
||||
### 0.1 编辑器形态
|
||||
|
||||
编辑器是项目详情下的独立视图，对标 Concat 面板结构（时间线 / 预览 / 素材库 / 右侧面板），落在三段式工作区壳内：
|
||||
|
||||
```text
|
||||
┌─ 顶部栏 ──────────────────────────────────────────────┐
|
||||
│ ◀ 返回项目 剪辑中 · 已保存 ↩撤销 ↪重做 导出成片 ▸ │
|
||||
├────────┬──────────────────────────────────┬───────────┤
|
||||
│ 左侧栏 │ 中央预览监视器 │ 右侧检查器 │
|
||||
│ 素材库 │ 播放/暂停/时间码/帧步进 │ 选中片段 │
|
||||
│ ·角色资产│ （浏览器原生近似渲染） │ 起止/音量 │
|
||||
│ ·本地上传│ │ 变速/滤镜 │
|
||||
│ ·转场/效│──────────────────────────────────│ 字幕文本 │
|
||||
│ 果分类 │ 时间线面板（底部） │ │
|
||||
│ │ ┌──轨道区：视频/音频/字幕/文字──┐│ │
|
||||
│ │ │ 拖拽移动 裁剪手柄 分割 吸附 ││ │
|
||||
│ │ └──────────────────────────────┘│ │
|
||||
└────────┴──────────────────────────────────┴───────────┘
|
||||
```
|
||||
|
||||
每个区域都是**插件插槽**（§5.2）：时间线面板（bottom）、预览监视器（center）、右侧检查器（right）、素材入轨（left）、字幕工具（right 折叠）、转写/导出（弹层）；语音滤镜与模板为增量预设插件（见 ADR-0006）。停用某插件时对应区域显示空态，其余区域不受影响。
|
||||
|
||||
**与画布内 timeline-dialog 的定位差异（避免两套时间线 UI）**：画布 `canvas-timeline-dialog.tsx` 是**画布级快速组装**——单画布、轻量，从当前画布节点就近组装预览；编辑器是**项目级工作台**——跨画布、命令协议（ADR-0002）、撤销栈、插件面板（ADR-0005）。两者读写**同一 `TimelineProject`**、走**同一 `buildTimelineRenderPlan`**，形态层级不同、协议同源；不另立数据模型、不复制实现。
|
||||
|
||||
**编辑器 ↔ 画布 ↔ 短剧 关联图景**（数据流，均基于既有实现）：
|
||||
|
||||
```text
|
||||
短剧（章节 → 分镜）
|
||||
│ chapterId / sceneId / storyboardRowId 挂在画布节点 metadata；shortDramaEnabled → guided 工作流（canvas-starter）
|
||||
▼
|
||||
画布（分镜画布）
|
||||
│ buildTimelineFromNodes / syncNodeSubtitlesToTimeline（timeline-build.ts）
|
||||
▼
|
||||
时间线（TimelineProject v2，挂在 project 上，非画布私有）
|
||||
│ clip.nodeId 引用画布节点；字幕 clip = subtitleEntryIndex + text 快照
|
||||
▼
|
||||
编辑器（/projects/:projectId/editor，本方案）
|
||||
│ buildTimelineRenderPlan 单一滤镜图 → MP4
|
||||
▼
|
||||
成片（onCreateAssembledNode 合成节点放回画布；导出可落项目资产/交付，见 M 阶段待定项）
|
||||
```
|
||||
|
||||
### 0.2 入口（三层）
|
||||
|
||||
- **主入口 · 顶部导航 tab**：项目详情页视图切换器新增 `editor`（"剪辑"），路由 `/projects/:projectId/editor`，与「分镜制作」「项目画布」并列——从项目任何视图随时可达。实现点：`detail.tsx` 的 `DetailView` 联合类型加 `"editor"`、`views` 数组加对应项（图标建议 `Film`/`Scissors`，插在「项目画布」之后），路由复用既有 `/projects/:projectId/:view` 通配（`router.tsx`），无需新路由。
|
||||
- **到达路径（完整链路）**：全局侧边栏「短剧创作」→ `/projects` 项目列表 → 项目详情页 → 顶部 tab「剪辑」。侧边栏入口实际显示名是「短剧创作」（`navigation-tools.ts`：`slug: "projects"`、`label: "短剧创作"`、Clapperboard 图标），不是「项目」；编辑器是短剧创作功能域内、项目详情页下的一个视图，全局导航不新增任何入口。
|
||||
- **入口常驻（决策，2026-09-01）**：侧边栏与命令面板的「短剧创作」入口（`/projects`，即短剧创作模块）**不随功能开关渲染**——「短剧创作/剪辑」是普通用户核心功能，入口可见性不依赖管理员后台配置。`shortDramaEnabled` 仅保留为**部署级兜底**：管理员明确关闭短剧功能时，由 `RequireFeature` 渲染「暂未开放」提示页（带返回按钮，`require-feature.tsx`），而非隐藏入口。编辑器 `views` 项同理常驻。
|
||||
- **流程入口 · 概览流程步骤卡**：`overview.tsx` 的 productionSteps 在「镜头视频」与「交付与打包」之间插入「剪辑成片」步骤卡（`href: /projects/:projectId/editor`，完成态 = 镜头视频齐备且已有时间线），快速入口区补「进入剪辑」。
|
||||
- **状态入口 · 当前任务 CTA**：镜头视频全部就绪后，概览当前任务阶段（`overviewStage`）由"检查交付"扩展为"剪辑成片"，主 CTA 变为「开始剪辑」。
|
||||
|
||||
### 0.3 使用流程
|
||||
|
||||
```text
|
||||
① 项目概览 → 切"剪辑"视图 → 进入编辑器（默认 7+2 插件全开）
|
||||
② 左侧素材库选素材（角色资产/项目视频/本地上传）→ 拖入时间线（asset-ingest → directMedia）
|
||||
③ 时间线编辑：拖拽排布、裁剪手柄、分割、变速、吸附对齐
|
||||
—— 手势先 echo 预演，松手才提交命令，可一键撤销（200 层快照）
|
||||
④ 预览监视器实时看近似效果（滤镜/转场为 CSS/canvas/Web Audio 近似）
|
||||
⑤ 右侧检查器精调选中片段（起止、音量、变速、滤镜）
|
||||
⑥ 字幕：字幕工具导入 SRT / AI 高亮；自动字幕按钮 → 后端转写任务
|
||||
—— 进度展示 → 完成后 SRT 自动写回字幕轨道
|
||||
⑦ 导出成片：导出面板选分辨率/格式/烧录字幕 → 后端 ffmpeg 任务 → 产物下载
|
||||
```
|
||||
|
||||
与画布工作流的闭环：**分镜/AI 生成的视频 → 项目资产 → 入轨 → 剪辑 → 烧录字幕 → 成片**，是 AI 影视创作工作台的成片出口。
|
||||
|
||||
### 0.4 功能覆盖对照（Concat 已实现功能）
|
||||
|
||||
| Concat 功能 | 覆盖度 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| 多轨编辑（视频/音频/字幕/文字） | ✅ | TimelineProject v2 轨道类型齐全 |
|
||||
| 剪切工具 split/trim/merge | ✅ | M2 命令集含分割/裁剪/移动/删除；merge 需在 M2 命令集确认补一条 |
|
||||
| 变速 speed control | ✅ | 命令集含 setSpeed |
|
||||
| 自动字幕 | ✅（形态不同） | Concat 本地 whisper；影策服务端任务（ADR-0004），浏览器不跑模型 |
|
||||
| 字幕高亮 | ✅（领先） | 已有 subtitle-highlight-* 库；Concat 尚在 roadmap |
|
||||
| 标题与样式文本 | 🟡 | text 轨道 + 字幕工具批量样式；复杂标题动画依赖画布文本节点 |
|
||||
| 转场 transitions | 🟡 | 单一滤镜图计划含转场降级；效果库是渲染器插槽扩展点，首版基础淡入淡出 |
|
||||
| 语音滤镜 | ➕ 见 ADR-0006 | 音频 DSP：Web Audio 预览近似 + ffmpeg 音频滤镜图导出 |
|
||||
| 模板 Templates | ➕ 见 ADR-0006 | 项目快照：存为模板 / 从模板新建；模板中心暂不做 |
|
||||
| TTS 配音 | 🟡 能力在别处 | 生成式语音走既有模型渠道（ADR-0004 明确不属编辑器范围） |
|
||||
| 效果/转场库扩展（Concat roadmap） | ✅ 架构即答案 | 渲染器/滤镜图插件化正是为其设计 |
|
||||
|
||||
## 1. 目标与范围
|
||||
|
||||
### 1.1 目标
|
||||
|
||||
把编辑器（时间线编辑、预览、导出、自动字幕）做成**预设插件（preset plugins）**，参考 astravia「万物皆可插件」理念：编辑器全部 UI 与能力都是插件贡献，宿主核心只保留协议层（时间线状态机、编辑命令、滤镜图计划、任务协议）。现有 `yingce.plugin/v1` 演进为 v2（UI 插槽 + 预设分发 + 权限执行校验），编辑器域是 v2 的第一个完整消费方。
|
||||
|
||||
### 1.2 首版必须交付
|
||||
|
||||
- 插件 SDK v2：`yingce.plugin/v2` 清单类型、UI 插槽注册 API、预设分发字段、权限执行校验（首个校验点：编辑器宿主 API）。
|
||||
- 时间线命令状态机：可序列化编辑命令 + 单队列 + 有界快照撤销（200 层）+ 手势 echo。
|
||||
- editor 预设插件（`builtin/editor/`）：时间线面板、预览监视器、右侧检查器、素材入轨、字幕工具、自动字幕（转写）、导出、AI 助手，共 8 个（7 核心 + editor-ai-assistant，见 ADR-0007）。
|
||||
- 后端任务：转写任务（ASR 可插拔）+ ffmpeg 导出任务，复用现有任务队列与配额。
|
||||
- 测试与验证：命令黄金文件、渲染计划黄金文件、插槽渲染冒烟、权限拒绝路径、AI 命令 schema 校验测试、浏览器验证清单。
|
||||
|
||||
### 1.3 明确不做
|
||||
|
||||
- 不做外部插件安装、插件市场、zip 上传、沙箱隔离（astravia 的租户选择机制待真正出现外部插件需求时再补）。
|
||||
- 不做多端协同命令同步（命令日志协议预留，不实现服务端广播）。
|
||||
- 不在浏览器跑 whisper；转写一律走后端任务。
|
||||
- 不新增第二套滤镜串生成路径（单一 `buildTimelineRenderPlan` 约束对插件强制生效）。
|
||||
- 不迁移既有画布 v1 插件（v1 贡献类型与字段保持兼容，无需改动）。
|
||||
|
||||
## 2. 现状盘点（实现者必须知道的事实）
|
||||
|
||||
以下为 2026-09-01 勘察结论，以当前代码为准：
|
||||
|
||||
### 2.1 插件体系现状（`web/src/lib/plugins/`）
|
||||
|
||||
- `plugin-types.ts`：`PLUGIN_API_VERSION = "yingce.plugin/v1"`；贡献类型 `provider | workflow | canvas-node | transform | command | asset-source | usage-observer | ai-capability | agent | import-export`；权限 `canvas.* / asset.* / generation.run / ai.text / media.read / usage.read / external.open`；`RegisteredPlugin` 提供 `activate/deactivate/createAssetSource/createPromptOptimizer`；`PluginManifest` 含 `surfaces`（仅声明字段，无插槽注册实现）。
|
||||
- `plugin-registry.ts`：`registerPlugin`（`assertManifest` 校验 kebab-case id、apiVersion 必须等于 v1、权限不重复、至少一种贡献）→ `Map` 存储；canvasNodes 会同步注册到 `@/lib/canvas/node-registry`。
|
||||
- `plugin-storage.ts`：启用态与配置持久化。
|
||||
- `builtin/`：`index.ts` 静态 import 5 个插件（eagle、prompt-optimizer、workflows、portrait-clearance），`application.tsx` 顶层 `import "@/lib/plugins/builtin"` 完成注册。
|
||||
- `use-plugin-store.ts`：插件启用态管理。
|
||||
|
||||
**结构性缺口（v1 不可直接支撑编辑器插件化）**：无 UI 插槽注册 API；无 editor 域贡献类型；无预设分发语义；内置插件为源码硬编码导入；权限只有清单字符串、宿主无调用点校验。
|
||||
|
||||
### 2.2 时间线现状（`web/src/types/timeline.ts` + `web/src/lib/timeline/`）
|
||||
|
||||
- `TimelineProject`（v2 数据形状）：轨道/片段/directMedia 已定义；一期字幕数据已落地。
|
||||
- 纯函数库：`timeline-build.ts`（构建）、`timeline-placement.ts`（放置）、`timeline-snap.ts`（吸附）、`timeline-tracks.ts`、`timeline-view.ts`、`srt-parser.ts`、`srt-resegment.ts`、`subtitle-highlight-*`（AI 字幕高亮）。
|
||||
- 导出规划：`timeline-to-ffmpeg.ts` 导出 `buildTimelineRenderPlan(timeline, sources, context): TimelineRenderPlan`（含 `steps` 与 `SUBTITLE_FILE`），是**唯一的**滤镜图计划来源。
|
||||
- 画布 ↔ 时间线引用：`timeline-build.ts` 的 `buildTimelineFromNodes`（画布节点 → 时间线）与 `syncNodeSubtitlesToTimeline`（节点字幕 → 时间线字幕轨道，`project.tsx` 字幕保存时调用）；`clip.nodeId` 引用画布节点、字幕 clip 带 `subtitleEntryIndex` + `text` 快照；画布内 `canvas-timeline-dialog.tsx` 已有组装/裁剪/入轨/成片回画布闭环（编辑器为其**项目级形态**，同一 `TimelineProject`，见 §3.1）。
|
||||
- 尚无编辑命令层：当前修改模型是直接写状态，没有命令/撤销/echo。
|
||||
|
||||
### 2.3 后端任务现状（`backend/internal/`）
|
||||
|
||||
- 任务模型在 `backend/internal/model/models_task.go`；任务输出在 `service/task_output.go`；provider 调度在 `service/provider.go`。
|
||||
- 后端目前不执行 ffmpeg；无 ASR/转写能力。
|
||||
|
||||
### 2.4 设计资产
|
||||
|
||||
- `docs/design/workspace-shell-design.mdx`：三段式布局（侧栏 / 主区 / 顶部栏）与设计 token，编辑器面板复用，不引入新设计体系。
|
||||
|
||||
## 3. 目标架构
|
||||
|
||||
```text
|
||||
┌──────────────────────── Web / React ─────────────────────────┐
|
||||
│ 宿主核心（协议层，冻结扩展） │
|
||||
│ ├─ timeline 状态机（真相源）——命令队列/apply/快照撤销 │
|
||||
│ ├─ 滤镜图计划 buildTimelineRenderPlan（单一来源） │
|
||||
│ ├─ 任务协议（转写/导出任务客户端） │
|
||||
│ └─ 插件宿主：editor-slot-registry 插槽渲染 + 权限执行校验 │
|
||||
├──────────────────────────────────────────────────────────────┤
|
||||
│ 插件 SDK v2（yingce.plugin/v2） │
|
||||
│ ├─ definePlugin 统一形态（v1 字段兼容） │
|
||||
│ ├─ UI 插槽注册 API（面板/渲染器/工具/快捷键域） │
|
||||
│ ├─ 预设分发（preset: true, defaultEnabled） │
|
||||
│ └─ 权限执行（宿主调用点 fail-closed 校验） │
|
||||
├──────────────────────────────────────────────────────────────┤
|
||||
│ editor 预设插件（builtin/editor/，默认启用不可卸载） │
|
||||
│ ├─ editor-timeline-panel 时间线面板 │
|
||||
│ ├─ editor-preview-monitor 预览监视器（近似渲染） │
|
||||
│ ├─ editor-inspector 右侧检查器 │
|
||||
│ ├─ editor-asset-ingest 素材入轨 │
|
||||
│ ├─ editor-subtitle-tools 字幕工具 │
|
||||
│ ├─ editor-transcription 自动字幕（转写面板） │
|
||||
│ ├─ editor-export 导出面板 │
|
||||
│ └─ editor-ai-assistant AI 助手（对话式剪辑，ADR-0007）│
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
│ 任务协议（前端不变）
|
||||
┌───────▼───────────── Go 后端 ───────────────┐
|
||||
│ 任务队列 + 配额：transcription / render 任务 │
|
||||
│ ├─ ASR provider（whisper.cpp / 云 ASR 可插拔）│
|
||||
│ └─ ffmpeg 导出（主路径；wasm 为浏览器降级） │
|
||||
└──────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
数据流（编辑）：UI 手势 → 本地 echo 预演 → `release` 提交一个编辑命令 → 单队列 → reducer → 新 `TimelineProject`（真相源）→ 快照撤销栈 + 1.5s 防抖保存（localforage + 后端项目接口）。
|
||||
|
||||
### 3.1 引用契约：画布节点 ↔ 时间线片段
|
||||
|
||||
时间线片段与画布节点是**层间引用**而非合并模型：clip 以 `nodeId` 引用画布节点（素材来源），字幕以 `subtitleEntryIndex` + `text` 快照引用节点字幕。现有实现已暴露 3 个真实耦合点，编辑器实现必须立契约束缚：
|
||||
|
||||
1. **媒体元数据双份**：`timeline-build.ts` 构建 clip 时把节点 `durationMs` 复制为 `sourceDurationMs`，构建后节点时长变化不自动同步。
|
||||
2. **字幕双份（快照契约）**：节点 `subtitleEntries` 是实体，字幕 clip `text` 是快照。`syncNodeSubtitlesToTimeline` 已提供「节点 → 时间线」单向同步（`project.tsx` 字幕保存时调用）；「时间线 → 节点」方向**不自动回写**——编辑后由 `editor-subtitle-tools` 提供显式「从节点重建字幕片段」命令，把漂移变成用户可操作的动作，不做双向隐式同步。
|
||||
3. **nodeId 悬空引用**：节点删除/替换后 clip 引用失效。render 层（`buildTimelineRenderPlan` sources 解析）必须区分两种结果：**可降级**（跳过该 clip 并提示）与**不可解析**（报错并定位到具体 clip），禁止静默产出错误渲染。
|
||||
|
||||
契约总原则：**时间线以「快照 + 可重建」持有来自画布的数据，单向显式同步，双向不同步**；画布数据变更不自动改写时间线，避免隐式漂移。与画布内 `canvas-timeline-dialog`（画布级快速组装，单画布、轻量）不同，编辑器是**项目级工作台**（跨画布、命令协议、撤销栈、插件面板）——两者读写同一 `TimelineProject`、同一 `buildTimelineRenderPlan`，形态层级不同、协议同源。
|
||||
|
||||
## 4. 分阶段实施计划
|
||||
|
||||
### M1 插件 SDK v2（前端插件体系演进）
|
||||
|
||||
目标：v1 → v2 类型与注册机制，向后兼容；编辑器域贡献类型与插槽注册表就位。
|
||||
|
||||
任务：
|
||||
|
||||
1. `web/src/lib/plugins/plugin-types.ts`
|
||||
- 新增 `PLUGIN_API_VERSION_V2 = "yingce.plugin/v2"`；`PluginManifest.apiVersion` 允许 v1 | v2。
|
||||
- 新增 editor 贡献类型：`timeline-panel | preview-renderer | export-renderer | transcription-provider | subtitle-tool | inspector-panel | asset-ingest | shortcut-scope`（并入 `PluginContributionKind` 与 `PluginContributions`，v1 插件不声明即为空）。
|
||||
- 新增权限：`timeline.read / timeline.write / timeline.command / transcription.run / export.run`（并入 `PluginPermission` 联合类型）。
|
||||
- 新增预设分发字段：`preset?: boolean`、`defaultEnabled?: boolean`（默认 `preset: false`，v1 清单不设即保持现状）。
|
||||
- 新增 `RegisteredPlugin` 的 editor 工厂入口：`createTimelinePanel? / createPreviewRenderer? / createExportRenderer? / createTranscriptionProvider? / createSubtitleTool?`（与 `createAssetSource` 同构）。
|
||||
2. 新建 `web/src/lib/plugins/editor-slot-registry.ts`：UI 插槽注册表与渲染入口（接口草案见 §5.2），含插槽去重（同一 pluginId+slotId 幂等覆盖）、顺序（`order` 字段）、卸载（`unregisterPlugin` 时同步清理）。
|
||||
3. `web/src/lib/plugins/plugin-registry.ts`：`assertManifest` 按 apiVersion 分支校验；v2 清单允许空 `contributes`（若仅贡献 UI 插槽，插槽在注册时单独校验）；注册/注销时联动 `editor-slot-registry`。
|
||||
4. `web/src/lib/plugins/builtin/index.ts`：保持静态导入，语义化为"预设插件入口"（注释标明）；新增 `builtin/editor/` 子目录。
|
||||
|
||||
产出：v1 插件零改动可运行；`listRegisteredManifests` 可枚举 v2 清单。
|
||||
验证：`cd web && bun run build` 通过；现有 5 个 builtin 插件注册无回归。
|
||||
|
||||
### M2 时间线命令状态机（宿主核心协议）
|
||||
|
||||
目标：时间线唯一修改入口命令化，撤销/echo/保存就位；命令 handler 可插件注册。
|
||||
|
||||
任务：
|
||||
|
||||
1. 新建 `web/src/lib/timeline/editor-commands.ts`
|
||||
- `type EditCommand = { op: string; payload: unknown }`；`type CommandHandler = (state: TimelineProject, payload: unknown) => TimelineProject`（纯函数，禁止依赖组件实例）。
|
||||
- `createEditorCommandRegistry()`：`register(op, handler)`（宿主与插件共用，插件经宿主 API 注册）、`apply(state, cmd)`（未知 op 抛错，fail-closed）、黄金命令集合（`addClip / moveClip / trimClip / splitClip / deleteClip / setVolume / setSpeed / addSubtitle / updateSubtitle / deleteSubtitle / setDirectMedia / ...`，首版以一期/二期能力为准）。
|
||||
2. 新建 `web/src/lib/timeline/editor-history.ts`：有界快照撤销（`undoStack` / `redoStack` 各 200 层，快照只存结构化模型，媒体大对象以 directMedia 引用/存储 key 入快照）；`undo() / redo() / push(state)`；重做栈在 push 时清空。
|
||||
3. 新建 `web/src/lib/timeline/editor-store.ts`：命令单队列（串行 apply）、`dispatch(cmd)` 入口、快照撤销接入、1.5s 防抖保存（localforage user-scope + 后端项目接口；写失败必须上报，不吞错）。
|
||||
4. 手势 echo：在 `editor-store` 提供 `previewGesture(state)` 只读预演（拖拽/裁剪位置），`commitGesture(cmd)` 提交唯一命令；撤销粒度是手势。
|
||||
5. 锁定滤镜图计划：`timeline-to-ffmpeg.ts` 的 `buildTimelineRenderPlan` 标注为协议模块（新增 JSDoc：插件不得绕过）；`timeline-export.ts` 保持降级路径。**render 层按 §3.1 契约处理 `nodeId` 悬空引用**：可降级（跳过 + 提示）与不可解析（报错 + 定位 clip）两条路径，禁止静默错误渲染。
|
||||
|
||||
产出：任意编辑操作可回放为命令序列；撤销/重做可用；插件可注册自定义 op。
|
||||
验证：命令黄金文件测试（§7.1）；既有字幕一期功能经命令层无回归。
|
||||
|
||||
### M3 editor 预设插件（UI 与能力插件化）
|
||||
|
||||
目标：7 个核心预设插件全部以 v2 清单 + 插槽贡献形态实现（AI 助手插件在 M6，见 ADR-0007），宿主核心不再新增编辑器 UI 硬编码分支。
|
||||
|
||||
任务（每个插件 = `builtin/editor/<name>.ts`，`manifest.apiVersion = "yingce.plugin/v2"`，`preset: true`，`defaultEnabled: true`）：
|
||||
|
||||
1. `editor-timeline-panel.ts`：`createTimelinePanel` → 注册 `timeline-panel` 插槽（dock: bottom）；轨道/片段渲染、拖拽移动、裁剪手柄、吸附复用 `timeline-snap`、右键菜单；组件只消费状态机视图并派发命令。
|
||||
2. `editor-preview-monitor.ts`：`createPreviewRenderer` → 注册 `preview-renderer`；`<video>` 裁剪/缩放/透明度/音量 + CSS 滤镜 + canvas 近似合成（ADR-0003 近似层）；交互真相非导出像素。
|
||||
3. `editor-inspector.ts`：`createInspector` → 注册 `inspector-panel`（dock: right）；选中片段属性编辑（起止、音量、变速、字幕文本），全部经命令提交。
|
||||
4. `editor-asset-ingest.ts`：`createAssetIngest` → 注册 `asset-ingest`；素材库/项目资产/本地上传入轨为 directMedia，复用 `@/services/` 文件与媒体层。
|
||||
5. `editor-subtitle-tools.ts`：`createSubtitleTool` → 注册 `subtitle-tool`；SRT 导入导出（`srt-parser` / `srt-resegment`）、AI 高亮（`subtitle-highlight-*`）、批量样式；**「从节点重建字幕片段」命令**（按 §3.1 字幕快照契约：把节点 `subtitleEntries` 显式同步为时间线字幕 clip，替换过期快照）。
|
||||
6. `editor-transcription.ts`：`createTranscriptionProvider` → 注册 `transcription-provider`；提交后端转写任务（§M4 任务协议客户端）、进度/重试 UI、结果写回字幕轨道。
|
||||
7. `editor-export.ts`：`createExportRenderer` → 注册 `export-renderer`；导出面板（分辨率/格式/字幕烧录开关）；默认执行器走后端 ffmpeg 任务，降级走 `exportTimelineToMp4`（wasm）；两者吃同一 `buildTimelineRenderPlan` 计划。
|
||||
|
||||
宿主接线：
|
||||
|
||||
- `detail.tsx`：`DetailView` 联合类型加 `"editor"`，`views` 数组新增「剪辑」项（常驻，与侧边栏「短剧创作」入口一致，不随功能开关过滤）；编辑器视图页壳复用三段式布局（`../design/workspace-shell-design.mdx`），从 `editor-slot-registry` 渲染各插槽。
|
||||
- `application.tsx`：无需新增路由；仅确保编辑器视图页壳挂载后正确初始化 `editor-slot-registry` 渲染；无插槽注册时显示空态（插件被停用时不渲染对应区域）。
|
||||
- 页面壳只做布局与插槽聚合，不含编辑器业务分支。
|
||||
|
||||
产出：编辑器全部 UI 由插件贡献；停用某插件即停用对应区域。
|
||||
验证：浏览器冒烟（§7.4）；每个插件独立可停用/启用。
|
||||
|
||||
### M4 后端任务（转写 + 导出）
|
||||
|
||||
目标：转写与 ffmpeg 导出作为后端任务，复用任务队列与配额；前端协议不变。
|
||||
|
||||
任务：
|
||||
|
||||
1. 任务类型扩展：`backend/internal/model/models_task.go` 增加任务类型 `transcription` 与 `render`（沿用现有任务状态机：pending/running/success/failed/canceled）。
|
||||
2. 新建 `backend/internal/service/transcription/`：ASR provider 接口（`Transcribe(ctx, audioRef, opts) (segments, error)`）+ 两个实现（whisper.cpp 本地、云 ASR 预留）；service 层负责校验归属、配额、任务编排、结果 SRT 落库；SSRF/私网放行遵循 AGENTS.md 第 5 节。
|
||||
3. 新建 `backend/internal/service/render/`：ffmpeg 导出任务，消费前端传来的 `TimelineRenderPlan`（`buildTimelineRenderPlan` 产物，前端序列化上传）；按 plan.steps 执行（trim → gap → concat → subtitle → burn）；产物写入资源存储。
|
||||
4. handler：`/api/timeline/transcription`（提交/查询/取消）、`/api/timeline/render`（提交/查询/取消），响应统一 `{ code, data, msg }`；写路径强校验归属与配额。
|
||||
5. 前端任务客户端：`web/src/services/api/timeline-tasks.ts`（经 `apiClient`，复用 `request<T>`；不新建 axios 实例），`editor-transcription` 与 `editor-export` 插件消费。
|
||||
6. 数据库字段/表变化同步 `docs/content/docs/backend/backend-database.mdx`（AGENTS.md 第 5 节义务）。
|
||||
|
||||
产出：转写/导出为异步任务，浏览器 wasm 仅为无后端降级。
|
||||
验证：后端 `cd backend && go test ./...`；任务冒烟路径（提交→轮询→产物可访问）。
|
||||
|
||||
### M5 权限执行校验与测试收尾
|
||||
|
||||
目标：权限从"声明"变为"执行"；黄金文件与浏览器验证收口；文档同步。
|
||||
|
||||
任务：
|
||||
|
||||
1. 权限执行校验：新建 `web/src/lib/plugins/plugin-permission-check.ts`，宿主 API 调用点（命令入队、转写提交、导出提交、素材读取、外部打开）统一走 `checkPermission(pluginId, permission)`，fail-closed（未声明 → 拒绝并报错；后续按 astravia 语义可扩展 warn+noop / 抛错三档，首版只做 fail-closed）。
|
||||
2. 黄金文件：命令序列黄金文件（§7.1）、渲染计划黄金文件（§7.2）入库为测试夹具。
|
||||
3. 浏览器验证清单执行（§7.4），关键路由/明暗主题/滚动/空态/核心交互逐项记录。
|
||||
4. 文档同步：`docs/content/docs/progress/todo.mdx` 更新待办；已实现未确认项写入 `docs/content/docs/progress/pending-test.mdx`；功能清单 `docs/content/docs/overview/features.mdx` 补编辑器插件化条目。
|
||||
|
||||
产出：无权限插件调用编辑器 API 被拒绝且界面给出明确提示。
|
||||
验证：权限拒绝路径测试（§7.3）；全量构建通过。
|
||||
|
||||
### M6 AI 编辑交互（对话式剪辑，ADR-0007）
|
||||
|
||||
目标：AI 作为时间线一等公民编辑者——自然语言 → 受约束命令 JSON → 命令队列执行，与人编辑共享撤销栈；接入既有模型渠道与画布聊天 UI 模式。
|
||||
|
||||
任务：
|
||||
|
||||
1. 新建 `web/src/lib/timeline/ai-command-schema.ts`：per-op 命令 JSON schema（与 `editor-commands.ts` handler 同源维护），`aiCommandSchemaVersion` 版本化；新增 `timeline-summary.ts`：时间线结构化精简摘要（轨道/片段/时长/关键属性，不含媒体二进制），作为 AI 上下文。
|
||||
2. 新建 `web/src/lib/plugins/builtin/editor/editor-ai-assistant.ts`：预设插件（`ai-assistant` 贡献类型 + `ai.text` / `timeline.read` / `timeline.command` 权限），对话面板插槽（right），复用画布 agent 聊天 UI 交互模式（流式输出/可停止），不移植画布会话协议。
|
||||
3. AI 命令执行链路：LLM 输出 `{ commands, reasoning }` → schema 校验（fail-closed，任一失败整批拒绝并回填错误供 AI 自纠）→ 权限校验 → 入队；≤3 条直接执行，>3 条或涉及删除/整体重排先展示 diff 预览待确认（ADR-0007 执行语义）。
|
||||
4. AI 只读问答：`timeline.read` 分析对话（节奏/剪辑建议），不产生命令；`timeline.command` 未声明时写操作被拒。
|
||||
5. 聚合入口：AI 面板可调起转写（ADR-0004）、AI 字幕高亮（既有 `subtitle-highlight-*`）、AI 素材入轨（生成链路 + asset-ingest），各自协议不变。
|
||||
|
||||
产出：对话式剪辑可用；AI 命令与人命令同撤销栈、同黄金文件测试。
|
||||
验证：AI 命令 schema 校验测试（§7.1 扩展）；浏览器对话冒烟（§7.4 扩展）。
|
||||
|
||||
### M 阶段待定项（画布 / 短剧深化关联）
|
||||
|
||||
不阻塞首版，实现中按需决策：
|
||||
|
||||
1. **章节 → 时间线导航**：画布节点有 `chapterId`（`canvas.ts` metadata），时间线 clip 目前**没有** `chapterId`。若「从分镜入轨」时把章节信息带入 clip（`timeline-build.ts` 扩展），编辑器可提供「按章节查看 / 定位时间线」，直接呼应短剧章节结构。决策点：clip 模型加 `chapterId` 字段 vs 通过 `nodeId` 反查节点章节。
|
||||
2. **成片 → 交付**：当前导出走 `onCreateAssembledNode` 回画布；可顺带把 MP4 落入项目资产 / 交付物，接进 overview「交付与打包」流程（`productionSteps` 末步）。决策点：导出产物写入资产库 vs 独立交付物表。
|
||||
|
||||
## 5. 接口草案
|
||||
|
||||
### 5.1 v2 清单扩展（`plugin-types.ts` 增量）
|
||||
|
||||
```ts
|
||||
export const PLUGIN_API_VERSION_V2 = "yingce.plugin/v2" as const;
|
||||
|
||||
export type EditorContributionKind =
|
||||
| "timeline-panel" | "preview-renderer" | "export-renderer"
|
||||
| "transcription-provider" | "subtitle-tool" | "inspector-panel"
|
||||
| "asset-ingest" | "shortcut-scope";
|
||||
|
||||
export type PluginPermissionV2 =
|
||||
| PluginPermission
|
||||
| "timeline.read" | "timeline.write" | "timeline.command"
|
||||
| "transcription.run" | "export.run";
|
||||
|
||||
// PluginManifest 增量字段（v2 可选）
|
||||
// preset?: boolean // 预设插件（随应用分发，默认启用，不可卸载删改）
|
||||
// defaultEnabled?: boolean // 默认启用（preset 时恒 true）
|
||||
// apiVersion: "yingce.plugin/v1" | "yingce.plugin/v2"
|
||||
```
|
||||
|
||||
### 5.2 UI 插槽注册（新建 `web/src/lib/plugins/editor-slot-registry.ts`）
|
||||
|
||||
```ts
|
||||
export type EditorSlotDock = "bottom" | "right" | "left" | "center" | "fullscreen";
|
||||
|
||||
export type TimelinePanelSlot = {
|
||||
slotId: string; pluginId: string; order: number; dock: EditorSlotDock;
|
||||
component: React.ComponentType<TimelinePanelProps>;
|
||||
};
|
||||
|
||||
export type PreviewRendererSlot = {
|
||||
slotId: string; pluginId: string; order: number;
|
||||
render: (ctx: PreviewRendererContext) => React.ReactNode; // 浏览器原生近似渲染
|
||||
};
|
||||
|
||||
export type ExportRendererSlot = {
|
||||
slotId: string; pluginId: string; order: number;
|
||||
// 消费 buildTimelineRenderPlan 产物；禁止插件内拼第二套滤镜串
|
||||
execute: (plan: TimelineRenderPlan, ctx: ExportContext) => Promise<ExportResult>;
|
||||
fallback?: boolean; // true = wasm 降级执行器
|
||||
};
|
||||
|
||||
export type TranscriptionProviderSlot = {
|
||||
slotId: string; pluginId: string; order: number;
|
||||
submit: (req: TranscriptionRequest, ctx: TranscriptionContext) => Promise<TaskHandle>;
|
||||
};
|
||||
|
||||
export type SubtitleToolSlot = {
|
||||
slotId: string; pluginId: string; order: number; dock: EditorSlotDock;
|
||||
component: React.ComponentType<SubtitleToolProps>;
|
||||
};
|
||||
|
||||
export type InspectorPanelSlot = {
|
||||
slotId: string; pluginId: string; order: number; dock: "right";
|
||||
component: React.ComponentType<InspectorProps>;
|
||||
};
|
||||
|
||||
export type AssetIngestSlot = {
|
||||
slotId: string; pluginId: string; order: number; dock: "left" | "bottom";
|
||||
component: React.ComponentType<AssetIngestProps>;
|
||||
};
|
||||
|
||||
// 注册 / 渲染 / 卸载
|
||||
export function registerTimelinePanel(slot: TimelinePanelSlot): void;
|
||||
export function registerPreviewRenderer(slot: PreviewRendererSlot): void;
|
||||
export function registerExportRenderer(slot: ExportRendererSlot): void;
|
||||
export function registerTranscriptionProvider(slot: TranscriptionProviderSlot): void;
|
||||
export function registerSubtitleTool(slot: SubtitleToolSlot): void;
|
||||
export function registerInspectorPanel(slot: InspectorPanelSlot): void;
|
||||
export function registerAssetIngest(slot: AssetIngestSlot): void;
|
||||
export function unregisterEditorSlots(pluginId: string): void; // unregisterPlugin 联动
|
||||
export function listEditorSlots(): EditorSlotIndex; // 页面壳按 dock 渲染
|
||||
```
|
||||
|
||||
### 5.3 命令协议（新建 `web/src/lib/timeline/editor-commands.ts`）
|
||||
|
||||
```ts
|
||||
export type EditCommand = { op: string; payload: unknown };
|
||||
|
||||
export type CommandHandler = (state: TimelineProject, payload: unknown) => TimelineProject;
|
||||
|
||||
export function createEditorCommandRegistry(): {
|
||||
register: (op: string, handler: CommandHandler) => void; // 插件经宿主 API 调用
|
||||
apply: (state: TimelineProject, cmd: EditCommand) => TimelineProject; // 未知 op 抛错
|
||||
knownOps: () => string[];
|
||||
};
|
||||
|
||||
// 手势 echo（editor-store 内）：previewGesture 只读预演，commitGesture 提交唯一命令
|
||||
```
|
||||
|
||||
### 5.4 预设插件清单（`web/src/lib/plugins/builtin/editor/`）
|
||||
|
||||
| 文件 | 插槽 | 权限 | 依赖的宿主协议 |
|
||||
| --- | --- | --- | --- |
|
||||
| `editor-timeline-panel.ts` | timeline-panel (bottom) | timeline.read / timeline.write / timeline.command | 命令状态机、timeline-snap |
|
||||
| `editor-preview-monitor.ts` | preview-renderer (center) | timeline.read / media.read | 近似渲染、directMedia 解析 |
|
||||
| `editor-inspector.ts` | inspector-panel (right) | timeline.read / timeline.write | 命令状态机 |
|
||||
| `editor-asset-ingest.ts` | asset-ingest (left) | asset.read / asset.search / asset.import / timeline.write | 素材服务、directMedia |
|
||||
| `editor-subtitle-tools.ts` | subtitle-tool (right) | timeline.read / timeline.write / ai.text | srt-parser / srt-resegment / subtitle-highlight-* |
|
||||
| `editor-transcription.ts` | transcription-provider | timeline.read / timeline.write / transcription.run | 后端任务协议（M4） |
|
||||
| `editor-export.ts` | export-renderer | timeline.read / export.run / media.read | buildTimelineRenderPlan、后端 render 任务 / wasm 降级 |
|
||||
| `editor-ai-assistant.ts` | ai-assistant (right) | ai.text / timeline.read / timeline.command | ai-command-schema、timeline-summary、模型渠道、命令队列（ADR-0007） |
|
||||
|
||||
### 5.5 后端任务协议（M4）
|
||||
|
||||
- 提交：`POST /api/timeline/transcription` `{ assetRef | clipRef, provider?, lang? }` → `{ taskId }`；查询 `GET /api/timeline/transcription/:taskId`；取消 `DELETE /api/timeline/transcription/:taskId`。
|
||||
- 提交：`POST /api/timeline/render` `{ plan: TimelineRenderPlan, sources: TimelineRenderSource[], opts? }` → `{ taskId }`；查询/取消同构。
|
||||
- 结果：转写任务返回 SRT（写回字幕轨道）；render 任务返回资源存储 key。
|
||||
- 前端客户端：`web/src/services/api/timeline-tasks.ts`（`apiClient` / `request<T>`，AbortSignal 透传，轮询或 SSE 沿用既有任务约定）。
|
||||
|
||||
## 6. 文件规划
|
||||
|
||||
新建：
|
||||
|
||||
- `web/src/lib/plugins/editor-slot-registry.ts`
|
||||
- `web/src/lib/plugins/plugin-permission-check.ts`
|
||||
- `web/src/lib/timeline/editor-commands.ts`、`editor-history.ts`、`editor-store.ts`、`ai-command-schema.ts`、`timeline-summary.ts`
|
||||
- `web/src/lib/plugins/builtin/editor/editor-timeline-panel.ts`、`editor-preview-monitor.ts`、`editor-inspector.ts`、`editor-asset-ingest.ts`、`editor-subtitle-tools.ts`、`editor-transcription.ts`、`editor-export.ts`、`editor-ai-assistant.ts`、`index.ts`
|
||||
- `web/src/services/api/timeline-tasks.ts`
|
||||
- `backend/internal/service/transcription/`、`backend/internal/service/render/`
|
||||
- 测试：`web/src/lib/timeline/__tests__/editor-commands.test.ts`、`editor-history.test.ts`、`ai-command-schema.test.ts`、`timeline-summary.test.ts`、`render-plan.golden.test.ts`、`web/src/lib/plugins/__tests__/editor-slot-registry.test.ts`、`permission-check.test.ts`；夹具 `web/src/lib/timeline/__fixtures__/commands.golden.json`、`ai-commands.golden.json`、`render-plans.golden.json`
|
||||
|
||||
修改：
|
||||
|
||||
- `web/src/lib/plugins/plugin-types.ts`（v2 类型）、`plugin-registry.ts`（v2 分支 + 插槽联动）、`builtin/index.ts`（editor 预设入口）
|
||||
- `web/src/application.tsx`（编辑器页面壳接线插槽；不新增业务分支）
|
||||
- `backend/internal/model/models_task.go`（任务类型）、`backend/internal/handler/`（transcription/render handler）
|
||||
- `docs/content/docs/backend/backend-database.mdx`（任务表变化）、`docs/content/docs/progress/todo.mdx`、`pending-test.mdx`、`overview/features.mdx`
|
||||
|
||||
## 7. 测试与验证策略
|
||||
|
||||
### 7.1 命令黄金文件
|
||||
|
||||
命令序列 → 期望状态快照的 JSON 夹具（`commands.golden.json`）：新增/移动/裁剪/分割/字幕编辑等命令逐个断言；插件自定义 op 的黄金文件由插件目录自带。回归时 `bun test` 比对夹具，防 reducer 漂移。
|
||||
|
||||
**扩展（M6 / ADR-0007）**：`ai-commands.golden.json` 存 AI 命令序列 → 状态快照；`ai-command-schema.test.ts` 校验合法/非法 payload（fail-closed：单条非法整批拒绝、错误信息回填格式）。AI 命令与人命令共用同一黄金文件体系，防止 schema 与 handler 漂移。
|
||||
|
||||
### 7.2 渲染计划黄金文件
|
||||
|
||||
`buildTimelineRenderPlan` 对代表性时间线（多轨/间隙/字幕/转场降级）输出计划快照；任何新增效果必须更新夹具而非绕过测试——这是"单一滤镜图计划"的机器闸门。
|
||||
|
||||
### 7.3 权限拒绝路径
|
||||
|
||||
单元测试：清单未声明 `timeline.command` 的插件调用命令入队被拒；`transcription.run` 未声明提交转写被拒；界面提示明确（不静默）。
|
||||
|
||||
### 7.4 浏览器冒烟清单
|
||||
|
||||
- 编辑器路由加载：三段式布局渲染，各插槽区域来自插件注册表。
|
||||
- 停用某插件（如 preview-monitor）→ 预览区域空态，其余区域正常。
|
||||
- 拖拽移动/裁剪：echo 预演流畅，release 后命令入队、撤销一次回退手势粒度。
|
||||
- 明暗主题切换、窄屏降级（dock 折叠）。
|
||||
- 转写：提交任务 → 进度 → SRT 写回字幕轨道；导出：后端任务产物可下载；无后端时 wasm 降级可导出。
|
||||
- 快捷键作用域（shortcut-scope 插槽）不与画布快捷键冲突。
|
||||
- AI 对话冒烟：对话面板打开/流式输出/停止；自然语言 → 命令执行 → 撤销回退；非法命令（schema 错/权限不足）整批拒绝并回填错误；批量改动（>3 条）显示 diff 预览待确认。
|
||||
|
||||
### 7.5 验证纪律
|
||||
|
||||
按 AGENTS.md 第 8 节选择最小充分命令并如实记录：前端 `cd web && bun run build`、专项 `bun test ...`；后端 `cd backend && go test ./...`；无法浏览器验证时说明替代依据，不把静态阅读写成运行验证。
|
||||
|
||||
## 8. 风险、依赖与未决问题
|
||||
|
||||
- **v1/v2 并存**：`assertManifest` 双版本分支是首个兼容点；回归范围限现有 5 个 builtin 插件，风险可控。M1 结束前必须跑通全部既有插件注册。
|
||||
- **快照撤销内存**：快照只存结构化模型，directMedia 引用入快照不复制二进制；200 层为上限，超限时丢弃最旧快照（与 ADR-0002 一致）。
|
||||
- **转写模型部署**：whisper.cpp 需要后端机器与模型权重；provider 接口先行、首版可只接 whisper.cpp，云 ASR 为预留接口。模型下载与部署路径在 M4 单独确认（不影响前端协议）。
|
||||
- **插件间耦合**：editor 预设插件只允许依赖宿主协议与共享纯函数库，禁止插件互相 import（评审时检查 import 图）。
|
||||
- **已确认**：路由挂载为**项目内视图**——复用 `/projects/:projectId/:view` 通配（`router.tsx` 第 153 行已存在），`DetailView` 加 `"editor"`，不新增顶层路由、不采用画布内嵌面板；与「分镜制作」「项目画布」同级 tab。
|
||||
- **未决**：预览近似与导出像素的级差表（哪些效果允许差、差多少）在 M3 评审时定稿。
|
||||
|
||||
- **画布 ↔ 时间线引用耦合**：`nodeId` 悬空引用（节点删除）与字幕快照漂移（节点字幕变更不回写）是真实存在的层间耦合。约束见 §3.1：render 层降级/报错二分、字幕单向显式同步；M2/M3 按契约实现。剩余风险是节点删除后用户需手动清理悬空 clip（右键「定位来源/移除」缓解，列入后续迭代）。
|
||||
|
||||
## 9. 交付前检查清单
|
||||
|
||||
- [ ] 改动聚焦：未动 v1 插件与画布/生成链路既有行为。
|
||||
- [ ] 调用方与类型同步：v2 清单、插槽类型、命令协议三处类型一致。
|
||||
- [ ] 错误/权限/数据归属完整：写路径强校验、fail-closed、配额与归属不遗漏。
|
||||
- [ ] 文档同步：ADR、backend-database、todo、pending-test、features 一致。
|
||||
- [ ] 验证如实：黄金文件 + 浏览器冒烟记录在案，未把静态阅读写成运行验证。
|
||||
- [ ] 未留下密钥/本地数据。
|
||||
145
docs/plans/m4-transcription-render-design.md
Normal file
145
docs/plans/m4-transcription-render-design.md
Normal file
@@ -0,0 +1,145 @@
|
||||
# M4 转写与渲染任务设计（增量）
|
||||
|
||||
> 状态：M4.1–M4.3 已实现并提交（执行侧 e9d1b8ad、创建 API bf26ebb1、前端字幕回写 fd5e8139、
|
||||
> 渲染任务 3f16d13b）。本文按实现回写；任何出入以 `backend/internal/service/` 现行代码为准。
|
||||
> 参考锚点：`task_worker.go`、`backend/internal/repository/repository.go`、
|
||||
> `backend/internal/handler/routes.go`（各小节内另行标注实现文件）。
|
||||
|
||||
## 1. 现状边界（调研结论）
|
||||
|
||||
现有模型生成链路对"任务"的约定：
|
||||
|
||||
- `CreateTask`（`task_creation.go`）：draining 检查 → prompt/type 校验 → **模型路由**
|
||||
`resolveTaskModelSelection`（绑定 logical model / revision / route / channel model / billing）→
|
||||
额度与活跃任务配额 → 落库 `queued`。`text_replay` 是唯一旁路（前端自管、不排队）。
|
||||
- worker（`task_worker.go`）：`ClaimNextTask` **不过滤 task type**——任何 `queued` 都会被模型
|
||||
worker 领取；`processClaimedTask` 随后做二次路由、billing `MarkRunning`、provider 执行、
|
||||
`handleSuccess`（billing settle + session/message 落库）。
|
||||
- 结论（实现，修正原草案）：M4 任务**进入同一公共队列**，由唯一 worker 池领取
|
||||
（`ClaimNextTask` 不过滤类型），但在 `processClaimedTask` 顶部按类型分叉到独立执行器，
|
||||
**不经计费与模型渠道路由**（`beginTaskRouteAttempt` / `MarkBillingRunning` /
|
||||
`routeExecutor` / `handleSuccess` 全部跳过）；终态分别走 `SaveTaskCompletion`（成功）/
|
||||
`UpdateTaskTerminalState`（失败）。
|
||||
|
||||
## 2. 架构决策
|
||||
|
||||
1. **新任务类型常量**（放 `backend/internal/model`，与 `TaskStatus*` 并列）：
|
||||
- `TaskTypeTimelineTranscription = "timeline_transcription"`
|
||||
- `TaskTypeTimelineRender = "timeline_render"`
|
||||
两者都不经过 `validateTaskType` 白名单（创建走独立入口）。
|
||||
2. **创建走独立 API 与 service 方法**（不经过 `POST /api/tasks` 的模型路由/计费入口）：
|
||||
- `POST /api/timeline/transcriptions`（M4.1，`CreateTimelineTranscriptionTask`）
|
||||
- `POST /api/timeline/renders`（M4.2，`CreateTimelineRenderTask`）
|
||||
- 两路由**注册在 `RegisterTaskRoutes` 内**（挂载于 `/api` 组），复用任务路由组的
|
||||
鉴权/限流骨架（限流键 `timeline-ts:<userID>` 等），非独立路由组。
|
||||
- 复用现有任务基础设施：同一 `tasks` 表、同一 `TaskStatus` 状态机、租约/取消原语；
|
||||
无 billing/session/message 关联（`BillingOrderID` 为空，收尾走旁路终态）。
|
||||
- 查询与取消**复用现有端点**：`GET /api/tasks/:id`、`POST /api/tasks/:id/cancel`
|
||||
（service 的 `Task()` / `CancelTask()` 均与 task type 无关，已核对）。
|
||||
3. **单一 worker 池，领取不过滤**（实现修正原草案）：`ClaimNextTask` **不加类型过滤**
|
||||
——worker 是 queued 任务的唯一领取方，若按类型排除会使两类新任务无人领取；改为在
|
||||
`processClaimedTask` 顶部按 `task.Type` 分叉（见决策 4）。任务类型常量从 `model` 包引入。
|
||||
4. **`processClaimedTask` 顶部按类型分叉**：在 cancelled 复查之后、stage 覆盖/路由之前，
|
||||
`timeline_transcription` → `processTimelineTranscription(task, ctx)`（`task_timeline.go`）、
|
||||
`timeline_render` → `processTimelineRender(task, ctx)`（`task_render.go`），复用外层已建立的
|
||||
租约续期、`registerActiveTask`（取消即时生效）与超时 context 框架。超时
|
||||
`taskExecutionTimeoutWithPolicy` 分叉：转写 **20 分钟**、渲染 **60 分钟**（草案 30 分钟已改）。
|
||||
5. **旁路终态**：转写/渲染成功不用 `handleSuccess`，`ResultJSON` 落盘后
|
||||
`repo.SaveTaskCompletion(task, running, nil, nil, nil)`（清租约由框架现有 defer 完成）；
|
||||
失败走 `repo.UpdateTaskTerminalState(failed, stage, message, now)` 记可读错误。日志沿用 `s.log`。
|
||||
|
||||
## 3. M4.1 转写任务规格
|
||||
|
||||
### 3.1 输入（`POST /api/timeline/transcriptions` body，路由注册于 `RegisterTaskRoutes`）
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"resourceId": "string", // 必填，音频/视频资源；校验归属且存在
|
||||
"language": "zh", // 可选，默认空 = whisper 自动检测
|
||||
"projectId": "string" // 可选，记录到任务归属字段（ProjectID）
|
||||
}
|
||||
```
|
||||
|
||||
校验顺序（`CreateTimelineTranscriptionTask`）：`IsDraining`(503) → `RequireFeature`
|
||||
（timelineTranscription，默认开）→ `Resource()` 归属读取（失败提示"无法读取待转写媒体，
|
||||
可能已被删除"）→ `isTranscribableMime`（失败提示"仅支持音视频文件转写"）→
|
||||
`RuntimePolicy` → 配额入队（`createTaskWithinStorageQuota`，无 billing order；
|
||||
`repository.ErrActiveTaskLimit` → 可读 400）→ 落库 `queued`
|
||||
（Stage="等待队列调度"、Progress=5、Provider=local、Model=whisper.cpp，
|
||||
`InputJSON = {"resourceId","language"}`）。
|
||||
|
||||
### 3.2 输出 JSON 形状（`ResultJSON`，成功时）
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"segments": [
|
||||
{ "startMs": 0, "endMs": 3200, "text": "字幕文本…" }
|
||||
],
|
||||
"srt": "1\n00:00:00,000 --> 00:00:03,200\n字幕文本…",
|
||||
"language": "zh"
|
||||
}
|
||||
```
|
||||
|
||||
毫秒为整型（`timelineTranscriptionSegment{StartMs,EndMs,Text}`）。前端（M4.3）把
|
||||
`segments` 映射为 `SrtEntry[]`（index = i+1）后直接 `rebuildSubtitleClips` 写入字幕轨道，
|
||||
不做二次解析；`srt` 供导出。
|
||||
|
||||
### 3.3 状态机
|
||||
|
||||
与现有 Task 完全一致：`queued → running(claim) → succeeded | failed | cancelled`；
|
||||
stage/progress 由 `processTimelineTranscription` 内更新：
|
||||
`"等待转写服务"`(progress 15) → `"正在转写…"`(40) → `"整理字幕…"`(80) → succeeded(100)。
|
||||
取消：外层 `registerActiveTask` 的 cancel ctx 令 provider HTTP 调用中断（需在请求中透传
|
||||
`ctx`）。
|
||||
|
||||
### 3.4 转写执行实现（`transcription_whisper.go`，未引入独立 Provider 包）
|
||||
|
||||
- `whisperClient`（`newWhisperClient`）：baseURL 取自环境变量 `CANVAS_WHISPER_BASE_URL`
|
||||
（§3.6 已决：独立 env，非模型渠道）。
|
||||
- `transcribe(ctx, wavPath, language)`：本地 ffmpeg 预处理为 16k 单声道 PCM wav
|
||||
（`prepareWhisperWav`），POST `{baseURL}/inference`，multipart `file` 字段，
|
||||
`response_format=verbose_json`；ctx 随外层任务 context 透传（取消即时生效）。
|
||||
- `decodeWhisperVerboseJSON` → `timelineTranscriptionResult{Segments,SRT,Language}`；
|
||||
`formatSRTTimestamp` / `buildTimelineSRT` 生成 SRT（对齐 `HH:MM:SS,mmm`）。
|
||||
|
||||
### 3.5 任务执行（`task_timeline.go` 内 `processTimelineTranscription`）
|
||||
|
||||
1. 解密 `InputJSON` → 校验 `resourceId`；`Resource()` 读取并做 user scope 归属校验。
|
||||
2. `isTranscribableMime`（audio/video）前置校验；ffmpeg 预处理 16k 单声道 PCM wav。
|
||||
3. 转写（stage/progress：等待转写服务 15 → 正在转写… 40 → 整理字幕… 80 → 完成 100）。
|
||||
4. `ResultJSON` 落盘（3.2 形状）→ `repo.SaveTaskCompletion`；失败走
|
||||
`repo.UpdateTaskTerminalState` 记可读错误（未配置 `CANVAS_WHISPER_BASE_URL` 时
|
||||
明确失败并提示设置）。
|
||||
|
||||
### 3.6 已决项
|
||||
|
||||
- baseURL：**环境变量 `CANVAS_WHISPER_BASE_URL`**（whisper.cpp HTTP，语音数据不出本机）；
|
||||
`.env.example` 已补充。
|
||||
- 语言：`language` 直传 whisper `language=`，空 = 自动检测。
|
||||
- feature gate：`FeatureTimelineTranscription`（availability JSON
|
||||
`timelineTranscriptionEnabled`，默认开；未开时 `RequireFeature` → Forbidden
|
||||
"字幕转写暂未开放"）。
|
||||
- ffmpeg 路径：`CANVAS_FFMPEG_PATH`（可空，空则 PATH 查找；转写/渲染/播放副本共用）。
|
||||
|
||||
## 4. M4.2 渲染任务（已实现：`task_render.go` + `timeline_render_plan.go` + `task_timeline.go` 创建侧）
|
||||
|
||||
- `POST /api/timeline/renders`（注册于 `RegisterTaskRoutes`）：body =
|
||||
`{projectId, timeline}`；timeline 为 v2 快照（tracks/clips 平铺，`renderProject`），片段经
|
||||
`directMedia.storageKey = "resource:"+<id>` 引用后端资源。
|
||||
- 创建（`CreateTimelineRenderTask`）：draining(503) → `buildRenderPlan` 校验 ≥1 个可渲染
|
||||
媒体片段（否则 400 "时间线没有可渲染的媒体片段"）→ 配额入队（Provider=local、
|
||||
Model=ffmpeg、Stage="等待队列调度"、Progress=5）。
|
||||
- 执行（`processTimelineRender`，60 分钟超时）：`buildRenderPlan` 展开合成脚本 → 本地
|
||||
ffmpeg（`CANVAS_FFMPEG_PATH` 或 PATH 查找）→ 产物写资源存储（`storeResource` 路径）→
|
||||
`ResultJSON` = `{"resourceId","fileName","size","durationMs","subtitleSrt"?}`
|
||||
（`subtitleSrt`：时间线含字幕轨时携带导出的 SRT 文本，可空）。
|
||||
- 终态旁路（同 §2 决策 5）；无 billing/session/message 关联。
|
||||
|
||||
## 5. 数据库/文档同步
|
||||
|
||||
- 无 schema 变更（复用 tasks 表）。任务 type 以字符串存储，无须迁移。
|
||||
- `auth.go` 的 API 前缀白名单已加 `timeline`（防 NoRoute 短代理把未匹配的
|
||||
`/api/timeline/*` 当渠道请求）。
|
||||
- 同步更新 `docs/content/docs/progress/pending-test.mdx`（gitignore，仅本地）与
|
||||
Runbook M4 章节的 API 表格（端点/入参/出参），以及权限文档中的 feature gate。
|
||||
本文 §2–§4 已按实现回写，仍以代码为准。
|
||||
Reference in New Issue
Block a user