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/specs/browser-preview-server/spec.md
+++ b/openspec/specs/browser-preview-server/spec.md
@@ -6,39 +6,44 @@ Browser Preview Server 负责提供浏览器实时预览功能，包括启动 We

 ## Requirements

-### Requirement: 系统必须支持通过命令行参数启用预览模式
+### Requirement: 系统必须支持通过独立子命令启用预览模式

-系统 SHALL 在 `yaml2pptx.py` 中提供 `--preview` 参数，启用浏览器预览模式。
+系统 SHALL 通过独立的 `preview` 子命令启用浏览器预览模式，而不是作为 convert 命令的参数。

-#### Scenario: 使用 --preview 参数启动预览服务器
+#### Scenario: 使用 preview 子命令启动预览服务器

- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml --preview`
- **THEN** 系统启动预览服务器，而不是生成 PPTX 文件
+- **WHEN** 用户运行 `uv run yaml2pptx.py preview input.yaml`
+- **THEN** 系统启动预览服务器

-#### Scenario: 不使用 --preview 参数时保持原有行为
+#### Scenario: convert 命令不再支持 --preview 参数

- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml`
- **THEN** 系统生成 PPTX 文件，不启动预览服务器
+- **WHEN** 用户运行 `uv run yaml2pptx.py convert input.yaml --preview`
+- **THEN** 系统报错，提示使用 `preview` 子命令

-#### Scenario: --preview 参数与其他参数兼容
+#### Scenario: preview 子命令与其他参数兼容

- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml --preview --template-dir templates`
+- **WHEN** 用户运行 `uv run yaml2pptx.py preview input.yaml --template-dir templates`
 - **THEN** 系统启动预览服务器，并使用指定的模板目录

 ### Requirement: 系统必须提供 HTTP 服务

 系统 SHALL 使用 Flask 启动 HTTP 服务器，监听指定端口，提供预览页面。

-#### Scenario: 启动 HTTP 服务器
+#### Scenario: 启动 HTTP 服务器（随机端口）

- **WHEN** 预览模式启动
- **THEN** 系统在默认端口 5000 启动 Flask 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** 指定的端口已被其他服务占用
@@ -46,7 +51,7 @@ Browser Preview Server 负责提供浏览器实时预览功能，包括启动 We

 #### Scenario: 提供主页面路由

- **WHEN** 浏览器访问 `http://localhost:5000/`
+- **WHEN** 浏览器访问服务器根路径
 - **THEN** 系统返回包含所有幻灯片预览的 HTML 页面

 ### Requirement: 系统必须监听 YAML 文件变化
@@ -97,14 +102,19 @@ Browser Preview Server 负责提供浏览器实时预览功能，包括启动 We
 - **WHEN** SSE 连接因网络问题断开
 - **THEN** 浏览器自动尝试重新连接到 SSE 端点

-### Requirement: 系统必须自动打开浏览器
+### Requirement: 系统必须支持控制浏览器自动打开

-系统 SHALL 在预览服务器启动后，自动在默认浏览器中打开预览页面。
+系统 SHALL 支持通过参数控制是否自动打开浏览器。

-#### Scenario: 启动后自动打开浏览器
+#### Scenario: 默认自动打开浏览器

- **WHEN** 预览服务器启动成功
- **THEN** 系统自动在默认浏览器中打开 `http://localhost:5000/`
+- **WHEN** 预览服务器启动成功且未使用 --no-browser 参数
+- **THEN** 系统自动在默认浏览器中打开预览页面
+
+#### Scenario: 不自动打开浏览器
+
+- **WHEN** 用户使用 `--no-browser` 参数
+- **THEN** 系统启动服务器但不自动打开浏览器，仅在终端输出预览 URL

 #### Scenario: 浏览器打开失败时提示 URL

--- a/openspec/specs/cli-interface/spec.md
+++ b/openspec/specs/cli-interface/spec.md
@@ -0,0 +1,184 @@
+# CLI Interface
+
+## Purpose
+
+CLI Interface 定义 yaml2pptx 命令行工具的用户交互界面，包括子命令结构、参数规范、行为约定和错误处理。它确保用户能够通过清晰、一致的命令行接口使用工具的所有功能。
+
+## 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** 系统行为完全一致