ToonFlow 分镜表回写主库 o_storyboard
何时用
- 核查进度发现
o_storyboard为 0 行，但o_agentWorkData(key=productionAgent) 的storyboardTable字段已有分镜表。 - 想走 ToonFlow 原生「分镜图生成 / 视频合成」步骤，却发现读不到分镜数据。
- 同一项目有多个剧本（episodesId），需要逐集把分镜表接入主库。
关键事实（本机已验证）
- DB：
%APPDATA%\ToonFlow\data\db2.sqlite（主库，WAL 模式，读用mode=ro不锁写）。 - 分镜表权威源：
o_agentWorkData中key='productionAgent'的行，data为 JSON，分镜在storyboardTable字段（markdown）。该 JSON 还含script/scriptPlan/assets/storyboard/workbench。 - 剧本表
o_script：id=episodesId，name为剧名，projectId共享同一项目。 o_storyboardschema 关键列：id(整数主键，非自增→由 insert 自动取 rowid)、scriptId、prompt、duration、state、track、videoDesc、shouldGenerateImage、trackId、projectId、filePath、reason。- 资产表
o_assets：id / name；分镜表每场 header 的「引用资产ID」即关联资产。 - HTTP API 端口动态：用 PowerShell
Get-NetTCPConnection -State Listen过滤 ToonFlow 进程 PID 找监听端口（常见 49xxx/50xxx）。 - 鉴权：JWT Bearer，HS256，密钥 =
o_setting.tokenKey（本机234001a6）。自签：b64url(header).b64url(payload).b64url(HMAC_SHA256(secret, header.payload))，payload 任意。 - 写入口：
POST /api/production/storyboard/batchAddStoryboardInfo，body{ data:[{prompt,duration,track,state,src,videoDesc,shouldGenerateImage,associateAssetsIds}], scriptId, projectId }。该接口会自动按track分组建o_videoTrack并回填o_storyboard.trackId，并建立o_assets2Storyboard关联。
步骤
- 端口 + 密钥：发现 ToonFlow 监听端口；从
o_setting读tokenKey。 - 确认 scriptId：查
o_script找目标剧名 → 记scriptId(episodesId) 与projectId。 - 备份 DB：
copy db2.sqlite db2.sqlite.bak_xxx（回写前必做）。 - 解析 storyboardTable：按
## 场N：...切场景；每场取「引用资产ID」行（如[1,4,5]）；按| 序号 | 画面描述 | 时长 | 景别 | 运镜 | 台词 | 音效 |表头解析行。时长→int 秒；景别+运镜→prompt 后缀。 - 构造 prompt（注意格式）：
{画面描述}，{景别}景别，{运镜}运镜。{风格}。
⚠️ 易错：若拼成{景别}景，会出「全景景，缓摇」重复「景」字 bug；正确为「全景景别，缓摇运镜。」风格串示例：古典中国风写实真人剧照质感，电影级光影，16:9 横构图。
-videoDesc填{画面描述} 台词：… 音效：…（给视频步用）。
-state="未生成"，src=null，shouldGenerateImage=1，track=场名，associateAssetsIds=该场资产ID列表。
- ⚠️ 项目红线（莽途/历史人物剧务必加）：在prompt与videoDesc末尾追加【严格约束】段，包含两条：(1)人物一致性——每名角色外貌须与对应角色设定图(参考图)完全一致，禁止跨镜头改貌/加设定外特征；(2)时代一致性——西汉背景，严禁任何非西汉/跨时代/现代物品(眼镜、钟表、手机、塑料、玻璃幕墙、电线、电灯、机动车、霓虹、现代招牌、拉丁字母/阿拉伯数字标识、空调外机等)，仅可出现剧本明确提及内容。资产 prompt 同理按类型追加（role→一致性自引用；scene/tool→反跨时代）。 - 自签 JWT + POST：调用
batchAddStoryboardInfo，拿到返回的每个分镜id（按场景顺序 1..N）。 - 验证落库：查
o_storyboard WHERE scriptId=?行数；o_videoTrack WHERE scriptId=?应有每场一条；o_storyboard.trackId应全非空；o_assets2Storyboard关联数 = Σ每场资产数。复核无prompt LIKE '%景，%'残留。
常见坑
- 端口会变：每次都重新发现，别硬编码旧端口。
- 直接写 DB 有锁风险：优先走 API；API 已正确处理 track/资产关联/id。
o_storyboard.id非自增列，但 insert 不带 id 时 sqlite 自动赋 rowid，API 用法安全。- prompt 里的「景别/运镜」指令直接影响出图质量，务必用「景别/运镜」而非裸「景」。
- 后续「分镜图生成」用
POST /api/production/storyboard/batchGenerateImage，body{ storyboardIds:[全量], scriptId, projectId, concurrentCount }；图片修复需已让 openai 厂商imageRequest真实实现（url→base64）。
