# 18 · Agent 动态编排升级方案 PRD

> 文档版本: v2.2  
> 更新日期: 2026-05-25  
> 适用范围: `yaoai-comic-studio` / `doc/html` / `yaoai-admin-web`  
> 核心目标: 先准确理解原剧本，再围绕同一套剧情事实、角色锚点、场景锚点和画面风格持续生成内容。

## 1. 现实校准

当前代码里的 Agent 还不是动态 Agent，而是固定步骤执行器：

```text
AgentController.startRun(projectId, goal)
  -> AgentRunServiceImpl.startRun(projectId, tenantId, goal)
    -> 固定创建 7 个 graph_steps
    -> decision
    -> outline_gen
    -> episode_gen
    -> supervision_1
    -> asset_gen
    -> storyboard_gen
    -> supervision_2
```

其中 `decision` 只是自然语言计划，真实执行路径仍然固定。更关键的是，`outline_gen` 当前会把前端 `goal` 当作剧本内容传给 `OutlinePipelineServiceImpl`：

```java
outlinePipeline.generateOutline(projectId, tenantId, goal)
```

所以即使用户上传了剧本，Agent 也可能没有优先消费剧本原文，导致大纲、角色、场景、分镜、视频提示词从第一步就偏离原数据。

模型栈也要按当前实际校准：当前文本模型链路是 `ArkLlmService` 调火山方舟 `/chat/completions`，默认模型来自 `VOLCENGINE_ARK_TEXT_MODEL`，不是原方案里提到的 `Spring AI Alibaba / 通义 qwen`。

## 2. 核心问题

当前生成不稳定和发散，根因不是某个 Prompt 不够长，而是缺少四层运行时能力：

1. **剧情理解层**: 没有先把原剧本抽成可验证的剧情事实。
2. **一致性基准层**: 没有项目级角色、场景、风格、画面锚点。
3. **动态计划层**: 没有根据项目状态决定跳过、续跑、补齐或重跑。
4. **质量门禁层**: 没有要求每个结果先通过结构、证据、剧情、视觉一致性校验后再落库。

直接表现：

- 有剧本时仍按 `goal` 自由发挥。
- 对剧情理解不准，导致提取出来的角色、场景和分镜严重偏离原数据。
- 视频提示词不是从剧情事实推导，而是从短描述自由扩写。
- 角色发型、年龄感、服装色系、身份关系容易漂。
- 场景空间结构、光线、色彩、关键道具容易漂。
- 同一项目画面风格在不同步骤中随机变化。
- 失败后只能看到文本错误，无法定位是剧本理解错、Prompt 错、模型输出错还是校验规则错。

## 3. 方案总览

目标架构：

```text
AgentController.startRun
  -> RunIntentResolver
  -> RunContextLoader
  -> ScriptUnderstandingService
  -> ConsistencyBibleService
  -> RunModeRouter
  -> RunPlanExecutor
       -> PromptAssemblyService
       -> OutlinePipeline
       -> EpisodePipeline
       -> AssetGenPipeline
       -> StoryboardPipeline
       -> QualityGateService
       -> ConsistencyGateService
       -> PromptSnapshotService
```

执行原则：

- 先读剧本，不先创作。
- 先抽事实，不先写大纲。
- 先绑定证据，不让模型猜测当事实。
- 先建立一致性基准，再生成角色、场景、分镜和视频提示词。
- 视频提示词必须从剧情事实、角色视觉锚点、场景空间锚点和镜头语言推导。

## 4. 剧情理解层

新增 `ScriptUnderstandingService`，作为有剧本场景下的第一步。

它的职责不是创作，而是从原剧本中抽取可验证事实：

- `plotFacts`: 核心事件、因果、转折、人物关系变化。
- `characterFacts`: 角色身份、别名、关系、动机、首次出现事实。
- `sceneFacts`: 场景名称、类型、叙事功能、来源事实。
- `uncertainties`: 指代不明、关系不明、时间线冲突等不确定项。
- `evidence`: 每条关键事实对应的原文片段、资产 ID、位置或摘要哈希。

处理策略：

```text
原始剧本
  -> Chunk Fact Extraction     按场次/段落/台词块切片抽取事实
  -> Fact Merge & Normalize    合并同名角色、同一事件、多次出现的场景
  -> Coverage Check            检查关键剧情段落是否被事实覆盖
  -> Contradiction Check       检查人物身份、事件顺序、地点归属是否冲突
  -> Human Confirmation        关键不确定项存在时请求用户确认
```

硬规则：

- 不允许在剧情理解层新增剧本中没有的关键人物、核心冲突、世界观设定。
- 无证据的人物关系、动机、事件因果只能进入 `pending_inference`。
- `coverageScore` 低于阈值时，不允许进入 `outline_gen`。
- 关键不确定项影响主线时，Agent 应进入 `script_clarification_required`，而不是继续自动生成。

