refactor: restructure CLI with clear subcommand architecture

重构命令行接口，建立清晰的子命令架构，提升用户体验和代码可维护性。主要变更： - 移除传统模式，统一使用子命令架构（check/convert/preview） - 将 preview 从 convert 的标志独立为子命令，职责分离 - 重命名参数：--no-check → --skip-validation - 新增 --force/-f：convert 命令支持强制覆盖已存在文件 - 新增 --host：preview 命令支持配置主机地址（局域网预览） - 新增 --no-browser：preview 命令支持不自动打开浏览器 - 优化 --port 默认值：从固定端口改为随机端口（30000-40000）破坏性变更： - 不再支持传统模式（yaml2pptx.py input.yaml output.pptx） - convert 命令不再支持 --preview 参数，需使用 preview 子命令文档更新： - 更新 README.md 和 README_DEV.md 的所有使用示例 - 更新命令行选项说明表格 - 新增 CLI 接口规范文档 OpenSpec： - 创建 cli-interface 规范（新能力） - 更新 browser-preview-server 规范（修改的能力） - 归档 refactor-cli-args change（45/45 任务完成）
2026-03-02 18:47:50 +08:00
parent 83ff827ad1
commit 66472cbd86
13 changed files with 934 additions and 112 deletions
--- a/openspec/changes/archive/2026-03-02-refactor-cli-args/.openspec.yaml
+++ b/openspec/changes/archive/2026-03-02-refactor-cli-args/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-02
--- a/openspec/changes/archive/2026-03-02-refactor-cli-args/design.md
+++ b/openspec/changes/archive/2026-03-02-refactor-cli-args/design.md
@@ -0,0 +1,187 @@
+## Context
+
+当前 `yaml2pptx.py` 的 CLI 实现存在以下问题：
+
+1. **双模式解析**：同时支持子命令模式（`check`/`convert`）和传统模式（直接参数），导致参数解析逻辑复杂，代码中需要手动检查 `sys.argv[1]` 来决定使用哪种解析器
+2. **职责混乱**：`convert` 命令通过 `--preview` 标志切换到预览模式，但 convert 和 preview 是完全不同的操作（一个生成文件，一个启动服务器）
+3. **参数重复定义**：`--template-dir`、`--preview`、`--port` 等参数在两个解析器中重复定义
+4. **命名不清晰**：`--no-check` 是双重否定，不够直观
+
+本次重构的目标是建立清晰的子命令架构，提升代码可维护性和用户体验。
+
+## Goals / Non-Goals
+
+**Goals:**
+- 统一使用子命令架构，移除传统模式
+- 将 preview 独立为子命令，职责分离
+- 简化参数解析逻辑，消除代码重复
+- 优化参数命名和默认值
+- 新增实用功能（文件覆盖控制、局域网预览、浏览器控制）
+
+**Non-Goals:**
+- 不改变核心转换逻辑（YAML 解析、PPTX 生成）
+- 不改变验证逻辑（ERROR/WARNING/INFO 分级）
+- 不改变预览服务器的核心功能（文件监听、SSE 推送）
+- 不考虑向后兼容传统模式（项目未上线）
+
+## Decisions
+
+### 决策 1：使用纯子命令架构
+
+**选择：** 移除传统模式，统一使用 `<command> <subcommand>` 结构
+
+**理由：**
+- 子命令架构更清晰，每个子命令职责单一
+- 避免双模式解析的复杂性
+- 符合现代 CLI 工具的设计习惯（如 git、docker）
+
+**替代方案：**
+- 保留传统模式作为快捷方式：增加维护成本，用户容易混淆
+- 使用选项组而非子命令：无法清晰表达互斥的操作模式
+
+### 决策 2：preview 独立为子命令
+
+**选择：** 将 preview 从 `convert --preview` 改为独立的 `preview` 子命令
+
+**理由：**
+- convert 和 preview 是完全不同的操作：
+  - convert：一次性操作，生成文件后退出
+  - preview：长期运行，启动服务器，监听文件变化
+- 独立子命令使参数更清晰（preview 特有的 `--port`、`--host`、`--no-browser` 不会出现在 convert 中）
+- 符合单一职责原则
+
+**替代方案：**
+- 保持 `convert --preview`：职责混乱，参数难以组织
+- 使用 `serve` 或 `watch` 命名：preview 更直观，表达预览意图
+
+### 决策 3：参数解析使用 argparse 的 subparsers
+
+**选择：** 使用 argparse 的 `add_subparsers()` 和 `required=True`
+
+**理由：**
+- argparse 是 Python 标准库，无需额外依赖
+- subparsers 自动处理子命令路由，无需手动检查 `sys.argv`
+- 自动生成帮助信息
+
+**实现结构：**
+```python
+parser = argparse.ArgumentParser()
+subparsers = parser.add_subparsers(dest='command', required=True)
+
+# 每个子命令独立配置
+check_parser = subparsers.add_parser('check')
+convert_parser = subparsers.add_parser('convert')
+preview_parser = subparsers.add_parser('preview')
+```
+
+### 决策 4：preview 默认使用随机端口（30000-40000）
+
+**选择：** `--port` 默认值为 None，运行时随机选择 30000-40000 范围内的端口
+
+**理由：**
+- 避免端口冲突，支持同时运行多个预览实例
+- 30000+ 端口通常不被系统服务占用
+- 用户可以通过 `--port` 指定固定端口
+
+**替代方案：**
+- 固定端口 5000：容易冲突，不支持多实例
+- 完全随机端口（1024-65535）：可能与其他服务冲突
+
+### 决策 5：convert 默认不覆盖已存在文件
+
+**选择：** 输出文件已存在时报错，需要 `--force/-f` 强制覆盖
+
+**理由：**
+- 避免意外覆盖用户文件
+- 符合安全优先原则
+- 提供明确的覆盖控制
+
+**替代方案：**
+- 默认覆盖：不安全，可能导致数据丢失
+- 自动重命名（如 output-1.pptx）：用户可能不知道生成了多个文件
+
+### 决策 6：简化参数，移除不必要的选项
+
+**选择：** 移除 `--verbose`、`--quiet`、`--strict`、`--format`、`--no-watch`
+
+**理由：**
+- `--verbose`/`--quiet`：当前输出已经足够简洁，不需要额外控制
+- `--strict`：保持原有的 ERROR/WARNING/INFO 分级即可
+- `--format`：命令行工具主要面向人类用户，text 格式足够
+- `--no-watch`：preview 的核心价值就是实时监听，不需要关闭
+
+**保留的参数：**
+- `--template-dir`：所有命令通用
+- `--skip-validation`：convert 特有，用于快速转换
+- `--force/-f`：convert 特有，文件覆盖控制
+- `--port`、`--host`、`--no-browser`：preview 特有
+
+## Risks / Trade-offs
+
+### 风险 1：破坏性变更影响现有用户
+
+**风险：** 移除传统模式和 `convert --preview` 会导致现有脚本失效
+
+**缓解措施：**
+- 项目未上线，无现有用户
+- 更新所有文档和示例
+- 在错误信息中提示新的使用方式（如检测到 `--preview` 时提示使用 `preview` 子命令）
+
+### 风险 2：随机端口可能导致防火墙问题
+
+**风险：** 随机端口可能被防火墙阻止
+
+**缓解措施：**
+- 用户可以通过 `--port` 指定固定端口
+- 在文档中说明端口范围（30000-40000）
+- 默认 host 为 127.0.0.1，仅本地访问
+
+### 风险 3：参数验证逻辑需要重新实现
+
+**风险：** 移除双模式后，参数验证逻辑需要调整
+
+**缓解措施：**
+- 在 `main()` 函数中统一验证输入文件存在性
+- 在 `handle_convert()` 中验证输出文件覆盖逻辑
+- 在 `handle_preview()` 中验证端口合法性
+
+## Migration Plan
+
+### 实施步骤
+
+1. **重构 `parse_args()` 函数**
+   - 移除双模式检查逻辑
+   - 使用 `subparsers.add_parser()` 定义三个子命令
+   - 为每个子命令配置独立的参数
+
+2. **更新 `handle_convert()` 函数**
+   - 移除 `--preview` 相关逻辑
+   - 添加输出文件存在性检查（`--force` 控制）
+   - 保持自动验证逻辑（`--skip-validation` 控制）
+
+3. **创建 `handle_preview()` 函数**
+   - 从 `handle_convert()` 中提取 preview 逻辑
+   - 添加随机端口生成逻辑
+   - 调用 `start_preview_server()` 时传递新参数
+
+4. **更新 `preview/server.py`**
+   - 修改 `start_preview_server()` 函数签名
+   - 添加 `host` 参数（默认 127.0.0.1）
+   - 添加 `open_browser` 参数（默认 True）
+   - 更新端口随机生成逻辑（30000-40000）
+
+5. **更新文档**
+   - 更新 `README.md` 中的所有使用示例
+   - 更新命令行选项说明表格
+   - 添加迁移指南（如果需要）
+
+### 回滚策略
+
+如果发现重大问题，可以：
+1. 回退到上一个 commit
+2. 保留新的子命令架构，但临时添加传统模式兼容层
+3. 通过环境变量或配置文件控制行为
+
+## Open Questions
+
+无待解决的问题。设计已经明确，可以开始实施。
--- a/openspec/changes/archive/2026-03-02-refactor-cli-args/proposal.md
+++ b/openspec/changes/archive/2026-03-02-refactor-cli-args/proposal.md
@@ -0,0 +1,37 @@
+## Why
+
+当前 CLI 结构存在混乱：双模式解析（子命令模式和传统模式）增加了代码复杂度，preview 作为 convert 的一个标志导致职责不清晰。需要建立清晰的子命令架构，提升用户体验和代码可维护性。
+
+## What Changes
+
+- **BREAKING**: 移除传统模式（直接 `yaml2pptx.py input.yaml output.pptx`），统一使用子命令模式
+- **BREAKING**: 将 preview 从 convert 的 `--preview` 标志独立为 `preview` 子命令
+- 重命名参数：`--no-check` → `--skip-validation`（更清晰的语义）
+- 新增 `--force/-f` 参数：convert 命令支持强制覆盖已存在文件
+- 新增 `--host` 参数：preview 命令支持配置主机地址（支持局域网预览）
+- 新增 `--no-browser` 参数：preview 命令支持不自动打开浏览器
+- 优化 `--port` 默认值：从固定 5000 改为随机端口（30000-40000）
+- 简化参数：移除不必要的 `--verbose`、`--quiet`、`--strict`、`--format`、`--no-watch` 等参数
+
+## Capabilities
+
+### New Capabilities
+
+- `cli-interface`: 命令行接口规范，定义 check、convert、preview 三个子命令的参数、行为和交互方式
+
+### Modified Capabilities
+
+- `browser-preview-server`: 预览服务器的启动方式和参数配置发生变化，从 convert 的标志变为独立子命令，新增 host、no-browser 等配置选项
+
+## Impact
+
+**受影响的代码：**
+- `yaml2pptx.py`：完全重构参数解析逻辑，移除双模式支持
+- `preview/server.py`：修改 `start_preview_server` 函数签名，支持 host 和 open_browser 参数
+
+**破坏性变更：**
+- 用户需要从传统模式迁移到子命令模式
+- 使用 `convert --preview` 的用户需要改用 `preview` 子命令
+
+**文档更新：**
+- `README.md`：更新所有使用示例和命令行选项说明
--- a/openspec/changes/archive/2026-03-02-refactor-cli-args/specs/browser-preview-server/spec.md
+++ b/openspec/changes/archive/2026-03-02-refactor-cli-args/specs/browser-preview-server/spec.md
@@ -0,0 +1,74 @@
+# Browser Preview Server (Delta Spec)
+
+## MODIFIED Requirements
+
+### Requirement: 系统必须支持通过独立子命令启用预览模式
+
+系统 SHALL 通过独立的 `preview` 子命令启用浏览器预览模式，而不是作为 convert 命令的参数。
+
+#### Scenario: 使用 preview 子命令启动预览服务器
+
+- **WHEN** 用户运行 `uv run yaml2pptx.py preview input.yaml`
+- **THEN** 系统启动预览服务器
+
+#### Scenario: convert 命令不再支持 --preview 参数
+
+- **WHEN** 用户运行 `uv run yaml2pptx.py convert input.yaml --preview`
+- **THEN** 系统报错，提示使用 `preview` 子命令
+
+#### Scenario: preview 子命令与其他参数兼容
+
+- **WHEN** 用户运行 `uv run yaml2pptx.py preview input.yaml --template-dir templates`
+- **THEN** 系统启动预览服务器，并使用指定的模板目录
+
+### Requirement: 系统必须提供 HTTP 服务
+
+系统 SHALL 使用 Flask 启动 HTTP 服务器，监听指定端口，提供预览页面。
+
+#### Scenario: 启动 HTTP 服务器（随机端口）
+
+- **WHEN** 预览模式启动且未指定端口
+- **THEN** 系统在 30000-40000 范围内随机选择端口启动 Flask HTTP 服务器
+
+#### Scenario: 自定义端口
+
+- **WHEN** 用户使用 `--port 8080` 参数
+- **THEN** 系统在端口 8080 启动 HTTP 服务器
+
+#### Scenario: 配置主机地址
+
+- **WHEN** 用户使用 `--host 0.0.0.0` 参数
+- **THEN** 系统在 0.0.0.0 启动 HTTP 服务器，允许局域网访问
+
+#### Scenario: 端口被占用时报错
+
+- **WHEN** 指定的端口已被其他服务占用
+- **THEN** 系统抛出错误，提示端口被占用，建议使用 `--port` 参数指定其他端口
+
+#### Scenario: 提供主页面路由
+
+- **WHEN** 浏览器访问服务器根路径
+- **THEN** 系统返回包含所有幻灯片预览的 HTML 页面
+
+### Requirement: 系统必须支持控制浏览器自动打开
+
+系统 SHALL 支持通过参数控制是否自动打开浏览器。
+
+#### Scenario: 默认自动打开浏览器
+
+- **WHEN** 预览服务器启动成功且未使用 --no-browser 参数
+- **THEN** 系统自动在默认浏览器中打开预览页面
+
+#### Scenario: 不自动打开浏览器
+
+- **WHEN** 用户使用 `--no-browser` 参数
+- **THEN** 系统启动服务器但不自动打开浏览器，仅在终端输出预览 URL
+
+#### Scenario: 浏览器打开失败时提示 URL
+
+- **WHEN** 系统无法自动打开浏览器（如无图形界面环境）
+- **THEN** 系统在终端输出预览 URL，提示用户手动打开
+
+## REMOVED Requirements
+
+无移除的需求。其他需求（文件监听、SSE 推送、错误处理等）保持不变。
--- a/openspec/changes/archive/2026-03-02-refactor-cli-args/specs/cli-interface/spec.md
+++ b/openspec/changes/archive/2026-03-02-refactor-cli-args/specs/cli-interface/spec.md
@@ -0,0 +1,184 @@
+# CLI Interface
+
+## Purpose
+
+CLI Interface 定义 yaml2pptx 命令行工具的用户交互界面，包括子命令结构、参数规范、行为约定和错误处理。它确保用户能够通过清晰、一致的命令行接口使用工具的所有功能。
+
+## ADDED Requirements
+
+### Requirement: 系统必须使用子命令架构
+
+系统 SHALL 采用子命令架构，提供 check、convert、preview 三个独立子命令，每个子命令有明确的职责。
+
+#### Scenario: 使用 check 子命令验证文件
+
+- **WHEN** 用户运行 `uv run yaml2pptx.py check input.yaml`
+- **THEN** 系统验证 YAML 文件并输出验证结果
+
+#### Scenario: 使用 convert 子命令转换文件
+
+- **WHEN** 用户运行 `uv run yaml2pptx.py convert input.yaml`
+- **THEN** 系统将 YAML 文件转换为 PPTX 文件
+
+#### Scenario: 使用 preview 子命令启动预览
+
+- **WHEN** 用户运行 `uv run yaml2pptx.py preview input.yaml`
+- **THEN** 系统启动预览服务器
+
+#### Scenario: 不提供子命令时显示帮助
+
+- **WHEN** 用户运行 `uv run yaml2pptx.py`
+- **THEN** 系统显示帮助信息，列出所有可用子命令
+
+### Requirement: check 子命令必须验证 YAML 文件
+
+系统 SHALL 提供 check 子命令，用于验证 YAML 文件的正确性，输出 ERROR/WARNING/INFO 三级分类的验证结果。
+
+#### Scenario: 基本验证
+
+- **WHEN** 用户运行 `uv run yaml2pptx.py check input.yaml`
+- **THEN** 系统验证文件并输出文本格式的验证结果
+
+#### Scenario: 使用模板目录验证
+
+- **WHEN** 用户运行 `uv run yaml2pptx.py check input.yaml --template-dir ./templates`
+- **THEN** 系统使用指定的模板目录进行验证
+
+#### Scenario: 验证通过时返回退出码 0
+
+- **WHEN** 验证完成且无错误
+- **THEN** 系统返回退出码 0
+
+#### Scenario: 验证失败时返回退出码 1
+
+- **WHEN** 验证发现错误
+- **THEN** 系统返回退出码 1
+
+### Requirement: convert 子命令必须转换 YAML 为 PPTX
+
+系统 SHALL 提供 convert 子命令，将 YAML 文件转换为 PPTX 文件，支持自动验证和文件覆盖控制。
+
+#### Scenario: 基本转换（自动生成输出文件名）
+
+- **WHEN** 用户运行 `uv run yaml2pptx.py convert input.yaml`
+- **THEN** 系统生成 `input.pptx` 文件
+
+#### Scenario: 指定输出文件名
+
+- **WHEN** 用户运行 `uv run yaml2pptx.py convert input.yaml output.pptx`
+- **THEN** 系统生成 `output.pptx` 文件
+
+#### Scenario: 使用模板目录转换
+
+- **WHEN** 用户运行 `uv run yaml2pptx.py convert input.yaml --template-dir ./templates`
+- **THEN** 系统使用指定的模板目录进行转换
+
+#### Scenario: 默认自动验证
+
+- **WHEN** 用户运行 `uv run yaml2pptx.py convert input.yaml`
+- **THEN** 系统先验证 YAML 文件，发现错误时终止转换
+
+#### Scenario: 跳过自动验证
+
+- **WHEN** 用户运行 `uv run yaml2pptx.py convert input.yaml --skip-validation`
+- **THEN** 系统跳过验证，直接转换
+
+#### Scenario: 输出文件已存在时报错
+
+- **WHEN** 输出文件已存在且未使用 --force 参数
+- **THEN** 系统报错并提示使用 --force 强制覆盖
+
+#### Scenario: 强制覆盖已存在文件
+
+- **WHEN** 用户运行 `uv run yaml2pptx.py convert input.yaml output.pptx --force`
+- **THEN** 系统覆盖已存在的 output.pptx 文件
+
+### Requirement: preview 子命令必须启动预览服务器
+
+系统 SHALL 提供 preview 子命令，启动预览服务器，支持端口配置、主机配置和浏览器控制。
+
+#### Scenario: 基本预览（随机端口）
+
+- **WHEN** 用户运行 `uv run yaml2pptx.py preview input.yaml`
+- **THEN** 系统在随机端口（30000-40000）启动预览服务器并自动打开浏览器
+
+#### Scenario: 指定端口
+
+- **WHEN** 用户运行 `uv run yaml2pptx.py preview input.yaml --port 8080`
+- **THEN** 系统在端口 8080 启动预览服务器
+
+#### Scenario: 配置主机地址（局域网预览）
+
+- **WHEN** 用户运行 `uv run yaml2pptx.py preview input.yaml --host 0.0.0.0`
+- **THEN** 系统在 0.0.0.0 启动服务器，允许局域网访问
+
+#### Scenario: 不自动打开浏览器
+
+- **WHEN** 用户运行 `uv run yaml2pptx.py preview input.yaml --no-browser`
+- **THEN** 系统启动服务器但不自动打开浏览器
+
+#### Scenario: 使用模板目录预览
+
+- **WHEN** 用户运行 `uv run yaml2pptx.py preview input.yaml --template-dir ./templates`
+- **THEN** 系统使用指定的模板目录进行预览
+
+### Requirement: 系统必须提供 --template-dir 通用参数
+
+系统 SHALL 在所有子命令中提供 --template-dir 参数，用于指定模板文件目录。
+
+#### Scenario: check 命令使用模板目录
+
+- **WHEN** 用户运行 `uv run yaml2pptx.py check input.yaml --template-dir ./templates`
+- **THEN** 系统使用指定的模板目录进行验证
+
+#### Scenario: convert 命令使用模板目录
+
+- **WHEN** 用户运行 `uv run yaml2pptx.py convert input.yaml --template-dir ./templates`
+- **THEN** 系统使用指定的模板目录进行转换
+
+#### Scenario: preview 命令使用模板目录
+
+- **WHEN** 用户运行 `uv run yaml2pptx.py preview input.yaml --template-dir ./templates`
+- **THEN** 系统使用指定的模板目录进行预览
+
+### Requirement: 系统必须验证输入文件存在性
+
+系统 SHALL 在执行任何操作前验证输入文件是否存在，不存在时报错并退出。
+
+#### Scenario: 输入文件不存在时报错
+
+- **WHEN** 用户指定的输入文件不存在
+- **THEN** 系统输出错误信息 "输入文件不存在: <文件路径>" 并返回退出码 1
+
+#### Scenario: 输入文件存在时继续执行
+
+- **WHEN** 用户指定的输入文件存在
+- **THEN** 系统继续执行相应的子命令操作
+
+### Requirement: 系统必须提供清晰的帮助信息
+
+系统 SHALL 为每个子命令提供清晰的帮助信息，包括参数说明和使用示例。
+
+#### Scenario: 显示全局帮助
+
+- **WHEN** 用户运行 `uv run yaml2pptx.py --help`
+- **THEN** 系统显示工具描述和所有可用子命令列表
+
+#### Scenario: 显示子命令帮助
+
+- **WHEN** 用户运行 `uv run yaml2pptx.py check --help`
+- **THEN** 系统显示 check 子命令的参数说明和使用示例
+
+### Requirement: 系统必须提供短选项支持
+
+系统 SHALL 为常用参数提供短选项，提升用户体验。
+
+#### Scenario: 使用 -f 作为 --force 的短选项
+
+- **WHEN** 用户运行 `uv run yaml2pptx.py convert input.yaml -f`
+- **THEN** 系统强制覆盖已存在文件
+
+#### Scenario: 短选项和长选项等效
+
+- **WHEN** 用户使用 -f 或 --force
+- **THEN** 系统行为完全一致
--- a/openspec/changes/archive/2026-03-02-refactor-cli-args/tasks.md
+++ b/openspec/changes/archive/2026-03-02-refactor-cli-args/tasks.md
@@ -0,0 +1,65 @@
+## 1. 重构参数解析逻辑
+
+- [x] 1.1 移除 `parse_args()` 中的双模式检查逻辑（删除 `sys.argv[1]` 检查）
+- [x] 1.2 使用 `subparsers.add_parser()` 创建 check 子命令解析器
+- [x] 1.3 使用 `subparsers.add_parser()` 创建 convert 子命令解析器
+- [x] 1.4 使用 `subparsers.add_parser()` 创建 preview 子命令解析器
+- [x] 1.5 为 convert 子命令添加 `--force/-f` 参数
+- [x] 1.6 将 convert 子命令的 `--no-check` 重命名为 `--skip-validation`
+- [x] 1.7 移除 convert 子命令的 `--preview` 和 `--port` 参数
+- [x] 1.8 为 preview 子命令添加 `--port`、`--host`、`--no-browser` 参数
+
+## 2. 更新 convert 命令处理逻辑
+
+- [x] 2.1 从 `handle_convert()` 中移除 preview 相关逻辑
+- [x] 2.2 在 `handle_convert()` 中添加输出文件存在性检查
+- [x] 2.3 实现 `--force` 参数逻辑（已存在文件时检查是否有 --force）
+- [x] 2.4 更新 `--skip-validation` 参数的处理（原 --no-check）
+
+## 3. 创建 preview 命令处理逻辑
+
+- [x] 3.1 创建 `handle_preview()` 函数
+- [x] 3.2 实现随机端口生成逻辑（30000-40000 范围）
+- [x] 3.3 处理 `--port` 参数（用户指定时使用指定端口）
+- [x] 3.4 处理 `--host` 参数（默认 127.0.0.1）
+- [x] 3.5 处理 `--no-browser` 参数（控制是否自动打开浏览器）
+- [x] 3.6 调用 `start_preview_server()` 并传递新参数
+
+## 4. 更新预览服务器模块
+
+- [x] 4.1 修改 `start_preview_server()` 函数签名，添加 `host` 参数
+- [x] 4.2 修改 `start_preview_server()` 函数签名，添加 `open_browser` 参数
+- [x] 4.3 更新 Flask 服务器启动逻辑，使用传入的 `host` 参数
+- [x] 4.4 更新浏览器自动打开逻辑，根据 `open_browser` 参数决定是否打开
+- [x] 4.5 移除或更新端口随机生成逻辑（现在由调用方处理）
+
+## 5. 更新主函数路由逻辑
+
+- [x] 5.1 更新 `main()` 函数，根据 `args.command` 路由到对应的处理函数
+- [x] 5.2 确保 check 命令路由到 `handle_check()`
+- [x] 5.3 确保 convert 命令路由到 `handle_convert()`
+- [x] 5.4 确保 preview 命令路由到 `handle_preview()`
+- [x] 5.5 移除传统模式的兼容逻辑（`args.command is None` 的处理）
+
+## 6. 更新文档
+
+- [x] 6.1 更新 README.md 中的"快速开始"部分，移除传统模式示例
+- [x] 6.2 更新 README.md 中的"实时预览"部分，使用 `preview` 子命令
+- [x] 6.3 更新 README.md 中的"命令行选项"表格，反映新的参数结构
+- [x] 6.4 更新 README.md 中的所有使用示例
+- [x] 6.5 更新 `yaml2pptx.py` 文件顶部的 docstring 使用说明
+
+## 7. 测试验证
+
+- [x] 7.1 测试 check 子命令基本功能
+- [x] 7.2 测试 check 子命令的 --template-dir 参数
+- [x] 7.3 测试 convert 子命令基本功能（自动生成输出文件名）
+- [x] 7.4 测试 convert 子命令指定输出文件名
+- [x] 7.5 测试 convert 子命令的 --force 参数（覆盖已存在文件）
+- [x] 7.6 测试 convert 子命令的 --skip-validation 参数
+- [x] 7.7 测试 preview 子命令基本功能（随机端口）
+- [x] 7.8 测试 preview 子命令的 --port 参数
+- [x] 7.9 测试 preview 子命令的 --host 参数
+- [x] 7.10 测试 preview 子命令的 --no-browser 参数
+- [x] 7.11 验证输入文件不存在时的错误提示
+- [x] 7.12 验证输出文件已存在且未使用 --force 时的错误提示