# AI生成

<cite>
**本文引用的文件**
- [main.py](file://main.py)
- [PROJECT_README.md](file://PROJECT_README.md)
- [requirements.txt](file://requirements.txt)
- [backend/scripter.py](file://backend/scripter.py)
- [backend/extractor.py](file://backend/extractor.py)
- [backend/data_builder.py](file://backend/data_builder.py)
- [backend/media_fetcher.py](file://backend/media_fetcher.py)
- [backend/video_processor/schemas.py](file://backend/video_processor/schemas.py)
- [backend/video_processor/utils.py](file://backend/video_processor/utils.py)
- [tests/test_video_cli.py](file://tests/test_video_cli.py)
- [tests/test_video_processor.py](file://tests/test_video_processor.py)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本项目是一个“自动人生规划视频生成器”，通过将PDF版人生规划报告与采访视频，结合AI生成的自然日语旁白、图表动画与B-Roll素材，最终合成3-5分钟的个性化解释性视频。其中，scripter.py模块负责使用Google Gemini Pro API将结构化的财务数据转化为自然流畅的日语旁白脚本。本文围绕该模块展开，详细说明提示词工程设计（如何整合客户数据、财务预测与视频节奏要求）、在主流程中的位置与输入输出格式、以及面向初学者的流程图与面向高级开发者的实现细节与优化建议。

## 项目结构
- 后端Python模块位于 backend/，包含：
  - scripter.py：脚本生成器（当前为占位实现）
  - extractor.py：PDF与视频抽取器（当前为占位实现）
  - data_builder.py：财务模拟与图表数据构建
  - media_fetcher.py：B-Roll素材抓取（当前为占位实现）
  - video_processor/：视频处理工具与数据结构（供未来集成）
- 前端Remotion渲染引擎位于 frontend/，通过 render_props.json 与后端对接
- main.py 作为入口，编排整个流水线

```mermaid
graph TB
A["main.py<br/>入口与流水线编排"] --> B["backend/scripter.py<br/>脚本生成器"]
A --> C["backend/extractor.py<br/>PDF/视频抽取器"]
A --> D["backend/data_builder.py<br/>财务模拟与图表数据"]
A --> E["backend/media_fetcher.py<br/>B-Roll素材抓取"]
A --> F["frontend/<br/>Remotion渲染引擎"]
G["backend/video_processor/schemas.py<br/>视频处理数据结构"] -. 可选集成 .-> A
H["backend/video_processor/utils.py<br/>FFmpeg工具集"] -. 可选集成 .-> A
```

**图表来源**
- [main.py](file://main.py#L48-L84)
- [backend/scripter.py](file://backend/scripter.py#L14-L69)
- [backend/extractor.py](file://backend/extractor.py#L15-L84)
- [backend/data_builder.py](file://backend/data_builder.py#L150-L200)
- [backend/media_fetcher.py](file://backend/media_fetcher.py#L15-L72)
- [backend/video_processor/schemas.py](file://backend/video_processor/schemas.py#L12-L91)
- [backend/video_processor/utils.py](file://backend/video_processor/utils.py#L13-L164)

**章节来源**
- [main.py](file://main.py#L48-L84)
- [PROJECT_README.md](file://PROJECT_README.md#L132-L141)

## 核心组件
- 脚本生成器（ScriptGenerator）：封装Gemini Pro调用、提示词构建、响应解析与时长估计
- PDF/视频抽取器（PDFExtractor/VideoExtractor）：从PDF与视频中提取结构化数据与时间戳
- 财务模拟器（FinancialSimulator）：基于参数模拟资产枯竭与现金流，生成图表所需数据
- B-Roll素材抓取器（MediaFetcher）：根据关键词检索并下载B-Roll素材
- 视频处理工具（VideoProcessor）：提供视频分析与切片等能力（可选）

**章节来源**
- [backend/scripter.py](file://backend/scripter.py#L14-L69)
- [backend/extractor.py](file://backend/extractor.py#L15-L84)
- [backend/data_builder.py](file://backend/data_builder.py#L15-L115)
- [backend/media_fetcher.py](file://backend/media_fetcher.py#L15-L72)
- [backend/video_processor/schemas.py](file://backend/video_processor/schemas.py#L12-L91)
- [backend/video_processor/utils.py](file://backend/video_processor/utils.py#L13-L164)

## 架构总览
脚本生成在整体流水线中的位置如下：

```mermaid
sequenceDiagram
participant U as "用户"
participant M as "main.py<br/>VideoGeneratorPipeline"
participant X as "extractor.py<br/>PDF/视频抽取"
participant S as "scripter.py<br/>ScriptGenerator"
participant D as "data_builder.py<br/>财务模拟"
participant R as "Remotion<br/>前端渲染"
U->>M : 运行命令行
M->>X : 提取PDF/视频数据
X-->>M : 返回结构化数据
M->>S : 生成旁白脚本
S-->>M : 返回脚本片段与同步点
M->>D : 构建图表数据
D-->>M : 返回资产/现金流数据
M->>R : 写入render_props.json并触发渲染
R-->>U : 输出MP4视频
```

**图表来源**
- [main.py](file://main.py#L48-L84)
- [backend/scripter.py](file://backend/scripter.py#L22-L49)
- [backend/data_builder.py](file://backend/data_builder.py#L150-L200)

**章节来源**
- [main.py](file://main.py#L48-L84)
- [PROJECT_README.md](file://PROJECT_README.md#L132-L141)

## 详细组件分析

### ScriptGenerator（脚本生成器）
- 职责
  - 初始化：从环境变量读取API密钥，校验可用性
  - generate：接收PDF数据与可选视频数据，返回包含分段、总时长与同步点的结构化脚本
  - _build_prompt：构建提示词（当前为占位），应整合客户信息、财务预测、风格约束与输出格式要求
- 输入输出
  - 输入：pdf_data（结构化财务数据）、video_data（可选，含转录与时间戳）、style（友好/专业/随意）
  - 输出：包含segments（脚本文本、时长、类型）、total_duration、sync_points
- 设计要点
  - 风格控制：通过style参数与提示词工程控制语气与专业度
  - 结构化输出：要求模型以JSON格式返回segments，便于后续解析与时长估算
  - 多模态融合：将视频转录的时间戳与脚本同步点对齐，提升节奏一致性

```mermaid
classDiagram
class ScriptGenerator {
+api_key : str
+__init__(api_key)
+generate(pdf_data, video_data, style) Dict
-_build_prompt(pdf_data, style) str
}
```

**图表来源**
- [backend/scripter.py](file://backend/scripter.py#L14-L69)

**章节来源**
- [backend/scripter.py](file://backend/scripter.py#L14-L69)

### 提示词工程设计（Prompt Engineering）
- 数据整合
  - 客户数据：姓名、年龄、退休年龄、寿命预期、资产、收入、支出等
  - 财务预测：来自data_builder.py的资产枯竭与现金流数据，用于生成“现状”“趋势”“风险预警”等段落
  - 视频节奏：来自extractor.py的视频转录与时间戳，用于生成“配合画面”的过渡与强调段落
- 风格与语气
  - friendly：自然、温和、易懂
  - professional：严谨、准确、适合正式场合
  - casual：轻松、口语化、贴近日常
- 输出约束
  - JSON格式，包含segments数组，每段含id、text、duration、type
  - 总时长控制在3-5分钟范围内
- 同步点
  - 在脚本中标注chart/intro/transition等类型，便于后续与图表动画与B-Roll素材对齐

提示词模板设计要点（概念性说明，不对应具体代码）：
- 角色设定：你是专业的财务顾问，用日语向客户讲解其人生规划
- 上下文：提供客户画像与财务预测摘要
- 任务：生成一段自然流畅的旁白，包含引言、现状分析、趋势解读、风险提示与建议
- 风格：根据style参数调整语气
- 输出：严格遵循JSON结构，包含分段文本与时长

**章节来源**
- [backend/scripter.py](file://backend/scripter.py#L22-L49)
- [backend/data_builder.py](file://backend/data_builder.py#L150-L200)
- [backend/extractor.py](file://backend/extractor.py#L23-L41)

### main.py 中的 generate_script 方法
- 位置：VideoGeneratorPipeline.generate_script
- 功能：调用后端脚本生成模块，返回结构化脚本
- 当前实现：占位返回mock脚本，包含segments列表
- 实际实现建议：调用ScriptGenerator.generate，传入pdf_data与video_data，解析返回的JSON并估算每段时长

```mermaid
flowchart TD
Start(["进入 generate_script"]) --> CheckArgs["检查输入参数<br/>pdf_data, video_data"]
CheckArgs --> CallGen["调用 ScriptGenerator.generate(...)"]
CallGen --> ParseResp["解析返回的JSON结构<br/>segments, total_duration, sync_points"]
ParseResp --> EstimateDur["估算每段时长<br/>按目标时长比例分配"]
EstimateDur --> ReturnScript["返回结构化脚本"]
```

**图表来源**
- [main.py](file://main.py#L115-L134)
- [backend/scripter.py](file://backend/scripter.py#L22-L49)

**章节来源**
- [main.py](file://main.py#L115-L134)

### 财务数据与脚本的衔接
- data_builder.py 模块根据pdf_data生成资产枯竭与现金流数据，供前端图表使用
- scripter.py 应在提示词中引用这些数据摘要，使脚本内容与图表一致
- 通过style参数与提示词工程，确保脚本语气与数据呈现相匹配

**章节来源**
- [backend/data_builder.py](file://backend/data_builder.py#L150-L200)
- [backend/scripter.py](file://backend/scripter.py#L22-L49)

### B-Roll素材与脚本的协同
- media_fetcher.py 的fetch_broll函数可根据脚本关键词检索B-Roll素材
- 关键词提取：从segments.text中抽取主题词，如“資産”“将来”“リスク”等
- 同步：将脚本的sync_points与B-Roll片段起止时间对齐，提升观看体验

**章节来源**
- [backend/media_fetcher.py](file://backend/media_fetcher.py#L15-L72)
- [backend/scripter.py](file://backend/scripter.py#L22-L49)

### 视频处理（可选集成）
- schemas.py 定义了VideoSegment、KeyMoment、VideoAnalysisResult等数据结构
- utils.py 提供FFmpeg封装，支持时长查询、音频提取、视频切片
- 可选策略：audio-first或direct，用于抽取视频转录与时间戳，辅助scripter生成更贴合画面的脚本

**章节来源**
- [backend/video_processor/schemas.py](file://backend/video_processor/schemas.py#L12-L91)
- [backend/video_processor/utils.py](file://backend/video_processor/utils.py#L13-L164)
- [tests/test_video_cli.py](file://tests/test_video_cli.py#L1-L161)
- [tests/test_video_processor.py](file://tests/test_video_processor.py#L1-L143)

## 依赖关系分析
- main.py 依赖 backend/scripter.py 生成脚本，依赖 backend/data_builder.py 生成图表数据
- backend/scripter.py 依赖环境变量中的GEMINI_API_KEY
- backend/media_fetcher.py 依赖PEXELS_API_KEY
- backend/extractor.py 依赖GEMINI_API_KEY与OPENAI_API_KEY
- 视频处理模块与main.py之间为可选集成

```mermaid
graph LR
M["main.py"] --> SG["backend/scripter.py"]
M --> DB["backend/data_builder.py"]
M --> MF["backend/media_fetcher.py"]
M --> EX["backend/extractor.py"]
SG --> ENV1["GEMINI_API_KEY"]
MF --> ENV2["PEXELS_API_KEY"]
EX --> ENV3["GEMINI_API_KEY/OPENAI_API_KEY"]
```

**图表来源**
- [main.py](file://main.py#L48-L84)
- [backend/scripter.py](file://backend/scripter.py#L17-L21)
- [backend/media_fetcher.py](file://backend/media_fetcher.py#L18-L22)
- [backend/extractor.py](file://backend/extractor.py#L18-L21)

**章节来源**
- [requirements.txt](file://requirements.txt#L1-L34)
- [PROJECT_README.md](file://PROJECT_README.md#L106-L111)

## 性能考量
- API调用成本控制
  - 使用缓存：对重复的提示词与翻译结果进行缓存，减少Gemini/Whisper调用次数
  - 批量请求：合并相似请求，避免频繁往返
- 响应解析与结构化
  - 强制JSON输出，减少后处理开销
  - 对异常响应进行重试与降级策略
- 渲染阶段
  - render_props.json尽量紧凑，避免冗余字段
  - 图表数据按需生成，避免不必要的计算

[本节为通用建议，无需特定文件引用]

## 故障排查指南
- API密钥缺失
  - 确认 .env 文件存在且包含有效密钥
  - GEMINI_API_KEY、OPENAI_API_KEY、PEXELS_API_KEY
- FFmpeg依赖
  - 使用测试脚本检查依赖安装情况
  - 若未安装，按提示安装FFmpeg与ffprobe
- 渲染失败
  - 确认前端依赖已安装
  - 检查render_props.json结构是否符合前端schema

**章节来源**
- [PROJECT_README.md](file://PROJECT_README.md#L106-L111)
- [tests/test_video_cli.py](file://tests/test_video_cli.py#L68-L91)
- [backend/video_processor/utils.py](file://backend/video_processor/utils.py#L148-L164)

## 结论
scripter.py模块是将结构化财务数据转化为自然日语旁白的关键环节。通过精心设计的提示词工程，将客户数据、财务预测与视频节奏要求有机融合，可生成既专业又富有人情味的脚本。在主流水线中，它位于PDF/视频抽取之后、图表数据构建之前，为后续B-Roll与渲染阶段提供高质量的文本基础。随着各模块逐步完善，系统将形成一条从数据到视频的完整自动化管线。

[本节为总结性内容，无需特定文件引用]

## 附录

### 实际代码示例（路径指引）
- 调整生成风格
  - 在调用处设置style参数，参考：[backend/scripter.py](file://backend/scripter.py#L22-L49)
- 添加新的解说段落类型
  - 在提示词中新增类型定义与样例，参考：[backend/scripter.py](file://backend/scripter.py#L50-L59)
- 解析与扩展脚本结构
  - 在返回后对segments进行二次加工，参考：[main.py](file://main.py#L115-L134)

### API与配置清单
- 环境变量
  - GEMINI_API_KEY：Google Gemini API
  - OPENAI_API_KEY：OpenAI Whisper
  - PEXELS_API_KEY：Pexels B-Roll
- 依赖安装
  - Python依赖：参考 [requirements.txt](file://requirements.txt#L1-L34)

**章节来源**
- [PROJECT_README.md](file://PROJECT_README.md#L106-L111)
- [requirements.txt](file://requirements.txt#L1-L34)