feat: 移除图片适配模式功能

移除图片 fit 和 background 参数支持，简化图片渲染逻辑。系统恢复到直接使用 python-pptx 原生图片添加功能，图片将被拉伸到指定尺寸。变更内容： - 移除 ImageElement 的 fit 和 background 字段 - 移除 metadata.dpi 配置 - 删除 utils/image_utils.py 图片处理工具模块 - 删除 validators/image_config.py 验证器 - 简化 PPTX 和 HTML 渲染器的图片处理逻辑 - HTML 渲染器使用硬编码 DPI=96（Web 标准） - 删除相关测试文件（单元测试、集成测试、e2e 测试） - 更新规格文档和用户文档 - 保留 Pillow 依赖用于未来可能的图片处理需求影响： - 删除 11 个文件 - 修改 10 个文件 - 净减少 1558 行代码 - 所有 402 个测试通过 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-03-04 14:23:12 +08:00
parent 2fd8bc1b4a
commit f34405be36
31 changed files with 494 additions and 1556 deletions
--- a/openspec/changes/archive/2026-03-04-remove-image-fit-modes/.openspec.yaml
+++ b/openspec/changes/archive/2026-03-04-remove-image-fit-modes/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-04
--- a/openspec/changes/archive/2026-03-04-remove-image-fit-modes/design.md
+++ b/openspec/changes/archive/2026-03-04-remove-image-fit-modes/design.md
@@ -0,0 +1,184 @@
+# 移除图片适配模式技术设计
+
+## Context
+
+### 当前状态
+
+图片适配模式功能已在 `openspec/changes/archive/2026-03-04-add-image-fit-modes/` 中实现并归档，包括：
+
+- `utils/image_utils.py`: 图片处理工具模块（英寸像素转换、fit 模式处理）
+- `validators/image_config.py`: 图片参数验证器
+- `core/elements.py`: ImageElement 添加了 fit 和 background 字段
+- `renderers/pptx_renderer.py`: 重写 _render_image() 支持四种 fit 模式
+- `renderers/html_renderer.py`: render_image() 支持 CSS object-fit 映射
+- `core/presentation.py`: 读取 metadata.dpi 配置
+- 完整的单元测试和集成测试
+
+该功能尚未上线使用，无需考虑向后兼容性。
+
+### 约束条件
+
+- 必须保留 Pillow 依赖（用户要求留作备用）
+- HTML 渲染器需要保留英寸到像素的转换功能（使用硬编码 DPI=96）
+- 移除后图片渲染行为：直接拉伸到 box 指定的尺寸
+
+### 利益相关者
+
+- 最终用户：获得更简单的图片配置（只需 src 和 box）
+- 开发者：降低代码复杂度和维护成本
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- 完全移除图片适配模式功能（fit、background、dpi 配置）
+- 简化图片渲染逻辑，恢复到直接使用 python-pptx 原生功能
+- 删除不再需要的工具模块和验证器
+- 删除相关测试文件
+- 更新规格文档和用户文档
+- 保留 Pillow 依赖用于未来可能的图片处理需求
+
+**Non-Goals:**
+
+- 不移除 Pillow 依赖
+- 不改变 HTML 渲染器的基础英寸到像素转换功能（保留硬编码 DPI=96）
+- 不影响其他元素类型（text、shape、table）的渲染逻辑
+
+## Decisions
+
+### 决策 1: HTML 渲染器使用硬编码 DPI
+
+**选择：** HtmlRenderer 使用硬编码的 `self.dpi = 96`，移除 __init__ 的 dpi 参数
+
+**理由：**
+
+- 96 是 Web 标准 DPI，适用于绝大多数场景
+- HTML 预览的尺寸转换是基础功能，不需要用户配置
+- 移除 metadata.dpi 配置后，简化了用户 YAML 文件
+
+**实现：**
+```python
+# renderers/html_renderer.py
+class HtmlRenderer:
+    def __init__(self):  # 移除 dpi 参数
+        self.dpi = 96  # 硬编码 Web 标准 DPI
+```
+
+### 决策 2: PPTX 图片渲染恢复到简单实现
+
+**选择：** 直接使用 python-pptx 的 `slide.shapes.add_picture()` 方法
+
+**理由：**
+
+- python-pptx 原生支持图片添加，会自动拉伸到指定尺寸
+- 移除对 Pillow 的运行时依赖（保留依赖但代码中不使用）
+- 代码更简洁，易于维护
+
+**实现：**
+```python
+# renderers/pptx_renderer.py
+def _render_image(self, slide, elem: ImageElement, base_path):
+    img_path = Path(elem.src)
+    if not img_path.is_absolute() and base_path:
+        img_path = Path(base_path) / elem.src
+
+    if not img_path.exists():
+        raise YAMLError(f"图片文件未找到: {img_path}")
+
+    x, y, w, h = [Inches(v) for v in elem.box]
+    slide.shapes.add_picture(str(img_path), x, y, width=w, height=h)
+```
+
+### 决策 3: 完全删除相关文件而非注释代码
+
+**选择：** 直接删除 image_utils.py、image_config.py 及相关测试文件
+
+**理由：**
+
+- 功能尚未上线，无需保留代码历史
+- Git 历史已记录所有实现细节
+- 保持代码库整洁
+
+### 决策 4: 删除 image-fit-modes 规格
+
+**选择：** 删除 `openspec/specs/image-fit-modes/` 整个目录
+
+**理由：**
+
+- 该规格对应的 capability 正在被移除
+- 归档的变更中已保留完整规格副本
+
+## Risks / Trade-offs
+
+### 风险 1: HTML 预览尺寸可能与 PPTX 不完全一致
+
+**风险：** 硬编码 DPI=96 可能在某些显示器上导致预览尺寸与实际 PPTX 有差异
+
+**缓解措施：**
+- 96 是 Web 标准，覆盖绝大多数场景
+- 预览功能主要用于布局参考，不需要像素级精确
+- 用户主要关注 PPTX 输出结果
+
+### 风险 2: 删除文件可能影响其他未发现的依赖
+
+**风险：** 可能有其他代码或测试依赖 image_utils 或 image_config
+
+**缓解措施：**
+- 运行完整的测试套件验证
+- 检查 imports 确保没有遗漏的引用
+- 使用 Grep 搜索可能的引用点
+
+### 风险 3: 文档更新可能不完整
+
+**风险：** README.md 或 README_DEV.md 中可能残留相关说明
+
+**缓解措施：**
+- 在 tasks 中明确列出文档更新任务
+- 人工审查最终文档内容
+
+## Migration Plan
+
+### 部署步骤
+
+由于功能尚未上线，无需迁移策略。直接执行删除和修改即可。
+
+1. **删除工具和验证器模块**
+   - 删除 `utils/image_utils.py`
+   - 删除 `validators/image_config.py`
+   - 更新 `validators/validator.py` 移除引用
+
+2. **修改核心代码**
+   - 更新 `core/elements.py` 的 ImageElement
+   - 更新 `core/presentation.py` 的 Presentation
+   - 更新 `renderers/pptx_renderer.py`
+   - 更新 `renderers/html_renderer.py`
+   - 更新 `yaml2pptx.py`
+   - 更新 `preview/server.py`
+
+3. **删除测试文件**
+   - 删除 `tests/unit/test_image_utils.py`
+   - 删除 `tests/unit/test_validators/test_image_config.py`
+   - 删除 `tests/integration/test_image_fit_modes.py`
+
+4. **删除规格文件**
+   - 删除 `openspec/specs/image-fit-modes/` 目录
+
+5. **更新文档**
+   - 更新 `README.md`
+   - 更新 `README_DEV.md`
+   - 更新 `openspec/specs/element-rendering/spec.md`
+   - 更新 `openspec/specs/html-rendering/spec.md`
+
+6. **验证**
+   - 运行完整测试套件
+   - 检查是否有遗留的 import 引用
+
+### 回滚策略
+
+- Git 历史保留了所有实现
+- 如需恢复功能，可以从归档的变更中恢复代码
+- 或者从 Git 历史中恢复提交 `19d6661` 之前的代码
+
+## Open Questions
+
+无。移除操作明确清晰，无未决问题。
--- a/openspec/changes/archive/2026-03-04-remove-image-fit-modes/proposal.md
+++ b/openspec/changes/archive/2026-03-04-remove-image-fit-modes/proposal.md
@@ -0,0 +1,57 @@
+# 移除图片适配模式功能
+
+## Why
+
+图片适配模式功能已实现但尚未上线使用，经过评估决定移除该功能以简化系统复杂度。移除后系统将恢复到更简单直接的图片渲染方式：直接使用 python-pptx 的原生图片添加功能，图片会被拉伸到指定尺寸。
+
+## What Changes
+
+- **BREAKING** 移除图片元素的 `fit` 参数（stretch、contain、cover、center 四种模式）
+- **BREAKING** 移除图片元素的 `background` 参数（背景色填充）
+- **BREAKING** 移除文档级的 `metadata.dpi` 配置
+- **BREAKING** 删除 `utils/image_utils.py` 模块（图片处理工具）
+- **BREAKING** 删除 `validators/image_config.py` 模块（图片配置验证器）
+- 重写 `renderers/pptx_renderer.py` 的 `_render_image()` 方法，恢复简单实现
+- 简化 `renderers/html_renderer.py` 的 `render_image()` 方法，移除 fit/background 处理
+- 简化 `core/elements.py` 的 `ImageElement` 类，移除 fit/background 字段
+- 简化 `core/presentation.py` 的 `Presentation` 类，移除 dpi 配置读取
+- 保留 Pillow 依赖（留作未来可能的其他用途）
+- HTML 渲染器使用硬编码的 DPI=96（Web 标准，无需用户配置）
+
+## Capabilities
+
+### Modified Capabilities
+- `element-rendering`: 移除图片元素的 fit 和 background 参数支持，恢复到基础图片渲染
+- `html-rendering`: 移除图片元素的 fit 和 background 参数支持，简化 HTML 图片渲染
+
+## Impact
+
+### 代码变更
+- `core/elements.py`: ImageElement 移除 fit 和 background 字段及验证逻辑
+- `core/presentation.py`: Presentation 移除 dpi 配置读取
+- `renderers/pptx_renderer.py`: 重写 _render_image() 方法，移除 Pillow 图片处理和 fit 模式逻辑
+- `renderers/html_renderer.py`: 简化 render_image() 方法，移除 fit 模式映射和背景色容器
+- `yaml2pptx.py`: 移除传递 dpi 参数到 PptxGenerator
+- `preview/server.py`: 移除传递 dpi 参数到 HtmlRenderer
+- `validators/validator.py`: 移除对 image_config 的引用
+
+### 删除的文件
+- `utils/image_utils.py`: 整个文件删除
+- `validators/image_config.py`: 整个文件删除
+- `tests/unit/test_image_utils.py`: 删除
+- `tests/unit/test_validators/test_image_config.py`: 删除
+- `tests/integration/test_image_fit_modes.py`: 删除
+- `openspec/specs/image-fit-modes/`: 整个规格目录删除
+
+### API 变更
+- YAML 语法移除：
+  - 图片元素不再支持 `fit` 字段
+  - 图片元素不再支持 `background` 字段
+  - metadata 层级不再支持 `dpi` 字段
+
+### 依赖变更
+- Pillow 依赖保留（在 pyproject.toml 中），用于未来可能的图片处理需求
+
+### 文档变更
+- `README.md`: 移除图片适配模式使用说明
+- `README_DEV.md`: 移除图片处理架构说明
--- a/openspec/changes/archive/2026-03-04-remove-image-fit-modes/specs/element-rendering/spec.md
+++ b/openspec/changes/archive/2026-03-04-remove-image-fit-modes/specs/element-rendering/spec.md
@@ -0,0 +1,82 @@
+# Element Rendering Delta Spec
+
+## REMOVED Requirements
+
+### Requirement: 系统必须支持图片元素渲染 (部分移除)
+
+**Reason**: 移除图片适配模式功能（fit 和 background 参数），简化图片渲染逻辑
+
+**Migration**: 移除图片元素的 `fit` 和 `background` 参数定义，系统将使用简单的拉伸模式渲染图片
+
+#### Scenario: 使用 fit 模式渲染图片
+
+**REMOVED**
+
+- **WHEN** 元素定义为 `{type: image, src: "photo.jpg", box: [1, 1, 4, 3], fit: contain}`
+- **THEN** 系统使用 `contain` 模式渲染图片
+- **AND** 保持图片宽高比，完整显示在 box 内
+
+#### Scenario: 使用背景色渲染图片
+
+**REMOVED**
+
+- **WHEN** 元素定义为 `{type: image, src: "photo.png", box: [1, 1, 4, 3], fit: contain, background: "#f0f0f0"}`
+- **THEN** 系统使用 `contain` 模式渲染图片
+- **AND** 用 #f0f0f0 颜色填充留白区域
+
+#### Scenario: 图片格式不支持时报错
+
+**REMOVED**
+
+- **WHEN** 图片文件格式不被 Pillow 支持
+- **THEN** 系统抛出错误，提示图片格式不支持，并列出支持的格式
+
+#### Scenario: 图片处理失败时报错
+
+**REMOVED**
+
+- **WHEN** Pillow 处理图片时发生异常（如文件损坏）
+- **THEN** 系统抛出 ERROR 级别错误，不降级到其他模式
+
+#### Scenario: 使用 DPI 配置渲染图片
+
+**REMOVED**
+
+- **WHEN** metadata 定义了 `dpi: 120` 且图片需要处理
+- **THEN** 系统使用该 DPI 值进行像素与英寸的转换
+
+#### Scenario: fit 参数值无效时报错
+
+**REMOVED**
+
+- **WHEN** `fit` 参数值不是 stretch、contain、cover、center 之一
+- **THEN** 系统抛出 ERROR，并列出有效值
+
+#### Scenario: background 参数颜色格式无效时报错
+
+**REMOVED**
+
+- **WHEN** `background` 值不是有效的颜色格式
+- **THEN** 系统抛出 ERROR，提示颜色格式应为 #RRGGBB 或 #RGB
+
+## MODIFIED Requirements
+
+### Requirement: 系统必须支持图片元素渲染
+
+系统 SHALL 将 YAML 中定义的图片元素渲染为 PPTX 图片对象，直接使用 python-pptx 的原生图片添加功能。
+
+#### Scenario: 渲染本地图片
+
+- **WHEN** 元素定义为 `{type: image, src: "images/logo.png", box: [2, 3, 4, 3]}`
+- **THEN** 系统从指定路径加载图片，在 (2, 3) 位置渲染为 4×3 英寸大小
+- **AND** 图片会被拉伸到指定尺寸（python-pptx 默认行为）
+
+#### Scenario: 图片文件不存在时报错
+
+- **WHEN** 图片 src 指向不存在的文件路径
+- **THEN** 系统抛出错误，明确指出图片文件未找到
+
+#### Scenario: 相对路径处理
+
+- **WHEN** 图片 src 使用相对路径 `"assets/images/logo.png"`
+- **THEN** 系统基于演示文稿文件所在目录解析相对路径
--- a/openspec/changes/archive/2026-03-04-remove-image-fit-modes/specs/html-rendering/spec.md
+++ b/openspec/changes/archive/2026-03-04-remove-image-fit-modes/specs/html-rendering/spec.md
@@ -0,0 +1,86 @@
+# HTML Rendering Delta Spec
+
+## REMOVED Requirements
+
+### Requirement: 系统必须渲染图片元素 (部分移除)
+
+**Reason**: 移除图片适配模式功能（fit 和 background 参数），简化 HTML 图片渲染
+
+**Migration**: 移除图片元素的 `fit` 和 `background` 参数定义，HTML 渲染器将输出简单的 `<img>` 标签
+
+#### Scenario: 使用 fit 模式渲染图片
+
+**REMOVED**
+
+- **WHEN** 元素定义为 `{type: image, src: "photo.jpg", box: [1, 1, 4, 3], fit: contain}`
+- **THEN** 系统应用 CSS `object-fit: contain`
+- **AND** 保持图片宽高比，完整显示在 box 内
+
+#### Scenario: fit 模式与 CSS object-fit 映射
+
+**REMOVED**
+
+- **WHEN** `fit` 参数为 `stretch`
+- **THEN** 系统应用 CSS `object-fit: fill`
+
+- **WHEN** `fit` 参数为 `contain`
+- **THEN** 系统应用 CSS `object-fit: contain`
+
+- **WHEN** `fit` 参数为 `cover`
+- **THEN** 系统应用 CSS `object-fit: cover`
+
+- **WHEN** `fit` 参数为 `center`
+- **THEN** 系统应用 CSS `object-fit: none` 和 `object-position: center`
+
+#### Scenario: 使用背景色渲染图片
+
+**REMOVED**
+
+- **WHEN** 元素定义为 `{type: image, src: "photo.png", box: [1, 1, 4, 3], fit: contain, background: "#f0f0f0"}`
+- **THEN** 系统为图片容器添加 CSS `background-color: #f0f0f0`
+- **AND** 应用 CSS `object-fit: contain`
+
+#### Scenario: 图片容器支持背景色
+
+**REMOVED**
+
+- **WHEN** 图片指定了 `background` 参数
+- **THEN** 系统创建包装容器，应用背景色到容器
+- **AND** 图片在容器内使用 object-fit 定位
+
+#### Scenario: 使用 DPI 配置渲染图片
+
+**REMOVED**
+
+- **WHEN** metadata 定义了 `dpi: 120`
+- **THEN** 系统使用该 DPI 值进行英寸到像素的转换
+- **AND** box: [1, 1, 4, 3] 转换为 CSS: left: 120px; top: 120px; width: 480px; height: 360px
+
+#### Scenario: HTML 渲染与 PPTX 渲染效果一致
+
+**REMOVED**
+
+- **WHEN** 同一图片元素使用相同的 fit 和 background 参数
+- **THEN** HTML 预览和 PPTX 输出的视觉效果应保持一致
+- **AND** 图片位置、尺寸、适配方式相同
+
+## MODIFIED Requirements
+
+### Requirement: 系统必须渲染图片元素
+
+系统 SHALL 将 YAML 中的图片元素转换为 HTML `<img>` 标签，使用固定 DPI 进行尺寸转换。
+
+#### 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** 系统显示占位符或错误提示，而不是崩溃
--- a/openspec/changes/archive/2026-03-04-remove-image-fit-modes/tasks.md
+++ b/openspec/changes/archive/2026-03-04-remove-image-fit-modes/tasks.md
@@ -0,0 +1,67 @@
+# 移除图片适配模式功能 - 任务清单
+
+## 1. 删除工具和验证器模块
+
+- [x] 1.1 删除 `utils/image_utils.py` 文件
+- [x] 1.2 删除 `validators/image_config.py` 文件
+- [x] 1.3 更新 `validators/validator.py`，移除对 image_config 的引用
+
+## 2. 修改核心元素定义
+
+- [x] 2.1 更新 `core/elements.py` 的 ImageElement 类，移除 fit 字段
+- [x] 2.2 更新 `core/elements.py` 的 ImageElement 类，移除 background 字段
+- [x] 2.3 简化 `core/elements.py` 的 ImageElement.validate() 方法，移除 fit/background 验证逻辑
+
+## 3. 修改演示文稿类
+
+- [x] 3.1 更新 `core/presentation.py` 的 Presentation 类，移除 self.dpi = metadata.get("dpi", 96)
+
+## 4. 修改 PPTX 渲染器
+
+- [x] 4.1 更新 `renderers/pptx_renderer.py`，移除 `from PIL import Image` 导入
+- [x] 4.2 更新 `renderers/pptx_renderer.py`，移除 `from utils.image_utils import ...` 导入
+- [x] 4.3 更新 `renderers/pptx_renderer.py` 的 PptxGenerator.__init__()，移除 dpi 参数
+- [x] 4.4 重写 `renderers/pptx_renderer.py` 的 _render_image() 方法，恢复简单实现
+
+## 5. 修改 HTML 渲染器
+
+- [x] 5.1 更新 `renderers/html_renderer.py` 的 HtmlRenderer.__init__()，移除 dpi 参数，硬编码 self.dpi = 96
+- [x] 5.2 简化 `renderers/html_renderer.py` 的 render_image() 方法，移除 fit 模式映射逻辑
+- [x] 5.3 简化 `renderers/html_renderer.py` 的 render_image() 方法，移除 background 容器逻辑
+
+## 6. 修改入口文件
+
+- [x] 6.1 更新 `yaml2pptx.py`，移除传递 dpi 参数到 PptxGenerator
+- [x] 6.2 更新 `preview/server.py`，移除传递 dpi 参数到 HtmlRenderer
+
+## 7. 删除测试文件
+
+- [x] 7.1 删除 `tests/unit/test_image_utils.py`
+- [x] 7.2 删除 `tests/unit/test_validators/test_image_config.py`
+- [x] 7.3 删除 `tests/integration/test_image_fit_modes.py`
+- [x] 7.4 检查并更新 `tests/fixtures/create_test_images.py`（如果有其他依赖则保留，否则删除）
+- [x] 7.5 检查并更新 `tests/integration/test_rendering_flow.py`，移除相关测试
+
+## 8. 删除规格文件
+
+- [x] 8.1 删除 `openspec/specs/image-fit-modes/` 整个目录
+
+## 9. 更新主规格文件
+
+- [x] 9.1 更新 `openspec/specs/element-rendering/spec.md`，移除 fit 和 background 相关规格
+- [x] 9.2 更新 `openspec/specs/html-rendering/spec.md`，移除 fit 和 background 相关规格
+
+## 10. 更新用户文档
+
+- [x] 10.1 更新 `README.md`，移除图片适配模式章节
+- [x] 10.2 更新 `README.md`，移除 metadata.dpi 配置说明
+- [x] 10.3 更新 `README_DEV.md`，移除图片处理架构说明
+- [x] 10.4 更新 `README_DEV.md`，移除 Pillow 依赖说明（改为保留用于备用）
+
+## 11. 验证和测试
+
+- [x] 11.1 运行 `uv run pytest`，确保所有测试通过
+- [x] 11.2 使用 Grep 搜索代码库，确认没有遗留的 image_utils 或 image_config 引用
+- [x] 11.3 使用 Grep 搜索代码库，确认没有遗留的 fit 或 background 参数引用（在图片元素上下文中）
+- [x] 11.4 运行 `uv run python yaml2pptx.py` 测试基本转换功能
+- [x] 11.5 运行 `uv run python preview/server.py` 测试预览功能