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

3.3 KiB
Raw Blame History

1. 重构参数解析逻辑

  • 1.1 移除 parse_args() 中的双模式检查逻辑（删除 sys.argv[1] 检查）
  • 1.2 使用 subparsers.add_parser() 创建 check 子命令解析器
  • 1.3 使用 subparsers.add_parser() 创建 convert 子命令解析器
  • 1.4 使用 subparsers.add_parser() 创建 preview 子命令解析器
  • 1.5 为 convert 子命令添加 --force/-f 参数
  • 1.6 将 convert 子命令的 --no-check 重命名为 --skip-validation
  • 1.7 移除 convert 子命令的 --preview 和 --port 参数
  • 1.8 为 preview 子命令添加 --port、--host、--no-browser 参数

2. 更新 convert 命令处理逻辑

  • 2.1 从 handle_convert() 中移除 preview 相关逻辑
  • 2.2 在 handle_convert() 中添加输出文件存在性检查
  • 2.3 实现 --force 参数逻辑（已存在文件时检查是否有 --force）
  • 2.4 更新 --skip-validation 参数的处理（原 --no-check）

3. 创建 preview 命令处理逻辑

  • 3.1 创建 handle_preview() 函数
  • 3.2 实现随机端口生成逻辑（30000-40000 范围）
  • 3.3 处理 --port 参数（用户指定时使用指定端口）
  • 3.4 处理 --host 参数（默认 127.0.0.1）
  • 3.5 处理 --no-browser 参数（控制是否自动打开浏览器）
  • 3.6 调用 start_preview_server() 并传递新参数

4. 更新预览服务器模块

  • 4.1 修改 start_preview_server() 函数签名，添加 host 参数
  • 4.2 修改 start_preview_server() 函数签名，添加 open_browser 参数
  • 4.3 更新 Flask 服务器启动逻辑，使用传入的 host 参数
  • 4.4 更新浏览器自动打开逻辑，根据 open_browser 参数决定是否打开
  • 4.5 移除或更新端口随机生成逻辑（现在由调用方处理）

5. 更新主函数路由逻辑

  • 5.1 更新 main() 函数，根据 args.command 路由到对应的处理函数
  • 5.2 确保 check 命令路由到 handle_check()
  • 5.3 确保 convert 命令路由到 handle_convert()
  • 5.4 确保 preview 命令路由到 handle_preview()
  • 5.5 移除传统模式的兼容逻辑（args.command is None 的处理）

6. 更新文档

  • 6.1 更新 README.md 中的"快速开始"部分，移除传统模式示例
  • 6.2 更新 README.md 中的"实时预览"部分，使用 preview 子命令
  • 6.3 更新 README.md 中的"命令行选项"表格，反映新的参数结构
  • 6.4 更新 README.md 中的所有使用示例
  • 6.5 更新 yaml2pptx.py 文件顶部的 docstring 使用说明

7. 测试验证

  • 7.1 测试 check 子命令基本功能
  • 7.2 测试 check 子命令的 --template-dir 参数
  • 7.3 测试 convert 子命令基本功能（自动生成输出文件名）
  • 7.4 测试 convert 子命令指定输出文件名
  • 7.5 测试 convert 子命令的 --force 参数（覆盖已存在文件）
  • 7.6 测试 convert 子命令的 --skip-validation 参数
  • 7.7 测试 preview 子命令基本功能（随机端口）
  • 7.8 测试 preview 子命令的 --port 参数
  • 7.9 测试 preview 子命令的 --host 参数
  • 7.10 测试 preview 子命令的 --no-browser 参数
  • 7.11 验证输入文件不存在时的错误提示
  • 7.12 验证输出文件已存在且未使用 --force 时的错误提示
View Git Blame Copy Permalink