lanyuanxiaoyao
66472cbd86
重构命令行接口，建立清晰的子命令架构，提升用户体验和代码可维护性。 主要变更： - 移除传统模式，统一使用子命令架构（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 任务完成）
66 lines
3.3 KiB
Markdown
66 lines
3.3 KiB
Markdown
## 1. 重构参数解析逻辑
|
||
|
||
- [x] 1.1 移除 `parse_args()` 中的双模式检查逻辑（删除 `sys.argv[1]` 检查）
|
||
- [x] 1.2 使用 `subparsers.add_parser()` 创建 check 子命令解析器
|
||
- [x] 1.3 使用 `subparsers.add_parser()` 创建 convert 子命令解析器
|
||
- [x] 1.4 使用 `subparsers.add_parser()` 创建 preview 子命令解析器
|
||
- [x] 1.5 为 convert 子命令添加 `--force/-f` 参数
|
||
- [x] 1.6 将 convert 子命令的 `--no-check` 重命名为 `--skip-validation`
|
||
- [x] 1.7 移除 convert 子命令的 `--preview` 和 `--port` 参数
|
||
- [x] 1.8 为 preview 子命令添加 `--port`、`--host`、`--no-browser` 参数
|
||
|
||
## 2. 更新 convert 命令处理逻辑
|
||
|
||
- [x] 2.1 从 `handle_convert()` 中移除 preview 相关逻辑
|
||
- [x] 2.2 在 `handle_convert()` 中添加输出文件存在性检查
|
||
- [x] 2.3 实现 `--force` 参数逻辑（已存在文件时检查是否有 --force）
|
||
- [x] 2.4 更新 `--skip-validation` 参数的处理（原 --no-check）
|
||
|
||
## 3. 创建 preview 命令处理逻辑
|
||
|
||
- [x] 3.1 创建 `handle_preview()` 函数
|
||
- [x] 3.2 实现随机端口生成逻辑（30000-40000 范围）
|
||
- [x] 3.3 处理 `--port` 参数（用户指定时使用指定端口）
|
||
- [x] 3.4 处理 `--host` 参数（默认 127.0.0.1）
|
||
- [x] 3.5 处理 `--no-browser` 参数（控制是否自动打开浏览器）
|
||
- [x] 3.6 调用 `start_preview_server()` 并传递新参数
|
||
|
||
## 4. 更新预览服务器模块
|
||
|
||
- [x] 4.1 修改 `start_preview_server()` 函数签名，添加 `host` 参数
|
||
- [x] 4.2 修改 `start_preview_server()` 函数签名，添加 `open_browser` 参数
|
||
- [x] 4.3 更新 Flask 服务器启动逻辑，使用传入的 `host` 参数
|
||
- [x] 4.4 更新浏览器自动打开逻辑，根据 `open_browser` 参数决定是否打开
|
||
- [x] 4.5 移除或更新端口随机生成逻辑（现在由调用方处理）
|
||
|
||
## 5. 更新主函数路由逻辑
|
||
|
||
- [x] 5.1 更新 `main()` 函数，根据 `args.command` 路由到对应的处理函数
|
||
- [x] 5.2 确保 check 命令路由到 `handle_check()`
|
||
- [x] 5.3 确保 convert 命令路由到 `handle_convert()`
|
||
- [x] 5.4 确保 preview 命令路由到 `handle_preview()`
|
||
- [x] 5.5 移除传统模式的兼容逻辑（`args.command is None` 的处理）
|
||
|
||
## 6. 更新文档
|
||
|
||
- [x] 6.1 更新 README.md 中的"快速开始"部分，移除传统模式示例
|
||
- [x] 6.2 更新 README.md 中的"实时预览"部分，使用 `preview` 子命令
|
||
- [x] 6.3 更新 README.md 中的"命令行选项"表格，反映新的参数结构
|
||
- [x] 6.4 更新 README.md 中的所有使用示例
|
||
- [x] 6.5 更新 `yaml2pptx.py` 文件顶部的 docstring 使用说明
|
||
|
||
## 7. 测试验证
|
||
|
||
- [x] 7.1 测试 check 子命令基本功能
|
||
- [x] 7.2 测试 check 子命令的 --template-dir 参数
|
||
- [x] 7.3 测试 convert 子命令基本功能（自动生成输出文件名）
|
||
- [x] 7.4 测试 convert 子命令指定输出文件名
|
||
- [x] 7.5 测试 convert 子命令的 --force 参数（覆盖已存在文件）
|
||
- [x] 7.6 测试 convert 子命令的 --skip-validation 参数
|
||
- [x] 7.7 测试 preview 子命令基本功能（随机端口）
|
||
- [x] 7.8 测试 preview 子命令的 --port 参数
|
||
- [x] 7.9 测试 preview 子命令的 --host 参数
|
||
- [x] 7.10 测试 preview 子命令的 --no-browser 参数
|
||
- [x] 7.11 验证输入文件不存在时的错误提示
|
||
- [x] 7.12 验证输出文件已存在且未使用 --force 时的错误提示
|