Short Drama Agent Front

短剧 Agent 的前端工作台。支持剧本创作、拆解、视觉风格、角色选角、主体形态、分镜设计、镜头首帧与视频生产，使用真实后端 API，不包含演示数据或浏览器端模型调用。

启动

需要 Node.js >= 22.18 和 pnpm 11。

pnpm install
cp .env.example .env
pnpm dev

浏览器访问 http://localhost:5173。先在后端仓库启动 pnpm dev，默认监听 3412。

VITE_API_BASE_URL=/api
API_PROXY_TARGET=http://localhost:3412

更改环境变量后重启 Vite。后端若运行在其他机器或端口，请修改 API_PROXY_TARGET。不能把 API Key、数据库密码等秘密写入任何 VITE_* 变量。

功能

工作区	已实现
项目列表	真实项目读取、搜索、状态筛选、新建剧本
剧本创作	主题／风格／集数配置、剧集目录与正文、角色、世界观、审核、执行记录、正文导出
创作恢复	恢复剧集生成、恢复改写，操作前确认
拆解配置	每组集数、人物／场景／道具模块选择、后端分组预览
拆解结果	主体、别名、视觉形态、Episode → Beat → Shot、主体绑定、抽取任务状态、校验问题、JSON 导出
拆解恢复	失败抽取重试、缺失剧集镜头补齐、分镜引用与 Form 绑定修复
视觉风格	AI 生成、人工编辑、分类 Prompt、JSON 硬约束、锁定；风格参考图地址登记、启停和删除
主体身份	正式主体目录、单个／批量身份文本、人工编辑与锁定；无形态 Character 也可先完成身份
角色选角	选角就绪检查、角色身份专用批量生成、Seedream 候选小批量生成、确认演员并原子锁定 Identity
身份母版	普通身份图与辅助视角、实际 Prompt 和来源追溯；Character 母版通过确认选角确定
分镜检查	按剧集、Beat、正式 Shot ID 浏览；导演设计、环境与主体即时状态；单集覆盖率与 JSON 导出
分镜生成	Direction / VisualState 单集生成、项目批量补齐、覆盖重生成；并发和自动修复次数；部分失败诊断
镜头工具	主体参考图与缺失原因、确定性 GenerationSpec 查询与导出、单镜头／批量视频提示词
形态图片	正式形态图库、主图／候选图预览、图片历史与失败记录、Seedream 单图／批量生图、切换主参考图
镜头生产	Prompt／首帧／视频就绪诊断、Seedream 首帧候选、Seedance 任务、成片播放、主资产切换与失败重试

尚未实现：手工编辑剧本或分镜设计（后端暂无对应写接口）、用户登录。模型输出按纯文本显示，避免执行不可信 HTML。图片和视频只接受 HTTP(S) 或后端 /storage/ 路径。

技术与规范

• Vite 8、Vue 3、TypeScript、Vue Router
• Tailwind CSS 4，通过 @tailwindcss/vite 集成
• Naive UI：布局、菜单、表格、选择器、输入框、按钮、弹窗、标签、折叠面板、进度和时间线
• Oxlint：脚本质量检查；ESLint：补充 Vue 模板语义
• Oxfmt（不是 oxformat）：沿用后端四空格、单引号、无分号、无尾逗号的风格
• Vitest + Vue Test Utils + happy-dom：API 契约、组件交互和异步生命周期测试
• Lefthook + Commitlint：提交前执行检查，提交信息使用 feat:、fix:、refactor: 等

pnpm check         # lint + format:check + typecheck + test
pnpm format        # 格式化
pnpm lint:fix      # 修复可自动处理的问题
pnpm build         # Vue 类型检查 + 生产构建
pnpm preview       # 预览 dist，不含开发代理

Oxfmt 不负责代码质量，Oxlint 不负责 Vue 的完整类型推导；Vue SFC 的类型检查由 vue-tsc 承担。未照搬后端 --type-aware 来冒充完整 Vue 类型检查。

目录

