autoppt

AutoPPT 是什么

AutoPPT 是一款“AI备课神器”：一套给 AI 编程智能体（Claude Code、OpenAI Codex）用的技能（skill）+ 课件引擎。你只要说出课程主题（或者给它一份教学大纲），智能体就按固定流程交付一整周可以直接上课的课件——你不需要写一行代码，也不需要排一页 PPT：

• 理论一、理论二、实践课三套幻灯片（各约 45 分钟、20 页左右），16:9、1920×1080，看起来像精心制作的 Keynote；
• 每页都有完整讲稿（建议用时、本页目标、讲述建议、互动提问、易错点、转场），放映时按 S 打开演讲者视图；
• 在浏览器里真实计算的互动：拖滑块、点按钮、改输入，结果当场算出来，而不是播放动画；
• 可以直接跑的实践代码：代码、运行结果、Jupyter Notebook 出自同一次真实运行，学生在自己电脑上得到一模一样的结果；
• 自动生成的学生版（去掉讲稿）、教师授课指南（分钟级安排）、学生指南、事实出处与图片来源页。

它来自复旦大学《人工智能基础》（2026 年秋季学期）的真实教学：一门面向大一新生的 16 周通识课，14 周课件全部用这套方法做成。本仓库附上第 1 周的完整课件作为参考示例。

为什么要做这个

做课件很花时间，而用 PPT 做出来的课件还有几个老问题：

三种课件风格

开始做一门课时，智能体会先请你选一种风格（同一门课各周保持一致，之后也能一键更换）：

三种风格共用同一套页型、互动组件和讲稿格式，只是视觉不同：换风格只需替换一个 CSS 文件（src/styles/theme.css）。

亮点

• 🖱️ 交互性强：选择卡、翻牌卡、小测、滑块、可视化……全部在浏览器里现场计算，并与 Python 的结果逐项对照。
• 💬 说一句话就能开始：“帮我做第 1 周的课件：人工智能概述，面向大一新生”——智能体先写设计文档，再做成品；想精修时再改设计文档。
• 🎨 三种风格任选：学术刊物、黑底舞台、几何色块。
• 📚 全学科：引擎与学科无关——文科的史料对比、理科的参数模拟、医科的病例判断、工科的代码实验，都能做成互动。
• ⏱️ 快：在我们的课上，教师每周投入大约半小时——读一遍、改一遍设计文档，确认几件事；其余（三节课、讲稿、互动、代码、检查）由智能体完成。
• 🧑‍💻 学生实践是真的：实践课有可以直接运行的代码和 Notebook，有验收清单、检查点、常见问题，学生跟着做就能跑通。
• 📝 讲稿完整：每页的讲稿教师照着念也能讲好；教师指南按讲稿自动汇总出每节课的分钟级安排。
• 🎓 专业、可核对：主线清晰、事实有出处；示意数据标“示意”，课程组撰写的数据标“课程组撰写”。
• 📦 一个文件夹，离线可用：Reveal.js 与字体都在本地，双击 index.html 就能打开；python3 start.py 打开演讲者视图；网址加 ?print-pdf 可导出 PDF。
• 🔍 自带检查：冒烟测试、文字重叠检查（两种分辨率 × 教师版 / 学生版）、逐页截图与总览图。
• 🔁 越做越快：每做完一周，智能体把新学到的规矩写进“课件制作约定”，下一周直接沿用。

截图（第 1 周示例）

示例中的照片、新闻截图、电影剧照属于课堂教学引用，不能公开再分发，开源版已换成标有原内容的占位图。

快速开始

1. 准备环境

• 一个能读写文件、运行命令的 AI 编程智能体：Claude Code 或 OpenAI Codex（两套技能都已提供）。其他支持 AGENTS.md / skill 的智能体也可以按 AGENTS.md 使用。
• Python 3.9+（构建；可选 pip install fonttools，配合 Noto CJK 字体按实际用字裁剪字体）。
• Node.js 18+ 与 Playwright（检查与截图）：npm i -g playwright && npx playwright install chromium。
• 实践课需要什么就装什么（NumPy、pandas、scikit-learn……）。

唯一的前提是有一个 AI 编程智能体。你自己不需要会编程：上面这些依赖也可以让智能体帮你装。

2. 安装技能（Claude Code / Codex 二选一或都装）

git clone https://github.com/<你的用户名>/autoppt.git && cd autoppt

python3 install.py --agent claude      # Claude Code：装到 ~/.claude/skills/autoppt
python3 install.py --agent codex       # OpenAI Codex：装到 ~/.agents/skills/autoppt
python3 install.py --agent both        # 两个都装
python3 install.py --agent codex --project <课程文件夹>   # 只给某门课用（项目级）

（Windows 用 py -3 install.py …。）

两套技能共用同一套引擎、模板和脚本，做出来的课件完全一样；Codex 版的 SKILL.md 由 SKILL.codex.md 安装而来，多了 Codex 的使用说明。

3. 打开示例看一眼

cd autoppt/examples/week01
python3 start.py          # 浏览器自动打开；按 S 看讲稿，按 → 翻页

4. 说一句话，开始做课

在课程文件夹里启动智能体，然后说：

快速模式：帮我做第 1 周的课件：人工智能概述。面向大一新生、零编程基础，用「学术刊物」风格。

智能体会先问你几个它推断不出来的问题（学生是谁、风格选哪种），其余先用默认值，然后写设计文档、做出成品、自检，最后告诉你需要确认的事。

整门课模式（推荐）：我要上一门《中国古代史》，这是我的教学大纲（附上 docx / pdf）。请先问清楚我的需求，整理出整学期的课程内容设计给我确认，再做第 1 周。

读完、按你的实际需求改完设计文档之后：

我改好了，开干！