## 5. 一致性基准

新增 `ProjectConsistencyBible`，解决剧情、角色、人物视觉、场景、风格、画面连续性漂移。

它是每次生成前必须加载的结构化基准卡，至少包含：

- `storyWorld`: 题材、主题、时间线、核心冲突、禁改项。
- `characters`: 角色身份、性格、关系、视觉锚点、服装规则、禁改项。
- `scenes`: 场景空间结构、主色调、光线、关键道具、禁改项。
- `visualStyle`: 基础画风、镜头语言、色彩策略、人物渲染规则、场景渲染规则。
- `lockedFields`: 用户人工确认或修改过的高优先级事实。

示例：

```json
{
  "storyWorld": {
    "genre": "现代都市言情",
    "coreConflict": "女主查清背叛真相并夺回人生主动权",
    "forbiddenDrift": ["不得突然改成古风", "不得新增超自然设定"]
  },
  "characters": [
    {
      "id": 1001,
      "name": "林知夏",
      "identity": "被陷害的年轻设计师",
      "visualAnchor": "25岁，黑色长发，清冷气质，浅色通勤装",
      "forbiddenDrift": ["不得变成短发", "不得改成学生身份"]
    }
  ],
  "scenes": [
    {
      "id": 2001,
      "name": "盛华集团顶层会议室",
      "spatialAnchor": "落地窗在右侧，长会议桌居中，城市天际线作为背景",
      "lighting": "冷白顶光 + 玻璃反射",
      "colorPalette": "steel blue / cold grey / black"
    }
  ]
}
```

生成与更新规则：

- `script_understanding` 后生成剧情事实底座。
- `outline_gen` 基于剧情事实生成初版一致性基准。
- `asset_gen` 落库角色、场景后，回写角色视觉锚点和场景空间锚点。
- 用户人工修改角色、场景、风格时，同步更新一致性基准，并标记为人工锁定事实。

## 6. 动态运行模式

最低支持：

| 模式 | 命中条件 | 执行策略 |
|---|---|---|
| `script_based` | 有剧本资产，无可用大纲 | 先做剧情理解，再生成大纲和下游 |
| `goal_based` | 无剧本资产，无大纲 | 基于目标创作大纲 |
| `outline_continue` | 有大纲，缺分集或下游资产 | 跳过大纲，从分集或资产继续 |
| `asset_continue` | 有分集，缺角色或场景 | 只提取角色和场景 |
| `storyboard_only` | 有分集、角色、场景，缺分镜或提示词 | 只生成或补齐分镜和提示词 |
| `resume_failed` | 最近一次运行失败 | 从失败步骤或最近安全步骤恢复 |
| `selected_steps` | 用户指定步骤 | 执行指定步骤及必要依赖 |

路由必须优先使用代码规则。只有规则冲突或用户目标含混时，才调用 LLM 辅助判断。

## 7. RunPlan

`RunPlan` 是执行器唯一依据，必须落库。

```json
{
  "runMode": "script_based",
  "plannedSteps": [
    "script_understanding",
    "outline_gen",
    "episode_gen",
    "asset_gen",
    "storyboard_gen",
    "final_review"
  ],
  "stepInputs": {
    "script_understanding": ["scriptAsset", "goal"],
    "outline_gen": ["scriptUnderstanding", "project", "goal"],
    "episode_gen": ["latestOutline", "scriptUnderstanding"],
    "asset_gen": ["scriptUnderstanding", "episodes", "projectStyle"],
    "storyboard_gen": ["scriptUnderstanding", "episodes", "characters", "scenes", "consistencyBible"]
  },
  "qualityRules": {
    "scriptUnderstandingRequired": true,
    "sourceEvidenceRequired": true,
    "scriptCoverageRequired": true,
    "promptTraceabilityRequired": true,
    "plotContinuityRequired": true,
    "characterVisualConsistencyRequired": true,
    "sceneSpatialConsistencyRequired": true,
    "visualStyleConsistencyRequired": true
  }
}
```

## 8. Prompt 协议

所有 Prompt 统一拆成四段：

1. 角色定义块。
2. 事实上下文块。
3. 输出协议块。
4. 校验约束块。

重点规则：

- `script_understanding`: 只抽取事实，不创作，不扩写，不把 `goal` 当剧本事实。
- `outline_gen`: 必须读取剧情事实图谱，不能只用 `goal` 或未校验摘要。
- `episode_gen`: 每集必须绑定一个或多个 `plotFactIds`。
- `asset_gen`: 角色身份、关系、动机必须来自 `characterFacts` 或 `plotFacts`。
- `storyboard_gen`: 每条分镜必须说明使用了哪些剧情事实。
- `prompt_gen`: 视频提示词必须从分镜事实、角色视觉锚点、场景空间锚点推导。

