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:
184
openspec/specs/cli-interface/spec.md
Normal file
184
openspec/specs/cli-interface/spec.md
Normal 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** 系统行为完全一致
|
||||
Reference in New Issue
Block a user