前言¶
在 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