视频提示词建议先输出中间结构，再渲染最终 Prompt：

```json
{
  "storyboardId": 3001,
  "sourceFactIds": ["pf_023", "pf_024"],
  "characterRefs": [
    {
      "characterId": 1001,
      "name": "林知夏",
      "usedAnchor": "25岁，黑色长发，清冷气质，浅色通勤装"
    }
  ],
  "sceneRef": {
    "sceneId": 2001,
    "usedAnchor": "落地窗在右侧，长会议桌居中，城市天际线作为背景"
  },
  "shotFacts": {
    "action": "女主克制地看向会议桌对面，压下愤怒",
    "emotion": "隐忍、警觉",
    "dialogueIntent": "她意识到对方在隐瞒关键证据"
  },
  "visualDirectives": {
    "camera": "medium close-up, slight low angle",
    "lighting": "cold white overhead light with glass reflection",
    "composition": "female lead on left third, conference table leading lines"
  },
  "finalPrompt": "..."
}
```

校验要求：

- `finalPrompt` 中的人物、动作、情绪、场景、关键道具必须能在中间结构里找到来源。
- 不允许新增未声明的人物、地点、事件、道具。
- 剧情事实不足时返回 `need_more_context`，不要凭空补剧情。

## 9. 质量门禁

新增 `QualityGateService` 和 `ConsistencyGateService`。

### 9.1 剧情理解门禁

- `plotFacts` 不得为空。
- 主要角色必须至少绑定一条剧情事实。
- 主要场景必须至少绑定一条剧情事实。
- 每条核心事实必须有来源证据。
- 覆盖率低或关键冲突未解决，不进入下游。

### 9.2 产物结构门禁

- JSON 可解析。
- 类型正确。
- 必填字段完整。
- 分集数量连续且与大纲一致。
- 角色名、场景名不重复。
- 分镜序号连续，视频提示词非空。

### 9.3 一致性门禁

- 大纲不得偏离剧本主题。
- 分集不得新增无来源主线事件。
- 分镜引用的角色和场景必须存在。
- 视频提示词中的人物、动作、情绪、场景和道具必须能追溯到剧情事实或一致性基准。
- 相邻分镜不得出现无剧情依据的人物状态、位置、服装、场景跳变。

## 10. 数据库最小增量

一期建议新增四张表：

### `script_understandings`

剧情事实底座。

关键字段：

- `tenant_id`
- `project_id`
- `asset_id`
- `understanding_json`
- `evidence_hash`
- `coverage_report_json`
- `quality_status`
- `quality_issues_json`

### `project_consistency_bibles`

跨步骤一致性基准。

关键字段：

- `tenant_id`
- `project_id`
- `bible_json`
- `source_version`
- `locked_fields_json`

### `agent_run_plans`

运行计划快照。

关键字段：

- `run_id`
- `run_mode`
- `planned_steps_json`
- `skipped_steps_json`
- `step_inputs_json`
- `quality_rules_json`
- `model_policy_json`
- `context_options_json`
- `idempotency_key`

### `agent_prompt_snapshots`

Prompt、模型响应、解析和校验审计。

关键字段：

- `run_id`
- `step_key`
- `prompt_role`
- `system_prompt_version`
- `context_hash`
- `context_summary`
- `request_json`
- `response_raw`
- `parsed_output_json`
- `validation_result_json`
- `model_provider`
- `model_id`
- `latency_ms`
- `error_message`

## 11. 后端落地

建议在 `yaoai-agent` 新增：

- `RunIntentResolver`
- `RunContextLoader`
- `RunModeRouter`
- `RunPlanExecutor`
- `ScriptUnderstandingService`
- `ConsistencyBibleService`
- `QualityGateService`
- `ConsistencyGateService`
- `PromptSnapshotService`

建议在 `yaoai-pipeline` 新增或扩展：

- `ScriptUnderstandingPromptContext`
- `OutlinePromptContext`
- `EpisodePromptContext`
- `AssetPromptContext`
- `StoryboardPromptContext`
- `PromptAssemblyService`

现有 Pipeline 保持旧方法兼容，新增上下文驱动方法：

```java
ScriptUnderstanding understandScript(ScriptUnderstandingPromptContext context);
Outline generateOutline(OutlinePromptContext context);
List<Episode> generateEpisodes(EpisodePromptContext context);
List<Character> extractCharacters(AssetPromptContext context);
List<Scene> extractScenes(AssetPromptContext context);
List<Storyboard> generateStoryboards(StoryboardPromptContext context);
```

## 12. 前端落地

