1
0

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:
2026-03-02 18:47:50 +08:00
parent 83ff827ad1
commit 66472cbd86
13 changed files with 934 additions and 112 deletions

View File

@@ -0,0 +1,37 @@
## Why
当前 CLI 结构存在混乱双模式解析子命令模式和传统模式增加了代码复杂度preview 作为 convert 的一个标志导致职责不清晰。需要建立清晰的子命令架构,提升用户体验和代码可维护性。
## What Changes
- **BREAKING**: 移除传统模式(直接 `yaml2pptx.py input.yaml output.pptx`),统一使用子命令模式
- **BREAKING**: 将 preview 从 convert 的 `--preview` 标志独立为 `preview` 子命令
- 重命名参数:`--no-check``--skip-validation`(更清晰的语义)
- 新增 `--force/-f` 参数convert 命令支持强制覆盖已存在文件
- 新增 `--host` 参数preview 命令支持配置主机地址(支持局域网预览)
- 新增 `--no-browser` 参数preview 命令支持不自动打开浏览器
- 优化 `--port` 默认值:从固定 5000 改为随机端口30000-40000
- 简化参数:移除不必要的 `--verbose``--quiet``--strict``--format``--no-watch` 等参数
## Capabilities
### New Capabilities
- `cli-interface`: 命令行接口规范,定义 check、convert、preview 三个子命令的参数、行为和交互方式
### Modified Capabilities
- `browser-preview-server`: 预览服务器的启动方式和参数配置发生变化,从 convert 的标志变为独立子命令,新增 host、no-browser 等配置选项
## Impact
**受影响的代码:**
- `yaml2pptx.py`:完全重构参数解析逻辑,移除双模式支持
- `preview/server.py`:修改 `start_preview_server` 函数签名,支持 host 和 open_browser 参数
**破坏性变更:**
- 用户需要从传统模式迁移到子命令模式
- 使用 `convert --preview` 的用户需要改用 `preview` 子命令
**文档更新:**
- `README.md`:更新所有使用示例和命令行选项说明