📚 tutoring_prep

AI 家教备课助手 — 通过对话收集学生信息，自动生成专业 Word 教案 + PPT 演示文稿

✨ 核心功能

功能	说明
🤖 AI 教案生成	调用 Gitee.AI MiniMax-M2.7 大模型，自动生成结构完整的家教级教案
🏠 本地模式	无 API Key 时由 Claude Code 直接生成，通过文件机制通信，零依赖运行
📄 Word 导出	标准 A4 排版教案（黑体/宋体层级、表格流程、页码），开箱即用
📽️ PPT 生成	16:9 宽屏演示文稿（深蓝主题色），适配课堂讲解场景
➗ 数学符号书面化	LaTeX 标记（`x^2`→x², `\sqrt{3}`→√3, `\alpha`→α）自动转 Unicode
🧠 学生记忆	多学生信息存储，随时调用/修改，无需重复录入
📈 学习计划	长期备课计划按章节追踪（pending→in_progress→completed）
📊 调用统计	记录每次 API 调用的时间、延迟、Token 消耗，支持查询

🏗️ 技术架构

┌─ 用户输入学生信息 ────────────────────────────────────────────────────┐
                              │
                              ▼
┌────────────── skills/tutoring_prep/scripts/generate_with_ai.py ────┐
│  主程序编排流程：收集信息 → AI生成 → 符号规范化 → 文档生成           │
└────────┬──────────┬─────────────┬──────────────┬───────────────────┘
         │          │             │              │
         ▼          ▼             ▼              ▼
┌────────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐
│ model_    │ │ local_   │ │ app.py   │ │ ppt_         │
│ service   │ │ model_   │ │ (Word)   │ │ generator/   │
│ (API 调用) │ │ service  │ │          │ │ (PPT)        │
└─────┬──────┘ └────┬─────┘ └────┬─────┘ └──────┬───────┘
      │             │            │              │
      ▼             ▼            ▼              ▼
┌──────────┐ ┌──────────┐ ┌──────────────┐ ┌─────────────┐
│ call_   │ │ local_   │ │ math_        │ │ 教案/       │
│ logs/    │ │ requests/│ │ normalizer   │ │ .docx+.pptx │
│ (JSONL)  │ │ (文件通信)│ │ (LaTeX→Uni) │ │             │
└──────────┘ └──────────┘ └──────────────┘ └─────────────┘

数学/理科配图（函数图像、几何图形、3D 曲面）由独立的 skills/math_image skill 负责，调用 GeoGebra 引擎生成。

🚀 运行与部署方法

环境要求

依赖	说明
Python	≥ 3.10
pip 包	`python-docx` · `python-pptx` · `Pillow` · `requests` · `python-dotenv`
API Key（可选）	Gitee.AI 平台，配置后启用 API 模式

pip install python-docx python-pptx Pillow requests python-dotenv

方式一：Claude Code Skill 触发（推荐）

在 Claude Code 中说出 「我要备课」，激活「tutoring_prep」skill，通过对话引导完成全部流程：

用户：我要备课
助手：请选择操作：
      1. 使用已储存的学生信息
      2. 储存新学生信息
...（分步引导，自动生成 Word + PPT）

无需手动安装依赖 — Claude Code 环境中已预装 Python 环境。

方式二：直接运行脚本

1. 配置 API 密钥（API 模式需要）

在项目根目录创建 .env 文件：

echo "GITEE_AI_API_KEY=你的API密钥" > .env

2. 运行主程序

python tutoring_prep/scripts/generate_with_ai.py

程序自动检测 API Key：有 Key → 进入 API 模式；无 Key → 自动进入本地模式。

部署说明

模式	部署方式	适用场景
API 模式	配置 `.env` 密钥后运行脚本，或通过 Claude Code Skill 触发	需要稳定、快速的大模型教案生成
本地模式	无需任何配置，直接在 Claude Code 中说「我要备课」	无 API Key、想纯用 Claude Code 生成

两种模式均输出 .docx 和 .pptx 文件到 教案/ 目录，生成逻辑完全一致，仅内容生成引擎不同。

🎯 运行模式

模式一：Gitee.AI API 模式

项目	内容
模型服务商	Gitee.AI
GPU 算力	沐曦 GPU (MXGPU)
模型名称	MiniMax-M2.7
API 接口	OpenAI 兼容格式
Endpoint	`https://ai.gitee.com/v1`

完整流程：信息收集 → AI 生成 → 数学符号规范化 → Word 生成 → PPT 生成

模式二：本地模式（无需 API Key）

无需 API Key，由 Claude Code（主 AI） 直接生成教案，流程更简洁高效：

