# 18 · Agent 实施细节附录

> 主文档: [18-Agent升级方案PRD.md](/Users/linshizhanghu/Documents/yaoai-video/design-docs/18-Agent升级方案PRD.md)  
> 用途: 记录数据库、后端服务、前端页面和验收测试的落地细节。

## 1. 新增表

### 1.1 `script_understandings`

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | bigint | 主键 |
| `tenant_id` | bigint | 租户 ID |
| `project_id` | bigint | 项目 ID |
| `asset_id` | bigint | 来源剧本资产 ID |
| `understanding_json` | json | 剧情事实、角色事实、场景事实、不确定项 |
| `evidence_hash` | varchar(64) | 原文证据摘要哈希 |
| `coverage_report_json` | json | 剧情覆盖率、缺失片段、冲突事实 |
| `quality_status` | varchar(32) | PASSED / NEED_CONFIRMATION / FAILED |
| `quality_issues_json` | json | 剧情理解问题 |
| `created_at` | datetime(3) | 创建时间 |
| `updated_at` | datetime(3) | 更新时间 |

### 1.2 `project_consistency_bibles`

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | bigint | 主键 |
| `tenant_id` | bigint | 租户 ID |
| `project_id` | bigint | 项目 ID |
| `bible_json` | json | 剧情、角色、场景、风格、画面基准 |
| `source_version` | varchar(64) | 来源版本，如 outline_v1 / manual_v2 |
| `locked_fields_json` | json | 人工锁定字段 |
| `created_at` | datetime(3) | 创建时间 |
| `updated_at` | datetime(3) | 更新时间 |

### 1.3 `agent_run_plans`

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | bigint | 主键 |
| `run_id` | bigint | `graph_runs.id` |
| `run_mode` | varchar(64) | 运行模式 |
| `reasoning_summary` | text | 计划说明 |
| `planned_steps_json` | json | 计划步骤 |
| `skipped_steps_json` | json | 跳过步骤与原因 |
| `step_inputs_json` | json | 每步上下文输入 |
| `quality_rules_json` | json | 质量规则 |
| `model_policy_json` | json | 模型策略 |
| `context_options_json` | json | 上下文开关 |
| `idempotency_key` | varchar(128) | 幂等键 |
| `plan_version` | varchar(32) | 计划版本 |
| `created_at` | datetime(3) | 创建时间 |

### 1.4 `agent_prompt_snapshots`

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | bigint | 主键 |
| `run_id` | bigint | 运行 ID |
| `step_key` | varchar(64) | 步骤标识 |
| `prompt_role` | varchar(64) | outline / episode / asset / storyboard / review |
| `system_prompt_version` | varchar(64) | Prompt 版本 |
| `context_hash` | varchar(64) | 上下文哈希 |
| `context_summary` | text | 上下文摘要 |
| `request_json` | json | 模型请求快照，注意脱敏 |
| `response_raw` | longtext | 原始响应 |
| `parsed_output_json` | json | 解析结果 |
| `validation_result_json` | json | 校验结果 |
| `model_provider` | varchar(64) | 当前应为 `volcengine` |
| `model_id` | varchar(128) | 方舟模型 ID |
| `latency_ms` | bigint | 耗时 |
| `error_message` | text | 错误信息 |
| `created_at` | datetime(3) | 创建时间 |

## 2. 后端服务

建议在 `yaoai-agent` 新增：

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

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

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

新增上下文驱动方法：

```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);
```

旧方法保留并包装新方法，避免破坏现有手动生成入口。

## 3. 前端页面

`AgentStudio` 需要增加：

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

## 4. 分阶段实施

### Phase 0: 快速止血

- 读取 `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 快照和失败记录。

## 5. 验收测试

核心测试：

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

