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): 支持按文件名匹配 notes 文件

hugohe3e2855193f7d7
diff --git a/AGENTS.md b/AGENTS.md
index d7093032..f451d446 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -304,11 +304,14 @@ python3 tools/svg_to_pptx.py <项目路径> -s final --no-notes
```
project/
├── svg_output/ # 原始版本(带占位符,作为模板参考)
+│ ├── 01_封面.svg
+│ ├── 02_目录.svg
+│ └── ...
├── svg_final/ # 最终版本(后处理完成)
├── images/ # 图片资源
-├── notes/ # 演讲备注(Markdown 格式,可选)
-│ ├── slide01.md
-│ ├── slide02.md
+├── notes/ # 演讲备注(Markdown 格式,与 SVG 同名)
+│ ├── 01_封面.md
+│ ├── 02_目录.md
│ └── ...
└── *.pptx # 导出的 PPT 文件
```
diff --git a/roles/Executor_Consultant.md b/roles/Executor_Consultant.md
index c095e8f6..e64d1f76 100644
--- a/roles/Executor_Consultant.md
+++ b/roles/Executor_Consultant.md
@@ -135,7 +135,9 @@
生成每页 SVG 后,**同步创建**对应的演讲备注文件。
-**输出路径**: `notes/slideXX.md`
+**文件命名规范**:
+- **推荐**:与 SVG 同名(如 `01_封面.svg` 对应 `notes/01_封面.md`)
+- **兼容**:也支持 `slide01.md` 格式(向后兼容)
**格式模板**:
@@ -156,3 +158,4 @@ X 分钟
**要求**:
- 讲稿建议应自然流畅
- 用户可在 `notes/` 目录手动编辑覆盖
+
diff --git a/roles/Executor_Consultant_Top.md b/roles/Executor_Consultant_Top.md
index 96bcbb90..04630515 100644
--- a/roles/Executor_Consultant_Top.md
+++ b/roles/Executor_Consultant_Top.md
@@ -229,7 +229,9 @@
生成每页 SVG 后,**同步创建**对应的演讲备注文件,为演讲者提供讲稿参考。
-**输出路径**: `notes/slideXX.md`(XX 为两位数页码,如 `slide01.md`)
+**文件命名规范**:
+- **推荐**:与 SVG 同名(如 `01_封面.svg` 对应 `notes/01_封面.md`)
+- **兼容**:也支持 `slide01.md` 格式(向后兼容)
**格式模板**:
@@ -253,3 +255,4 @@ X 分钟
- 讲稿建议应自然流畅,便于直接朗读
- 咨询风格应突出数据解读和洞察传达
- 用户可在 `notes/` 目录手动编辑覆盖
+
diff --git a/roles/Executor_General.md b/roles/Executor_General.md
index 939b7fae..056df034 100644
--- a/roles/Executor_General.md
+++ b/roles/Executor_General.md
@@ -140,7 +140,9 @@
生成每页 SVG 后,**同步创建**对应的演讲备注文件。
-**输出路径**: `notes/slideXX.md`
+**文件命名规范**:
+- **推荐**:与 SVG 同名(如 `01_封面.svg` 对应 `notes/01_封面.md`)
+- **兼容**:也支持 `slide01.md` 格式(向后兼容)
**格式模板**:
@@ -161,3 +163,4 @@ X 分钟
**要求**:
- 讲稿建议应自然流畅
- 用户可在 `notes/` 目录手动编辑覆盖
+
diff --git a/tools/README.md b/tools/README.md
index 56b9d220..4ab8eafd 100644
--- a/tools/README.md
+++ b/tools/README.md
@@ -473,7 +473,11 @@ python3 tools/svg_to_pptx.py <项目路径> -s final -q
**演讲备注**:
-工具默认读取 `notes/` 目录中的 Markdown 备注文件(如 `slide01.md`),并嵌入到 PPTX 的演讲者备注中。
+工具自动读取 `notes/` 目录中的 Markdown 备注文件,并嵌入到 PPTX 的演讲者备注中。
+
+**文件命名支持两种方式**:
+- **推荐**:与 SVG 同名(如 `01_封面.svg` 对应 `notes/01_封面.md`)
+- **兼容**:`slide01.md` 格式(向后兼容)
| 参数 | 说明 |
|------|------|
diff --git a/tools/svg_to_pptx.py b/tools/svg_to_pptx.py
index 220ab8d2..ac96c561 100644
--- a/tools/svg_to_pptx.py
+++ b/tools/svg_to_pptx.py
@@ -247,15 +247,20 @@ 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:
+def find_notes_files(project_path: Path, svg_files: List[Path] = None) -> dict:
"""
查找项目中的备注文件
+ 支持两种匹配模式:
+ 1. 按文件名匹配(推荐):notes/01_封面.md 对应 01_封面.svg
+ 2. 按序号匹配(向后兼容):notes/slide01.md 对应第1个 SVG
+
Args:
project_path: 项目目录路径
+ svg_files: SVG 文件列表(用于按文件名匹配)
Returns:
- 字典,key 为幻灯片编号(1-indexed),value 为备注内容
+ 字典,key 为 SVG 文件名(不含扩展名)或幻灯片编号,value 为备注内容
"""
notes_dir = project_path / 'notes'
notes = {}
@@ -263,19 +268,40 @@ def find_notes_files(project_path: Path) -> dict:
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
+ # 收集所有 notes 文件信息
+ notes_by_name = {} # 按文件名
+ notes_by_num = {} # 按序号(向后兼容)
+
+ for notes_file in notes_dir.glob('*.md'):
+ try:
+ with open(notes_file, 'r', encoding='utf-8') as f:
+ content = f.read().strip()
+ if not content:
+ continue
+
+ stem = notes_file.stem
+ notes_by_name[stem] = content
+
+ # 尝试提取序号(向后兼容 slide01.md 格式)
+ match = re.search(r'slide[_]?(\d+)', stem)
+ if match:
+ notes_by_num[int(match.group(1))] = content
+ except Exception:
+ pass
+
+ # 如果提供了 SVG 文件列表,优先按文件名匹配
+ if svg_files:
+ for i, svg_path in enumerate(svg_files, 1):
+ svg_stem = svg_path.stem
+ if svg_stem in notes_by_name:
+ # 按文件名匹配
+ notes[svg_stem] = notes_by_name[svg_stem]
+ elif i in notes_by_num:
+ # 回退到按序号匹配
+ notes[svg_stem] = notes_by_num[i]
+ else:
+ # 没有 SVG 文件列表时,返回序号索引(向后兼容)
+ notes = notes_by_num
return notes
@@ -713,7 +739,9 @@ def create_pptx_with_native_svg(
# 处理备注
if enable_notes:
- notes_content = notes.get(i, '') if notes else ''
+ # 按文件名匹配(新逻辑)或按序号匹配(向后兼容)
+ svg_stem = svg_path.stem
+ notes_content = notes.get(svg_stem, notes.get(i, '')) if notes else ''
if notes_content:
notes_text = markdown_to_plain_text(notes_content)
else:
@@ -747,7 +775,8 @@ def create_pptx_with_native_svg(
if verbose:
mode_str = " (PNG+SVG)" if (use_compat_mode and png_generated) else " (SVG)"
- notes_str = " +备注" if (enable_notes and notes and notes.get(i)) else ""
+ has_notes = enable_notes and notes and (notes.get(svg_stem) or notes.get(i))
+ notes_str = " +备注" if has_notes else ""
print(f" [{i}/{len(svg_files)}] {svg_path.name}{mode_str}{notes_str}")
success_count += 1
@@ -844,7 +873,9 @@ SVG 来源目录 (-s):
演讲备注 (默认开启):
- 自动读取 notes/ 目录中的 Markdown 备注文件
- - 嵌入到 PPTX 的演讲者备注中
+ - 支持两种命名方式:
+ 1. 按文件名匹配(推荐):01_封面.md 对应 01_封面.svg
+ 2. 按序号匹配:slide01.md 对应第1个 SVG(向后兼容)
- 使用 --no-notes 可禁用
'''
)
@@ -910,7 +941,7 @@ SVG 来源目录 (-s):
enable_notes = not args.no_notes
notes = {}
if enable_notes:
- notes = find_notes_files(project_path)
+ notes = find_notes_files(project_path, svg_files)
if verbose:
print("PPT Master - SVG 转 PPTX 工具(原生 SVG)")