目录	职责
src/features/projects	项目接口、类型、列表、新建弹窗、项目布局与共享上下文
src/features/create-drama	剧本创作 graph 页面
src/features/breakdown	拆解 graph 的 API、类型、配置页面、主体与分镜组件
src/features/storyboard	分镜 API、类型、生成操作、依赖判断、设计与状态、镜头资源、生成回执
src/features/subject-images	正式形态图库、图片生成参数、历史图片、主图选择与批量回执
src/features/visual-style	项目视觉风格 API、类型、编辑器、锁定和风格参考图管理
src/features/subject-identity	稳定身份 API、正式主体目录、文本编辑、生图配置、身份图库和母版切换
src/features/production	视频提示词、镜头首帧、视频任务、就绪诊断、资产候选与批量回执
src/features/workflows	checkpoint 选择、执行记录、长请求互斥与操作确认
src/components/ui	Naive UI 公共封装、工作区滚动容器与图片展示
src/composables	具备取消和竞态保护的轮询、系统主题与偏好持久化
src/lib	HTTP、错误格式、日期和导出工具
src/router	按 graph 拆分的懒加载路由

每个功能模块通过 index.ts 暴露公共入口。业务类型和行为函数均添加中文职责注释。不要把下一条 graph 的服务继续堆进 App.vue。

后台布局与主题

• 外层应用固定为视口高度；侧栏、顶栏、项目标题和工作流导航不会随正文滚动。
• 工作流只保留左侧导航，项目标题下不再重复展示相同标签。主体身份、分镜设计、镜头生产和图库采用内容优先布局：常用筛选／剧集选择／刷新在固定的紧凑工具栏，列表占据剩余高度。
• 项目列表采用固定表头表格；剧本、分镜、身份与生产页的目录和详情独立滚动，其他工作区只滚动内容区。
• 目录、详情、执行记录、折叠操作区、图片历史和 JSON 查看区统一使用 Naive UI NScrollbar；外层只负责尺寸与裁切，不再设置原生 overflow: auto。内边距与横向排列放在 content-class 内容层，避免双滚动条。
• 身份与形态图库采用限高预览及紧邻其下的横向历史栏；缩略图固定宽度，保留全部候选、辅助视图、失败及进行中记录。点击仅切换预览，不自动切换母版或主图；图片尺寸规则放在非分层组件覆盖样式中，避免被 Naive 按钮默认宽度覆盖。
• 身份母版、图库大图、历史缩略图、形态／风格／分镜参考图及首帧统一通过 NImage 采用 cover 铺满。母版与展示图片可点击原生预览查看完整原图；历史缩略图只切换选中记录，再点击大图查看原图，避免与候选选择混淆。“查看图片与记录”仍单独打开历史管理。
• 拆解页固定精简状态栏与结果标签，设置、预览及恢复操作收进“拆解设置与恢复”面板；人物、场景、道具、分镜和任务明细共用独立结果滚动区，执行记录单独滚动。结果区占满剩余高度，切换标签回到顶部，轮询刷新或开关设置不重置阅读位置；失败与校验提示在面板关闭时仍然可见。
• 剧集正文按编号连续展示全部已写入剧集；点击目录定位正文，滚动正文同步高亮并保持当前目录项可见。目录分行显示集数和完整标题，执行记录可按需展开。切换角色／世界观等标签不会销毁阅读器或重置位置。
• 主体身份、分镜设计和镜头生产共用 DirectoryItem：编号、完整标题和状态分层展示，桌面目录为 240–280px，窄屏改为可横向滚动的条目。目录标题与筛选固定，只有列表滚动。拆解结果的导出按钮与标签同排右对齐；形态图片筛选按内容区宽度自动排成一行或两列网格。
• 身份、分镜、生产与图库的批量配置、说明和诊断统一放入 WorkspaceTools（Naive UI Drawer），按需覆盖当前工作区，不挤压列表。面板支持 Esc 或关闭按钮；关闭不会取消任务或清除配置。历史回执可从入口查看，新回执主动打开诊断；查询错误始终在外层可见。
• 生产步骤的操作按钮保留上下间距；ConfirmAction 用稳定根元素承接外部间距，避免多根弹窗组件吞掉 class。
• 右上角提供浅色、暗黑、跟随系统三种模式，默认跟随系统，选择保存在本机浏览器。存储被禁用时仍可在当前会话切换。
• 以黑白灰为主，仅错误、警告、成功等语义状态保留辅助色。Naive UI 和业务内容共用主题；加载前应用偏好，减少主题闪烁。
• 窄屏默认收起侧栏，目录与正文改用紧凑布局；执行记录仍可查看。长弹窗在自身内部滚动。

