教材自学教程生成器
概述
将教材PDF转化为结构化自学教程Word文档（.docx），采用"排版引擎 + 数据分离"架构：Python排版引擎负责Word渲染，数据模块按章节组织内容，12板块模板确保每节结构统一。
适用场景：中小学各学科教材的自学教程、预习指南、教辅材料生成。
必要输入
调用此技能时，必须向用户确认以下信息：
- 教材：提供教材PDF路径，或教材名称+版本+年级（如"人教版八年级物理上册 2022版 六三制"）
- 学科：如物理、化学、数学、生物等（影响公式风格和实验描述规范）
可选输入：
- 目标读者（默认：零基础预习学生）
- 输出格式偏好（默认：Word .docx）
- 是否需要联网补充教参（默认：是）
工作流
第一阶段：分析教材结构
- 读取教材PDF：使用 Read 工具读取教材PDF，提取章节目录和知识点框架
- 搜索补充资料（可选）：使用 WebSearch 搜索对应学科章节的优质教参材料，补充教材中阐述不足的知识点
- 生成章节大纲：列出全部章节、小节、跨学科实践的标题清单，供用户确认
第二阶段：构建排版引擎
- 创建
scripts/build_tutorial.py：从本技能scripts/build_tutorial.py复制排版引擎模板 - 适配封面信息：修改
add_cover()中的标题、版本信息 - 适配数据导入：修改
build_tutorial()中的数据模块导入和输出路径
排版引擎提供以下核心函数（无需修改，直接复用）：
| 函数 | 用途 |
|---|---|
create_document() |
创建A4文档，设置页边距 |
setup_styles(doc) |
注册6种样式：章标题/节标题/板块标题/正文/公式/练习 |
add_cover(doc) |
封面页 |
add_toc(doc) |
目录页（TOC域代码，Word中更新域生效） |
add_chapter_title(doc, text) |
章标题+分隔线 |
add_colored_box(doc, title, lines, bg, line_color) |
通用彩色框 |
add_memory_box(doc, title, lines) |
记忆锦囊（蓝底蓝线） |
add_warning_box(doc, title, lines) |
易错警示（红底红线） |
add_example_box(doc, title, lines) |
经典例题（橙底橙线） |
add_table(doc, headers, rows, col_widths) |
深蓝表头+隔行灰底表格 |
render_full_section(doc, section_data) |
渲染完整12板块节 |
12个 render_*() 函数 |
各板块独立渲染 |
第三阶段：逐章生成数据模块
按章节创建 data_chXX.py 文件，每个文件导出 get_chXX_data() 函数。
数据模板：详见 references/data_template_spec.md
12板块标准模板（每节必须包含）：
| 序号 | 板块 | emoji | 数据字段 | 说明 |
|---|---|---|---|---|
| 1 | 学习导航 | 📋 | objectives/key_points/difficulties/duration | 学习目标+重点难点 |
| 2 | 课前热身 | 🔥 | warmup: [(Q,A),...] | 激趣导入问题 |
| 3 | 知识精讲 | 📖 | knowledge: [(子标题, 行列表),...] | 核心知识详解 |
| 4 | 记忆锦囊 | 🧠 | memory: [(标题, 行列表),...] | 口诀/技巧/对比表 |
| 5 | 易错警示 | ⚠️ | warnings: [(误区,正解),...] | 常见错误辨析 |
| 6 | 经典例题 | 📝 | examples: (标题,题目,分析,解答[,总结]) | 5元组或4元组 |
| 7 | 重难点专项突破 | 🎯 | breakthrough: {title,analysis,method,exercises} | 专项突破方法 |
| 8 | 实验与探究 | 🔬 | experiments: 5元组 | 实验全流程 |
| 9 | 生活物理 | 🏠 | life_physics: [(标题,内容),...] | 生活应用链接 |
| 10 | 知识框架 | 🗺️ | framework: [缩进文本,...] | 知识树 |
| 11 | 达标检测 | ✅ | quiz: {questions, answers} | 基础练习+答案 |
| 12 | 自我评价 | 📊 | self_eval: {items, suggestions} | 评价表+建议 |
内容编写核心原则：
- 物理公式用 Unicode 上下标（10³、v=s/t），禁用 OMML
- 支持 **加粗** 富文本标记
- 记忆锦囊必须有口诀、技巧或对比表，不能只是知识复述
- 易错警示要明确 ❌误区 + ✅正解 的对比
- 经典例题必须包含思路分析，不能只给答案
- breakthrough 可为 None（无专项突破的节），但不能为空字典 {}
- 跨学科实践整合到章节末尾，不单独成章
并行生成策略：章节数据文件之间无依赖，可使用 Agent 工具并行创建多个 data_chXX.py，每章一个后台 agent。
第四阶段：组装与生成
- 测试构建：先只导入前2章数据，运行
build_tutorial.py，验证排版无误 - 完整构建：导入全部数据模块，生成完整文档
- 检查统计：验证段落数、表格数、章节数是否匹配预期
第五阶段：质量审查
按照 references/quality_checklist.md 逐项检查：
- 内容完整性：每节至少6板块，知识点全覆盖
- 科学性审查：公式、常数值、单位换算、实验步骤、例题逻辑
- 数据格式校验：元组长度、字典键名、无占位符
- 排版一致性：标题格式、Unicode渲染、表格宽度
重点检查项（历史经验教训）：
- 密度/速度等数值中无重复系数（如 "1.05×1.05×10³" 应为 "1.05×10³"）
- 对比表格内容完整，不能只有标题空壳
- 例题答案逻辑自洽，多解情况需明确标注
- breakthrough 字段：None 正常，空字典 {} 会导致渲染异常
第六阶段：错误修复与重建
发现问题后修改对应 data_chXX.py，重新运行 build_tutorial.py 生成文档。
技术栈
- Python 3.12+ + python-docx 1.2.0
- 工作目录：用户指定的工作空间下
scripts/子目录 - 输出：工作空间根目录下的
.docx文件
关键注意事项
- 禁止 OMML 公式：所有物理/数学公式使用 Unicode 字符，不使用 Word 的 OMML 数学公式。原因：python-docx 对 OMML 支持有限且渲染不稳定。
- rich text 仅支持加粗：
**text**标记由_parse_rich_text()解析，不支持斜体/下划线等其他格式。 - 彩色框实现：使用单列表格模拟（左侧粗竖线 + 背景色），不是真正的文本框。这是 python-docx 的局限。
- breakthrough 判断：使用
sd.get('breakthrough')而非'breakthrough' in sd，因为None值存在但不应渲染。 - examples 元组兼容：渲染函数同时支持 4 元组和 5 元组，5 元组多一个"方法总结"字段。
- 中文排版：正文字体宋体，标题字体微软雅黑，公式字体 Cambria Math。需设置
w:eastAsia属性确保中文字体生效。 - TOC 域代码：目录使用 Word 域代码插入，用户需在 Word 中右键更新域才能显示实际目录。
