# Plan · 实体提取解耦 + 资产页提取入口

> 目标:根治"角色没提取 / 参考图全空 / 退化文生图"。把**实体提取从脚本生成里拆出来**,做成定稿剧本后、进资产页时的独立一步(AI 提角色+场景,商品用预创建的)。脚本只管脚本,随便改不影响。

## 根因回顾(已实测)
脚本 AI 把"实体"和脚本一起吐 → 模型不稳(尤其改稿 revise 会丢实体)→ 最近项目 `实体数=0 / entity_refs=空` → 角色提不出、参考图选 0 张 → 分镜/视频全文生图。**解耦后,提取在定稿剧本上单独跑一次,与改稿无关,稳。**

---

## Phase 1 · 写「提取 skill」(用官方 skill-creator 的方法写)
新建 skill(放 `skills/` 下,如 `ecommerce-entity-extract/`)。契约:
- **输入**:定稿剧本全部分镜(narration/visual/role)+ 商品信息(名称/卖点)。
- **只提 角色 + 场景**(**不提商品**)。商品由代码用预创建商品注入,不从剧本提(避免和上传的不符)。
- **每个实体写 `visual_prompt`**:
  - **角色**:① 真人电商模特、**穿着得体、符合剧情的整套衣服**;② 剧本没写穿搭就**按剧情+商品风格设计一套**;③ **空着手 / 不拿任何道具 / 不拎包**;④ **不得出现与商品同类的物件**(商品是包→人身上无包);⑤ 不暴露(除非商品本身是泳装等)。
  - **场景**:地点 / 光线 / 风格,干净构图。
- **AI 判定每镜出现哪些角色/场景** → 每个 segment 的 `entity_refs`。
- **输出 JSON**:`entities:[{id,type:character|scene,name,visual_prompt}]` + `segment_refs:[{index, refs:[实体id...]}]`。
- skill 里把上面"角色铁律"写死。注:`visual_prompt` 只写"中间那段人物/场景描述",外面那层质量模板由代码加(用户看不到)。

## Phase 2 · 后端独立提取步
- **新端点** `POST /api/projects/{id}/extract-entities/`(可带 `generate: none|character|full` 决定提完要不要接着生成)。
- 读定稿(已采用)剧本 → 调提取 skill(一个文本模型,复用现成 `_extract_cast_scene` 升级)→ 得角色/场景 entities + 每镜 refs。
- **商品参考图:三视图优先 → 主图兜底,且无条件带上**。提取只产角色/场景、不碰商品。改 `_storyboard_reference_images` 与视频取参考图:每镜**无条件带一张商品参考** = 优先已采用的**商品三视图**(product 组的 adopted_asset)→ 没有则用**预创建商品主图** `_product_cover_url`。(现状只在"refs 里有商品实体、或一张都没匹配"才带 → 提取后没商品实体会漏,实测确认。)商品不进 entity_refs、不从剧本提、不生成。
- **创建商品强制要主图**(堵兜底的洞):实测 `Product.cover_asset` 可空、后端 create 不校验图、images `required=False` → 能建出一张图都没有的商品,那主图兜底就空了。**后端 ProductSerializer.create / validate 加校验:创建商品必须至少 1 张图**(前端抽屉已校验,后端补上,堵 API/向导路径)。
- 落库:`project.metadata`(cast/cast_prompts/scenes/scene_prompts/**script_entities**)+ 回填每条 `ScriptSegment.entity_refs`。**提取是实体的唯一权威来源**(脚本生成里就算吐了 entities 也以这步为准、被覆盖)。
- **脚本生成那块完全不动**(脚本只管脚本)。我之前提的"改稿保底"补丁因此作废、不需要了。
- `generate=character`:提完顺手生成 **角色 + 场景** 基础资产;`generate=full`:角色 **全身照 + 三视图** + 场景。商品不生成(用主图)。

## Phase 3 · 前端资产页提取入口(蒙版 + 3 按钮)
- 进资产页 + 尚未提取 → 资产区盖**半透明蒙版**(同脚本页风格),中间面板:
  - 标题「先从剧本认出角色 / 场景」· 副 `// 生成图会扣费,交给你点,不自动花钱`
  - 三按钮(轻→重):
    | 按钮 | 主文案 | 角标 | 做什么 |
    |---|---|---|---|
    | ① | 只提取关键词 | `不出图` | 提角色/场景,出提示词,不生成 |
    | ② | 提取 + 生成角色和场景 | `会扣费` | 提完生成角色立绘 + 场景图 |
    | ③ | 提取 + 全套资产 | `会扣费·最全` | 角色全身照+三视图 + 场景图 |
  - 点 → 蒙版留住 + Loading 转 → 完成取掉蒙版:① 只露提示词卡;②③ 连图摆好。
- **角色卡只显示可改的"描述"(visual_prompt)**,写死的质量模板不展示给用户。
- 加「**重新提取**」按钮(改了脚本可重提,会覆盖)。

## Phase 4 · 兜底弹窗拦截(防"花冤枉钱"·重点)
现状兜底是**静默退化成文生图/文生视频** —— 出来的东西跟用户建的角色/商品完全无关,用户觉得花了冤枉钱、易起纠纷。因为参考图是**自动关联**(没给用户手选),所以**生成前必须检查 + 拦截**,不许静默生成。
- **检查时机**:生成**故事板**、生成**视频**前(消费参考图的步骤;角色/场景基础资产本身是文生图、不在此列)。单镜生成查该镜,整批生成查所有相关镜。
- **检查内容**:对每镜 entity_refs,逐个**角色/场景实体看有没有已采用的基础资产**(商品永远有主图、不算缺)。算出"缺哪几个"(按名字)。
- **不齐就弹窗拦截、不生成**:弹窗列"这镜需要 角色A/角色B/场景X,但【角色B、场景X】还没生成参考图",主按钮「**去补齐**」(跳资产区高亮待生成项)+ 次按钮「仍要生成(可能跟你的角色对不上)」。默认引导补齐;齐了才正常生成。
- 后端原有的文生图兜底保留作"用户执意 仍要生成"时的最后退路,但**默认走前端拦截**。

## (未来待办,现在不做)质量词搬进 Admin
平台暂无 Admin 页面。等做 Admin 页(用户会给参考代码)时,再把各阶段写死的质量/规格词(画面清晰/9:16/镜头稳定…)抽进可配置表 + 编辑入口。**本轮不碰,仅记录。**

## Phase 5 · 真跑验证(不是构建过就算完)
真实流程跑一遍:生成脚本 → 进资产页 → 点①看角色/场景实体和每镜 refs 出来(商品永远带主图)→ 点②③看角色+场景图生成 → **故意留一个角色不生成,验证故事板/视频前弹窗拦截**(列出缺的、不静默生成)→ 补齐后故事板/视频看参考图真接上(不再全文生图)。用 `_storyboard_reference_images` 实测脚本逐镜核 refs 数。

---

## 待你确认
1. **脚本生成完全不动、提取步覆盖为准**(改稿无忧)—— 对吧?
2. **商品永远带主图当参考**(不提取、不进 entity_refs、不生成)—— 对吧?
3. 按钮 ②③ = **角色 + 场景都生成**(商品不生成)—— 对吧?
4. **兜底弹窗拦截**:缺参考图就弹窗让用户去补 —— 要不要保留「仍要生成」强制选项(带警告),还是**硬拦到补齐为止**?
5. 质量词 Admin 本轮不做、只记着 —— 确认。