refactor: 重构文档结构，采用渐进式信息披露模式

将 README.md 拆分为多个专题文档，减少认知负荷： - 用户文档迁移到 docs/ (用户指南、元素、模板、参考等) - 开发文档迁移到 docs/development/ (架构、模块、规范) - README.md 精简至 ~290 行，仅保留概览和导航 - 删除 README_DEV.md，内容已迁移 - 归档 OpenSpec 变更 refactor-docs-progressive-disclosure
2026-03-06 15:11:36 +08:00
parent 98098dc911
commit 124ef0e5ce
41 changed files with 5238 additions and 2228 deletions
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -0,0 +1,216 @@
+# 故障排查
+
+本文档提供常见问题的解决方法。
+
+## 常见错误
+
+### 文件不存在: xxx.yaml
+
+**原因**：找不到输入文件
+
+**解决方法**：
+- 检查文件路径是否正确
+- 确认文件在当前目录或使用相对/绝对路径
+- 检查文件名拼写是否正确
+
+```bash
+# 错误示例
+uv run yaml2pptx.py convert presntation.yaml  # 拼写错误
+
+# 正确示例
+uv run yaml2pptx.py convert presentation.yaml
+```
+
+### YAML 语法错误: 第 X 行
+
+**原因**：YAML 格式错误
+
+**解决方法**：
+- 检查缩进是否正确（使用空格，不要使用 Tab）
+- 确保冒号后有空格
+- 检查引号是否成对
+- 使用 YAML 验证工具检查语法
+
+```yaml
+# 错误示例
+slides:
+- elements:  # 缩进错误
+  - type: text
+content: "hello"
+
+# 正确示例
+slides:
+  - elements:
+      - type: text
+        content: "hello"
+```
+
+### 模板文件不存在: xxx
+
+**原因**：模板文件未找到
+
+**解决方法**：
+- 检查 `--template` 参数是否正确
+- 确认模板库文件存在
+- 检查模板名称拼写
+
+```bash
+# 错误示例
+uv run yaml2pptx.py convert presentation.yaml --template ./templat.yaml  # 拼写错误
+
+# 正确示例
+uv run yaml2pptx.py convert presentation.yaml --template ./templates.yaml
+```
+
+### 缺少必需变量: xxx
+
+**原因**：未提供必需的模板变量
+
+**解决方法**：
+- 在 `vars` 中提供该变量
+- 检查模板定义中哪些变量是 `required: true`
+
+```yaml
+# 模板定义
+templates:
+  title-slide:
+    vars:
+      - name: title
+        required: true
+
+# 错误示例
+- template: title-slide
+    vars: {}  # 缺少 title
+
+# 正确示例
+- template: title-slide
+    vars:
+      title: "我的标题"
+```
+
+### 图片文件未找到: xxx
+
+**原因**：图片文件不存在
+
+**解决方法**：
+- 检查图片路径是否正确
+- 确认图片文件存在
+- 使用相对路径（相对于 YAML 文件位置）
+
+```yaml
+# 错误示例
+- type: image
+  src: "images/logo.png"  # 文件不存在
+
+# 正确示例
+- type: image
+  src: "../assets/logo.png"  # 使用正确的相对路径
+```
+
+### 无效的颜色格式: xxx
+
+**原因**：颜色格式不符合要求
+
+**解决方法**：
+- 使用 `#RGB` 或 `#RRGGBB` 格式
+- 不要使用颜色名称（如 `red`、`blue`）
+
+```yaml
+# 错误示例
+font:
+  color: "red"
+
+# 正确示例
+font:
+  color: "#ff0000"
+```
+
+## 其他问题
+
+### 元素超出页面范围
+
+**警告**：元素右边界超出: 10.50 > 10
+
+**说明**：元素的右边界超出了幻灯片宽度
+
+**解决方法**：
+- 调整元素的 `box` 尺寸
+- 确保元素在页面范围内
+- 0.1 英寸内的超出是允许的
+
+```yaml
+# 16:9 幻灯片，最大宽度 10"
+# 错误示例
+box: [1, 1, 9, 1]  # 右边界 = 1 + 9 = 10"（警告）
+
+# 正确示例
+box: [1, 1, 8.9, 1]  # 右边界 = 1 + 8.9 = 9.9"（正常）
+```
+
+### 模板名称冲突
+
+**警告**：模板名称冲突: 'title-slide'
+
+**说明**：内联和外部模板同名
+
+**解决方法**：
+- 重命名其中一个模板
+- 系统会优先使用内联模板
+
+### 字体大小过小
+
+**警告**：字体大小过小: 5
+
+**说明**：字体小于 6pt 可能难以阅读
+
+**解决方法**：
+- 增加字体大小到至少 6pt
+- 建议使用 12pt 以上
+
+## 调试技巧
+
+### 使用验证功能
+
+```bash
+# 在转换前验证
+uv run yaml2pptx.py check presentation.yaml
+```
+
+### 使用预览模式
+
+```bash
+# 实时查看效果
+uv run yaml2pptx.py preview presentation.yaml
+```
+
+### 检查 YAML 语法
+
+使用在线 YAML 验证工具：
+- https://www.yamllint.com/
+- https://yaml-online-parser.appspot.com/
+
+### 查看详细错误
+
+使用 `-v` 参数查看详细输出：
+
+```bash
+uv run python -c "
+import yaml
+with open('presentation.yaml') as f:
+    yaml.safe_load(f)
+"
+```
+
+## 获取帮助
+
+如果以上方法无法解决问题：
+
+1. 查看 [开发文档](../development/) 了解更多信息
+2. 检查 GitHub Issues
+3. 提交新的 Issue，包含：
+   - 完整的错误信息
+   - YAML 文件内容（脱敏后）
+   - 使用的命令
+   - 系统环境信息
+
+[返回文档索引](../README.md)