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: 新增图片布局强制规范

hugohe30b02c06f2f24
diff --git a/AGENTS.md b/AGENTS.md
index 320ce99b..34a4f9f1 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -275,6 +275,7 @@ project/
| 图表模板 | `templates/charts/` |
| **图标库** | `templates/icons/` (640+ 图标) |
| 设计指南 | `docs/design_guidelines.md` |
+| **图片布局规范** | `docs/image_layout_spec.md` ⚠️ 强制执行 |
| 画布格式 | `docs/canvas_formats.md` |
| 图片嵌入 | `docs/svg_image_embedding.md` |
| 工作流教程 | `docs/workflow_tutorial.md` |
diff --git a/docs/design_guidelines.md b/docs/design_guidelines.md
index ed4480e2..05de93a3 100644
--- a/docs/design_guidelines.md
+++ b/docs/design_guidelines.md
@@ -282,6 +282,17 @@ H3 - 章节标题: 28-32px, SemiBold
按钮: 6-8px
```
+## 图片布局规范
+
+含图片页面的布局需根据图片比例动态计算,确保图片完整展示。
+
+**详细规范请参考**:[图片布局规范](./image_layout_spec.md)
+
+**快速规则**:
+- 比例 > 2.0 (超宽) → 上下布局
+- 比例 1.2-2.0 → 上下或左右,需计算验证
+- 比例 < 1.5 (标准/竖图) → 左右布局
+
## 图表设计
### 常用图表类型
diff --git a/docs/image_layout_spec.md b/docs/image_layout_spec.md
new file mode 100644
index 00000000..542461d9
--- /dev/null
+++ b/docs/image_layout_spec.md
@@ -0,0 +1,227 @@
+# 图片布局规范(强制执行)
+
+本文档定义了含图片页面的布局规则。Strategist 在规划阶段、Executor 在生成阶段都必须遵循。
+
+**核心原则:根据图片原始比例计算布局,确保图片完整展示,杜绝留白或裁切。**
+
+---
+
+## 布局决策流程
+
+```
+1. 获取图片原始尺寸 → 计算比例 (宽/高)
+2. 根据比例选择布局类型
+3. 计算图片最大展示尺寸
+4. 分配剩余空间给文字区域
+5. 将结果填入《设计规范》的图片资源清单
+```
+
+---
+
+## 布局类型选择(强制)
+
+| 图片比例 | 布局类型 | 图片位置 | 说明 |
+|----------|----------|----------|------|
+| **> 2.0** (超宽) | 上下分栏 | 上方通栏 | 图片占画布宽度,高度按比例计算 |
+| **1.5 - 2.0** (宽幅) | 上下分栏 | 上方 | 图片宽度=内容区宽度,高度按比例 |
+| **1.2 - 1.5** (标准) | 左右分栏 | 左侧 | 图片高度优先适配,宽度按比例 |
+| **0.8 - 1.2** (方形) | 左右分栏 | 左侧 | 图片取内容区高度,宽度按比例 |
+| **< 0.8** (竖图) | 左右分栏 | 左侧 | 图片高度=内容区高度,宽度按比例 |
+
+> ⚠️ **边界情况**:当比例处于边界值时(如 1.5),需根据文字量判断。文字多选左右布局,文字少选上下布局。
+
+---
+
+## 尺寸计算公式
+
+### PPT 16:9 (1280×720) 画布参数
+
+```
+画布尺寸: 1280 × 720 px
+内容区: 1160 × 640 px (左右边距 60px, 上下边距 40px)
+标题区高度: 60 px
+内容起点: y = 80 px (标题 + 间距)
+```
+
+### 上下布局计算
+
+```
+给定:
+ 图片比例 R = 原始宽度 / 原始高度
+ 内容区宽度 W = 1160 px
+ 内容区高度 H = 640 px
+
+计算:
+ 图片宽度 = W = 1160 px
+ 图片高度 = W / R = 1160 / R px
+
+ 文字区高度 = H - 图片高度 - 间距(20px)
+
+验证:
+ 文字区高度 >= 150px (至少能放 3-4 行文字)
+ 若不满足,改用左右布局
+```
+
+### 左右布局计算
+
+```
+给定:
+ 图片比例 R = 原始宽度 / 原始高度
+ 内容区宽度 W = 1160 px
+ 内容区高度 H = 600 px (留 40px 底部页码区)
+
+计算方式 1(高度优先,适用于竖图):
+ 图片高度 = H = 600 px
+ 图片宽度 = H × R = 600 × R px
+ 文字区宽度 = W - 图片宽度 - 间距(20px)
+
+计算方式 2(宽度受限,适用于宽图转左右):
+ 设定图片区宽度占比 = 65%-75%
+ 图片宽度 = W × 0.7 = 812 px
+ 图片高度 = 图片宽度 / R
+ 文字区宽度 = W - 图片宽度 - 间距(20px)
+
+验证:
+ 文字区宽度 >= 280px (至少能放标题 + 3-4 个要点)
+ 若不满足,需减小图片区宽度
+```
+
+---
+
+## 布局示例
+
+### 示例 1:超宽图 (比例 2.45)
+
+```
+原图: 1960 × 800 px
+比例: R = 2.45
+
+布局决策: 比例 > 2.0 → 上下分栏
+
+计算:
+ 图片宽度 = 1160 px
+ 图片高度 = 1160 / 2.45 = 473 px
+ 文字区高度 = 640 - 473 - 20 = 147 px ✓ (足够)
+
+结果:
+ 布局方案: 上下 7:3
+ 图片区域: 1160 × 473 px
+ 文字区域: 1160 × 147 px
+```
+
+### 示例 2:标准横图 (比例 1.38)
+
+```
+原图: 1614 × 1171 px
+比例: R = 1.38
+
+布局决策: 比例 1.2-1.5 → 左右分栏
+
+计算 (高度优先):
+ 图片高度 = 560 px (垂直居中)
+ 图片宽度 = 560 × 1.38 = 773 px
+ 文字区宽度 = 1160 - 773 - 20 = 367 px ✓
+
+结果:
+ 布局方案: 左右 7:3
+ 图片区域: 773 × 560 px (左侧)
+ 文字区域: 367 × 560 px (右侧)
+```
+
+### 示例 3:宽幅图 (比例 1.75) - 边界情况
+
+```
+原图: 1820 × 1040 px
+比例: R = 1.75
+
+尝试上下布局:
+ 图片高度 = 1160 / 1.75 = 663 px
+ 文字区高度 = 640 - 663 - 20 = -43 px ❌ (不可行!)
+
+改用左右布局:
+ 设图片宽度 = 780 px (约 67%)
+ 图片高度 = 780 / 1.75 = 446 px
+ 文字区宽度 = 1160 - 780 - 20 = 360 px ✓
+
+结果:
+ 布局方案: 左右 7:3
+ 图片区域: 780 × 446 px (左侧,垂直居中)
+ 文字区域: 360 × 600 px (右侧)
+```
+
+---
+
+## 禁止事项
+
+| ❌ 禁止 | ✅ 正确做法 |
+|--------|------------|
+| 固定使用 50:50 或任意比例 | 根据图片比例动态计算 |
+| 将宽图塞入方形容器 | 使用上下布局或加大图片区宽度 |
+| 将竖图放入横向窄条 | 使用左右布局,图片在左 |
+| 图片留白超过 10% | 重新计算布局或选择其他方案 |
+| 裁切图片关键内容 | 使用 `preserveAspectRatio="xMidYMid meet"` |
+| 文字区太小无法阅读 | 确保文字区 >= 150px (上下) 或 >= 280px (左右) |
+
+---
+
+## SVG 图片嵌入代码
+
+### 完整展示(推荐用于数据图表)
+
+```xml
+<image href="../images/xxx.png"
+ x="60" y="80" width="780" height="446"
+ preserveAspectRatio="xMidYMid meet"/>
+```
+
+### 裁切填充(仅用于背景图)
+
+```xml
+<image href="../images/bg.png"
+ x="0" y="0" width="1280" height="720"
+ preserveAspectRatio="xMidYMid slice"/>
+```
+
+---
+
+## 图片资源清单模板
+
+在《设计规范与内容大纲》中,图片资源清单**必须**包含以下字段:
+
+| 字段 | 说明 | 示例 |
+|------|------|------|
+| 文件名 | 图片文件名 | `p12_0.png` |
+| 原始尺寸 | 宽×高 | 1524×968 |
+| 比例 | 宽/高 | 1.57 |
+| 页码 | 使用页码 | 第5页 |
+| **布局方案** | 上下/左右 + 分栏比 | **上下 6:4** 或 **左右 7:3** |
+| **图片区域** | 图片展示尺寸 | 1160×420 或 780×446 |
+| **文字区域** | 剩余空间尺寸 | 1160×200 或 360×600 |
+
+---
+
+## 自动化工具支持
+
+### 获取图片尺寸信息
+
+```bash
+python3 tools/analyze_images.py <项目路径>/images
+```
+
+工具输出包含:尺寸、比例、布局建议(Markdown 表格),可直接用于填写图片资源清单。
+
+---
+
+## 角色职责
+
+| 角色 | 职责 |
+|------|------|
+| **Strategist** | 规划阶段:运行 analyze_images.py,按本规范计算布局,填写图片资源清单 |
+| **Executor** | 执行阶段:严格按图片资源清单中的布局方案和尺寸生成 SVG |
+
+---
+
+## 参考
+
+- [SVG 图片嵌入指南](./svg_image_embedding.md)
+- [画布格式规范](./canvas_formats.md)
diff --git a/roles/Strategist.md b/roles/Strategist.md
index 58af5952..d5bb6e98 100644
--- a/roles/Strategist.md
+++ b/roles/Strategist.md
@@ -105,6 +105,9 @@
2. **读取图片数据**:获取工具输出的图片尺寸、比例和布局建议(Markdown 表格形式)。
3. **整合进规范**:将扫描结果直接填入《设计规范》的「图片资源清单」章节。
4. **图片与布局适配原则(消灭无效留白)**:
+
+ > ⚠️ **强制执行**:详细计算规则请参考 [图片布局规范](../docs/image_layout_spec.md)
+
* **核心逻辑**:**布局容器的宽高比必须与图片原始比例相近**。不做“小脚穿大鞋”或“大脚穿小鞋”的匹配。
- 🚫 **避免**:将扁长的宽图塞进方形容器(导致上下留白);将竖长的图片塞进横向容器(导致左右留白)。
* **适配策略**: