feat: initial implementation of html2pptx with OpenSpec documentation
Add core Python script (yaml2pptx.py) for converting YAML to PowerPoint: - Element rendering: text, image, shape, table, chart - Template system with placeholders - PPTX generation with python-pptx OpenSpec workflow setup: - 3 archived changes: browser-preview, template-dir-cli, yaml-to-pptx - 7 main specifications covering all core modules - Config and documentation structure 30 files changed, 4984 insertions(+)
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-03-02
|
||||
@@ -0,0 +1,250 @@
|
||||
## Context
|
||||
|
||||
当前 `yaml2pptx.py` 是一个命令行工具，接收 YAML 文件作为输入，生成 PPTX 文件作为输出。脚本使用 uv 的 Inline script metadata 管理依赖（`python-pptx`、`pyyaml`），包含完整的 YAML 解析、模板渲染、元素渲染和 PPTX 生成逻辑。
|
||||
|
||||
现在需要在同一个脚本中添加预览模式，当用户使用 `--preview` 参数时，启动一个轻量级的 Web 服务器，提供浏览器实时预览功能。预览模式需要复用现有的 YAML 解析和模板渲染逻辑，但将输出目标从 PPTX 改为 HTML/CSS。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- 在 `yaml2pptx.py` 中添加预览模式，通过 `--preview` 参数启用
|
||||
- 使用轻量级的 Web 框架（Flask）提供 HTTP 服务
|
||||
- 使用 Server-Sent Events (SSE) 实现浏览器自动刷新
|
||||
- 使用 watchdog 监听 YAML 文件变化
|
||||
- 复用现有的 `Presentation` 类和 YAML 解析逻辑
|
||||
- 将 YAML 元素（文本、形状、表格、图片）渲染为 HTML/CSS
|
||||
- 保持向后兼容，不影响现有的 PPTX 生成功能
|
||||
|
||||
**Non-Goals:**
|
||||
- 不追求 100% 像素级精确的预览效果（HTML/CSS 与 PPTX 渲染存在差异是可接受的）
|
||||
- 不支持交互功能（如点击元素查看属性、拖拽调整位置等）
|
||||
- 不支持导出为静态 HTML 文件
|
||||
- 不支持多用户同时预览
|
||||
- 不支持 PPTX 动画和过渡效果的预览
|
||||
|
||||
## Decisions
|
||||
|
||||
### 决策 1: 集成到现有脚本 vs 独立脚本
|
||||
|
||||
**选择**: 集成到 `yaml2pptx.py` 中，通过 `--preview` 参数启用
|
||||
|
||||
**理由**:
|
||||
- 保持项目简洁，只有一个主脚本
|
||||
- 用户体验更统一，无需记忆多个命令
|
||||
- 更容易复用现有的解析逻辑和类定义
|
||||
- 减少代码重复和维护成本
|
||||
|
||||
**替代方案**: 创建独立的 `preview.py` 脚本
|
||||
- 优点：代码分离更清晰
|
||||
- 缺点：需要重复导入或复制代码，增加维护成本
|
||||
|
||||
### 决策 2: Web 框架选择
|
||||
|
||||
**选择**: Flask
|
||||
|
||||
**理由**:
|
||||
- 轻量级，适合本地开发工具
|
||||
- API 简单，易于实现
|
||||
- 社区成熟，文档丰富
|
||||
- 支持 Server-Sent Events
|
||||
|
||||
**替代方案**:
|
||||
- FastAPI: 更现代，但对于简单的预览服务来说过于复杂
|
||||
- Python 内置 http.server: 太简单，不支持动态路由和 SSE
|
||||
|
||||
### 决策 3: 实时刷新方案
|
||||
|
||||
**选择**: Server-Sent Events (SSE)
|
||||
|
||||
**理由**:
|
||||
- 单向推送，符合需求（服务器通知浏览器刷新）
|
||||
- 浏览器原生支持，无需额外的 JavaScript 库
|
||||
- 实现简单，约 10 行代码
|
||||
- 无需 WebSocket 的复杂握手和双向通信
|
||||
|
||||
**替代方案**:
|
||||
- WebSocket: 过于复杂，需要 Flask-SocketIO 依赖
|
||||
- 轮询: 延迟高，资源浪费
|
||||
- Meta refresh: 固定时间刷新，无法响应文件变化
|
||||
|
||||
### 决策 4: 文件监听方案
|
||||
|
||||
**选择**: watchdog
|
||||
|
||||
**理由**:
|
||||
- 跨平台，支持 macOS、Linux、Windows
|
||||
- 成熟稳定，广泛使用
|
||||
- API 简单，易于集成
|
||||
- 可以监听整个目录（包括模板文件变化）
|
||||
|
||||
**替代方案**:
|
||||
- 轮询文件修改时间: 延迟高，不够优雅
|
||||
- 操作系统原生 API: 不跨平台，实现复杂
|
||||
|
||||
### 决策 5: 单位转换策略
|
||||
|
||||
**选择**: 固定 DPI (96 DPI)，幻灯片固定尺寸 960x540 像素
|
||||
|
||||
**理由**:
|
||||
- 实现简单，无需复杂的缩放计算
|
||||
- 960x540 是合理的预览尺寸（16:9 比例）
|
||||
- 用户可以使用浏览器缩放功能（Cmd +/-）调整大小
|
||||
- 与 PPTX 的英寸单位转换清晰：1 英寸 = 96 像素
|
||||
|
||||
**替代方案**:
|
||||
- 自适应缩放: 更灵活，但实现复杂，需要处理百分比定位
|
||||
- CSS 英寸单位: 不同浏览器可能有差异
|
||||
|
||||
### 决策 6: HTML 渲染策略
|
||||
|
||||
**选择**: 使用 `<div>` + 内联样式渲染元素
|
||||
|
||||
**理由**:
|
||||
- 简单直接，易于实现
|
||||
- 使用绝对定位模拟 PPTX 的坐标系统
|
||||
- 内联样式避免 CSS 类管理的复杂性
|
||||
- 文本使用 `pt` 单位保持与 PPTX 一致
|
||||
|
||||
**元素映射**:
|
||||
- 文本元素: `<div>` + `font-size: Xpt`
|
||||
- 形状元素: `<div>` + `background-color` + `border-radius`
|
||||
- 表格元素: `<table>` 标签
|
||||
- 图片元素: `<img>` 标签
|
||||
|
||||
**替代方案**:
|
||||
- SVG 渲染: 更精确，但实现复杂
|
||||
- Canvas 渲染: 性能好，但无法选择文本，调试困难
|
||||
|
||||
### 决策 7: 代码组织
|
||||
|
||||
**选择**: 在 `yaml2pptx.py` 末尾添加预览相关代码，使用条件判断分离两种模式
|
||||
|
||||
**结构**:
|
||||
```python
|
||||
# 现有代码（PPTX 生成）
|
||||
class Presentation: ...
|
||||
class PptxGenerator: ...
|
||||
|
||||
# 新增代码（预览模式）
|
||||
# HTML 渲染函数
|
||||
def render_element_to_html(elem): ...
|
||||
|
||||
# Flask 应用
|
||||
app = Flask(__name__)
|
||||
@app.route('/'): ...
|
||||
@app.route('/events'): ...
|
||||
|
||||
# 主函数修改
|
||||
def main():
|
||||
if args.preview:
|
||||
# 启动预览服务器
|
||||
start_preview_server()
|
||||
else:
|
||||
# 生成 PPTX（现有逻辑）
|
||||
generate_pptx()
|
||||
```
|
||||
|
||||
**理由**:
|
||||
- 清晰分离两种模式的逻辑
|
||||
- 不影响现有代码的可读性
|
||||
- 易于维护和测试
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
### 风险 1: HTML/CSS 渲染与 PPTX 渲染存在差异
|
||||
|
||||
**风险**: 预览效果与最终 PPTX 可能不完全一致（字体渲染、间距、换行等）
|
||||
|
||||
**缓解措施**:
|
||||
- 在文档中明确说明预览仅供参考
|
||||
- 使用相同的单位系统（pt、英寸）尽量保持一致
|
||||
- 提供快速生成 PPTX 的方式进行最终确认
|
||||
|
||||
### 风险 2: 依赖增加
|
||||
|
||||
**风险**: 新增 `flask` 和 `watchdog` 依赖，增加脚本启动时间和依赖管理复杂度
|
||||
|
||||
**缓解措施**:
|
||||
- 使用 uv 的 Inline script metadata 自动管理依赖
|
||||
- 仅在预览模式下导入 Flask 和 watchdog（延迟导入）
|
||||
- 依赖都是轻量级库，影响较小
|
||||
|
||||
### 风险 3: 端口冲突
|
||||
|
||||
**风险**: 默认端口 5000 可能被其他服务占用
|
||||
|
||||
**缓解措施**:
|
||||
- 提供 `--port` 参数允许用户指定端口
|
||||
- 捕获端口占用错误，提示用户更换端口
|
||||
|
||||
### 风险 4: 文件监听性能
|
||||
|
||||
**风险**: 监听大型目录可能影响性能
|
||||
|
||||
**缓解措施**:
|
||||
- 仅监听 YAML 文件所在目录，不递归监听
|
||||
- 使用 watchdog 的高效事件机制
|
||||
- 添加防抖逻辑，避免短时间内多次刷新
|
||||
|
||||
### 权衡 1: 简单性 vs 功能完整性
|
||||
|
||||
**权衡**: 选择简单的实现方案，牺牲一些高级功能（如元素交互、网格线、标尺等）
|
||||
|
||||
**理由**: 预览功能的核心价值是快速反馈，简单实现可以更快交付，后续可根据需求迭代
|
||||
|
||||
### 权衡 2: 精确性 vs 速度
|
||||
|
||||
**权衡**: 使用 HTML/CSS 渲染而不是生成 PPTX 再转图片，牺牲精确性换取速度
|
||||
|
||||
**理由**: 实时预览的核心是速度，用户可以随时生成 PPTX 进行精确确认
|
||||
|
||||
## Migration Plan
|
||||
|
||||
### 部署步骤
|
||||
|
||||
1. 在 `yaml2pptx.py` 的 Inline script metadata 中添加依赖：
|
||||
```python
|
||||
# dependencies = [
|
||||
# "python-pptx",
|
||||
# "pyyaml",
|
||||
# "flask", # 新增
|
||||
# "watchdog", # 新增
|
||||
# ]
|
||||
```
|
||||
|
||||
2. 添加预览相关代码（约 200 行）
|
||||
|
||||
3. 修改 `parse_args()` 函数，添加 `--preview` 和 `--port` 参数
|
||||
|
||||
4. 修改 `main()` 函数，根据参数选择模式
|
||||
|
||||
5. 更新 README.md，添加预览功能的使用说明
|
||||
|
||||
### 回滚策略
|
||||
|
||||
- 如果预览功能有问题，用户仍可使用原有的 PPTX 生成功能（完全向后兼容）
|
||||
- 可以通过 git revert 回滚到之前的版本
|
||||
- 预览功能是可选的，不影响核心功能
|
||||
|
||||
### 测试计划
|
||||
|
||||
1. 单元测试：测试 HTML 渲染函数的正确性
|
||||
2. 集成测试：测试预览服务器的启动和文件监听
|
||||
3. 手动测试：在不同浏览器中测试预览效果
|
||||
4. 兼容性测试：确保不影响现有的 PPTX 生成功能
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. 是否需要支持多幻灯片的缩略图导航？
|
||||
- 当前方案：垂直排列显示所有幻灯片
|
||||
- 可选方案：添加左侧缩略图导航栏
|
||||
|
||||
2. 是否需要支持深色模式？
|
||||
- 当前方案：仅支持浅色背景
|
||||
- 可选方案：添加深色模式切换
|
||||
|
||||
3. 是否需要显示元素边框和尺寸标注？
|
||||
- 当前方案：不显示辅助信息
|
||||
- 可选方案：添加调试模式，显示元素边框和尺寸
|
||||
|
||||
这些问题可以在实现后根据用户反馈决定是否添加。
|
||||
@@ -0,0 +1,50 @@
|
||||
## Why
|
||||
|
||||
当前工作流程中，每次编辑 YAML 文件后，需要手动运行 `yaml2pptx.py` 生成 PPTX 文件，然后在 Keynote 或 PowerPoint 中打开查看效果。这个反馈循环较慢，需要频繁切换应用程序，降低了内容创作和调试的效率。添加浏览器实时预览功能可以让用户在编辑 YAML 时立即看到效果，大幅提升开发体验。
|
||||
|
||||
## What Changes
|
||||
|
||||
- 在 `yaml2pptx.py` 中添加 `--preview` 参数，启用浏览器预览模式
|
||||
- 使用 Flask 提供 Web 服务，动态生成 HTML 预览
|
||||
- 使用 Server-Sent Events (SSE) 实现浏览器自动刷新
|
||||
- 使用 watchdog 监听 YAML 文件变化
|
||||
- 复用现有的 YAML 解析和模板渲染逻辑
|
||||
- 将 YAML 元素转换为 HTML/CSS 进行渲染
|
||||
- 新增依赖：`flask`、`watchdog`（添加到脚本的 Inline script metadata）
|
||||
- 保持向后兼容，不影响现有的 PPTX 生成功能
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `browser-preview-server`: 浏览器预览服务器，负责启动 Web 服务、文件监听、SSE 事件推送
|
||||
- `html-rendering`: HTML 渲染系统，负责将 YAML 元素（文本、形状、表格、图片）转换为 HTML/CSS
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
无。此变更不修改现有能力的需求，仅复用 `yaml-parsing` 和 `template-system` 的功能。
|
||||
|
||||
## Impact
|
||||
|
||||
### 修改文件
|
||||
- `yaml2pptx.py`: 添加预览服务器功能（约 200 行新增代码）
|
||||
- 新增 `--preview` 命令行参数
|
||||
- 新增 Flask 路由和 SSE 事件流
|
||||
- 新增 HTML 渲染函数
|
||||
- 新增文件监听逻辑
|
||||
|
||||
### 依赖变化
|
||||
- 在 `yaml2pptx.py` 的 Inline script metadata 中新增依赖：`flask`、`watchdog`
|
||||
- 使用 uv 自动管理依赖，无需手动安装
|
||||
|
||||
### 现有功能
|
||||
- 完全向后兼容，不影响现有的 PPTX 生成功能
|
||||
- 复用 `Presentation` 类和 YAML 解析逻辑
|
||||
- 不修改现有的模板系统和元素渲染逻辑
|
||||
|
||||
### 用户体验
|
||||
- 生成 PPTX：`uv run yaml2pptx.py input.yaml` （保持不变）
|
||||
- 浏览器预览：`uv run yaml2pptx.py input.yaml --preview` （新增）
|
||||
- 预览模式下浏览器自动打开预览页面
|
||||
- 编辑 YAML 文件后浏览器自动刷新
|
||||
- 预览效果与最终 PPTX 可能存在细微差异（HTML/CSS vs PPTX 渲染）
|
||||
@@ -0,0 +1,186 @@
|
||||
# Browser Preview Server
|
||||
|
||||
## Purpose
|
||||
|
||||
Browser Preview Server 负责提供浏览器实时预览功能，包括启动 Web 服务、监听 YAML 文件变化、通过 Server-Sent Events (SSE) 推送更新通知到浏览器。它是预览模式的核心组件，协调文件监听、HTML 生成和浏览器刷新的整个流程。
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 系统必须支持通过命令行参数启用预览模式
|
||||
|
||||
系统 SHALL 在 `yaml2pptx.py` 中提供 `--preview` 参数，启用浏览器预览模式。
|
||||
|
||||
#### Scenario: 使用 --preview 参数启动预览服务器
|
||||
|
||||
- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml --preview`
|
||||
- **THEN** 系统启动预览服务器，而不是生成 PPTX 文件
|
||||
|
||||
#### Scenario: 不使用 --preview 参数时保持原有行为
|
||||
|
||||
- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml`
|
||||
- **THEN** 系统生成 PPTX 文件，不启动预览服务器
|
||||
|
||||
#### Scenario: --preview 参数与其他参数兼容
|
||||
|
||||
- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml --preview --template-dir templates`
|
||||
- **THEN** 系统启动预览服务器，并使用指定的模板目录
|
||||
|
||||
### Requirement: 系统必须提供 HTTP 服务
|
||||
|
||||
系统 SHALL 使用 Flask 启动 HTTP 服务器，监听指定端口，提供预览页面。
|
||||
|
||||
#### Scenario: 启动 HTTP 服务器
|
||||
|
||||
- **WHEN** 预览模式启动
|
||||
- **THEN** 系统在默认端口 5000 启动 Flask HTTP 服务器
|
||||
|
||||
#### Scenario: 自定义端口
|
||||
|
||||
- **WHEN** 用户使用 `--port 8080` 参数
|
||||
- **THEN** 系统在端口 8080 启动 HTTP 服务器
|
||||
|
||||
#### Scenario: 端口被占用时报错
|
||||
|
||||
- **WHEN** 指定的端口已被其他服务占用
|
||||
- **THEN** 系统抛出错误，提示端口被占用，建议使用 `--port` 参数指定其他端口
|
||||
|
||||
#### Scenario: 提供主页面路由
|
||||
|
||||
- **WHEN** 浏览器访问 `http://localhost:5000/`
|
||||
- **THEN** 系统返回包含所有幻灯片预览的 HTML 页面
|
||||
|
||||
### Requirement: 系统必须监听 YAML 文件变化
|
||||
|
||||
系统 SHALL 使用 watchdog 监听 YAML 文件所在目录，检测文件修改事件。
|
||||
|
||||
#### Scenario: 监听 YAML 文件修改
|
||||
|
||||
- **WHEN** 用户修改并保存 YAML 文件
|
||||
- **THEN** 系统检测到文件变化事件
|
||||
|
||||
#### Scenario: 监听模板文件修改
|
||||
|
||||
- **WHEN** 用户修改并保存模板文件（如 `templates/title_slide.yaml`）
|
||||
- **THEN** 系统检测到文件变化事件
|
||||
|
||||
#### Scenario: 忽略非 YAML 文件变化
|
||||
|
||||
- **WHEN** 用户修改其他类型的文件（如 `.txt`、`.md`）
|
||||
- **THEN** 系统不触发预览更新
|
||||
|
||||
#### Scenario: 防抖处理
|
||||
|
||||
- **WHEN** 用户在短时间内多次保存文件（如 1 秒内保存 3 次）
|
||||
- **THEN** 系统仅触发一次预览更新，避免频繁刷新
|
||||
|
||||
### Requirement: 系统必须通过 SSE 推送更新通知
|
||||
|
||||
系统 SHALL 提供 Server-Sent Events (SSE) 端点，当文件变化时推送更新通知到浏览器。
|
||||
|
||||
#### Scenario: 提供 SSE 端点
|
||||
|
||||
- **WHEN** 浏览器连接到 `http://localhost:5000/events`
|
||||
- **THEN** 系统建立 SSE 连接，保持连接打开
|
||||
|
||||
#### Scenario: 文件变化时推送更新
|
||||
|
||||
- **WHEN** 检测到 YAML 文件变化
|
||||
- **THEN** 系统通过 SSE 连接发送 `data: reload` 消息到所有连接的浏览器
|
||||
|
||||
#### Scenario: 浏览器接收更新后自动刷新
|
||||
|
||||
- **WHEN** 浏览器接收到 `reload` 消息
|
||||
- **THEN** 浏览器自动刷新页面，显示最新的预览内容
|
||||
|
||||
#### Scenario: SSE 连接断开时自动重连
|
||||
|
||||
- **WHEN** SSE 连接因网络问题断开
|
||||
- **THEN** 浏览器自动尝试重新连接到 SSE 端点
|
||||
|
||||
### Requirement: 系统必须自动打开浏览器
|
||||
|
||||
系统 SHALL 在预览服务器启动后，自动在默认浏览器中打开预览页面。
|
||||
|
||||
#### Scenario: 启动后自动打开浏览器
|
||||
|
||||
- **WHEN** 预览服务器启动成功
|
||||
- **THEN** 系统自动在默认浏览器中打开 `http://localhost:5000/`
|
||||
|
||||
#### Scenario: 浏览器打开失败时提示 URL
|
||||
|
||||
- **WHEN** 系统无法自动打开浏览器（如无图形界面环境）
|
||||
- **THEN** 系统在终端输出预览 URL，提示用户手动打开
|
||||
|
||||
### Requirement: 系统必须提供清晰的日志输出
|
||||
|
||||
系统 SHALL 在终端输出清晰的日志信息，帮助用户了解预览服务器的状态。
|
||||
|
||||
#### Scenario: 启动时输出日志
|
||||
|
||||
- **WHEN** 预览服务器启动
|
||||
- **THEN** 系统输出以下信息：
|
||||
- 正在监听的 YAML 文件路径
|
||||
- 预览服务器的 URL
|
||||
- 停止服务器的方法（按 Ctrl+C）
|
||||
|
||||
#### Scenario: 文件变化时输出日志
|
||||
|
||||
- **WHEN** 检测到文件变化
|
||||
- **THEN** 系统输出 `[INFO] 检测到文件变化: <文件路径>`
|
||||
|
||||
#### Scenario: 错误时输出日志
|
||||
|
||||
- **WHEN** 发生错误（如 YAML 解析错误）
|
||||
- **THEN** 系统输出 `[ERROR]` 级别的日志，包含错误详情
|
||||
|
||||
### Requirement: 系统必须支持优雅退出
|
||||
|
||||
系统 SHALL 支持通过 Ctrl+C 优雅地停止预览服务器。
|
||||
|
||||
#### Scenario: 按 Ctrl+C 停止服务器
|
||||
|
||||
- **WHEN** 用户按下 Ctrl+C
|
||||
- **THEN** 系统停止文件监听和 HTTP 服务器，输出 `[INFO] 已停止`，然后退出
|
||||
|
||||
#### Scenario: 停止时清理资源
|
||||
|
||||
- **WHEN** 服务器停止
|
||||
- **THEN** 系统关闭所有 SSE 连接，停止 watchdog 监听器，释放端口
|
||||
|
||||
### Requirement: 系统必须处理 YAML 解析错误
|
||||
|
||||
系统 SHALL 在 YAML 解析失败时，在预览页面显示友好的错误信息，而不是崩溃。
|
||||
|
||||
#### Scenario: YAML 语法错误时显示错误页面
|
||||
|
||||
- **WHEN** YAML 文件存在语法错误（如缺少冒号、缩进错误）
|
||||
- **THEN** 系统在预览页面显示错误信息，包括错误类型和行号
|
||||
|
||||
#### Scenario: 错误修复后自动恢复
|
||||
|
||||
- **WHEN** 用户修复 YAML 错误并保存
|
||||
- **THEN** 系统检测到文件变化，重新解析 YAML，显示正常的预览内容
|
||||
|
||||
#### Scenario: 错误页面仍然监听文件变化
|
||||
|
||||
- **WHEN** 预览页面显示错误信息
|
||||
- **THEN** 系统继续监听文件变化，等待用户修复错误
|
||||
|
||||
### Requirement: 系统必须支持多幻灯片预览
|
||||
|
||||
系统 SHALL 在预览页面中显示所有幻灯片，支持用户查看完整的演示文稿。
|
||||
|
||||
#### Scenario: 垂直排列显示所有幻灯片
|
||||
|
||||
- **WHEN** YAML 文件包含多个幻灯片
|
||||
- **THEN** 系统在预览页面中垂直排列显示所有幻灯片，每个幻灯片之间有间距
|
||||
|
||||
#### Scenario: 显示幻灯片编号
|
||||
|
||||
- **WHEN** 预览页面显示幻灯片
|
||||
- **THEN** 每个幻灯片右下角显示编号（如 "幻灯片 1"、"幻灯片 2"）
|
||||
|
||||
#### Scenario: 幻灯片尺寸一致
|
||||
|
||||
- **WHEN** 预览页面显示多个幻灯片
|
||||
- **THEN** 所有幻灯片使用相同的尺寸（960x540 像素，16:9 比例）
|
||||
@@ -0,0 +1,236 @@
|
||||
# HTML Rendering
|
||||
|
||||
## Purpose
|
||||
|
||||
HTML Rendering 系统负责将 YAML 中定义的各类元素（文本、图片、形状、表格）转换为 HTML/CSS 代码，在浏览器中显示。它复用现有的 YAML 解析和模板渲染逻辑，但将输出目标从 PPTX 改为 HTML/CSS，提供快速的预览体验。
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 系统必须将 YAML 元素转换为 HTML
|
||||
|
||||
系统 SHALL 将解析后的 YAML 元素转换为 HTML 代码，在浏览器中渲染。
|
||||
|
||||
#### Scenario: 生成完整的 HTML 页面
|
||||
|
||||
- **WHEN** 浏览器请求预览页面
|
||||
- **THEN** 系统生成包含 HTML、CSS 和 JavaScript 的完整页面
|
||||
|
||||
#### Scenario: 动态生成 HTML
|
||||
|
||||
- **WHEN** YAML 文件变化
|
||||
- **THEN** 系统重新解析 YAML，动态生成新的 HTML 内容，无需生成中间文件
|
||||
|
||||
#### Scenario: HTML 页面包含 SSE 客户端代码
|
||||
|
||||
- **WHEN** 生成 HTML 页面
|
||||
- **THEN** 页面包含 JavaScript 代码，连接到 SSE 端点，监听更新事件
|
||||
|
||||
### Requirement: 系统必须使用固定 DPI 进行单位转换
|
||||
|
||||
系统 SHALL 使用固定 DPI (96) 将 YAML 中的英寸单位转换为 CSS 像素单位。
|
||||
|
||||
#### Scenario: 英寸转换为像素
|
||||
|
||||
- **WHEN** 元素定义 `box: [1, 2, 8, 3]`（单位为英寸）
|
||||
- **THEN** 系统转换为 CSS：`left: 96px; top: 192px; width: 768px; height: 288px`
|
||||
|
||||
#### Scenario: 幻灯片尺寸固定
|
||||
|
||||
- **WHEN** 渲染 16:9 幻灯片
|
||||
- **THEN** 系统使用固定尺寸 960x540 像素（10 英寸 x 5.625 英寸 x 96 DPI）
|
||||
|
||||
#### Scenario: 4:3 幻灯片尺寸
|
||||
|
||||
- **WHEN** 渲染 4:3 幻灯片
|
||||
- **THEN** 系统使用固定尺寸 960x720 像素（10 英寸 x 7.5 英寸 x 96 DPI）
|
||||
|
||||
### Requirement: 系统必须渲染文本元素
|
||||
|
||||
系统 SHALL 将 YAML 中的文本元素转换为 HTML `<div>` 标签，应用相应的样式。
|
||||
|
||||
#### Scenario: 渲染基本文本元素
|
||||
|
||||
- **WHEN** 元素定义为 `{type: text, content: "Hello", box: [1, 2, 8, 3]}`
|
||||
- **THEN** 系统生成 `<div>` 标签，内容为 "Hello"，位置为 (96px, 192px)，尺寸为 768x288 像素
|
||||
|
||||
#### Scenario: 应用文本字体样式
|
||||
|
||||
- **WHEN** 文本元素定义了 `font: {size: 32, bold: true, color: "#333333"}`
|
||||
- **THEN** 系统应用 CSS：`font-size: 32pt; font-weight: bold; color: #333333`
|
||||
|
||||
#### Scenario: 应用文本对齐方式
|
||||
|
||||
- **WHEN** 文本元素定义了 `font: {align: center}`
|
||||
- **THEN** 系统应用 CSS：`text-align: center`
|
||||
|
||||
#### Scenario: 支持多行文本
|
||||
|
||||
- **WHEN** 文本内容包含换行符（`\n`）
|
||||
- **THEN** 系统使用 `white-space: pre-wrap` 保留换行
|
||||
|
||||
#### Scenario: 使用 pt 单位表示字体大小
|
||||
|
||||
- **WHEN** 文本字体大小为 44
|
||||
- **THEN** 系统使用 CSS：`font-size: 44pt`（与 PPTX 保持一致）
|
||||
|
||||
### Requirement: 系统必须渲染形状元素
|
||||
|
||||
系统 SHALL 将 YAML 中的形状元素转换为 HTML `<div>` 标签，使用 CSS 样式模拟形状。
|
||||
|
||||
#### Scenario: 渲染矩形形状
|
||||
|
||||
- **WHEN** 元素定义为 `{type: shape, shape: rectangle, box: [1, 2, 3, 1], fill: "#4a90e2"}`
|
||||
- **THEN** 系统生成 `<div>` 标签，背景色为 #4a90e2，`border-radius: 0`
|
||||
|
||||
#### Scenario: 渲染圆形形状
|
||||
|
||||
- **WHEN** 元素的 `shape` 字段为 `ellipse`
|
||||
- **THEN** 系统应用 CSS：`border-radius: 50%`
|
||||
|
||||
#### Scenario: 渲染圆角矩形
|
||||
|
||||
- **WHEN** 元素的 `shape` 字段为 `rounded_rectangle`
|
||||
- **THEN** 系统应用 CSS：`border-radius: 8px`
|
||||
|
||||
#### Scenario: 应用形状边框样式
|
||||
|
||||
- **WHEN** 形状定义了 `line: {color: "#000000", width: 2}`
|
||||
- **THEN** 系统应用 CSS：`border: 2pt solid #000000`
|
||||
|
||||
#### Scenario: 形状无填充色时透明
|
||||
|
||||
- **WHEN** 形状未定义 `fill` 字段
|
||||
- **THEN** 系统应用 CSS：`background: transparent`
|
||||
|
||||
### Requirement: 系统必须渲染表格元素
|
||||
|
||||
系统 SHALL 将 YAML 中的表格元素转换为 HTML `<table>` 标签。
|
||||
|
||||
#### Scenario: 渲染基本表格
|
||||
|
||||
- **WHEN** 元素定义为 `{type: table, position: [1, 2], data: [["A", "B"], ["C", "D"]], col_widths: [2, 2]}`
|
||||
- **THEN** 系统生成 `<table>` 标签，位置为 (96px, 192px)，包含 2 行 2 列
|
||||
|
||||
#### Scenario: 应用表格样式
|
||||
|
||||
- **WHEN** 表格定义了 `style: {font_size: 14, header_bg: "#4a90e2", header_color: "#ffffff"}`
|
||||
- **THEN** 系统将第一行设置为表头样式，背景色为 #4a90e2，文字颜色为白色，字体大小为 14pt
|
||||
|
||||
#### Scenario: 表格单元格边框
|
||||
|
||||
- **WHEN** 渲染表格
|
||||
- **THEN** 系统为所有单元格添加边框：`border: 1px solid #ddd`
|
||||
|
||||
#### Scenario: 表格单元格内边距
|
||||
|
||||
- **WHEN** 渲染表格
|
||||
- **THEN** 系统为所有单元格添加内边距：`padding: 8px`
|
||||
|
||||
### Requirement: 系统必须渲染图片元素
|
||||
|
||||
系统 SHALL 将 YAML 中的图片元素转换为 HTML `<img>` 标签。
|
||||
|
||||
#### Scenario: 渲染本地图片
|
||||
|
||||
- **WHEN** 元素定义为 `{type: image, src: "images/logo.png", box: [2, 3, 4, 3]}`
|
||||
- **THEN** 系统生成 `<img>` 标签，src 为图片的文件路径，位置为 (192px, 288px)，尺寸为 384x288 像素
|
||||
|
||||
#### Scenario: 处理相对路径
|
||||
|
||||
- **WHEN** 图片 src 使用相对路径 `"assets/logo.png"`
|
||||
- **THEN** 系统基于 YAML 文件所在目录解析相对路径
|
||||
|
||||
#### Scenario: 图片不存在时显示占位符
|
||||
|
||||
- **WHEN** 图片文件不存在
|
||||
- **THEN** 系统显示占位符或错误提示，而不是崩溃
|
||||
|
||||
### Requirement: 系统必须渲染幻灯片背景
|
||||
|
||||
系统 SHALL 支持为幻灯片设置纯色背景。
|
||||
|
||||
#### Scenario: 设置纯色背景
|
||||
|
||||
- **WHEN** 幻灯片定义了 `background: {color: "#ffffff"}`
|
||||
- **THEN** 系统为幻灯片容器应用 CSS：`background: #ffffff`
|
||||
|
||||
#### Scenario: 无背景时使用白色
|
||||
|
||||
- **WHEN** 幻灯片未定义 `background` 字段
|
||||
- **THEN** 系统使用默认白色背景
|
||||
|
||||
### Requirement: 系统必须使用绝对定位
|
||||
|
||||
系统 SHALL 使用 CSS 绝对定位（`position: absolute`）渲染所有元素，模拟 PPTX 的坐标系统。
|
||||
|
||||
#### Scenario: 元素使用绝对定位
|
||||
|
||||
- **WHEN** 渲染任何元素
|
||||
- **THEN** 系统应用 CSS：`position: absolute`
|
||||
|
||||
#### Scenario: 幻灯片容器使用相对定位
|
||||
|
||||
- **WHEN** 渲染幻灯片容器
|
||||
- **THEN** 系统应用 CSS：`position: relative`，作为元素的定位上下文
|
||||
|
||||
#### Scenario: 元素层次按定义顺序
|
||||
|
||||
- **WHEN** elements 列表为 `[shape1, text1, image1]`
|
||||
- **THEN** 系统按顺序渲染，后定义的元素显示在前面元素之上（通过 DOM 顺序控制）
|
||||
|
||||
### Requirement: 系统必须提供视觉反馈
|
||||
|
||||
系统 SHALL 在预览页面中提供视觉反馈，帮助用户了解预览状态。
|
||||
|
||||
#### Scenario: 显示实时预览状态指示器
|
||||
|
||||
- **WHEN** 预览页面加载
|
||||
- **THEN** 页面右上角显示绿色的 "● 实时预览" 状态指示器
|
||||
|
||||
#### Scenario: 幻灯片添加阴影效果
|
||||
|
||||
- **WHEN** 渲染幻灯片
|
||||
- **THEN** 系统为幻灯片容器添加阴影：`box-shadow: 0 2px 8px rgba(0,0,0,0.1)`
|
||||
|
||||
#### Scenario: 幻灯片之间有间距
|
||||
|
||||
- **WHEN** 渲染多个幻灯片
|
||||
- **THEN** 每个幻灯片之间有 20px 的垂直间距
|
||||
|
||||
### Requirement: 系统必须复用现有的解析逻辑
|
||||
|
||||
系统 SHALL 复用 `yaml2pptx.py` 中现有的 `Presentation` 类和模板渲染逻辑。
|
||||
|
||||
#### Scenario: 使用 Presentation 类解析 YAML
|
||||
|
||||
- **WHEN** 预览模式启动
|
||||
- **THEN** 系统使用 `Presentation` 类加载和解析 YAML 文件
|
||||
|
||||
#### Scenario: 使用 render_slide 方法渲染幻灯片
|
||||
|
||||
- **WHEN** 生成预览 HTML
|
||||
- **THEN** 系统调用 `Presentation.render_slide()` 方法获取渲染后的幻灯片数据
|
||||
|
||||
#### Scenario: 支持模板系统
|
||||
|
||||
- **WHEN** YAML 文件使用模板（如 `template: title_slide`）
|
||||
- **THEN** 系统正确解析模板变量，渲染模板元素
|
||||
|
||||
### Requirement: 系统必须处理渲染错误
|
||||
|
||||
系统 SHALL 在元素渲染失败时，显示错误信息，而不是崩溃。
|
||||
|
||||
#### Scenario: 元素类型不支持时显示错误
|
||||
|
||||
- **WHEN** 元素的 `type` 为未定义的值（如 "video"）
|
||||
- **THEN** 系统在预览页面显示错误信息，提示不支持该元素类型
|
||||
|
||||
#### Scenario: 元素缺少必需字段时显示错误
|
||||
|
||||
- **WHEN** 元素缺少必需字段（如文本元素缺少 `content`）
|
||||
- **THEN** 系统在预览页面显示错误信息，提示缺少字段
|
||||
|
||||
#### Scenario: 部分元素错误不影响其他元素
|
||||
|
||||
- **WHEN** 某个元素渲染失败
|
||||
- **THEN** 系统继续渲染其他元素，仅在失败位置显示错误提示
|
||||
@@ -0,0 +1,79 @@
|
||||
## 1. 准备工作
|
||||
|
||||
- [x] 1.1 在 `yaml2pptx.py` 的 Inline script metadata 中添加 `flask` 和 `watchdog` 依赖
|
||||
- [x] 1.2 在文件顶部添加预览模式相关的导入语句（使用条件导入，仅在预览模式下导入）
|
||||
|
||||
## 2. 命令行参数
|
||||
|
||||
- [x] 2.1 在 `parse_args()` 函数中添加 `--preview` 参数（布尔类型，默认 False）
|
||||
- [x] 2.2 在 `parse_args()` 函数中添加 `--port` 参数（整数类型，默认 5000）
|
||||
|
||||
## 3. HTML 渲染函数
|
||||
|
||||
- [x] 3.1 实现 `render_text_element_to_html(elem)` 函数，将文本元素转换为 HTML `<div>` 标签
|
||||
- [x] 3.2 实现 `render_shape_element_to_html(elem)` 函数，将形状元素转换为 HTML `<div>` 标签
|
||||
- [x] 3.3 实现 `render_table_element_to_html(elem)` 函数，将表格元素转换为 HTML `<table>` 标签
|
||||
- [x] 3.4 实现 `render_image_element_to_html(elem, base_path)` 函数，将图片元素转换为 HTML `<img>` 标签
|
||||
- [x] 3.5 实现 `render_slide_to_html(slide_data, index)` 函数，渲染单个幻灯片为 HTML
|
||||
- [x] 3.6 实现 `generate_preview_html(yaml_file, template_dir)` 函数，生成完整的预览 HTML 页面
|
||||
|
||||
## 4. HTML 模板
|
||||
|
||||
- [x] 4.1 定义 `HTML_TEMPLATE` 常量，包含完整的 HTML 页面结构、CSS 样式和 SSE 客户端 JavaScript
|
||||
- [x] 4.2 定义 `ERROR_TEMPLATE` 常量，用于显示 YAML 解析错误
|
||||
|
||||
## 5. Flask 应用
|
||||
|
||||
- [x] 5.1 创建 Flask 应用实例 `app = Flask(__name__)`
|
||||
- [x] 5.2 实现主页面路由 `@app.route('/')`，返回预览 HTML
|
||||
- [x] 5.3 实现 SSE 事件流路由 `@app.route('/events')`，推送文件变化通知
|
||||
|
||||
## 6. 文件监听
|
||||
|
||||
- [x] 6.1 实现 `YAMLChangeHandler` 类，继承 `FileSystemEventHandler`
|
||||
- [x] 6.2 在 `on_modified()` 方法中检测 `.yaml` 文件变化，推送更新通知到队列
|
||||
- [x] 6.3 创建全局队列 `change_queue = queue.Queue()` 用于通知文件变化
|
||||
|
||||
## 7. 预览服务器启动
|
||||
|
||||
- [x] 7.1 实现 `start_preview_server(yaml_file, template_dir, port)` 函数
|
||||
- [x] 7.2 在函数中启动 watchdog 监听器，监听 YAML 文件所在目录
|
||||
- [x] 7.3 在函数中使用 `webbrowser.open()` 自动打开浏览器
|
||||
- [x] 7.4 在函数中启动 Flask 应用，监听指定端口
|
||||
- [x] 7.5 添加 Ctrl+C 信号处理，优雅退出服务器
|
||||
|
||||
## 8. 主函数修改
|
||||
|
||||
- [x] 8.1 在 `main()` 函数中添加条件判断：`if args.preview:`
|
||||
- [x] 8.2 在预览模式分支中调用 `start_preview_server()`
|
||||
- [x] 8.3 在非预览模式分支中保持原有的 PPTX 生成逻辑
|
||||
|
||||
## 9. 错误处理
|
||||
|
||||
- [x] 9.1 在预览 HTML 生成中捕获 `YAMLError`，返回错误页面
|
||||
- [x] 9.2 在 Flask 路由中添加异常处理，避免服务器崩溃
|
||||
- [x] 9.3 在端口占用时捕获异常，提示用户使用 `--port` 参数
|
||||
|
||||
## 10. 日志输出
|
||||
|
||||
- [x] 10.1 在预览服务器启动时输出日志：监听的文件路径、预览 URL、停止方法
|
||||
- [x] 10.2 在文件变化时输出日志：`[INFO] 检测到文件变化: <文件路径>`
|
||||
- [x] 10.3 在服务器停止时输出日志：`[INFO] 已停止`
|
||||
|
||||
## 11. 测试
|
||||
|
||||
- [x] 11.1 测试基本功能：启动预览服务器，浏览器自动打开
|
||||
- [x] 11.2 测试文件监听：修改 YAML 文件，浏览器自动刷新
|
||||
- [x] 11.3 测试模板支持：使用模板的 YAML 文件能正确预览
|
||||
- [x] 11.4 测试错误处理：YAML 语法错误时显示错误页面
|
||||
- [x] 11.5 测试所有元素类型：文本、形状、表格、图片都能正确渲染
|
||||
- [x] 11.6 测试多幻灯片：多个幻灯片垂直排列显示
|
||||
- [x] 11.7 测试向后兼容：不使用 `--preview` 参数时，PPTX 生成功能正常
|
||||
- [x] 11.8 测试自定义端口：`--port` 参数能正确指定端口
|
||||
- [x] 11.9 测试 Ctrl+C 退出：能优雅停止服务器
|
||||
|
||||
## 12. 文档更新
|
||||
|
||||
- [x] 12.1 在 README.md 中添加预览功能的使用说明
|
||||
- [x] 12.2 在 README.md 中添加预览功能的示例命令
|
||||
- [x] 12.3 在 README.md 中说明预览效果与 PPTX 可能存在差异
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-03-02
|
||||
@@ -0,0 +1,201 @@
|
||||
## Context
|
||||
|
||||
当前 `yaml2pptx.py` 脚本的模板系统使用硬编码的相对路径 `templates_dir='templates'` 作为默认值。这导致脚本只能在包含 templates 目录的特定位置运行，限制了可移植性。
|
||||
|
||||
**当前实现**（184-196行）：
|
||||
```python
|
||||
def __init__(self, template_file, templates_dir='templates'):
|
||||
template_path = Path(template_file)
|
||||
if not template_path.is_absolute() and not template_path.exists():
|
||||
template_path = Path(templates_dir) / f"{template_file}.yaml"
|
||||
```
|
||||
|
||||
**问题**：
|
||||
1. 默认值 `'templates'` 是相对于当前工作目录（CWD），不够明确
|
||||
2. 先检查当前目录是否存在同名文件，可能导致意外行为
|
||||
3. 没有验证模板名称，允许路径遍历（如 `../other/template`）
|
||||
4. 错误提示不够清晰
|
||||
|
||||
**约束**：
|
||||
- 脚本使用 Python 3.8+，通过 uv 运行
|
||||
- 必须支持 Mac 和 Windows 平台
|
||||
- 使用 pathlib.Path 处理路径（已在代码中使用）
|
||||
- 保持向后兼容：不使用模板的用户不受影响
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- 支持通过 `--template-dir` 参数明确指定模板目录
|
||||
- 移除隐式默认行为，使用模板时必须明确指定目录
|
||||
- 添加模板名称验证，防止路径遍历
|
||||
- 提供清晰的错误提示，告知用户查找位置和失败原因
|
||||
- 确保跨平台兼容性（Mac 和 Windows）
|
||||
|
||||
**Non-Goals:**
|
||||
- 不支持多个模板目录搜索路径
|
||||
- 不支持模板目录的嵌套子目录
|
||||
- 不改变模板文件格式或渲染逻辑
|
||||
- 不影响不使用模板的纯自定义幻灯片
|
||||
|
||||
## Decisions
|
||||
|
||||
### 决策 1: 移除默认 templates_dir，要求明确指定
|
||||
|
||||
**选择**: `templates_dir=None`，使用模板时必须通过 `--template-dir` 指定
|
||||
|
||||
**理由**:
|
||||
- **明确性**: 避免"默认在哪里找"的困惑
|
||||
- **可移植性**: 脚本可以在任何位置运行
|
||||
- **统一性**: 所有模板都从同一个明确的位置加载
|
||||
|
||||
**替代方案**:
|
||||
- 方案 A: 默认为源 YAML 文件目录下的 templates/
|
||||
- ✗ 仍然是隐式行为，不够明确
|
||||
- ✗ 如果 YAML 文件和模板不在同一位置，仍然会失败
|
||||
- 方案 B: 支持多个搜索路径（如 `--template-dir dir1:dir2`）
|
||||
- ✗ 增加复杂度，违背"简单统一"的设计原则
|
||||
- ✗ 可能导致模板命名冲突
|
||||
|
||||
### 决策 2: 使用 pathlib.Path 处理所有路径操作
|
||||
|
||||
**选择**: 统一使用 `pathlib.Path` 进行路径拼接、验证和存在性检查
|
||||
|
||||
**理由**:
|
||||
- **跨平台**: Path 自动处理 Mac（`/`）和 Windows（`\`）的路径分隔符
|
||||
- **安全性**: Path 对象避免了字符串拼接的错误
|
||||
- **一致性**: 代码中已经在使用 Path
|
||||
|
||||
**实现**:
|
||||
```python
|
||||
# 路径拼接（跨平台）
|
||||
template_path = Path(templates_dir) / f"{template_file}.yaml"
|
||||
|
||||
# 存在性检查
|
||||
if not template_path.exists():
|
||||
raise YAMLError(...)
|
||||
```
|
||||
|
||||
### 决策 3: 模板名称验证 - 禁止路径分隔符
|
||||
|
||||
**选择**: 检查模板名称中是否包含 `/` 或 `\`，如果包含则报错
|
||||
|
||||
**理由**:
|
||||
- **安全性**: 防止路径遍历攻击（如 `../../etc/passwd`）
|
||||
- **简单性**: 只支持一层目录，逻辑清晰
|
||||
- **跨平台**: 同时检查两种路径分隔符
|
||||
|
||||
**实现**:
|
||||
```python
|
||||
if '/' in template_file or '\\' in template_file:
|
||||
raise YAMLError(
|
||||
f"模板名称不能包含路径分隔符: {template_file}\n"
|
||||
f"模板名称应该是纯文件名，如: 'title-slide'"
|
||||
)
|
||||
```
|
||||
|
||||
**替代方案**:
|
||||
- 方案 A: 使用 `os.path.sep` 只检查当前平台的分隔符
|
||||
- ✗ 在 Windows 上创建的 YAML 文件可能包含 `/`，在 Mac 上会被忽略
|
||||
- ✗ 不够严格，可能导致跨平台问题
|
||||
- 方案 B: 使用正则表达式验证文件名格式
|
||||
- ✗ 过度设计，简单的字符串检查已足够
|
||||
|
||||
### 决策 4: 改进错误提示 - 三层信息
|
||||
|
||||
**选择**: 错误信息包含三层：问题描述、查找位置、解决建议
|
||||
|
||||
**理由**:
|
||||
- **可调试性**: 用户能快速定位问题
|
||||
- **可操作性**: 提供明确的解决方案
|
||||
|
||||
**实现**:
|
||||
```python
|
||||
# 未指定 template_dir
|
||||
raise YAMLError(
|
||||
f"未指定模板目录，无法加载模板: {template_file}\n"
|
||||
f"请使用 --template-dir 参数指定模板目录"
|
||||
)
|
||||
|
||||
# 模板文件不存在
|
||||
raise YAMLError(
|
||||
f"模板文件不存在: {template_file}\n"
|
||||
f"查找位置: {templates_dir}\n"
|
||||
f"期望文件: {template_path}\n"
|
||||
f"提示: 请检查模板名称和模板目录是否正确"
|
||||
)
|
||||
```
|
||||
|
||||
### 决策 5: 参数传递链 - 从 CLI 到 Template
|
||||
|
||||
**选择**: `main() → Presentation() → Template()`
|
||||
|
||||
**理由**:
|
||||
- **清晰性**: 参数传递路径明确
|
||||
- **最小改动**: 只需修改参数默认值和传递方式
|
||||
|
||||
**实现**:
|
||||
```python
|
||||
# parse_args: 添加参数
|
||||
parser.add_argument('--template-dir', type=str, default=None)
|
||||
|
||||
# main: 传递给 Presentation
|
||||
pres = Presentation(input_path, templates_dir=args.template_dir)
|
||||
|
||||
# Presentation.__init__: 传递给 Template
|
||||
def __init__(self, pres_file, templates_dir=None):
|
||||
self.templates_dir = templates_dir
|
||||
|
||||
# Template.__init__: 使用参数
|
||||
def __init__(self, template_file, templates_dir=None):
|
||||
if templates_dir is None:
|
||||
raise YAMLError(...)
|
||||
```
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
### 风险 1: 破坏性变更影响现有用户
|
||||
|
||||
**风险**: 现有使用模板的用户升级后脚本会报错
|
||||
|
||||
**缓解**:
|
||||
- 提供清晰的错误信息，告知用户需要添加 `--template-dir` 参数
|
||||
- 在文档中明确标注为破坏性变更
|
||||
- 错误信息中包含使用示例
|
||||
|
||||
### 风险 2: 相对路径的解析基准
|
||||
|
||||
**风险**: 用户可能不清楚相对路径是相对于哪里
|
||||
|
||||
**决策**: 相对路径相对于当前工作目录（CWD），这是命令行工具的标准行为
|
||||
|
||||
**缓解**:
|
||||
- 在帮助信息中说明
|
||||
- 错误信息中显示完整的绝对路径
|
||||
|
||||
### 风险 3: Windows 路径中的反斜杠
|
||||
|
||||
**风险**: Windows 用户可能在命令行中输入 `C:\templates`，shell 可能需要转义
|
||||
|
||||
**缓解**:
|
||||
- Python 的 argparse 会正确处理
|
||||
- 用户可以使用正斜杠 `C:/templates`（Windows 支持）
|
||||
- 在文档中提供 Windows 示例
|
||||
|
||||
### 权衡 1: 灵活性 vs 简单性
|
||||
|
||||
**权衡**: 不支持多模板目录搜索路径，牺牲了灵活性
|
||||
|
||||
**理由**:
|
||||
- 大多数用户只需要一个模板目录
|
||||
- 如果需要多个来源，可以使用符号链接或复制文件
|
||||
- 保持逻辑简单，易于理解和维护
|
||||
|
||||
### 权衡 2: 向后兼容 vs 明确性
|
||||
|
||||
**权衡**: 破坏性变更，不向后兼容
|
||||
|
||||
**理由**:
|
||||
- 隐式默认行为是问题的根源
|
||||
- 明确性比兼容性更重要
|
||||
- 影响范围可控（只影响使用模板的用户）
|
||||
- 修复成本低（只需添加一个参数）
|
||||
@@ -0,0 +1,44 @@
|
||||
## Why
|
||||
|
||||
当前脚本默认使用相对路径 `templates_dir='templates'` 加载模板，这限制了脚本的可移植性——脚本只能在包含 templates 目录的项目根目录下运行。为了让脚本可以在任何位置使用，需要支持通过命令行参数明确指定模板目录，并移除隐式的默认行为。
|
||||
|
||||
## What Changes
|
||||
|
||||
- 添加 `--template-dir` 命令行参数，允许用户指定模板文件目录
|
||||
- **BREAKING**: 移除默认模板目录行为，使用模板时必须通过 `--template-dir` 明确指定模板目录
|
||||
- 添加模板名称验证，禁止在模板名称中使用路径分隔符（`/` 或 `\`），确保模板只能从指定目录的一层加载
|
||||
- 改进错误提示信息，明确告知用户模板查找位置和失败原因
|
||||
- 不使用模板的纯自定义幻灯片不受影响，无需指定 `--template-dir`
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `template-directory-cli`: 支持通过命令行参数指定模板目录，包括参数解析、路径验证、错误提示
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `template-system`: 修改模板加载逻辑，从硬编码的 `templates/` 目录改为必须明确指定的目录；添加模板名称验证规则
|
||||
|
||||
## Impact
|
||||
|
||||
**代码影响**:
|
||||
- `Template.__init__` 方法（184行）：修改模板路径解析逻辑，添加名称验证
|
||||
- `Presentation.__init__` 方法（610行）：移除默认 templates_dir 参数
|
||||
- `parse_args` 函数（756行）：添加 `--template-dir` 参数定义
|
||||
- `main` 函数（775行）：传递 template_dir 参数给 Presentation
|
||||
|
||||
**用户影响**:
|
||||
- **破坏性变更**: 现有使用模板的用户必须在命令行添加 `--template-dir` 参数
|
||||
- 不使用模板的用户不受影响
|
||||
- 脚本可以在任何位置运行，不再依赖特定的目录结构
|
||||
|
||||
**示例**:
|
||||
```bash
|
||||
# 之前（只能在项目根目录运行）
|
||||
uv run yaml2pptx.py presentation.yaml
|
||||
|
||||
# 之后（可以在任何位置运行，但使用模板时必须指定目录）
|
||||
uv run yaml2pptx.py presentation.yaml --template-dir ./templates
|
||||
uv run yaml2pptx.py presentation.yaml --template-dir /path/to/templates
|
||||
```
|
||||
@@ -0,0 +1,83 @@
|
||||
# Template Directory CLI
|
||||
|
||||
## Purpose
|
||||
|
||||
提供命令行参数支持，允许用户通过 `--template-dir` 参数明确指定模板文件目录，使脚本可以在任何位置运行而不依赖特定的目录结构。
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 系统必须支持 --template-dir 命令行参数
|
||||
|
||||
系统 SHALL 提供 `--template-dir` 命令行参数，允许用户指定模板文件目录的路径。
|
||||
|
||||
#### Scenario: 指定绝对路径的模板目录
|
||||
|
||||
- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml --template-dir /path/to/templates`
|
||||
- **THEN** 系统使用 `/path/to/templates` 作为模板目录
|
||||
|
||||
#### Scenario: 指定相对路径的模板目录
|
||||
|
||||
- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml --template-dir ./templates`
|
||||
- **THEN** 系统将相对路径解析为相对于当前工作目录（CWD）的绝对路径
|
||||
|
||||
#### Scenario: Windows 路径格式支持
|
||||
|
||||
- **WHEN** Windows 用户运行 `uv run yaml2pptx.py input.yaml --template-dir C:\Users\me\templates`
|
||||
- **THEN** 系统正确解析 Windows 路径格式
|
||||
|
||||
#### Scenario: 不指定 template-dir 参数且不使用模板
|
||||
|
||||
- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml`，且 YAML 文件中所有幻灯片都是自定义幻灯片（不使用模板）
|
||||
- **THEN** 系统正常处理，不报错
|
||||
|
||||
### Requirement: 使用模板时必须指定 template-dir
|
||||
|
||||
系统 SHALL 在 YAML 文件中使用了模板但未指定 `--template-dir` 参数时报错。
|
||||
|
||||
#### Scenario: 使用模板但未指定 template-dir
|
||||
|
||||
- **WHEN** YAML 文件中包含 `template: title-slide`，但用户未提供 `--template-dir` 参数
|
||||
- **THEN** 系统抛出错误，提示"未指定模板目录，无法加载模板: title-slide"，并建议使用 `--template-dir` 参数
|
||||
|
||||
#### Scenario: 错误信息包含使用示例
|
||||
|
||||
- **WHEN** 系统因未指定 template-dir 而报错
|
||||
- **THEN** 错误信息中包含"请使用 --template-dir 参数指定模板目录"的提示
|
||||
|
||||
### Requirement: 系统必须支持跨平台路径处理
|
||||
|
||||
系统 SHALL 正确处理 Mac 和 Windows 平台的路径格式，包括路径分隔符和路径表示。
|
||||
|
||||
#### Scenario: Mac 路径格式
|
||||
|
||||
- **WHEN** Mac 用户指定 `--template-dir /Users/me/templates`
|
||||
- **THEN** 系统正确解析 Unix 风格的路径
|
||||
|
||||
#### Scenario: Windows 路径格式（反斜杠）
|
||||
|
||||
- **WHEN** Windows 用户指定 `--template-dir C:\templates`
|
||||
- **THEN** 系统正确解析 Windows 风格的路径
|
||||
|
||||
#### Scenario: Windows 路径格式（正斜杠）
|
||||
|
||||
- **WHEN** Windows 用户指定 `--template-dir C:/templates`
|
||||
- **THEN** 系统正确解析路径（Windows 支持正斜杠）
|
||||
|
||||
#### Scenario: 相对路径在不同平台
|
||||
|
||||
- **WHEN** 用户在任意平台指定 `--template-dir ./templates`
|
||||
- **THEN** 系统根据当前平台的规则正确解析相对路径
|
||||
|
||||
### Requirement: 参数帮助信息必须清晰
|
||||
|
||||
系统 SHALL 在 `--help` 输出中提供清晰的 `--template-dir` 参数说明。
|
||||
|
||||
#### Scenario: 查看帮助信息
|
||||
|
||||
- **WHEN** 用户运行 `uv run yaml2pptx.py --help`
|
||||
- **THEN** 帮助信息中包含 `--template-dir` 参数的说明，注明"如果 YAML 中使用了模板则必须指定"
|
||||
|
||||
#### Scenario: 帮助信息包含路径说明
|
||||
|
||||
- **WHEN** 用户查看 `--template-dir` 的帮助信息
|
||||
- **THEN** 说明中注明"可以是绝对路径或相对路径（相对于当前工作目录）"
|
||||
@@ -0,0 +1,72 @@
|
||||
# Template System (Delta)
|
||||
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 模板文件必须可从指定目录加载
|
||||
|
||||
系统 SHALL 从用户通过 `--template-dir` 参数指定的目录加载模板文件，支持通过模板名称引用。模板名称必须是纯文件名，不能包含路径分隔符。
|
||||
|
||||
#### Scenario: 通过名称加载模板
|
||||
|
||||
- **WHEN** 幻灯片指定 `template: title-slide`，且用户提供 `--template-dir /path/to/templates`
|
||||
- **THEN** 系统从 `/path/to/templates/title-slide.yaml` 加载模板文件
|
||||
|
||||
#### Scenario: 模板文件不存在时报错
|
||||
|
||||
- **WHEN** 幻灯片引用不存在的模板名称
|
||||
- **THEN** 系统抛出错误，提示"模板文件不存在: <模板名>"，并显示查找位置和期望文件路径
|
||||
|
||||
#### Scenario: 缓存已加载的模板
|
||||
|
||||
- **WHEN** 多个幻灯片使用同一个模板
|
||||
- **THEN** 系统仅加载一次模板文件，后续使用缓存
|
||||
|
||||
#### Scenario: 错误信息包含详细的查找信息
|
||||
|
||||
- **WHEN** 模板文件未找到
|
||||
- **THEN** 错误信息包含：模板名称、查找位置（template_dir）、期望文件的完整路径、解决建议
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 模板名称必须是纯文件名
|
||||
|
||||
系统 SHALL 验证模板名称不包含路径分隔符，确保模板只能从指定目录的一层加载。
|
||||
|
||||
#### Scenario: 拒绝包含正斜杠的模板名称
|
||||
|
||||
- **WHEN** 幻灯片指定 `template: subdir/title-slide`
|
||||
- **THEN** 系统抛出错误，提示"模板名称不能包含路径分隔符: subdir/title-slide"
|
||||
|
||||
#### Scenario: 拒绝包含反斜杠的模板名称
|
||||
|
||||
- **WHEN** 幻灯片指定 `template: subdir\title-slide`
|
||||
- **THEN** 系统抛出错误，提示"模板名称不能包含路径分隔符: subdir\title-slide"
|
||||
|
||||
#### Scenario: 拒绝路径遍历尝试
|
||||
|
||||
- **WHEN** 幻灯片指定 `template: ../other-templates/slide`
|
||||
- **THEN** 系统抛出错误，提示模板名称不能包含路径分隔符
|
||||
|
||||
#### Scenario: 接受纯文件名
|
||||
|
||||
- **WHEN** 幻灯片指定 `template: title-slide`（不包含路径分隔符）
|
||||
- **THEN** 系统正常处理，从指定的 template_dir 加载模板
|
||||
|
||||
#### Scenario: 错误信息提供正确格式示例
|
||||
|
||||
- **WHEN** 系统因模板名称包含路径分隔符而报错
|
||||
- **THEN** 错误信息中包含"模板名称应该是纯文件名，如: 'title-slide'"的提示
|
||||
|
||||
### Requirement: 未指定模板目录时必须报错
|
||||
|
||||
系统 SHALL 在用户未提供 `--template-dir` 参数但 YAML 文件中使用了模板时，立即报错。
|
||||
|
||||
#### Scenario: 使用模板但未指定目录
|
||||
|
||||
- **WHEN** YAML 文件中包含 `template: title-slide`，但 `templates_dir` 参数为 `None`
|
||||
- **THEN** 系统在尝试加载模板时抛出错误，提示"未指定模板目录，无法加载模板"
|
||||
|
||||
#### Scenario: 不使用模板时不检查目录
|
||||
|
||||
- **WHEN** YAML 文件中所有幻灯片都是自定义幻灯片（不包含 `template` 字段）
|
||||
- **THEN** 系统不检查 `templates_dir` 是否为 `None`，正常处理
|
||||
@@ -0,0 +1,40 @@
|
||||
## 1. 添加命令行参数
|
||||
|
||||
- [x] 1.1 在 `parse_args` 函数中添加 `--template-dir` 参数定义
|
||||
- [x] 1.2 设置参数类型为 `str`，默认值为 `None`
|
||||
- [x] 1.3 添加清晰的帮助信息，说明参数用途和路径格式
|
||||
|
||||
## 2. 修改 Template 类
|
||||
|
||||
- [x] 2.1 修改 `Template.__init__` 方法签名，将 `templates_dir='templates'` 改为 `templates_dir=None`
|
||||
- [x] 2.2 添加 templates_dir 为 None 的检查，抛出清晰的错误信息
|
||||
- [x] 2.3 添加模板名称验证，检查是否包含 `/` 或 `\` 路径分隔符
|
||||
- [x] 2.4 移除 `if not template_path.is_absolute() and not template_path.exists()` 的逻辑
|
||||
- [x] 2.5 直接使用 `Path(templates_dir) / f"{template_file}.yaml"` 构建模板路径
|
||||
- [x] 2.6 改进模板文件不存在时的错误信息，包含查找位置和期望路径
|
||||
|
||||
## 3. 修改 Presentation 类
|
||||
|
||||
- [x] 3.1 修改 `Presentation.__init__` 方法签名，将 `templates_dir='templates'` 改为 `templates_dir=None`
|
||||
- [x] 3.2 确保 templates_dir 参数正确传递给 Template 类
|
||||
|
||||
## 4. 修改 main 函数
|
||||
|
||||
- [x] 4.1 从 `args.template_dir` 获取参数值
|
||||
- [x] 4.2 将 `templates_dir=args.template_dir` 传递给 Presentation 构造函数
|
||||
|
||||
## 5. 错误信息优化
|
||||
|
||||
- [x] 5.1 实现"未指定模板目录"错误信息，包含使用建议
|
||||
- [x] 5.2 实现"模板名称包含路径分隔符"错误信息，包含正确格式示例
|
||||
- [x] 5.3 实现"模板文件不存在"错误信息，包含查找位置、期望路径和解决建议
|
||||
|
||||
## 6. 测试验证
|
||||
|
||||
- [x] 6.1 测试不使用模板的纯自定义幻灯片（不指定 --template-dir）
|
||||
- [x] 6.2 测试使用模板但未指定 --template-dir 的错误提示
|
||||
- [x] 6.3 测试使用绝对路径指定 template-dir
|
||||
- [x] 6.4 测试使用相对路径指定 template-dir
|
||||
- [x] 6.5 测试模板名称包含路径分隔符的错误提示
|
||||
- [x] 6.6 测试模板文件不存在的错误提示
|
||||
- [x] 6.7 在 Mac 和 Windows 上验证路径处理的跨平台兼容性
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-03-02
|
||||
@@ -0,0 +1,312 @@
|
||||
## Context
|
||||
|
||||
当前大模型无法直接理解 PPTX 的二进制格式（本质是 XML 压缩包），导致 AI 生成演示文稿时需要依赖付费 API 或第三方服务。
|
||||
|
||||
我们需要创建一个开源的 YAML → PPTX 转换系统，让演示文稿的"源代码"变得人类和 AI 都可读可编辑，同时保持对样式和布局的精确控制。
|
||||
|
||||
**约束条件**:
|
||||
- 仅使用开源工具，不依赖付费服务
|
||||
- 使用 uv 运行 Python 脚本（项目规范）
|
||||
- 面向中文开发者，代码注释使用中文
|
||||
- 原型阶段，支持核心功能即可，不追求完整的 PPTX 规范覆盖
|
||||
|
||||
**利益相关者**:
|
||||
- AI 应用开发者（需要让 AI 生成 PPT）
|
||||
- 内容创作者（需要批量生成或版本控制演示文稿）
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- 实现 YAML 到 PPTX 的基础转换能力
|
||||
- 支持核心元素：文本、图片、形状、表格
|
||||
- 提供主题和模板系统，减少重复配置
|
||||
- 验证 AI 能够高效生成符合格式的 YAML 源文件
|
||||
- Token 友好的 YAML Schema 设计（简洁但可读）
|
||||
|
||||
**Non-Goals:**
|
||||
- 不支持复杂样式（渐变、阴影、动画等）
|
||||
- 不支持 PPTX 到 YAML 的反向解析（后续再考虑）
|
||||
- 不追求与 PowerPoint 的 100% 兼容性
|
||||
- 不处理视频、音频等多媒体嵌入
|
||||
- 不提供 GUI 界面（命令行工具即可）
|
||||
|
||||
## Decisions
|
||||
|
||||
### 1. 选择 python-pptx 作为底层库
|
||||
|
||||
**决策**: 使用 python-pptx 而非 PptxGenJS
|
||||
|
||||
**理由**:
|
||||
- **Python 生态契合度高**: 与 AI 工具链集成更方便，YAML 解析（PyYAML）更自然
|
||||
- **读写能力**: python-pptx 支持读取现有文件（虽然原型暂不使用，但为后续反向解析留下可能性）
|
||||
- **单位系统灵活**: 提供 Inches(), Cm(), Pt() 等便捷函数，符合精确控制需求
|
||||
- **文档完善**: 官方文档详尽，边界情况处理清晰
|
||||
- **符合项目规范**: uv 运行 Python 脚本是项目既定规范
|
||||
|
||||
**替代方案**:
|
||||
- PptxGenJS (JavaScript): 仅能创建不能读取，且 JS 环境与项目规范不符
|
||||
- 直接操作 OOXML: 复杂度高，开发成本大，不适合原型阶段
|
||||
|
||||
### 2. 两层架构设计（已简化）
|
||||
|
||||
**决策**: 采用模板（Template）+ 演示文稿（Presentation）两层架构
|
||||
|
||||
```
|
||||
模板层 (templates/*.yaml)
|
||||
↓ 定义可复用的幻灯片布局、变量占位符、颜色和样式
|
||||
演示文稿层 (presentations/*.yaml)
|
||||
↓ 实际内容，引用模板并提供变量值
|
||||
```
|
||||
|
||||
**理由**:
|
||||
- **简单直观**: 颜色和样式直接在模板中定义，无需额外抽象层
|
||||
- **灵活性强**: 每个模板可以有独立的配色方案，不受主题约束
|
||||
- **AI 友好**: 大模型可以直接生成颜色值（如 #4a90e2），无需理解主题变量
|
||||
- **维护成本低**: 减少一层抽象，代码量减少约 100 行
|
||||
|
||||
**已废弃的设计**:
|
||||
- ~~三层架构（主题+模板+演示文稿）~~: 增加复杂度，颜色复用场景有限
|
||||
- 主题层的抽象在实践中发现意义不大
|
||||
- 颜色和样式通常不会大量复用
|
||||
- 直接指定更符合直觉
|
||||
|
||||
**替代方案考量**:
|
||||
- 扁平结构（所有配置写在一个文件）: Token 消耗大，AI 生成效率低
|
||||
- ✅ **当前方案**（模板+演示文稿）: 平衡了简洁性和可复用性
|
||||
|
||||
### 3. YAML Schema 设计原则
|
||||
|
||||
**决策**: 使用"可读版"格式，平衡 token 消耗和人类可读性
|
||||
|
||||
```yaml
|
||||
# 采用的设计
|
||||
- type: text
|
||||
content: "Hello"
|
||||
box: [1, 2, 8, 3] # 数组形式，紧凑
|
||||
font: {size: 32, bold: true, color: "#333"} # 单行对象
|
||||
|
||||
# 拒绝的极简版（token 更少但可读性差）
|
||||
- [text, "Hello", [1,2,8,3], {s:32, b:true}]
|
||||
|
||||
# 拒绝的冗长版（可读性好但 token 多）
|
||||
- type: text
|
||||
content: "Hello"
|
||||
position:
|
||||
x: 1
|
||||
y: 2
|
||||
width: 8
|
||||
height: 3
|
||||
font:
|
||||
size: 32
|
||||
bold: true
|
||||
```
|
||||
|
||||
**理由**:
|
||||
- `box: [x, y, w, h]` 紧凑且语义清晰
|
||||
- 单行对象 `{size: 32, bold: true}` 比多行嵌套节省约 50% token
|
||||
- 大模型能够准确理解和生成这种结构
|
||||
- 人类阅读时仍能快速理解布局
|
||||
|
||||
### 4. 单位系统
|
||||
|
||||
**决策**: 默认使用英寸（inches），初期不支持混合单位
|
||||
|
||||
**理由**:
|
||||
- python-pptx 内部使用 EMU（914,400 EMU = 1 inch），Inches() 转换最直接
|
||||
- PowerPoint 标准尺寸明确：16:9 = 10×5.625 英寸，4:3 = 10×7.5 英寸
|
||||
- 避免单位换算带来的精度损失和复杂度
|
||||
- AI 生成时，统一单位更不容易出错
|
||||
|
||||
**替代方案**:
|
||||
- 百分比：响应式但精确度不足
|
||||
- 混合单位（"10%", "2cm", 3.0）：增加解析复杂度，原型不必要
|
||||
|
||||
**未来扩展**: 可在 v2 支持 `box: ["10%", "20%", "80%", "30%"]` 等灵活单位
|
||||
|
||||
### 5. 变量引用系统（已简化）
|
||||
|
||||
**决策**: 仅支持模板变量引用 `{title}`
|
||||
|
||||
```yaml
|
||||
# 模板变量引用
|
||||
content: "{title}"
|
||||
background_color: "{background_color}"
|
||||
|
||||
# 颜色和样式直接指定（不再使用变量）
|
||||
color: "#4a90e2"
|
||||
size: 44
|
||||
```
|
||||
|
||||
**理由**:
|
||||
- 简化实现，仅需处理用户提供的变量值
|
||||
- 颜色等样式值直接在模板中定义，更直观
|
||||
- 初期不支持计算表达式（如 `{spacing * 2}`），降低复杂度
|
||||
|
||||
**实现方式**:
|
||||
```python
|
||||
def resolve_value(value, vars_values):
|
||||
pattern = r'\{([^}]+)\}'
|
||||
def replacer(match):
|
||||
expr = match.group(1)
|
||||
if expr in vars_values:
|
||||
return str(vars_values[expr])
|
||||
else:
|
||||
raise YAMLError(f"未定义的变量: {expr}")
|
||||
return re.sub(pattern, replacer, value)
|
||||
```
|
||||
|
||||
**已移除功能**:
|
||||
- ~~主题变量引用~~（`{theme.colors.primary}`）
|
||||
- ~~Theme.resolve() 方法~~
|
||||
|
||||
### 6. 文件组织结构（已简化）
|
||||
|
||||
**决策**:
|
||||
```
|
||||
project/
|
||||
├── templates/ # 模板定义（包含颜色和样式）
|
||||
│ ├── title_slide.yaml
|
||||
│ ├── content_slide.yaml
|
||||
│ └── two_column.yaml
|
||||
├── presentations/ # 用户创建的演示文稿
|
||||
│ └── my_pres.yaml
|
||||
├── assets/ # 图片等资源
|
||||
│ └── images/
|
||||
├── examples/ # 示例文件
|
||||
│ ├── demo.yaml
|
||||
│ ├── custom.yaml
|
||||
│ └── complex.yaml
|
||||
└── yaml2pptx.py # 转换脚本（使用 uv 运行）
|
||||
```
|
||||
|
||||
**理由**:
|
||||
- 简化目录结构，移除 themes/ 目录
|
||||
- 模板自包含样式定义，更容易理解
|
||||
- assets/ 集中管理资源文件
|
||||
|
||||
**已移除**:
|
||||
- ~~themes/ 目录~~：颜色和样式现在直接在模板中定义
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
### 风险 1: YAML 格式复杂度
|
||||
|
||||
**风险**: YAML 的缩进敏感性可能导致 AI 生成格式错误
|
||||
|
||||
**缓解方案**:
|
||||
- 提供严格的 YAML schema 验证（使用 jsonschema）
|
||||
- 在错误消息中明确指出格式问题位置
|
||||
- 提供丰富的示例文件供 AI 参考
|
||||
|
||||
### 风险 2: python-pptx 功能限制
|
||||
|
||||
**风险**: python-pptx 不支持某些高级 PowerPoint 特性（如 SmartArt、自定义动画）
|
||||
|
||||
**缓解方案**:
|
||||
- 原型阶段明确定义支持范围（文本、图片、形状、表格）
|
||||
- 在文档中清晰标注不支持的功能
|
||||
- 预留扩展接口，未来可通过直接操作 OOXML 实现高级功能
|
||||
|
||||
### 风险 3: 性能问题
|
||||
|
||||
**风险**: 大型演示文稿（100+ 页）转换可能较慢
|
||||
|
||||
**缓解方案**:
|
||||
- 原型阶段不优化性能，聚焦功能验证
|
||||
- 未来可考虑并行处理、缓存模板等优化手段
|
||||
|
||||
### Trade-off: 灵活性 vs 简洁性
|
||||
|
||||
**权衡**: 模板系统提供了灵活性，但增加了学习成本
|
||||
|
||||
**选择**: 保留模板系统，因为：
|
||||
- AI 生成时 token 节省显著（75%）
|
||||
- 提供默认模板，降低使用门槛
|
||||
- 高级用户可自定义模板，初学者直接用现成的
|
||||
|
||||
### Trade-off: 完整性 vs 原型速度
|
||||
|
||||
**权衡**: 支持更多 PPTX 特性 vs 快速验证核心假设
|
||||
|
||||
**选择**: 原型阶段仅实现核心功能
|
||||
- 文本、图片、形状、表格已覆盖 80% 常见场景
|
||||
- 快速验证"AI 能否高效生成 YAML"这一核心假设
|
||||
- 后续根据反馈再扩展功能
|
||||
|
||||
## 实现策略
|
||||
|
||||
### 核心类设计（已简化）
|
||||
|
||||
```python
|
||||
class Template:
|
||||
"""模板类，渲染模板并替换变量"""
|
||||
def __init__(self, template_file): ...
|
||||
def render(self, vars_values) -> list: ... # 返回渲染后的元素列表
|
||||
def resolve_value(self, value, vars_values): ... # 仅解析模板变量
|
||||
|
||||
class Presentation:
|
||||
"""演示文稿类，协调模板、内容"""
|
||||
def __init__(self, pres_file): ...
|
||||
def render_slide(self, slide_data) -> dict: ...
|
||||
|
||||
class PptxGenerator:
|
||||
"""PPTX 生成器，调用 python-pptx API"""
|
||||
def add_slide(self, slide_data): ...
|
||||
def save(self, output_file): ...
|
||||
```
|
||||
|
||||
**已移除**:
|
||||
- ~~Theme 类~~：不再需要主题抽象
|
||||
|
||||
### 实现阶段（已完成）
|
||||
|
||||
**Phase 1: 基础框架** ✅
|
||||
1. YAML 解析和基础数据结构
|
||||
2. 简单的文本元素渲染
|
||||
3. 验证 python-pptx 基本用法
|
||||
|
||||
**Phase 2: 模板系统** ✅
|
||||
1. 模板 YAML schema 定义
|
||||
2. Template 类和变量替换（仅模板变量）
|
||||
3. 创建 3 个常用模板（标题页、内容页、双栏等）
|
||||
|
||||
**Phase 3: 完整元素支持** ✅
|
||||
1. 图片、形状、表格渲染
|
||||
2. 样式系统完善（颜色、字体、对齐）
|
||||
3. 完整的示例演示文稿
|
||||
|
||||
**Phase 4: 简化优化** ✅
|
||||
1. 移除主题系统，简化架构
|
||||
2. 颜色和样式直接在模板中定义
|
||||
3. 更新所有文档和示例
|
||||
|
||||
## 已解决问题
|
||||
|
||||
1. **条件渲染语法**: ✅ 已实现
|
||||
- 支持简单的存在性检查：`visible: "{subtitle != ''}"`
|
||||
- 仅支持简单表达式，不支持复杂逻辑
|
||||
|
||||
2. ~~**主题继承**~~: ❌ 已废弃
|
||||
- 主题系统已移除，不再需要此功能
|
||||
|
||||
3. **错误处理策略**: ✅ 已实现
|
||||
- YAML 语法错误：显示文件路径和行号
|
||||
- 文件不存在：明确提示文件路径
|
||||
- 变量未定义：清晰的错误消息
|
||||
- 颜色格式错误：提示使用 #RRGGBB 格式
|
||||
|
||||
4. **默认值机制**: ✅ 已实现
|
||||
- 必需变量未提供值且无默认值：抛出错误
|
||||
- 可选变量未提供值：使用模板定义的 default
|
||||
|
||||
## 架构简化决策
|
||||
|
||||
**2026-03-02 重要变更**：移除主题系统
|
||||
|
||||
- **原因**: 颜色和样式复用场景有限，主题抽象增加复杂度
|
||||
- **变更**: 颜色、字体大小等直接在模板中定义
|
||||
- **优势**:
|
||||
- 减少 ~100 行代码
|
||||
- 更直观，无需查找主题定义
|
||||
- 每个模板可独立配色
|
||||
- AI 更容易生成（直接输出颜色值）
|
||||
@@ -0,0 +1,38 @@
|
||||
## Why
|
||||
|
||||
大模型无法直接读取或理解 PPTX 二进制文档格式，导致 AI 无法有效生成和编辑演示文稿。我们需要一个人类和 AI 都能轻松理解、编辑的源文件格式（YAML），通过脚本转换为 PPTX，从而让 AI 能够高效生成高质量的演示文稿。
|
||||
|
||||
## What Changes
|
||||
|
||||
- 实现 YAML 到 PPTX 的转换脚本原型
|
||||
- 支持模板系统（template）+ 演示文稿（presentation）两层架构
|
||||
- 实现核心 PPTX 元素生成：文本、图片、形状、表格
|
||||
- 提供精确的布局控制（基于英寸单位）
|
||||
- 创建示例模板，颜色和样式直接在模板中定义
|
||||
- 使用 Python + python-pptx 库实现，遵循项目规范（uv 运行）
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `yaml-parsing`: YAML 文件解析和数据结构验证，支持演示文稿、模板两种类型的 YAML 文件
|
||||
- `template-system`: 模板系统，支持可复用的幻灯片布局、变量替换、条件渲染，颜色和样式直接在模板中定义
|
||||
- `element-rendering`: 元素渲染系统，将 YAML 中定义的元素（文本、图片、形状、表格）转换为 PPTX 对象
|
||||
- `pptx-generation`: PPTX 文件生成，基于 python-pptx 库创建完整的演示文稿文件
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
无（新项目）
|
||||
|
||||
## Impact
|
||||
|
||||
- **新增依赖**: python-pptx, PyYAML
|
||||
- **新增文件结构**:
|
||||
- `templates/` - 模板定义目录（颜色和样式直接在模板中定义）
|
||||
- `presentations/` - 演示文稿源文件目录
|
||||
- `yaml2pptx.py` - 核心转换脚本
|
||||
- `examples/` - 示例文件
|
||||
- `assets/` - 资源文件目录（图片等）
|
||||
- **运行环境**: 使用 uv 运行 Python 脚本，遵循项目规范
|
||||
- **设计理念**: 简化系统，移除主题抽象层，颜色和样式直接在模板中指定
|
||||
- **无现有代码影响**: 这是一个独立的新功能原型
|
||||
@@ -0,0 +1,168 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 系统必须支持文本元素渲染
|
||||
|
||||
系统 SHALL 将 YAML 中定义的文本元素渲染为 PPTX 文本框。
|
||||
|
||||
#### Scenario: 渲染基本文本元素
|
||||
|
||||
- **WHEN** 元素定义为 `{type: text, content: "Hello", box: [1, 2, 8, 3]}`
|
||||
- **THEN** 系统在幻灯片的 (1, 2) 位置创建 8×3 英寸的文本框，内容为 "Hello"
|
||||
|
||||
#### Scenario: 应用文本字体样式
|
||||
|
||||
- **WHEN** 文本元素定义了 `font: {size: 32, bold: true, color: "#333333"}`
|
||||
- **THEN** 系统将文本设置为 32pt、粗体、颜色为 #333333
|
||||
|
||||
#### Scenario: 应用文本对齐方式
|
||||
|
||||
- **WHEN** 文本元素定义了 `font: {align: center}`
|
||||
- **THEN** 系统将文本设置为居中对齐
|
||||
|
||||
#### Scenario: 支持多种对齐方式
|
||||
|
||||
- **WHEN** 文本对齐方式为 `left`、`center`、`right` 之一
|
||||
- **THEN** 系统正确应用对应的对齐方式
|
||||
|
||||
### Requirement: 系统必须支持图片元素渲染
|
||||
|
||||
系统 SHALL 将 YAML 中定义的图片元素渲染为 PPTX 图片对象。
|
||||
|
||||
#### Scenario: 渲染本地图片
|
||||
|
||||
- **WHEN** 元素定义为 `{type: image, src: "images/logo.png", box: [2, 3, 4, 3]}`
|
||||
- **THEN** 系统从指定路径加载图片，在 (2, 3) 位置渲染为 4×3 英寸大小
|
||||
|
||||
#### Scenario: 图片文件不存在时报错
|
||||
|
||||
- **WHEN** 图片 src 指向不存在的文件路径
|
||||
- **THEN** 系统抛出错误，明确指出图片文件未找到
|
||||
|
||||
#### Scenario: 图片格式不支持时报错
|
||||
|
||||
- **WHEN** 图片文件格式不被 python-pptx 支持
|
||||
- **THEN** 系统抛出错误，提示图片格式不支持，并列出支持的格式
|
||||
|
||||
#### Scenario: 相对路径处理
|
||||
|
||||
- **WHEN** 图片 src 使用相对路径 `"assets/images/logo.png"`
|
||||
- **THEN** 系统基于演示文稿文件所在目录解析相对路径
|
||||
|
||||
### Requirement: 系统必须支持形状元素渲染
|
||||
|
||||
系统 SHALL 将 YAML 中定义的形状元素渲染为 PPTX 形状对象。
|
||||
|
||||
#### Scenario: 渲染矩形形状
|
||||
|
||||
- **WHEN** 元素定义为 `{type: shape, shape: rectangle, box: [1, 2, 3, 1], fill: "#4a90e2"}`
|
||||
- **THEN** 系统在 (1, 2) 位置创建 3×1 英寸的矩形，填充颜色为 #4a90e2
|
||||
|
||||
#### Scenario: 渲染圆形形状
|
||||
|
||||
- **WHEN** 元素的 `shape` 字段为 `ellipse`
|
||||
- **THEN** 系统渲染椭圆/圆形形状
|
||||
|
||||
#### Scenario: 渲染圆角矩形
|
||||
|
||||
- **WHEN** 元素的 `shape` 字段为 `rounded_rectangle`
|
||||
- **THEN** 系统渲染圆角矩形形状
|
||||
|
||||
#### Scenario: 应用形状边框样式
|
||||
|
||||
- **WHEN** 形状定义了 `line: {color: "#000000", width: 2}`
|
||||
- **THEN** 系统为形状添加黑色、2pt 宽度的边框
|
||||
|
||||
### Requirement: 系统必须支持表格元素渲染
|
||||
|
||||
系统 SHALL 将 YAML 中定义的表格元素渲染为 PPTX 表格对象。
|
||||
|
||||
#### Scenario: 渲染基本表格
|
||||
|
||||
- **WHEN** 元素定义为 `{type: table, position: [1, 2], data: [["A", "B"], ["C", "D"]], col_widths: [2, 2]}`
|
||||
- **THEN** 系统在 (1, 2) 位置创建 2×2 表格，列宽各为 2 英寸
|
||||
|
||||
#### Scenario: 应用表格样式
|
||||
|
||||
- **WHEN** 表格定义了 `style: {font_size: 14, header_bg: "#4a90e2", header_color: "#ffffff"}`
|
||||
- **THEN** 系统将第一行设置为表头样式，背景色为 #4a90e2，文字颜色为白色
|
||||
|
||||
#### Scenario: 表格数据为空时报错
|
||||
|
||||
- **WHEN** 表格的 `data` 字段为空数组
|
||||
- **THEN** 系统抛出错误，提示表格数据不能为空
|
||||
|
||||
#### Scenario: 表格列宽不匹配时报错
|
||||
|
||||
- **WHEN** `col_widths` 数组长度与表格列数不一致
|
||||
- **THEN** 系统抛出错误，要求列宽数量与列数匹配
|
||||
|
||||
### Requirement: 元素位置必须使用英寸单位
|
||||
|
||||
系统 SHALL 将元素的 box 或 position 字段中的数值解释为英寸单位。
|
||||
|
||||
#### Scenario: box 数组表示位置和尺寸
|
||||
|
||||
- **WHEN** 元素定义了 `box: [1, 2, 8, 3]`
|
||||
- **THEN** 系统将其解释为 x=1英寸, y=2英寸, width=8英寸, height=3英寸
|
||||
|
||||
#### Scenario: position 数组表示位置
|
||||
|
||||
- **WHEN** 表格元素定义了 `position: [1, 2]`
|
||||
- **THEN** 系统将其解释为 x=1英寸, y=2英寸
|
||||
|
||||
#### Scenario: 负数坐标值报错
|
||||
|
||||
- **WHEN** box 或 position 包含负数值
|
||||
- **THEN** 系统抛出错误，要求坐标值必须为非负数
|
||||
|
||||
### Requirement: 系统必须支持幻灯片背景设置
|
||||
|
||||
系统 SHALL 支持为幻灯片设置纯色背景或图片背景。
|
||||
|
||||
#### Scenario: 设置纯色背景
|
||||
|
||||
- **WHEN** 幻灯片定义了 `background: {color: "#ffffff"}`
|
||||
- **THEN** 系统将幻灯片背景设置为白色
|
||||
|
||||
#### Scenario: 设置图片背景
|
||||
|
||||
- **WHEN** 幻灯片定义了 `background: {image: "bg.png"}`
|
||||
- **THEN** 系统使用指定图片作为幻灯片背景
|
||||
|
||||
#### Scenario: 背景图片不存在时报错
|
||||
|
||||
- **WHEN** 背景图片路径不存在
|
||||
- **THEN** 系统抛出错误，提示背景图片文件未找到
|
||||
|
||||
### Requirement: 系统必须处理元素重叠和层次
|
||||
|
||||
系统 SHALL 按照元素在 elements 列表中的顺序渲染，后定义的元素显示在前面元素之上。
|
||||
|
||||
#### Scenario: 元素按定义顺序渲染
|
||||
|
||||
- **WHEN** elements 列表为 `[shape1, text1, image1]`
|
||||
- **THEN** 系统先渲染 shape1，再渲染 text1，最后渲染 image1（image1 在最上层）
|
||||
|
||||
#### Scenario: 重叠元素的显示层次
|
||||
|
||||
- **WHEN** 两个元素的位置有重叠
|
||||
- **THEN** 后定义的元素遮盖先定义的元素
|
||||
|
||||
### Requirement: 系统必须验证元素类型
|
||||
|
||||
系统 SHALL 验证每个元素的 type 字段，仅支持已定义的元素类型。
|
||||
|
||||
#### Scenario: 支持的元素类型
|
||||
|
||||
- **WHEN** 元素的 `type` 为 `text`、`image`、`shape`、`table` 之一
|
||||
- **THEN** 系统正常渲染该元素
|
||||
|
||||
#### Scenario: 不支持的元素类型报错
|
||||
|
||||
- **WHEN** 元素的 `type` 为未定义的值（如 "video"）
|
||||
- **THEN** 系统抛出错误，提示不支持该元素类型，并列出支持的类型
|
||||
|
||||
#### Scenario: 缺少 type 字段报错
|
||||
|
||||
- **WHEN** 元素未定义 `type` 字段
|
||||
- **THEN** 系统抛出错误，要求每个元素必须包含 type 字段
|
||||
@@ -0,0 +1,215 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 系统必须创建符合 OOXML 标准的 PPTX 文件
|
||||
|
||||
系统 SHALL 使用 python-pptx 库生成符合 Office Open XML (OOXML) 标准的 .pptx 文件。
|
||||
|
||||
#### Scenario: 生成的 PPTX 文件可被 PowerPoint 打开
|
||||
|
||||
- **WHEN** 系统生成 PPTX 文件
|
||||
- **THEN** 该文件可被 Microsoft PowerPoint 正常打开和编辑
|
||||
|
||||
#### Scenario: 生成的 PPTX 文件可被其他软件打开
|
||||
|
||||
- **WHEN** 系统生成 PPTX 文件
|
||||
- **THEN** 该文件可被 LibreOffice Impress、Google Slides 等软件正常打开
|
||||
|
||||
#### Scenario: PPTX 文件扩展名正确
|
||||
|
||||
- **WHEN** 系统保存演示文稿
|
||||
- **THEN** 输出文件的扩展名为 `.pptx`
|
||||
|
||||
### Requirement: 系统必须支持设置演示文稿尺寸
|
||||
|
||||
系统 SHALL 支持设置演示文稿的幻灯片尺寸，支持 16:9 和 4:3 两种标准比例。
|
||||
|
||||
#### Scenario: 创建 16:9 比例的演示文稿
|
||||
|
||||
- **WHEN** metadata 中指定 `size: "16:9"`
|
||||
- **THEN** 系统创建 10×5.625 英寸的幻灯片
|
||||
|
||||
#### Scenario: 创建 4:3 比例的演示文稿
|
||||
|
||||
- **WHEN** metadata 中指定 `size: "4:3"`
|
||||
- **THEN** 系统创建 10×7.5 英寸的幻灯片
|
||||
|
||||
#### Scenario: 默认使用 16:9 比例
|
||||
|
||||
- **WHEN** metadata 中未指定 size 字段
|
||||
- **THEN** 系统默认使用 16:9 比例
|
||||
|
||||
#### Scenario: 不支持的尺寸比例报错
|
||||
|
||||
- **WHEN** metadata 中指定了不支持的尺寸比例（如 "21:9"）
|
||||
- **THEN** 系统抛出错误，提示仅支持 16:9 和 4:3
|
||||
|
||||
### Requirement: 系统必须按顺序添加幻灯片
|
||||
|
||||
系统 SHALL 按照 YAML 中 slides 列表的顺序，依次添加幻灯片到 PPTX 文件。
|
||||
|
||||
#### Scenario: 幻灯片顺序与 YAML 一致
|
||||
|
||||
- **WHEN** YAML 中 slides 列表为 `[slide1, slide2, slide3]`
|
||||
- **THEN** 生成的 PPTX 文件中，幻灯片顺序为 slide1、slide2、slide3
|
||||
|
||||
#### Scenario: 空幻灯片列表生成空演示文稿
|
||||
|
||||
- **WHEN** YAML 中 slides 列表为空
|
||||
- **THEN** 系统生成一个不包含任何幻灯片的 PPTX 文件（或抛出警告）
|
||||
|
||||
### Requirement: 系统必须使用空白布局
|
||||
|
||||
系统 SHALL 为每个幻灯片使用空白布局（blank layout），以便完全自定义内容。
|
||||
|
||||
#### Scenario: 使用空白布局添加幻灯片
|
||||
|
||||
- **WHEN** 系统添加幻灯片
|
||||
- **THEN** 使用 `prs.slide_layouts[6]`（空白布局）而非预定义布局
|
||||
|
||||
#### Scenario: 空白幻灯片不包含占位符
|
||||
|
||||
- **WHEN** 创建新的空白幻灯片
|
||||
- **THEN** 幻灯片不包含任何预定义的标题或内容占位符
|
||||
|
||||
### Requirement: 系统必须保存到指定路径
|
||||
|
||||
系统 SHALL 将生成的 PPTX 文件保存到用户指定的路径。
|
||||
|
||||
#### Scenario: 保存到指定文件路径
|
||||
|
||||
- **WHEN** 用户指定输出路径为 `output/presentation.pptx`
|
||||
- **THEN** 系统将 PPTX 文件保存到该路径
|
||||
|
||||
#### Scenario: 自动创建输出目录
|
||||
|
||||
- **WHEN** 输出路径包含不存在的目录（如 `output/subdir/file.pptx`）
|
||||
- **THEN** 系统自动创建所需的目录结构
|
||||
|
||||
#### Scenario: 输出路径已存在时覆盖
|
||||
|
||||
- **WHEN** 指定的输出文件路径已存在
|
||||
- **THEN** 系统覆盖原有文件（或提供选项询问用户）
|
||||
|
||||
#### Scenario: 无写入权限时报错
|
||||
|
||||
- **WHEN** 输出路径没有写入权限
|
||||
- **THEN** 系统抛出错误，提示权限不足
|
||||
|
||||
### Requirement: 系统必须使用 python-pptx 的单位转换函数
|
||||
|
||||
系统 SHALL 使用 python-pptx 提供的 Inches() 函数将英寸值转换为 EMU（English Metric Units）。
|
||||
|
||||
#### Scenario: 使用 Inches() 转换坐标
|
||||
|
||||
- **WHEN** 元素 box 定义为 `[1, 2, 8, 3]`
|
||||
- **THEN** 系统调用 `Inches(1)`, `Inches(2)`, `Inches(8)`, `Inches(3)` 转换为 EMU
|
||||
|
||||
#### Scenario: EMU 转换的精度
|
||||
|
||||
- **WHEN** 使用 Inches(1.0)
|
||||
- **THEN** 返回值为 914400 EMU（1 英寸 = 914400 EMU）
|
||||
|
||||
### Requirement: 系统必须处理颜色转换
|
||||
|
||||
系统 SHALL 将十六进制颜色值（如 "#4a90e2"）转换为 python-pptx 的 RGBColor 对象。
|
||||
|
||||
#### Scenario: 十六进制颜色转 RGB
|
||||
|
||||
- **WHEN** 颜色值为 "#4a90e2"
|
||||
- **THEN** 系统转换为 RGBColor(74, 144, 226)
|
||||
|
||||
#### Scenario: 短格式十六进制颜色
|
||||
|
||||
- **WHEN** 颜色值为 "#fff"（短格式）
|
||||
- **THEN** 系统扩展为 "#ffffff" 并转换为 RGBColor(255, 255, 255)
|
||||
|
||||
#### Scenario: 无效颜色格式报错
|
||||
|
||||
- **WHEN** 颜色值不是有效的十六进制格式
|
||||
- **THEN** 系统抛出错误，提示颜色格式无效
|
||||
|
||||
### Requirement: 系统必须使用 uv 运行 Python 脚本
|
||||
|
||||
系统 SHALL 使用 uv 运行转换脚本，通过 Inline script metadata 指定依赖。
|
||||
|
||||
#### Scenario: 脚本包含 Inline script metadata
|
||||
|
||||
- **WHEN** 查看 `yaml2pptx.py` 文件头部
|
||||
- **THEN** 包含 `# /// script` 块，定义 python-pptx 和 PyYAML 依赖
|
||||
|
||||
#### Scenario: 使用 uv 运行脚本
|
||||
|
||||
- **WHEN** 执行转换命令
|
||||
- **THEN** 使用 `uv run yaml2pptx.py` 而非 `python yaml2pptx.py`
|
||||
|
||||
#### Scenario: 禁止直接安装依赖
|
||||
|
||||
- **WHEN** 需要使用 python-pptx 或 PyYAML
|
||||
- **THEN** 不使用 `pip install`，而是在 script metadata 中声明依赖
|
||||
|
||||
### Requirement: 系统架构保持简洁
|
||||
|
||||
系统 SHALL 采用两层架构（模板 + 演示文稿），颜色和样式直接在模板中定义。
|
||||
|
||||
#### Scenario: 模板自包含样式
|
||||
|
||||
- **WHEN** 查看模板文件
|
||||
- **THEN** 颜色值直接以十六进制格式指定（如 "#4a90e2"）
|
||||
|
||||
#### Scenario: 无需主题配置
|
||||
|
||||
- **WHEN** 创建新的演示文稿
|
||||
- **THEN** metadata 中不需要指定 theme 字段
|
||||
|
||||
#### Scenario: 模板独立配色
|
||||
|
||||
- **WHEN** 创建新模板
|
||||
- **THEN** 可以为该模板定义独立的颜色方案，不受其他模板影响
|
||||
|
||||
### Requirement: 系统必须提供命令行接口
|
||||
|
||||
系统 SHALL 提供命令行接口，接受输入 YAML 文件路径和输出 PPTX 文件路径。
|
||||
|
||||
#### Scenario: 基本命令行使用
|
||||
|
||||
- **WHEN** 执行 `uv run yaml2pptx.py input.yaml output.pptx`
|
||||
- **THEN** 系统读取 input.yaml，生成 output.pptx
|
||||
|
||||
#### Scenario: 仅提供输入文件时自动命名输出
|
||||
|
||||
- **WHEN** 执行 `uv run yaml2pptx.py input.yaml`
|
||||
- **THEN** 系统自动生成输出文件名为 `input.pptx`
|
||||
|
||||
#### Scenario: 显示帮助信息
|
||||
|
||||
- **WHEN** 执行 `uv run yaml2pptx.py --help`
|
||||
- **THEN** 系统显示使用说明和参数列表
|
||||
|
||||
#### Scenario: 输入文件不存在时报错
|
||||
|
||||
- **WHEN** 提供的输入文件路径不存在
|
||||
- **THEN** 系统抛出错误，提示输入文件未找到
|
||||
|
||||
### Requirement: 系统必须报告转换进度
|
||||
|
||||
系统 SHALL 在转换过程中输出进度信息，包括当前处理的幻灯片数量。
|
||||
|
||||
#### Scenario: 输出转换开始信息
|
||||
|
||||
- **WHEN** 开始转换
|
||||
- **THEN** 系统输出 "开始转换: input.yaml"
|
||||
|
||||
#### Scenario: 输出幻灯片处理进度
|
||||
|
||||
- **WHEN** 处理每个幻灯片
|
||||
- **THEN** 系统输出 "处理幻灯片 N/M"
|
||||
|
||||
#### Scenario: 输出转换完成信息
|
||||
|
||||
- **WHEN** 转换成功完成
|
||||
- **THEN** 系统输出 "转换完成: output.pptx"
|
||||
|
||||
#### Scenario: 转换失败时输出错误
|
||||
|
||||
- **WHEN** 转换过程中发生错误
|
||||
- **THEN** 系统输出详细的错误信息和堆栈跟踪（调试模式下）
|
||||
@@ -0,0 +1,134 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 模板必须定义变量列表
|
||||
|
||||
模板 SHALL 包含 vars 字段，定义该模板需要的变量，包括变量名、是否必需、默认值等。
|
||||
|
||||
#### Scenario: 加载模板变量定义
|
||||
|
||||
- **WHEN** 模板文件定义了 `vars` 列表，包含 `name`、`required`、`default` 等字段
|
||||
- **THEN** 系统成功加载变量定义，可通过模板对象访问
|
||||
|
||||
#### Scenario: 验证必需变量
|
||||
|
||||
- **WHEN** 模板定义了 `{name: title, required: true}` 的变量
|
||||
- **THEN** 渲染时如果未提供该变量，系统抛出错误
|
||||
|
||||
#### Scenario: 使用变量默认值
|
||||
|
||||
- **WHEN** 模板定义了 `{name: subtitle, required: false, default: ""}` 的变量
|
||||
- **THEN** 渲染时如果未提供该变量，系统使用空字符串作为默认值
|
||||
|
||||
### Requirement: 模板必须定义元素列表
|
||||
|
||||
模板 SHALL 包含 elements 字段，定义该模板的幻灯片布局和元素。
|
||||
|
||||
#### Scenario: 加载模板元素定义
|
||||
|
||||
- **WHEN** 模板文件定义了 `elements` 列表，包含文本、图片、形状等元素
|
||||
- **THEN** 系统成功加载元素列表，准备渲染
|
||||
|
||||
#### Scenario: 元素包含模板变量引用
|
||||
|
||||
- **WHEN** 模板元素中包含 `{title}` 等模板变量引用
|
||||
- **THEN** 系统在渲染时用用户提供的值替换变量
|
||||
|
||||
#### Scenario: 元素直接指定样式值
|
||||
|
||||
- **WHEN** 模板元素中直接指定 `color: "#4a90e2"` 等样式值
|
||||
- **THEN** 系统正确应用该样式值
|
||||
|
||||
### Requirement: 系统必须支持模板渲染
|
||||
|
||||
系统 SHALL 能够根据用户提供的变量值渲染模板，生成实际的元素列表。
|
||||
|
||||
#### Scenario: 渲染包含变量的模板
|
||||
|
||||
- **WHEN** 用户提供 `{title: "Hello", subtitle: "World"}` 渲染模板
|
||||
- **THEN** 系统将模板中的 `{title}` 替换为 "Hello"，`{subtitle}` 替换为 "World"
|
||||
|
||||
#### Scenario: 数值类型自动转换
|
||||
|
||||
- **WHEN** 模板定义 `size: "{font_size}"` 且用户提供 `{font_size: "44"}`
|
||||
- **THEN** 系统自动将字符串 "44" 转换为整数 44
|
||||
|
||||
#### Scenario: 检测未定义的模板变量
|
||||
|
||||
- **WHEN** 模板中引用了 `{undefined_var}`，但该变量未在 vars 中定义，也未由用户提供
|
||||
- **THEN** 系统抛出错误，指出未定义的变量
|
||||
|
||||
### Requirement: 系统必须支持条件渲染
|
||||
|
||||
系统 SHALL 支持基于变量值的条件渲染，通过 `visible` 字段控制元素是否显示。
|
||||
|
||||
#### Scenario: 显示满足条件的元素
|
||||
|
||||
- **WHEN** 元素定义了 `visible: "{subtitle != ''}"`，且用户提供了非空的 subtitle
|
||||
- **THEN** 系统渲染该元素
|
||||
|
||||
#### Scenario: 隐藏不满足条件的元素
|
||||
|
||||
- **WHEN** 元素定义了 `visible: "{subtitle != ''}"`，但用户提供的 subtitle 为空字符串
|
||||
- **THEN** 系统跳过该元素，不渲染到幻灯片中
|
||||
|
||||
#### Scenario: 条件表达式语法错误
|
||||
|
||||
- **WHEN** visible 字段包含无效的条件表达式
|
||||
- **THEN** 系统抛出错误，提示条件表达式格式错误
|
||||
|
||||
### Requirement: 模板文件必须可从指定目录加载
|
||||
|
||||
系统 SHALL 从 `templates/` 目录加载模板文件，支持通过模板名称引用。
|
||||
|
||||
#### Scenario: 通过名称加载模板
|
||||
|
||||
- **WHEN** 幻灯片指定 `template: title_slide`
|
||||
- **THEN** 系统从 `templates/title_slide.yaml` 加载模板文件
|
||||
|
||||
#### Scenario: 模板文件不存在时报错
|
||||
|
||||
- **WHEN** 幻灯片引用不存在的模板名称
|
||||
- **THEN** 系统抛出错误，提示模板文件未找到，并列出可用模板
|
||||
|
||||
#### Scenario: 缓存已加载的模板
|
||||
|
||||
- **WHEN** 多个幻灯片使用同一个模板
|
||||
- **THEN** 系统仅加载一次模板文件，后续使用缓存
|
||||
|
||||
### Requirement: 系统必须支持自定义幻灯片
|
||||
|
||||
系统 SHALL 支持不使用模板，直接定义元素的自定义幻灯片。
|
||||
|
||||
#### Scenario: 渲染自定义幻灯片
|
||||
|
||||
- **WHEN** 幻灯片未指定 `template` 字段，直接包含 `elements` 列表
|
||||
- **THEN** 系统跳过模板渲染，直接处理元素列表
|
||||
|
||||
#### Scenario: 自定义幻灯片中直接指定样式
|
||||
|
||||
- **WHEN** 自定义幻灯片的元素直接指定 `color: "#4a90e2"`
|
||||
- **THEN** 系统正确应用该颜色值
|
||||
|
||||
#### Scenario: 自定义幻灯片和模板混合使用
|
||||
|
||||
- **WHEN** 演示文稿中部分幻灯片使用模板，部分为自定义
|
||||
- **THEN** 系统正确处理两种类型的幻灯片
|
||||
|
||||
### Requirement: 模板变量解析必须深度递归
|
||||
|
||||
系统 SHALL 递归解析模板元素的所有嵌套字段中的变量引用。
|
||||
|
||||
#### Scenario: 解析嵌套对象中的变量
|
||||
|
||||
- **WHEN** 模板元素定义了 `font: {size: "{font_size}", color: "{text_color}"}`
|
||||
- **THEN** 系统正确解析嵌套对象中的所有变量引用
|
||||
|
||||
#### Scenario: 解析数组中的变量
|
||||
|
||||
- **WHEN** 模板元素定义了 `box: ["{left}", 2, 8, 3]`
|
||||
- **THEN** 系统正确解析数组中的变量引用
|
||||
|
||||
#### Scenario: 解析多层嵌套的变量
|
||||
|
||||
- **WHEN** 模板包含复杂的嵌套结构，多层使用变量引用
|
||||
- **THEN** 系统递归解析所有层级的变量，直到无变量引用为止
|
||||
@@ -0,0 +1,91 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 系统必须能解析演示文稿 YAML 文件
|
||||
|
||||
系统 SHALL 能够解析包含 metadata 和 slides 的演示文稿 YAML 文件，并验证其结构的正确性。
|
||||
|
||||
#### Scenario: 解析有效的演示文稿 YAML
|
||||
|
||||
- **WHEN** 提供一个包含 `metadata` 和 `slides` 字段的 YAML 文件
|
||||
- **THEN** 系统成功解析并返回 Python 字典结构
|
||||
|
||||
#### Scenario: 检测缺少必需字段
|
||||
|
||||
- **WHEN** 提供的 YAML 文件缺少 `slides` 字段
|
||||
- **THEN** 系统抛出验证错误，明确指出缺少必需字段
|
||||
|
||||
#### Scenario: 处理无效的 YAML 语法
|
||||
|
||||
- **WHEN** 提供的文件包含无效的 YAML 语法（如缩进错误）
|
||||
- **THEN** 系统抛出解析错误，包含行号和错误描述
|
||||
|
||||
### Requirement: 系统必须验证颜色值格式
|
||||
|
||||
系统 SHALL 验证模板和演示文稿 YAML 文件中的颜色值为有效的十六进制格式。
|
||||
|
||||
#### Scenario: 验证有效的颜色值
|
||||
|
||||
- **WHEN** 模板或演示文稿 YAML 文件中包含 `color: "#4a90e2"` 的颜色值
|
||||
- **THEN** 系统接受该颜色值
|
||||
|
||||
#### Scenario: 验证颜色值格式错误
|
||||
|
||||
- **WHEN** 颜色值格式不正确（如 "blue" 或 "#xyz"）
|
||||
- **THEN** 系统抛出验证错误，提示使用 #RRGGBB 格式
|
||||
|
||||
#### Scenario: 支持短格式颜色值
|
||||
|
||||
- **WHEN** 颜色值为短格式 "#fff"
|
||||
- **THEN** 系统自动扩展为 "#ffffff" 并接受
|
||||
|
||||
### Requirement: 系统必须能解析模板 YAML 文件
|
||||
|
||||
系统 SHALL 能够解析包含 vars 定义和 elements 列表的模板 YAML 文件。
|
||||
|
||||
#### Scenario: 解析有效的模板文件
|
||||
|
||||
- **WHEN** 提供一个包含 `vars` 和 `elements` 字段的模板 YAML 文件
|
||||
- **THEN** 系统成功解析并返回模板对象
|
||||
|
||||
#### Scenario: 验证变量定义的完整性
|
||||
|
||||
- **WHEN** 模板 vars 中的变量缺少 `name` 字段
|
||||
- **THEN** 系统抛出验证错误，指出变量定义不完整
|
||||
|
||||
#### Scenario: 验证必需变量标记
|
||||
|
||||
- **WHEN** 模板 vars 中定义了 `required: true` 的变量
|
||||
- **THEN** 系统记录该变量为必需变量，在渲染时必须提供值
|
||||
|
||||
### Requirement: 系统必须支持 UTF-8 编码
|
||||
|
||||
系统 SHALL 以 UTF-8 编码读取所有 YAML 文件，支持中文等多字节字符。
|
||||
|
||||
#### Scenario: 解析包含中文的 YAML 文件
|
||||
|
||||
- **WHEN** 提供包含中文字符的 YAML 文件
|
||||
- **THEN** 系统正确解析中文内容，不出现乱码
|
||||
|
||||
#### Scenario: 处理 BOM 标记
|
||||
|
||||
- **WHEN** YAML 文件包含 UTF-8 BOM 标记
|
||||
- **THEN** 系统能够正确处理并解析文件内容
|
||||
|
||||
### Requirement: 系统必须提供清晰的错误消息
|
||||
|
||||
系统 SHALL 在 YAML 解析失败时提供包含文件路径、行号、错误原因的详细错误消息。
|
||||
|
||||
#### Scenario: YAML 语法错误的错误消息
|
||||
|
||||
- **WHEN** YAML 文件在第 10 行存在缩进错误
|
||||
- **THEN** 错误消息包含 "文件路径, 第 10 行: 缩进错误" 等信息
|
||||
|
||||
#### Scenario: 文件不存在的错误消息
|
||||
|
||||
- **WHEN** 尝试加载不存在的 YAML 文件
|
||||
- **THEN** 错误消息明确指出文件路径不存在
|
||||
|
||||
#### Scenario: 权限不足的错误消息
|
||||
|
||||
- **WHEN** YAML 文件存在但没有读取权限
|
||||
- **THEN** 错误消息提示权限不足，无法读取文件
|
||||
@@ -0,0 +1,103 @@
|
||||
## 1. 项目初始化和基础设置
|
||||
|
||||
- [x] 1.1 创建项目目录结构（themes/, templates/, presentations/, assets/, examples/）
|
||||
- [x] 1.2 创建 yaml2pptx.py 主脚本文件，添加 Inline script metadata（依赖 python-pptx, PyYAML）
|
||||
- [x] 1.3 添加基础的命令行参数解析（输入 YAML 文件路径、输出 PPTX 文件路径）
|
||||
- [x] 1.4 实现 --help 帮助信息输出
|
||||
- [x] 1.5 添加基础的日志输出函数（转换开始、进度、完成、错误）
|
||||
|
||||
## 2. YAML 解析模块实现
|
||||
|
||||
- [x] 2.1 实现通用 YAML 文件加载函数（UTF-8 编码，错误处理）
|
||||
- [x] 2.2 实现演示文稿 YAML 结构验证（必需字段：slides）
|
||||
- [x] 2.3 实现主题 YAML 结构验证（colors, fonts, spacing, defaults）
|
||||
- [x] 2.4 实现模板 YAML 结构验证（vars, elements）
|
||||
- [x] 2.5 实现颜色值格式验证（十六进制 #RRGGBB）
|
||||
- [x] 2.6 实现清晰的错误消息生成（文件路径、行号、错误原因）
|
||||
|
||||
## 3. 主题系统实现
|
||||
|
||||
- [x] 3.1 创建 Theme 类，实现主题文件加载
|
||||
- [x] 3.2 实现 Theme.resolve() 方法，支持路径解析（如 "colors.primary"）
|
||||
- [x] 3.3 实现颜色值访问（theme.colors.xxx）
|
||||
- [x] 3.4 实现字体方案访问（theme.fonts.heading, theme.fonts.sizes.xxx）
|
||||
- [x] 3.5 实现间距规则访问（theme.spacing.xxx）
|
||||
- [x] 3.6 实现默认值访问（theme.defaults.xxx）
|
||||
- [x] 3.7 实现从 themes/ 目录按名称加载主题文件
|
||||
- [x] 3.8 创建示例主题：corporate_blue.yaml（企业蓝主题）
|
||||
- [x] 3.9 创建示例主题：dark_modern.yaml（暗色现代主题）
|
||||
|
||||
## 4. 模板系统实现
|
||||
|
||||
- [x] 4.1 创建 Template 类，实现模板文件加载
|
||||
- [x] 4.2 实现变量定义解析（vars 列表，name, required, default）
|
||||
- [x] 4.3 实现变量引用解析函数（正则匹配 {xxx}）
|
||||
- [x] 4.4 实现 resolve_value() 方法，替换单个值中的变量引用
|
||||
- [x] 4.5 实现 resolve_element() 方法，递归解析元素中的所有变量
|
||||
- [x] 4.6 实现 Template.render() 方法，验证必需变量并渲染元素列表
|
||||
- [x] 4.7 实现条件渲染支持（visible 字段，简单存在性检查）
|
||||
- [x] 4.8 实现从 templates/ 目录按名称加载模板文件
|
||||
- [x] 4.9 实现模板缓存机制
|
||||
- [x] 4.10 创建示例模板：title_slide.yaml（标题页模板）
|
||||
- [x] 4.11 创建示例模板：content_slide.yaml（内容页模板）
|
||||
- [x] 4.12 创建示例模板：two_column.yaml（双栏模板）
|
||||
|
||||
## 5. 元素渲染实现
|
||||
|
||||
- [x] 5.1 实现十六进制颜色转 RGB 函数（hex_to_rgb）
|
||||
- [x] 5.2 实现文本元素渲染函数（add_text_element）
|
||||
- [x] 5.3 实现文本字体样式应用（size, bold, italic, color）
|
||||
- [x] 5.4 实现文本对齐方式应用（left, center, right）
|
||||
- [x] 5.5 实现图片元素渲染函数（add_image_element）
|
||||
- [x] 5.6 实现图片相对路径解析
|
||||
- [x] 5.7 实现图片文件存在性检查和错误提示
|
||||
- [x] 5.8 实现形状元素渲染函数（add_shape_element）
|
||||
- [x] 5.9 实现形状类型映射（rectangle, ellipse, rounded_rectangle）
|
||||
- [x] 5.10 实现形状填充色和边框样式应用
|
||||
- [x] 5.11 实现表格元素渲染函数（add_table_element）
|
||||
- [x] 5.12 实现表格数据和样式应用（字体、表头背景色、边框）
|
||||
- [x] 5.13 实现幻灯片背景设置（纯色背景）
|
||||
- [x] 5.14 实现幻灯片背景设置（图片背景，可选）
|
||||
- [x] 5.15 实现元素类型验证和错误提示
|
||||
|
||||
## 6. PPTX 生成和导出
|
||||
|
||||
- [x] 6.1 创建 Presentation 类，实现演示文稿加载
|
||||
- [x] 6.2 实现演示文稿尺寸设置（16:9, 4:3）
|
||||
- [x] 6.3 实现主题加载和关联
|
||||
- [x] 6.4 实现 render_slide() 方法，处理模板和自定义幻灯片
|
||||
- [x] 6.5 创建 PptxGenerator 类，封装 python-pptx 操作
|
||||
- [x] 6.6 实现空白幻灯片创建（使用 layout[6]）
|
||||
- [x] 6.7 实现 add_slide() 方法，添加幻灯片并渲染所有元素
|
||||
- [x] 6.8 实现按 elements 顺序渲染（控制层次）
|
||||
- [x] 6.9 实现 save() 方法，保存 PPTX 到指定路径
|
||||
- [x] 6.10 实现输出目录自动创建
|
||||
- [x] 6.11 实现主流程：加载 YAML → 渲染幻灯片 → 生成 PPTX
|
||||
|
||||
## 7. 示例和文档创建
|
||||
|
||||
- [x] 7.1 创建完整示例演示文稿：examples/demo.yaml（使用模板）
|
||||
- [x] 7.2 创建自定义幻灯片示例：examples/custom.yaml（不使用模板）
|
||||
- [ ] 7.3 准备示例图片资源（assets/images/）
|
||||
- [x] 7.4 编写 README.md，说明项目用途和使用方法
|
||||
- [ ] 7.5 编写 YAML Schema 文档（演示文稿、主题、模板的格式说明）
|
||||
- [x] 7.6 添加使用示例和命令行说明
|
||||
|
||||
## 8. 测试和验证
|
||||
|
||||
- [x] 8.1 测试基本转换：使用 demo.yaml 生成 PPTX，验证可被 PowerPoint 打开
|
||||
- [x] 8.2 测试主题系统：修改主题颜色，验证生成的 PPTX 样式变化
|
||||
- [x] 8.3 测试模板系统：创建新演示文稿使用现有模板，验证变量替换正确
|
||||
- [x] 8.4 测试所有元素类型：文本、图片、形状、表格在同一幻灯片中正常渲染
|
||||
- [ ] 8.5 测试错误处理：缺少文件、格式错误、变量未定义等场景的错误消息清晰
|
||||
- [x] 8.6 测试 UTF-8 中文支持：演示文稿包含中文内容，验证无乱码
|
||||
- [x] 8.7 测试两种幻灯片尺寸：16:9 和 4:3 比例正确生成
|
||||
- [x] 8.8 性能测试：生成包含 10+ 幻灯片的演示文稿，记录转换时间
|
||||
|
||||
## 9. 优化和完善
|
||||
|
||||
- [ ] 9.1 优化错误消息的可读性和有用性
|
||||
- [ ] 9.2 添加更多主题和模板供选择
|
||||
- [ ] 9.3 优化代码注释（中文），确保代码可读性
|
||||
- [ ] 9.4 代码重构：提取重复逻辑，提高可维护性
|
||||
- [ ] 9.5 添加 --verbose 选项，输出详细的调试信息
|
||||
8
openspec/config.yaml
Normal file
8
openspec/config.yaml
Normal file
@@ -0,0 +1,8 @@
|
||||
schema: spec-driven
|
||||
|
||||
context: |
|
||||
本项目始终面向中文开发者，使用中文进行注释、交流等内容的处理，不考虑多语言；
|
||||
本项目编写的python脚本始终使用uv运行，脚本使用Inline script metadata来指定脚本的依赖包和python运行版本；
|
||||
严禁直接使用主机环境的python直接执行脚本，严禁在主机环境直接安装python依赖包；
|
||||
本项目编写的测试文件、临时文件必须放在temp目录下；
|
||||
严禁污染主机环境的任何配置，如有需要，必须请求用户审核操作；
|
||||
186
openspec/specs/browser-preview-server/spec.md
Normal file
186
openspec/specs/browser-preview-server/spec.md
Normal file
@@ -0,0 +1,186 @@
|
||||
# Browser Preview Server
|
||||
|
||||
## Purpose
|
||||
|
||||
Browser Preview Server 负责提供浏览器实时预览功能，包括启动 Web 服务、监听 YAML 文件变化、通过 Server-Sent Events (SSE) 推送更新通知到浏览器。它是预览模式的核心组件，协调文件监听、HTML 生成和浏览器刷新的整个流程。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 系统必须支持通过命令行参数启用预览模式
|
||||
|
||||
系统 SHALL 在 `yaml2pptx.py` 中提供 `--preview` 参数，启用浏览器预览模式。
|
||||
|
||||
#### Scenario: 使用 --preview 参数启动预览服务器
|
||||
|
||||
- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml --preview`
|
||||
- **THEN** 系统启动预览服务器，而不是生成 PPTX 文件
|
||||
|
||||
#### Scenario: 不使用 --preview 参数时保持原有行为
|
||||
|
||||
- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml`
|
||||
- **THEN** 系统生成 PPTX 文件，不启动预览服务器
|
||||
|
||||
#### Scenario: --preview 参数与其他参数兼容
|
||||
|
||||
- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml --preview --template-dir templates`
|
||||
- **THEN** 系统启动预览服务器，并使用指定的模板目录
|
||||
|
||||
### Requirement: 系统必须提供 HTTP 服务
|
||||
|
||||
系统 SHALL 使用 Flask 启动 HTTP 服务器，监听指定端口，提供预览页面。
|
||||
|
||||
#### Scenario: 启动 HTTP 服务器
|
||||
|
||||
- **WHEN** 预览模式启动
|
||||
- **THEN** 系统在默认端口 5000 启动 Flask HTTP 服务器
|
||||
|
||||
#### Scenario: 自定义端口
|
||||
|
||||
- **WHEN** 用户使用 `--port 8080` 参数
|
||||
- **THEN** 系统在端口 8080 启动 HTTP 服务器
|
||||
|
||||
#### Scenario: 端口被占用时报错
|
||||
|
||||
- **WHEN** 指定的端口已被其他服务占用
|
||||
- **THEN** 系统抛出错误，提示端口被占用，建议使用 `--port` 参数指定其他端口
|
||||
|
||||
#### Scenario: 提供主页面路由
|
||||
|
||||
- **WHEN** 浏览器访问 `http://localhost:5000/`
|
||||
- **THEN** 系统返回包含所有幻灯片预览的 HTML 页面
|
||||
|
||||
### Requirement: 系统必须监听 YAML 文件变化
|
||||
|
||||
系统 SHALL 使用 watchdog 监听 YAML 文件所在目录，检测文件修改事件。
|
||||
|
||||
#### Scenario: 监听 YAML 文件修改
|
||||
|
||||
- **WHEN** 用户修改并保存 YAML 文件
|
||||
- **THEN** 系统检测到文件变化事件
|
||||
|
||||
#### Scenario: 监听模板文件修改
|
||||
|
||||
- **WHEN** 用户修改并保存模板文件（如 `templates/title_slide.yaml`）
|
||||
- **THEN** 系统检测到文件变化事件
|
||||
|
||||
#### Scenario: 忽略非 YAML 文件变化
|
||||
|
||||
- **WHEN** 用户修改其他类型的文件（如 `.txt`、`.md`）
|
||||
- **THEN** 系统不触发预览更新
|
||||
|
||||
#### Scenario: 防抖处理
|
||||
|
||||
- **WHEN** 用户在短时间内多次保存文件（如 1 秒内保存 3 次）
|
||||
- **THEN** 系统仅触发一次预览更新，避免频繁刷新
|
||||
|
||||
### Requirement: 系统必须通过 SSE 推送更新通知
|
||||
|
||||
系统 SHALL 提供 Server-Sent Events (SSE) 端点，当文件变化时推送更新通知到浏览器。
|
||||
|
||||
#### Scenario: 提供 SSE 端点
|
||||
|
||||
- **WHEN** 浏览器连接到 `http://localhost:5000/events`
|
||||
- **THEN** 系统建立 SSE 连接，保持连接打开
|
||||
|
||||
#### Scenario: 文件变化时推送更新
|
||||
|
||||
- **WHEN** 检测到 YAML 文件变化
|
||||
- **THEN** 系统通过 SSE 连接发送 `data: reload` 消息到所有连接的浏览器
|
||||
|
||||
#### Scenario: 浏览器接收更新后自动刷新
|
||||
|
||||
- **WHEN** 浏览器接收到 `reload` 消息
|
||||
- **THEN** 浏览器自动刷新页面，显示最新的预览内容
|
||||
|
||||
#### Scenario: SSE 连接断开时自动重连
|
||||
|
||||
- **WHEN** SSE 连接因网络问题断开
|
||||
- **THEN** 浏览器自动尝试重新连接到 SSE 端点
|
||||
|
||||
### Requirement: 系统必须自动打开浏览器
|
||||
|
||||
系统 SHALL 在预览服务器启动后，自动在默认浏览器中打开预览页面。
|
||||
|
||||
#### Scenario: 启动后自动打开浏览器
|
||||
|
||||
- **WHEN** 预览服务器启动成功
|
||||
- **THEN** 系统自动在默认浏览器中打开 `http://localhost:5000/`
|
||||
|
||||
#### Scenario: 浏览器打开失败时提示 URL
|
||||
|
||||
- **WHEN** 系统无法自动打开浏览器（如无图形界面环境）
|
||||
- **THEN** 系统在终端输出预览 URL，提示用户手动打开
|
||||
|
||||
### Requirement: 系统必须提供清晰的日志输出
|
||||
|
||||
系统 SHALL 在终端输出清晰的日志信息，帮助用户了解预览服务器的状态。
|
||||
|
||||
#### Scenario: 启动时输出日志
|
||||
|
||||
- **WHEN** 预览服务器启动
|
||||
- **THEN** 系统输出以下信息：
|
||||
- 正在监听的 YAML 文件路径
|
||||
- 预览服务器的 URL
|
||||
- 停止服务器的方法（按 Ctrl+C）
|
||||
|
||||
#### Scenario: 文件变化时输出日志
|
||||
|
||||
- **WHEN** 检测到文件变化
|
||||
- **THEN** 系统输出 `[INFO] 检测到文件变化: <文件路径>`
|
||||
|
||||
#### Scenario: 错误时输出日志
|
||||
|
||||
- **WHEN** 发生错误（如 YAML 解析错误）
|
||||
- **THEN** 系统输出 `[ERROR]` 级别的日志，包含错误详情
|
||||
|
||||
### Requirement: 系统必须支持优雅退出
|
||||
|
||||
系统 SHALL 支持通过 Ctrl+C 优雅地停止预览服务器。
|
||||
|
||||
#### Scenario: 按 Ctrl+C 停止服务器
|
||||
|
||||
- **WHEN** 用户按下 Ctrl+C
|
||||
- **THEN** 系统停止文件监听和 HTTP 服务器，输出 `[INFO] 已停止`，然后退出
|
||||
|
||||
#### Scenario: 停止时清理资源
|
||||
|
||||
- **WHEN** 服务器停止
|
||||
- **THEN** 系统关闭所有 SSE 连接，停止 watchdog 监听器，释放端口
|
||||
|
||||
### Requirement: 系统必须处理 YAML 解析错误
|
||||
|
||||
系统 SHALL 在 YAML 解析失败时，在预览页面显示友好的错误信息，而不是崩溃。
|
||||
|
||||
#### Scenario: YAML 语法错误时显示错误页面
|
||||
|
||||
- **WHEN** YAML 文件存在语法错误（如缺少冒号、缩进错误）
|
||||
- **THEN** 系统在预览页面显示错误信息，包括错误类型和行号
|
||||
|
||||
#### Scenario: 错误修复后自动恢复
|
||||
|
||||
- **WHEN** 用户修复 YAML 错误并保存
|
||||
- **THEN** 系统检测到文件变化，重新解析 YAML，显示正常的预览内容
|
||||
|
||||
#### Scenario: 错误页面仍然监听文件变化
|
||||
|
||||
- **WHEN** 预览页面显示错误信息
|
||||
- **THEN** 系统继续监听文件变化，等待用户修复错误
|
||||
|
||||
### Requirement: 系统必须支持多幻灯片预览
|
||||
|
||||
系统 SHALL 在预览页面中显示所有幻灯片，支持用户查看完整的演示文稿。
|
||||
|
||||
#### Scenario: 垂直排列显示所有幻灯片
|
||||
|
||||
- **WHEN** YAML 文件包含多个幻灯片
|
||||
- **THEN** 系统在预览页面中垂直排列显示所有幻灯片，每个幻灯片之间有间距
|
||||
|
||||
#### Scenario: 显示幻灯片编号
|
||||
|
||||
- **WHEN** 预览页面显示幻灯片
|
||||
- **THEN** 每个幻灯片右下角显示编号（如 "幻灯片 1"、"幻灯片 2"）
|
||||
|
||||
#### Scenario: 幻灯片尺寸一致
|
||||
|
||||
- **WHEN** 预览页面显示多个幻灯片
|
||||
- **THEN** 所有幻灯片使用相同的尺寸（960x540 像素，16:9 比例）
|
||||
174
openspec/specs/element-rendering/spec.md
Normal file
174
openspec/specs/element-rendering/spec.md
Normal file
@@ -0,0 +1,174 @@
|
||||
# Element Rendering
|
||||
|
||||
## Purpose
|
||||
|
||||
Element rendering系统负责将 YAML 中定义的各类元素（文本、图片、形状、表格）转换为 PPTX 文档中的实际对象。它处理元素的定位、样式应用、层次管理，以及幻灯片背景设置。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 系统必须支持文本元素渲染
|
||||
|
||||
系统 SHALL 将 YAML 中定义的文本元素渲染为 PPTX 文本框。
|
||||
|
||||
#### Scenario: 渲染基本文本元素
|
||||
|
||||
- **WHEN** 元素定义为 `{type: text, content: "Hello", box: [1, 2, 8, 3]}`
|
||||
- **THEN** 系统在幻灯片的 (1, 2) 位置创建 8×3 英寸的文本框，内容为 "Hello"
|
||||
|
||||
#### Scenario: 应用文本字体样式
|
||||
|
||||
- **WHEN** 文本元素定义了 `font: {size: 32, bold: true, color: "#333333"}`
|
||||
- **THEN** 系统将文本设置为 32pt、粗体、颜色为 #333333
|
||||
|
||||
#### Scenario: 应用文本对齐方式
|
||||
|
||||
- **WHEN** 文本元素定义了 `font: {align: center}`
|
||||
- **THEN** 系统将文本设置为居中对齐
|
||||
|
||||
#### Scenario: 支持多种对齐方式
|
||||
|
||||
- **WHEN** 文本对齐方式为 `left`、`center`、`right` 之一
|
||||
- **THEN** 系统正确应用对应的对齐方式
|
||||
|
||||
### Requirement: 系统必须支持图片元素渲染
|
||||
|
||||
系统 SHALL 将 YAML 中定义的图片元素渲染为 PPTX 图片对象。
|
||||
|
||||
#### Scenario: 渲染本地图片
|
||||
|
||||
- **WHEN** 元素定义为 `{type: image, src: "images/logo.png", box: [2, 3, 4, 3]}`
|
||||
- **THEN** 系统从指定路径加载图片，在 (2, 3) 位置渲染为 4×3 英寸大小
|
||||
|
||||
#### Scenario: 图片文件不存在时报错
|
||||
|
||||
- **WHEN** 图片 src 指向不存在的文件路径
|
||||
- **THEN** 系统抛出错误，明确指出图片文件未找到
|
||||
|
||||
#### Scenario: 图片格式不支持时报错
|
||||
|
||||
- **WHEN** 图片文件格式不被 python-pptx 支持
|
||||
- **THEN** 系统抛出错误，提示图片格式不支持，并列出支持的格式
|
||||
|
||||
#### Scenario: 相对路径处理
|
||||
|
||||
- **WHEN** 图片 src 使用相对路径 `"assets/images/logo.png"`
|
||||
- **THEN** 系统基于演示文稿文件所在目录解析相对路径
|
||||
|
||||
### Requirement: 系统必须支持形状元素渲染
|
||||
|
||||
系统 SHALL 将 YAML 中定义的形状元素渲染为 PPTX 形状对象。
|
||||
|
||||
#### Scenario: 渲染矩形形状
|
||||
|
||||
- **WHEN** 元素定义为 `{type: shape, shape: rectangle, box: [1, 2, 3, 1], fill: "#4a90e2"}`
|
||||
- **THEN** 系统在 (1, 2) 位置创建 3×1 英寸的矩形，填充颜色为 #4a90e2
|
||||
|
||||
#### Scenario: 渲染圆形形状
|
||||
|
||||
- **WHEN** 元素的 `shape` 字段为 `ellipse`
|
||||
- **THEN** 系统渲染椭圆/圆形形状
|
||||
|
||||
#### Scenario: 渲染圆角矩形
|
||||
|
||||
- **WHEN** 元素的 `shape` 字段为 `rounded_rectangle`
|
||||
- **THEN** 系统渲染圆角矩形形状
|
||||
|
||||
#### Scenario: 应用形状边框样式
|
||||
|
||||
- **WHEN** 形状定义了 `line: {color: "#000000", width: 2}`
|
||||
- **THEN** 系统为形状添加黑色、2pt 宽度的边框
|
||||
|
||||
### Requirement: 系统必须支持表格元素渲染
|
||||
|
||||
系统 SHALL 将 YAML 中定义的表格元素渲染为 PPTX 表格对象。
|
||||
|
||||
#### Scenario: 渲染基本表格
|
||||
|
||||
- **WHEN** 元素定义为 `{type: table, position: [1, 2], data: [["A", "B"], ["C", "D"]], col_widths: [2, 2]}`
|
||||
- **THEN** 系统在 (1, 2) 位置创建 2×2 表格，列宽各为 2 英寸
|
||||
|
||||
#### Scenario: 应用表格样式
|
||||
|
||||
- **WHEN** 表格定义了 `style: {font_size: 14, header_bg: "#4a90e2", header_color: "#ffffff"}`
|
||||
- **THEN** 系统将第一行设置为表头样式，背景色为 #4a90e2，文字颜色为白色
|
||||
|
||||
#### Scenario: 表格数据为空时报错
|
||||
|
||||
- **WHEN** 表格的 `data` 字段为空数组
|
||||
- **THEN** 系统抛出错误，提示表格数据不能为空
|
||||
|
||||
#### Scenario: 表格列宽不匹配时报错
|
||||
|
||||
- **WHEN** `col_widths` 数组长度与表格列数不一致
|
||||
- **THEN** 系统抛出错误，要求列宽数量与列数匹配
|
||||
|
||||
### Requirement: 元素位置必须使用英寸单位
|
||||
|
||||
系统 SHALL 将元素的 box 或 position 字段中的数值解释为英寸单位。
|
||||
|
||||
#### Scenario: box 数组表示位置和尺寸
|
||||
|
||||
- **WHEN** 元素定义了 `box: [1, 2, 8, 3]`
|
||||
- **THEN** 系统将其解释为 x=1英寸, y=2英寸, width=8英寸, height=3英寸
|
||||
|
||||
#### Scenario: position 数组表示位置
|
||||
|
||||
- **WHEN** 表格元素定义了 `position: [1, 2]`
|
||||
- **THEN** 系统将其解释为 x=1英寸, y=2英寸
|
||||
|
||||
#### Scenario: 负数坐标值报错
|
||||
|
||||
- **WHEN** box 或 position 包含负数值
|
||||
- **THEN** 系统抛出错误，要求坐标值必须为非负数
|
||||
|
||||
### Requirement: 系统必须支持幻灯片背景设置
|
||||
|
||||
系统 SHALL 支持为幻灯片设置纯色背景或图片背景。
|
||||
|
||||
#### Scenario: 设置纯色背景
|
||||
|
||||
- **WHEN** 幻灯片定义了 `background: {color: "#ffffff"}`
|
||||
- **THEN** 系统将幻灯片背景设置为白色
|
||||
|
||||
#### Scenario: 设置图片背景
|
||||
|
||||
- **WHEN** 幻灯片定义了 `background: {image: "bg.png"}`
|
||||
- **THEN** 系统使用指定图片作为幻灯片背景
|
||||
|
||||
#### Scenario: 背景图片不存在时报错
|
||||
|
||||
- **WHEN** 背景图片路径不存在
|
||||
- **THEN** 系统抛出错误，提示背景图片文件未找到
|
||||
|
||||
### Requirement: 系统必须处理元素重叠和层次
|
||||
|
||||
系统 SHALL 按照元素在 elements 列表中的顺序渲染，后定义的元素显示在前面元素之上。
|
||||
|
||||
#### Scenario: 元素按定义顺序渲染
|
||||
|
||||
- **WHEN** elements 列表为 `[shape1, text1, image1]`
|
||||
- **THEN** 系统先渲染 shape1，再渲染 text1，最后渲染 image1（image1 在最上层）
|
||||
|
||||
#### Scenario: 重叠元素的显示层次
|
||||
|
||||
- **WHEN** 两个元素的位置有重叠
|
||||
- **THEN** 后定义的元素遮盖先定义的元素
|
||||
|
||||
### Requirement: 系统必须验证元素类型
|
||||
|
||||
系统 SHALL 验证每个元素的 type 字段，仅支持已定义的元素类型。
|
||||
|
||||
#### Scenario: 支持的元素类型
|
||||
|
||||
- **WHEN** 元素的 `type` 为 `text`、`image`、`shape`、`table` 之一
|
||||
- **THEN** 系统正常渲染该元素
|
||||
|
||||
#### Scenario: 不支持的元素类型报错
|
||||
|
||||
- **WHEN** 元素的 `type` 为未定义的值（如 "video"）
|
||||
- **THEN** 系统抛出错误，提示不支持该元素类型，并列出支持的类型
|
||||
|
||||
#### Scenario: 缺少 type 字段报错
|
||||
|
||||
- **WHEN** 元素未定义 `type` 字段
|
||||
- **THEN** 系统抛出错误，要求每个元素必须包含 type 字段
|
||||
231
openspec/specs/html-rendering/spec.md
Normal file
231
openspec/specs/html-rendering/spec.md
Normal file
@@ -0,0 +1,231 @@
|
||||
# HTML Rendering
|
||||
|
||||
## Purpose
|
||||
|
||||
HTML Rendering 系统负责将 YAML 中定义的各类元素（文本、图片、形状、表格）转换为 HTML/CSS 代码，在浏览器中显示。它复用现有的 YAML 解析和模板渲染逻辑，但将输出目标从 PPTX 改为 HTML/CSS，提供快速的预览体验。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 系统必须将 YAML 元素转换为 HTML
|
||||
|
||||
系统 SHALL 将解析后的 YAML 元素转换为 HTML 代码，在浏览器中渲染。
|
||||
|
||||
#### Scenario: 生成完整的 HTML 页面
|
||||
|
||||
- **WHEN** 浏览器请求预览页面
|
||||
- **THEN** 系统生成包含 HTML、CSS 和 JavaScript 的完整页面
|
||||
|
||||
#### Scenario: 动态生成 HTML
|
||||
|
||||
- **WHEN** YAML 文件变化
|
||||
- **THEN** 系统重新解析 YAML，动态生成新的 HTML 内容，无需生成中间文件
|
||||
|
||||
#### Scenario: HTML 页面包含 SSE 客户端代码
|
||||
|
||||
- **WHEN** 生成 HTML 页面
|
||||
- **THEN** 页面包含 JavaScript 代码，连接到 SSE 端点，监听更新事件
|
||||
|
||||
### Requirement: 系统必须使用固定 DPI 进行单位转换
|
||||
|
||||
系统 SHALL 使用固定 DPI (96) 将 YAML 中的英寸单位转换为 CSS 像素单位。
|
||||
|
||||
#### Scenario: 英寸转换为像素
|
||||
|
||||
- **WHEN** 元素定义 `box: [1, 2, 8, 3]`（单位为英寸）
|
||||
- **THEN** 系统转换为 CSS：`left: 96px; top: 192px; width: 768px; height: 288px`
|
||||
|
||||
#### Scenario: 幻灯片尺寸固定
|
||||
|
||||
- **WHEN** 渲染 16:9 幻灯片
|
||||
- **THEN** 系统使用固定尺寸 960x540 像素（10 英寸 x 5.625 英寸 x 96 DPI）
|
||||
|
||||
#### Scenario: 4:3 幻灯片尺寸
|
||||
|
||||
- **WHEN** 渲染 4:3 幻灯片
|
||||
- **THEN** 系统使用固定尺寸 960x720 像素（10 英寸 x 7.5 英寸 x 96 DPI）
|
||||
|
||||
### Requirement: 系统必须渲染文本元素
|
||||
|
||||
系统 SHALL 将 YAML 中的文本元素转换为 HTML `<div>` 标签，应用相应的样式。
|
||||
|
||||
#### Scenario: 渲染基本文本元素
|
||||
|
||||
- **WHEN** 元素定义为 `{type: text, content: "Hello", box: [1, 2, 8, 3]}`
|
||||
- **THEN** 系统生成 `<div>` 标签，内容为 "Hello"，位置为 (96px, 192px)，尺寸为 768x288 像素
|
||||
|
||||
#### Scenario: 应用文本字体样式
|
||||
|
||||
- **WHEN** 文本元素定义了 `font: {size: 32, bold: true, color: "#333333"}`
|
||||
- **THEN** 系统应用 CSS：`font-size: 32pt; font-weight: bold; color: #333333`
|
||||
|
||||
#### Scenario: 应用文本对齐方式
|
||||
|
||||
- **WHEN** 文本元素定义了 `font: {align: center}`
|
||||
- **THEN** 系统应用 CSS：`text-align: center`
|
||||
|
||||
#### Scenario: 支持多行文本
|
||||
|
||||
- **WHEN** 文本内容包含换行符（`\n`）
|
||||
- **THEN** 系统使用 `white-space: pre-wrap` 保留换行
|
||||
|
||||
#### Scenario: 使用 pt 单位表示字体大小
|
||||
|
||||
- **WHEN** 文本字体大小为 44
|
||||
- **THEN** 系统使用 CSS：`font-size: 44pt`（与 PPTX 保持一致）
|
||||
|
||||
### Requirement: 系统必须渲染形状元素
|
||||
|
||||
系统 SHALL 将 YAML 中的形状元素转换为 HTML `<div>` 标签，使用 CSS 样式模拟形状。
|
||||
|
||||
#### Scenario: 渲染矩形形状
|
||||
|
||||
- **WHEN** 元素定义为 `{type: shape, shape: rectangle, box: [1, 2, 3, 1], fill: "#4a90e2"}`
|
||||
- **THEN** 系统生成 `<div>` 标签，背景色为 #4a90e2，`border-radius: 0`
|
||||
|
||||
#### Scenario: 渲染圆形形状
|
||||
|
||||
- **WHEN** 元素的 `shape` 字段为 `ellipse`
|
||||
- **THEN** 系统应用 CSS：`border-radius: 50%`
|
||||
|
||||
#### Scenario: 渲染圆角矩形
|
||||
|
||||
- **WHEN** 元素的 `shape` 字段为 `rounded_rectangle`
|
||||
- **THEN** 系统应用 CSS：`border-radius: 8px`
|
||||
|
||||
#### Scenario: 应用形状边框样式
|
||||
|
||||
- **WHEN** 形状定义了 `line: {color: "#000000", width: 2}`
|
||||
- **THEN** 系统应用 CSS：`border: 2pt solid #000000`
|
||||
|
||||
#### Scenario: 形状无填充色时透明
|
||||
|
||||
- **WHEN** 形状未定义 `fill` 字段
|
||||
- **THEN** 系统应用 CSS：`background: transparent`
|
||||
|
||||
### Requirement: 系统必须渲染表格元素
|
||||
|
||||
系统 SHALL 将 YAML 中的表格元素转换为 HTML `<table>` 标签。
|
||||
|
||||
#### Scenario: 渲染基本表格
|
||||
|
||||
- **WHEN** 元素定义为 `{type: table, position: [1, 2], data: [["A", "B"], ["C", "D"]], col_widths: [2, 2]}`
|
||||
- **THEN** 系统生成 `<table>` 标签，位置为 (96px, 192px)，包含 2 行 2 列
|
||||
|
||||
#### Scenario: 应用表格样式
|
||||
|
||||
- **WHEN** 表格定义了 `style: {font_size: 14, header_bg: "#4a90e2", header_color: "#ffffff"}`
|
||||
- **THEN** 系统将第一行设置为表头样式，背景色为 #4a90e2，文字颜色为白色，字体大小为 14pt
|
||||
|
||||
#### Scenario: 表格单元格边框
|
||||
|
||||
- **WHEN** 渲染表格
|
||||
- **THEN** 系统为所有单元格添加边框：`border: 1px solid #ddd`
|
||||
|
||||
#### Scenario: 表格单元格内边距
|
||||
|
||||
- **WHEN** 渲染表格
|
||||
- **THEN** 系统为所有单元格添加内边距：`padding: 8px`
|
||||
|
||||
### Requirement: 系统必须渲染图片元素
|
||||
|
||||
系统 SHALL 将 YAML 中的图片元素转换为 HTML `<img>` 标签。
|
||||
|
||||
#### Scenario: 渲染本地图片
|
||||
|
||||
- **WHEN** 元素定义为 `{type: image, src: "images/logo.png", box: [2, 3, 4, 3]}`
|
||||
- **THEN** 系统生成 `<img>` 标签，src 为图片的文件路径，位置为 (192px, 288px)，尺寸为 384x288 像素
|
||||
|
||||
#### Scenario: 处理相对路径
|
||||
|
||||
- **WHEN** 图片 src 使用相对路径 `"assets/logo.png"`
|
||||
- **THEN** 系统基于 YAML 文件所在目录解析相对路径
|
||||
|
||||
#### Scenario: 图片不存在时显示占位符
|
||||
|
||||
- **WHEN** 图片文件不存在
|
||||
- **THEN** 系统显示占位符或错误提示，而不是崩溃
|
||||
|
||||
### Requirement: 系统必须渲染幻灯片背景
|
||||
|
||||
系统 SHALL 支持为幻灯片设置纯色背景。
|
||||
|
||||
#### Scenario: 设置纯色背景
|
||||
|
||||
- **WHEN** 幻灯片定义了 `background: {color: "#ffffff"}`
|
||||
- **THEN** 系统为幻灯片容器应用 CSS：`background: #ffffff`
|
||||
|
||||
#### Scenario: 无背景时使用白色
|
||||
|
||||
- **WHEN** 幻灯片未定义 `background` 字段
|
||||
- **THEN** 系统使用默认白色背景
|
||||
|
||||
### Requirement: 系统必须使用绝对定位
|
||||
|
||||
系统 SHALL 使用 CSS 绝对定位（`position: absolute`）渲染所有元素，模拟 PPTX 的坐标系统。
|
||||
|
||||
#### Scenario: 元素使用绝对定位
|
||||
|
||||
- **WHEN** 渲染任何元素
|
||||
- **THEN** 系统应用 CSS：`position: absolute`
|
||||
|
||||
#### Scenario: 幻灯片容器使用相对定位
|
||||
|
||||
- **WHEN** 渲染幻灯片容器
|
||||
- **THEN** 系统应用 CSS：`position: relative`，作为元素的定位上下文
|
||||
|
||||
#### Scenario: 元素层次按定义顺序
|
||||
|
||||
- **WHEN** elements 列表为 `[shape1, text1, image1]`
|
||||
- **THEN** 系统按顺序渲染，后定义的元素显示在前面元素之上（通过 DOM 顺序控制）
|
||||
|
||||
### Requirement: 系统必须提供视觉反馈
|
||||
|
||||
系统 SHALL 在预览页面中提供视觉反馈，帮助用户了解预览状态。
|
||||
|
||||
#### Scenario: 幻灯片添加阴影效果
|
||||
|
||||
- **WHEN** 渲染幻灯片
|
||||
- **THEN** 系统为幻灯片容器添加阴影：`box-shadow: 0 2px 8px rgba(0,0,0,0.1)`
|
||||
|
||||
#### Scenario: 幻灯片之间有间距
|
||||
|
||||
- **WHEN** 渲染多个幻灯片
|
||||
- **THEN** 每个幻灯片之间有 20px 的垂直间距
|
||||
|
||||
### Requirement: 系统必须复用现有的解析逻辑
|
||||
|
||||
系统 SHALL 复用 `yaml2pptx.py` 中现有的 `Presentation` 类和模板渲染逻辑。
|
||||
|
||||
#### Scenario: 使用 Presentation 类解析 YAML
|
||||
|
||||
- **WHEN** 预览模式启动
|
||||
- **THEN** 系统使用 `Presentation` 类加载和解析 YAML 文件
|
||||
|
||||
#### Scenario: 使用 render_slide 方法渲染幻灯片
|
||||
|
||||
- **WHEN** 生成预览 HTML
|
||||
- **THEN** 系统调用 `Presentation.render_slide()` 方法获取渲染后的幻灯片数据
|
||||
|
||||
#### Scenario: 支持模板系统
|
||||
|
||||
- **WHEN** YAML 文件使用模板（如 `template: title_slide`）
|
||||
- **THEN** 系统正确解析模板变量，渲染模板元素
|
||||
|
||||
### Requirement: 系统必须处理渲染错误
|
||||
|
||||
系统 SHALL 在元素渲染失败时，显示错误信息，而不是崩溃。
|
||||
|
||||
#### Scenario: 元素类型不支持时显示错误
|
||||
|
||||
- **WHEN** 元素的 `type` 为未定义的值（如 "video"）
|
||||
- **THEN** 系统在预览页面显示错误信息，提示不支持该元素类型
|
||||
|
||||
#### Scenario: 元素缺少必需字段时显示错误
|
||||
|
||||
- **WHEN** 元素缺少必需字段（如文本元素缺少 `content`）
|
||||
- **THEN** 系统在预览页面显示错误信息，提示缺少字段
|
||||
|
||||
#### Scenario: 部分元素错误不影响其他元素
|
||||
|
||||
- **WHEN** 某个元素渲染失败
|
||||
- **THEN** 系统继续渲染其他元素，仅在失败位置显示错误提示
|
||||
221
openspec/specs/pptx-generation/spec.md
Normal file
221
openspec/specs/pptx-generation/spec.md
Normal file
@@ -0,0 +1,221 @@
|
||||
# PPTX Generation
|
||||
|
||||
## Purpose
|
||||
|
||||
PPTX generation 系统负责使用 python-pptx 库创建符合 OOXML 标准的 PowerPoint 文档。它管理演示文稿的整体属性（如尺寸），按顺序添加幻灯片，并提供命令行接口供用户使用。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 系统必须创建符合 OOXML 标准的 PPTX 文件
|
||||
|
||||
系统 SHALL 使用 python-pptx 库生成符合 Office Open XML (OOXML) 标准的 .pptx 文件。
|
||||
|
||||
#### Scenario: 生成的 PPTX 文件可被 PowerPoint 打开
|
||||
|
||||
- **WHEN** 系统生成 PPTX 文件
|
||||
- **THEN** 该文件可被 Microsoft PowerPoint 正常打开和编辑
|
||||
|
||||
#### Scenario: 生成的 PPTX 文件可被其他软件打开
|
||||
|
||||
- **WHEN** 系统生成 PPTX 文件
|
||||
- **THEN** 该文件可被 LibreOffice Impress、Google Slides 等软件正常打开
|
||||
|
||||
#### Scenario: PPTX 文件扩展名正确
|
||||
|
||||
- **WHEN** 系统保存演示文稿
|
||||
- **THEN** 输出文件的扩展名为 `.pptx`
|
||||
|
||||
### Requirement: 系统必须支持设置演示文稿尺寸
|
||||
|
||||
系统 SHALL 支持设置演示文稿的幻灯片尺寸，支持 16:9 和 4:3 两种标准比例。
|
||||
|
||||
#### Scenario: 创建 16:9 比例的演示文稿
|
||||
|
||||
- **WHEN** metadata 中指定 `size: "16:9"`
|
||||
- **THEN** 系统创建 10×5.625 英寸的幻灯片
|
||||
|
||||
#### Scenario: 创建 4:3 比例的演示文稿
|
||||
|
||||
- **WHEN** metadata 中指定 `size: "4:3"`
|
||||
- **THEN** 系统创建 10×7.5 英寸的幻灯片
|
||||
|
||||
#### Scenario: 默认使用 16:9 比例
|
||||
|
||||
- **WHEN** metadata 中未指定 size 字段
|
||||
- **THEN** 系统默认使用 16:9 比例
|
||||
|
||||
#### Scenario: 不支持的尺寸比例报错
|
||||
|
||||
- **WHEN** metadata 中指定了不支持的尺寸比例（如 "21:9"）
|
||||
- **THEN** 系统抛出错误，提示仅支持 16:9 和 4:3
|
||||
|
||||
### Requirement: 系统必须按顺序添加幻灯片
|
||||
|
||||
系统 SHALL 按照 YAML 中 slides 列表的顺序，依次添加幻灯片到 PPTX 文件。
|
||||
|
||||
#### Scenario: 幻灯片顺序与 YAML 一致
|
||||
|
||||
- **WHEN** YAML 中 slides 列表为 `[slide1, slide2, slide3]`
|
||||
- **THEN** 生成的 PPTX 文件中，幻灯片顺序为 slide1、slide2、slide3
|
||||
|
||||
#### Scenario: 空幻灯片列表生成空演示文稿
|
||||
|
||||
- **WHEN** YAML 中 slides 列表为空
|
||||
- **THEN** 系统生成一个不包含任何幻灯片的 PPTX 文件（或抛出警告）
|
||||
|
||||
### Requirement: 系统必须使用空白布局
|
||||
|
||||
系统 SHALL 为每个幻灯片使用空白布局（blank layout），以便完全自定义内容。
|
||||
|
||||
#### Scenario: 使用空白布局添加幻灯片
|
||||
|
||||
- **WHEN** 系统添加幻灯片
|
||||
- **THEN** 使用 `prs.slide_layouts[6]`（空白布局）而非预定义布局
|
||||
|
||||
#### Scenario: 空白幻灯片不包含占位符
|
||||
|
||||
- **WHEN** 创建新的空白幻灯片
|
||||
- **THEN** 幻灯片不包含任何预定义的标题或内容占位符
|
||||
|
||||
### Requirement: 系统必须保存到指定路径
|
||||
|
||||
系统 SHALL 将生成的 PPTX 文件保存到用户指定的路径。
|
||||
|
||||
#### Scenario: 保存到指定文件路径
|
||||
|
||||
- **WHEN** 用户指定输出路径为 `output/presentation.pptx`
|
||||
- **THEN** 系统将 PPTX 文件保存到该路径
|
||||
|
||||
#### Scenario: 自动创建输出目录
|
||||
|
||||
- **WHEN** 输出路径包含不存在的目录（如 `output/subdir/file.pptx`）
|
||||
- **THEN** 系统自动创建所需的目录结构
|
||||
|
||||
#### Scenario: 输出路径已存在时覆盖
|
||||
|
||||
- **WHEN** 指定的输出文件路径已存在
|
||||
- **THEN** 系统覆盖原有文件（或提供选项询问用户）
|
||||
|
||||
#### Scenario: 无写入权限时报错
|
||||
|
||||
- **WHEN** 输出路径没有写入权限
|
||||
- **THEN** 系统抛出错误，提示权限不足
|
||||
|
||||
### Requirement: 系统必须使用 python-pptx 的单位转换函数
|
||||
|
||||
系统 SHALL 使用 python-pptx 提供的 Inches() 函数将英寸值转换为 EMU（English Metric Units）。
|
||||
|
||||
#### Scenario: 使用 Inches() 转换坐标
|
||||
|
||||
- **WHEN** 元素 box 定义为 `[1, 2, 8, 3]`
|
||||
- **THEN** 系统调用 `Inches(1)`, `Inches(2)`, `Inches(8)`, `Inches(3)` 转换为 EMU
|
||||
|
||||
#### Scenario: EMU 转换的精度
|
||||
|
||||
- **WHEN** 使用 Inches(1.0)
|
||||
- **THEN** 返回值为 914400 EMU（1 英寸 = 914400 EMU）
|
||||
|
||||
### Requirement: 系统必须处理颜色转换
|
||||
|
||||
系统 SHALL 将十六进制颜色值（如 "#4a90e2"）转换为 python-pptx 的 RGBColor 对象。
|
||||
|
||||
#### Scenario: 十六进制颜色转 RGB
|
||||
|
||||
- **WHEN** 颜色值为 "#4a90e2"
|
||||
- **THEN** 系统转换为 RGBColor(74, 144, 226)
|
||||
|
||||
#### Scenario: 短格式十六进制颜色
|
||||
|
||||
- **WHEN** 颜色值为 "#fff"（短格式）
|
||||
- **THEN** 系统扩展为 "#ffffff" 并转换为 RGBColor(255, 255, 255)
|
||||
|
||||
#### Scenario: 无效颜色格式报错
|
||||
|
||||
- **WHEN** 颜色值不是有效的十六进制格式
|
||||
- **THEN** 系统抛出错误，提示颜色格式无效
|
||||
|
||||
### Requirement: 系统必须使用 uv 运行 Python 脚本
|
||||
|
||||
系统 SHALL 使用 uv 运行转换脚本，通过 Inline script metadata 指定依赖。
|
||||
|
||||
#### Scenario: 脚本包含 Inline script metadata
|
||||
|
||||
- **WHEN** 查看 `yaml2pptx.py` 文件头部
|
||||
- **THEN** 包含 `# /// script` 块，定义 python-pptx 和 PyYAML 依赖
|
||||
|
||||
#### Scenario: 使用 uv 运行脚本
|
||||
|
||||
- **WHEN** 执行转换命令
|
||||
- **THEN** 使用 `uv run yaml2pptx.py` 而非 `python yaml2pptx.py`
|
||||
|
||||
#### Scenario: 禁止直接安装依赖
|
||||
|
||||
- **WHEN** 需要使用 python-pptx 或 PyYAML
|
||||
- **THEN** 不使用 `pip install`，而是在 script metadata 中声明依赖
|
||||
|
||||
### Requirement: 系统架构保持简洁
|
||||
|
||||
系统 SHALL 采用两层架构（模板 + 演示文稿），颜色和样式直接在模板中定义。
|
||||
|
||||
#### Scenario: 模板自包含样式
|
||||
|
||||
- **WHEN** 查看模板文件
|
||||
- **THEN** 颜色值直接以十六进制格式指定（如 "#4a90e2"）
|
||||
|
||||
#### Scenario: 无需主题配置
|
||||
|
||||
- **WHEN** 创建新的演示文稿
|
||||
- **THEN** metadata 中不需要指定 theme 字段
|
||||
|
||||
#### Scenario: 模板独立配色
|
||||
|
||||
- **WHEN** 创建新模板
|
||||
- **THEN** 可以为该模板定义独立的颜色方案，不受其他模板影响
|
||||
|
||||
### Requirement: 系统必须提供命令行接口
|
||||
|
||||
系统 SHALL 提供命令行接口，接受输入 YAML 文件路径和输出 PPTX 文件路径。
|
||||
|
||||
#### Scenario: 基本命令行使用
|
||||
|
||||
- **WHEN** 执行 `uv run yaml2pptx.py input.yaml output.pptx`
|
||||
- **THEN** 系统读取 input.yaml，生成 output.pptx
|
||||
|
||||
#### Scenario: 仅提供输入文件时自动命名输出
|
||||
|
||||
- **WHEN** 执行 `uv run yaml2pptx.py input.yaml`
|
||||
- **THEN** 系统自动生成输出文件名为 `input.pptx`
|
||||
|
||||
#### Scenario: 显示帮助信息
|
||||
|
||||
- **WHEN** 执行 `uv run yaml2pptx.py --help`
|
||||
- **THEN** 系统显示使用说明和参数列表
|
||||
|
||||
#### Scenario: 输入文件不存在时报错
|
||||
|
||||
- **WHEN** 提供的输入文件路径不存在
|
||||
- **THEN** 系统抛出错误，提示输入文件未找到
|
||||
|
||||
### Requirement: 系统必须报告转换进度
|
||||
|
||||
系统 SHALL 在转换过程中输出进度信息，包括当前处理的幻灯片数量。
|
||||
|
||||
#### Scenario: 输出转换开始信息
|
||||
|
||||
- **WHEN** 开始转换
|
||||
- **THEN** 系统输出 "开始转换: input.yaml"
|
||||
|
||||
#### Scenario: 输出幻灯片处理进度
|
||||
|
||||
- **WHEN** 处理每个幻灯片
|
||||
- **THEN** 系统输出 "处理幻灯片 N/M"
|
||||
|
||||
#### Scenario: 输出转换完成信息
|
||||
|
||||
- **WHEN** 转换成功完成
|
||||
- **THEN** 系统输出 "转换完成: output.pptx"
|
||||
|
||||
#### Scenario: 转换失败时输出错误
|
||||
|
||||
- **WHEN** 转换过程中发生错误
|
||||
- **THEN** 系统输出详细的错误信息和堆栈跟踪（调试模式下）
|
||||
83
openspec/specs/template-directory-cli/spec.md
Normal file
83
openspec/specs/template-directory-cli/spec.md
Normal file
@@ -0,0 +1,83 @@
|
||||
# Template Directory CLI
|
||||
|
||||
## Purpose
|
||||
|
||||
提供命令行参数支持，允许用户通过 `--template-dir` 参数明确指定模板文件目录，使脚本可以在任何位置运行而不依赖特定的目录结构。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 系统必须支持 --template-dir 命令行参数
|
||||
|
||||
系统 SHALL 提供 `--template-dir` 命令行参数，允许用户指定模板文件目录的路径。
|
||||
|
||||
#### Scenario: 指定绝对路径的模板目录
|
||||
|
||||
- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml --template-dir /path/to/templates`
|
||||
- **THEN** 系统使用 `/path/to/templates` 作为模板目录
|
||||
|
||||
#### Scenario: 指定相对路径的模板目录
|
||||
|
||||
- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml --template-dir ./templates`
|
||||
- **THEN** 系统将相对路径解析为相对于当前工作目录（CWD）的绝对路径
|
||||
|
||||
#### Scenario: Windows 路径格式支持
|
||||
|
||||
- **WHEN** Windows 用户运行 `uv run yaml2pptx.py input.yaml --template-dir C:\Users\me\templates`
|
||||
- **THEN** 系统正确解析 Windows 路径格式
|
||||
|
||||
#### Scenario: 不指定 template-dir 参数且不使用模板
|
||||
|
||||
- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml`，且 YAML 文件中所有幻灯片都是自定义幻灯片（不使用模板）
|
||||
- **THEN** 系统正常处理，不报错
|
||||
|
||||
### Requirement: 使用模板时必须指定 template-dir
|
||||
|
||||
系统 SHALL 在 YAML 文件中使用了模板但未指定 `--template-dir` 参数时报错。
|
||||
|
||||
#### Scenario: 使用模板但未指定 template-dir
|
||||
|
||||
- **WHEN** YAML 文件中包含 `template: title-slide`，但用户未提供 `--template-dir` 参数
|
||||
- **THEN** 系统抛出错误，提示"未指定模板目录，无法加载模板: title-slide"，并建议使用 `--template-dir` 参数
|
||||
|
||||
#### Scenario: 错误信息包含使用示例
|
||||
|
||||
- **WHEN** 系统因未指定 template-dir 而报错
|
||||
- **THEN** 错误信息中包含"请使用 --template-dir 参数指定模板目录"的提示
|
||||
|
||||
### Requirement: 系统必须支持跨平台路径处理
|
||||
|
||||
系统 SHALL 正确处理 Mac 和 Windows 平台的路径格式，包括路径分隔符和路径表示。
|
||||
|
||||
#### Scenario: Mac 路径格式
|
||||
|
||||
- **WHEN** Mac 用户指定 `--template-dir /Users/me/templates`
|
||||
- **THEN** 系统正确解析 Unix 风格的路径
|
||||
|
||||
#### Scenario: Windows 路径格式（反斜杠）
|
||||
|
||||
- **WHEN** Windows 用户指定 `--template-dir C:\templates`
|
||||
- **THEN** 系统正确解析 Windows 风格的路径
|
||||
|
||||
#### Scenario: Windows 路径格式（正斜杠）
|
||||
|
||||
- **WHEN** Windows 用户指定 `--template-dir C:/templates`
|
||||
- **THEN** 系统正确解析路径（Windows 支持正斜杠）
|
||||
|
||||
#### Scenario: 相对路径在不同平台
|
||||
|
||||
- **WHEN** 用户在任意平台指定 `--template-dir ./templates`
|
||||
- **THEN** 系统根据当前平台的规则正确解析相对路径
|
||||
|
||||
### Requirement: 参数帮助信息必须清晰
|
||||
|
||||
系统 SHALL 在 `--help` 输出中提供清晰的 `--template-dir` 参数说明。
|
||||
|
||||
#### Scenario: 查看帮助信息
|
||||
|
||||
- **WHEN** 用户运行 `uv run yaml2pptx.py --help`
|
||||
- **THEN** 帮助信息中包含 `--template-dir` 参数的说明，注明"如果 YAML 中使用了模板则必须指定"
|
||||
|
||||
#### Scenario: 帮助信息包含路径说明
|
||||
|
||||
- **WHEN** 用户查看 `--template-dir` 的帮助信息
|
||||
- **THEN** 说明中注明"可以是绝对路径或相对路径（相对于当前工作目录）"
|
||||
188
openspec/specs/template-system/spec.md
Normal file
188
openspec/specs/template-system/spec.md
Normal file
@@ -0,0 +1,188 @@
|
||||
# Template System
|
||||
|
||||
## Purpose
|
||||
|
||||
Template system 提供可复用的幻灯片布局和样式定义。模板包含变量定义、元素列表，支持变量替换、条件渲染，以及从目录加载。颜色和样式直接在模板中定义，无需额外的主题抽象层。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 模板必须定义变量列表
|
||||
|
||||
模板 SHALL 包含 vars 字段，定义该模板需要的变量，包括变量名、是否必需、默认值等。
|
||||
|
||||
#### Scenario: 加载模板变量定义
|
||||
|
||||
- **WHEN** 模板文件定义了 `vars` 列表，包含 `name`、`required`、`default` 等字段
|
||||
- **THEN** 系统成功加载变量定义，可通过模板对象访问
|
||||
|
||||
#### Scenario: 验证必需变量
|
||||
|
||||
- **WHEN** 模板定义了 `{name: title, required: true}` 的变量
|
||||
- **THEN** 渲染时如果未提供该变量，系统抛出错误
|
||||
|
||||
#### Scenario: 使用变量默认值
|
||||
|
||||
- **WHEN** 模板定义了 `{name: subtitle, required: false, default: ""}` 的变量
|
||||
- **THEN** 渲染时如果未提供该变量，系统使用空字符串作为默认值
|
||||
|
||||
### Requirement: 模板必须定义元素列表
|
||||
|
||||
模板 SHALL 包含 elements 字段，定义该模板的幻灯片布局和元素。
|
||||
|
||||
#### Scenario: 加载模板元素定义
|
||||
|
||||
- **WHEN** 模板文件定义了 `elements` 列表，包含文本、图片、形状等元素
|
||||
- **THEN** 系统成功加载元素列表，准备渲染
|
||||
|
||||
#### Scenario: 元素包含模板变量引用
|
||||
|
||||
- **WHEN** 模板元素中包含 `{title}` 等模板变量引用
|
||||
- **THEN** 系统在渲染时用用户提供的值替换变量
|
||||
|
||||
#### Scenario: 元素直接指定样式值
|
||||
|
||||
- **WHEN** 模板元素中直接指定 `color: "#4a90e2"` 等样式值
|
||||
- **THEN** 系统正确应用该样式值
|
||||
|
||||
### Requirement: 系统必须支持模板渲染
|
||||
|
||||
系统 SHALL 能够根据用户提供的变量值渲染模板，生成实际的元素列表。
|
||||
|
||||
#### Scenario: 渲染包含变量的模板
|
||||
|
||||
- **WHEN** 用户提供 `{title: "Hello", subtitle: "World"}` 渲染模板
|
||||
- **THEN** 系统将模板中的 `{title}` 替换为 "Hello"，`{subtitle}` 替换为 "World"
|
||||
|
||||
#### Scenario: 数值类型自动转换
|
||||
|
||||
- **WHEN** 模板定义 `size: "{font_size}"` 且用户提供 `{font_size: "44"}`
|
||||
- **THEN** 系统自动将字符串 "44" 转换为整数 44
|
||||
|
||||
#### Scenario: 检测未定义的模板变量
|
||||
|
||||
- **WHEN** 模板中引用了 `{undefined_var}`，但该变量未在 vars 中定义，也未由用户提供
|
||||
- **THEN** 系统抛出错误，指出未定义的变量
|
||||
|
||||
### Requirement: 系统必须支持条件渲染
|
||||
|
||||
系统 SHALL 支持基于变量值的条件渲染，通过 `visible` 字段控制元素是否显示。
|
||||
|
||||
#### Scenario: 显示满足条件的元素
|
||||
|
||||
- **WHEN** 元素定义了 `visible: "{subtitle != ''}\"`，且用户提供了非空的 subtitle
|
||||
- **THEN** 系统渲染该元素
|
||||
|
||||
#### Scenario: 隐藏不满足条件的元素
|
||||
|
||||
- **WHEN** 元素定义了 `visible: "{subtitle != ''}\"`，但用户提供的 subtitle 为空字符串
|
||||
- **THEN** 系统跳过该元素，不渲染到幻灯片中
|
||||
|
||||
#### Scenario: 条件表达式语法错误
|
||||
|
||||
- **WHEN** visible 字段包含无效的条件表达式
|
||||
- **THEN** 系统抛出错误，提示条件表达式格式错误
|
||||
|
||||
### Requirement: 模板文件必须可从指定目录加载
|
||||
|
||||
系统 SHALL 从用户通过 `--template-dir` 参数指定的目录加载模板文件，支持通过模板名称引用。模板名称必须是纯文件名，不能包含路径分隔符。
|
||||
|
||||
#### Scenario: 通过名称加载模板
|
||||
|
||||
- **WHEN** 幻灯片指定 `template: title-slide`，且用户提供 `--template-dir /path/to/templates`
|
||||
- **THEN** 系统从 `/path/to/templates/title-slide.yaml` 加载模板文件
|
||||
|
||||
#### Scenario: 模板文件不存在时报错
|
||||
|
||||
- **WHEN** 幻灯片引用不存在的模板名称
|
||||
- **THEN** 系统抛出错误，提示"模板文件不存在: <模板名>"，并显示查找位置和期望文件路径
|
||||
|
||||
#### Scenario: 缓存已加载的模板
|
||||
|
||||
- **WHEN** 多个幻灯片使用同一个模板
|
||||
- **THEN** 系统仅加载一次模板文件，后续使用缓存
|
||||
|
||||
#### Scenario: 错误信息包含详细的查找信息
|
||||
|
||||
- **WHEN** 模板文件未找到
|
||||
- **THEN** 错误信息包含：模板名称、查找位置（template_dir）、期望文件的完整路径、解决建议
|
||||
|
||||
### Requirement: 系统必须支持自定义幻灯片
|
||||
|
||||
系统 SHALL 支持不使用模板，直接定义元素的自定义幻灯片。
|
||||
|
||||
#### Scenario: 渲染自定义幻灯片
|
||||
|
||||
- **WHEN** 幻灯片未指定 `template` 字段，直接包含 `elements` 列表
|
||||
- **THEN** 系统跳过模板渲染，直接处理元素列表
|
||||
|
||||
#### Scenario: 自定义幻灯片中直接指定样式
|
||||
|
||||
- **WHEN** 自定义幻灯片的元素直接指定 `color: "#4a90e2"`
|
||||
- **THEN** 系统正确应用该颜色值
|
||||
|
||||
#### Scenario: 自定义幻灯片和模板混合使用
|
||||
|
||||
- **WHEN** 演示文稿中部分幻灯片使用模板，部分为自定义
|
||||
- **THEN** 系统正确处理两种类型的幻灯片
|
||||
|
||||
### Requirement: 模板变量解析必须深度递归
|
||||
|
||||
系统 SHALL 递归解析模板元素的所有嵌套字段中的变量引用。
|
||||
|
||||
#### Scenario: 解析嵌套对象中的变量
|
||||
|
||||
- **WHEN** 模板元素定义了 `font: {size: "{font_size}", color: "{text_color}"}`
|
||||
- **THEN** 系统正确解析嵌套对象中的所有变量引用
|
||||
|
||||
#### Scenario: 解析数组中的变量
|
||||
|
||||
- **WHEN** 模板元素定义了 `box: ["{left}", 2, 8, 3]`
|
||||
- **THEN** 系统正确解析数组中的变量引用
|
||||
|
||||
#### Scenario: 解析多层嵌套的变量
|
||||
|
||||
- **WHEN** 模板包含复杂的嵌套结构，多层使用变量引用
|
||||
- **THEN** 系统递归解析所有层级的变量，直到无变量引用为止
|
||||
|
||||
### Requirement: 模板名称必须是纯文件名
|
||||
|
||||
系统 SHALL 验证模板名称不包含路径分隔符，确保模板只能从指定目录的一层加载。
|
||||
|
||||
#### Scenario: 拒绝包含正斜杠的模板名称
|
||||
|
||||
- **WHEN** 幻灯片指定 `template: subdir/title-slide`
|
||||
- **THEN** 系统抛出错误，提示"模板名称不能包含路径分隔符: subdir/title-slide"
|
||||
|
||||
#### Scenario: 拒绝包含反斜杠的模板名称
|
||||
|
||||
- **WHEN** 幻灯片指定 `template: subdir\title-slide`
|
||||
- **THEN** 系统抛出错误，提示"模板名称不能包含路径分隔符: subdir\title-slide"
|
||||
|
||||
#### Scenario: 拒绝路径遍历尝试
|
||||
|
||||
- **WHEN** 幻灯片指定 `template: ../other-templates/slide`
|
||||
- **THEN** 系统抛出错误，提示模板名称不能包含路径分隔符
|
||||
|
||||
#### Scenario: 接受纯文件名
|
||||
|
||||
- **WHEN** 幻灯片指定 `template: title-slide`（不包含路径分隔符）
|
||||
- **THEN** 系统正常处理，从指定的 template_dir 加载模板
|
||||
|
||||
#### Scenario: 错误信息提供正确格式示例
|
||||
|
||||
- **WHEN** 系统因模板名称包含路径分隔符而报错
|
||||
- **THEN** 错误信息中包含"模板名称应该是纯文件名，如: 'title-slide'"的提示
|
||||
|
||||
### Requirement: 未指定模板目录时必须报错
|
||||
|
||||
系统 SHALL 在用户未提供 `--template-dir` 参数但 YAML 文件中使用了模板时，立即报错。
|
||||
|
||||
#### Scenario: 使用模板但未指定目录
|
||||
|
||||
- **WHEN** YAML 文件中包含 `template: title-slide`，但 `templates_dir` 参数为 `None`
|
||||
- **THEN** 系统在尝试加载模板时抛出错误，提示"未指定模板目录，无法加载模板"
|
||||
|
||||
#### Scenario: 不使用模板时不检查目录
|
||||
|
||||
- **WHEN** YAML 文件中所有幻灯片都是自定义幻灯片（不包含 `template` 字段）
|
||||
- **THEN** 系统不检查 `templates_dir` 是否为 `None`，正常处理
|
||||
97
openspec/specs/yaml-parsing/spec.md
Normal file
97
openspec/specs/yaml-parsing/spec.md
Normal file
@@ -0,0 +1,97 @@
|
||||
# YAML Parsing
|
||||
|
||||
## Purpose
|
||||
|
||||
YAML parsing 系统负责读取和验证演示文稿和模板的 YAML 文件。它支持 UTF-8 编码、验证颜色格式、验证文件结构，并提供清晰的错误消息帮助用户定位问题。
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 系统必须能解析演示文稿 YAML 文件
|
||||
|
||||
系统 SHALL 能够解析包含 metadata 和 slides 的演示文稿 YAML 文件，并验证其结构的正确性。
|
||||
|
||||
#### Scenario: 解析有效的演示文稿 YAML
|
||||
|
||||
- **WHEN** 提供一个包含 `metadata` 和 `slides` 字段的 YAML 文件
|
||||
- **THEN** 系统成功解析并返回 Python 字典结构
|
||||
|
||||
#### Scenario: 检测缺少必需字段
|
||||
|
||||
- **WHEN** 提供的 YAML 文件缺少 `slides` 字段
|
||||
- **THEN** 系统抛出验证错误，明确指出缺少必需字段
|
||||
|
||||
#### Scenario: 处理无效的 YAML 语法
|
||||
|
||||
- **WHEN** 提供的文件包含无效的 YAML 语法（如缩进错误）
|
||||
- **THEN** 系统抛出解析错误，包含行号和错误描述
|
||||
|
||||
### Requirement: 系统必须验证颜色值格式
|
||||
|
||||
系统 SHALL 验证模板和演示文稿 YAML 文件中的颜色值为有效的十六进制格式。
|
||||
|
||||
#### Scenario: 验证有效的颜色值
|
||||
|
||||
- **WHEN** 模板或演示文稿 YAML 文件中包含 `color: "#4a90e2"` 的颜色值
|
||||
- **THEN** 系统接受该颜色值
|
||||
|
||||
#### Scenario: 验证颜色值格式错误
|
||||
|
||||
- **WHEN** 颜色值格式不正确（如 "blue" 或 "#xyz"）
|
||||
- **THEN** 系统抛出验证错误，提示使用 #RRGGBB 格式
|
||||
|
||||
#### Scenario: 支持短格式颜色值
|
||||
|
||||
- **WHEN** 颜色值为短格式 "#fff"
|
||||
- **THEN** 系统自动扩展为 "#ffffff" 并接受
|
||||
|
||||
### Requirement: 系统必须能解析模板 YAML 文件
|
||||
|
||||
系统 SHALL 能够解析包含 vars 定义和 elements 列表的模板 YAML 文件。
|
||||
|
||||
#### Scenario: 解析有效的模板文件
|
||||
|
||||
- **WHEN** 提供一个包含 `vars` 和 `elements` 字段的模板 YAML 文件
|
||||
- **THEN** 系统成功解析并返回模板对象
|
||||
|
||||
#### Scenario: 验证变量定义的完整性
|
||||
|
||||
- **WHEN** 模板 vars 中的变量缺少 `name` 字段
|
||||
- **THEN** 系统抛出验证错误，指出变量定义不完整
|
||||
|
||||
#### Scenario: 验证必需变量标记
|
||||
|
||||
- **WHEN** 模板 vars 中定义了 `required: true` 的变量
|
||||
- **THEN** 系统记录该变量为必需变量，在渲染时必须提供值
|
||||
|
||||
### Requirement: 系统必须支持 UTF-8 编码
|
||||
|
||||
系统 SHALL 以 UTF-8 编码读取所有 YAML 文件，支持中文等多字节字符。
|
||||
|
||||
#### Scenario: 解析包含中文的 YAML 文件
|
||||
|
||||
- **WHEN** 提供包含中文字符的 YAML 文件
|
||||
- **THEN** 系统正确解析中文内容，不出现乱码
|
||||
|
||||
#### Scenario: 处理 BOM 标记
|
||||
|
||||
- **WHEN** YAML 文件包含 UTF-8 BOM 标记
|
||||
- **THEN** 系统能够正确处理并解析文件内容
|
||||
|
||||
### Requirement: 系统必须提供清晰的错误消息
|
||||
|
||||
系统 SHALL 在 YAML 解析失败时提供包含文件路径、行号、错误原因的详细错误消息。
|
||||
|
||||
#### Scenario: YAML 语法错误的错误消息
|
||||
|
||||
- **WHEN** YAML 文件在第 10 行存在缩进错误
|
||||
- **THEN** 错误消息包含 "文件路径, 第 10 行: 缩进错误" 等信息
|
||||
|
||||
#### Scenario: 文件不存在的错误消息
|
||||
|
||||
- **WHEN** 尝试加载不存在的 YAML 文件
|
||||
- **THEN** 错误消息明确指出文件路径不存在
|
||||
|
||||
#### Scenario: 权限不足的错误消息
|
||||
|
||||
- **WHEN** YAML 文件存在但没有读取权限
|
||||
- **THEN** 错误消息提示权限不足，无法读取文件
|
||||
Reference in New Issue
Block a user