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:
@@ -6,39 +6,44 @@ Browser Preview Server 负责提供浏览器实时预览功能，包括启动 We
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: 系统必须支持通过命令行参数启用预览模式
|
||||
### Requirement: 系统必须支持通过独立子命令启用预览模式
|
||||
|
||||
系统 SHALL 在 `yaml2pptx.py` 中提供 `--preview` 参数，启用浏览器预览模式。
|
||||
系统 SHALL 通过独立的 `preview` 子命令启用浏览器预览模式，而不是作为 convert 命令的参数。
|
||||
|
||||
#### Scenario: 使用 --preview 参数启动预览服务器
|
||||
#### Scenario: 使用 preview 子命令启动预览服务器
|
||||
|
||||
- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml --preview`
|
||||
- **THEN** 系统启动预览服务器，而不是生成 PPTX 文件
|
||||
- **WHEN** 用户运行 `uv run yaml2pptx.py preview input.yaml`
|
||||
- **THEN** 系统启动预览服务器
|
||||
|
||||
#### Scenario: 不使用 --preview 参数时保持原有行为
|
||||
#### Scenario: convert 命令不再支持 --preview 参数
|
||||
|
||||
- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml`
|
||||
- **THEN** 系统生成 PPTX 文件，不启动预览服务器
|
||||
- **WHEN** 用户运行 `uv run yaml2pptx.py convert input.yaml --preview`
|
||||
- **THEN** 系统报错，提示使用 `preview` 子命令
|
||||
|
||||
#### Scenario: --preview 参数与其他参数兼容
|
||||
#### Scenario: preview 子命令与其他参数兼容
|
||||
|
||||
- **WHEN** 用户运行 `uv run yaml2pptx.py input.yaml --preview --template-dir templates`
|
||||
- **WHEN** 用户运行 `uv run yaml2pptx.py preview input.yaml --template-dir templates`
|
||||
- **THEN** 系统启动预览服务器，并使用指定的模板目录
|
||||
|
||||
### Requirement: 系统必须提供 HTTP 服务
|
||||
|
||||
系统 SHALL 使用 Flask 启动 HTTP 服务器，监听指定端口，提供预览页面。
|
||||
|
||||
#### Scenario: 启动 HTTP 服务器
|
||||
#### Scenario: 启动 HTTP 服务器（随机端口）
|
||||
|
||||
- **WHEN** 预览模式启动
|
||||
- **THEN** 系统在默认端口 5000 启动 Flask 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** 指定的端口已被其他服务占用
|
||||
@@ -46,7 +51,7 @@ Browser Preview Server 负责提供浏览器实时预览功能，包括启动 We
|
||||
|
||||
#### Scenario: 提供主页面路由
|
||||
|
||||
- **WHEN** 浏览器访问 `http://localhost:5000/`
|
||||
- **WHEN** 浏览器访问服务器根路径
|
||||
- **THEN** 系统返回包含所有幻灯片预览的 HTML 页面
|
||||
|
||||
### Requirement: 系统必须监听 YAML 文件变化
|
||||
@@ -97,14 +102,19 @@ Browser Preview Server 负责提供浏览器实时预览功能，包括启动 We
|
||||
- **WHEN** SSE 连接因网络问题断开
|
||||
- **THEN** 浏览器自动尝试重新连接到 SSE 端点
|
||||
|
||||
### Requirement: 系统必须自动打开浏览器
|
||||
### Requirement: 系统必须支持控制浏览器自动打开
|
||||
|
||||
系统 SHALL 在预览服务器启动后，自动在默认浏览器中打开预览页面。
|
||||
系统 SHALL 支持通过参数控制是否自动打开浏览器。
|
||||
|
||||
#### Scenario: 启动后自动打开浏览器
|
||||
#### Scenario: 默认自动打开浏览器
|
||||
|
||||
- **WHEN** 预览服务器启动成功
|
||||
- **THEN** 系统自动在默认浏览器中打开 `http://localhost:5000/`
|
||||
- **WHEN** 预览服务器启动成功且未使用 --no-browser 参数
|
||||
- **THEN** 系统自动在默认浏览器中打开预览页面
|
||||
|
||||
#### Scenario: 不自动打开浏览器
|
||||
|
||||
- **WHEN** 用户使用 `--no-browser` 参数
|
||||
- **THEN** 系统启动服务器但不自动打开浏览器，仅在终端输出预览 URL
|
||||
|
||||
#### Scenario: 浏览器打开失败时提示 URL
|
||||
|
||||
|
||||
Reference in New Issue
Block a user