DeckCraft v6 — 工程化实践规范

版本: 6.0.0 · 引擎: DeckEngine（基于 python-pptx 的原生图表）+ ChartEngine（原生实现）

必需工具: Read、Write、Bash 依赖安装: pip install python-pptx lxml Pillow 渲染质量验证（Render QA）: LibreOffice Impress（soffice --headless）+ poppler-utils（pdftoppm）

反模式（每次生成前必读）

反模式 1：口头宣称“关卡已通过”

错误做法: “QA 发现 5 处问题，但均为轻微问题，关卡通过。” 正确做法: 运行 gate_check.py，阅读其输出的 JSON，仅当 "passed": true 时才视为通过。

反模式 2：“我在脑子里检查过了”

内容 JSON 中的格式错误无法通过脑内审查识别。 正确做法: 运行 gate_check_content.py，并仔细阅读其输出的 JSON。

反模式 3：为“简单”演示文稿跳过流程

即使是简单演示文稿，也可能存在文字溢出、字体异常或布局错乱等问题。 正确做法: 可启用快速通道（Fast Track，见下文），但 绝不可跳过 QA 关卡。

硬性规则（HARD RULES）

1. 每次生成必须严格遵循五阶段流程
2. 所有关卡判定必须机器可读 —— 运行脚本并解析 JSON 输出
3. 鼓励经验沉淀 —— 记录模式级修复方案，用于后续持续优化
4. 所有定位数值必须使用 int() 包裹，以兼容 python-pptx
5. 添加文本运行段（run）前须清空段落（paragraph） —— 切勿假定 p.runs[0] 存在

五阶段生成流程

S1 简报 → S2 结构 → S3 内容 → S4 渲染+质量验证 → S5 交付
                          ⭐ 关卡检查        ⭐⭐ 关卡检查

阶段 1：简报（Brief）

收集信息：目标受众、核心目标、预计时长、关键信息点、风格偏好。 输出文件: /brief.md

设计规范模板（v6.0+）: 使用 templates/design_spec.md 记录结构化设计决策（画布比例、页数、受众、配色方案、字体排印、演讲者备注）。完整示例见 templates/design_spec_demo.md。推荐用于 ≥ 8 页的演示文稿。

阶段 2：结构（Structure）

分配每页类型，撰写关键要点（需为完整洞察句）。 输出文件: /outline.json

阶段 3：内容（Content）

填充文案、数据、图表原始数据；严格遵守 designs/layout_matrix.yaml 中定义的字符预算限制。 输出文件: /content.json

⭐ S3 关卡检查:

python3 scripts/gate_check_content.py /content.json 

阅读生成的 gate_content.json —— 仅当 "passed": true 时方可进入下一阶段。

阶段 4：渲染 + 质量验证（Render + QA）

基于 content.json 生成 PPTX，随后执行质量验证。

python3 scripts/gate_check.py  

阅读生成的 gate_result.json —— 仅当 "passed": true 时方可进入下一阶段。

视觉质量验证（渲染预览）:

# 将 PPT 渲染为 PDF，再转为 PNG 用于人工视觉检查
soffice --headless --convert-to pdf  --outdir /
pdftoppm -png -r 200  /preview/slide

检查生成的 PNG 图像，确认布局、字体、颜色及图表渲染效果是否符合预期。发现任何视觉问题均需修正后重新生成，并再次运行关卡检查。

阶段 5：交付 + 自我精炼（Deliver + Self-Refinement）

交付最终 PPTX 文件。

快速通道（Fast Track，适用于简单请求）

当且仅当同时满足以下全部条件时，可跳过 S2/S3 阶段的关卡检查：

• 总页数 ≤ 5
• 不含任何数据图表
• 用户明确要求“quick” / “fast” / “simple”

仍必须执行: S1 简报 + S4 QA 关卡检查 + S5 交付。

断点恢复（Checkpoint Recovery）

继续一个已有演示文稿项目时，请检查当前目录下已存在的文件：

• 无 brief.md → 从阶段 1 开始
• 无 outline.json → 从阶段 2 开始
• 无 content.json → 从阶段 3 开始
• 无 gate_content.json → 执行阶段 3 关卡检查
• 无 .pptx → 从阶段 4 开始
• 无 gate_result.json → 执行阶段 4 关卡检查
• 以上文件全部存在 → 进入阶段 5

请根据识别出的起始阶段继续工作，切勿从 S1 重新开始。

DeckEngine API

import sys, os
sys.path.insert(0, '')
from engine import DeckEngine

# v5.2+: 支持 canvas 参数（16:9 / 9:16 / 1:1 / 4:3 / A4）
eng = DeckEngine(theme_name="business", canvas="16:9")  # 默认值
eng = DeckEngine(theme_name="business", canvas="9:16")   # 垂直移动端（TikTok、Reels、Stories）
eng = DeckEngine(theme_name="business", canvas="1:1")    # 方形（Instagram）
eng = DeckEngine(theme_name="business", canvas="4:3")    # 经典投影仪
eng = DeckEngine(theme_name="business", canvas="A4")     # 打印用横向 A4

