feat: 实现幻灯片备注功能，将description写入PPT备注页
- 添加 PptxGenerator._set_notes() 方法设置备注 - 在 add_slide() 中调用 _set_notes() 处理 description - 仅幻灯片级别的 description 写入备注，不继承模板 - 添加备注功能测试用例（8个测试） - 更新 README.md 和 README_DEV.md 文档 - 新建 pptx-slide-notes spec - 更新 page-description spec 允许写入备注 - 归档 add-slide-notes 变更
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-03-04
|
||||
@@ -0,0 +1,75 @@
|
||||
## Context
|
||||
|
||||
当前系统中，`description` 字段已在以下位置被解析：
|
||||
- `core/presentation.py`: 演示文稿级别的 `metadata.description`
|
||||
- `core/template.py`: 模板级别的 `template.description`
|
||||
- `core/presentation.py`: 幻灯片级别的 `slide.description` 在 `render_slide` 方法返回值中
|
||||
|
||||
然而，PPTX 渲染器 (`renderers/pptx_renderer.py`) 的 `add_slide` 方法只处理 `background` 和 `elements`，完全忽略了 `description` 字段。
|
||||
|
||||
python-pptx 库原生支持备注功能，通过 `slide.notes_slide.notes_text_frame.text` 即可设置。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- 将幻灯片的 `description` 字段写入 PPT 备注页
|
||||
- 仅处理幻灯片级别的 description，不涉及模板或演示文稿级别的 description
|
||||
- 保持向后兼容，没有 description 时不设置备注
|
||||
|
||||
**Non-Goals:**
|
||||
- 不实现富文本备注（仅支持纯文本）
|
||||
- 不合并模板的 description
|
||||
- 不处理演示文稿级别的 metadata.description
|
||||
|
||||
## Decisions
|
||||
|
||||
### 1. 备注内容来源
|
||||
|
||||
**决策**: 仅使用幻灯片自己的 `description` 字段
|
||||
|
||||
**理由**:
|
||||
- 幻灯片 description 是用户针对具体页面编写的说明
|
||||
- 模板 description 描述的是模板用途，不适合作为单个幻灯片的备注
|
||||
- 避免复杂的合并逻辑，保持简单清晰
|
||||
|
||||
**考虑的替代方案**:
|
||||
- 合并模板 description 和幻灯片 description → 过于复杂，可能产生冗余内容
|
||||
- 仅在没有幻灯片 description 时使用模板 description → 增加认知负担
|
||||
|
||||
### 2. 无 description 时的行为
|
||||
|
||||
**决策**: 不设置备注，保持备注页为空
|
||||
|
||||
**理由**:
|
||||
- python-pptx 默认创建空备注页
|
||||
- 不需要额外判断或清理操作
|
||||
- 保持行为可预测
|
||||
|
||||
### 3. 代码位置
|
||||
|
||||
**决策**: 在 `PptxGenerator` 类中添加私有方法 `_set_notes`
|
||||
|
||||
**理由**:
|
||||
- 与现有的 `_render_background`、`_render_element` 等方法保持一致
|
||||
- 封装备注设置逻辑，便于测试和维护
|
||||
- 不影响 `add_slide` 方法的主流程
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
### Risk: 长文本可能导致备注溢出
|
||||
|
||||
**影响**: description 内容过长时，可能在备注页中显示不佳
|
||||
|
||||
**缓解**: python-pptx 会自动处理文本换行，这是库的默认行为，无需额外处理
|
||||
|
||||
### Trade-off: 仅支持纯文本
|
||||
|
||||
**限制**: python-pptx 的备注不支持富文本格式（加粗、颜色等）
|
||||
|
||||
**权衡**: 备注的主要用途是演讲者参考，纯文本已满足需求；富文本支持需要更复杂的实现，收益不大
|
||||
|
||||
### Risk: 现有 spec 需要更新
|
||||
|
||||
**影响**: `page-description` spec 明确规定 "description不写入PPTX文件"
|
||||
|
||||
**缓解**: 这正是本次变更的目的，需要更新该 spec 以反映新行为
|
||||
@@ -0,0 +1,25 @@
|
||||
## Why
|
||||
|
||||
幻灯片的 description 字段已经在系统中被解析和传递，但目前未被实际使用。PPT 备注页是演讲者的原生工具，非常适合存储这些演讲说明。通过将 description 写入 PPT 备注，可以让用户在演示时查看说明而不显示给观众，充分利用已有数据。
|
||||
|
||||
## What Changes
|
||||
|
||||
- 在 PPTX 生成时，将幻灯片的 `description` 字段写入备注页
|
||||
- 仅处理幻灯片级别的 `description`，不继承模板的 `description`
|
||||
- 如果幻灯片没有 `description`，则不设置备注
|
||||
- 修改现有 `page-description` spec 的需求，因为 description 现在会影响 PPTX 输出
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `pptx-slide-notes`: 幻灯片备注功能，支持将 description 内容写入 PPT 备注页
|
||||
|
||||
### Modified Capabilities
|
||||
- `page-description`: 现有 spec 规定 "description字段不得影响渲染逻辑" 和 "description不写入PPTX文件"，需要更新为允许 description 写入备注页
|
||||
|
||||
## Impact
|
||||
|
||||
- `renderers/pptx_renderer.py`: 在 `add_slide` 方法中添加设置备注的逻辑
|
||||
- `openspec/specs/page-description/spec.md`: 更新需求，移除 "不得影响渲染逻辑" 的限制
|
||||
- `openspec/specs/pptx-slide-notes/spec.md`: 新建 spec 定义备注功能需求
|
||||
- `README.md` 和 `README_DEV.md`: 更新文档说明备注功能
|
||||
@@ -0,0 +1,23 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: description字段不得影响渲染逻辑
|
||||
|
||||
系统 SHALL 在渲染幻灯片时忽略 `description` 字段对视觉元素的影响，但会将幻灯片级别的 `description` 写入 PPTX 备注页。
|
||||
|
||||
#### Scenario: 渲染包含description的模板
|
||||
|
||||
- **WHEN** 系统渲染包含 `description` 字段的模板
|
||||
- **THEN** description不参与元素渲染，不影响幻灯片视觉输出
|
||||
|
||||
#### Scenario: 渲染包含description的幻灯片
|
||||
|
||||
- **WHEN** 系统渲染包含 `description` 字段的幻灯片
|
||||
- **THEN** description写入PPTX文件的备注页，不影响幻灯片视觉输出
|
||||
|
||||
## REMOVED Requirements
|
||||
|
||||
### Requirement: description不写入PPTX文件
|
||||
|
||||
**Reason**: 幻灯片备注功能需要将 description 写入 PPTX 备注页，这是对 description 字段的合理利用。
|
||||
|
||||
**Migration**: 无需迁移，这是新增功能，不影响现有行为。没有 description 的幻灯片行为与之前完全一致。
|
||||
@@ -0,0 +1,52 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 幻灯片description必须写入PPT备注页
|
||||
|
||||
系统 SHALL 在生成 PPTX 时，将幻灯片的 `description` 字段内容写入该幻灯片的备注页。
|
||||
|
||||
#### Scenario: 幻灯片包含description
|
||||
|
||||
- **WHEN** 幻灯片定义了 `description: "这是幻灯片的演讲说明"`
|
||||
- **THEN** PPTX 幻灯片的备注页包含该文本内容
|
||||
|
||||
#### Scenario: description包含多行文本
|
||||
|
||||
- **WHEN** 幻灯片的 description 使用 YAML 多行文本格式定义
|
||||
- **THEN** 备注页保留完整的文本内容，包括换行符
|
||||
|
||||
#### Scenario: description为空字符串
|
||||
|
||||
- **WHEN** 幻灯片定义了 `description: ""`
|
||||
- **THEN** 备注页设置为空字符串（不为 None）
|
||||
|
||||
### Requirement: 无description时不设置备注
|
||||
|
||||
系统 SHALL 在幻灯片没有 `description` 字段时不设置备注内容。
|
||||
|
||||
#### Scenario: 幻灯片不包含description
|
||||
|
||||
- **WHEN** 幻灯片定义未包含 `description` 字段
|
||||
- **THEN** PPTX 幻灯片不设置备注，使用默认空备注页
|
||||
|
||||
### Requirement: 模板description不写入备注
|
||||
|
||||
系统 SHALL 仅处理幻灯片级别的 `description`，不使用模板的 `description`。
|
||||
|
||||
#### Scenario: 模板有description但幻灯片没有
|
||||
|
||||
- **WHEN** 模板定义了 `description: "模板说明"` 但幻灯片未定义 `description`
|
||||
- **THEN** PPTX 幻灯片不设置备注，不继承模板的 description
|
||||
|
||||
#### Scenario: 模板和幻灯片都有description
|
||||
|
||||
- **WHEN** 模板定义了 `description` 且幻灯片也定义了 `description`
|
||||
- **THEN** PPTX 幻灯片备注仅包含幻灯片的 description，忽略模板的 description
|
||||
|
||||
### Requirement: description必须支持中文字符
|
||||
|
||||
系统 SHALL 支持在 `description` 字段中使用中文字符，并正确写入 PPTX 备注。
|
||||
|
||||
#### Scenario: description包含中文
|
||||
|
||||
- **WHEN** 幻灯片的 description 包含中文字符，如 "这是演讲备注内容"
|
||||
- **THEN** 系统正确处理，PPTX 备注页显示正确的中文内容
|
||||
17
openspec/changes/archive/2026-03-04-add-slide-notes/tasks.md
Normal file
17
openspec/changes/archive/2026-03-04-add-slide-notes/tasks.md
Normal file
@@ -0,0 +1,17 @@
|
||||
## 1. 核心实现
|
||||
|
||||
- [x] 1.1 在 PptxGenerator 类中添加 _set_notes 私有方法
|
||||
- [x] 1.2 在 add_slide 方法中调用 _set_notes 设置备注
|
||||
|
||||
## 2. 测试
|
||||
|
||||
- [x] 2.1 添加幻灯片包含 description 的测试用例
|
||||
- [x] 2.2 添加幻灯片不包含 description 的测试用例
|
||||
- [x] 2.3 添加 description 包含多行文本的测试用例
|
||||
- [x] 2.4 添加 description 包含中文字符的测试用例
|
||||
- [x] 2.5 添加模板有 description 但幻灯片没有的测试用例
|
||||
|
||||
## 3. 文档更新
|
||||
|
||||
- [x] 3.1 更新 README.md 添加备注功能说明
|
||||
- [x] 3.2 更新 README_DEV.md 添加备注功能开发文档
|
||||
@@ -60,17 +60,17 @@ Page Description功能允许用户为文档元数据、模板和幻灯片添加
|
||||
|
||||
### Requirement: description字段不得影响渲染逻辑
|
||||
|
||||
系统 SHALL 在渲染过程中忽略 `description` 字段，不影响最终的PPTX输出。
|
||||
系统 SHALL 在渲染幻灯片时忽略 `description` 字段对视觉元素的影响，但会将幻灯片级别的 `description` 写入 PPTX 备注页。
|
||||
|
||||
#### Scenario: 渲染包含description的模板
|
||||
|
||||
- **WHEN** 系统渲染包含 `description` 字段的模板
|
||||
- **THEN** description不参与元素渲染，不影响输出结果
|
||||
- **THEN** description不参与元素渲染，不影响幻灯片视觉输出
|
||||
|
||||
#### Scenario: 渲染包含description的幻灯片
|
||||
|
||||
- **WHEN** 系统渲染包含 `description` 字段的幻灯片
|
||||
- **THEN** description不写入PPTX文件，不影响输出结果
|
||||
- **THEN** description写入PPTX文件的备注页，不影响幻灯片视觉输出
|
||||
|
||||
### Requirement: YAML解析器必须正确解析description字段
|
||||
|
||||
|
||||
58
openspec/specs/pptx-slide-notes/spec.md
Normal file
58
openspec/specs/pptx-slide-notes/spec.md
Normal file
@@ -0,0 +1,58 @@
|
||||
# PPTX Slide Notes
|
||||
|
||||
## Purpose
|
||||
|
||||
PPTX 备注功能允许用户在生成 PPTX 文件时，将幻灯片的 description 字段内容写入备注页。备注页是 PPT 的原生演讲者工具，在演示时可以查看但不显示给观众，非常适合存储演讲说明和备注信息。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 幻灯片description必须写入PPT备注页
|
||||
|
||||
系统 SHALL 在生成 PPTX 时，将幻灯片的 `description` 字段内容写入该幻灯片的备注页。
|
||||
|
||||
#### Scenario: 幻灯片包含description
|
||||
|
||||
- **WHEN** 幻灯片定义了 `description: "这是幻灯片的演讲说明"`
|
||||
- **THEN** PPTX 幻灯片的备注页包含该文本内容
|
||||
|
||||
#### Scenario: description包含多行文本
|
||||
|
||||
- **WHEN** 幻灯片的 description 使用 YAML 多行文本格式定义
|
||||
- **THEN** 备注页保留完整的文本内容，包括换行符
|
||||
|
||||
#### Scenario: description为空字符串
|
||||
|
||||
- **WHEN** 幻灯片定义了 `description: ""`
|
||||
- **THEN** 备注页设置为空字符串（不为 None）
|
||||
|
||||
### Requirement: 无description时不设置备注
|
||||
|
||||
系统 SHALL 在幻灯片没有 `description` 字段时不设置备注内容。
|
||||
|
||||
#### Scenario: 幻灯片不包含description
|
||||
|
||||
- **WHEN** 幻灯片定义未包含 `description` 字段
|
||||
- **THEN** PPTX 幻灯片不设置备注，使用默认空备注页
|
||||
|
||||
### Requirement: 模板description不写入备注
|
||||
|
||||
系统 SHALL 仅处理幻灯片级别的 `description`，不使用模板的 `description`。
|
||||
|
||||
#### Scenario: 模板有description但幻灯片没有
|
||||
|
||||
- **WHEN** 模板定义了 `description: "模板说明"` 但幻灯片未定义 `description`
|
||||
- **THEN** PPTX 幻灯片不设置备注，不继承模板的 description
|
||||
|
||||
#### Scenario: 模板和幻灯片都有description
|
||||
|
||||
- **WHEN** 模板定义了 `description` 且幻灯片也定义了 `description`
|
||||
- **THEN** PPTX 幻灯片备注仅包含幻灯片的 description，忽略模板的 description
|
||||
|
||||
### Requirement: description必须支持中文字符
|
||||
|
||||
系统 SHALL 支持在 `description` 字段中使用中文字符，并正确写入 PPTX 备注。
|
||||
|
||||
#### Scenario: description包含中文
|
||||
|
||||
- **WHEN** 幻灯片的 description 包含中文字符，如 "这是演讲备注内容"
|
||||
- **THEN** 系统正确处理，PPTX 备注页显示正确的中文内容
|
||||
Reference in New Issue
Block a user