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:对齐模板流程与 Template_Designer 规范

hugohe339f7a906ad81
diff --git a/.agent/workflows/create-template.md b/.agent/workflows/create-template.md
index 0b0293ad..6a59523c 100644
--- a/.agent/workflows/create-template.md
+++ b/.agent/workflows/create-template.md
@@ -52,6 +52,7 @@ ls -la "<参考来源路径>"
# 创建新模板目录
mkdir -p "templates/layouts/<新模板名称>"
```
+> 说明:本流程用于**创建标准化模板库**,输出到 `templates/layouts/`。若是**项目内模板生成**,请遵循 `roles/Template_Designer.md`,输出到项目目录的 `templates/`。
---
@@ -88,7 +89,7 @@ mkdir -p "templates/layouts/<新模板名称>"
| 配色方案 | 主色系、文字色系、功能色(带 HEX 值) |
| 排版体系 | 字体栈、字号层级(H1-Sub) |
| 页面结构 | 通用布局、装饰设计 |
-| 页面类型 | 5 种页面的详细说明 |
+| 页面类型 | 4 种核心页面 + 目录页(可选) |
| SVG 技术约束 | 必须遵守项 + 禁用元素列表 |
| 占位符规范 | 常用占位符表格 |
@@ -96,7 +97,7 @@ mkdir -p "templates/layouts/<新模板名称>"
## 步骤 4:生成 SVG 模板文件
-根据 design_spec.md 的规范,生成以下 5 个 SVG 模板:
+根据 design_spec.md 的规范,生成 **4 个核心模板** + **目录页(可选)** + **可选扩展页(按需)**:
### 4.1 封面页 `01_cover.svg`
@@ -104,40 +105,54 @@ mkdir -p "templates/layouts/<新模板名称>"
- 装饰元素(与设计风格一致)
- 主标题占位符 `{{TITLE}}`
- 副标题占位符 `{{SUBTITLE}}`
-- 演讲者/单位信息占位符
+- 作者/机构占位符 `{{AUTHOR}}`
- 日期占位符 `{{DATE}}`
-### 4.2 目录页 `02_toc.svg`
+### 4.2 目录页 `02_toc.svg`(可选)
- 背景 + 顶部装饰
-- 页面标题
-- 章节列表(`{{TOC_ITEM_1}}` ~ `{{TOC_ITEM_5}}`)
+- 目录标题 `{{TOC_TITLE}}`
+- 章节列表 `{{TOC_ITEMS}}`
- 装饰元素
+> **命名说明**:目录页如需生成,保持 `02_toc.svg` 命名以兼容模板库与排序规则;未生成则直接跳过,无需调整其他文件名。
### 4.3 章节页 `02_chapter.svg`
- 深色/渐变背景
- 大号章节编号 `{{CHAPTER_NUM}}`
- 章节标题 `{{CHAPTER_TITLE}}`
-- 英文副标题 `{{CHAPTER_TITLE_EN}}`(可选)
+- 章节描述 `{{CHAPTER_DESC}}`(可选)
### 4.4 内容页 `03_content.svg`
- 白色/浅色背景
- 顶部装饰条
- 页面标题 `{{PAGE_TITLE}}`
+- 核心观点 `{{KEY_MESSAGE}}`(可选,咨询风格)
- 内容区域占位 `{{CONTENT_AREA}}`(虚线框 + 说明文字)
+- 章节名称 `{{SECTION_NAME}}`
+- 数据来源 `{{SOURCE}}`
- 页码 `{{PAGE_NUM}}`
- 页脚装饰
### 4.5 结束页 `04_ending.svg`
- 背景(与封面呼应)
-- 感谢语/结束标题
-- 感谢列表或联系信息占位符
-- 结语 `{{CLOSING_MESSAGE}}`
+- 感谢语 `{{THANK_YOU}}`
+- 口号/结束语 `{{TAGLINE}}`
+- 联系信息 `{{CONTACT_INFO}}`
+- 版权信息 `{{COPYRIGHT}}`
+- 页码 `{{PAGE_NUM}}`(可选)
- 装饰元素
+### 4.6 可选扩展页(按需)
+
+根据场景补充以下可选页面(仅建议,不强制):
+
+- 过渡页 / 小节页(如 `05_section_break.svg`)
+- 附录页(如 `06_appendix.svg`)
+- 免责声明 / 保密页(如 `07_disclaimer.svg`)
+
---
## 步骤 5:验证模板完整性
@@ -151,7 +166,7 @@ ls -la "templates/layouts/<新模板名称>"
**检查清单**:
- [ ] `design_spec.md` 包含完整的设计规范(按标准章节结构)
-- [ ] 所有 5 个 SVG 模板文件存在
+- [ ] 4 个核心模板齐全(目录页可选)
- [ ] SVG viewBox 设置正确(`0 0 1280 720`)
- [ ] 占位符格式一致(`{{PLACEHOLDER}}`)
- [ ] 颜色值统一使用 HEX 格式
@@ -176,10 +191,11 @@ ls -la "templates/layouts/<新模板名称>"
|------|------|
| `design_spec.md` | ✅ 完成 |
| `01_cover.svg` | ✅ 完成 |
-| `02_toc.svg` | ✅ 完成 |
+| `02_toc.svg` | ⬜ 可选 |
| `02_chapter.svg` | ✅ 完成 |
| `03_content.svg` | ✅ 完成 |
| `04_ending.svg` | ✅ 完成 |
+| 可选扩展页(如有) | ⬜ 未生成 |
### 设计亮点
@@ -252,7 +268,7 @@ cp templates/layouts/<新模板名称>/design_spec.md projects/<项目>/template
| | `feGaussianBlur` 等滤镜原语 | 用阴影色块替代 |
| **其他** | `<iframe>` | 不应出现在 SVG 中 |
-> 📌 **记忆口诀**:PPT 只认基础形状 + 内联样式 + 系统字体 + 实色填充
+> 📌 **记忆口诀**:PPT 只认基础形状 + 内联样式 + 系统字体(渐变可用,透明度需合规)
---
@@ -262,44 +278,28 @@ cp templates/layouts/<新模板名称>/design_spec.md projects/<项目>/template
### 禁止的透明度写法
-| ❌ 禁止 | 问题描述 | ✅ 正确替代方案 |
-| ------------------------------------ | -------------------------------- | -------------------------------------- |
-| `opacity="0.3"` (元素透明度) | PPT 可能不正确渲染 | 使用**浅色实色值**替代 |
-| `fill-opacity="0.3"` | PPT 支持有限 | 使用**浅色实色值**替代 |
-| `fill="rgba(255,255,255,0.1)"` | PPT 不支持 rgba 格式 | `fill="#FFFFFF" fill-opacity="0.1"` |
-| `stroke="rgba(0,0,0,0.5)"` | PPT 不支持 rgba 格式 | `stroke="#000000" stroke-opacity="0.5"`|
-| `<g opacity="0.2">...</g>` | PPT 不支持组透明度 | 每个子元素单独设置透明度 |
-| `<image ... opacity="0.3"/>` | PPT 不支持图片透明度 | 用遮罩层 `<rect fill="背景色" opacity="0.7"/>` |
-| `filter="url(#shadow)"` | PPT 不支持 SVG 滤镜 | 移除滤镜效果 |
+| ❌ 禁止 | 问题描述 | ✅ 正确替代方案 |
+| ----------------------------- | ------------------------ | ------------------------------------------------ |
+| `fill="rgba(255,255,255,0.1)"`| PPT 不支持 rgba 格式 | `fill="#FFFFFF" fill-opacity="0.1"` |
+| `stroke="rgba(0,0,0,0.5)"` | PPT 不支持 rgba 格式 | `stroke="#000000" stroke-opacity="0.5"` |
+| `<g opacity="0.2">...</g>` | PPT 不支持组透明度 | 每个子元素单独设置透明度 |
+| `<image ... opacity="0.3"/>` | PPT 不支持图片透明度 | 图片后加遮罩层 `<rect fill="背景色" opacity="0.7"/>` |
-### 透明度的正确替代方案
+### 透明度的正确写法
-**推荐做法**:用**浅色实色值**代替透明度,确保 PPT 兼容。
+**推荐做法**:使用 `fill-opacity` / `stroke-opacity` 或单元素 `opacity`(非 `<g>`),避免 `rgba()`。
```xml
-<!-- ❌ 禁止:使用透明度 -->
+<!-- ✅ 正确:单元素透明度 -->
<path fill="#DE3545" opacity="0.3"/>
<path fill="#DE3545" fill-opacity="0.4"/>
-
-<!-- ✅ 正确:使用计算后的浅色实色 -->
-<path fill="#F5A0A8"/> <!-- 相当于 #DE3545 + 30% 透明度 -->
-<path fill="#E97983"/> <!-- 相当于 #DE3545 + 40% 透明度 -->
```
-### 常用半透明效果的实色替代色表
-
-| 原色 | 透明度 | 替代实色 | 备注 |
-| --------- | ------ | --------- | ------------------- |
-| `#DE3545` | 30% | `#F5A0A8` | 淡红色 |
-| `#DE3545` | 40% | `#E97983` | 浅红色 |
-| `#DE3545` | 50% | `#E86A76` | 中浅红色 |
-| `#DE3545` | 60% | `#E45967` | 中红色 |
-| `#333333` | 30% | `#ADADAD` | 淡灰色 |
-| `#333333` | 40% | `#999999` | 浅灰色 |
-| `#333333` | 50% | `#666666` | 中灰色 |
-| `#FFFFFF` | 30% | `#F5F5F5` | 近白色(浅灰背景) |
+### 透明度检查要点
-> 💡 **计算公式**:混合色 = 原色 × 透明度 + 背景色 × (1 - 透明度)
+- 禁止 `rgba()` 颜色格式
+- 禁止 `<g opacity>` 组透明度
+- 禁止图片透明度,改用遮罩层
---
@@ -356,4 +356,3 @@ PPT 不支持 SVG 的 `marker-end` 属性,需使用 `<polygon>` 三角形替
- [ ] viewBox 设置正确(`0 0 1280 720`)
- [ ] 占位符格式一致(`{{PLACEHOLDER}}`)
- [ ] 设计风格在所有页面中保持一致
-
diff --git a/roles/Template_Designer.md b/roles/Template_Designer.md
index 7e4b2938..cfd2306f 100644
--- a/roles/Template_Designer.md
+++ b/roles/Template_Designer.md
@@ -26,6 +26,15 @@
| -- | `02_toc.svg` | 目录页 | **可选**:目录标题、章节列表(编号+标题) |
> **设计理念**:模板定义视觉一致性和结构性页面,内容页保持最大灵活性,让 Executor 根据实际内容决定具体布局(单栏、双栏、图文等)。
+> **命名说明**:目录页如需生成,保持 `02_toc.svg` 命名以兼容模板库与排序规则;未生成则直接跳过,无需调整其他文件名。
+
+## 可选扩展页(按需)
+
+根据场景补充以下可选页面(仅建议,不强制):
+
+- 过渡页 / 小节页(如 `05_section_break.svg`)
+- 附录页(如 `06_appendix.svg`)
+- 免责声明 / 保密页(如 `07_disclaimer.svg`)
## 模板设计规范
@@ -83,6 +92,8 @@
模板文件保存到项目的 `templates/` 目录:
+> 说明:本角色用于**项目内模板生成**,输出到项目目录的 `templates/`。如需创建**标准化模板库**,请使用 `/.agent/workflows/create-template.md`,输出到 `templates/layouts/`。
+
```
projects/<项目名>_<格式>_<日期>/
├── templates/ # 项目模板目录
@@ -110,6 +121,7 @@ projects/<项目名>_<格式>_<日期>/
| `03_content.svg` | 内容页 - 页眉页脚框架,内容区灵活 | ✅ 已生成 |
| `04_ending.svg` | 结束页 - 感谢语居中布局 | ✅ 已生成 |
| `02_toc.svg` | 目录页 - 章节列表(可选) | ⬜ 未生成 |
+| 可选扩展页(如有) | 过渡页 / 附录页 / 免责声明等 | ⬜ 未生成 |
```
## 阶段完成检查点
@@ -120,6 +132,7 @@ projects/<项目名>_<格式>_<日期>/
- [x] 已阅读 `roles/Template_Designer.md`
- [x] 已生成 4 个核心页面模板
- [ ] 目录页模板(可选)
+- [ ] 可选扩展页(如需)
- [x] 所有模板已保存到 `templates/` 目录
- [x] 模板遵循设计规范(配色、字体、布局)
- [x] 占位符标记清晰规范
diff --git a/templates/layouts/README.md b/templates/layouts/README.md
index cc6ea928..05b68806 100644
--- a/templates/layouts/README.md
+++ b/templates/layouts/README.md
@@ -86,13 +86,13 @@
## 模板文件结构
-每个布局模板包含以下标准文件:
+模板建议包含以下标准文件(目录页可选):
| 文件名 | 必须 | 用途 | 说明 |
|--------|------|------|------|
| `design_spec.md` | ✅ | 设计规范 | 完整的配色、排版、布局规范 |
| `01_cover.svg` | ✅ | 封面页 | 标题、副标题、日期、机构 |
-| `02_toc.svg` | ✅ | 目录页 | 章节列表、导航 |
+| `02_toc.svg` | ⬜ 可选 | 目录页 | 章节列表、导航 |
| `02_chapter.svg` | ✅ | 章节页 | 章节编号、章节标题 |
| `03_content.svg` | ✅ | 内容页 | 页眉页脚固定,内容区灵活 |
| `04_ending.svg` | ✅ | 结束页 | 感谢语、联系方式 |