布局样式集中在 src/admin.css，业务排版保留在 src/styles.css。新增页面应使用 WorkspacePage（内容优先页开启 compact），低频操作使用 WorkspaceTools；避免通过 body 或 window.scrollTo 管理滚动。

本次 UI 重构保留前端 dev@5551653 的业务更新，包括过期形态图、主首帧和主视频的提示与更新入口。首帧默认只补当前剧集；存在过期主首帧时优先更新全项目过期项。非覆盖模式下的过期主视频重建完成后，会接替旧主视频；普通新增候选不自动替换主资产。

本地验收建议使用 1920×1080、1280×720 和窄屏视口：打开长剧本、长项目标题和多镜头项目，确认顶栏不移动、目录与正文能分别滚到底；切换暗黑模式后检查弹窗、下拉菜单、图片失败占位，刷新后主题应保持。

接口基线

对齐后端 qianlanse/short-drama-agent 的 dev： 40c700f47d578888105484cfb317f52568855e0e（2026-09-01），包含 Character Casting、身份／形态双参考首帧、首帧与视频生产就绪检查，以及独立候选生成和中国人物默认选角基线。本轮只修改前端，请确保后端依照其开发流程同步 Prisma migration 并重启服务。

HTTP	路径（以 /api 为前缀）	用途
GET / POST	/projects	项目列表 / 创建剧本
GET	/projects/:id	正式数据库详情、剧集、角色、世界观与审核
GET	/projects/:id/checkpoints	两条 graph 的 checkpoint；前端按 workflowName 过滤
POST	/projects/:id/resume-generation	继续生成未完成剧集
POST	/projects/:id/resume-rewrite	恢复审核与改写
GET	/projects/:id/breakdown-preview?groupSize=3&modules=character,scene,prop	真实分组与任务预览
POST	/projects/:id/breakdown/start	启动拆解
POST	/projects/:id/breakdown/retry	仅重试失败的抽取 Task
POST	/projects/:id/breakdown/resume-shots	复用已成功剧集镜头，生成缺失剧集
POST	/projects/:id/breakdown/resume-storyboard	修复已有镜头的 SubjectRef / Form，再持久化
GET	/projects/:id/storyboard-directions?episodeNo=N	正式 Shot ID、导演设计、单集覆盖率
POST	/projects/:id/storyboard-directions/generate-test	单集导演设计；明确发送 persist: true
POST	/projects/:id/storyboard-directions/generate	项目批量；concurrency、force
GET	/projects/:id/storyboard-visual-states?episodeNo=N	已持久化的环境、主体状态、单集覆盖率
POST	/projects/:id/storyboard-visual-states/generate-test	单集即时状态；persist: true、maxRepairAttempts
POST	/projects/:id/storyboard-visual-states/generate	项目批量；增加 maxRepairAttempts
GET	/storyboard-shots/:shotId/references	主体形态参考图、缺失原因
GET	/storyboard-shots/:shotId/generation-spec	后端确定性编译结果，不调用模型
POST	/storyboard-shots/:shotId/video-prompt	复用已有 Prompt 或调用模型生成；force 控制覆盖
POST	/projects/:id/video-prompts/generate	项目批量 Prompt；concurrency、force
GET	/projects/:id/subject-forms	正式 SubjectForm ID、主体名称／引用、主图与图片元数据；只读查询
GET	/subject-forms/:formId/images	此形态的全部图片历史及实际 Prompt
POST	/subject-forms/:formId/images	单图生成；显式 provider: seedream，可选 Prompt 和成对尺寸，setPrimary
PUT	/subject-forms/:formId/images/:imageId/primary	选择已完成图片作为主参考图，不调用模型
POST	/projects/:id/subject-images/generate	全项目批量生图；provider、concurrency、force
GET / PUT	/projects/:id/visual-style	查询／人工保存视觉风格，包含分类 Prompt、硬约束和锁定
POST	/projects/:id/visual-style/generate	AI 生成风格；已有风格重生成显式 force: true，锁定时禁止
POST	/projects/:id/visual-style/images	登记已有风格图片地址，不上传文件
PUT	/projects/:id/visual-style/images/:imageId/enabled	风格图片启停
DELETE	/projects/:id/visual-style/images/:imageId	删除风格图片记录，不删除远程文件
GET / PUT	/subjects/:subjectId/identity	查询／人工编辑稳定身份；使用正式 Subject ID
POST	/subjects/:subjectId/identity/generate	AI 生成身份文本，需要项目视觉风格
POST	/projects/:id/subject-identities/generate	项目批量身份文本；force、concurrency，已锁定始终跳过
POST	/projects/:id/character-identities/generate	只批量生成 Character Identity 文本
GET	/projects/:id/character-casting/readiness	角色身份、候选、Anchor 与锁定状态汇总
POST	/projects/:id/character-casting/candidates/generate	为缺少 Anchor 的角色小批量生成停用候选
GET / POST	/subjects/:subjectId/identity/images	查询带 isAnchor 的身份图片／Seedream 生图
POST	/subjects/:subjectId/identity/casting-candidates	单角色生成 primary 选角候选，不自动成为 Anchor
PUT	/subjects/:subjectId/identity/images/:imageId/anchor	将成功的 primary 候选设为身份母版
PUT	/subjects/:subjectId/identity/images/:imageId/casting	确认 Character 选角：切换 Anchor 并锁定 Identity
GET	/projects/:id/video-prompts/readiness	项目视频提示词前置条件检查
GET / POST	/projects/:id/keyframes/readiness、/keyframes/generate	首帧就绪检查与批量 Seedream 生图
GET / POST	/storyboard-shots/:shotId/keyframes、/keyframe	单镜头首帧历史与生图
PUT	/storyboard-shots/:shotId/keyframes/:keyframeId/primary	切换主首帧
GET / POST	/projects/:id/videos/readiness、/videos/generate	视频前置检查与批量 Seedance 任务
GET	/projects/:id/videos/status	项目最近视频任务状态
POST	/projects/:id/videos/retry-failed	重试最近失败的视频任务
GET / POST	/storyboard-shots/:shotId/videos	单镜头视频历史与任务创建
PUT	/storyboard-shots/:shotId/videos/:videoId/primary	切换主视频

