8.8 KiB
核心功能
**本文档中引用的文件** - [extractor.py](file://backend/extractor.py) - [scripter.py](file://backend/scripter.py) - [media_fetcher.py](file://backend/media_fetcher.py) - [data_builder.py](file://backend/data_builder.py) - [index.ts](file://src/index.ts) - [Root.tsx](file://src/Root.tsx) - [types.ts](file://src/types.ts) - [main.py](file://main.py) - [PROJECT_README.md](file://PROJECT_README.md)目录
简介
本项目是一个混合型Python/Node.js系统，能够将静态的财务规划报告（PDF）和原始访谈视频自动转换为动态、个性化的3-5分钟解说视频。系统整合了动画图表、AI生成的日语解说、情境化素材片段（B-Roll）以及同步的访谈剪辑，为用户提供直观的财务规划可视化服务。整个流程由Python后端驱动，利用AI模型进行数据提取和内容生成，再通过Remotion前端引擎完成视频渲染。
项目结构
项目采用分层架构，清晰地分离了数据处理逻辑与视频渲染逻辑。后端（Python）负责数据提取、AI生成和模拟计算，前端（Node.js/TypeScript）则专注于程序化视频渲染。两者通过一个名为render_props.json的数据契约文件进行通信。
graph TD
subgraph "Backend (Python)"
A[extractor.py] --> B[scripter.py]
B --> C[media_fetcher.py]
C --> D[data_builder.py]
D --> E[main.py]
end
subgraph "Frontend (Node.js/TypeScript)"
F[index.ts]
G[Root.tsx]
H[CashFlowChart.tsx]
I[LifePlanChart.tsx]
end
E --> |生成| J[render_props.json]
J --> |消费| F
Diagram sources
Section sources
核心组件
系统的核心功能由五个关键模块构成：PDF/视频数据提取器、AI日语解说脚本生成器、B-Roll素材自动获取器、财务数据模拟与图表构建器以及最终的视频渲染合成器。这些模块协同工作，形成一个从原始输入到最终视频输出的完整流水线。
Section sources
架构概述
系统的整体架构遵循“后端处理，前端渲染”的模式。Python后端作为“导演”，负责协调所有AI和数据处理任务；而Node.js前端作为“引擎”，专注于高质量的视频合成。main.py是整个流水线的入口点，它按顺序调用各个模块，最终生成render_props.json文件，触发Remotion进行视频渲染。
graph TD
A[PDF/视频输入] --> B[extractor.py]
B --> C[scripter.py]
C --> D[media_fetcher.py]
D --> E[data_builder.py]
E --> F[render_props.json]
F --> G[Remotion渲染]
G --> H[最终视频输出]
Diagram sources
详细组件分析
PDF/视频数据提取器 (extractor.py)
该模块负责解析输入的PDF报告和视频文件，从中提取结构化数据。它利用Google Gemini Pro API来解析日语财务报告，并使用OpenAI Whisper API对访谈视频进行转录，获取时间戳和关键词。
Section sources
AI日语解说脚本生成器 (scripter.py)
此模块是AI驱动内容生成的核心。它接收从PDF和视频中提取的数据，利用Google Gemini Pro生成自然流畅的日语解说脚本。脚本被划分为多个片段，每个片段都包含预计的持续时间，为后续的视频同步提供依据。
classDiagram
class ScriptGenerator {
+api_key : str
+__init__(api_key : Optional[str])
+generate(pdf_data : Dict, video_data : Optional[Dict], style : str) : Dict
-_build_prompt(pdf_data : Dict, style : str) : str
}
Diagram sources
Section sources
B-Roll素材自动获取器 (media_fetcher.py)
该模块根据生成的脚本内容，自动从Pexels API获取相关的背景视频素材（B-Roll）。它会从脚本中提取关键词，将日语关键词翻译成英语，然后搜索并下载匹配的视频片段，为视频增添视觉吸引力。
sequenceDiagram
participant Script as 脚本
participant Fetcher as MediaFetcher
participant Pexels as Pexels API
Script->>Fetcher : 提供关键词列表
Fetcher->>Fetcher : 翻译关键词(日->英)
Fetcher->>Pexels : 搜索视频
Pexels-->>Fetcher : 返回视频URL
Fetcher->>Fetcher : 下载视频到本地
Fetcher-->>Script : 返回本地文件路径
Diagram sources
Section sources
财务数据模拟与图表构建器 (data_builder.py)
这是数据驱动视频渲染的关键。该模块包含一个财务模拟引擎，能够基于提取的财务数据，模拟未来几十年的资产耗尽和现金流情况。它考虑了通货膨胀、投资回报和债务复利等因素，生成精确的年度财务快照，并将其格式化为Remotion图表组件所需的格式。
classDiagram
class FinancialSimulator {
+config : Dict
+inflation_rate : float
+deficit_interest_rate : float
+investment_return : float
+__init__(config : Optional[Dict])
+simulate_timeline(...) : List[Dict]
+build_cashflow_data(timeline : List[Dict]) : List[Dict]
-_get_event_cost(...) : float
-_get_event_labels(...) : List[str]
}
Diagram sources
Section sources
视频渲染合成器 (src/index.ts)
前端部分使用Remotion库进行程序化视频渲染。index.ts是入口文件，它注册了Root.tsx作为根组件。Root.tsx中定义了多个<Composition>，每个都对应一个视频片段（如资产耗尽图、现金流图），并将render_props.json中的数据作为属性传递给相应的React组件。
flowchart TD
A[index.ts] --> B[Root.tsx]
B --> C[Composition: LifePlanChart]
B --> D[Composition: CashFlowChart]
B --> E[Composition: DualChartView]
C --> F[LifePlanChart.tsx]
D --> G[CashFlowChart.tsx]
E --> H[DualChartView.tsx]
Diagram sources
Section sources
依赖分析
系统的主要依赖关系清晰地体现在main.py的流水线设计中。VideoGeneratorPipeline类按顺序调用extract_pdf、generate_script、fetch_broll和build_render_props等方法，形成了一个强依赖的线性流程。外部API密钥通过环境变量注入，确保了配置的安全性。
graph TD
main.VideoGeneratorPipeline.run[run] --> main.VideoGeneratorPipeline.extract_pdf[extract_pdf]
main.VideoGeneratorPipeline.run[run] --> main.VideoGeneratorPipeline.generate_script[generate_script]
main.VideoGeneratorPipeline.run[run] --> main.VideoGeneratorPipeline.fetch_broll[fetch_broll]
main.VideoGeneratorPipeline.run[run] --> main.VideoGeneratorPipeline.build_render_props[build_render_props]
main.VideoGeneratorPipeline.run[run] --> main.VideoGeneratorPipeline.render_video[render_video]
Diagram sources
Section sources
性能考虑
虽然代码中包含了一些TODO注释，表明部分功能尚未完全实现，但其架构设计已考虑到性能。例如，media_fetcher.py中提到了翻译缓存，以避免重复的API调用。财务模拟使用了数学公式进行高效计算。对于视频渲染，Remotion支持并行渲染和缓存，可以显著缩短生成时间。
故障排除指南
常见问题主要集中在API密钥和环境配置上。确保.env文件存在且包含有效的GEMINI_API_KEY、OPENAI_API_KEY和PEXELS_API_KEY。如果遇到渲染失败，检查npm install是否成功，并确认frontend/src/目录结构正确。对于PDF解析失败，需确认PDF文件可读且未加密。
Section sources
结论
该项目成功地将AI驱动的内容生成与数据驱动的视频渲染相结合，创造了一个自动化视频生成的解决方案。通过模块化的设计，每个核心功能都职责明确，易于维护和扩展。未来的工作应集中在实现TODO中提到的功能，如Gemini和Whisper的实际集成，并优化数据流以处理更复杂的财务场景。