lanyuanxiaoyao
124ef0e5ce
将 README.md 拆分为多个专题文档，减少认知负荷： - 用户文档迁移到 docs/ (用户指南、元素、模板、参考等) - 开发文档迁移到 docs/development/ (架构、模块、规范) - README.md 精简至 ~290 行，仅保留概览和导航 - 删除 README_DEV.md，内容已迁移 - 归档 OpenSpec 变更 refactor-docs-progressive-disclosure
3.0 KiB
3.0 KiB
开发规范
本文档说明 yaml2pptx 项目的开发规范和约定。
Python 环境
必须使用 uv 运行脚本
# 正确
uv run yaml2pptx.py input.yaml output.pptx
# 错误 - 严禁直接使用主机环境的 python
python yaml2pptx.py input.yaml output.pptx
依赖管理
- 所有依赖在
pyproject.toml的[project.dependencies]中声明 - uv 会自动安装依赖，无需手动
pip install
命令行接口
子命令架构
# check - 验证 YAML 文件
uv run yaml2pptx.py check <input> [--template <path>]
# convert - 转换为 PPTX
uv run yaml2pptx.py convert <input> [output] [--template <path>] [--skip-validation] [--force]
# preview - 启动预览服务器
uv run yaml2pptx.py preview <input> [--template <path>] [--port <port>] [--host <host>] [--no-browser]
参数说明
--template：指定模板库文件路径--skip-validation：convert 专用，跳过自动验证--force/-f：convert 专用，强制覆盖已存在文件--port：preview 专用，指定端口--host：preview 专用，指定主机地址--no-browser：preview 专用，不自动打开浏览器
文件组织
代码文件
- 每个模块文件控制在 150-300 行
- 入口脚本约 200 行
- 使用有意义的文件名和目录结构
测试文件
- 所有测试文件、临时文件必须放在
temp/目录下 - 不污染项目根目录
代码风格
导入顺序
# 1. 标准库
import sys
from pathlib import Path
# 2. 第三方库
import yaml
from pptx import Presentation
# 3. 本地模块
from utils import log_info
from core.elements import TextElement
文档字符串
- 每个模块必须有模块级文档字符串
- 每个类和函数必须有文档字符串
- 使用中文编写注释和文档
命名规范
- 模块名：小写 + 下划线（如
yaml_loader.py） - 类名：大驼峰（如
TextElement） - 函数名：小写 + 下划线（如
load_yaml_file()） - 常量：大写 + 下划线（如
HTML_TEMPLATE）
项目约束
- 面向中文开发者：注释、文档、错误消息使用中文
- 使用 uv 运行：严禁直接使用主机环境的 python
- 测试文件隔离：所有测试文件放在
temp/目录 - 不污染主机环境：不修改主机的 Python 配置
验证容忍度
几何验证时，允许 0.1 英寸的容忍度：
TOLERANCE = 0.1 # 英寸
if right > slide_width + TOLERANCE:
# 报告 WARNING
最佳实践
模块职责
- 每个模块职责明确，单一功能
- 模块间通过清晰接口通信
- 避免循环依赖
错误处理
- 使用自定义异常类（如
YAMLError） - 提供清晰的错误信息
- 包含错误位置（文件、行号、元素）
日志
- 使用统一的日志函数（
log_info(),log_success(),log_error()） - 显示友好的中文错误信息