主 AI 直接生成 plan_content（参考 build_prompt() 的 JSON 格式）
保存为 JSON 文件（可调用 create_response_file() 辅助）
以 --plan-content 参数调用 Python 脚本生成 Word 和 PPT 文档

💬 示例输入输出

示例 1：初中数学 — 二次函数

输入（通过对话逐步收集的学生信息）：

项目	内容
学生姓名	小明
年级	初三
科目	数学
教材版本	人教版
学校类型	普通中学
考试类型	中考
薄弱点	二次函数图像性质理解不够，顶点式不会灵活运用
学习风格	视觉型
教学风格	严谨型，注重逻辑推导
课时长	60 分钟

输出 — 自动生成以下文件到 教案/ 目录：

教案/
├── 小明_二次函数_教案.docx          # Word 教案（含完整排版）
└── 小明_二次函数_教案.pptx          # PPT 演示文稿（16:9 宽屏）

Word 教案内容预览：

┌─ 封面 ──────────────────────────────────────────┐
│  二次函数 教案                                    │
│  学生：小明 | 初三 | 数学                        │
├─ 一、教学目标与重难点 ────────────────────────────┤
│  • 理解二次函数 y=ax²+bx+c 的图像性质            │
│  • 掌握顶点式 y=a(x-h)²+k 的灵活运用             │
│  • 重点：二次函数图像特征                        │
│  • 难点：顶点式的转化与应用                      │
├─ 二、教学流程与时间分配 ─────────────────────────┤
│  ┌──────────┬─────────┬────────────────┐          │
│  │ 环节     │ 时间    │ 内容           │          │
│  ├──────────┼─────────┼────────────────┤          │
│  │ 复习引入 │ 5min    │ 回顾一次函数   │          │
│  │ 新知识讲 │ 25min   │ y=ax² 图像特征 │          │
│  │ 例题精讲 │ 15min   │ 顶点式应用     │          │
│  │ 随堂练习 │ 10min   │ 限时练习       │          │
│  │ 课堂小结 │ 5min    │ 总结知识点      │          │
│  └──────────┴─────────┴────────────────┘          │
├─ 三、知识讲解要点 ────────────────────────────────┤
│  • 二次函数 y=ax²+bx+c 顶点坐标 (-b/2a, ...)     │
│  • 结合配图说明 a>0 开口向上，a<0 开口向下       │
├─ 四、例题精讲 ────────────────────────────────────┤
│  【例1】已知 y=x²-4x+3，求顶点坐标...            │
│  【例2】按指定平移，求解析式...                   │
├─ 五、随堂练习 ────────────────────────────────────┤
│  【练1】判断 y=-2x²+4x-1 开口方向...             │
├─ 六、课后作业 ────────────────────────────────────┤
│  • 完成练习册 P32-P33                             │
└─ 七、备忘卡片 ────────────────────────────────────┘

示例 2：小学数学 — 分数乘除法

输入（对话收集摘要）：

学生：小红 | 年级：六年级 | 科目：数学
教材：人教版 | 学校类型：重点小学
考试类型：小升初 | 薄弱点：分数乘除混合运算易错
学习风格：动手型 | 教学风格：鼓励型
课时长：60分钟
课题：分数乘除法

输出文件：

教案/
├── 小红_分数乘除法_教案.docx
└── 小红_分数乘除法_教案.pptx

示例 3：高中数学 — 三角函数

输入：

学生：小华 | 年级：高一 | 科目：数学
教材：人教版 | 学校类型：重点高中
考试类型：期末 | 薄弱点：三角函数恒等变换记忆不牢
学习风格：听觉型 | 教学风格：幽默型
课时长：90分钟
课题：三角恒等变换

输出文件：

教案/
├── 小华_三角恒等变换_教案.docx
├── 小华_三角恒等变换_教案.pptx
└── 小华_三角恒等变换_配图需求.json

数学配图（函数图像、几何图形）可使用 math_image skill 单独生成。

📁 项目结构