API 层也提供 state 与 breakdown/latest 方法。页面通过共享 checkpoint 查询取得阶段状态，避免重复拉取同样内容。

异步与恢复约定

1. POST /projects 返回顶层 202 { projectId, status }，其他接口通常返回 { data }；HTTP 层分别兼容。
2. Breakdown、Storyboard 和恢复接口目前是长 HTTP 请求。不设客户端短超时，不自动重试 POST。关闭页面只会丢失请求连接，不会取消后端任务。
3. 项目列表每 12 秒、项目详情每 6 秒串行刷新。隐藏页面暂停自动查询。切换项目或离开布局时取消查询，旧响应不会覆盖新项目。
4. 抽取任务进度不是全流程进度。抽取完成之后还需要主体合并、形态、节拍、镜头和持久化。
5. 后端失败 checkpoint 可能只有错误。页面回看最近可用的完整快照以保留成果，同时使用最新记录的 execution 状态。显示的是最近可用快照，并不保证全部成果来自最后一次执行。
6. 后端并不为每个阶段提供持久化的 running 状态。没有明确终态时，页面显示“阶段快照 · 执行状态待确认”，不会猜测成功或失败。
7. 恢复操作要求确认后台已停止。当前只做浏览器会话内、项目级互斥，不能替代后端跨浏览器／跨用户的任务锁。断网后先检查后台和 checkpoint，不要立即重复点击。
8. 修改分组或模块后，必须重新预览再启动；重新拆解会调用完整流程，可能替换旧的主体和分镜。

Storyboard 约定

