### Workspace 可见文件

```text
./project.json                         # 唯一 Project 领域状态
./assets/sources/*                    # 已入库源素材
./assets/source-intelligence/*        # 素材理解文本
./assets/artifacts/*                  # 图片、视频等生成结果
```

`project.json.assets.files_by_id` 是所有可见资产文件的索引；索引文本通过 `file_id` 读取，不以文件系统路径作为读写接口。

### project.json 根结构

```text
Project
├── name, description, scenario
├── settings                          # 画幅、分辨率、平台、语言、目标时长、内容类型
├── strategy                          # brief、受众、创意方向、约束、成功标准
├── sources.sources                   # ProjectSource 的 EntityCollection
├── visual                            # visual_bible、style、entities、cast_lineups
│   ├── entities.items[entityId]      # VisualEntity：kind、name、description、continuity、required_variant_ids、canonical_variant_id
│   │   └── variants.items[variantId] # VisualVariant：requirements、prompt、参考、生成版本与独立 selected_artifact_version_id、derived_from_variant_id
│   └── cast_lineups.items[lineupId]  # VisualCastLineup：多角色阵容图（群体锚点）：character_refs 顺序即站位、relative_notes、生成/选定版本
├── timelines                         # Timeline 的 EntityCollection；一条 Timeline = 一个叙事节点（单视频 / 剧集）
│   └── items[timelineId]
│       ├── title, synopsis, description, planned_duration_seconds   # 标题、梗概、正文剧本与本集时长
│       ├── edit_plan                 # 剪辑品味契约（可为 null）：concept、dials(energy/density/decoration: low|mid|high)、signature_device、pacing、design_floor(opening/transitions/body/ending)、mechanical_exemption、scene_ledger[]
│       └── elements_by_id
│           └── span, location, z_index, creation, outputs, render_source
└── assets                            # 文件、源版本、理解版本、Artifact 槽位与版本索引
```

### 基础不变量