📁 项目根目录/
├── CLAUDE.md                        # 项目指南（供 Claude Code 使用）
├── README.md                        # 本文件
├── LICENSE                          # MIT License
├── requirements.txt                 # Python 依赖清单
├── .env.example                     # API 密钥模板（复制为 .env 使用）
├── .gitignore                       # Git 忽略规则
├── .claude-plugin/
│   └── plugin.json                  # Claude Code 插件注册
│
├── skills/tutoring_prep/            # 🎯 备课 Skill 主目录
│   ├── SKILL.md                     # 技能定义（触发词：我要备课）
│   ├── templete.txt                 # Word 排版规范
│   └── scripts/
│       ├── generate_with_ai.py      # ⭐ 主程序入口
│       ├── app.py                   # Word 教案生成器
│       ├── math_normalizer.py       # 数学符号书面化（LaTeX → Unicode）
│       ├── model_service.py         # Gitee.AI API 封装
│       ├── local_model_service.py   # 本地模式服务
│       ├── local_run.py             # 本地模式文档生成封装
│       ├── memory_manager.py        # 学生信息 & 学习计划管理
│       ├── utils.py                 # 工具函数（编码、路径、JSON）
│       ├── ppt_generator/
│       │   ├── __init__.py
│       │   ├── ppt_generator.py     # PPT 生成器（16:9 宽屏）
│       │   └── README.md
│       ├── local_requests/          # 本地模式文件通信
│       │   └── archive/             # 已处理响应归档
│       ├── call_logs/               # API 调用日志 (JSONL)
│       ├── generation_reports/      # 生成报告 (JSON)
│       └── memory/
│           ├── students.json        # 学生信息索引
│           └── learning_plans.json  # 长期学习计划
│
├── skills/math_image/               # 📐 配图 Skill 主目录
│   ├── SKILL.md                     # 技能定义（触发词：生成配图）
│   └── scripts/
│       ├── image_generator.py       # 配图生成入口
│       └── geogebra_generator/
│           ├── geogebra_api.py      # 2D/3D 绘图引擎（Pillow + numpy）
│           ├── validators.py        # 表达式安全校验
│           ├── demo.py              # 使用示例
│           └── 数学图片生成经验.md    # 经验规范文档

教案/                                # 📄 输出目录（自动创建）

📄 输出文件

所有产物自动保存到 教案/ 目录：

文件	格式	命名规则
Word 教案	`.docx`	`{学生姓名}_{课题}_教案.docx`
PPT 演示文稿	`.pptx`	`{学生姓名}_{课题}_教案.pptx`
配图需求	`.json`	`{学生姓名}_{课题}_配图需求.json`
生成报告	`.json`	`scripts/generation_reports/report_{时间戳}.json`

📝 排版规范

Word 教案

纸张：A4 纵向 · 页边距上下 2.54cm / 左右 3.18cm · 页码居中

层级	字体	字号	对齐
文档主标题	黑体	小三号	居中
章节标题（二级）	黑体	四号	左对齐
节标题（三级）	黑体	小四号	左对齐
子标题（四级）	宋体	小四号	左对齐
正文	宋体	五号 (10.5pt)	左对齐，首行缩进2字符

内容模块：① 封面区 → ② 教学目标与重难点 → ③ 教学流程与时间分配（表格） → ④ 知识讲解要点 → ⑤ 例题精讲 → ⑥ 随堂练习 → ⑦ 课后作业 → ⑧ 备忘卡片

PPT 演示文稿

格式：16:9 宽屏 (10” × 7.5”)
配色：深蓝色标题 #003366 · 蓝色强调 #0070C0
结构：封面 → 目录 → 教学目标/重难点 → 教学流程（表格） → 知识讲解（每知识点一页） → 例题精讲 → 随堂练习 → 课后作业 → 备忘卡片

➗ 数学符号书面化

math_normalizer.py 自动将 LaTeX 标记转换为 Unicode 符号，无需额外渲染引擎：

LaTeX	结果	LaTeX	结果
`x^2`	x²	`x^{10}`	x¹⁰
`x_1`	x₁	`\sqrt{3}`	√3
`\sqrt[3]{x}`	³√x	`\frac{1}{2}`	1/2
`\alpha`	α	`\pi`	π
`\geq`	≥	`\rightarrow`	→
`\sum_{i=1}^{n}`	∑	`\times`	×

🧠 学生与学习计划管理

学生信息（students.json）— 姓名、年级、科目、教材版本、学校类型、考试类型、薄弱点、学习风格、教学风格、课时长等。

学习计划（learning_plans.json）— 按章节追踪进度：

⏳ pending — 未上课
🔄 in_progress — 进行中
✅ completed — 已完成

操作流程：

启动时自动检测已有学生 → 列出列表供选择
可选择「使用已储存学生」或「储存新学生」
支持制定长期计划，逐章生成教案
生成后可标记章节完成状态，追踪进度

📊 调用统计

from model_service import get_call_stats

stats = get_call_stats()
print(f"总调用次数: {stats['total_calls']}")
print(f"成功: {stats['successful_calls']} | 失败: {stats['failed_calls']}")
print(f"平均延迟: {stats['avg_latency_ms']}ms")
print(f"总 Token 消耗: {stats['total_tokens']}")

🔗 相关 Skill

`math_image` — 数学/理科配图生成

生成函数图像、几何示意图、3D 曲面图等配图，使用 GeoGebra 引擎（Pillow + numpy 渲染）。

触发词：生成配图、我需要配图、帮我画图
支持：2D 函数图像 · 几何图形 · 3D 曲面（含颜色映射） · GeoGebra 脚本命令