之后每一周都只需要一句：“设计第 N 周的课程内容” → 改 → “开干”。

工作流程

⓪ 说清你的课（一次）  ──► ① 课程内容设计（一次）  ──► ② 每周设计文档  ──► ③ 开干：实现  ──► ④ 验证与交付
   需求访谈、选风格          课程大纲（你确认）         你按需修改          三节课 + 配图      截图检查、更新约定

⓪ 说清你的课（整门课一次） 每位老师的课都不一样，所以智能体先问清楚你要教什么、教给谁、怎么教，再动手。它会先读你给的教学大纲、教材目录或旧课件，再用几道选择题补齐缺的信息（见课程需求表）：学生是谁、会不会编程；一共几周、每周几节；每周大致讲什么；实践课做什么（编程 / 案例研讨 / 实验与数据分析 / 习题 / 写作展示）；配图能不能从开放图库搜、能不能用 AI 生成、课件会不会公开；课件风格选哪种。

① 课程内容设计（整门课一次） 智能体把你的需求整理成课程大纲：每周主题、三节课各讲什么、实践课形式、项目里程碑、每周一句主线、配图计划。你确认（或修改）之后才开始做第 1 周。同时建立《课件制作约定》——智能体的工作备忘，以后每周追加。

② 每周：设计文档，你按实际需求改 说“设计第 N 周的课程内容”，智能体按周设计文档模板写出：一句主线、三节课的逐页表（标题、内容、时长）、要做的互动、实践课的材料或代码、事实核查清单（已联网核对）、需要你确认的事。你读一遍，按自己的需要改：加一个你常讲的案例、换一个更贴近学生的实验、删掉不想讲的……参考：第 1 周设计文档。

③ 开干：智能体实现（含配图） 说“开干”，智能体生成骨架，然后按顺序：数据与实践课脚本（真实运行）→ 配图 → 互动组件 → 三节课和讲稿 → 配套页面 → 构建。 配图按“自绘示意图 → 数据图 → 你的素材 → 开放许可图库 → AI 生成示意图”的顺序选：历史课的文物、医学课的显微图、地理课的卫星图这类需要真实图片的，智能体会到 Wikimedia Commons、Openverse 等开放许可图库搜索，挑选后下载并自动登记作者、许可和链接；AI 生成的插图会标明“AI 生成示意”。

④ 验证与交付 冒烟测试、文字重叠检查、逐页截图并逐张查看；互动的计算与 Python 逐项对照；写进课程文件夹，在上一周首页加“第 N 周 →”，更新《课件制作约定》。最后给你一段简短总结和需要你确认的事。

一周课件包含什么

weekNN/
├─ index.html                 每周首页：三节课入口与下载
├─ lecture1.html              理论一（约 21 页，含讲稿）
├─ lecture2.html              理论二（约 21 页）
├─ lab1.html                  实践课（约 22 页）
├─ student/                   学生版（自动生成，无讲稿）
├─ teacher-guide.html         教师授课指南（分钟级安排、课前待办、应急预案、数据核对）
├─ student-setup.html         学生指南（可在手机上看）
├─ sources.html               事实出处与核查记录
├─ image-sources.html         图片来源（自动生成）
├─ examples/                  Notebook（学生版 + 参考答案）、数据、模板
├─ src/                       deck.js 外壳、样式、互动组件、数据
├─ tools/                     数据脚本、实践课脚本（真实运行 + 自检）
├─ build.py  start.py  week.json  README.md  TESTING.md

放映快捷键：→ / 空格 下一步，← 上一步，F 全屏，Esc 概览，S 演讲者视图，R 重置当前页互动，H 回首页；移动鼠标时底部出现三节课切换栏；网址加 ?print-pdf 用 Chrome 打印为 PDF。

给智能体看的说明

• 入口：Claude Code 读 skills/autoppt/SKILL.md；Codex 读 skills/autoppt/SKILL.codex.md 与 references/codex.md。再按需读 references/。
• 参考实现：examples/week01/ 与其 第一周 设计文档.md。
• 先了解老师的课：⓪ 需求访谈（读大纲 → 选择题补齐）→ ① 课程内容设计（老师确认）。
• 先请用户选风格：给用户看 skills/autoppt/styles/styles.jpg，在 A 学术刊物（academic）/ B 黑底舞台（stage）/ C 几何色块（blocks）中选一个，写进《课件制作约定》。
• 生成骨架：python3 skills/autoppt/scripts/new_week.py --dest <课程文件夹> --week N --style academic --course … --l1 … --l2 … --lab …
• 检查：bash skills/autoppt/scripts/check_week.sh <课程文件夹>/weekNN
• 硬性要求：不编造（事实联网核对，模型输出只来自真实运行）；互动是真实计算并与 Python 对照；实践课代码、输出、Notebook 出自同一次运行；代码页 data-fit="off"、代码行 ≤ 86 列；无文字重叠；第三方图片登记来源。
• 触发语：“设计第 N 周的课件”= 设计文档 + 实现；“设计第 N 周的课程内容 / 设计文档”= 只写文档；“开干”= 按已确认的设计文档实现。

仓库结构

autoppt/
├─ README.md  README.en.md  AGENTS.md  CLAUDE.md  install.py  LICENSE  LICENSE-CONTENT.md  THIRD_PARTY_NOTICES.md
├─ assets/                    logo
├─ docs/                     demo.gif、styles.jpg、screenshots/（README 用图）
├─ skills/autoppt/           ← 技能本体（install.py 安装到 Claude Code / Codex）
│  ├─ SKILL.md                Claude Code 版入口
│  ├─ SKILL.codex.md          Codex 版入口（安装时改名为 SKILL.md）
│  ├─ references/             流程、写法、组件、实践课、质量
│  ├─ tem