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 任务完成）
38 lines
1.8 KiB
Markdown
38 lines
1.8 KiB
Markdown
## 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`：更新所有使用示例和命令行选项说明
|