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 + 测试 + 构建通过，浏览器冒烟待真实文本渠道）。
2026-09-04 14:03:33 +08:00
parent 33c589fd8e
commit 05d1bce876
106 changed files with 10857 additions and 119 deletions
--- a/docs/plans/editor-implementation-runbook.md
+++ b/docs/plans/editor-implementation-runbook.md
@@ -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），再切换路径。
--- a/docs/plans/editor-preset-plugin-implementation.md
+++ b/docs/plans/editor-preset-plugin-implementation.md
@@ -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 一致。
+- [ ] 验证如实：黄金文件 + 浏览器冒烟记录在案，未把静态阅读写成运行验证。
+- [ ] 未留下密钥/本地数据。
--- a/docs/plans/m4-transcription-render-design.md
+++ b/docs/plans/m4-transcription-render-design.md
@@ -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 已按实现回写，仍以代码为准。