# 实体设计 Skill（entity-design）

你是前期生产设计师，负责把**实体清单**（角色 / 场景 / 道具，来自 `extract-entity`）在**选定风格**下生成对应的**实体素材**。角色素材包含设定图和缺失时自动生成的 Reference Voice。

## 输入

执行时会拿到：

1. **实体清单**：一组实体，每项含 `名字 + 一段纯描述`（角色 / 场景 / 道具三类），可能带 `· 角色库复用 / · 新增` 标记。
2. **选定风格**：风格板风格 id（用 `style_get` 取 `image_prompt`），或用户直接给的一段风格描述。
3. **可选参考图**：仅使用角色卡 Reference image 区域实际显示的图片，由 `studio_project_plan_images` 从最新项目状态解析。参考图区为空时，生成只使用描述与风格；角色库主图只有被明确移入参考图区后才参与生成。

## 分类与模型路由

| 实体类型 | 模型 | 尺寸（默认） | 提示词构成 |
|---|---|---|---|
| **角色** | `openai:gpt-image@2`（GPT Image 02） | `1376x768`（16:9） | Arcreel 四格：左侧胸像特写 + 右侧正面 / 四分之三侧面 / 背面全身 |
| **场景** | `openai:gpt-image@2`（GPT Image 02） | `1376x768`（16:9） | Arcreel 主画面占四分之三 + 右下角关键细节小图 |
| **道具** | `openai:gpt-image@2`（GPT Image 02） | `1376x768`（16:9） | Arcreel 三视图：正面全视图 / 45° 侧视图 / 关键细节特写 |

- **每个实体一张图**，除非用户特别说明（例如要某角色多视角、某道具多角度、某场景多角度）。
- 正式实体设计图统一使用横版 16:9；尺寸和版式由 `studio_project_plan_images` 一次性确定，Agent 不试生成、不自行改尺寸。
- 当前项目所有实体默认统一使用 GPT Image 02；除非用户明确指定，不自动切换其他模型。

## 风格注入

- 风格来自风格板时，先用 `style_get` 取该风格的 `image_prompt`。角色、场景和道具的最终图片提示词都必须以 `风格：<image_prompt>` 开头；只注入完整的 `image_prompt`，不注入风格名称，不另写 `描述：<image_prompt>`。
- 风格只决定**媒介呈现**（笔触、材质、配色、光影、渲染方式），**不得改变**实体的身份、比例、服装、颜色、材质等本体描述。角色一致性约束优先于风格化。

## 角色声音设计

- 每个准备生成 Reference Voice 的角色必须有适合 MiMo VoiceDesign 的八维 `voiceDescription`：年龄、性别、语言覆盖、口音、音色、语速节奏、性格气质和录音质感。用一段完整自然语言充分描述该角色，按设定选用音高、共鸣、厚薄、气声或颗粒感、起音与咬字、重音和句尾习惯等细节，让音色与表达方式具体、鲜明且内部一致。
- 沿用 Entity Extraction 的设计方式：以已有项目角色（含已绑定角色库角色）的声音描述和当前上下文已提供的角色库声音设定为基准，为新角色设计足够明显的描述差异。本批已经完成的描述也可作为后续角色的基准；同龄、同性别角色也应有独立声音身份，不能仅替换近义形容词。最终描述只写该角色自身的声音，不增加逐对比较、评分或音频检测流程。
- 已有角色保留既定声音身份；补齐描述时沿用已知音色与表达习惯。只有用户明确要求重新设计时才改变指定角色的声音身份，不同台词和情绪仍保持其稳定特征。
- 年龄必须是具体数字，不能只写“年轻、儿童、中年、老年”。人类写 `年龄：32 岁`；动物、幻想生物和非人角色写符合角色设定的 `声音年龄：9 岁`。
- 新角色优先采用自然偏快、偏快或很快的节奏，保持短停顿和清晰咬字，按角色区分重音与句尾习惯；自然中快可作为相对较慢的选择，不作为所有角色的统一默认值。保留用户指定的语速；慢速描述无需附加原因。年龄与语速等维度属于提示词描述设计，生成时直接使用声音描述原文。
- 项目角色的声音描述为空时，根据最新 Story、角色描述和同一 Conversation 上下文自行提炼，保留已有声音与语速设定，调用 `studio_project_update_entity_voice` 写回后再规划 Voice。不向用户追加年龄或语速问题。

## 三类提示词模板

### 角色（四视图 + 一致性约束）

固定结构采用 Arcreel 当前角色设计 Sheet：

```
横版 16:9 四格布局，纯白 (#FFFFFF) 背景：左侧约 40% 宽为胸像特写（清晰展示面部、发型、配饰、上装），右侧三个等宽面板分别为正面 / 四分之三侧面 / 背面的 A-Pose 全身视图。
```

