# 故障排除

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

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

## 简介
本指南面向使用本项目的用户与开发者，聚焦“常见问题现象—根本原因—解决方案”的闭环排查流程，并结合项目内置的结构验证脚本，帮助快速定位缺失文件、环境变量、依赖安装与渲染失败等问题。同时提供可操作的诊断步骤与修复命令，降低技术支持门槛。

## 项目结构
项目采用“Python 后端 + Node.js 前端（Remotion）”的混合架构，数据通过中间产物 JSON 在两端之间传递。关键目录与文件包括：
- assets/0_input：原始输入（PDF、MP4）
- assets/1_processed：中间产物（提取结果、翻译缓存、B-Roll下载等）
- assets/2_output：最终输出（生成的视频）
- backend：Python 模块（PDF/视频解析、脚本生成、媒体抓取、数据模拟）
- frontend：Remotion 前端工程（React + TypeScript + Recharts）
- 根目录配置：.env、requirements.txt、package.json、remotion.config.ts、verify_structure.py、main.py

```mermaid
graph TB
A["main.py<br/>主入口与流水线编排"] --> B["backend.extractor.py<br/>PDF/视频解析"]
A --> C["backend.scripter.py<br/>脚本生成"]
A --> D["backend.media_fetcher.py<br/>B-Roll抓取"]
A --> E["backend.data_builder.py<br/>财务模拟/图表数据"]
A --> F["assets/1_processed/render_props.json<br/>数据契约"]
F --> G["frontend/src/index.ts<br/>Remotion渲染入口"]
G --> H["frontend/src/components/*<br/>图表与合成组件"]
H --> I["最终视频输出<br/>assets/2_output/*.mp4"]
```