`AgentStudio` 需要从进度页升级为运行解释页：

- 运行意图选择: 自动、续跑失败、局部补齐、强制重跑。
- 剧情理解面板: 展示剧情事实、人物关系、关键场景、不确定项。
- 用户确认入口: 关键不确定项存在时，允许用户确认或修正后再继续。
- 一致性面板: 展示角色视觉锚点、场景空间锚点、项目风格和锁定字段。
- 漂移提醒: 展示某次生成偏离了哪个剧情事实、角色、场景或风格规则。
- 计划展示: 本次会执行哪些步骤、跳过哪些步骤、为什么跳过。

## 13. 分阶段实施

### Phase 0: 快速止血

目标：解决有剧本仍按 `goal` 发散、未理解剧本就生成的问题。

- 读取 `project_assets.asset_type = script`。
- 新增最小 `ScriptUnderstandingService`。
- `outline_gen` 前优先使用剧情事实。
- 没有剧本才使用 `goal`。

验收：

- 上传剧本后，先生成剧情事实摘要和证据引用。
- 大纲明显基于剧情事实，而不是默认目标。

### Phase 1: 计划与路由

- 新增 `RunIntentResolver`、`RunModeRouter`、`RunPlan`。
- 新增 `agent_run_plans`。
- 支持 `script_based`、`outline_continue`、`storyboard_only`、`resume_failed`。
- `graph_steps` 由计划动态创建。

### Phase 2: Prompt 协议化与门禁

- 新增 `PromptAssemblyService`。
- 新增 `QualityGateService`。
- 剧情理解、大纲、分集、角色、场景、分镜接入结构校验。
- 新增 `agent_prompt_snapshots`。

### Phase 3: 一致性基准与漂移检测

- 新增 `project_consistency_bibles`。
- 新增 `ConsistencyBibleService`。
- 新增 `ConsistencyGateService`。
- 检查剧情、角色、人物视觉、场景、风格、画面连续性漂移。

### Phase 4: 分镜与提示词追溯

- 分镜生成显式引用剧情事实、角色、场景。
- 视频提示词基于中间结构生成。
- 视频提示词必须能追溯到 `sourceFactIds / characterRefs / sceneRef`。

### Phase 5: 前端解释与后台审计

- AgentStudio 展示剧情理解、运行计划、一致性基准、漂移提醒。
- 管理端可查询 Prompt 快照和失败记录。

## 14. 验收标准

功能验收：

- 有剧本时先抽取剧情事实和证据，再生成大纲、角色、场景、分镜和提示词。
- 支持根据项目状态动态计划步骤。
- 支持已有大纲、分集、角色、场景时跳过对应步骤。
- 支持失败续跑。
- 支持 Prompt 快照、剧情理解快照、一致性基准。

效果验收：

- 大纲偏离剧本的问题明显下降。
- 角色、场景、分镜、视频提示词能回溯到剧情事实或原文证据。
- 同一角色跨集、跨镜头的人物视觉锚点保持稳定。
- 同一场景跨镜头的空间结构、主色调、光线方向保持稳定。
- 图像 Prompt、视频 Prompt、分镜描述的整体风格一致。

工程验收：

- `ScriptUnderstandingService` 具备切片、事实合并、覆盖率、冲突检测测试。
- `RunModeRouter` 具备规则路由测试。
- `QualityGateService` 具备剧情理解、大纲、分集、资产、分镜校验测试。
- `ConsistencyGateService` 具备角色视觉、场景空间、风格冲突、相邻分镜连续性测试。
- 旧 API 行为兼容，不影响已有手动生成入口。

## 15. 风险与应对

| 风险 | 应对 |
|---|---|
| 剧本正文过长导致 Token 过高 | 切片抽取事实，保存摘要和证据哈希 |
| 剧情理解抽错导致后续全部偏离 | 将剧情理解独立落库并展示，关键不确定项要求用户确认 |
| 模型把推测当事实 | 核心事实必须带证据，无证据内容进入 `uncertainties` |
| 一致性基准过死导致画面缺少变化 | 区分 locked anchor 和 flexible variation |
| 角色视觉锚点靠文本仍不够稳定 | 后续结合角色参考图和图片 key 作为高优先级视觉事实 |
| 动态链路一次改造过大 | 先做 Phase 0 止血，再逐步替换固定执行器 |

## 16. 附录

为避免主 PRD 过长导致界面加载失败，详细结构拆到附录：

- [18-Agent剧情理解与一致性附录.md](/Users/linshizhanghu/Documents/yaoai-video/design-docs/18-Agent剧情理解与一致性附录.md)
- [18-Agent实施细节附录.md](/Users/linshizhanghu/Documents/yaoai-video/design-docs/18-Agent实施细节附录.md)

