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

@@ -0,0 +1,74 @@
# Browser Preview Server (Delta Spec)
## MODIFIED Requirements
### Requirement: 系统必须支持通过独立子命令启用预览模式
系统 SHALL 通过独立的 `preview` 子命令启用浏览器预览模式,而不是作为 convert 命令的参数。
#### Scenario: 使用 preview 子命令启动预览服务器
- **WHEN** 用户运行 `uv run yaml2pptx.py preview input.yaml`
- **THEN** 系统启动预览服务器
#### Scenario: convert 命令不再支持 --preview 参数
- **WHEN** 用户运行 `uv run yaml2pptx.py convert input.yaml --preview`
- **THEN** 系统报错,提示使用 `preview` 子命令
#### Scenario: preview 子命令与其他参数兼容
- **WHEN** 用户运行 `uv run yaml2pptx.py preview input.yaml --template-dir templates`
- **THEN** 系统启动预览服务器,并使用指定的模板目录
### Requirement: 系统必须提供 HTTP 服务
系统 SHALL 使用 Flask 启动 HTTP 服务器,监听指定端口,提供预览页面。
#### Scenario: 启动 HTTP 服务器(随机端口)
- **WHEN** 预览模式启动且未指定端口
- **THEN** 系统在 30000-40000 范围内随机选择端口启动 Flask HTTP 服务器
#### Scenario: 自定义端口
- **WHEN** 用户使用 `--port 8080` 参数
- **THEN** 系统在端口 8080 启动 HTTP 服务器
#### Scenario: 配置主机地址
- **WHEN** 用户使用 `--host 0.0.0.0` 参数
- **THEN** 系统在 0.0.0.0 启动 HTTP 服务器,允许局域网访问
#### Scenario: 端口被占用时报错
- **WHEN** 指定的端口已被其他服务占用
- **THEN** 系统抛出错误,提示端口被占用,建议使用 `--port` 参数指定其他端口
#### Scenario: 提供主页面路由
- **WHEN** 浏览器访问服务器根路径
- **THEN** 系统返回包含所有幻灯片预览的 HTML 页面
### Requirement: 系统必须支持控制浏览器自动打开
系统 SHALL 支持通过参数控制是否自动打开浏览器。
#### Scenario: 默认自动打开浏览器
- **WHEN** 预览服务器启动成功且未使用 --no-browser 参数
- **THEN** 系统自动在默认浏览器中打开预览页面
#### Scenario: 不自动打开浏览器
- **WHEN** 用户使用 `--no-browser` 参数
- **THEN** 系统启动服务器但不自动打开浏览器,仅在终端输出预览 URL
#### Scenario: 浏览器打开失败时提示 URL
- **WHEN** 系统无法自动打开浏览器(如无图形界面环境)
- **THEN** 系统在终端输出预览 URL提示用户手动打开
## REMOVED Requirements
无移除的需求。其他需求文件监听、SSE 推送、错误处理等)保持不变。