refactor: modularize yaml2pptx into layered architecture

Refactor yaml2pptx.py from a 1,245-line monolithic script into a modular
architecture with clear separation of concerns. The entry point is now
127 lines, with business logic distributed across focused modules.

Architecture:
- core/: Domain models (elements, template, presentation)
- loaders/: YAML loading and validation
- renderers/: PPTX and HTML rendering
- preview/: Flask preview server
- utils.py: Shared utilities

Key improvements:
- Element abstraction layer using dataclass with validation
- Renderer logic built into generator classes
- Single-direction dependencies (no circular imports)
- Each module 150-300 lines for better readability
- Backward compatible CLI interface

Documentation:
- README.md: User-facing usage guide
- README_DEV.md: Developer documentation

OpenSpec:
- Archive refactor-yaml2pptx-modular change (63/70 tasks complete)
- Sync 5 delta specs to main specs (2 new + 3 updated)

openspec/changes/archive/2026-03-02-refactor-yaml2pptx-modular/proposal.md

@@ -0,0 +1,52 @@
+## Why
+
+yaml2pptx.py 脚本已增长到 1,245 行，包含了 YAML 解析、模板系统、元素渲染、PPTX 生成、HTML 预览等多个功能模块。单文件结构导致代码难以阅读、维护和扩展，对开发者和 LLM 工具都不友好。需要将其重构为模块化结构，同时引入元素抽象层，为未来添加新元素类型和渲染器奠定基础。
+
+## What Changes
+
+- 将 yaml2pptx.py 拆分为多个功能模块文件，按 core/loaders/renderers/preview 四层架构组织
+- 引入元素抽象层，使用 dataclass 定义元素数据类（TextElement, ImageElement, ShapeElement, TableElement）
+- 在元素创建时进行验证（`__post_init__` 方法）
+- 重构 PPTX 生成器，将渲染器内置在 PptxGenerator 类中
+- 重构 HTML 渲染器，作为独立的 HtmlRenderer 类用于预览功能
+- 保持 yaml2pptx.py 作为单一入口点，所有依赖声明保留在入口脚本的 `/// script` 头部
+- 保持向后兼容：`uv run yaml2pptx.py` 的使用方式不变
+
+## Capabilities
+
+### New Capabilities
+
+- `modular-architecture`: 模块化代码架构，将单文件脚本拆分为 core（核心领域模型）、loaders（加载器）、renderers（渲染器）、preview（预览服务）四层结构，每个模块职责清晰，文件大小控制在 150-300 行
+- `element-abstraction`: 元素抽象层，定义统一的元素接口和数据类，支持元素验证和未来扩展新元素类型
+
+### Modified Capabilities
+
+- `element-rendering`: 从函数式渲染改为基于元素数据类的面向对象渲染，引入元素抽象层和创建时验证
+- `pptx-generation`: 重构为内置渲染器的架构，PptxGenerator 类内部包含 PPTX 渲染逻辑，通过元素类型分发到对应的渲染方法
+- `html-rendering`: 从内联函数重构为独立的 HtmlRenderer 类，与 PptxRenderer 共享元素抽象层
+
+## Impact
+
+**代码结构**：
+- yaml2pptx.py：从 1,245 行缩减为约 100 行（仅保留 CLI 和 main 函数）
+- 新增文件：
+  - core/elements.py（元素数据类）
+  - core/template.py（Template 类）
+  - core/presentation.py（Presentation 类）
+  - loaders/yaml_loader.py（YAML 加载和验证）
+  - renderers/pptx_renderer.py（PptxGenerator）
+  - renderers/html_renderer.py（HtmlRenderer）
+  - preview/server.py（Flask 服务器和文件监听）
+  - utils.py（工具函数）
+
+**导入路径**：
+- 内部导入路径会发生变化（如 `from core.elements import TextElement`）
+- 外部使用方式不变（`uv run yaml2pptx.py input.yaml output.pptx`）
+
+**依赖管理**：
+- 所有依赖保持在 yaml2pptx.py 的 `/// script` 头部
+- 预览功能的依赖（flask, watchdog）不再可选，统一在入口声明
+
+**测试和验证**：
+- 需要验证所有现有功能在重构后仍正常工作
+- 需要测试 YAML 解析、模板渲染、PPTX 生成、HTML 预览等完整流程