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:
54
README.md
54
README.md
@@ -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` | 不自动打开浏览器 |
|
||||
|
||||
## 📐 坐标系统
|
||||
|
||||
|
||||
Reference in New Issue
Block a user