feat(*): 短剧创作工作台 - 完善章节分镜、资产管理、技能运行与生成任务恢复

docs/content/docs/backend/backend-database.mdx

@@ -7,10 +7,23 @@ description: 影策后端核心持久化表与状态边界
 
 后端通过 GORM 管理 SQLite 与 PostgreSQL 表结构。服务启动时由 `backend/internal/database/schema.go` 执行迁移；业务写路径必须通过 service 和 repository 的状态约束，不能直接依赖前端状态。
 
+## 技能包与版本
+
+| 表 | 用途 | 关键边界 |
+| --- | --- | --- |
+| `skills` | 保存技能公开元数据、当前版本指针、来源和 GitHub 同步状态 | `instruction` 仅保留入口 `SKILL.md` 的兼容投影；目录文件不展开写入该字段 |
+| `skill_versions` | 保存每次安装、编辑或同步形成的不可变技能版本 | 记录内容哈希、入口路径、规范化 ZIP 的存储键、文件数、总大小和 GitHub commit |
+| `skill_files` | 保存某个版本的文件索引 | `(skill_version_id, path)` 唯一；只保存路径、类型、MIME、大小和 SHA-256，不保存正文 |
+| `user_skill_states` | 保存用户的加入、收藏、安装版本和自动更新选择 | 技能正文读取仍经过公开性和归属校验，不能通过文件接口绕过私有技能权限 |
+
+规范化技能包保存在后端数据目录的 `skill-packages/<skill-id>/<version-id>.zip`，数据库只保存索引和版本指针。上传 ZIP 时强制校验 `SKILL.md`、路径越界、软链接、重复路径、文件数量和解压大小；GitHub 技能保存公开仓库、分支、子目录和提交 SHA，后台每 6 小时检查一次开启自动更新的技能，并记录最近检查、同步时间及失败状态。
+
 ## 短剧分镜生产
 
 | 表 | 用途 | 关键边界 |
 | --- | --- | --- |
+| `projects` | 保存短剧项目基础设置、画幅、画风快照和项目主图 | `cover_resource_id` 只能引用当前用户已就绪的图片资源；资源删除检查会阻止仍被项目主图使用的图片被回收 |
+| `project_units` | 保存项目章节或集数的正文、排序和状态 | `word_count` 在正文创建、导入和更新时同步维护，项目详情只返回摘要和字数，不批量返回长篇正文；升级时会为旧正文回填字数 |
 | `shots` | 保存章节内稳定的镜头身份、排序和当前版本指针 | 不保存完整生成历史；`current_revision_id` 指向当前采用的分镜脚本版本 |
 | `shot_revisions` | 保存画面、动作、台词、景别、机位、运镜、提示词和动作节拍 | 每次编辑创建新版本；历史版本不可被静默覆盖 |
 | `shot_asset_references` | 将镜头绑定到具体资产版本 | 修改引用时只使该镜头的下游产物过期，不影响其他镜头 |

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

@@ -5,17 +5,48 @@ description: 影策已实现功能的手工验证清单与未确认边界
 
 # 待测试
 
