课堂讲义整理 Lucas101518/dsh-class-skill

dsh-class-skill

把课程/讲座录音转写材料整理成干净讲义（Markdown）＋ 公式为 Word 原生可编辑对象的 .docx。

给 DeepSeek Harness（DSH）用的技能，也可以脱离 DSH 直接当命令行工具用。

English: a DSH skill that turns lecture/meeting transcripts into clean Markdown handouts plus a Word document whose equations are native OMML objects (editable on double-click — not images, not LaTeX source). It ships the converter, a KaTeX-compatibility linter, an ECMA-376 element-order validator, and a Word-COM end-to-end test.

为什么需要它

课堂/会议转写稿有三个固有问题，纯靠人读会漏、纯靠模型总结会错：

| 问题 | 例子 | 本技能的做法 |
| 语音识别把专业术语听成谐音 | "阿曼转向"→阿克曼、"侧边角"→侧偏角、"争议"→增益、"纸巾"→质心 | 按领域知识还原，而不是照抄转写稿；对照表见 reference/asr-fixes.md |
| 公式几乎不可能被正确记录 | 转写稿写"加UR" | 按标准教材体系补齐公式、符号表、推导链与编号 |
| 口水词、点名、闲聊淹没内容 | "大家看""能明白吗""是吧" | 清洗为可阅读的讲义结构 |

额外解决一个真正的工程坑：Markdown 公式能转成 Word 公式 ≠ 它在 Markdown 渲染器里能正常显示，反之亦然。
本技能把这两件事拆成两个独立的验收维度，都有脚本强制校验（见下文）。

它产出什么

在源文件同目录下：

- <主题>-整理版.md —— 论文式排版讲义：显示公式独占段落并统一编号（\tag{2.5}）、正文交叉引用"式 (2.5) / 表 3-1"、符号表、核心公式速查、术语辨析框
- <主题>-整理版.docx —— Word 版：公式为 OMML 原生对象（双击可编辑）、中文 w:eastAsia="宋体" + 西文 Times New Roman、公式居中 + 编号右对齐、A4 页边距与 1.5 倍行距

安装

作为 DSH 技能（推荐）

git clone https://github.com/Lucas101518/dsh-class-skill.git \
"$HOME/.dsh/skills/class-skill" # Windows: %USERPROFILE%\.dsh\skills\class-skill

DSH 会自动发现该目录下的 SKILL.md（技能目录：$DSH_HOME/skills/<名>/SKILL.md，项目级 .dsh/skills/ 优先级更高）。

把 SKILL.md 当作技能清单、其余 .py 当工具即可；也可以把整个目录指给任何支持"技能目录 + SKILL.md"约定的智能体。

作为命令行工具

只需要 Python 3.8+ 与两个纯 Python 依赖：

pip install python-docx lxml

用法

在 DSH 里

把腾讯会议导出的三件套（纪要文本 / 时间轴文本 / 逐字稿文本）发给它，说一句 "整理一下"，技能会走完整流程：读全部输入 → 清洗重构 → 论文式排版 → 转 Word → 跑全量校验。

触发词：整理一下 / 整理成讲义 / 整理成笔记 / 总结成文档 / 做成 Word / 转成 Word。

命令行：一键转换 + 校验

Windows：自动定位带 python-docx+lxml 的解释器，转换后立即全量校验 .\run.ps1 讲义.md # 输出 讲义.docx（同名同目录） .\run.ps1 讲义.md 输出.docx 指定解释器：$env:CLASS_SKILL_PYTHON = "D:\py\python.exe"

等价的手工两步
python md2docx.py 讲义.md 讲义.docx # Markdown → DOCX（原生公式）
python verify_all.py 讲义.md 讲义.docx # 全量校验，必须全部 PASS

单项校验：

python check_render.py 讲义.md # R1–R7：KaTeX 宏支持、$$ 摆放、锚点残留、公式内中文
python validate_ooxml.py 讲义.docx # ECMA-376 子元素顺序（Word 最严格的一项）
python word_test.py 讲义.docx # 用真实 Word COM 打开，确认不弹"发现无法读取的内容"

两个验收维度（本技能的核心设计）

