lanyuanxiaoyao
66472cbd86
重构命令行接口，建立清晰的子命令架构，提升用户体验和代码可维护性。 主要变更： - 移除传统模式，统一使用子命令架构（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 任务完成）
6.7 KiB
6.7 KiB
Browser Preview Server
Purpose
Browser Preview Server 负责提供浏览器实时预览功能，包括启动 Web 服务、监听 YAML 文件变化、通过 Server-Sent Events (SSE) 推送更新通知到浏览器。它是预览模式的核心组件，协调文件监听、HTML 生成和浏览器刷新的整个流程。
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: 系统必须监听 YAML 文件变化
系统 SHALL 使用 watchdog 监听 YAML 文件所在目录，检测文件修改事件。
Scenario: 监听 YAML 文件修改
- WHEN 用户修改并保存 YAML 文件
- THEN 系统检测到文件变化事件
Scenario: 监听模板文件修改
- WHEN 用户修改并保存模板文件（如
templates/title_slide.yaml） - THEN 系统检测到文件变化事件
Scenario: 忽略非 YAML 文件变化
- WHEN 用户修改其他类型的文件（如
.txt、.md） - THEN 系统不触发预览更新
Scenario: 防抖处理
- WHEN 用户在短时间内多次保存文件（如 1 秒内保存 3 次）
- THEN 系统仅触发一次预览更新，避免频繁刷新
Requirement: 系统必须通过 SSE 推送更新通知
系统 SHALL 提供 Server-Sent Events (SSE) 端点，当文件变化时推送更新通知到浏览器。
Scenario: 提供 SSE 端点
- WHEN 浏览器连接到
http://localhost:5000/events - THEN 系统建立 SSE 连接，保持连接打开
Scenario: 文件变化时推送更新
- WHEN 检测到 YAML 文件变化
- THEN 系统通过 SSE 连接发送
data: reload消息到所有连接的浏览器
Scenario: 浏览器接收更新后自动刷新
- WHEN 浏览器接收到
reload消息 - THEN 浏览器自动刷新页面，显示最新的预览内容
Scenario: SSE 连接断开时自动重连
- WHEN SSE 连接因网络问题断开
- THEN 浏览器自动尝试重新连接到 SSE 端点
Requirement: 系统必须支持控制浏览器自动打开
系统 SHALL 支持通过参数控制是否自动打开浏览器。
Scenario: 默认自动打开浏览器
- WHEN 预览服务器启动成功且未使用 --no-browser 参数
- THEN 系统自动在默认浏览器中打开预览页面
Scenario: 不自动打开浏览器
- WHEN 用户使用
--no-browser参数 - THEN 系统启动服务器但不自动打开浏览器，仅在终端输出预览 URL
Scenario: 浏览器打开失败时提示 URL
- WHEN 系统无法自动打开浏览器（如无图形界面环境）
- THEN 系统在终端输出预览 URL，提示用户手动打开
Requirement: 系统必须提供清晰的日志输出
系统 SHALL 在终端输出清晰的日志信息，帮助用户了解预览服务器的状态。
Scenario: 启动时输出日志
- WHEN 预览服务器启动
- THEN 系统输出以下信息：
- 正在监听的 YAML 文件路径
- 预览服务器的 URL
- 停止服务器的方法（按 Ctrl+C）
Scenario: 文件变化时输出日志
- WHEN 检测到文件变化
- THEN 系统输出
[INFO] 检测到文件变化: <文件路径>
Scenario: 错误时输出日志
- WHEN 发生错误（如 YAML 解析错误）
- THEN 系统输出
[ERROR]级别的日志，包含错误详情
Requirement: 系统必须支持优雅退出
系统 SHALL 支持通过 Ctrl+C 优雅地停止预览服务器。
Scenario: 按 Ctrl+C 停止服务器
- WHEN 用户按下 Ctrl+C
- THEN 系统停止文件监听和 HTTP 服务器，输出
[INFO] 已停止，然后退出
Scenario: 停止时清理资源
- WHEN 服务器停止
- THEN 系统关闭所有 SSE 连接，停止 watchdog 监听器，释放端口
Requirement: 系统必须处理 YAML 解析错误
系统 SHALL 在 YAML 解析失败时，在预览页面显示友好的错误信息，而不是崩溃。
Scenario: YAML 语法错误时显示错误页面
- WHEN YAML 文件存在语法错误（如缺少冒号、缩进错误）
- THEN 系统在预览页面显示错误信息，包括错误类型和行号
Scenario: 错误修复后自动恢复
- WHEN 用户修复 YAML 错误并保存
- THEN 系统检测到文件变化，重新解析 YAML，显示正常的预览内容
Scenario: 错误页面仍然监听文件变化
- WHEN 预览页面显示错误信息
- THEN 系统继续监听文件变化，等待用户修复错误
Requirement: 系统必须支持多幻灯片预览
系统 SHALL 在预览页面中显示所有幻灯片，支持用户查看完整的演示文稿。
Scenario: 垂直排列显示所有幻灯片
- WHEN YAML 文件包含多个幻灯片
- THEN 系统在预览页面中垂直排列显示所有幻灯片，每个幻灯片之间有间距
Scenario: 显示幻灯片编号
- WHEN 预览页面显示幻灯片
- THEN 每个幻灯片右下角显示编号（如 "幻灯片 1"、"幻灯片 2"）
Scenario: 幻灯片尺寸一致
- WHEN 预览页面显示多个幻灯片
- THEN 所有幻灯片使用相同的尺寸（960x540 像素，16:9 比例）