- `EntityCollection` 始终由 `items` 和 `order` 组成；两者 ID 集合必须完全一致且顺序不重复。
- 结构起草（structure_draft）：多集项目直接用 `patch_project` 创建/更新 `timelines.items[*]`，`title` 是本集标题，`synopsis` 是梗概，`description` 保存可读的完整正文剧本（动作、表演、衔接、对白和声音），`planned_duration_seconds` 是本集时长；顺序写入 `timelines.order`。已有选中的 `timeline_script` 正文时沿用该剧本，不重复创建另一份。按集增量写作与制作，后续集尚未写完不阻塞前面已就绪的镜头。
- `variants` 只存在于 `visual.entities.items[<entityId>].variants`；`visual` 顶层没有 `variants` 字段。
- `required_variant_ids` 是用户需求中全部必需视觉状态的结构化合同。先完整列出，再逐项建立 `variants`；不得把它缩减成当前已经创建的 Variant。每个实际 Variant ID 都必须已在该清单中声明。
- R2V Element 通过 `creation.visual_variant_refs[entityId]=variantId` 绑定本段使用的角色/场景/道具状态；引用多 Variant 实体时不得依赖实体级默认图。`visual_variant_refs` 的每个 entityId 必须同时出现在本 creation 顶层的 `character_refs`/`prop_refs`/`scene_ref` 中，绑定前先把实体加入对应引用列表。
- 多角色同框的 R2V Element 可声明 `creation.cast_lineup_refs[]` 引用 `visual.cast_lineups` 中的阵容图：它是角色间相对身高/体型比例与风格基准的群体锚点，生成分镜/视频时 Runtime 会自动将其选定图注入参考链首位。引用的 lineup 必须已存在。
- 每个 VisualVariant 的 `selected_artifact_version_id` 只选择该 Variant 的 `generated_artifact_version_ids`；实体级选择仅用于无 Variant 或单 Variant 旧数据兼容。
- 生成某个分镜图前，只要求该 Element 实际引用的角色、场景、道具状态及阵容图已选中真实产物；无 Variant 的实体需有实体级选中产物，多 Variant 引用必须显式绑定。其他镜头或后续集的视觉状态可继续规划/生成，不构成本镜的前置条件。已声明的正确依赖尚在制作时保留引用并等待，不因为暂未生成就删除阵容/衍生状态或换成不符合本镜要求的旧图。
- `schema_version`、`project_id`、`generation`、`created_at` 和 `updated_at` 是受保护字段。
- Element ID 在全部 Timeline 中唯一；时间区间统一使用整数 tick 和半开区间。
- Timeline 的 `color_grade` 只能填写 Schema 列出的命名调色预设；空字符串表示不调色。暖金晨光等自由文本风格描述写入视觉或视频 prompt，不得写入 `color_grade`。
- `location.x/y` 是内容框锚点在归一化成片画面中的位置，`anchor_x/anchor_y` 指定框内哪个点对齐到该位置并作为旋转基点；全画面内容使用 `x=0.5, y=0.5, width=1, height=1, anchor_x=0.5, anchor_y=0.5`。
- Edit 的 `span.duration_tick` 必须等于 `round((source_out_tick-source_in_tick)/playback_rate)`。
- Project 不持久化额外的内容分组、轨道、独立 Content、ProductionFlow 或顺序 Composition。
- `creation.type` 表达 r2v/edit/overlay/transition/audio 的创作语义；执行器与任务状态不属于该结构。
- Overlay `creation` 结构（`type="overlay"`）：字段只有 `text`、`vibe`、`prompt`、`reference_version_ids`、`motion`，没有 kind 字段——角色由数据决定。常用形式：台词卡（宠物 OS 内心独白、采访要点摘要等）把权威文案写入 `text`；无文字装饰动效把 `text` 留空、创意写入 `prompt`、动效文档在 `creation.motion`；媒体贴片把 `text` 留空并用 Element 的 `render_source` 引用媒体版本。`text` 为空的 Overlay 必须携带非空 `prompt` 或引用版本。`emotion`、`entrance`、`exit`、`intensity`、`theme`、`variant`、`motif`、`html`、`fps`、`loop`、`design_notes` 等动效字段属于 `MotionGraphic`，必须放在 `creation.motion` 子对象内，不得直接写在 `creation` 上。正确示例：
  ```json
  {"type":"overlay","prompt":"聚焦标记动效","motion":{"html":"<html>…</html>","emotion":"curious","entrance":"pop","exit":"soft_fade","intensity":0.6}}
  ```
- Transition 元素的 `span` 必须完全包含在其两个端点元素 span 的交集中，即 `max(from.start, to.start) <= transition.start` 且 `transition.end <= min(from.end, to.end)`。创建 transition 前必须确保 `from_element_id` 和 `to_element_id` 对应的两个元素存在时间重叠，并将 transition 的 span 设在该重叠区间内。
- outputs 通过 ArtifactSlot 表达具名产物，render_source 表达当前实际渲染来源。
- source、visual、artifact、file 等引用必须指向当前 Project 中已经存在的实体或版本。
- `assets` 中的文件和版本记录来自素材入库、素材理解或媒体生成结果；未产出的结果保持 `null` 或空集合。
- 禁止使用 `pending-render`、`todo`、`placeholder` 等虚构 ID。
- R2V Creation 用 `creation.narrative` 保存生成单元的完整叙述，包括动作、运镜、节奏、衔接、对白和旁白。`creation.storyboard_prompt` 和 `creation.video_prompt` 分别描述实际图像和视频生成要求；`creation.storyboard_reference_version_ids` 和 `creation.video_reference_version_ids` 是同级的有序图片版本引用字段。以上字段都在 `creation` 内，不能放到 Element 顶层；例如视频提示词的 patch 路径是 `/timelines/items/<timelineId>/elements_by_id/<elementId>/creation/video_prompt`。
- 视频生成按 creation 类型区分，每个类型只包含其模型真正消费的字段：
  - `type=r2v`（参考生视频）：完整片段叙述、分镜图提示词、视频提示词及图片引用。
  - `type=t2v`（纯文本生视频）：只有 intent/narrative/continuity/video_prompt/recipe，无分镜、无参考。
  - `type=i2v`（首帧生视频）：在 t2v 字段基础上增加 `first_frame_version_id`（exact 图片 version id）。
  - `type=s2v`（数字人口播）：`character_ref`（角色实体）、`portrait_version_id`（人物图 exact version，s2v 的 reference）、`script`（台词，经 TTS 变成驱动音频）、`audio_version_id`（驱动音频 exact version）、recipe；无分镜 prompt。
  类型声明即生成模式：提交工具的 mode 必须与 creation 类型一致，不得在提交时替换。
