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

@@ -21,7 +21,7 @@
### 基本用法
```bash
# 使用 convert 子命令(推荐)
# 转换 YAML 为 PPTX
uv run yaml2pptx.py convert presentation.yaml output.pptx
# 自动生成输出文件名
@@ -29,22 +29,22 @@ uv run yaml2pptx.py convert presentation.yaml
# 使用模板
uv run yaml2pptx.py convert presentation.yaml output.pptx --template-dir ./templates
# 传统用法(向后兼容)
uv run yaml2pptx.py presentation.yaml output.pptx
```
### 实时预览
```bash
# 启动预览服务器(自动打开浏览器)
uv run yaml2pptx.py convert presentation.yaml --preview
uv run yaml2pptx.py preview presentation.yaml
# 指定端口
uv run yaml2pptx.py convert presentation.yaml --preview --port 8080
uv run yaml2pptx.py preview presentation.yaml --port 8080
# 传统用法(向后兼容)
uv run yaml2pptx.py presentation.yaml --preview
# 允许局域网访问
uv run yaml2pptx.py preview presentation.yaml --host 0.0.0.0
# 不自动打开浏览器
uv run yaml2pptx.py preview presentation.yaml --no-browser
```
预览模式会自动监听文件变化,修改 YAML 文件后浏览器会自动刷新。
@@ -69,14 +69,11 @@ uv run yaml2pptx.py check presentation.yaml --template-dir ./templates
- ✅ 字体大小是否合理
- ✅ 表格数据是否一致
**自动验证**:转换时默认会自动验证,如果发现错误会终止转换。可以使用 `--no-check` 跳过验证:
**自动验证**:转换时默认会自动验证,如果发现错误会终止转换。可以使用 `--skip-validation` 跳过验证:
```bash
# 跳过自动验证convert 子命令)
uv run yaml2pptx.py convert presentation.yaml --no-check
# 跳过自动验证(传统用法)
uv run yaml2pptx.py presentation.yaml --no-check
# 跳过自动验证
uv run yaml2pptx.py convert presentation.yaml --skip-validation
```
**验证结果示例**
@@ -260,13 +257,38 @@ slides:
## 🎯 命令行选项
### check 命令
验证 YAML 文件的正确性。
| 选项 | 说明 |
|------|------|
| `input` | 输入的 YAML 文件路径(必需) |
| `--template-dir` | 模板文件目录 |
### convert 命令
将 YAML 文件转换为 PPTX 文件。
| 选项 | 说明 |
|------|------|
| `input` | 输入的 YAML 文件路径(必需) |
| `output` | 输出的 PPTX 文件路径(可选) |
| `--template-dir` | 模板文件目录 |
| `--preview` | 启用浏览器预览模式 |
| `--port` | 预览服务器端口(默认:随机) |
| `--skip-validation` | 跳过自动验证 |
| `--force` / `-f` | 强制覆盖已存在文件 |
### preview 命令
启动预览服务器,实时查看演示文稿效果。
| 选项 | 说明 |
|------|------|
| `input` | 输入的 YAML 文件路径(必需) |
| `--template-dir` | 模板文件目录 |
| `--port` | 服务器端口(默认:随机端口 30000-40000 |
| `--host` | 主机地址默认127.0.0.1 |
| `--no-browser` | 不自动打开浏览器 |
## 📐 坐标系统