docs: refine agent storyboard enrichment design

docs/superpowers/specs/2026-04-28-agent-storyboard-enrichment-design.md

@@ -37,6 +37,8 @@
 - 不在本次改造中重做整个分镜编辑器。
 - 不把 `storyboards` 改造成全量结构化 JSON 模型。
 - 不改现有视频生成主流程的入参协议，只补充分镜默认可用数据。
+- 不在本次改动 `end_frame_prompt` 的语义与展示。
+- 不在本次支持一个分镜横跨多个场景引用。
 
 ## 方案对比
 
@@ -91,11 +93,12 @@
 
 ### 1. 数据模型
 
-在 `storyboards` 表新增两个字段：
+在 `storyboards` 表新增两个字段，迁移文件命名为 `V17__storyboard_scene_ref_video_prompt.sql`：
 
 - `scene_ref VARCHAR(128) NULL`
   - 存单个场景引用，格式统一为 `@场景名`
   - 仅表示该分镜主场景
+  - 显式不支持多场景
 - `video_prompt LONGTEXT NULL`
   - 存分镜最终视频生成提示词
 
@@ -104,6 +107,7 @@
 - `characters`
 - `start_frame_prompt`
 - `motion_script`
+- `end_frame_prompt`，本次不动，沿用现状
 
 其中 `characters` 在本次改造后只表达“出镜角色引用”，不再混入场景引用。旧数据继续兼容，读取时允许为空或保留旧格式。
 
@@ -142,6 +146,23 @@
 
 为了避免重复维护 prompt 模板，本次不新写第二套视频提示词生成 prompt，而是直接复用现有 `generatePrompt` 主逻辑。
 
+#### generatePrompt 用户消息模板调整
+
+现有 `generatePrompt` 在拼装“当前分镜信息”时，只引用了 `sb.getCharacters()`。本次改造后 `characters` 不再混入场景引用，必须同步调整 user message 模板：
+
+- 在“出场角色/场景”行之外新增“分镜场景：${sceneRef}”行
+- 当 `sceneRef` 为空且 `characters` 仍为旧格式时，回退到现有逻辑读旧 `characters`
+- 否则提示词会丢失场景上下文，质量明显回退
+
+#### 计费策略
+
+`generatePrompt` 自带 `billingService.checkBalance` + `charge`，`operation=storyboard_prompt_generate`，`unitCount=1`。Agent 自动批量补全后，每个项目会多出“分镜数”次 LLM 调用与扣费：
+
+- 复用同一个 `operation=storyboard_prompt_generate` 计费 key，不新增计费项
+- 在补全开始前先按“剩余待补条数”做一次合并 `checkBalance`，避免逐条触发预检
+- 实际扣费仍按条记账，便于审计
+- 余额不足导致中途失败时：已成功条数保留，剩余分镜 `video_prompt` 留空，整步标记失败
+
 ### 4. Agent 流程调整
 
 保持 Agent 现有步骤数量不变，仍然保留 `storyboard_gen` 这一步，对前端步骤卡片和 SSE 事件名不做额外拆分。
@@ -166,14 +187,40 @@ SSE 日志建议新增类似文案：
 
 - `第 1 集分镜：12 个镜头`
 - `第 1 集视频提示词：12 条已生成`
+- `第 1 集分镜生成中 6/12`
+- `第 1 集提示词生成中 3/12`
+
+#### 并发策略
+
+提示词补全默认在**同集内**用固定并发度执行，默认值建议 `3`，配置上限建议不超过 `5`：
+
+- 串行下 5 集 × 10 镜 ≈ 50 次 LLM 串行，Agent 总耗时翻倍，体验差
+- 跨集仍按集顺序执行，保证日志和失败定位清晰
+- 并发度取自配置，便于按账户配额或模型 RPM 调整
+- 任一并发任务抛出余额不足异常时，立即中断同集后续任务并标记步骤失败
+
+#### 重跑与幂等
+
+本次只为 **`video_prompt` 补全链路** 引入幂等保证，不改变基础分镜生成 `generateStoryboards(...)` 的现有语义。
+
+- 若某集基础分镜已经存在，但部分或全部 `video_prompt` 为空，则 Agent 重跑时允许只补全缺失的 `video_prompt`
+- 若某集基础分镜与 `video_prompt` 都已齐全，则跳过该集的提示词补全
+- 若用户希望“整集分镜从头重做”，仍沿用现有做法：先手动删除该集分镜，再重新生成
+
+这样可以修复“分镜已生成但提示词补全失败”的场景，同时避免这次把“基础分镜重跑语义”一起做大。
 
 ### 5. API 与 DTO
 
