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:
@@ -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
|
||||
```
|
||||
在浏览器中查看渲染结果,支持热重载。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user