1. 入口为 /projects/:projectId/storyboard。先完成 Breakdown 的主体、形态、镜头与持久化，再生成 Direction，最后生成 VisualState。
2. 当前 Direction 服务读取最新 Breakdown 的 state.breakdownResult.storyboardEpisodeShots；VisualState 读取顶层 state.storyboardEpisodeShots、subjectCandidates、subjectForms。页面不使用历史可恢复快照代替这些生成前置条件。历史快照只补充镜头标题和剧情描述。
3. 镜头 ID 来自正式数据库 GET，按 shotId 关联 Direction 和 VisualState。shotNo 仅在 Beat 内唯一，不能用它拼装接口 ID。VisualState 查询响应的环境字段是扁平结构，与单集生成返回的领域结构不同。
4. 单集入口虽然名为 generate-test，也是后端目前唯一的单集生成接口。页面发送 persist: true，通过校验才保存；单集始终重生成，不受批量的覆盖开关影响。
5. 批量默认 force: false，跳过完整剧集。重新点击“补齐”用于重试未完成项，没有虚构独立 retry 接口。force: true 才覆盖全部。VisualState 可设置非负整数修复次数，0 表示不修复。
6. VisualState 单集生成需要该集所有正式镜头都有 Direction；批量接口由后端逐集检查，缺少前置条件的集数会单独失败。HTTP 200 也可能包含校验失败或部分失败，页面展示逐集诊断和修复次数，不视为全成功。
7. 上游重生成不会自动使下游旧数据失效。覆盖 Direction 后请重生成 VisualState，修改设计／状态／参考图后按需覆盖 Prompt。覆盖率只说明字段已保存，不能证明下游与新版本一致。
8. 每 6 秒查询当前剧集的两类正式结果；这不是全项目实时进度。后端没有独立 Storyboard running / executionId 查询。回执只保留当前浏览器会话，切换页面不丢失，刷新浏览器会丢失。
9. 参考图和 GenerationSpec 按需 GET，切换镜头或设计变化时取消旧查询。GenerationSpec 需要有效的 Direction、VisualState 和形态关联，不生成图片或视频。
10. Video Prompt、Keyframe 与 Video 都有项目级 readiness。页面只向 ready 镜头批量提交；force 会重写 Prompt 或新增首帧／视频候选，但不会静默替换主首帧和主视频。视频任务创建成功不代表成片完成，最终状态以后端轮询和持久化资产为准。

形态图片约定

1. 入口为 /projects/:projectId/subject-images；项目导航、拆解主体列表和分镜参考图缺失提示均可进入。图库自动读取后端已生成图片，不需要重新生图才能显示。
2. 生图使用正式数据库 SubjectForm.id。Checkpoint 的领域 formId 不是数据库 ID，不能直接调用图片接口。新增查询从项目关联读取正式形态，返回轻量图片元数据，不包含图片的 rawJson 或长 Prompt；打开历史弹窗后再读取详细记录。
3. 单图明确发送 provider: 'seedream'，避免后端单图入口默认使用 mock。模型和凭证仅配置在后端，前端不保存 API Key。默认使用后端的 generationPrompt，其次 appearancePrompt；可为本次输入自定义 Prompt，详情显示后端最终实际使用的文本。
4. 单图宽高同时留空使用后端默认 2K，自定义时必须同时提供正整数，具体尺寸限制仍由模型校验。当前 Seedream Provider 没有使用 negativePrompt，所以页面不提供无效的负向提示词输入。
5. 单图生成新增历史记录，不删除旧图。无主图时默认勾选“生成成功后设为主图”；已有主图时默认不替换。候选图可以在历史弹窗二次确认后通过 PUT 设为主图，只允许已完成图片。
6. 批量默认跳过已有主图的形态；勾选“已有主图也新增候选图”发送 force: true。后端批量 force 只生成新图，不会替换已有主图。批量作用于整个项目，不受类型／文字／缺图筛选影响，也不接收单图的尺寸与自定义 Prompt。
7. 图库每 6 秒读取一次真实记录，弹窗只在打开时查询该形态图片。数据库存在 pending / generating 时暂停再次生图；网络错误不自动重试有费用的请求。HTTP 200 中的批量部分失败单独展示。
8. 图片使用持久化后的 /storage/... 地址，开发代理已配置。生产环境也必须代理 /storage/，不能让 SPA 回退返回 index.html。无效 URL、加载失败、无图和后端生成失败有各自提示；不会自动使用可能过期的 Provider 临时地址。
9. 设为主图后，回到分镜点击“刷新参考图”读取最新绑定。已有视频提示词不会自动重生成，需要按需覆盖。本页面不会调用 /production/start 或实际视频生成。

视觉风格、身份与形态的衔接

