xiaji/ppt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8618867f92a5f980b588f8fc2a9c45a3174feeb8
ppt/ppt_manager_v2/README.md

11 KiB
Raw Blame History

📊 PPT智能管理系统 V2.0 说明书

基于 锚点定位 + 原生图表更新 + 插件化架构 + WebSocket实时日志 的下一代PPT自动化平台。

🚀 快速开始

1. 环境准备

cd f:\ppt\ppt_manager_v2
pip install -r requirements_v2.txt

2. 启动WebSocket服务

python web_socket_app.py

3. 浏览器访问

打开 http://localhost:5001

📁 项目目录结构

ppt_manager_v2/
├── 📄 web_socket_app.py          # WebSocket服务端
├── 📄 orchestrator.py             # 主编排引擎（Pipeline）
├── 📄 requirements_v2.txt         # Python依赖包
├── 📄 README.md                   # 本文件
├──
├── 📂 core/                       # 核心层
│   ├── anchor_engine.py           # ✅ 锚点定位引擎
│   ├── native_chart.py            # ✅ 原生图表数据源更新
│   └── conditional_renderer.py    # ✅ 条件渲染引擎（动态增删页）
├──
├── 📂 plugins/                    # 插件化架构
│   ├── base_generator.py          # BaseGenerator 标准接口
│   └── generators/                # 插件目录（自动扫描注册）
│       ├── gdp_generator.py       # GDP趋势图生成插件
│       └── cpi_generator.py       # CPI/PPI图表生成插件
├──
├── 📂 ai/                         # AI智能化
│   └── llm_analyst.py             # LLM分析师 + Diff对比器
├──
├── 📂 connectors/                 # 多数据源适配
│   └── sql_connector.py           # MySQL/ClickHouse/REST API/CSV
├──
├── 📂 config/
│   └── project_config_v2.yaml     # V2版配置文件范式
├──
├── 📂 templates/                   # Flask模板目录
│   └── index_v2.html              # WebSocket前端页面
├──
├── 📂 logs/                        # 日志目录
└── 📂 web/                         # 备用（template_dir配置用）
    └── templates/
        └── index_v2.html

输出目录: f:\ppt\output\ （所有生成的PPT文件在这里）

🎯 五大核心增强能力

一、PPT核心操作层（从"拼图"到"原生替换"）

1.1 锚点(Anchor)定位引擎 → 无惧页码变动

痛点解决: 旧版YAML写 page: 5，老板在第3页插一页，所有配置页码全乱。

新版方案:

  1. 打开你的PPT模板 → 选中一个 Shape/图表/文本框
  2. 在PowerPoint的 "选择窗格" 里给Shape改名（例如：chart_gdp_trend）
  3. 在YAML里直接配置 锚点名，不是页码：
anchors:
  - name: chart_gdp_trend       # Shape Name（选择窗格里的名称）
    type: native_chart_update
    plugin: gdp_chart

代码参考: core/anchor_engine.py

1.2 原生图表数据源直接更新（不是插PNG！）

痛点解决: 旧版先生成PNG再插入PPT → 图片无法编辑、丢失主题配色和动画效果、文件体积大。

新版方案: 用 python-pptx 直接替换PPT内嵌图表的Excel数据源：

# 在native_chart.py里的实现
chart_data = CategoryChartData()
chart_data.categories = ['2026Q1', '2026Q2', '2026Q3']
chart_data.add_series('GDP同比增长', [5.2, 5.0, 5.1])
chart.replace_data(chart_data)  # ✅ 原生数据源替换！

这样做的好处:

  • ✅ 生成的PPT里双击图表可以进入Excel编辑
  • ✅ 自动继承PPT母版的主题配色
  • ✅ 保留图表原有的进入/强调动画效果
  • ✅ 文本清晰，不是模糊的点阵图

代码参考: core/native_chart.py

1.3 条件渲染与动态增删页

能力描述: 支持规则判断动态插入/隐藏页面：

slide_conditions:
  - condition: unemployment_rate > 5.1
    action: insert_slide
    template: "risk_warning_template.pptx"
    position: 5

表达式求值：unemployment_rate > 5.1 AND gdp_growth < 5.0 等复合条件。

代码参考: core/conditional_renderer.py

二、插件化数据流架构（真正的即插即用）

2.1 BaseGenerator 标准接口

所有插件继承 BaseGenerator 抽象基类，实现两个方法：

# plugins/base_generator.py 定义
class BaseGenerator(ABC):
    generator_id = "gdp_chart"
    generator_name = "GDP趋势生成器"
    
    @abstractmethod
    def fetch_data(self, params):    # 步骤A：取数
        pass
    
    @abstractmethod
    def render(self):                 # 步骤B：渲染返回原生图表数据
        pass

插件例子 → plugins/generators/gdp_generator.py

2.2 插件自动扫描注册

启动时系统自动扫描 plugins/generators/ 目录下所有 .py 文件，发现继承 BaseGenerator 且有 generator_id 的类自动注册到插件管理器，无需修改任何注册代码，真正即插即用。

# 启动日志里可以看到：
SUCCESS  | 加载插件 [cpi_chart]: CPI/PPI通胀图表生成器
SUCCESS  | 加载插件 [gdp_chart]: GDP趋势图表生成器
INFO     | 插件扫描完成，共加载 2 个生成器

代码参考: plugins/base_generator.py - GeneratorPluginManager.discover_plugins()

2.3 参数化生成

