Merge remote-tracking branch 'origin/main'

docs/content/docs/backend/local-development.mdx

@@ -56,6 +56,55 @@ bun run dev
 
 前端默认监听 `0.0.0.0:3000`，Vite 将 `/api` 和 OAuth 回调代理到 `127.0.0.1:8080`。如需修改代理目标，可设置 `VITE_API_PROXY_TARGET`。
 
+## 时间线字幕转写（whisper.cpp）
+
+时间线“字幕转写”由**本地 whisper.cpp server** 执行：后端将片段音频预处理为 16k mono wav 后，POST 到 `CANVAS_WHISPER_BASE_URL/inference`（whisper server 原生接口，`response_format=verbose_json`）。未配置该地址时，转写任务会立即明确失败，提示“撰写失败未配置本地转写服务”。
+
+### 安装 whisper-server
+
+```bash
+brew install whisper-cpp
+```
+
+### 下载模型
+
+仓库脚本将模型放在 `.local/whisper-models/`（已被 `.gitignore` 忽略）。多语言模型（含中文）用 `ggml-base.bin`（约 141MB）；网络受限时可用 aifasthub 镜像：
+
+```bash
+mkdir -p .local/whisper-models
+curl -fL -o .local/whisper-models/ggml-base.bin \
+  https://aifasthub.com/ggerganov/whisper.cpp/resolve/main/ggml-base.bin
+```
+
+### 启动服务
+
+```bash
+scripts/start-whisper-local.sh
+```
+
+脚本默认以 `ggml-base.bin` 监听 `127.0.0.1:8082`（`-l auto` 自动识别语言）。需要换模型或端口时：`WHISPER_MODEL=ggml-small.bin WHISPER_PORT=8083 scripts/start-whisper-local.sh`。
+
+### 让后端指向该服务
+
+后端不读取 `.env` 文件，环境变量必须由启动 shell 注入（在手工启动命令基础上追加）：
+
+```bash
+cd backend
+CANVAS_BACKEND_DATA_DIR=../.local/project-workbench-debug \
+CANVAS_WHISPER_BASE_URL=http://127.0.0.1:8082 \
+go run ./cmd/server
+```
+
+### 验证
+
+```bash
+# 服务就绪：返回 200/404 即可
+curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8082/
+# 冒烟：20 秒语音 → verbose_json 字幕段
+curl -s -X POST http://127.0.0.1:8082/inference \
+  -F 'file=@sample.wav' -F 'response_format=verbose_json'
+```
+
 ## Docker 开发
 
 需要容器化热更新时，在仓库根目录执行：

docs/content/docs/overview/features.mdx

@@ -159,3 +159,39 @@ SEO 标题、描述、可选关键词会投影到浏览器 metadata、Open Graph
 - `web/src/components/canvas/canvas-zoom-controls.tsx`：底部视图控制 Dock 与“自动整理节点”入口。
 - `web/src/pages/canvas/use-canvas-node-operations.ts`：候选节点筛选、流程/网格布局选择和位置提交。
 - `web/src/lib/canvas/canvas-layout.ts`：媒体泳道、拓扑流程、网格、行列排列和对齐算法。
