lanyuanxiaoyao/PPTX
1
0
Fork 0
Code Activity
Files
master
PPTX/openspec/changes/archive/2026-03-02-refactor-cli-args/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

6.4 KiB
Raw Permalink Blame History

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 系统行为完全一致
View Git Blame Copy Permalink