+## 多文件技能包库
+
+- [x] 后端新增技能版本与文件索引，支持单个 Markdown、ZIP 和公开 GitHub 仓库安装；ZIP 路径越界、软链接、重复路径、文件数、单文件大小和总解压大小均在写入前校验，后端全量测试通过。
+- [x] 技能详情改为约 82vw × 82vh 的弹窗，左侧支持多层文件树，右侧支持 Markdown 预览、源码、代码/文本及媒体文件查看；前端生产构建通过。
+- [x] 在线 Agent 只在系统上下文保留技能元数据，并通过入口、文件清单、单文件读取和搜索工具渐进式加载；本机 Agent 只把用户本轮显式提及的完整技能包写入临时目录，321 项 Agent 测试与 TypeScript 构建通过。
+- [x] 新增统一 Skill Runtime：画布、创作页和短剧工作台共用同一技能选择、引用解析、版本/文件来源记录与上下文预算；普通生成只加载 `SKILL.md` 和入口直接引用的相关文本，在线 Agent 使用渐进工具，本机 Agent 使用原生完整包，专项测试与前端类型检查通过。
+- [ ] 分别安装无 Frontmatter 的单个 Markdown、两个用户提供的示例 ZIP，确认名称/简介推断、文件树层级、中文路径、预览/源码切换和相对 Markdown 链接正确。
+- [ ] 使用公开 GitHub 仓库的默认分支、指定分支和子目录安装技能，修改仓库后手动同步并等待一次后台检查，确认 commit、版本、检查时间、同步时间和失败信息准确。
+- [ ] 在浅色、深色、常规桌面、窄屏下检查大弹窗尺寸、双栏滚动、文件筛选、长路径、省略文本、键盘焦点和媒体预览；确认弹窗不会触发画布缩放或快捷键。
+- [ ] 在线 Agent 使用示例技能完成一次任务，确认先读 `SKILL.md`，仅在入口引用时读取对应 reference；本机 Agent 确认 scripts/assets 保持目录结构、turn 完成后临时目录被清理，且聊天历史不出现完整技能正文。
+- [ ] 分别在画布图片/视频/文本生成、创作页文本/图片/视频、短剧分镜图/动作预演/镜头视频中选择示例技能，确认任务只记录本轮技能版本和实际读取文件，不重复注入历史消息，也不加载 `scripts/`、`assets/` 或整个技能包。
+- [x] 画布、创作页和 Agent 共用的 `@` 引用菜单改为真实光标定位，输入框或页面滚动、尺寸变化时同步更新；向上弹出按实际内容高度贴边。技能候选改为工作流图标、名称、说明、版本和文件数的统一信息行，专项测试和前端生产构建通过。
+- [ ] 登录后分别在高输入框首行、末行、滚动后的中间行输入 `@`，确认菜单与光标保持约 8px 间距；在浅色/深色及窄屏下确认技能说明、版本、文件数和键盘选中态清晰可读。
+
 ## 短剧分镜工作流 v2
 
 - [x] 后端新增镜头版本、镜头产物和生产任务上下文；分镜修改与资产版本变更会局部将旧产物标记为 `stale`，专项测试通过。
 - [x] 短剧工作流调整为“剧情与章节 → 资产拆分 → 分镜脚本 → 黑白动作预演 → 视频生成 → 交付与打包”，旧 v1 实例保留，新章节使用 v2。
 - [x] 项目工作台新增独立分镜工作流路由，支持初始化章节流程、新增镜头、保存分镜版本、绑定资产版本、查看预演/视频版本和交付缺失状态；前端生产构建通过。
+- [x] 镜头轨道按当前制作阶段显示待生成、生成中、已生成和生成失败状态，状态标签固定在卡片右下角；横向镜头只在轨道内部滚动，不再撑宽脚本区或挤出产物预览。制作概览六个流程节点改为独立可点击卡片；前端类型检查、生产构建与相关专项测试通过。
 - [ ] 在真实项目中初始化一个已有章节，确认不会误用旧 v1 工作流，刷新和切换章节后阶段、镜头和当前版本保持一致。
+- [ ] 在同一章节准备待生成、生成中、已生成和生成失败镜头，确认灰、蓝、绿、红标签始终显示在卡片右下角；增加到几十个镜头后确认只有底部轨道横向滚动，中间脚本和右侧产物预览仍完整可见。
+- [ ] 在浅色、深色、常规桌面和窄屏下检查制作概览六张流程卡片的边界、间距、完成态、悬停和键盘焦点，确认跳转目标正确。
 - [ ] 连续保存同一镜头多个版本并绑定不同资产版本，确认只有该镜头的动作预演和视频转为过期，其他镜头不受影响。
 - [ ] 使用画布任务和项目任务分别登记镜头产物，确认 `production_task_links` 正确记录 Project、Canvas、Unit、Shot 和 WorkflowStep，且账号归属校验有效。
 - [ ] 在浅色、深色、窄屏和常规桌面验证阶段导航、镜头列表、表单、检查器、媒体预览和长章节内容滚动。
 - [ ] 当前“资产拆分 AI、多宫格生成提交、批量视频任务、后端交付包”仍是后续阶段，界面不得显示为已完成或可用。
 
