hs-physics-handout

一个 Claude Skill：把高中物理真题 / 原卷 .docx 自动整理成 印刷级复习讲义 / 学案（.docx）——按人教版教材知识体系编排，自动生成 学生版（无解析） 与 教师版（含解析），并且——最关键的——公式在 WPS 和 Microsoft Word 中都能正确显示。

适用于任意高中物理模块（力学 / 电磁学 / 热学 / 光学 / 近代物理），不限于热学。

为什么需要它

做讲义最折磨人的两件事，这个 skill 都解决了：

1. 公式在 WPS 乱码。 用 MathType/公式对象做的公式抽取时会丢数据、跨编辑器显示不一致。 本工具把公式渲染成普通的上下标 + 线性分式，任何编辑器显示都一致。你写一小段 LaTeX 子集 （\dfrac{}{}、_{}、^{}、\sqrt[]{}），开箱即用。
2. 排版繁琐。 专题横幅、高频考点/易错警示彩框、题目卡、解析框、斑马表、页边框、目录、 页码全部封装成一行方法，你只写内容。

沉淀的工作流（四段式）

每个专题固定结构：

专题 N  <知识主线>
  一、核心知识梳理   （概念/规律/物理意义/易错点/高频考点，按教材顺序）
  二、典型例题        （保留题干 + 标注考点 + 详细过程 + 规范答案）
  三、方法归纳        （解题模型/常见题型/解题步骤/易错原因）
  四、随堂练习        （额外 2~3 题 + 参考答案）

知识点编排、各模块知识主线、各题型解题模型详见 references/physics_workflow.md。

目录结构

hs-physics-handout/
├── SKILL.md                       # 技能定义：触发条件 + 完整操作步骤
├── scripts/
│   ├── handout_builder.py         # 可复用排版库（Handout 类 + WPS 兼容公式引擎）
│   └── extract_docx.py            # 从源 .docx 抽取文字 + 图片（含公式对象陷阱提醒）
├── references/
│   ├── physics_workflow.md        # 物理专属工作流：知识主线 + 解题模型 + 规范
│   ├── api_and_formulas.md        # 全部方法 + LaTeX 子集语法
│   └── example_build.py           # 完整可运行模板（已通过冒烟测试）
├── assets/
│   └── sample_teacher_edition.docx# 模板生成的样例成品
├── requirements.txt / LICENSE / .gitignore / README.md

快速开始

pip install -r requirements.txt

# 冒烟测试：生成两个专题的样例讲义
python references/example_build.py

# 实际使用：抽取原卷 → 分析考点 → 写内容脚本驱动 builder
python scripts/extract_docx.py "专题05 热学（原卷版）.docx" --out-dir extracted

API 与公式语法见 references/api_and_formulas.md，完整示例见 references/example_build.py。

API 一瞥

from handout_builder import Handout

h = Handout(title="高二物理热学专题复习讲义", edition="教师版·含解析",
            topics=["专题一　分子动理论"], image_dir="extracted/img")
h.cover()
h.h1("专题一　分子动理论")
h.h2("一、核心知识梳理")
h.formula_box(r"\dfrac{p_{1}V_{1}}{T_{1}}=\dfrac{p_{2}V_{2}}{T_{2}}=C")
h.callout("【高频考点】", "油膜法 d=V/S 是高频实验。", kind="hot")
h.example(1, "分子力与浸润")
h.problem([("t", "露珠凝结于荷叶上…（　　）"), ("img", "image1.jpeg", 5.0)])
h.solution("B", [("t", "表面分子间距大，表现为引力，故选B。")])
h.save("讲义_教师版.docx")

作为 Claude Skill 安装

本仓库本身就是 skill：

• Claude Code / Agent SDK：放进技能目录（如 ~/.claude/skills/hs-physics-handout/）。
• Claude.ai / Cowork：打包整个文件夹上传为 skill。

安装后用自然语言即可触发，例如："把这份热学期末真题按考点做成复习讲义，出学生版和教师版"。

小贴士

• 打开成品后在目录处 右键 → 更新域 / Update Field 生成页码。
• 假定系统有中文字体（宋体/黑体）与 Times New Roman（Windows + WPS/Office 默认满足）。
• 公式引擎对数学/化学的上下标同样适用。

License

MIT — 见 LICENSE。