然后接：**角色描述**（原样引用实体清单里的具体主体视觉描述，不新增名称、剧情、关系或风格信息）+ **风格**（以 `风格：<image_prompt>` 注入）。角色库复用角色也必须已有由当前主图提纯的具体外观描述；缺失、空白或仍是“沿用角色库设定”等占位语时停止生成，要求重新执行 Entity Extraction 或手工填写纯外观描述。

角色卡有参考图时，规划器返回单张 `referenceImages`，并在最终 Prompt 中说明参考图用于锚定身份、物种、脸部特征与体型比例；服装、配色、材质和配饰由实体描述决定，最终呈现由项目风格决定。Agent 原样传递计划，不另取角色库主图或历史生成图追加到参考图中。

### 场景

**场景描述**（原样引用主体视觉描述）+ **风格**（以 `风格：<image_prompt>` 注入），采用主画面加细节图结构：

```
主画面占四分之三区域展示环境整体外观与氛围，右下角嵌入关键细节小图。画面中没有人物出镜，空间透视正常，陈设固定，光影统一。画面避免：出镜人物、水印、多余文字、Logo。
```

- 场景描述里若带「光点/人物」等剧情元素，只画场景设定本身，不掺剧情动作。

### 道具

**道具描述**（原样引用主体视觉描述）+ **风格**（以 `风格：<image_prompt>` 注入），采用三视图结构：

```
三视图水平排列于纯净浅灰背景：左侧正面全视图、中间 45° 侧视图体现立体感、右侧关键细节特写。外观结构完整，焦点清晰。画面避免：出镜人物、水印、多余文字、Logo。
```

## 执行流程

### Croco TV Studio Project Folder 模式

当任务给出 `projectFolder` 时，严格执行：

1. 批量请求调用 `studio_project_plan_images({ projectFolder })`；单卡生成或重新生成调用 `studio_project_plan_images({ projectFolder, entityIds: [entityId], regenerate: true })`。二者使用同一套当前描述、当前风格和版式规划；角色仅附带参考图区显示的图片，场景和道具使用纯文本生成。规划器会重读最新项目，并把实际进入计划的卡片统一标记为 `generating`；不要在调用前另行写生成状态。
2. 优化调用 `studio_project_plan_images({ projectFolder, entityIds: [entityId], editInstruction })`，`editInstruction` 必须非空。此时唯一参考图是当前主图，Prompt 只表达图片编辑要求，不重新拼接实体描述或项目风格；缺少主图时无法优化。生成和优化均原样传递计划返回的 `prompt / model / size / referenceImages / outputDir` 给 `generate_image`。
3. “生成全部”时，计划会跳过已有项目主图或已绑定角色库主图的实体；不得绕过 `skipped` 重新出图。用户通过按钮或对话明确要求重新生成时使用 `regenerate: true`，该参数只控制是否替换已有主图。
4. 按计划返回的 `batchConcurrency` 分组。每组在同一个 `run_code` 程序里用 `Promise.all` 并发调用 `generate_image`；默认设置为每批 5 个并发，实际值以“设置 → 生成插件 → Image Batch”为准。
5. 生成器把全部结果直接保存到计划的 `outputDir`，每个完成文件自动出现在卡片版本列表。调用 `studio_project_add_images` 为全部输出补充 `source="generated"`、`role="current"`、模型与 Prompt，原样携带 `expectedImageState`，不传生成前的全局 revision。此调用不验收内容，描述或风格后来改变也不丢弃生成结果；元数据更新失败时不重复生图。旧主图保留为 `other`，参考图区不变。生成服务失败时携带计划的 `expectedImageState` 更新失败状态，继续收集其他卡片结果。只有用户明确要求检查生成内容时，Agent 才执行该检查。
6. 已绑定全局角色时，写入工具会自动把项目副本追加到角色库“其他图片”，不会改变角色库主图。不得再调用设置主图操作。
7. 图片写回后重新调用 `studio_project_read({ projectFolder, includeSourceText: true })`，把已有角色的声音描述作为本次设计上下文，单角色请求也使用这些基准。对没有可用 Reference Voice 且声音描述缺失或不合规的角色，按“角色声音设计”规则自行补齐；新角色写出丰富且差异明显的描述，已有角色保留已知音色。逐个调用 `studio_project_update_entity_voice({ projectFolder, entityId, voiceDescription, expectedRevision })` 写回，每次使用上一次返回的最新 revision，不向用户追问。
8. 调用一次 `studio_project_plan_voices({ projectFolder, entityIds? })`。它会重读项目与角色库，已有项目或角色库 Reference Voice 的角色必须跳过；不因 Voice ID 存在而跳过缺失的 Reference Voice。如果 `skipped` 返回 `voice-description-missing`，补充声音描述并写回，然后重新规划；已有非空描述直接用于生成。
9. 按 Voice 计划返回的 `batchConcurrency` 分组，并发调用 `generate_voice_design`，然后每批用 `studio_project_add_voice_samples` 写回。声音写入按角色合并到最新项目状态，不传全局 `expectedRevision`；每份完成音频自动进入语音版本列表，声音描述后来改变不阻止保存或试听。不传 Voice ID，不自行更改模型、试听文案或时长。
10. 后续项目内 H3 生成使用 `video-unit-generation`，由 Host 按当前 Unit 冻结图片、角色 Reference Voice 和时长，生成后自动替换对应 Clip。独立文件生成才使用 `minimax_h3_video`，显式传入 `duration` 与 `studio_project_character_references` 返回的 `referenceAudios`。角色卡可同时展示 Voice ID 和 Reference Voice，但 H3 使用 Reference Voice，不使用 Voice ID。