+
+## 剪辑成片（时间线编辑器）
+
+“剪辑成片”是项目详情里的时间线编辑器入口（`/projects/:id/editor`），用于把已就绪的分镜视频编排成一段可播放、可导出的成片。它运行在浏览器本地时间线模型之上，通过后端任务队列完成语音转写与成片导出，编辑器本身不直接触碰原始媒体大文件。
+
+### 使用入口
+
+- 项目详情“制作流程 → 剪辑成片”步骤卡，或地址栏直接访问 `/projects/:id/editor`。
+- 编辑器按项目隔离时间线状态；离开后再次进入会恢复该项目的编辑器快照。
+
+### 当前能力
+
+- **轨道与命令**：时间线支持添加、删除、拆分、移动、修剪片段等操作，全部通过统一命令状态机执行并进入 200 层历史记录，可撤销与重做；非法操作整批拒绝，不产生半应用状态。
+- **预设面板**：左侧“添加”分类提供 8 个内置片段/字幕插件，按分类分组接入同一插槽注册链，第三方插件可与内置面板共存。
+- **权限与执行边界**：命令执行遵循失败关闭（fail-closed）策略，`timeline.command` 权限与全局 `plugins.run` 权限分开控制；未授权插件或命令不会被执行或回显。
+- **语音转写（字幕）**：对时间线音视频发起转写任务，转写进度沿任务 SSE 回流，完成后生成字幕轨。
+- **成片导出（渲染）**：发起渲染任务，由服务端 ffmpeg 按渲染计划输出成片；渲染成功后在项目概览的“剪辑成片”步骤卡呈现“已输出 N 个成片”，并作为该步骤完成度的判定依据。
+- **AI 编辑助手**：可以用自然语言描述剪辑意图，系统将其解析为受支持的命令序列；不超过 3 条命令时直接执行，多于 3 条先给出差异预览，确认后才批量执行。
+
+### 运行环境要求
+
+- 语音转写依赖本地 whisper.cpp 服务（`CANVAS_WHISPER_BASE_URL`），未配置时转写任务明确失败。
+- 成片导出依赖服务端 ffmpeg（`CANVAS_FFMPEG_PATH`，留空时在 PATH 中查找）。
+- AI 编辑助手需要可用的文本模型渠道。
+
+### 相关实现
+
+- `web/src/pages/projects/detail/editor.tsx`、`web/src/pages/projects/detail.tsx`：编辑器页面与路由入口。
+- `web/src/pages/projects/detail/overview.tsx`：制作流程步骤卡与成片完成度展示。
+- `web/src/lib/timeline/`：时间线命令状态机、历史记录、命令 schema 与摘要（`editor-commands.ts`、`editor-history.ts`、`ai-command-schema.ts`、`timeline-summary.ts`）。
+- `web/src/stores/editor/editor-store.ts`：编辑器状态与快照持久化。
+- `web/src/lib/plugins/editor-slot-registry.ts`、`web/src/lib/plugins/builtin/editor/`：插槽注册链与内置预设插件。
+- `web/src/lib/plugins/plugin-permission-check.ts`：命令执行权限与失败关闭策略。
+- `web/src/services/api/timeline-tasks.ts`：转写与渲染任务客户端。
+- `backend/internal/service/task_timeline.go`、`task_render.go`、`timeline_render_plan.go`、`transcription_whisper.go`：后端转写、渲染与渲染计划任务。
+- `backend/internal/repository/project_workbench_read.go`：项目概览指标聚合（含成片完成度计数）。

docs/content/docs/progress/pending-test.mdx

