ttstd-infinite-canvas/docs/plans/editor-implementation-runbook.md

编辑器实施 Runbook（分步执行计划）

配套文档：编辑器预设插件化实施规格（目标架构与接口）与 ADR-0001 ~ 0007（决策）。本文件只解决一个问题：按什么顺序、以什么粒度动手，让每一步都可验证、可回退、看得见进度。

状态：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），再切换路径。