Web端不是单一"开始生成"按钮，而是传参给后端插件：

// 前端传params给WebSocket
socket.emit('start_generation', {
    params: {
        year: 2026,
        quarter: "Q2",
        theme: "保守型"
    }
});

插件的 fetch_data(params) 拿到这些参数去数据库/API拉对应区间的数据。

三、WebSocket Web交互体验（实时日志推流）

3.1 启动服务

python web_socket_app.py

控制台输出：

=================================================================
 🚀 PPT智能管理系统 V2.0 - WebSocket实时日志版
    请在浏览器打开: http://localhost:5001
=================================================================

3.2 前端页面三大区域

区域 功能
左上角参数表单 Year/Quarter 参数化输入
左下角实时面板 动态进度条 0-100% + Loguru日志逐行推送
右侧边栏 已加载插件清单 + 历史生成文件下载列表

WebSocket后端代码: web_socket_app.py

四、主编排引擎 Pipeline

Orchestrator 是串联所有模块的大脑：

# orchestrator.py - run_full_pipeline()
def run_full_pipeline(self):
    self.load_template()          # 1. 打开PPT，扫描所有锚点
    self.run_plugins(params)      # 2. 并行执行所有插件 fetch_data + render
    self.update_native_charts()   # 3. 原生图表数据源逐个更新
    self.ai_generate_summary()    # 4. LLM生成200字洞察文本
    self.process_conditions()     # 5. 条件表达式求值动态增删页
    return self.save()            # 6. 保存最终PPT

Pipeline代码位置: orchestrator.py - 第244-251行

五、AI 智能化（LLM + Diff对比）

5.1 LLM 自动生成"分析结论"

图表只能展示"是什么"，LLM帮你解释"为什么"：

# ai/llm_analyst.py
prompt = "基于以下数据：{gdp}、{cpi}，200字专业分析师口吻总结本月市场"
llm.generate_analysis({
    'gdp_growth': 5.1, 
    'cpi': 0.9,
    'unemployment': 5.2
})

# 返回示例：
"""
本月宏观经济洞察：GDP增长5.1%，动能平稳。CPI同比0.9%，
通胀水平温和为货币政策留出空间。就业失业率5.2%，
青年失业率需重点关注...
"""

支持 Mock模式 / OpenAI / 通义千问 三种provider切换。

代码参考: ai/llm_analyst.py

📄 YAML V2版 配置范式参考

project_name: "宏观经济月度分析报告"
version: "2.0"
template: "macro_analysis_template.pptx"

params:                    # 参数化生成默认值
  default_year: 2026
  default_quarter: "Q2"

anchors:                   # 锚点绑定关系
  - name: chart_gdp
    type: native_chart_update
    plugin: gdp_chart
    chart_type: line
    fallback: gdp_fallback.png

  - name: chart_cpi
    type: native_chart_update
    plugin: cpi_chart

slide_conditions:          # 条件渲染规则
  - condition: unemployment_rate > 5.1
    action: insert_slide
    position: 5

connectors:                # 多数据源配置
  mysql_stats: {type: mysql, database: macro_stats}

ai:                        # LLM配置
  provider: mock           # mock/openai/tongyi
  model: qwen-turbo

scheduler:                 # 定时调度
  cron: "0 8 1 * *"       # 每月1号早上8点

配置文件位置: config/project_config_v2.yaml

🔧 命令行非交互模式测试

直接跑整个Pipeline验证所有环节：

cd f:\ppt\ppt_manager_v2
python -c "
import sys
sys.path.insert(0, '.')
from orchestrator import Orchestrator
orch = Orchestrator()
orch.load_template()        # 检查: 锚点扫描
result = orch.run_plugins() # 检查: 插件取数+渲染
print('插件结果:', list(result.keys()))
orch.update_native_charts() # 检查: 原生图表更新
orch.ai_generate_summary()  # 检查: LLM生成
orch.save()                 # 检查: 输出文件
print('✅ 全流程通过!')
"

❓ 常见问题排查

Q1: TemplateNotFound jinja2 错误

现象: jinja2.exceptions.TemplateNotFound: index_v2.html

已修复: web_socket_app.py第16行明确了 template_folder 绝对路径，且文件在两处备份：

  • f:\ppt\ppt_manager_v2\templates\index_v2.html （Flask标准位置）
  • f:\ppt\ppt_manager_v2\web\templates\index_v2.html （配置位置）

Q2: 下载文件找不到 /api/files 返回空

已修复: /api/files 和 /download/<filename> 两处的 base_dir / "output" 统一改为 base_dir.parent / "output" 指向 f:\ppt\output\。

Q3: 'NoneType' object has no attribute 'text'

现象: 加载模板时报错

已修复: orchestrator.py 先判断 if slide.shapes.title: 再安全访问 .text。

Q4: 插件不显示/不执行

检查两点：

  1. 插件类继承 BaseGenerator(ABC)
  2. 类属性 generator_id 不能是 None
  3. 目录在 plugins/generators/*.py 且文件名不以 _ 开头

📌 维护信息

项目 详情
版本 V2.0 2026-05-29
入口 python web_socket_app.py
前端地址 http://localhost:5001
输出目录 f:\ppt\output\*.pptx
日志目录 f:\ppt\ppt_manager_v2\logs\
核心模块 orchestrator.py / anchor_engine.py / native_chart.py
插件目录 plugins/generators/
Reference in New Issue View Git Blame Copy Permalink