AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He
feat(tools): 添加演讲者备注嵌入功能到 svg_to_pptx
hugohe323a1f05c9194
diff --git a/AGENTS.md b/AGENTS.mdindex 25590bfd..d7093032 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -292,8 +292,11 @@ python3 -m http.server -d <路径>/svg_output 8000# 预览最终版本python3 -m http.server -d <路径>/svg_final 8000-# ⭐ 导出为 PPTX+# ⭐ 导出为 PPTX(默认嵌入演讲备注)python3 tools/svg_to_pptx.py <项目路径> -s final++# 导出 PPTX 但不嵌入备注+python3 tools/svg_to_pptx.py <项目路径> -s final --no-notes```### 项目目录结构@@ -303,6 +306,10 @@ project/├── svg_output/ # 原始版本(带占位符,作为模板参考)├── svg_final/ # 最终版本(后处理完成)├── images/ # 图片资源+├── notes/ # 演讲备注(Markdown 格式,可选)+│ ├── slide01.md+│ ├── slide02.md+│ └── ...└── *.pptx # 导出的 PPT 文件```diff --git a/roles/Executor_Consultant.md b/roles/Executor_Consultant.mdindex 77e175b3..c095e8f6 100644--- a/roles/Executor_Consultant.md+++ b/roles/Executor_Consultant.md@@ -128,3 +128,31 @@- [ ] 数据与源数据一致- [ ] 简洁专业,留白充足- [ ] **PPT 兼容**: 无 `rgba()`、无 `<g opacity>`、图片用遮罩层++---++## 演讲备注生成++生成每页 SVG 后,**同步创建**对应的演讲备注文件。++**输出路径**: `notes/slideXX.md`++**格式模板**:++```markdown+# PXX: [页面标题]++## 核心要点+- 要点1+- 要点2++## 讲稿建议+[2-5 句自然语言,描述如何讲述本页内容]++## 预计时长+X 分钟+```++**要求**:+- 讲稿建议应自然流畅+- 用户可在 `notes/` 目录手动编辑覆盖diff --git a/roles/Executor_Consultant_Top.md b/roles/Executor_Consultant_Top.mdindex 4e848457..96bcbb90 100644--- a/roles/Executor_Consultant_Top.md+++ b/roles/Executor_Consultant_Top.md@@ -223,3 +223,33 @@- [ ] **图表选型正确**:根据数据特点选择合适形式- [ ] **简洁专业**:留白充足,无冗余信息+---++## 演讲备注生成++生成每页 SVG 后,**同步创建**对应的演讲备注文件,为演讲者提供讲稿参考。++**输出路径**: `notes/slideXX.md`(XX 为两位数页码,如 `slide01.md`)++**格式模板**:++```markdown+# PXX: [页面标题]++## 核心要点+- 要点1:[本页需要传达的关键信息]+- 要点2:[补充要点]++## 讲稿建议+[2-5 句自然语言,描述如何讲述本页内容。例如:+"这一页我们来看整体架构。首先注意中央的 LLM 核心模块,+它通过三个增强模块获得更强的能力..."]++## 预计时长+X 分钟+```++**要求**:+- 讲稿建议应自然流畅,便于直接朗读+- 咨询风格应突出数据解读和洞察传达+- 用户可在 `notes/` 目录手动编辑覆盖diff --git a/roles/Executor_General.md b/roles/Executor_General.mdindex 94db33ac..939b7fae 100644--- a/roles/Executor_General.md+++ b/roles/Executor_General.md@@ -133,3 +133,31 @@- [ ] 元素不超出边界- [ ] 颜色符合规范- [ ] **PPT 兼容**: 无 `rgba()`、无 `<g opacity>`、图片用遮罩层++---++## 演讲备注生成++生成每页 SVG 后,**同步创建**对应的演讲备注文件。++**输出路径**: `notes/slideXX.md`++**格式模板**:++```markdown+# PXX: [页面标题]++## 核心要点+- 要点1+- 要点2++## 讲稿建议+[2-5 句自然语言,描述如何讲述本页内容]++## 预计时长+X 分钟+```++**要求**:+- 讲稿建议应自然流畅+- 用户可在 `notes/` 目录手动编辑覆盖diff --git a/tools/README.md b/tools/README.mdindex 5a2f5e50..56b9d220 100644--- a/tools/README.md+++ b/tools/README.md@@ -447,13 +447,17 @@ python3 tools/svg_quality_checker.py examples/project --export- 支持使用 svg_output 或 svg_final 目录- SVG 在 PowerPoint 中保持可编辑- **支持页面切换动画和入场动画**+- **自动嵌入演讲备注**(从 notes/ 目录读取)**用法**:```bash-# 推荐:使用后处理完成的版本+# 推荐:使用后处理完成的版本(默认嵌入备注)python3 tools/svg_to_pptx.py <项目路径> -s final+# 禁用演讲备注+python3 tools/svg_to_pptx.py <项目路径> -s final --no-notes+# 使用原始版本python3 tools/svg_to_pptx.py <项目路径>@@ -467,6 +471,15 @@ python3 tools/svg_to_pptx.py <项目路径> -t fade --transition-duration 1.0python3 tools/svg_to_pptx.py <项目路径> -s final -q```+**演讲备注**:++工具默认读取 `notes/` 目录中的 Markdown 备注文件(如 `slide01.md`),并嵌入到 PPTX 的演讲者备注中。++| 参数 | 说明 |+|------|------|+| 默认 | 自动嵌入备注(无备注文件则留空) |+| `--no-notes` | 禁用备注嵌入 |+**切换效果参数**:| 参数 | 说明 | 可选值 |@@ -518,6 +531,7 @@ pip install python-pptx- 需要 PowerPoint 2016+ 才能正确显示- 文件体积比 PNG 方案小很多- 切换效果默认关闭,需要用户显式启用+- 演讲备注默认开启,使用 `--no-notes` 禁用---diff --git a/tools/svg_to_pptx.py b/tools/svg_to_pptx.pyindex a8491500..220ab8d2 100644--- a/tools/svg_to_pptx.py+++ b/tools/svg_to_pptx.py@@ -247,6 +247,184 @@ def find_svg_files(project_path: Path, source: str = 'output') -> Tuple[List[Patreturn sorted(svg_dir.glob('*.svg')), dir_name+def find_notes_files(project_path: Path) -> dict:+ """+ 查找项目中的备注文件++ Args:+ project_path: 项目目录路径++ Returns:+ 字典,key 为幻灯片编号(1-indexed),value 为备注内容+ """+ notes_dir = project_path / 'notes'+ notes = {}++ if not notes_dir.exists():+ return notes++ # 支持 slide01.md, slide1.md, slide_01.md 等格式+ for notes_file in notes_dir.glob('slide*.md'):+ # 提取数字+ match = re.search(r'slide[_]?(\d+)', notes_file.stem)+ if match:+ slide_num = int(match.group(1))+ try:+ with open(notes_file, 'r', encoding='utf-8') as f:+ content = f.read().strip()+ if content:+ notes[slide_num] = content+ except Exception:+ pass++ return notes+++def markdown_to_plain_text(md_content: str) -> str:+ """+ 将 Markdown 备注转换为纯文本(用于 PPTX 备注)++ Args:+ md_content: Markdown 格式的备注内容++ Returns:+ 纯文本内容+ """+ lines = []+ for line in md_content.split('\n'):+ # 跳过标题行(# 开头)+ if line.startswith('#'):+ # 提取标题文本+ text = re.sub(r'^#+\s*', '', line).strip()+ if text:+ lines.append(text)+ lines.append('') # 空行+ # 处理列表项(- 开头)+ elif line.strip().startswith('- '):+ lines.append('• ' + line.strip()[2:])+ # 普通行+ elif line.strip():+ lines.append(line.strip())+ else:+ lines.append('')++ # 合并连续空行+ result = []+ prev_empty = False+ for line in lines:+ if line == '':+ if not prev_empty:+ result.append(line)+ prev_empty = True+ else:+ result.append(line)+ prev_empty = False++ return '\n'.join(result).strip()+++def create_notes_slide_xml(slide_num: int, notes_text: str) -> str:+ """+ 创建备注幻灯片 XML++ Args:+ slide_num: 幻灯片序号+ notes_text: 备注文本(纯文本格式)++ Returns:+ 备注幻灯片 XML 字符串+ """+ # 转义 XML 特殊字符+ notes_text = notes_text.replace('&', '&').replace('<', '<').replace('>', '>')++ # 将换行转换为 <a:p> 段落+ paragraphs = []+ for para in notes_text.split('\n'):+ if para.strip():+ paragraphs.append(f'''<a:p>+ <a:r>+ <a:rPr lang="zh-CN" dirty="0"/>+ <a:t>{para}</a:t>+ </a:r>+ </a:p>''')+ else:+ paragraphs.append('<a:p><a:endParaRPr lang="zh-CN" dirty="0"/></a:p>')++ paragraphs_xml = '\n '.join(paragraphs) if paragraphs else '<a:p><a:endParaRPr lang="zh-CN" dirty="0"/></a:p>'++ return f'''<?xml version="1.0" encoding="UTF-8" standalone="yes"?>+<p:notes xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main"+ xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"+ xmlns:p="http://schemas.openxmlformats.org/presentationml/2006/main">+ <p:cSld>+ <p:spTree>+ <p:nvGrpSpPr>+ <p:cNvPr id="1" name=""/>+ <p:cNvGrpSpPr/>+ <p:nvPr/>+ </p:nvGrpSpPr>+ <p:grpSpPr>+ <a:xfrm>+ <a:off x="0" y="0"/>+ <a:ext cx="0" cy="0"/>+ <a:chOff x="0" y="0"/>+ <a:chExt cx="0" cy="0"/>+ </a:xfrm>+ </p:grpSpPr>+ <p:sp>+ <p:nvSpPr>+ <p:cNvPr id="2" name="Slide Image Placeholder 1"/>+ <p:cNvSpPr>+ <a:spLocks noGrp="1" noRot="1" noChangeAspect="1"/>+ </p:cNvSpPr>+ <p:nvPr>+ <p:ph type="sldImg"/>+ </p:nvPr>+ </p:nvSpPr>+ <p:spPr/>+ </p:sp>+ <p:sp>+ <p:nvSpPr>+ <p:cNvPr id="3" name="Notes Placeholder 2"/>+ <p:cNvSpPr>+ <a:spLocks noGrp="1"/>+ </p:cNvSpPr>+ <p:nvPr>+ <p:ph type="body" idx="1"/>+ </p:nvPr>+ </p:nvSpPr>+ <p:spPr/>+ <p:txBody>+ <a:bodyPr/>+ <a:lstStyle/>+ {paragraphs_xml}+ </p:txBody>+ </p:sp>+ </p:spTree>+ </p:cSld>+ <p:clrMapOvr>+ <a:masterClrMapping/>+ </p:clrMapOvr>+</p:notes>'''+++def create_notes_slide_rels_xml(slide_num: int) -> str:+ """+ 创建备注幻灯片关系文件 XML++ Args:+ slide_num: 幻灯片序号++ Returns:+ 关系文件 XML 字符串+ """+ return f'''<?xml version="1.0" encoding="UTF-8" standalone="yes"?>+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">+ <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/notesMaster" Target="../notesMasters/notesMaster1.xml"/>+ <Relationship Id="rId2" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/slide" Target="../slides/slide{slide_num}.xml"/>+</Relationships>'''++def create_slide_xml_with_svg(slide_num: int,png_rid: str,@@ -379,7 +557,9 @@ def create_pptx_with_native_svg(transition: Optional[str] = None,transition_duration: float = 0.5,auto_advance: Optional[float] = None,- use_compat_mode: bool = True+ use_compat_mode: bool = True,+ notes: Optional[dict] = None,+ enable_notes: bool = True) -> bool:"""创建包含原生 SVG 的 PPTX 文件@@ -393,6 +573,8 @@ def create_pptx_with_native_svg(transition_duration: 切换持续时间(秒)auto_advance: 自动翻页间隔(秒)use_compat_mode: 使用 Office 兼容模式(PNG + SVG 双格式,默认开启)+ notes: 备注字典,key 为幻灯片编号,value 为备注内容+ enable_notes: 是否启用备注嵌入(默认开启)"""if not svg_files:print("错误: 没有找到 SVG 文件")@@ -432,6 +614,12 @@ def create_pptx_with_native_svg(if transition:trans_name = TRANSITIONS.get(transition, {}).get('name', transition) if TRANSITIONS else transitionprint(f" 切换效果: {trans_name}")+ if enable_notes and notes:+ print(f" 演讲备注: {len(notes)} 页")+ elif enable_notes:+ print(f" 演讲备注: 已启用(未找到备注文件)")+ else:+ print(f" 演讲备注: 已禁用")print()# 创建临时目录@@ -523,9 +711,44 @@ def create_pptx_with_native_svg(with open(rels_path, 'w', encoding='utf-8') as f:f.write(rels_xml)+ # 处理备注+ if enable_notes:+ notes_content = notes.get(i, '') if notes else ''+ if notes_content:+ notes_text = markdown_to_plain_text(notes_content)+ else:+ notes_text = '' # 空备注++ # 创建 notesSlides 目录+ notes_slides_dir = extract_dir / 'ppt' / 'notesSlides'+ notes_slides_dir.mkdir(exist_ok=True)++ # 创建备注幻灯片 XML+ notes_xml_path = notes_slides_dir / f'notesSlide{slide_num}.xml'+ notes_xml = create_notes_slide_xml(slide_num, notes_text)+ with open(notes_xml_path, 'w', encoding='utf-8') as f:+ f.write(notes_xml)++ # 创建备注幻灯片关系文件+ notes_rels_dir = notes_slides_dir / '_rels'+ notes_rels_dir.mkdir(exist_ok=True)+ notes_rels_path = notes_rels_dir / f'notesSlide{slide_num}.xml.rels'+ notes_rels_xml = create_notes_slide_rels_xml(slide_num)+ with open(notes_rels_path, 'w', encoding='utf-8') as f:+ f.write(notes_rels_xml)++ # 更新 slide.xml.rels 添加备注关联+ with open(rels_path, 'r', encoding='utf-8') as f:+ slide_rels_content = f.read()+ notes_rel = f' <Relationship Id="rId10" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/notesSlide" Target="../notesSlides/notesSlide{slide_num}.xml"/>'+ slide_rels_content = slide_rels_content.replace('</Relationships>', notes_rel + '\n</Relationships>')+ with open(rels_path, 'w', encoding='utf-8') as f:+ f.write(slide_rels_content)+if verbose:mode_str = " (PNG+SVG)" if (use_compat_mode and png_generated) else " (SVG)"- print(f" [{i}/{len(svg_files)}] {svg_path.name}{mode_str}")+ notes_str = " +备注" if (enable_notes and notes and notes.get(i)) else ""+ print(f" [{i}/{len(svg_files)}] {svg_path.name}{mode_str}{notes_str}")success_count += 1@@ -553,6 +776,15 @@ def create_pptx_with_native_svg(with open(content_types_path, 'w', encoding='utf-8') as f:f.write(content_types)+ # 添加 notesSlides 内容类型+ if enable_notes:+ for i in range(1, len(svg_files) + 1):+ override = f' <Override PartName="/ppt/notesSlides/notesSlide{i}.xml" ContentType="application/vnd.openxmlformats-officedocument.presentationml.notesSlide+xml"/>'+ if override not in content_types:+ content_types = content_types.replace('</Types>', override + '\n</Types>')+ with open(content_types_path, 'w', encoding='utf-8') as f:+ f.write(content_types)+# 重新打包 PPTXwith zipfile.ZipFile(output_path, 'w', zipfile.ZIP_DEFLATED) as zf:for file_path in extract_dir.rglob('*'):@@ -609,6 +841,11 @@ SVG 来源目录 (-s):- 新版 Office 仍显示 SVG(可编辑),旧版显示 PNG- 需要安装 svglib: pip install svglib reportlab- 使用 --no-compat 可禁用(仅 Office 2019+ 支持)++演讲备注 (默认开启):+ - 自动读取 notes/ 目录中的 Markdown 备注文件+ - 嵌入到 PPTX 的演讲者备注中+ - 使用 --no-notes 可禁用''')@@ -631,6 +868,10 @@ SVG 来源目录 (-s):parser.add_argument('--auto-advance', type=float, default=None,help='自动翻页间隔/秒 (默认: 手动翻页)')+ # 备注参数+ parser.add_argument('--no-notes', action='store_true',+ help='禁用演讲备注嵌入(默认启用)')+args = parser.parse_args()project_path = Path(args.project_path)@@ -664,6 +905,13 @@ SVG 来源目录 (-s):output_path.parent.mkdir(parents=True, exist_ok=True)verbose = not args.quiet++ # 读取备注文件+ enable_notes = not args.no_notes+ notes = {}+ if enable_notes:+ notes = find_notes_files(project_path)+if verbose:print("PPT Master - SVG 转 PPTX 工具(原生 SVG)")print("=" * 50)@@ -680,7 +928,9 @@ SVG 来源目录 (-s):transition=args.transition,transition_duration=args.transition_duration,auto_advance=args.auto_advance,- use_compat_mode=not args.no_compat+ use_compat_mode=not args.no_compat,+ notes=notes,+ enable_notes=enable_notes)sys.exit(0 if success else 1)