Skip to content

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.md
index 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.md
index 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.md
index 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.md
index 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.md
index 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.0
python3 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.py
index 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[Pat
return 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('&', '&amp;').replace('<', '&lt;').replace('>', '&gt;')
+
+ # 将换行转换为 <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 transition
print(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)
+
# 重新打包 PPTX
with 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)