教材自学教程生成器

概述

将教材PDF转化为结构化自学教程Word文档（.docx），采用"排版引擎 + 数据分离"架构：Python排版引擎负责Word渲染，数据模块按章节组织内容，12板块模板确保每节结构统一。

适用场景：中小学各学科教材的自学教程、预习指南、教辅材料生成。

必要输入

调用此技能时，必须向用户确认以下信息：

1. 教材：提供教材PDF路径，或教材名称+版本+年级（如"人教版八年级物理上册 2022版 六三制"）
2. 学科：如物理、化学、数学、生物等（影响公式风格和实验描述规范）

可选输入：

• 目标读者（默认：零基础预习学生）
• 输出格式偏好（默认：Word .docx）
• 是否需要联网补充教参（默认：是）

工作流

第一阶段：分析教材结构

1. 读取教材PDF：使用 Read 工具读取教材PDF，提取章节目录和知识点框架
2. 搜索补充资料（可选）：使用 WebSearch 搜索对应学科章节的优质教参材料，补充教材中阐述不足的知识点
3. 生成章节大纲：列出全部章节、小节、跨学科实践的标题清单，供用户确认

第二阶段：构建排版引擎

1. 创建 scripts/build_tutorial.py：从本技能 scripts/build_tutorial.py 复制排版引擎模板
2. 适配封面信息：修改 add_cover() 中的标题、版本信息
3. 适配数据导入：修改 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。

第四阶段：组装与生成

1. 测试构建：先只导入前2章数据，运行 build_tutorial.py，验证排版无误
2. 完整构建：导入全部数据模块，生成完整文档
3. 检查统计：验证段落数、表格数、章节数是否匹配预期

第五阶段：质量审查

按照 references/quality_checklist.md 逐项检查：

1. 内容完整性：每节至少6板块，知识点全覆盖
2. 科学性审查：公式、常数值、单位换算、实验步骤、例题逻辑
3. 数据格式校验：元组长度、字典键名、无占位符
4. 排版一致性：标题格式、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 文件

关键注意事项

1. 禁止 OMML 公式：所有物理/数学公式使用 Unicode 字符，不使用 Word 的 OMML 数学公式。原因：python-docx 对 OMML 支持有限且渲染不稳定。
2. rich text 仅支持加粗：text 标记由 _parse_rich_text() 解析，不支持斜体/下划线等其他格式。
3. 彩色框实现：使用单列表格模拟（左侧粗竖线 + 背景色），不是真正的文本框。这是 python-docx 的局限。
4. breakthrough 判断：使用 sd.get('breakthrough') 而非 'breakthrough' in sd，因为 None 值存在但不应渲染。
5. examples 元组兼容：渲染函数同时支持 4 元组和 5 元组，5 元组多一个"方法总结"字段。
6. 中文排版：正文字体宋体，标题字体微软雅黑，公式字体 Cambria Math。需设置 w:eastAsia 属性确保中文字体生效。
7. TOC 域代码：目录使用 Word 域代码插入，用户需在 Word 中右键更新域才能显示实际目录。