建议操作顺序：剧本创作 → 剧本拆解 → 视觉风格 → 角色身份与选角 → 形态图片 → 分镜设计 → 镜头生产。视觉风格也可以在拆解前准备；页面不会自动重生成已存在的下游资产。

层级	职责	本次可操作内容
VisualStyle	项目整体美术与视觉语言	整体／人物／场景／道具 Prompt、JSON 字符串数组硬约束、锁定、风格图片记录
SubjectIdentity	同一主体跨形态不变的特征	稳定身份描述、身份 Prompt、锁定、单个及批量 AI 文本生成
Character Casting	确认具体演员身份	候选图、人工选择 Anchor、Identity 原子锁定、项目就绪检查
Identity Image	固定主体身份或补充辅助视角	Scene / Prop 母版及 Character front、three-quarter、full-body 辅助图
SubjectForm Image	某个具体造型或状态的图片	原有单图／批量生图与主图选择；人物／场景图自动引用当前身份母版

1. 风格锁定仍用于阻止 AI 覆盖。Character 的 isLocked 同时是正式选角前置条件：必须具有 Identity、已确认的 primary Anchor 并锁定，Keyframe 才会就绪；确认选角接口会原子完成后两项。
2. 身份 AI 生成需要已创建 VisualStyle；身份图生成还需要已保存的非空 generationPrompt。不存在身份时不调用会报错的图片 GET。404 或网络失败不会被当作“尚未创建”。
3. 前端以正式 subject-forms 目录为基础，并合并 Character Casting readiness，因此尚无形态的角色也可先完成 Identity 和选角。Scene / Prop 若还没有 Form，仍不会凭 checkpoint 伪造正式 Subject ID。
4. 身份文本批量分为 Character 专用入口和全部主体高级入口。选角候选批量只处理 missing_anchor，受本批上限控制；candidate_pending 必须人工确认，不会由批量任务静默决定演员。
5. 身份图片的 isAnchor 来自专用 GET。Character primary 通过 Casting Candidate 接口生成且默认停用；点击确认演员后才成为 Anchor 并锁定 Identity。辅助视图不能直接成为母版。Scene / Prop 保留普通母版切换接口。
6. 普通身份生图不传 referenceImageId 时，由后端自动选择当前母版；无母版时按文本生成。指定时只能选择当前身份已完成的图片；候选图即使停用也可作为显式参考。Character Casting Candidate 是独立选角入口，即使已有 Anchor 也不会复用旧母版，避免旧演员身份污染新候选。尺寸成对留空或提供正整数。自定义 Prompt 会替换后端编译的完整文本，建议保留默认。
7. 目前人物与场景形态生图会自动注入当前身份母版，分别固定人物身份和空间骨架；道具暂不自动引用。没有身份或母版时，原形态生图流程仍可使用。已有母版但缺少 Provider 可访问远程地址时，后端会报错；本地 /storage/ 能显示并不证明原始 Provider URL 仍可访问。前端显示后端错误，不自动重试消耗额度。
8. 修改风格、身份文本或母版，不会自动使旧图失效或重生成。已有形态主图仍会被分镜使用；需要保持新身份时，主动生成候选图并设为形态主图，再刷新分镜参考图，按需覆盖视频提示词。图库详情展示当次 identityAnchorImageId 或 referenceImageId；旧记录没有该字段时明确显示未知，不推断它使用了当前母版。
9. 风格参考图支持登记已有 HTTP(S)／/storage/ 地址、分类、排序、启停和删除记录；没有文件上传接口，也没有风格图 AI 生成接口。当前身份图／形态图 Provider 调用不会自动消费风格参考图片，页面不暗示登记后已生效。
10. 编辑草稿与轮询分离。保存成功才清空草稿，失败保留；主体切换会提示放弃未保存修改。离开页面不会自动保存。所有新写操作沿用项目级会话互斥，生成前需要费用与后台任务确认，无法替代后端跨浏览器锁。
11. AI 生成 VisualStyle 与 Character Identity 时，若项目、世界观和角色事实都未指定人物背景，默认采用自然真实的中国人物选角基线。项目明确配置和角色事实优先于系统默认值，不限制后续使用其它国家、地区、族裔或肤色人物。

后端限制