@@ -43,7 +43,8 @@ description: 当前项目已实现功能的手工验证清单与未确认边界
 - [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.1 运行时端到端（2026-09-04，真实 whisper.cpp）：`brew install whisper-cpp` + `ggml-base.bin`，whisper-server `127.0.0.1:8082`（`-l auto`）；后端注入 `CANVAS_WHISPER_BASE_URL=http://127.0.0.1:8082` 重启；真实 mp4 资源经 worker 队列（status=queued → running → succeeded 100%）跑通：ffmpeg 16k mono 提取 → `/inference` verbose_json → 中文分段含 start/end/text 入库，与 `transcription_whisper.go` 解码协议一致。失败路径（未配置）此前 5 条任务均按设计报“撰写失败未配置本地转写服务”。启动步骤已写入 `local-development.mdx`，脚本 `scripts/start-whisper-local.sh`。
+- [ ] 浏览器端到端（待用户确认；本机 whisper-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`。
@@ -62,6 +63,8 @@ description: 当前项目已实现功能的手工验证清单与未确认边界
 - [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] 概览成片完成度接线：项目概览指标新增 `renderSucceededCount`（repository 聚合 SQL 子查询 `tasks` 表 `type=timeline_render` 且成功的计数），概览「剪辑成片」步骤卡的 complete 态由写死的 false 改为 `renderSucceededCount > 0`，提示文案随计数/就绪情况切换；新增后端专项测试 1 个、前端类型检查通过。
+- [ ] 用户浏览器 re-test（概览完成度）：渲染成功一次后刷新概览，「剪辑成片」卡应显示已输出 N 个成片且步骤完成态点亮；删除该成片对应任务后计数回退。
 - [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`）。
@@ -323,6 +326,11 @@ description: 当前项目已实现功能的手工验证清单与未确认边界
 - [x] 在桌面浏览器验证上方“参考内容”打开素材选择、折叠堆叠态中间卡片删除、展开态任意卡片删除、筛选、拖动排序和收起。
 - [ ] 在真实登录数据下验证“清空全部素材”同步移除全部附件引用，不影响技能引用和素材库原始文件。
 - [ ] 在触屏及窄窗口验证删除按钮无需悬停也可见，素材轨道可横向浏览且不会遮挡提示词和底部控制区。
+- [ ] 在创作首页选择图片或视频生成并修改画幅、质量、时长或生成数量后切换到其他工作区再返回，确认上次的创作类型和各自参数仍保留；切换到不支持某个已保存参数的模型时，确认该参数仅回退为当前模型默认值；生成结果点击“添加到画布”后确认仍能按现有交接流程进入画布。
+
+## 首页生成图片预览交互
+
+- [ ] 在生成结果、参考图片和故事板图片预览中使用鼠标滚轮放大/缩小，确认缩放以鼠标位置为中心；放大后按住鼠标左键拖动查看局部，缩回原尺寸后确认画面回到居中状态。
 
 ## Agnes Video 2.5 JSON 协议
 
@@ -859,3 +867,12 @@ description: 当前项目已实现功能的手工验证清单与未确认边界
 - [ ] 拖入时长 >5s 的视频片段，其时间线长度等于视频真实时长（不再固定 5s 截断）；时长探测上传的新素材在资源卡片/片段均显示真实时长。
 - [ ] 播放副本就绪前（processing）视频黑屏时出现"正在生成兼容版本（H.264）…"浮层 + "下载原片用本地播放器观看"链接；生成失败显示失败文案而非一直转圈。
 - [ ] 时间线 scrub/播放/变速往返 10 次以上无卡死、无播放头回跳、无 setState-after-unmount 报错（Console 无告警）。
+
+## MPEG-4 Part 2 播放死循环 + 画布产物素材同步（待浏览器验收）
+
+已实施，代码/单测/编译验证通过（后端 go vet/test、前端 tsc 全绿），需浏览器最终确认：
+
+- [ ] 导入 MPEG-4 Part 2(mp4v)视频(如 07ee…mp4 sprite/header damaged 样例)后拖入时间线：不再出现"正在生成兼容版本"提示闪烁死循环；损坏文件转码失败后显示终止性文案(不再反复回退重试)；正常 mp4v 文件自动生成 H.264 副本并可播放。
+- [ ] 打开剪辑器进入已含画布产物(selected+ready 的 storyboard/action_board/分镜/导出成片)的项目：素材面板自动出现"画布素材"分组与对应素材；再次进入/刷新不产生重复素材。
+- [ ] 素材面板"画布素材/本地上传/项目素材"三个页签与分组切换、来源徽章与详情来源文本正确。
+- [ ] 项目素材库页与剪辑器素材面板对本轮新同步的画布素材均可见；下载/删除画布素材不影响对应画布产物资源。

docs/index.md

@@ -45,6 +45,6 @@
 - [功能](content/docs/overview/features.mdx)
 - [本地开发](content/docs/backend/local-development.mdx)
 - [后端数据库](content/docs/backend/backend-database.mdx)
-- 代码地图：待补充
-- 待办：待补充
+- [代码地图](content/docs/backend/code-map.mdx)
+- [待办](content/docs/progress/todo.mdx)
 - [待测试](content/docs/progress/pending-test.mdx)