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

@@ -189,18 +189,40 @@ python yaml2pptx.py input.yaml output.pptx
- 所有依赖在 `yaml2pptx.py``/// script` 头部声明
- uv 会自动安装依赖,无需手动 `pip install`
### 2. 文件组织
### 2. 命令行接口
**子命令架构**
```bash
# check - 验证 YAML 文件
uv run yaml2pptx.py check <input> [--template-dir <dir>]
# convert - 转换为 PPTX
uv run yaml2pptx.py convert <input> [output] [--template-dir <dir>] [--skip-validation] [--force]
# preview - 启动预览服务器
uv run yaml2pptx.py preview <input> [--template-dir <dir>] [--port <port>] [--host <host>] [--no-browser]
```
**参数说明**
- `--template-dir`:所有命令通用,指定模板目录
- `--skip-validation`convert 专用,跳过自动验证
- `--force/-f`convert 专用,强制覆盖已存在文件
- `--port`preview 专用,指定端口(默认随机 30000-40000
- `--host`preview 专用,指定主机地址(默认 127.0.0.1
- `--no-browser`preview 专用,不自动打开浏览器
### 3. 文件组织
**代码文件**
- 每个模块文件控制在 150-300 行
- 入口脚本约 100 行
- 入口脚本约 200 行
- 使用有意义的文件名和目录结构
**测试文件**
- 所有测试文件、临时文件必须放在 `temp/` 目录下
- 不污染项目根目录
### 3. 代码风格
### 4. 代码风格
**导入顺序**
```python
@@ -458,23 +480,32 @@ uv run yaml2pptx.py check temp/test.yaml
# 使用模板时验证
uv run yaml2pptx.py check temp/demo.yaml --template-dir temp/templates
# 使用 convert 子命令转换(推荐)
# 转换 YAML 为 PPTX
uv run yaml2pptx.py convert temp/test.yaml temp/output.pptx
# 传统模式转换(向后兼容)
uv run yaml2pptx.py temp/test.yaml temp/output.pptx
# 自动生成输出文件名
uv run yaml2pptx.py convert temp/test.yaml
# 跳过自动验证
uv run yaml2pptx.py convert temp/test.yaml temp/output.pptx --no-check
uv run yaml2pptx.py convert temp/test.yaml temp/output.pptx --skip-validation
# 强制覆盖已存在文件
uv run yaml2pptx.py convert temp/test.yaml temp/output.pptx --force
# 使用模板
uv run yaml2pptx.py convert temp/demo.yaml temp/output.pptx --template-dir temp/templates
# 预览模式
uv run yaml2pptx.py convert temp/test.yaml --preview
# 启动预览服务器
uv run yaml2pptx.py preview temp/test.yaml
# 指定端口
uv run yaml2pptx.py convert temp/test.yaml --preview --port 8080
uv run yaml2pptx.py preview temp/test.yaml --port 8080
# 允许局域网访问
uv run yaml2pptx.py preview temp/test.yaml --host 0.0.0.0
# 不自动打开浏览器
uv run yaml2pptx.py preview temp/test.yaml --no-browser
```
### 测试文件位置
@@ -518,7 +549,7 @@ A: dataclass 提供:
A: 使用预览模式:
```bash
uv run yaml2pptx.py temp/test.yaml --preview
uv run yaml2pptx.py preview temp/test.yaml
```
在浏览器中查看渲染结果,支持热重载。