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

docs: 同步 README 与文档说明到当前流程和目录结构

hugohe3bad3c588eae2
diff --git a/README.md b/README.md
index d0c16fce..780d1cdd 100644
--- a/README.md
+++ b/README.md
@@ -74,9 +74,10 @@ pip install -r requirements.txt
```
用户:我有一份关于 Q3 季度业绩的报告,需要制作成 PPT
-AI(Strategist 角色):好的,在开始之前我需要完成八项确认...
- 1. 画布格式:[建议] PPT 16:9
- 2. 页数范围:[建议] 8-10 页
+AI:好的,先确认是否使用模板;确认后我会继续八项确认并生成设计规范。
+ [模板选项] [建议] B) 不使用模板;如需使用模板,我会先参考 templates/layouts/layouts_index.json 给出推荐
+ [Strategist] 1. 画布格式:[建议] PPT 16:9
+ [Strategist] 2. 页数范围:[建议] 8-10 页
...
```
@@ -98,9 +99,9 @@ AI(Strategist 角色):好的,在开始之前我需要完成八项确认.
| 🎨 [设计指南](./docs/design_guidelines.md) | 配色、排版、布局规范详解 |
| 📐 [画布格式](./docs/canvas_formats.md) | PPT、小红书、朋友圈等 10+ 种格式 |
| 🖼️ [图片嵌入指南](./docs/svg_image_embedding.md) | SVG 图片嵌入最佳实践 |
-| 📊 [图表模板库](./templates/charts/) | 13 种标准化图表模板 · [在线预览](./templates/charts/preview.html) |
+| 📊 [图表模板库](./templates/charts/) | 33 种标准化图表模板 · [索引说明](./templates/charts/README.md) |
| ⚡ [快速参考](./docs/quick_reference.md) | 常用命令和参数速查 |
-| 🔧 [角色定义](./roles/README.md) | 6 个 AI 角色的完整定义 |
+| 🔧 [角色定义](./roles/README.md) | 7 个 AI 角色的完整定义 |
| 🛠️ [工具集](./tools/README.md) | 所有工具的使用说明 |
| 💼 [示例索引](./examples/README.md) | 15 个项目、229 页 SVG 示例 |
@@ -191,12 +192,14 @@ python3 tools/svg_to_pptx.py <项目路径> -s final
```
ppt-master/
-├── roles/ # AI 角色定义(6 个专业角色)
+├── .agent/ # AI 工作流与辅助配置
+├── .github/ # CI / GitHub Actions
+├── roles/ # AI 角色定义(7 个角色,含 Template_Designer)
├── docs/ # 文档中心(教程、设计指南、格式规范等)
-├── templates/ # 模板库(图表模板 + 640+ 图标)
+├── templates/ # 模板库(33 个图表模板 + 640+ 图标 + 布局模板)
├── tools/ # 工具集(项目管理、转换、处理)
├── examples/ # 示例项目(15 个完整案例)
-└── projects/ # 用户项目工作区(含 sources/)
+└── projects/ # 用户项目工作区(README / 设计规范 / sources / images / notes / svg_output / svg_final / templates / *.pptx)
```
---
diff --git a/README_EN.md b/README_EN.md
index 142bc5f2..0db79767 100644
--- a/README_EN.md
+++ b/README_EN.md
@@ -74,9 +74,10 @@ Open the AI chat panel in your editor and describe what content you want to crea
```
User: I have a Q3 quarterly report that needs to be made into a PPT
-AI (Strategist role): Sure, before we begin I need to complete eight confirmations...
- 1. Canvas format: [Recommended] PPT 16:9
- 2. Page count: [Recommended] 8-10 pages
+AI: Sure. First we'll confirm whether to use a template; after that Strategist will continue with the eight confirmations and generate the design spec.
+ [Template Option] [Recommended] B) No template; if a template is needed, I will first consult templates/layouts/layouts_index.json and recommend one
+ [Strategist] 1. Canvas format: [Recommended] PPT 16:9
+ [Strategist] 2. Page count: [Recommended] 8-10 pages
...
```
@@ -98,9 +99,9 @@ AI (Strategist role): Sure, before we begin I need to complete eight confirmatio
| 🎨 [Design Guidelines](./docs/design_guidelines.md) | Colors, typography, layout specifications |
| 📐 [Canvas Formats](./docs/canvas_formats.md) | PPT, Xiaohongshu, WeChat Moments, and 10+ formats |
| 🖼️ [Image Embedding Guide](./docs/svg_image_embedding.md) | SVG image embedding best practices |
-| 📊 [Chart Template Library](./templates/charts/) | 13 standardized chart templates · [Online Preview](./templates/charts/preview.html) |
+| 📊 [Chart Template Library](./templates/charts/) | 33 standardized chart templates · [Index Guide](./templates/charts/README.md) |
| ⚡ [Quick Reference](./docs/quick_reference.md) | Common commands and parameters cheat sheet |
-| 🔧 [Role Definitions](./roles/README.md) | Complete definitions of 6 AI roles |
+| 🔧 [Role Definitions](./roles/README.md) | Complete definitions of 7 AI roles |
| 🛠️ [Toolset](./tools/README.md) | Usage instructions for all tools |
| 💼 [Examples Index](./examples/README.md) | 15 projects, 229 SVG pages of examples |
@@ -191,12 +192,14 @@ python3 tools/svg_to_pptx.py <project_path> -s final
```
ppt-master/
-├── roles/ # AI role definitions (6 professional roles)
+├── .agent/ # AI workflows and helper configs
+├── .github/ # CI / GitHub Actions
+├── roles/ # AI role definitions (7 roles including Template_Designer)
├── docs/ # Documentation center (tutorials, design guides, format specs)
-├── templates/ # Template library (chart templates + 640+ icons)
+├── templates/ # Template library (33 chart templates + 640+ icons + layouts)
├── tools/ # Toolset (project management, conversion, processing)
├── examples/ # Example projects (15 complete cases)
-└── projects/ # User project workspace (with sources/)
+└── projects/ # User project workspace (README / design spec / sources / images / notes / svg_output / svg_final / templates / *.pptx)
```
---
diff --git a/docs/README.md b/docs/README.md
index 0a411571..344d03c6 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -4,6 +4,7 @@
- [canvas_formats.md](./canvas_formats.md) - 画布格式规范
- [design_guidelines.md](./design_guidelines.md) - 设计规范详解
+- [image_layout_spec.md](./image_layout_spec.md) - 图片比例与布局适配规范
- [workflow_tutorial.md](./workflow_tutorial.md) - 工作流教程
- [quick_reference.md](./quick_reference.md) - 快速参考指南
- [svg_image_embedding.md](./svg_image_embedding.md) - SVG 图片嵌入指南
diff --git a/docs/canvas_formats.md b/docs/canvas_formats.md
index 9929586b..3fce9aea 100644
--- a/docs/canvas_formats.md
+++ b/docs/canvas_formats.md
@@ -178,16 +178,16 @@
```bash
# viewBox 应以 0 0 起始
-grep -R 'viewBox="0 0 ' examples
+rg 'viewBox="0 0 ' examples
# 常见格式
-grep -R 'viewBox="0 0 1280 720"' examples # PPT 16:9
-grep -R 'viewBox="0 0 1024 768"' examples # PPT 4:3
-grep -R 'viewBox="0 0 1242 1660"' examples # 小红书 3:4
-grep -R 'viewBox="0 0 1080 1080"' examples # 朋友圈/Instagram 1:1
-grep -R 'viewBox="0 0 1080 1920"' examples # Story 9:16
-grep -R 'viewBox="0 0 900 383"' examples # 公众号头图 2.35:1
-grep -R 'viewBox="0 0 1240 1754"' examples # A4 150dpi
+rg 'viewBox="0 0 1280 720"' examples # PPT 16:9
+rg 'viewBox="0 0 1024 768"' examples # PPT 4:3
+rg 'viewBox="0 0 1242 1660"' examples # 小红书 3:4
+rg 'viewBox="0 0 1080 1080"' examples # 朋友圈/Instagram 1:1
+rg 'viewBox="0 0 1080 1920"' examples # Story 9:16
+rg 'viewBox="0 0 900 383"' examples # 公众号头图 2.35:1
+rg 'viewBox="0 0 1240 1754"' examples # A4 150dpi
```
## 🎯 格式特定设计建议
diff --git a/docs/design_guidelines.md b/docs/design_guidelines.md
index 2be23475..0b01c794 100644
--- a/docs/design_guidelines.md
+++ b/docs/design_guidelines.md
@@ -297,8 +297,10 @@ H3 - 章节标题: 22-27px, SemiBold (1.2-1.5×)
**快速规则**:
- 比例 > 2.0 (超宽) → 上下布局
-- 比例 1.2-2.0 → 上下或左右,需计算验证
-- 比例 < 1.5 (标准/竖图) → 左右布局
+- 比例 1.5-2.0 (宽幅) → 优先上下布局,若文字区不足则改左右布局
+- 比例 1.2-1.5 (标准横图) → 左右布局
+- 比例 0.8-1.2 (方形) → 左右布局
+- 比例 < 0.8 (竖图) → 左右布局
## 图表设计
@@ -393,10 +395,11 @@ H3 - 章节标题: 22-27px, SemiBold (1.2-1.5×)
### 项目内置图标库(推荐)
-本项目提供 **预置图标库**,位于 `templates/icons/`,包含 40+ 常用图标,风格统一,可直接复制使用。
+本项目提供 **预置图标库**,位于 `templates/icons/`,包含 **640+ 个 SVG 图标**,可直接复制或通过占位符方式嵌入。
```
-查看图标: 浏览器打开 templates/icons/preview.html
+查看完整索引: templates/icons/FULL_INDEX.md
+程序化查询: templates/icons/icons_index.json
使用方式: 详见 templates/icons/README.md
```
@@ -430,7 +433,7 @@ H3 - 章节标题: 22-27px, SemiBold (1.2-1.5×)
- 识别度高
- 多种样式
-3. **Feather Icons** (https://feathericons.com/)
+4. **Feather Icons** (https://feathericons.com/)
- 极简风格
- 线条清晰
- 轻量级
diff --git a/docs/image_layout_spec.md b/docs/image_layout_spec.md
index 43a41410..cdbc6cae 100644
--- a/docs/image_layout_spec.md
+++ b/docs/image_layout_spec.md
@@ -13,7 +13,7 @@
2. 根据比例选择布局类型
3. 计算图片最大展示尺寸
4. 分配剩余空间给文字区域
-5. 将结果填入《设计规范》的图片资源清单
+5. 将结果填入《设计规范与内容大纲》的图片资源清单
```
**执行时机**:若图片方案包含「B) 用户提供」,在 Strategist 阶段完成八项确认后、进入内容分析与大纲编制之前,必须运行扫描并填充图片资源清单。
diff --git a/docs/quick_reference.md b/docs/quick_reference.md
index 83ebd94d..5c60ba23 100644
--- a/docs/quick_reference.md
+++ b/docs/quick_reference.md
@@ -7,6 +7,7 @@
| 角色 | 何时使用 | 输入 | 输出 |
| --------------------------- | ------------------------------ | ------------ | ------------------ |
| **Strategist** | 项目开始时 | 源文档 | 设计规范与内容大纲 |
+| **Template_Designer** | 需要创建新模板时 | 设计规范 | 页面模板 SVG |
| **Image_Generator** | 选择 AI 生成图片时 | 图片资源清单 | 图片文件 + 提示词 |
| **Executor_General** | 生成通用风格页面 | 设计规范 | SVG 代码 |
| **Executor_Consultant** | 生成一般咨询风格页面 | 设计规范 | SVG 代码 |
@@ -22,6 +23,10 @@
- [ ] 确定期望的页面数量
- [ ] 选择设计风格(通用 / 一般咨询 / 顶级咨询)
- [ ] 准备相关数据和素材
+- [ ] 创建项目文件夹:`python3 tools/project_manager.py init <名称> --format <格式>`
+- [ ] 归档源材料到项目目录:`python3 tools/project_manager.py import-sources <项目路径> <源文件或URL...>`
+- [ ] 确认模板选项(A 使用已有模板 / B 不使用模板)
+- [ ] 若选择 A,先根据 `templates/layouts/layouts_index.json` 推荐并复制模板
### ✅ 使用 Strategist
@@ -38,8 +43,6 @@
- [ ] **排版方案**(字体组合 P1-P5 + 正文字号基准 18-24px)
- [ ] 等待 Strategist 生成设计规范
- [ ] 仔细检查并确认设计规范
-- [ ] **创建项目文件夹**:`python3 tools/project_manager.py init <名称> --format <格式>`
-- [ ] **归档源材料到项目目录**:`python3 tools/project_manager.py import-sources <项目路径> <源文件或URL...>`
- [ ] 保存设计规范到项目文件夹
💡 **提示**: Strategist 不仅会提问,还会主动提供专业建议供你参考
@@ -58,7 +61,7 @@
💡 **提示**: 图片生成是串行环节,必须完成后才能进入 Executor 阶段
-### ✅ 使用 Executor(两阶段)
+### ✅ 使用 Executor(SVG + 讲稿)
**视觉构建阶段**:
- [ ] 明确告知需要生成哪一页
@@ -185,7 +188,7 @@
请根据设计规范生成第[X]页:[页面主题]
请将SVG保存到:projects/[项目名]_[格式]_[YYYYMMDD]/svg_output/[页码]_[主题].svg
-例如: projects/company_report_20251012/svg_output/01_cover.svg
+例如: projects/company_report_ppt169_20251012/svg_output/01_cover.svg
```
### 请求修改
@@ -371,7 +374,7 @@ sources/
### 设计规范
```
-design_specification.md
+设计规范与内容大纲.md
```
### SVG 文件
diff --git a/docs/svg_image_embedding.md b/docs/svg_image_embedding.md
index 3263001b..9fb1d6fc 100644
--- a/docs/svg_image_embedding.md
+++ b/docs/svg_image_embedding.md
@@ -1,6 +1,6 @@
# SVG 图片嵌入指南
-本文档介绍如何在 SVG 文件中添加图片。
+本文档介绍如何在 SVG 文件中添加图片,并说明当前项目中的推荐工作流。
---
@@ -43,13 +43,17 @@
├── 已有/待生成 → <image href="../images/xxx.png" .../>
└── 占位符 → 虚线框 + 描述文本
-4. 预览
- └── python3 -m http.server 8000
+4. 预览原始版本
+ └── python3 -m http.server -d <项目路径> 8000
+ 然后访问 /svg_output/<文件名>.svg
-5. 导出(可选)
- └── python3 tools/embed_images.py *.svg
+5. 后处理与导出(推荐)
+ ├── python3 tools/finalize_svg.py <项目路径>
+ └── python3 tools/svg_to_pptx.py <项目路径> -s final
```
+> 推荐做法:生成阶段在 `svg_output/` 中保留外部引用,后处理阶段通过 `finalize_svg.py` 自动把图片嵌入到 `svg_final/`,再从 `svg_final/` 导出 PPTX。
+
---
## 技术参考
@@ -58,17 +62,17 @@
| 方式 | 优点 | 缺点 | 适用场景 |
|------|------|------|----------|
-| **外部引用** | 文件小、图片可单独更新 | 需要HTTP服务器 | 开发调试阶段 |
-| **Base64 内嵌** | 完全独立、可离线查看 | 文件体积大 | 分享导出阶段 |
+| **外部引用** | 文件小、迭代快、便于替换素材 | 预览时需从项目根目录起 HTTP 服务 | `svg_output/` 开发调试阶段 |
+| **Base64 内嵌** | 文件独立、导出稳定、适合 PPTX | 文件体积更大 | `svg_final/` 导出与交付阶段 |
---
-## 方式一:外部引用(开发阶段推荐)
+## 方式一:外部引用(生成阶段推荐)
### 语法
```xml
-<image href="image.png" x="0" y="0" width="1280" height="720"
+<image href="../images/image.png" x="0" y="0" width="1280" height="720"
preserveAspectRatio="xMidYMid slice"/>
```
@@ -76,7 +80,7 @@
| 属性 | 说明 | 示例 |
|------|------|------|
-| `href` | 图片路径(相对或绝对) | `"cover.png"` 或 `"./images/cover.png"` |
+| `href` | 图片路径(相对或绝对) | `"../images/cover.png"` 或 `"../sources/article_files/image_1.png"` |
| `x`, `y` | 图片左上角位置 | `x="0" y="0"` |
| `width`, `height` | 图片显示尺寸 | `width="1280" height="720"` |
| `preserveAspectRatio` | 缩放方式 | `"xMidYMid slice"` 居中裁剪 |
@@ -91,19 +95,19 @@
### 预览方式
-由于浏览器安全限制,直接双击打开 SVG 无法加载外部图片。需要通过 HTTP 服务器访问:
+由于浏览器安全限制,直接双击打开 SVG 无法加载外部图片。项目中的图片通常位于 `images/` 或 `sources/*_files/`,因此应从**项目根目录**启动 HTTP 服务器:
```bash
# 启动本地服务器
-python3 -m http.server --directory <svg目录> 8000
+python3 -m http.server -d <项目路径> 8000
# 访问
-http://localhost:8000/your_file.svg
+http://localhost:8000/svg_output/your_file.svg
```
---
-## 方式二:Base64 内嵌(分享导出推荐)
+## 方式二:Base64 内嵌(交付阶段推荐)
### 语法
@@ -129,111 +133,29 @@ data:<MIME类型>;base64,<Base64编码数据>
## 转换流程
-### 步骤 1:生成 Base64 编码
-
-**macOS / Linux:**
+### 推荐方式:统一走 `finalize_svg.py`
```bash
-# 将图片转换为 Base64 并保存到文件
-base64 -i image.png -o image.b64
-
-# 或直接输出到终端
-base64 -i image.png
-```
+# 从 svg_output 复制到 svg_final,并自动处理图标、图片、文本与圆角
+python3 tools/finalize_svg.py <项目路径>
-**Windows (PowerShell):**
-
-```powershell
-[Convert]::ToBase64String([IO.File]::ReadAllBytes("image.png")) > image.b64
+# 从最终版本导出 PPTX
+python3 tools/svg_to_pptx.py <项目路径> -s final
```
-### 步骤 2:嵌入 SVG
-
-**手动方式:**
-
-1. 打开 `.b64` 文件,复制全部内容
-2. 在 SVG 中替换 `href="image.png"` 为 `href="data:image/png;base64,<粘贴内容>"`
-
-**自动化脚本(推荐):**
-
-```python
-#!/usr/bin/env python3
-"""
-SVG 图片嵌入工具
-将 SVG 中引用的外部图片转换为 Base64 内嵌格式
-"""
-
-import os
-import base64
-import re
-import sys
-
-def get_mime_type(filename):
- """根据文件扩展名返回 MIME 类型"""
- ext = filename.lower().split('.')[-1]
- mime_map = {
- 'png': 'image/png',
- 'jpg': 'image/jpeg',
- 'jpeg': 'image/jpeg',
- 'gif': 'image/gif',
- 'webp': 'image/webp',
- 'svg': 'image/svg+xml',
- }
- return mime_map.get(ext, 'application/octet-stream')
-
-def embed_images_in_svg(svg_path):
- """将 SVG 文件中的外部图片转换为 Base64 内嵌"""
- svg_dir = os.path.dirname(svg_path)
-
- with open(svg_path, 'r', encoding='utf-8') as f:
- content = f.read()
-
- # 匹配 href="xxx.png" 或 href="xxx.jpg" 等
- pattern = r'href="([^"]+\.(png|jpg|jpeg|gif|webp))"'
-
- def replace_with_base64(match):
- img_path = match.group(1)
- full_path = os.path.join(svg_dir, img_path)
-
- if not os.path.exists(full_path):
- print(f"Warning: Image not found: {full_path}")
- return match.group(0)
-
- with open(full_path, 'rb') as img_file:
- b64_data = base64.b64encode(img_file.read()).decode('utf-8')
-
- mime_type = get_mime_type(img_path)
- print(f"Embedded: {img_path} ({len(b64_data)} chars)")
-
- return f'href="data:{mime_type};base64,{b64_data}"'
-
- new_content = re.sub(pattern, replace_with_base64, content)
-
- with open(svg_path, 'w', encoding='utf-8') as f:
- f.write(new_content)
-
- print(f"Updated: {svg_path}")
-
-if __name__ == '__main__':
- if len(sys.argv) < 2:
- print("Usage: python embed_images.py <svg_file> [svg_file2] ...")
- sys.exit(1)
-
- for svg_file in sys.argv[1:]:
- if os.path.exists(svg_file):
- embed_images_in_svg(svg_file)
- else:
- print(f"File not found: {svg_file}")
-```
+### 独立使用 `embed_images.py`(高级用法)
-### 步骤 3:使用脚本
+当你只想单独处理某几个 SVG,而不想跑完整个后处理流程时,可直接使用:
```bash
-# 保存上述脚本为 embed_images.py,然后运行:
-python3 embed_images.py path/to/your_file.svg
+# 处理单个 SVG
+python3 tools/embed_images.py <svg文件>
-# 批量处理多个文件
-python3 embed_images.py *.svg
+# 批量处理多个 SVG
+python3 tools/embed_images.py <项目路径>/svg_output/*.svg
+
+# 仅预览,不实际写回
+python3 tools/embed_images.py --dry-run <项目路径>/svg_output/*.svg
```
---
@@ -245,18 +167,19 @@ python3 embed_images.py *.svg
```
1. 开发阶段
├── 创建 SVG 文件,使用外部引用
- │ <image href="cover.png" .../>
+ │ <image href="../images/cover.png" .../>
│
├── 启动本地服务器预览
- │ python3 -m http.server 8000
+ │ python3 -m http.server -d <项目路径> 8000
│
└── 调试修改,快速迭代
2. 导出阶段
- ├── 运行嵌入脚本
- │ python3 embed_images.py *.svg
+ ├── 运行后处理
+ │ python3 tools/finalize_svg.py <项目路径>
│
- └── 得到独立的 SVG 文件,可直接分享
+ └── 从 svg_final/ 导出 PPTX
+ python3 tools/svg_to_pptx.py <项目路径> -s final
```
---
@@ -279,12 +202,19 @@ pngquant --quality=65-80 input.png -o output.png
```
project/
+├── images/
+│ ├── cover_bg.png
+│ └── ...
+├── sources/
+│ ├── article.md
+│ └── article_files/
+│ └── image_1.png
├── svg_output/
-│ ├── 01_cover.svg # 开发版(外部引用)
-│ ├── cover_bg.png # 图片资源
+│ ├── 01_cover.svg # 原始版本(外部引用)
│ └── ...
-└── svg_export/
- └── 01_cover_embedded.svg # 导出版(Base64 内嵌)
+└── svg_final/
+ ├── 01_cover.svg # 最终版本(已嵌入图片)
+ └── ...
```
### 3. 圆角处理(禁止 clipPath)
@@ -302,9 +232,9 @@ project/
### Q: 直接打开 SVG 看不到图片?
-A: 浏览器安全策略阻止了本地文件的跨域请求。解决方案:
-- 使用 HTTP 服务器访问
-- 或将图片转换为 Base64 内嵌
+A: 浏览器安全策略阻止了本地文件的跨目录请求。解决方案:
+- 从项目根目录启动 HTTP 服务器,再访问 `/svg_output/*.svg`
+- 或先运行 `python3 tools/finalize_svg.py <项目路径>`,再查看 `svg_final/`
### Q: Base64 文件太大怎么办?
diff --git a/docs/workflow_tutorial.md b/docs/workflow_tutorial.md
index daf24f9f..dce49439 100644
--- a/docs/workflow_tutorial.md
+++ b/docs/workflow_tutorial.md
@@ -323,11 +323,9 @@
⚠️ **重要**: 在开始内容分析之前,Strategist 必须首先完成初始沟通与范围确认。
-**Strategist 的八项确认:**
+**模板选项属于流程前置步骤;Strategist 负责八项确认。**
```
-在开始分析您的内容之前,我需要先完成八项确认:
-
1. 画布格式:
[建议] PPT 标准格式 (1280×720, 16:9),适合季度战略会议的投影展示。
@@ -650,10 +648,13 @@ Optimizer_CRAP:
- 常见问题解答
- 推荐理由
-2. 与Strategist对话(八项确认)
+2. 先确认模板选项,再与 Strategist 对话
你: 我需要为小红书创建一份产品使用技巧分享
- Strategist: 在开始之前,我需要完成八项确认:
+ 系统/流程: 先确认模板选项:[建议] B) 不使用模板,自由生成。
+ 你: 按建议,模板选 B。
+
+ Strategist: 收到,下面继续八项确认:
1. 画布格式:[建议] 小红书帖子格式 (1242×1660, 3:4),
竖屏比例最适合手机端浏览,符合小红书用户阅读习惯。
@@ -935,8 +936,10 @@ Executor: 收到,我将从您指定的文件夹中引用图标。
在生成阶段,按规范使用 `<tspan>` 进行手动换行。后处理会自动扁平化:
```bash
-# 直接运行,无需参数
+# 推荐:直接运行后处理,已包含文本扁平化
python3 tools/finalize_svg.py <项目路径>
+
+# 高级用法:仅在需要单独处理某个 SVG 时再直接调用
python3 tools/flatten_tspan.py path/to/input.svg path/to/output.svg
```
diff --git a/projects/README.md b/projects/README.md
index aa2a613f..63a2d112 100644
--- a/projects/README.md
+++ b/projects/README.md
@@ -5,24 +5,44 @@
## 创建新项目
```bash
-python tools/project_manager.py init my_project --format ppt169
+python3 tools/project_manager.py init my_project --format ppt169
```
## 目录结构
-完成后的项目应包含:
+一个典型项目通常包含以下内容:
```
project_name_format_YYYYMMDD/
├── README.md
├── 设计规范与内容大纲.md
+├── sources/
+│ ├── 原始文件 / URL 归档 / 转换后的 Markdown
+│ └── *_files/ # Markdown 配套资源目录(如图片)
+├── images/ # 项目使用的图片资源
+├── notes/
+│ ├── 01_xxx.md
+│ ├── 02_xxx.md
+│ └── total.md
├── svg_output/
-│ ├── 01_cover.svg
+│ ├── 01_xxx.svg
│ └── ...
-└── images/ (可选)
+├── svg_final/
+│ ├── 01_xxx.svg
+│ └── ...
+├── templates/ # 项目级模板(如有)
+├── *.pptx
+└── image_analysis.csv # 可选,图片扫描分析结果
```
+项目可以停留在不同阶段,不一定一次性具备全部产物。例如:
+
+- 仅完成 `sources/` 归档和《设计规范与内容大纲》
+- 已生成 `svg_output/`,但尚未执行后处理
+- 已完成 `svg_final/`、`notes/` 和 `*.pptx`
+
## 注意事项
- 此目录下的内容已被 `.gitignore` 排除
- 完成的项目可以移动到 `examples/` 目录分享
+- 工作空间外文件默认复制;工作空间内文件会直接移动到项目 `sources/`