lanyuanxiaoyao/PPTX
1
0
Fork 0
Code Activity
Files
0a804eacc8fce6410c9923edd2858ecca807b9f1
PPTX/openspec/specs/cli-interface/spec.md
lanyuanxiaoyao 66472cbd86 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

185 lines
6.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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** 系统行为完全一致
View Git Blame Copy Permalink