1. 凌晨改稿的痛和 ppt-master 到底能做什么如果你也经历过这种场景晚上十点收到一份 30 页的 PDF 汇报材料对方说明早九点前给我一版 PPT然后你打开 PowerPoint 对着空白页面发呆——那你大概能理解我为什么会对 ppt-master 这个项目产生兴趣。市面上 AI 生成 PPT 的工具不少但绝大多数走的是渲染成图片再贴到幻灯片的路线。生成出来的东西看着像 PPT本质上却是一张张 PNG字体改不了、颜色调不动、图表点不开想改一个字等于重做整页。而 ppt-master 的思路完全不同它让大模型先生成 SVG 矢量代码再通过一条纯本地的 Python 编译流水线把 SVG 里的每一个rect、text、circle映射成 PowerPoint 原生的 DrawingML 形状对象。最终产出的.pptx文件里每个文本框、每条装饰线、每个色块都是真实可编辑的 PowerPoint 元素双击就能改字右键就能换色。这篇文章面向两类人一类是需要批量产出演示稿的开发者希望把 PPT 生成接入自己的自动化流程另一类是职场用户受够了通宵改稿想一次性把环境搭好、以后稳定复用。我会从 Python 环境准备讲起给出模型与 API 通道的配置骨架含config.toml示例演示 SVG 转 DrawingML 的验证动作最后走一遍从提示词到可编辑 PPTX 的完整链路。目标很明确一次部署之后每次生成都能拿到可二次编辑的幻灯片。整个链路可以拆成三段内容理解与分页大模型负责、SVG 矢量版式生成大模型扮演 UI 设计师、SVG 到 DrawingML 的编译纯 Python 本地执行。前两段依赖模型能力第三段完全离线。理解了这三段后面配置起来就不会迷路。2. 前置准备Python 环境与 TaoToken 通道配置2.1 Python 环境检查ppt-master 要求 Python 3.10 及以上。先确认版本python --version如果输出类似Python 3.11.9就没问题。版本过低的话去 python.org 下载安装Windows 用户安装时务必勾选 Add Python to PATH否则后续命令会提示找不到 python。接着克隆项目并安装依赖git clone https://github.com/hugohe3/ppt-master.git cd ppt-master pip install -r requirements.txt依赖装完后你会看到python-pptx、lxml、Pillow三个核心库。它们的分工是python-pptx负责把解析后的语法树节点映射成 PowerPoint 原生对象lxml负责高性能解析模型生成的 SVG 代码Pillow处理文档里嵌入的图片。2.2 为什么需要一条稳定的 API 通道ppt-master 本身不是独立 GUI 应用它作为技能文件嵌入 AI 编程助手运行。也就是说内容分页和 SVG 生成这两步都要调用大模型。如果你直接用官方 API会遇到两个现实问题一是不同模型的 SVG 坐标布局精度差异很大二是长文档分页时 token 消耗容易失控。我试过用 TaoToken 作为统一通道来管理这些调用好处是可以在一个地方切换模型、查看用量、控制成本。它的 API 地址是https://taotoken.net/api兼容主流模型调用格式。你需要在项目根目录创建一个config.toml把通道配置写进去# config.toml — ppt-master 模型通道配置骨架 [llm] provider openai-compatible base_url https://taotoken.net/api api_key sk-your-taotoken-key model claude-sonnet-4-20250514 max_tokens 8192 temperature 0.3 [llm.fallback] model gpt-4o max_tokens 4096 [render] slide_width 13.333 # 16:9 标准宽度英寸 slide_height 7.5 svg_scale 1.0 font_family Microsoft YaHei [paths] projects_dir projects exports_dir exports几个参数值得说明。temperature设成 0.3 是因为 SVG 版式生成需要精确的坐标温度太高会导致元素位置漂移。max_tokens给到 8192 是为了容纳单页 SVG 的完整代码一页复杂版式的 SVG 动辄两三千字符。slide_width和slide_height对应 16:9 比例如果你要做小红书 3:4 或朋友圈 1:1改这两个值即可。API Key 的获取入口在 TaoToken 控制台的 API Keys 页面创建后复制到config.toml的api_key字段。如果你更习惯用环境变量也可以把 key 写进.env文件然后在代码里用os.getenv读取。注意config.toml里不要提交真实的 API Key 到 Git 仓库建议把该文件加入.gitignore。3. 可复制配置从提示词到 SVG 的完整骨架3.1 项目目录结构配置好通道后先熟悉一下目录布局后面排障会用到ppt-master/ ├── prompts/ # 提示词模板内容提取 SVG 版式生成指令 ├── src/ │ ├── parser/ # SVG AST 解析器 │ │ ├── svg_ast.py # SVG → DOM 树 │ │ └── style_extractor.py # CSS 属性提取 │ └── render/ # PPTX 原生渲染引擎 │ ├── pptx_builder.py # 核心python-pptx API 映射 │ └── shape_factory.py # 形状路由分发 ├── projects/ # 源文档放这里 ├── exports/ # 生成的 .pptx 输出目录 ├── examples/ # 示例项目 └── docs/ # 详细文档3.2 提示词模板的关键字段prompts/目录下有两个核心模板。内容提取模板负责把源文档拆成结构化大纲输出 JSONSVG 版式模板负责把每一页大纲渲染成带绝对坐标的 SVG 代码。你可以在调用时覆盖默认参数比如指定页数、配色、比例/ppt-master 用 projects/季度述职报告.pdf 生成PPT - 10-15页 - 商务专业风深蓝金色配色 - 16:9 比例 - 每页不超过 5 个要点 - 第 3 页需要柱状图展示季度数据对比这段提示词会被拆解成两个阶段执行。第一阶段模型读取 PDF分析逻辑结构规划 10 页内容分布输出 JSON 大纲。第二阶段模型逐页设计布局生成精确坐标的 SVG 代码。两阶段之间有一个校验点如果 JSON 大纲的页数与你的要求偏差超过 2 页流程会暂停让你确认。3.3 SVG 转 DrawingML 的映射规则这是整个项目最核心的部分。SVG 和 PowerPoint 的 DrawingML 本质上都是基于绝对坐标的 2D 矢量格式转换更像是方言互译而非格式跨越。映射关系如下SVG 元素DrawingML 对象可编辑性rect原生矩形形状可拖动、改色、调圆角text可编辑文本框双击改字、调字体字号circle正圆形状可缩放、改填充line直线连接符可调端点、线型path自由曲线可编辑顶点坐标转换的比例因子由slide_width / svg_width决定。比如 SVG 画布是 960×540 像素幻灯片是 13.333×7.5 英寸那么 X 轴比例就是13.333/960 ≈ 0.01389Y 轴是7.5/540 ≈ 0.01389。两个方向比例一致保证图形不变形。4. 验证请求跑通第一份可编辑 PPTX4.1 纯 Python 调用渲染引擎如果你想跳过 AI 对话环节直接在自动化脚本里调用渲染模块可以用下面这段完整可运行的示例。它模拟了模型生成的 SVG 代码然后走一遍解析和渲染 ppt-master 核心渲染模块 —— 纯 Python 调用示例 输入AI 生成的 SVG 代码 输出原生可编辑 PPTX from pptx import Presentation from pptx.util import Inches, Pt from pptx.dml.color import RGBColor from pptx.enum.shapes import MSO_SHAPE from pptx.enum.text import PP_ALIGN import xml.etree.ElementTree as ET # 第1步定义 AI 生成的 SVG模拟 Phase 2 输出 svg_code svg xmlnshttp://www.w3.org/2000/svg width960 height540 rect x0 y0 width960 height540 fill#0d1b2a/ rect x0 y0 width960 height6 fill#e6b800/ text x480 y140 font-size46 font-familyMicrosoft YaHei fill#ffffff text-anchormiddle2026年度工作总结/text text x480 y210 font-size24 font-familyMicrosoft YaHei fill#8899aa text-anchormiddle技术研发部 · 张工/text rect x120 y260 width720 height3 fill#e6b800/ text x120 y340 font-size20 font-familyMicrosoft YaHei fill#c0c8d0核心成果/text text x140 y380 font-size18 font-familyMicrosoft YaHei fill#a0b0c0· 上线3个核心产品DAU突破50万季度营收增长240%/text text x140 y420 font-size18 font-familyMicrosoft YaHei fill#a0b0c0· 获得5项发明专利授权核心算法通过国家信创认证/text text x140 y460 font-size18 font-familyMicrosoft YaHei fill#a0b0c0· 研发团队从8人扩展至28人搭建完整技术中台/text /svg # 第2步解析 SVG root ET.fromstring(svg_code) ns {svg: http://www.w3.org/2000/svg} # 第3步创建 PPTX逐元素渲染原生形状 prs Presentation() prs.slide_width Inches(13.333) # 16:9 标准 prs.slide_height Inches(7.5) slide prs.slides.add_slide(prs.slide_layouts[6]) # 空白布局 # 坐标转换比例SVG 像素 → PPTX 英寸 SCALE_X 13.333 / 960 SCALE_Y 7.5 / 540 # ---- 渲染背景矩形 ---- bg root.find(.//svg:rect[fill#0d1b2a], ns) if bg is not None: shape slide.shapes.add_shape( MSO_SHAPE.RECTANGLE, Inches(0), Inches(0), Inches(13.333), Inches(7.5) ) shape.fill.solid() shape.fill.fore_color.rgb RGBColor(0x0d, 0x1b, 0x2a) shape.line.fill.background() # ---- 渲染顶部金色装饰线 ---- rects root.findall(.//svg:rect, ns) deco_line rects[1] x float(deco_line.get(x, 0)) * SCALE_X y float(deco_line.get(y, 0)) * SCALE_Y w float(deco_line.get(width, 0)) * SCALE_X h max(float(deco_line.get(height, 0)) * SCALE_Y, 0.05) line_shape slide.shapes.add_shape( MSO_SHAPE.RECTANGLE, Inches(x), Inches(y), Inches(w), Inches(h) ) line_shape.fill.solid() line_shape.fill.fore_color.rgb RGBColor(0xe6, 0xb8, 0x00) line_shape.line.fill.background() # ---- 渲染所有文本 ---- for text_elem in root.findall(.//svg:text, ns): x float(text_elem.get(x, 0)) * SCALE_X y float(text_elem.get(y, 0)) * SCALE_Y w float(text_elem.get(width, 700).replace(px, )) * SCALE_X h float(text_elem.get(height, 40).replace(px, )) * SCALE_Y txBox slide.shapes.add_textbox(Inches(x), Inches(y), Inches(w), Inches(h)) tf txBox.text_frame tf.word_wrap True p tf.paragraphs[0] p.text text_elem.text or # 字体样式注入 fs text_elem.get(font-size, 18).replace(px, ) p.font.size Pt(int(float(fs))) p.font.name text_elem.get(font-family, Microsoft YaHei) # 颜色注入 fc text_elem.get(fill, #000000).lstrip(#) r, g, b int(fc[0:2], 16), int(fc[2:4], 16), int(fc[4:6], 16) p.font.color.rgb RGBColor(r, g, b) # 对齐 if text_elem.get(text-anchor) middle: p.alignment PP_ALIGN.CENTER # ---- 渲染中间分隔线 ---- sep_line rects[2] x float(sep_line.get(x, 0)) * SCALE_X y float(sep_line.get(y, 0)) * SCALE_Y w float(sep_line.get(width, 0)) * SCALE_X h max(float(sep_line.get(height, 0)) * SCALE_Y, 0.03) sep_shape slide.shapes.add_shape( MSO_SHAPE.RECTANGLE, Inches(x), Inches(y), Inches(w), Inches(h) ) sep_shape.fill.solid() sep_shape.fill.fore_color.rgb RGBColor(0xe6, 0xb8, 0x00) sep_shape.line.fill.background() # 第4步保存为原生 .pptx prs.save(exports/demo_automated.pptx) print(PPT 生成成功 → exports/demo_automated.pptx) print(打开后验证每个文字、色块、线条都可以直接编辑)运行结果PPT 生成成功 → exports/demo_automated.pptx 打开后验证每个文字、色块、线条都可以直接编辑双击打开demo_automated.pptx你会看到深蓝背景上金色装饰条、白色标题文字、灰色要点列表。每个元素都可以点击、拖动、修改颜色和内容。这就是原生可编辑的含义——它不是一张图而是一组真实的 PowerPoint 对象。4.2 验证 SVG 转 DrawingML 是否成功判断转换是否成功有个简单的检查方法在 PowerPoint 里选中任意一个文本框看它是否显示为文本框而非图片。如果显示为图片说明转换链路某处退化成了位图渲染。正常情况下shape_factory.py会把text映射为add_textboxrect映射为add_shape两者在 PowerPoint 里的行为完全不同。另一个验证点是看导出的exports/目录结构exports/ ├── presentation.pptx # 原生可编辑版用这个 ├── presentation_svg.pptx # SVG 参考版像素级还原预览 └── backup/ └── 20260628_143052/ └── svg_output/ ├── slide_01.svg ├── slide_02.svg └── ...presentation.pptx是你要用的文件backup/里保留了每一页的 SVG 源码方便你回溯某页的版式设计。5. 本篇常见错排查5.1 报错ModuleNotFoundError: No module named pptx这是依赖没装全。python-pptx的包名和导入名不一致安装命令是pip install python-pptx导入时写from pptx import Presentation。如果你用了虚拟环境确认激活的是正确的环境# 确认当前 Python 路径 which python # Linux/macOS where python # Windows # 重新安装依赖 pip install -r requirements.txt --force-reinstall5.2 SVG 坐标偏移元素跑到画布外多半是SCALE_X和SCALE_Y不一致导致的。检查config.toml里的slide_width和slide_height是否与 SVG 画布的宽高比匹配。如果 SVG 是 960×54016:9幻灯片也必须是 16:9。混用 4:3 和 16:9 会让图形横向拉伸。还有一种情况是模型生成的 SVG 里用了viewBox而非width/height解析时拿不到画布尺寸。解决办法是在提示词里明确要求模型输出width和height属性。5.3 文本显示为方框或乱码字体缺失。config.toml里默认用Microsoft YaHei如果你的系统没装这个字体PowerPoint 会回退到默认字体中文可能显示异常。换成系统已有的中文字体即可比如SimSun、SimHei或Noto Sans CJK SC。5.4 API 调用返回 401 或 429401 是 Key 无效检查config.toml里的api_key是否复制完整有没有多余空格。429 是频率限制长文档分页时模型调用密集容易触发。可以在config.toml里加一个重试间隔[llm.retry] max_retries 3 backoff_seconds 55.5 生成的 PPTX 打开后提示文件损坏通常是python-pptx版本与 PowerPoint 版本不兼容。python-pptx1.0.2 生成的 OOXML 符合 ECMA-376 标准但如果你的 Office 版本过旧比如 2010 以前可能无法解析。升级 Office 或改用 WPS 打开验证。另外确认保存路径的目录存在prs.save()不会自动创建目录。5.6 模型生成的 SVG 里混入了 HTML 标签有些模型会把div、span混进 SVG 输出。lxml解析时会报错。在提示词里加一句只输出纯 SVG 代码不要包含 HTML 标签或 Markdown 代码块标记能大幅降低这个问题的出现率。如果已经生成了可以用正则先清洗一遍import re svg_code re.sub(rsvg|, , svg_code).strip()6. 把生成链路接进你的日常工作流环境搭好之后真正提升效率的是把这条链路固化下来。我的做法是在项目里建一个batch_generate.py遍历projects/目录下的所有文档逐个生成 PPTX输出到exports/并按日期归档。这样每周的周报、每月的述职、每季度的复盘都可以批量跑一遍生成后只需要在 PowerPoint 里微调几处措辞。如果你需要长期跑编码类任务或 Agent 工作流可以考虑用 Coding Plan 来管理调用配额避免每次手动切换 Key。模型对话入口适合快速验证某页 SVG 的版式效果接入文档则详细说明了config.toml里每个字段的含义和可选值。回到最初那个凌晨改稿的场景。现在你收到 PDF 后把它丢进projects/跑一条命令十分钟后拿到一份每个元素都能编辑的 PPTX。剩下的时间你可以用来打磨内容本身而不是和排版较劲。这才是工具该有的样子。
1. 凌晨改稿的痛和 ppt-master 到底能做什么如果你也经历过这种场景晚上十点收到一份 30 页的 PDF 汇报材料对方说明早九点前给我一版 PPT然后你打开 PowerPoint 对着空白页面发呆——那你大概能理解我为什么会对 ppt-master 这个项目产生兴趣。市面上 AI 生成 PPT 的工具不少但绝大多数走的是渲染成图片再贴到幻灯片的路线。生成出来的东西看着像 PPT本质上却是一张张 PNG字体改不了、颜色调不动、图表点不开想改一个字等于重做整页。而 ppt-master 的思路完全不同它让大模型先生成 SVG 矢量代码再通过一条纯本地的 Python 编译流水线把 SVG 里的每一个rect、text、circle映射成 PowerPoint 原生的 DrawingML 形状对象。最终产出的.pptx文件里每个文本框、每条装饰线、每个色块都是真实可编辑的 PowerPoint 元素双击就能改字右键就能换色。这篇文章面向两类人一类是需要批量产出演示稿的开发者希望把 PPT 生成接入自己的自动化流程另一类是职场用户受够了通宵改稿想一次性把环境搭好、以后稳定复用。我会从 Python 环境准备讲起给出模型与 API 通道的配置骨架含config.toml示例演示 SVG 转 DrawingML 的验证动作最后走一遍从提示词到可编辑 PPTX 的完整链路。目标很明确一次部署之后每次生成都能拿到可二次编辑的幻灯片。整个链路可以拆成三段内容理解与分页大模型负责、SVG 矢量版式生成大模型扮演 UI 设计师、SVG 到 DrawingML 的编译纯 Python 本地执行。前两段依赖模型能力第三段完全离线。理解了这三段后面配置起来就不会迷路。2. 前置准备Python 环境与 TaoToken 通道配置2.1 Python 环境检查ppt-master 要求 Python 3.10 及以上。先确认版本python --version如果输出类似Python 3.11.9就没问题。版本过低的话去 python.org 下载安装Windows 用户安装时务必勾选 Add Python to PATH否则后续命令会提示找不到 python。接着克隆项目并安装依赖git clone https://github.com/hugohe3/ppt-master.git cd ppt-master pip install -r requirements.txt依赖装完后你会看到python-pptx、lxml、Pillow三个核心库。它们的分工是python-pptx负责把解析后的语法树节点映射成 PowerPoint 原生对象lxml负责高性能解析模型生成的 SVG 代码Pillow处理文档里嵌入的图片。2.2 为什么需要一条稳定的 API 通道ppt-master 本身不是独立 GUI 应用它作为技能文件嵌入 AI 编程助手运行。也就是说内容分页和 SVG 生成这两步都要调用大模型。如果你直接用官方 API会遇到两个现实问题一是不同模型的 SVG 坐标布局精度差异很大二是长文档分页时 token 消耗容易失控。我试过用 TaoToken 作为统一通道来管理这些调用好处是可以在一个地方切换模型、查看用量、控制成本。它的 API 地址是https://taotoken.net/api兼容主流模型调用格式。你需要在项目根目录创建一个config.toml把通道配置写进去# config.toml — ppt-master 模型通道配置骨架 [llm] provider openai-compatible base_url https://taotoken.net/api api_key sk-your-taotoken-key model claude-sonnet-4-20250514 max_tokens 8192 temperature 0.3 [llm.fallback] model gpt-4o max_tokens 4096 [render] slide_width 13.333 # 16:9 标准宽度英寸 slide_height 7.5 svg_scale 1.0 font_family Microsoft YaHei [paths] projects_dir projects exports_dir exports几个参数值得说明。temperature设成 0.3 是因为 SVG 版式生成需要精确的坐标温度太高会导致元素位置漂移。max_tokens给到 8192 是为了容纳单页 SVG 的完整代码一页复杂版式的 SVG 动辄两三千字符。slide_width和slide_height对应 16:9 比例如果你要做小红书 3:4 或朋友圈 1:1改这两个值即可。API Key 的获取入口在 TaoToken 控制台的 API Keys 页面创建后复制到config.toml的api_key字段。如果你更习惯用环境变量也可以把 key 写进.env文件然后在代码里用os.getenv读取。注意config.toml里不要提交真实的 API Key 到 Git 仓库建议把该文件加入.gitignore。3. 可复制配置从提示词到 SVG 的完整骨架3.1 项目目录结构配置好通道后先熟悉一下目录布局后面排障会用到ppt-master/ ├── prompts/ # 提示词模板内容提取 SVG 版式生成指令 ├── src/ │ ├── parser/ # SVG AST 解析器 │ │ ├── svg_ast.py # SVG → DOM 树 │ │ └── style_extractor.py # CSS 属性提取 │ └── render/ # PPTX 原生渲染引擎 │ ├── pptx_builder.py # 核心python-pptx API 映射 │ └── shape_factory.py # 形状路由分发 ├── projects/ # 源文档放这里 ├── exports/ # 生成的 .pptx 输出目录 ├── examples/ # 示例项目 └── docs/ # 详细文档3.2 提示词模板的关键字段prompts/目录下有两个核心模板。内容提取模板负责把源文档拆成结构化大纲输出 JSONSVG 版式模板负责把每一页大纲渲染成带绝对坐标的 SVG 代码。你可以在调用时覆盖默认参数比如指定页数、配色、比例/ppt-master 用 projects/季度述职报告.pdf 生成PPT - 10-15页 - 商务专业风深蓝金色配色 - 16:9 比例 - 每页不超过 5 个要点 - 第 3 页需要柱状图展示季度数据对比这段提示词会被拆解成两个阶段执行。第一阶段模型读取 PDF分析逻辑结构规划 10 页内容分布输出 JSON 大纲。第二阶段模型逐页设计布局生成精确坐标的 SVG 代码。两阶段之间有一个校验点如果 JSON 大纲的页数与你的要求偏差超过 2 页流程会暂停让你确认。3.3 SVG 转 DrawingML 的映射规则这是整个项目最核心的部分。SVG 和 PowerPoint 的 DrawingML 本质上都是基于绝对坐标的 2D 矢量格式转换更像是方言互译而非格式跨越。映射关系如下SVG 元素DrawingML 对象可编辑性rect原生矩形形状可拖动、改色、调圆角text可编辑文本框双击改字、调字体字号circle正圆形状可缩放、改填充line直线连接符可调端点、线型path自由曲线可编辑顶点坐标转换的比例因子由slide_width / svg_width决定。比如 SVG 画布是 960×540 像素幻灯片是 13.333×7.5 英寸那么 X 轴比例就是13.333/960 ≈ 0.01389Y 轴是7.5/540 ≈ 0.01389。两个方向比例一致保证图形不变形。4. 验证请求跑通第一份可编辑 PPTX4.1 纯 Python 调用渲染引擎如果你想跳过 AI 对话环节直接在自动化脚本里调用渲染模块可以用下面这段完整可运行的示例。它模拟了模型生成的 SVG 代码然后走一遍解析和渲染 ppt-master 核心渲染模块 —— 纯 Python 调用示例 输入AI 生成的 SVG 代码 输出原生可编辑 PPTX from pptx import Presentation from pptx.util import Inches, Pt from pptx.dml.color import RGBColor from pptx.enum.shapes import MSO_SHAPE from pptx.enum.text import PP_ALIGN import xml.etree.ElementTree as ET # 第1步定义 AI 生成的 SVG模拟 Phase 2 输出 svg_code svg xmlnshttp://www.w3.org/2000/svg width960 height540 rect x0 y0 width960 height540 fill#0d1b2a/ rect x0 y0 width960 height6 fill#e6b800/ text x480 y140 font-size46 font-familyMicrosoft YaHei fill#ffffff text-anchormiddle2026年度工作总结/text text x480 y210 font-size24 font-familyMicrosoft YaHei fill#8899aa text-anchormiddle技术研发部 · 张工/text rect x120 y260 width720 height3 fill#e6b800/ text x120 y340 font-size20 font-familyMicrosoft YaHei fill#c0c8d0核心成果/text text x140 y380 font-size18 font-familyMicrosoft YaHei fill#a0b0c0· 上线3个核心产品DAU突破50万季度营收增长240%/text text x140 y420 font-size18 font-familyMicrosoft YaHei fill#a0b0c0· 获得5项发明专利授权核心算法通过国家信创认证/text text x140 y460 font-size18 font-familyMicrosoft YaHei fill#a0b0c0· 研发团队从8人扩展至28人搭建完整技术中台/text /svg # 第2步解析 SVG root ET.fromstring(svg_code) ns {svg: http://www.w3.org/2000/svg} # 第3步创建 PPTX逐元素渲染原生形状 prs Presentation() prs.slide_width Inches(13.333) # 16:9 标准 prs.slide_height Inches(7.5) slide prs.slides.add_slide(prs.slide_layouts[6]) # 空白布局 # 坐标转换比例SVG 像素 → PPTX 英寸 SCALE_X 13.333 / 960 SCALE_Y 7.5 / 540 # ---- 渲染背景矩形 ---- bg root.find(.//svg:rect[fill#0d1b2a], ns) if bg is not None: shape slide.shapes.add_shape( MSO_SHAPE.RECTANGLE, Inches(0), Inches(0), Inches(13.333), Inches(7.5) ) shape.fill.solid() shape.fill.fore_color.rgb RGBColor(0x0d, 0x1b, 0x2a) shape.line.fill.background() # ---- 渲染顶部金色装饰线 ---- rects root.findall(.//svg:rect, ns) deco_line rects[1] x float(deco_line.get(x, 0)) * SCALE_X y float(deco_line.get(y, 0)) * SCALE_Y w float(deco_line.get(width, 0)) * SCALE_X h max(float(deco_line.get(height, 0)) * SCALE_Y, 0.05) line_shape slide.shapes.add_shape( MSO_SHAPE.RECTANGLE, Inches(x), Inches(y), Inches(w), Inches(h) ) line_shape.fill.solid() line_shape.fill.fore_color.rgb RGBColor(0xe6, 0xb8, 0x00) line_shape.line.fill.background() # ---- 渲染所有文本 ---- for text_elem in root.findall(.//svg:text, ns): x float(text_elem.get(x, 0)) * SCALE_X y float(text_elem.get(y, 0)) * SCALE_Y w float(text_elem.get(width, 700).replace(px, )) * SCALE_X h float(text_elem.get(height, 40).replace(px, )) * SCALE_Y txBox slide.shapes.add_textbox(Inches(x), Inches(y), Inches(w), Inches(h)) tf txBox.text_frame tf.word_wrap True p tf.paragraphs[0] p.text text_elem.text or # 字体样式注入 fs text_elem.get(font-size, 18).replace(px, ) p.font.size Pt(int(float(fs))) p.font.name text_elem.get(font-family, Microsoft YaHei) # 颜色注入 fc text_elem.get(fill, #000000).lstrip(#) r, g, b int(fc[0:2], 16), int(fc[2:4], 16), int(fc[4:6], 16) p.font.color.rgb RGBColor(r, g, b) # 对齐 if text_elem.get(text-anchor) middle: p.alignment PP_ALIGN.CENTER # ---- 渲染中间分隔线 ---- sep_line rects[2] x float(sep_line.get(x, 0)) * SCALE_X y float(sep_line.get(y, 0)) * SCALE_Y w float(sep_line.get(width, 0)) * SCALE_X h max(float(sep_line.get(height, 0)) * SCALE_Y, 0.03) sep_shape slide.shapes.add_shape( MSO_SHAPE.RECTANGLE, Inches(x), Inches(y), Inches(w), Inches(h) ) sep_shape.fill.solid() sep_shape.fill.fore_color.rgb RGBColor(0xe6, 0xb8, 0x00) sep_shape.line.fill.background() # 第4步保存为原生 .pptx prs.save(exports/demo_automated.pptx) print(PPT 生成成功 → exports/demo_automated.pptx) print(打开后验证每个文字、色块、线条都可以直接编辑)运行结果PPT 生成成功 → exports/demo_automated.pptx 打开后验证每个文字、色块、线条都可以直接编辑双击打开demo_automated.pptx你会看到深蓝背景上金色装饰条、白色标题文字、灰色要点列表。每个元素都可以点击、拖动、修改颜色和内容。这就是原生可编辑的含义——它不是一张图而是一组真实的 PowerPoint 对象。4.2 验证 SVG 转 DrawingML 是否成功判断转换是否成功有个简单的检查方法在 PowerPoint 里选中任意一个文本框看它是否显示为文本框而非图片。如果显示为图片说明转换链路某处退化成了位图渲染。正常情况下shape_factory.py会把text映射为add_textboxrect映射为add_shape两者在 PowerPoint 里的行为完全不同。另一个验证点是看导出的exports/目录结构exports/ ├── presentation.pptx # 原生可编辑版用这个 ├── presentation_svg.pptx # SVG 参考版像素级还原预览 └── backup/ └── 20260628_143052/ └── svg_output/ ├── slide_01.svg ├── slide_02.svg └── ...presentation.pptx是你要用的文件backup/里保留了每一页的 SVG 源码方便你回溯某页的版式设计。5. 本篇常见错排查5.1 报错ModuleNotFoundError: No module named pptx这是依赖没装全。python-pptx的包名和导入名不一致安装命令是pip install python-pptx导入时写from pptx import Presentation。如果你用了虚拟环境确认激活的是正确的环境# 确认当前 Python 路径 which python # Linux/macOS where python # Windows # 重新安装依赖 pip install -r requirements.txt --force-reinstall5.2 SVG 坐标偏移元素跑到画布外多半是SCALE_X和SCALE_Y不一致导致的。检查config.toml里的slide_width和slide_height是否与 SVG 画布的宽高比匹配。如果 SVG 是 960×54016:9幻灯片也必须是 16:9。混用 4:3 和 16:9 会让图形横向拉伸。还有一种情况是模型生成的 SVG 里用了viewBox而非width/height解析时拿不到画布尺寸。解决办法是在提示词里明确要求模型输出width和height属性。5.3 文本显示为方框或乱码字体缺失。config.toml里默认用Microsoft YaHei如果你的系统没装这个字体PowerPoint 会回退到默认字体中文可能显示异常。换成系统已有的中文字体即可比如SimSun、SimHei或Noto Sans CJK SC。5.4 API 调用返回 401 或 429401 是 Key 无效检查config.toml里的api_key是否复制完整有没有多余空格。429 是频率限制长文档分页时模型调用密集容易触发。可以在config.toml里加一个重试间隔[llm.retry] max_retries 3 backoff_seconds 55.5 生成的 PPTX 打开后提示文件损坏通常是python-pptx版本与 PowerPoint 版本不兼容。python-pptx1.0.2 生成的 OOXML 符合 ECMA-376 标准但如果你的 Office 版本过旧比如 2010 以前可能无法解析。升级 Office 或改用 WPS 打开验证。另外确认保存路径的目录存在prs.save()不会自动创建目录。5.6 模型生成的 SVG 里混入了 HTML 标签有些模型会把div、span混进 SVG 输出。lxml解析时会报错。在提示词里加一句只输出纯 SVG 代码不要包含 HTML 标签或 Markdown 代码块标记能大幅降低这个问题的出现率。如果已经生成了可以用正则先清洗一遍import re svg_code re.sub(rsvg|, , svg_code).strip()6. 把生成链路接进你的日常工作流环境搭好之后真正提升效率的是把这条链路固化下来。我的做法是在项目里建一个batch_generate.py遍历projects/目录下的所有文档逐个生成 PPTX输出到exports/并按日期归档。这样每周的周报、每月的述职、每季度的复盘都可以批量跑一遍生成后只需要在 PowerPoint 里微调几处措辞。如果你需要长期跑编码类任务或 Agent 工作流可以考虑用 Coding Plan 来管理调用配额避免每次手动切换 Key。模型对话入口适合快速验证某页 SVG 的版式效果接入文档则详细说明了config.toml里每个字段的含义和可选值。回到最初那个凌晨改稿的场景。现在你收到 PDF 后把它丢进projects/跑一条命令十分钟后拿到一份每个元素都能编辑的 PPTX。剩下的时间你可以用来打磨内容本身而不是和排版较劲。这才是工具该有的样子。