# v6.0+: 支持多角色模式（可选策略师 → 执行者工作流）
eng = DeckEngine(theme_name="business", canvas="16:9", role_mode="multi")
plan = eng.strategist_plan({"title": "My Brief"})  # 获取计划模板
# ... 使用你的 LLM 填充 plan ...
eng.execute_plan(filled_plan)                       # 根据计划生成 PPT
eng.cover(title="Title", subtitle="Sub", author="Author", date="2026")
eng.toc(items=[("1", "Chapter", "Description")])
eng.section_divider("Section Title", section_number=1)
eng.content(title="Slide", bullets=["Point 1", "Point 2"], key_point="Insight")
eng.content_with_icon(title="Slide", items=[("01", "Head", "Desc")])
eng.two_col(title="Compare", left_title="A", left_items=[], right_title="B", right_items=[])
eng.vs_compare(title="VS", left_title="Before", right_title="After", rows=[("Dim", "Val1", "Val2")])
eng.table(title="Data", headers=["H1", "H2"], rows=[["a", "b"]], insights=["Key takeaway"])
eng.stat_cards(title="KPIs", stats=[("99%", "Uptime"), ("$2M", "Revenue")])
eng.chart_bar(title="Revenue", data=[[4.2, 3.8]], labels=["A", "B"], series_names=["S1"])
eng.chart_pie(title="Mix", data=[45, 30, 25], labels=["X", "Y", "Z"], donut=True)
eng.chart_line(title="Trend", data=[[1, 2, 3]], labels=["Q1", "Q2", "Q3"])
eng.chart_gauge(title="Score", value=87, max_value=100, label="NPS")
eng.timeline(title="Roadmap", milestones=[("Q1", "Launch"), ("Q2", "Scale")])
eng.process_flow(title="Steps", steps=["Research", "Build", "Launch"])
eng.matrix_2x2(title="Priority", quadrants=[("TL", "desc"), ("TR", "desc"), ("BL", "desc"), ("BR", "desc")])
eng.quote(title="Insight", quote_text="Words matter.", attribution="Author")
eng.image_full(title="Visual", image_path="photo.jpg", caption="Detail")
eng.image_split(title="Split", image_path="photo.jpg", bullets=["Point"])
eng.kpi_dashboard(title="Dashboard", kpis=[("Revenue", 12.4, 15, "M")])
eng.team_grid(title="Team", members=[("Name", "Role")])
eng.checklist(title="Tasks", items=["Task 1", "Task 2"], checked=[True, False])
eng.summary(title="Takeaways", key_points=["Point 1"], conclusion="Next step")
eng.closing(title="Thank You", message="Questions?")  # closing slide 不含 page_num
eng.save("output.pptx")

内置主题共 10 种: business、business_dark、tech、tech_gradient、minimal、elegant、creative、green、red、ocean

画布预设（v5.2+）: 16:9（默认，宽屏）、9:16（垂直移动端，适配 TikTok/Reels/Stories）、1:1（方形，适配 Instagram）、4:3（经典投影仪）、A4（打印用横向 A4）、A4-portrait（打印用纵向 A4）。别名支持：mobile=9:16、square=1:1、ppt=16:9。

列出所有可用画布: from engine.constants import list_canvases; print(list_canvases())

设计指南

色彩

优先从用户提供的原始 PPT 中提取主色调；其次选择与主题契合的鲜明配色方案。 建议采用一种主导色（占比 60–70%）、1–2 种辅助色、一种高对比度强调色。

字体排印

中日韩文字体：Noto Sans CJK SC；拉丁字母字体：Arial / Calibri

间距

• 最小页边距：0.5 英寸（≈12.7 mm）
• 模块间间距：0.3–0.5 英寸（≈7.6–12.7 mm）
• 整体需保留充足留白（breathing room）

应避免的做法

• 每页重复使用完全相同的版式
• 纯文字幻灯片 —— 必须添加可视化元素
• 正文采用居中对齐
• 低对比度文字（浅色字配浅色背景，深色字配深色背景）

依赖项

渲染质量验证（Render QA，非必需但强烈推荐）:

技能文件结构

deckcraft/
├── SKILL.md                     # 本文档
├── engine/
│   ├── __init__.py
│   ├── constants.py             # 10 套主题色板、字体定义、网格系统
│   ├── core.py                  # 绘图基础组件、XML 清理、CJK 字体支持
│   ├── chart_engine.py          # 原生条形图/饼图/折线图/仪表盘（基于 python-pptx）
│   ├── deck_engine.py           # 20 种版式方法、40+ 高阶 API 接口
│   └── importers/               # v5.3+ 源文件导入器
│       ├── __init__.py
│       ├── base.py              # 共享启发式逻辑
│       ├── pdf.py               # PDF → 大纲（PyMuPDF）
│       ├── docx.py              # DOCX → 大纲（python-docx）
│       └── text.py              # TXT/MD → 大纲
├── scripts/
│   ├── generate_ppt.py          # CLI：输入 outline JSON → 输出 PPTX
│   ├── import_source.py         # v5.3+ CLI：PDF/DOCX/MD → outline
│   ├── gate_check.py            # S4 QA 关卡 → 输出 gate_result.json
│   └── gate_check_content.py   # S3 内容关卡 → 输出 gate_content.json
├── designs/
│   └── layout_matrix.yaml       # 23 种版式定义及其字符预算限制
├── examples/                    # 可运行代码示例
│   ├── 01_basic_cover_to_closing.py
│   ├── 02_multi_canvas.py
│   ├── 03_from_outline_json.py
│   └── 04_from_source.py        # v5.3+
└── tests/
    ├── test_smoke.py            # 95 种版式 × 多画布组合测试
    ├── test_validation.py       # 20 项输入校验测试
    └── test_importers.py        # v5.3+ 34 项导入器测试