+## 角色声音素材绑定
+
+- [x] 角色卡声音绑定移除无效的预设声音下拉框，改为从素材库选择或实时上传声音样本；支持 MP3、WAV、M4A/AAC、FLAC、OGG/Opus 和 WebM 音频。前后端共同校验资源归属、完成状态、资源类型和格式白名单，画布生成引用会保留资源真实 MIME 与文件扩展名。
+- [ ] 在角色卡分别选择素材库已有音频并上传 MP3、WAV、M4A/AAC、FLAC、OGG/Opus、WebM 样本，确认选择器格式标签、浏览器试听、绑定、版本历史和刷新后的声音状态一致；再验证不支持格式、伪装扩展名、视频 WebM、未完成资源和其他账号资源均被拒绝。
+- [ ] 使用绑定了不同格式声音样本的角色执行画布生成，确认请求中的参考音频使用资源真实 MIME 和对应文件扩展名，不再统一伪装成 MP3；生成成功、失败及刷新恢复后引用关系不丢失。
+
+## 短剧章节后台生成与项目头部
+
+- [x] “提取角色”和“生成到分镜制作”继续使用后端任务中心，确认配置后立即关闭弹窗；章节按钮按任务真实开始时间每秒显示“已运行 X分钟XX秒”，任务完成后恢复可点击并显示“已生成”。刷新页面后会按章节从任务中心恢复运行计时和完成态，并接管尚未写回的角色或分镜结果。
+- [x] 项目名称、状态、六个项目导航、章节选择和新建画布操作已注册到全局公用头部，项目内容区不再重复占用一整行头部；相关专项测试、TypeScript 检查与前端生产构建通过。
+- [ ] 在真实慢任务中分别启动角色提取和章节分镜，确认弹窗立即关闭、按钮计时连续增长、可编辑正文和切换章节，完成后按钮显示“已生成”且仍可再次运行。
+- [ ] 在任务运行中和任务刚完成尚未写回结果时分别刷新项目，确认对应章节继续显示累计计时或“已生成”，成功结果会自动写回；再检查无新角色、生成失败和重新生成替换确认场景的按钮恢复、错误提示和旧分镜保护。
+- [ ] 在浅色、深色、常规桌面和窄屏下检查全局头部：项目名、状态、项目导航、右侧全局操作和新建画布/章节选择不重叠，导航可横向滚动，内容区高度确实增加。
+
 ## 画布生成结果命名
 
 - [x] 快捷键复制节点生成图片后保留 `_copyN`，参数变体生成图片后保留 `A/B/C/D` 版本标识；批量输出追加结果序号。
@@ -23,6 +54,14 @@ description: 影策已实现功能的手工验证清单与未确认边界
 - [ ] 分别使用快捷键复制和“创建参数变体”生成图片，确认生成中、生成完成和刷新画布后标题标识不丢失。
 - [ ] 下载原图、复制结果、多个参数变体和同批多图结果，确认浏览器不会再提示同名文件覆盖。
 
+## 画布生成进度与全屏视频控件
+
+- [x] 移除图片、视频任务进入模型调用时统一写入的假 35%；排队、后端接管和连接上游阶段只显示真实阶段文案，不再显示伪造百分比。
+- [x] 后端从图片、视频上游成功的创建与轮询响应中识别 `progress`、`percent`、`percentage`、`completion` 及常见百分比变体，支持数字、百分数字符串和 0~1 小数；进度单调写回任务，前端既有 2 秒轮询会同步到画布节点。
+- [x] 画布视频节点保留紧凑控件；进入全屏后恢复完整顶部控制组，底部按钮调整为 52px 操作目标，同时放大图标、时间文字、进度轨道和拖动滑块。
+- [ ] 分别使用会返回整数百分比、小数进度、百分数字符串和不返回进度的图片/视频渠道生成，确认前三者按上游实时增长，不返回进度的渠道仅显示阶段文案且不会卡在固定百分比；刷新页面后继续从后端任务恢复最新进度。
+- [ ] 在桌面、窄屏和触屏设备全屏播放横版、竖版视频，确认播放/暂停、音量、时间、画中画、设置、全屏退出和进度拖动尺寸清晰且不会遮挡字幕。
+
 ## 视频画面与片段提取
 
 - [x] 视频节点“尾帧截取”已合并为“提取画面”，支持首帧、当前帧、尾帧和最多 30 个自选时间点；批量结果保留来源节点与时间点元数据。