| 维度 | 工具 | 典型故障 | 只查 md 会漏 | 只查 Word 会漏 |
| Markdown 渲染 | check_render.py | KaTeX parse error: Undefined control sequence（用了 \iddots 等非标准宏）；正文原样显示 $$…$$ | — | ✔ |
| Word 能否打开 | validate_ooxml.py + word_test.py | Word 报"发现无法读取的内容"、根号显示成空心方框 | ✔ | — |
两者互不覆盖，必须都查。 经验法则：LibreOffice / WPS / 网页预览正常 ≠ Word 能打开 —— 只有 word_test.py（Word COM 实测）才是最终判据。

verify_all.py 把两者串起来，覆盖：md 结构 → LaTeX 全部可转换 → 输出无 m:ctrlPr → OOXML 顺序合规 → 无乱码/无残留 markdown → Word 实测可打开。

踩过的坑（血泪教训，已固化成检查项）

Word 侧（导致"文件已损坏"，但所有预览器都正常）

1. 绝不生成 m:ctrlPr —— 位置放错 Word 直接拒开；tex2omml.py 在出口统一 _strip_ctrlpr() 从源头杜绝
2. OOXML 子元素顺序必须合规 —— python-docx 对自己管理的属性会插对位置，手工 append 的元素会跑错位；用 ensure_child() 按 ECMA-376 序列插入
3. m:rad 必须含 m:deg，否则根号渲染成空心方框（数据丢失）
4. 函数要用 m:func，否则 \arctan 在 Word 里被当成连乘变量
5. 中文必须显式设 w:eastAsia="宋体"，只设 font.name 会掉字体

Markdown 渲染侧

6. \iddots、\xlongequal、\coloneqq、\prescript、\bm、\textcolor 等非标准宏 KaTeX 不支持，直接报错（\dfrac/\binom/\cancel/\xrightarrow 等是支持的，别误判）
7. 块引用 > 内的 $$ 会被渲染成字面量 —— $$ 必须独占段落、前后各一空行、不放进引用块
8. 表格单元内不要放块级公式（会破坏表格结构），只放简短行内式
9. 公式里的中文要包 \text{}

完整清单与判定方法见 SKILL.md、reference/katex-support.md、reference/ooxml-order.md。

目录结构

dsh-class-skill/
├── SKILL.md 技能主文档：工作流 + 全部踩坑与判定方法（Agent 读这个） ├── tex2omml.py LaTeX → OMML 转换器（分式/根式/上下标/矩阵/方程组/重音/函数…）
├── md2docx.py Markdown → DOCX（原生公式 + 中文双字体 + 论文版式） ├── check_render.py Markdown 渲染兼容性校验（R1–R7） ├── validate_ooxml.py OOXML 子元素顺序校验（ECMA-376） ├── word_test.py 用 Word COM 实测能否打开（最终判据） ├── verify_all.py 一键全量校验 ├── run.ps1 一键转换 + 校验（自动定位解释器） └── reference/ ├── asr-fixes.md 语音识别错误 → 正确术语对照表（按学科分类，可持续补充） ├── ooxml-order.md ECMA-376 关键复合类型完整子元素顺序表 └── katex-support.md KaTeX 宏支持清单与 $$ 摆放规则

兼容性与边界

- 需要 Python 3.8+，依赖仅 python-docx、lxml（纯 Python，无需编译）。
- Word 实测（word_test.py）只在 Windows + 装了 Microsoft Word 的机器上有效；其他环境 verify_all.py 会把它降级为 WARN 并继续跑完其余检查。没有 Word 时以 validate_ooxml.py + LibreOffice 预览为次优判据。
- run.ps1 依次查找：$env:CLASS_SKILL_PYTHON → DSH 内置运行时 → PATH 上的 python/python3，并逐个验证 import docx, lxml 可用。
- 本技能不做语音转写，只处理已有的转写文本（腾讯会议三件套、字幕文件、普通转写稿均可）。
- reference/asr-fixes.md 是术语对照表，目前含车辆动力学与机器学习两类课程，欢迎按学科补充。

相关

- dsh-anchor-memory —— 同一作者给 DSH 的 Markdown 长期记忆插件（索引常驻 + 锚点检索 + 预算守卫）。

License

MIT © 2026 Lucas (Lucas101518)