-扩展 `StoryboardDTO` 与前端 `Storyboard` 类型，新增：
+现状澄清：`StoryboardDTO` 已经透传 `startFramePrompt` 与 `motionScript`，前端“看不到”是渲染层未消费这两个字段。本次真正需要新增的只有：
 
 - `sceneRef: string | null`
 - `videoPrompt: string | null`
 
+扩展点：
+
+- 后端 `StoryboardDTO` 新增上述两字段并在 `from(...)` 中映射
+- 前端 `Storyboard` 类型同步新增对应字段
+
 现有接口不新增新路由，直接在已有分镜列表/详情返回中带出新字段：
 
 - `GET /projects/{projectId}/episodes/{episodeId}/storyboards`
@@ -248,6 +295,21 @@ SSE 日志建议新增类似文案：
 
 若用户手动更新分镜内容后再次点击“生成提示词”，后端应重新生成并覆盖 `video_prompt`，保持结果与当前分镜内容一致。
 
+但用户也可能只编辑分镜正文而**不**点重新生成，此时 `video_prompt` 会与正文脱节。本次采用以下策略：
+
+- `update(...)` 在检测到以下任一字段被修改时，自动清空 `video_prompt`
+  - `shortDescription`
+  - `detailedDescription`
+  - `characters`
+  - `sceneRef`
+  - `dialogues`
+  - `cameraDirection`
+  - `compositionGuide`
+  - `durationSeconds`
+  - `motionScript`
+- 前端读到 `videoPrompt` 为空时按“未生成”展示，用户可手动重新生成
+- 这样避免“陈旧提示词”被静默用于视频生成
+
 ## 失败处理
 
 ### 分镜生成成功，视频提示词补全失败
@@ -270,20 +332,41 @@ SSE 日志建议新增类似文案：
 - 失败分镜 ID / 场景号
 - 已成功条数 / 总条数
 
+整步失败后，已生成的分镜与已写入的 `video_prompt` 都保留。用户可通过：
+
+- 重新执行 Agent（按上文幂等补全策略，仅对未补全的分镜重补提示词）
+- 或在工作台逐条点击“重新生成提示词”
+
+二者任一方式恢复，无需手动清理脏数据。
+
 后续如有需要，可扩展为“容忍单条失败并记录失败列表”，但这不作为本次必做范围。
 
+### 余额不足
+
+并发或串行补全过程中，若 `billingService.checkBalance` 抛出余额不足：
+
+- 已成功条数保留
+- 立即中断当前集剩余任务及后续集
+- 整步标记失败，日志注明“余额不足，已生成 X 条分镜，已补全 Y 条提示词”
+- 用户充值后按上文幂等补全策略重跑即可继续
+
 ## 测试策略
 
 ### 后端
 
-- `StoryboardPipelineServiceImpl`：
+- `StoryboardPipelineServiceImpl`
   - 新 schema 正常解析 `scene_ref`
   - 旧格式 `characters` 能拆分出角色与场景
   - `generatePrompt` 回写 `video_prompt`
-- `AgentRunServiceImpl`：
+  - `generatePrompt` user message 在 `sceneRef` 存在时正确包含场景行；为空时回退读旧 `characters`
+  - 编辑分镜正文后 `video_prompt` 被清空
+- `AgentRunServiceImpl`
   - `storyboard_gen` 完成后，分镜已持久化 `video_prompt`
   - 任一提示词生成失败时，步骤状态正确标记为失败
-- DTO/Mapper：
+  - 重跑场景：已存在分镜的集只补缺失的 `video_prompt`，不改变基础分镜生成的旧行为
+  - 同集并发补全 N 条任务时进度日志正常
+  - 余额不足时立即中断剩余任务并标记失败
+- DTO/Mapper
   - 新字段能正确出入参
 
 ### 数据库迁移
@@ -313,6 +396,8 @@ SSE 日志建议新增类似文案：
 - 全量旧数据离线回填脚本
 - 分镜编辑器的深度结构化改造
 - 视频生成页面的大规模交互重构
+- `end_frame_prompt` 字段的语义调整或前后端展示
+- 多场景分镜的支持
 
 ## 预期结果