1
0

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 任务完成)
This commit is contained in:
2026-03-02 18:47:50 +08:00
parent 83ff827ad1
commit 66472cbd86
13 changed files with 934 additions and 112 deletions

View File

@@ -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** 系统行为完全一致