目前 checkpoints 接口返回完整历史与 state，没有分页或轻量状态接口。长篇剧本会增加轮询流量。下一步建议后端增加：

• 持久化 executionId、运行状态、跨请求互斥和幂等键；
• 精简的进度接口及按 graph 分页的 checkpoint；
• 将 Breakdown 改为 202 异步任务提交，再以轮询或 SSE 读取进度。

前端未模拟这些能力，不调用 stream-test 来伪造进度。Storyboard 的单集 generate-test 仅在用户明确确认生成后调用。

部署

pnpm build 生成 dist，使用 Nginx 等静态服务器部署。SPA 深层路由需要回退到 index.html。 开发代理只存在于 Vite dev server，vite preview 与生产环境需配置独立后端地址或反向代理。

server {
    listen 80;
    root /var/www/short-drama-agent-front/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        # 保留 /api 前缀，不在 proxy_pass 后追加斜杠。
        proxy_pass http://127.0.0.1:3412;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
        proxy_buffering off;
    }

    location /storage/ {
        # 参考图由同一后端的静态资源服务提供。
        proxy_pass http://127.0.0.1:3412;
        proxy_set_header Host $host;
    }
}

实际生成时间可能超过代理限制，仍建议将后端改为异步提交协议。部署前应给应用加访问控制；当前后端没有身份认证，不建议直接对公网开放。

本地联调验收

1. 后端启动成功，前端项目列表能显示数据库项目。
2. 新建 3 集剧本，确认获取项目 ID 后进入创作页，完成后能读到正文。
3. 查看角色、世界观与审核，再进入拆解页；预览分组与模块。
4. 启动拆解，查看 checkpoint、主体、形态、每集 Beat / Shot 和绑定。
5. 在可控测试项目中触发故障，确认 retry / resume-shots / resume-storyboard 各自对应正确失败阶段。
6. 进入分镜设计，确认正式镜头 ID 与 Beat 对应；先生成单集 Direction，再生成 VisualState，检查覆盖率和主体状态。
7. 用小型测试项目验证批量补齐、跳过完整集、失败诊断和明确覆盖；确认关闭覆盖后不会重生成完整设计。
8. 给主体形态准备参考图，读取镜头参考图和 GenerationSpec；在镜头生产页核对 Prompt、首帧和视频三类 readiness。
9. 打开“形态图片”，检查已有主图自动显示；单个形态新增候选图，查看历史、失败原因和实际 Prompt，再设为主图。
10. 在小型测试项目中验证批量补齐与“已有主图也新增候选图”；回到分镜刷新参考图，确认使用新选择的主图。
11. 进入“视觉风格”，保存或生成风格，检查分类 Prompt 和硬约束；锁定后 AI 入口禁用，人工编辑仍可保存。登记一张已有风格图，检查启停和移除确认。
12. 进入“主体身份”，先补齐 Character Identity，再小批量生成选角候选。确认候选不会自动成为 Anchor，人工确认演员后 Identity 同时锁定且 readiness 变为 ready。
13. 为已确认演员生成 front / three-quarter / full-body 辅助图；确认辅助图不能直接设为母版。角色需要更多演员候选时使用单角色候选入口。
14. 对人物和场景形态分别新增图片，在图片详情检查当次母版 ID；旧主图应保持不变，手动切换后再刷新分镜参考图。道具不应显示自动继承母版已生效。
15. 在镜头生产页生成单镜头首帧，确认规格同时列出 identity-anchor 与 form-primary。切换主首帧后再创建 Seedance 任务，等待完成后播放并选择主视频。

本轮新增测试覆盖风格 JSON／锁定／图片 DELETE、身份归并／前置条件／尺寸／显式参考图／母版切换、部分失败、旧响应、草稿保护与费用确认。模型调用均使用模拟 API。当前执行环境未能通过浏览器访问本地开发服务，未完成浏览器视觉验收及真实模型联调，请按上述步骤在本地验收。

自动测试使用模拟 API，覆盖既有流程、分镜接口与竞态，以及形态图片自动读取、正式 ID 生图、主图 PUT、费用确认、尺寸校验、候选图选择、批量部分失败和图片加载错误。不等同于真实模型、MySQL 或浏览器视觉联调。请勿用正式项目随意制造失败以测试恢复。