@@ -468,7 +507,41 @@ description: 影策已实现功能的手工验证清单与未确认边界
 - [x] 镜头编辑器改为脚本优先顺序：镜头名称与画面、镜头资产、表演与动作、对白/旁白优先展示，生成规格和模型补充保持折叠；字段统一为画幅、镜头时长、机位角度、运镜方式、排除内容和接戏备注等生产术语。
 - [x] 编辑器标题实时反映镜头名称与“已保存/有未保存修改/保存中”状态；无修改时禁止重复保存，切换或新增镜头前会拦截未保存修改。浏览器交互验证通过。
 - [x] 镜头保存使用真实版本写接口；资产点击绑定具体版本；生成统一进入后端任务生命周期，成功后登记对应镜头产物；下载使用带登录凭据的资源接口。
+- [x] “生成设置”新增技能库多选，分镜图、动作预演和镜头视频统一通过 Skill Runtime 解析，任务与镜头产物记录技能版本和实际引用文件。
+- [x] 镜头资产支持再次点击或从已绑定标签取消引用；解绑使用归属校验的独立写接口，并使该镜头旧产物失效。动态提示词复用画布 `@` 引用编辑器，已绑定图片和角色会按实际参考图顺序解析后提交；后端全量测试、前端专项测试和生产构建通过。
+- [x] 镜头编辑器底部在“保存脚本”左侧新增“删除镜头”；二次确认后原子清理该镜头的脚本版本、资产引用、生成产物、候选资产和生产任务关联，压紧剩余镜头顺序并自动切换到相邻镜头。
 - [ ] 使用包含角色、场景、道具和画风的真实项目，确认左侧分类、绑定状态、参考素材标签和镜头切换保持一致。
+- [ ] 分别删除首个、中间、末尾和唯一镜头，确认二次提示、相邻镜头切换、空态、镜头编号、总镜数以及刷新后的数据一致；有未保存修改时确认提示明确且取消不会丢失内容。
+- [ ] 在同一镜头绑定角色和场景后输入 `@`，确认菜单、行内缩略图和生成请求中的“图片 N”顺序一致；分别从左侧资产行和已绑定标签取消引用，确认刷新后状态一致，旧 token 会阻止生成并提示重新选择或删除引用。
 - [ ] 配置一个图片模型和一个视频模型，分别生成分镜预览、动作预演与视频，确认任务中心、镜头历史、最新预览和阶段状态同步更新。
 - [ ] 在浅色/深色主题及 1280px、1050px、760px 三个断点检查项目导航、表单滚动、右侧预览和底部镜头轨道，确认没有遮挡或不可达控件。
 - [ ] 验证下载视频、复制生成参数、将任务物化产物加入项目素材库、章节切换与新增分镜；确认失败任务展示真实错误且不会伪造产物成功。