图示来源
- [main.py](file://main.py#L1-L305)
- [backend/extractor.py](file://backend/extractor.py#L1-L84)
- [backend/scripter.py](file://backend/scripter.py#L1-L69)
- [backend/media_fetcher.py](file://backend/media_fetcher.py#L1-L72)
- [backend/data_builder.py](file://backend/data_builder.py#L1-L200)

章节来源
- [PROJECT_README.md](file://PROJECT_README.md#L50-L80)
- [PROJECT_README.md](file://PROJECT_README.md#L132-L141)

## 核心组件
- 主入口与流水线编排：负责参数解析、目录准备、步骤调度与调用各模块、保存 render_props.json 并触发 Remotion 渲染。
- 数据提取器：封装 PDF 与视频解析接口，读取环境变量中的 API Key，抛出明确错误提示。
- 脚本生成器：根据 PDF 与可选视频内容生成自然语言脚本，同样依赖环境变量。
- 媒体抓取器：基于关键词从 Pexels 抓取 B-Roll 视频，依赖 Pexels API Key。
- 数据构建器：执行财务模拟，生成资产枯竭与现金流图表数据，供前端渲染使用。
- 结构验证脚本：校验目录与文件完整性、导入可用性、CLI 可用性，辅助迁移与初始化。

章节来源
- [main.py](file://main.py#L33-L301)
- [backend/extractor.py](file://backend/extractor.py#L15-L84)
- [backend/scripter.py](file://backend/scripter.py#L14-L69)
- [backend/media_fetcher.py](file://backend/media_fetcher.py#L15-L72)
- [backend/data_builder.py](file://backend/data_builder.py#L1-L200)
- [verify_structure.py](file://verify_structure.py#L1-L136)

## 架构总览
下图展示从输入到输出的端到端流程，以及关键错误点的定位位置。

```mermaid
sequenceDiagram
participant U as "用户"
participant M as "main.py"
participant X as "extractor.py"
participant S as "scripter.py"
participant MF as "media_fetcher.py"
participant DB as "data_builder.py"
participant R as "Remotion渲染"
participant O as "assets/2_output"
U->>M : 运行命令传入PDF/可选视频
M->>X : 提取PDF/视频数据
X-->>M : 返回结构化数据或报错
M->>S : 生成脚本
S-->>M : 返回脚本或报错
M->>MF : 抓取B-Roll
MF-->>M : 返回资源或报错
M->>DB : 构建图表数据
DB-->>M : 返回render_props.json
M->>R : 触发渲染npx remotion render
R-->>O : 输出最终视频
```

图示来源
- [main.py](file://main.py#L48-L225)
- [backend/extractor.py](file://backend/extractor.py#L23-L42)
- [backend/scripter.py](file://backend/scripter.py#L22-L48)
- [backend/media_fetcher.py](file://backend/media_fetcher.py#L25-L41)
- [backend/data_builder.py](file://backend/data_builder.py#L150-L200)

## 详细组件分析

### 组件A：主入口与流水线编排
- 功能要点
  - 参数解析与配置合并（支持 --pdf/--video/--config/--output/--dry-run）
  - 自动创建 assets 子目录
  - 步骤顺序：PDF 解析 → 视频解析（可选）→ 脚本生成 → B-Roll 抓取 → 图表数据构建 → 保存 render_props.json → 触发渲染
  - 渲染命令通过 npx remotion render 执行，当前处于占位状态（注释掉实际子进程调用）
- 关键错误点
  - 缺少必要参数时直接报错
  - 渲染阶段若未启用实际子进程调用，会显示占位信息而非真实错误
- 优化建议
  - 在渲染阶段取消注释子进程调用，确保错误能被上层捕获
  - 将 dry-run 与渲染阶段解耦，便于独立调试

```mermaid
flowchart TD
Start(["开始"]) --> Parse["解析参数与配置"]
Parse --> MkDirs["创建assets子目录"]
MkDirs --> Step1["Step 1: PDF解析"]
Step1 --> Step2["Step 2: 视频解析可选"]
Step2 --> Step3["Step 3: 生成脚本"]
Step3 --> Step4["Step 4: 抓取B-Roll"]
Step4 --> Step5["Step 5: 构建图表数据"]
Step5 --> SaveProps["保存render_props.json"]
SaveProps --> Render["触发Remotion渲染"]
Render --> End(["结束"])
```

图示来源
- [main.py](file://main.py#L48-L225)

章节来源
- [main.py](file://main.py#L228-L301)

### 组件B：数据提取器（PDF/视频）
- 功能要点
  - PDFExtractor：从 PDF 中抽取结构化数据，需要 GEMINI_API_KEY
  - VideoExtractor：对视频进行转录与时间戳抽取，需要 OPENAI_API_KEY
- 错误处理
  - 若环境变量缺失，直接抛出异常，提示缺少对应 API Key
- 诊断要点
  - 确认 .env 文件存在且包含有效密钥
  - 确认网络可达与配额充足

```mermaid
classDiagram
class PDFExtractor {
+__init__(api_key)
+extract(pdf_path) Dict
}
class VideoExtractor {
+__init__(api_key)
+extract(video_path) Dict
}
PDFExtractor <.. VideoExtractor : "均依赖环境变量"
```

图示来源
- [backend/extractor.py](file://backend/extractor.py#L15-L84)

章节来源
- [backend/extractor.py](file://backend/extractor.py#L15-L84)

### 组件C：脚本生成器
- 功能要点
  - 基于 PDF 与可选视频内容生成自然语言脚本，需要 GEMINI_API_KEY
- 错误处理
  - 环境变量缺失时抛出异常
- 诊断要点
  - 配置 .env 并确认 Gemini API 可用

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

### 组件D：媒体抓取器（B-Roll）
- 功能要点
  - 依据关键词从 Pexels 搜索并下载 B-Roll，需要 PEKELS_API_KEY
- 错误处理
  - 环境变量缺失时抛出异常
- 诊断要点
  - 配置 .env 并确认 Pexels API 可用

章节来源
- [backend/media_fetcher.py](file://backend/media_fetcher.py#L15-L41)

### 组件E：数据构建器（财务模拟）
- 功能要点
  - 使用默认通胀率、赤字利率、投资回报率等参数进行年金模拟，生成资产枯竭与现金流数据
- 错误处理
  - 无显式异常处理，需在上游保证输入数据合法
- 诊断要点
  - 确保 PDF 解析返回的数据字段齐全

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

## 依赖关系分析
- Python 依赖
  - dotenv：加载 .env
  - ffmpeg-python、requests：媒体处理与网络请求
  - tqdm、rich：进度与日志
- Node.js 依赖
  - remotion、react、recharts：渲染引擎与图表
  - 开发工具链：ESLint、TypeScript、Prettier
- 外部服务
  - Google Gemini API（PDF 解析、脚本生成）
  - OpenAI Whisper（音频转录）
  - Pexels API（B-Roll）

```mermaid
graph LR
subgraph "Python"
P1["dotenv"]
P2["ffmpeg-python"]
P3["requests"]
P4["tqdm/rich"]
end
subgraph "Node.js"
N1["remotion"]
N2["react/recharts"]
N3["typescript/eslint/prettier"]
end
subgraph "外部服务"
E1["Gemini API"]
E2["OpenAI Whisper"]
E3["Pexels API"]
end
P1 --> E1
P2 --> E2
P3 --> E3
N1 --> E3
```

图示来源
- [requirements.txt](file://requirements.txt#L1-L34)
- [package.json](file://package.json#L1-L43)

章节来源
- [requirements.txt](file://requirements.txt#L1-L34)
- [package.json](file://package.json#L1-L43)

## 性能注意事项
- API 调用成本与配额
  - Gemini、Whisper、Pexels 均有配额限制，建议在本地或 CI 中合理控制并发与重试策略
- 渲染性能
  - Remotion 渲染耗时与图表复杂度、B-Roll 视频长度相关，建议先使用 dry-run 生成数据以验证流程
- 本地依赖
  - FFmpeg 安装与可用性直接影响视频转录与处理，建议在测试前单独验证

[本节为通用指导，不直接分析具体文件]

## 故障排除指南

### 一、环境变量与密钥问题
- 现象
  - “API 密钥未找到”
- 根因
  - .env 文件缺失或未正确填写；或运行环境中未加载 .env
- 修复步骤
  - 复制示例文件并填写密钥
    - 复制命令参考：[PROJECT_README.md](file://PROJECT_README.md#L99-L111)
    - 示例文件路径：[.env.example](file://.env.example#L1-L23)
  - 确认密钥类型与来源
    - Gemini：用于 PDF 解析与脚本生成
    - OpenAI：用于 Whisper 转录
    - Pexels：用于 B-Roll 下载
- 验证方法
  - 运行结构验证脚本，检查后端模块导入是否成功
    - 参考：[verify_structure.py](file://verify_structure.py#L75-L97)

章节来源
- [PROJECT_README.md](file://PROJECT_README.md#L97-L111)
- [.env.example](file://.env.example#L1-L23)
- [verify_structure.py](file://verify_structure.py#L75-L97)

### 二、PDF 提取失败
- 现象
  - PDF 解析阶段报错或返回空数据
- 根因
  - PDF 不可读或受密码保护；Gemini API 额度不足或网络异常
- 修复步骤
  - 确保输入 PDF 可打开且非加密
  - 检查 .env 中 GEMINI_API_KEY 是否正确
  - 如为首次使用，确认 API 已激活并有足够配额
- 验证方法
  - 使用 verify_structure.py 的导入测试，确认 extractor 模块可用
    - 参考：[verify_structure.py](file://verify_structure.py#L75-L97)
  - 查看 extractor 抛出的异常信息（缺少密钥时会直接报错）
    - 参考：[backend/extractor.py](file://backend/extractor.py#L18-L22)

章节来源
- [PROJECT_README.md](file://PROJECT_README.md#L228-L231)
- [backend/extractor.py](file://backend/extractor.py#L18-L22)
- [verify_structure.py](file://verify_structure.py#L75-L97)

### 三、视频转录失败
- 现象
  - 视频解析阶段报错或无法生成时间戳
- 根因
  - 缺少 OPENAI_API_KEY；FFmpeg 未安装或不可用；视频格式不受支持
- 修复步骤
  - 安装 FFmpeg 并确保在 PATH 中
    - 参考：[tests/test_video_cli.py](file://tests/test_video_cli.py#L71-L80)
  - 确认 .env 中 OPENAI_API_KEY 已设置
  - 使用独立测试工具检查依赖
    - 参考：[tests/test_video_cli.py](file://tests/test_video_cli.py#L68-L91)
- 验证方法
  - 运行单元测试（需 OPENAI_API_KEY），验证音频优先策略
    - 参考：[tests/test_video_processor.py](file://tests/test_video_processor.py#L113-L140)

章节来源
- [tests/test_video_cli.py](file://tests/test_video_cli.py#L68-L91)
- [tests/test_video_processor.py](file://tests/test_video_processor.py#L113-L140)
- [backend/extractor.py](file://backend/extractor.py#L48-L51)

### 四、B-Roll 抓取失败
- 现象
  - B-Roll 获取阶段报错或返回空结果
- 根因
  - 缺少 PEKELS_API_KEY；网络异常；关键词为空
- 修复步骤
  - 确认 .env 中 PEKELS_API_KEY 已设置
  - 检查网络连通性与 API 配额
- 验证方法
  - 运行结构验证脚本，确认 media_fetcher 模块可用
    - 参考：[verify_structure.py](file://verify_structure.py#L75-L97)
  - 查看 media_fetcher 抛出的异常信息（缺少密钥时会直接报错）
    - 参考：[backend/media_fetcher.py](file://backend/media_fetcher.py#L18-L21)

章节来源
- [PROJECT_README.md](file://PROJECT_README.md#L228-L231)
- [backend/media_fetcher.py](file://backend/media_fetcher.py#L18-L21)
- [verify_structure.py](file://verify_structure.py#L75-L97)

### 五、Remotion 渲染失败
- 现象
  - 渲染阶段报错或无输出
- 根因
  - Node.js 依赖未安装；Remotion 配置不正确；前端组件缺失；渲染命令未启用
- 修复步骤
  - 安装 Node.js 依赖
    - 参考：[PROJECT_README.md](file://PROJECT_README.md#L91-L95)
    - 依赖清单：[package.json](file://package.json#L1-L43)
  - 确认 frontend/src 目录结构与组件注册正确
    - 参考：[PROJECT_README.md](file://PROJECT_README.md#L50-L80)
  - 检查 remotion.config.ts 是否存在
    - 参考：[PROJECT_README.md](file://PROJECT_README.md#L56-L58)
  - 在 main.py 中启用渲染子进程调用（当前为占位）
    - 参考：[main.py](file://main.py#L217-L225)
- 验证方法
  - 使用 verify_structure.py 的 CLI 测试，确认 main.py --help 可用
    - 参考：[verify_structure.py](file://verify_structure.py#L98-L121)

章节来源
- [PROJECT_README.md](file://PROJECT_README.md#L91-L95)
- [PROJECT_README.md](file://PROJECT_README.md#L50-L80)
- [package.json](file://package.json#L1-L43)
- [main.py](file://main.py#L217-L225)
- [verify_structure.py](file://verify_structure.py#L98-L121)

### 六、项目目录结构完整性检查
- 现象
  - 运行后提示某些文件缺失或导入失败
- 根因
  - 迁移或克隆后遗漏关键目录/文件
- 修复步骤
  - 使用结构验证脚本一次性检查所有必需项
    - 参考：[verify_structure.py](file://verify_structure.py#L12-L74)
  - 若缺失，请对照项目结构补充
    - 参考：[PROJECT_README.md](file://PROJECT_README.md#L50-L80)
- 验证方法
  - 运行导入测试，确认 backend 包与子模块均可导入
    - 参考：[verify_structure.py](file://verify_structure.py#L75-L97)
  - 运行 CLI 测试，确认 main.py --help 可用
    - 参考：[verify_structure.py](file://verify_structure.py#L98-L121)

章节来源
- [verify_structure.py](file://verify_structure.py#L12-L74)
- [verify_structure.py](file://verify_structure.py#L75-L97)
- [verify_structure.py](file://verify_structure.py#L98-L121)
- [PROJECT_README.md](file://PROJECT_README.md#L50-L80)

### 七、Dry Run 与数据验证
- 现象
  - 希望跳过渲染阶段，仅生成数据
- 根因
  - 未使用 --dry-run 参数
- 修复步骤
  - 使用 --dry-run 生成 render_props.json，随后手动检查
    - 参考：[PROJECT_README.md](file://PROJECT_README.md#L126-L130)
- 验证方法
  - 检查 assets/1_processed/render_props.json 是否生成
    - 参考：[main.py](file://main.py#L72-L77)

章节来源
- [PROJECT_README.md](file://PROJECT_README.md#L126-L130)
- [main.py](file://main.py#L72-L77)

### 八、Python 依赖缺失
- 现象
  - 导入 backend 模块时报错或功能受限
- 根因
  - requirements.txt 未安装或版本不匹配
- 修复步骤
  - 安装 Python 依赖
    - 参考：[PROJECT_README.md](file://PROJECT_README.md#L87-L90)
    - 依赖清单：[requirements.txt](file://requirements.txt#L1-L34)
- 验证方法
  - 运行 verify_structure.py 的导入测试
    - 参考：[verify_structure.py](file://verify_structure.py#L75-L97)

章节来源
- [PROJECT_README.md](file://PROJECT_README.md#L87-L90)
- [requirements.txt](file://requirements.txt#L1-L34)
- [verify_structure.py](file://verify_structure.py#L75-L97)

## 结论
本指南围绕“环境变量、API 密钥、依赖安装、数据提取、脚本生成、B-Roll 抓取、财务模拟、Remotion 渲染”八个关键环节，提供了系统化的诊断与修复路径。配合 verify_structure.py 的结构检查与 dry-run 数据验证，可显著降低问题定位成本，提升整体使用体验。

[本节为总结性内容，不直接分析具体文件]

## 附录

### A. 常见命令速查
- 安装 Python 依赖
  - 参考：[PROJECT_README.md](file://PROJECT_README.md#L87-L90)
- 安装 Node.js 依赖
  - 参考：[PROJECT_README.md](file://PROJECT_README.md#L91-L95)
- 运行结构验证
  - 参考：[verify_structure.py](file://verify_structure.py#L128-L136)
- 生成数据（跳过渲染）
  - 参考：[PROJECT_README.md](file://PROJECT_README.md#L126-L130)
- 检查 FFmpeg 依赖
  - 参考：[tests/test_video_cli.py](file://tests/test_video_cli.py#L71-L80)

### B. 关键文件清单
- 环境变量模板：[.env.example](file://.env.example#L1-L23)
- Python 依赖清单：[requirements.txt](file://requirements.txt#L1-L34)
- Node.js 依赖清单：[package.json](file://package.json#L1-L43)
- 主入口与流水线：[main.py](file://main.py#L1-L305)
- 结构验证脚本：[verify_structure.py](file://verify_structure.py#L1-L136)
- 数据提取器：[backend/extractor.py](file://backend/extractor.py#L1-L84)
- 脚本生成器：[backend/scripter.py](file://backend/scripter.py#L1-L69)
- 媒体抓取器：[backend/media_fetcher.py](file://backend/media_fetcher.py#L1-L72)
- 数据构建器：[backend/data_builder.py](file://backend/data_builder.py#L1-L200)
- 视频处理测试工具：[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)