- `type=audio`（音频）：`source_asset_version_id`（exact 音频 version）、`role`（**必填**，混音角色枚举：`narration` 旁白压低画面原声 / `bgm` 音乐床 -12dB 并在人声区间自动闪避 / `sfx` 音效原样混入；无默认值，缺失会被校验拒绝）、`script`（合成旁白的文稿；上传素材音频留空）、`speech_rate`（语速倍率 0.5–2.0，默认 1.0，仅 CosyVoice 系列模型生效）、`gain_db`、`pan`、`fade_in_seconds`/`fade_out_seconds`（0–10 秒边缘淡化；留空 null 表示自适应默认：bgm 为 min(2s, span/4)，其余角色硬边）。合成的旁白必须把最终文稿写入 `script`，用户编辑 script 后会触发重新合成。

### jq_project 输出约束

- 日常结构化写入（新建/更新实体、Variant、Element、改字段）优先使用 `patch_project`：扁平 op 列表、逐 op 定位错误、无需输出完整 Project；`upsert_entity` 会自动同步 EntityCollection 的 items/order。只有需要计算或批量条件修改时才用 `jq_project`。
- jq 的唯一输出必须仍是完整 Project 根对象；不得以 `.timelines...`、`$timeline`、`$element` 等子对象选择结束 program。
- 受保护根字段必须与刚读取的 Project 完全一致。批量新增内容时把对象集合放进 `jsonArgs`，program 只做结构化赋值并自然返回 Project 根对象。
- `jsonArgs` 中的 object 已经是 jq object，直接赋值或合并；仅对真正的 `[{"key":...,"value":...}]` 数组使用 `from_entries`。
- Runtime 自动基于最近读取或成功提交返回的快照继续提交，无需回传 ETag；成功写入后的回执可直接作为后续修改的依据，不必每次重复读取整个 Project。缺少字段、需要查看真实产物或发生并发冲突时，才按 pointer/fields 读取相关内容。
- 一个 Element 的完整叙述、两种提示词和引用可在一次 `patch_project` 中一起提交，不能为了凑字节数删掉对白、拆坏层级或发布互相矛盾的中间状态。复杂批量写入按 Element/实体拆分；正文较长也保留完整内容。`jq_project` 仅在需要计算时使用，program 保持短小；遇到参数截断或修复告警时缩小批次（约 4KB 是 jq 出错恢复的建议，不是正文或合法 patch 的硬上限）。

### Specialist target

```text
R2V: element:<elementId>
AI Edit: timeline:<timelineId>
```

R2V 读写目标 Element 的 `creation(type=r2v)`，storyboard/main 由媒体工具写入 Element outputs。AI Edit 在目标 Timeline 中创建多个 `creation(type=edit)` Element，每个 Element 的 render_source 直接选择一个已有媒体范围：上传素材用 `source_asset_version`，已生成片段或逐集成片用 `artifact_version`，都必须提供 `source_in_tick/source_out_tick`。多集连播通过多个 Edit Element 顺序复用各集的真实成片版本，保留原声，不重新生成媒体；Overlay Element 只表达叠加内容，不能代替连播主轨。Timeline render slot 保存最终合成结果。

### Pydantic 权威 JSON Schema

以下 Schema 在进程启动时由当前 Project Pydantic 模型静态生成：

PROJECT_JSON_SCHEMA={{project_json_schema}}
