AI Agent 驱动的教育演示文稿生成器。输入主题，自动生成全页 SVG 设计稿，转换为可编辑的原生形状 PPTX。
- V2 SVG Pipeline — LLM 直接生成整页 SVG (Bento Grid 卡片布局)，SVG→DrawingML 原生形状转换
- 打开即编辑 — 输出原生 PowerPoint 形状，无需"转换为形状"
- 策划/设计分离 — Phase 1 专注信息架构 (金字塔原理)，Phase 3 专注视觉设计
- DESIGN.md 驱动设计 — 视觉系统输出为人机共读的 markdown，typography / Components / Do's-and-Don'ts 直接驱动 Phase 3 SVG；用户手编辑后重跑
render即生效 - 5 套教育风格 — emerald / academic / warm / minimal / tech
- 联网搜索 — Responses API 内置 web_search，规划阶段自动补充实时信息
- Debug 模式 —
--debug跳过素材获取，快速预览布局 - 教案备注 — 每页自动生成口语化教学脚本 (Speaker Notes)
- LLM Review — Phase 4 自动检测+LLM 审阅修正 SVG 质量
git clone https://github.com/CodePothunter/EduPPTXGenerator.git
cd EduPPTXGenerator
uv sync
source .venv/bin/activatecp .env.example .env
# 编辑 .env，填入 API 密钥支持火山方舟 (豆包) 或任何 OpenAI 兼容接口：
# 文本生成 LLM
GEN_MODEL=your-model-endpoint
GEN_APIKEY=your-api-key
# API 模式: "chat" = Chat Completions | "responses" = Responses API
LLM_PROVIDER=responses
# Provider-specific 推理控制（可选）
# DeepSeek: GEN_THINKING=enabled / GEN_REASONING_EFFORT=high
# OpenAI o-series: GEN_REASONING_EFFORT=low|medium|high
# GEN_THINKING=
# GEN_REASONING_EFFORT=
# 图片生成 (Seedream / DALL-E 兼容)
VISION_GEN_MODEL=your-image-model
VISION_GEN_APIKEY=your-image-key# 基础用法
uv run edupptx gen "勾股定理"
# 指定风格 + 附加要求
uv run edupptx gen "光合作用" -r "适合高中生" --style edu_academic
# Debug 模式 (跳过素材，快速预览)
uv run edupptx gen "计算机网络" --debug
# 启用 LLM 联网搜索 (仅 Responses API)
uv run edupptx gen "量子计算最新进展" --web-search
# 从文档生成 + Tavily 联网搜索
uv run edupptx gen "基于报告做汇报" --file report.pdf --research
# 分步：先出策划稿，审核后再渲染
uv run edupptx plan "人工智能"
uv run edupptx render output/session_xxx/plan.json
# 编辑 DESIGN.md 调视觉系统，重跑 render 即生效（需 EDUPPTX_VISUAL_PLANNER_FORMAT=design_md）
EDUPPTX_VISUAL_PLANNER_FORMAT=design_md uv run edupptx gen "光合作用" --debug
# 编辑 output/session_xxx/DESIGN.md 中的 colors / Components / Shapes
uv run edupptx render output/session_xxx/plan.json --debug
# 查看可用风格
uv run edupptx stylesEduPPTX CLI 设计为可被 LLM Agent 直接调用，提供机器可读输出。
# 静默 + JSON 输出 (适合 agent 解析)
uv run edupptx --quiet gen "牛顿三大定律" --debug --json
# → {"ok": true, "mode": "full", "session_dir": "...", "pptx_path": "...", ...}
# 失败时也返回 JSON 错误
uv run edupptx --quiet gen "x" --style invalid --json
# → {"ok": false, "error": "未知风格 'invalid'。可用: ...", "kind": "UnknownStyle"}
# styles 查询带描述
uv run edupptx --quiet styles --json
# → {"ok": true, "styles": [{"name": "edu_emerald", "description": "..."}, ...]}
# 生成后立即跑视觉 QA
uv run edupptx --quiet gen "电磁感应" --debug --json --qa
# 结果 payload 中追加 "qa": {...} 字段Agent 调用要点
--quiet抑制日志，stderr 安静；--json让 stdout 只输出一行 JSON- 退出码：0=成功，1=运行时错误（JSON 模式 stdout 含详情），2=参数错误（Click 标准）
- 风格在生成前校验，无效风格立即失败而不会浪费 LLM 调用
- 失败时 LLM 原始响应保存到
output/_debug/llm_parse_fail_*.txt
用户输入 (主题 + 要求)
│
▼
┌──────────────────────────────────────┐
│ Phase 0: Input Processing │
│ 文档解析 + 联网搜索 (可选) │
├──────────────────────────────────────┤
│ Phase 1a: Content Planning (LLM) │
│ 金字塔原理 → 大纲+内容 JSON │
├──────────────────────────────────────┤
│ Phase 1b: Visual Planning (LLM) │
│ 主题色 + 背景 prompt + 卡片色 │
├──────────────────────────────────────┤
│ Phase 2: Background (Seedream AI) │
│ Phase 2b: Materials (非 debug 模式) │
├──────────────────────────────────────┤
│ Phase 3: SVG Generation (并行 LLM) │
│ Bento Grid 卡片布局, 1280×720 │
├──────────────────────────────────────┤
│ Phase 4: Validate + LLM Review │
│ 自动修复 + LLM 审阅修正 │
├──────────────────────────────────────┤
│ Phase 5: SVG→DrawingML→PPTX │
│ 原生形状, 直接可编辑 │
└──────────────────────────────────────┘
│
▼
output/session_xxx/
├── plan.json # Phase 1 输出
├── materials/ # 背景图 + 素材
├── slides/ # Phase 4 修正后 SVG
└── output.pptx # 原生形状 PPTX
支持两种 API 模式，通过 .env 中 LLM_PROVIDER 切换：
| 模式 | 环境变量 | 说明 |
|---|---|---|
| Chat Completions | LLM_PROVIDER=chat |
默认，兼容所有 OpenAI 兼容 API |
| Responses API | LLM_PROVIDER=responses |
火山方舟专属，支持联网搜索、上下文缓存 |
LLM_CONCURRENCY 控制 SVG 生成和 Review 阶段的 LLM 并行请求数（默认 4）。API 有限流时调低。
Responses API 额外支持 --web-search CLI 参数，让 LLM 在规划阶段自动联网搜索补充内容。
Layer 3b 引入 DESIGN.md 作为人机共读的视觉风格中间产物，启用后驱动 Phase 3 SVG 输出：
| 环境变量 | 值 | 说明 |
|---|---|---|
EDUPPTX_VISUAL_PLANNER_FORMAT |
json (默认) / design_md |
设为 design_md 时，规划阶段额外写出 session_dir/DESIGN.md（YAML frontmatter + 8 段中文 prose）。其中 typography（硬字号/字体）+ Components / Elevation / Shapes / Do's-and-Don'ts 四段 prose 会被注入 Phase 3 SVG system prompt，{colors.xxx} token 自动解析为 hex |
EDUPPTX_LINT_STRICT |
0 (默认) / 1 |
设为 1 时把 style linter 的对比度告警升级为错误 |
风格文件加载器 load_style() 同时支持 .json（旧路径）与 .md（DESIGN.md 解析后 → StyleSchema）。
用户编辑流程：
edupptx gen写出 DESIGN.md 后，可手工编辑session_dir/DESIGN.md再跑edupptx render <plan.json>，编辑会真实生效。DESIGN.md 加载时立即过resolve_stylelint，broken-ref 等错误会被捕获并降级（不注入但不阻塞生成）。
styles/ 目录下的调色板文件可以是 .json（紧凑、机器可读）或 .md（YAML frontmatter + 8 段中文 prose，人机共读）。两种格式经 load_style() 解析后产出严格等价的 ResolvedStyle，由 tests/test_style_migration_regression.py 守护。
styles/blue.md— 科技蓝主题，理工科课程styles/emerald.md— 翠绿主题，自然科学 / 生命科学styles/blue.json/styles/emerald.json— 等价 JSON 版本
prose 8 段固定为：Overview、Colors、Typography、Layout、Elevation、Shapes、Components、Do's and Don'ts，用 {colors.xxx} token 引用调色板字段，确保切换调色板时文档自动跟随。
需要把已有的 JSON 调色板转换为 .md 脚手架时：
uv run edupptx styles convert <name> # 把 styles/<name>.json → styles/<name>.md（脚手架）
uv run edupptx styles convert blue --force # 强制覆盖（注意：会清空手写 prose）转换后编辑 8 段 prose，再用 uv run pytest tests/test_style_migration_regression.py -v 验证 .md ↔ .json 等价。
PPT 生成时可从已有素材库复用图片，而非每次都重新生成。库目录与开关：
EDUPPTX_DISABLE_AI_IMAGE_REUSE（默认0）：总开关。设为1完全关闭复用读路径，回到"每次新生成"的行为，并跳过 caption/keyword 等复用专用 LLM 调用。生产出问题时的一键回滚。EDUPPTX_REUSE_BACKEND（默认json）：复用库存储后端。json=split index + npz sidecar；sqlite=单文件library.db（sqlite-vec）。切sqlite前先edupptx assets migrate <库目录>生成library.db，并做 goldset A/B 确认与 json 行为一致。维护命令：edupptx assets migrate/export/doctor。LIBRARY_DIR（默认./materials_library）：主素材库目录。REUSE_LIBRARY_DIRS（默认[LIBRARY_DIR, ./materials_library_ppt]）：复用检索的库目录列表，逗号/os.pathsep分隔。建议显式设绝对路径，否则相对当前工作目录会随启动目录漂移。EDUPPTX_AI_IMAGE_EMBEDDING_MODEL（默认Qwen/Qwen3-Embedding-0.6B）：嵌入模型；离线服务器用本机绝对路径。EDUPPTX_DISABLE_AI_IMAGE_EMBEDDINGS（默认0）：关闭嵌入召回，仅用 BM25+substring（policy_score 会按可用权重归一化）。- 入库相关：
EDUPPTX_ASSET_LIBRARY_VLM_REVIEW（默认0，VLM 入库审查未充分调试）、EDUPPTX_ASSET_INGEST_JOB_DB（入库 SQLite 队列路径）、CLI--no-asset-ingest（本次运行不写库）。 - 可选：
EDUPPTX_LLM_MAX_WORKERS、EDUPPTX_REUSE_COVERAGE_LOG、EDUPPTX_AI_IMAGE_REUSE_DEBUG_MODE、EDUPPTX_AI_IMAGE_EMBEDDING_BUILD_BATCH_SIZE。
字段生成与 LLM 复审的并发/批量：
EDUPPTX_REUSE_TARGET_KEYWORD_BATCH_SIZE（默认1）：字段生成每次 LLM 处理的图片数。默认单张以保准确性。EDUPPTX_REUSE_TARGET_KEYWORD_WORKERS（默认15）：字段生成并行 worker 数。注意上游 LLM 限流（豆包 ~10–20 req/s），撞 429 调小。EDUPPTX_REUSE_POLICY_WORKERS（默认5）：policy/LLM-review 阶段跨图外层并发。单图内候选复审并发受预算MAX_LLM_REVIEWS_PER_QUERY=5约束。EDUPPTX_REUSE_EMBED_RESCUE_FLOOR（默认0.70）：policy_score 因关键词稀疏跌破 T_REJECT、但 embedding >= 此值的 page_image 候选，改判 LLM review 而非硬拒。调高更保守、调低更激进。
EDUPPTX_EXERCISE_POLICY=1 启用后，可在学科/年级/课名严格匹配时从 JSON 题库（EDUPPTX_EXERCISE_BANK_PATH）或 teach-kb SQLite（EDUPPTX_EXERCISE_DB_PATH）绑定题干/答案/解析/题图，题图根目录 EDUPPTX_EXERCISE_IMAGE_ROOT，每类候选上限 EDUPPTX_EXERCISE_CANDIDATE_LIMIT（默认 4）。
| 模板 | 适用场景 |
|---|---|
edu_emerald |
数学、自然科学 (默认) |
edu_academic |
学术、论文汇报 |
edu_warm |
文科、人文社科 |
edu_minimal |
简约通用 |
edu_tech |
计算机、工程技术 |
显式
-s锁定配色：传入edu_academic/edu_warm/edu_minimal/edu_tech时，该主题的整套配色会覆盖按学科/学段自动推断的调色板。 不传-s（即默认edu_emerald）时按主题自动选色——因此edu_emerald不参与锁定，等同"自动路由"。 注：-s只锁颜色；版式模板族仍按学科/学段自动路由。颜色在gen阶段固化进plan.json，故render阶段改-s不再生效（应改plan.json/DESIGN.md）。
edupptx/
agent.py # 5 阶段管线编排器
models.py # 数据模型 (InputContext, PlanningDraft, VisualPlan, ...)
llm_client.py # LLM 客户端 (Chat + Responses API)
config.py # 环境变量配置
session.py # 会话目录管理
cli.py # CLI 入口 (gen/render/plan/styles[+convert])
style_schema.py # 风格 schema + ResolvedStyle (load_style 双格式分发)
style_resolver.py # palette ref 解析 + 命名 intent 映射 + lint 钩子
style/
design_md.py # DESIGN.md ⇄ StyleSchema parser + Phase 3 约束抽取
planning/
content_planner.py # Phase 1a: 内容规划
visual_planner.py # Phase 1b: 视觉规划 (双路径: VisualPlan JSON + DESIGN.md)
prompts.py # 规划阶段 prompt 模板
design/
prompts.py # SVG 生成 prompt (Bento Grid + 约束 + DESIGN.md 注入)
svg_generator.py # Phase 3: 并行 SVG 生成
style_templates/ # 5 套教育主题 SVG 模板
references/ # V3 设计参考 (design-base / shared-standards / page-types)
chart_templates/ # 图表 SVG 参考模板 (bar/line/pie/timeline)
materials/
image_provider.py # 多源图片获取 (Pixabay/Unsplash/Seedream)
background_generator.py # Phase 2: Seedream 背景生成
icons.py # 255 个 Lucide SVG 图标
postprocess/
svg_validator.py # SVG 自动修复 (viewBox/字体/边界/重叠)
svg_sanitizer.py # PPT 兼容清理 (去 script/事件)
svg_reviewer.py # Phase 4: LLM 审阅修正
style_linter.py # WCAG 对比度 + palette broken-ref 自检
output/
svg_to_shapes.py # SVG→DrawingML 原生形状转换器
pptx_assembler.py # PPTX 组装 (原生形状模式)
input/
document_parser.py # PDF/Word/MD 文档解析
web_researcher.py # Tavily 联网搜索
edupptx gen TOPIC [OPTIONS] 从主题生成演示文稿
edupptx plan TOPIC [OPTIONS] 只生成策划稿
edupptx render PLAN [OPTIONS] 从策划稿渲染
edupptx styles 列出可用风格模板
gen 选项：
| 选项 | 说明 |
|---|---|
-r, --requirements |
附加要求 (如"适合高中生") |
-s, --style |
风格模板 (默认 edu_emerald)；显式传非默认值会锁定该主题配色，覆盖自动调色 |
--file |
输入文档 (PDF/Word/MD/TXT) |
--research |
启用 Tavily 联网搜索 |
--web-search |
启用 LLM 联网搜索 (仅 Responses API) |
--review |
策划稿生成后暂停审核 |
--debug |
跳过素材获取，快速预览布局 |
-o, --output |
输出目录 (默认 ./output) |
-v, --verbose |
详细日志 |
uv sync
uv run pytest tests/ -vV3 的设计系统（色彩层级、字号体系、SVG 技术约束规范）参考了 PPT Master（MIT 许可）的设计方法论。PPT Master 专注于咨询类演示文稿的高质量生成，其分层 prompt 架构和设计规范体系对本项目的教育类设计系统建设有重要启发。
EduPPTX 专注于 K12 教育场景，在以下方面有独立的设计：教育专属页面类型（练习题/公式推导/实验步骤/对比表格/知识归纳）、面向课堂投影的内容密度分级（讲授/复习模式）、自动化 SVG→DrawingML 原生形状管线、以及面向教师的一键生成工作流。
MIT