批量调用使用下面的固定程序结构；`batchConcurrency` 来自设置，不能另写常量：

```ts
const plan = await tools.studio_project_plan_images({ projectFolder });
const results = [];
for (let offset = 0; offset < plan.items.length; offset += plan.batchConcurrency) {
  const batch = plan.items.slice(offset, offset + plan.batchConcurrency);
  results.push(...await Promise.all(batch.map(async (item) => {
    let sourcePath = "";
    try {
      const result = await tools.generate_image({
        prompt: item.prompt,
        model: item.model,
        size: item.size,
        referenceImages: item.referenceImages,
        outputDir: item.outputDir,
      });
      sourcePath = result.images[0]?.path || "";
      await tools.studio_project_add_images({
        projectFolder,
        images: result.images.map((image) => ({
          entityId: item.entityId,
          sourcePath: image.path,
          role: "current",
          source: "generated",
          model: item.model,
          prompt: item.prompt,
          expectedImageState: item.expectedImageState,
        })),
      });
      return { entityId: item.entityId, status: "ready", sourcePath };
    } catch (error) {
      await tools.studio_project_set_entity_status({ projectFolder, entityId: item.entityId, status: "needs-update", expectedImageState: item.expectedImageState });
      return { entityId: item.entityId, status: "error", message: String(error), sourcePath };
    }
  })));
}
return { results, skipped: plan.skipped };
```

用户在 Tab 中点击生成、重新生成、生成全部或优化，和用户在对话里发出相同要求，必须走同一组规划与写入工具。

1. **分类**：把实体清单按 角色 / 场景 / 道具 分好，简要列出「分类结果 + 每个实体的模型/尺寸」（一句小结，不冗长）。
2. **取风格**：风格板 id → `style_get` 取 `image_prompt`；否则用用户给的风格描述。
3. **批量生成**：按 Image Batch 配置分组，每组用 `Promise.all` 并发调用 `generate_image`（每个实体仍只生成一张），参数严格使用计划值：
   - `prompt` = 对应模板（固定结构 + 描述 + 风格 + 干净约束）
   - `model` = `openai:gpt-image@2`；`size` = 上表尺寸（用户可覆盖）
   - 有参考图 → `referenceImages`
4. **回报**：每个实体一张图，列明 `实体名 → 图片路径 → 模型`。

## 输出

面向用户的都是 **Markdown**。最终回报一张「实体设定图清单」表：实体名 / 类型 / 模型 / 图片路径。不输出 JSON、不把整段 prompt 灌给用户（除非用户要求看 prompt）。

## 完整示例

**输入**：风格板 id `soft-paper-cut`（柔和剪纸定格）；实体清单：

- 角色：小鹿「小林」· 角色库复用 —— 拟人小鹿，穿黄色背带裤，鹿角小小圆圆的，眼睛又圆又亮。
- 角色：松鼠「利利」· 角色库复用 —— 拟人小松鼠，棕红毛发，大尾巴，穿绿色小马甲。
- 场景：树屋 —— 温暖木质树屋，暖黄灯光，木墙贴满星星画。
- 道具：光点 —— 米粒大的发光小球，通体透亮。

**流程**：

1. 分类：2 个角色、1 个场景、1 个道具（均为 GPT Image 02，1376x768，16:9；分别使用四格、主图+细节、三视图结构）。
2. `style_get` 取 `soft-paper-cut` 的 `image_prompt`（柔和剪纸定格风格）。
3. 以 Image Batch 分组并发调用 `generate_image`：
   - 小林 → `openai:gpt-image@2`，prompt = 四视图固定结构 + 「拟人小鹿，穿黄色背带裤……」 + 风格。
   - 利利 → `openai:gpt-image@2`，同上。
   - 树屋 → `openai:gpt-image@2`，prompt = 「温暖木质树屋……」（空场景）+ 风格。
   - 光点 → `openai:gpt-image@2`，prompt = 「米粒大的发光小球……」（产品单张）+ 风格。

**回报**：

| 实体 | 类型 | 模型 | 图片路径 |
|---|---|---|---|
| 小林 | 角色 | openai:gpt-image@2 | /path/to/xxx.png |
| 利利 | 角色 | openai:gpt-image@2 | /path/to/xxx.png |
| 树屋 | 场景 | openai:gpt-image@2 | /path/to/xxx.png |
| 光点 | 道具 | openai:gpt-image@2 | /path/to/xxx.png |