+
+## 章节分镜生成到分镜制作
+
+剧情章节的分镜入口已从“在画布中分镜”纠正为“生成到分镜制作”；生成结果直接写入镜头脚本，并在本章已有分镜时执行显式替换确认。以下场景仍需使用真实项目与已安装技能确认：
+
+- [x] 章节正文、项目画风、当前角色版本和项目资产统一进入 `agent_storyboard_rows` 任务；分镜生成继续经过 `Skill Runtime` 的 `shortDrama` profile，并记录实际技能版本和引用文件。
+- [x] 本章待确认角色也会进入分镜上下文；模型在 `characterIds` 中返回角色名称时，已确认角色自动映射到真实资产版本，待确认或未知角色降级为仅名称引用，不再触发结构修复请求或报废整份分镜。后端专项测试、前端映射测试与生产构建通过。
+- [x] 分镜任务结果映射到镜头画面、动作、对白、景别、机位、运镜、图片/动态提示词与接戏备注；模型返回的项目资产关联随镜头在同一替换事务中保存。
+- [x] 本章无分镜时直接写入“分镜制作”并跳转到分镜图阶段；已有分镜时展示镜头、脚本版本、资产引用、生成产物和候选资产影响数量，生成失败不修改旧数据。
+- [x] 技能多选框占满弹窗内容宽度；专项测试、TypeScript 检查、后端服务测试和前端生产构建通过。
+- [ ] 选择 1 至 4 个已安装技能生成真实章节，确认任务中心中的技能版本、文件来源和生成结果一致，完成后进入对应章节的“分镜制作 / 分镜图”。
+- [ ] 使用已提取但尚未确认资产的“张振天、张天昊”重新生成真实章节，确认镜头正常落库、提示词保留角色名称；确认角色资产后再次生成，确认同名角色自动带上真实资产与版本 ID。
+- [ ] 对已有镜头、历史脚本、资产引用和生成产物的章节重新生成，分别验证取消替换、模型生成失败和确认替换：前两者保留旧数据，确认替换后旧关联被移除且新资产引用可用。
+- [ ] 在 560px 及更窄视口打开设置弹窗和技能下拉框，确认选择器、选项面板、长技能名称和替换警告没有横向溢出。
+
+## 短剧项目导航与制作概览
+
+项目设置、章节导航、制作概览、镜头轨道和画布新增入口已按长篇短剧工作流重构；以下场景仍需使用登录态真实项目确认：
+
+- [x] 项目新增 `cover_resource_id`，服务端校验资源归属、就绪状态和图片类型；项目主图被资源删除流程识别为直接引用。章节新增持久化 `word_count`，新建、导入、更新和旧数据迁移均维护字数摘要；后端全量测试通过。
+- [x] 项目设置可从个人图片素材、项目图片素材或实时上传中设置主图；项目列表优先显示主图，未设置时回退画风示意图。分镜制作头部改为上一章、搜索定位、下一章的虚拟章节导航；前端生产构建通过。
+- [x] 修复项目更新仓储遗漏 `cover_resource_id`，避免接口返回“主图已更新”但数据库字段仍为空；回归测试同时校验设置与移除主图后的数据库重读结果，后端全量测试通过。
+- [x] 剧情章节列表去除装饰性侧边表达并显示状态、字数、画布数；制作概览新增六阶段标准流程、当前指标、制作缺口和可点击快速入口；底部镜头卡增加画面、加粗时长、镜头参数、产物版本与绿色成功状态。
+- [x] 画布空白区域双击改为直接打开已有新增节点面板，并保留双击位置作为节点落点；原“适配内容”能力继续由缩放控制区提供。
+- [ ] 在项目设置分别从个人素材、项目素材和上传图片设置主图，刷新项目列表后确认图片一致；替换、移除主图后确认回退逻辑正确，尝试删除当前主图资源时确认显示项目引用来源。
+- [ ] 使用 2500 章项目搜索章节序号和标题，连续切换上一章、下一章并刷新页面，确认当前位置、总章数、字数和路由一致，弹窗滚动流畅且不会一次渲染全部章节。
+- [ ] 在制作概览点击剧情、资产、分镜、预演、视频、交付和三个快速入口，确认跳转到正确章节及阶段，真实镜头产物数量与完成状态一致。
+- [ ] 在浅色、深色主题和 1280px、1680px 宽度检查镜头卡，确认时长明显、标题与镜头参数不溢出、“已生成”为绿色且选中态仍使用工作台强调色。
+- [ ] 在画布不同缩放和平移位置双击空白处，确认新增节点面板直接打开，选择文本、图片、视频和扩展节点后落点接近双击位置；双击节点、弹窗和其他浮层不应触发新增。