前言¶
在 DSH 工作流里把技术文档从 Markdown 落到 Word，公式往往是最易出错的一环：常见管线会把公式变成图片、用上标字符拼成「伪公式」，或留下一段 LaTeX 源码，后续在 Word 里难以双击编辑，导出 PDF 也容易发糊。若文档里公式多、还要在 Word / WPS 里继续改稿，就需要一条能把 LaTeX 写成 Word 原生公式对象（OMML） 的路径，并在生成后做数量与版式校验，而不是只写完 docx 就结束。
下面介绍社区插件 dsh-formula-docx（维护者 Red-Rayux，分类：工作流）。它在 DeepSeek Harness 生态里以插件形式接入，核心是把 Markdown 经 LaTeX → MathML → OMML 写入 .docx，并可通过导出 PDF、逐页看图的方式核对公式是否都正确渲染。
这是什么¶
dsh-formula-docx 的职责可以概括为：把 Markdown 变成公式为 Word 原生公式对象（OMML）的 .docx——在 Word 里可双击编辑，WPS 可正常打开，导出 PDF 时不依赖公式截图。它与「公式图片」或「上标下标字符拼贴」不是同一类方案。
- 插件名称（npm / 包名）：
dsh-formula-docx - 维护者：Red-Rayux
- 当前包版本（package.json）：0.1.0
- 许可证：MIT
- 社区目录页：https://www.skillhub.cn/plugins/Red-Rayux/dsh-formula-docx
- 源码与说明：https://github.com/Red-Rayux/dsh-formula-docx
DSH 的理念是「一切皆插件」；SkillHub 等社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。安装插件前，建议自行阅读仓库源码与许可证；插件在 当前 dsh 进程权限 下运行，应与对待任意第三方依赖一样谨慎。
核心功能¶
根据仓库 README 与包描述，已核实的能力包括：
- 公式转换链路：每个公式走
LaTeX → MathML → OMML，以原生方程对象写入文档，而非图片或字符 hack。 - 多文件合并构建：
build.py可接收一个或多个 Markdown 文件（或 glob），按顺序拼接，可选封面（cover.json）与页码。 - Markdown 扩展语法：标题（h1 自动分页）、行内与块级公式、表格（含列宽如
[w:20,30,50]）、::: core等 callout 块等；完整说明见仓库references/syntax.md。 - 校验流程：
-check_docx.py：对比 docx 中方程数量与 Markdown 源里的 LaTeX 数量，发现遗漏或重复渲染（静默失败常表现为空框或重复公式）。
-preview.py：经 Word 导出 PDF（LibreOffice 可作后备），将每页渲染为 PNG，用于发现 XML 里看不出的版式问题（表格挤压、标题孤行、callout 跨页等）。 - 生产踩坑文档：仓库
references/pitfalls.md记录了六类常见问题及修复思路（重复公式空框、WPS 与ns0:命名空间、\text{}内中文、编号列表被公式打断、粗体内含行内公式、\xrightarrow与 OMML 映射等）。
没有安装 Microsoft Office 时仍可生成 docx，但会失去基于 Word 的 PDF 预览校验能力。
依赖与环境¶
| 需求 | 用途 |
|---|---|
| Python 3.9+ | 运行转换脚本 |
pip install lxml latex2mathml python-docx |
转换与写 docx |
MML2OMML.XSL |
随 Microsoft Office 提供；可自动检测，或通过环境变量 MML2OMML_XSL 指定 |
| Microsoft Word | PDF 预览校验（LibreOffice 可作后备） |
pip install pymupdf |
预览校验阶段渲染 PDF 页面 |
DSH 插件侧声明的对等依赖：@deepseek-ai/dsh-tools（>=0.1.0-rc.1 <0.2.0-0）。
安装与启用¶
在已配置 DSH 的环境里，按 README 给出的命令安装插件（勿自行改写 owner/repo 格式）：
dsh plugin add Red-Rayux/dsh-formula-docx
本地跑转换脚本前，先装好 Python 依赖：
pip install lxml latex2mathml python-docx pymupdf
典型用法¶
README 建议 先做冒烟测试，再构建自己的文档。下列命令均来自仓库快速开始说明。
1. 冒烟测试（不要跳过）
python scripts/build.py /tmp/smoke.docx examples/smoke.md
python scripts/check_docx.py /tmp/smoke.docx --md examples/smoke.md
python scripts/preview.py /tmp/smoke.docx
2. 合并多章 Markdown 并加封面
python scripts/build.py out.docx ch01.md ch02.md ch03.md --cover cover.json
3. 校验与预览
python scripts/check_docx.py out.docx --md ch0*.md --pdf out.pdf
python scripts/preview.py out.docx --dpi 120
语法示例（节选，与 README 一致）：
# Headings (h1 auto page-breaks)
**Bold with an inline formula $E=\pi L$ inside.**
$$R=\frac{\pi\left(L-L_P\right)}{T_\phi\left(T_\theta E_0\cos\theta+E_D\right)}$$
[w:20,30,50]
| Quantity | Definition | Unit |
|---|---|---|
| Radiance | flux per projected area per solid angle | $\mathrm{W\cdot m^{-2}\cdot sr^{-1}}$ |
::: core
**Callout block** — holds paragraphs, lists, and display formulas.
:::
经过上面的步骤，你得到的是可编辑 OMML 公式的 docx，并用数量对比与 PDF 逐页图把「公式丢了」和「版式坏了」两类问题尽量拦在发布前。
适用场景与注意¶
更适合：
- 公式密集的说明书、讲义、技术章节，需要在 Word / WPS 中继续改公式、再导出 PDF。
- 希望把工作流里的 Markdown 源与 Word 交付物绑定，且愿意把
check_docx.py/preview.py当成发布流水线的一部分。
需要注意：
- 校验是流程的一部分，而不是可选 ornament；方程计数不一致往往不会在 XML 里 loudly 失败。
- 中文应尽量放在公式外的正文；
\text{}内中文可能导致转换问题（见 pitfalls 文档）。 - 插件通过 DSH 加载后，其行为取决于你本机 Python、Office 与脚本调用方式；在无 Word 环境下要接受「无视觉 PDF 校验」的折中。
结尾¶
dsh-formula-docx 针对的是 Markdown 转 Word 时公式不可编辑、易糊、难验收的痛点：用 OMML 落盘，并用计数校验加 PDF 翻页看图把风险压到可控范围。若你要在 DSH 工作流里接这条链路，可从社区目录与 GitHub 仓库对照安装命令与脚本用法。
- 目录页：https://www.skillhub.cn/plugins/Red-Rayux/dsh-formula-docx
- GitHub：https://github.com/Red-Rayux/dsh-formula-docx
