前言¶
在 DeepSeek Harness（DSH）裏處理技術文檔時，常見路徑是讓用戶上傳 .docx，再由 Agent 轉成 Markdown 入庫或續寫。直接用 Pandoc 往往卡在 Word 裏的公式：OLE（Equation Editor / MathType）、Word 原生 OMML，以及截圖式圖片公式，載體不同，誤差形態也不同。OLE 若只做二進制解碼，常常不報錯卻給出殘缺字符，比 outright 失敗更難排查。
下面介紹社區插件 dsh-docx2md（維護者 stallenlu），分類爲工作流。它把上述三類公式分別走確定性與讀圖兩條路，儘量保留公式編號與文檔結構，並在 DSH 中提供 inspect → extract → build 工具鏈，供 Agent 按步驟調用。
這是什麼¶
dsh-docx2md 是發佈在 npm 上的 DSH 插件（當前文檔中的示例版本爲 0.6.5），許可證爲 MIT。一句話定位：把含公式的 Word 文檔轉成帶 LaTeX 的 Markdown，跨平臺運行；OLE、Word 原生 OMML、圖片公式三種載體都會處理。
DSH 生態主張「一切皆插件」；SkillHub 等爲社區目錄站點，與 DeepSeek / 幻方無官方從屬關係。插件在當前 DSH 進程的權限下運行，安裝前應自行查看源碼與許可證。
三種公式，三條處理路徑¶
Word 裏公式的存儲方式決定了插件能否「確定性」轉出 LaTeX，還是必須藉助渲染後的位圖。
| OLE 公式 | OMML（Word 原生） | 圖片公式 | |
|---|---|---|---|
| 典型來源 | Equation Editor / MathType；WPS 公式默認載體 | Word 2007+ 插入公式默認格式 | 截圖粘貼、掃描頁、從 PDF 拷貝 |
| 插件策略 | 渲染 PNG → 視覺模型逐張轉寫 | extract 階段從 XML 確定性轉 LaTeX | 無法自動結構化；佔位符 + media/ 原件供轉寫 |
| 純 OMML 文檔 | 混排時才需讀圖部分 | 全程可不讀圖 | 需人工參與 |
對 OLE，插件原則是：以渲染位圖爲準，不以 MTEF 解析字符爲準。README 中舉例：同一份多公式文檔，直接解 MTEF 可能只得到兩三個字符，卻不報錯。渲染失敗會明確標記，不靜默降級到錯誤解碼。
純 OMML 文檔可用空的 LaTeX 表配合 docx2md_build 產出完整 Markdown（OMML 會預填）；混排文檔裏 OLE 與圖片公式部分才需要讀圖步驟。
核心能力（與 README 一致）¶
除正文與公式外，插件還處理文檔中的複雜圖形場景（細節以倉庫 README 爲準）：
- 掃描與統計：
docx2md_inspect只輸出事實（段落數、OLE / OMML / 圖片公式候選數量、本機渲染引擎等），不下結論。 - 抽取中間物：
docx2md_extract寫出paras.json、eq_index.json（OMML 條目可帶latex字段）、media/、png/、image_inventory.json等；流程圖畫布可整塊渲染爲media/canvasN.png，畫布內公式在索引中標記in_canvas，避免重複佔位。 - 組裝 Markdown：
docx2md_build根據工作目錄與 LaTeX 映射生成最終.md，並支持標題建議等可選參數（完整參數見 README）。
在 Agent 裏可直接說明需求，例如：「把 論文.docx 轉成 Markdown，公式要保留。」Agent 會加載 docx2md 技能並按 inspect → extract → 讀圖 → build 順序執行。
運行環境¶
| 依賴 | 用途 | 必需 |
|---|---|---|
| Python 3.9+ | 運行 py/ 下腳本 |
是 |
olefile |
解 OLE、讀取 Equation Native | 經 uvx 自動安裝 |
uv（可選） |
管理 Python 依賴 | 推薦 |
公式圖渲染會按平臺探測：Windows 桌面可用 GDI+；Linux / macOS 常用 LibreOffice（soffice），需自行安裝；畫布類 v:group / DrawingML 圖版需無頭瀏覽器（Edge / Chrome）。缺引擎時 docx2md_inspect 會說明，docx2md_extract 會把 render.ok 置爲 false，不假裝成功。
package.json 要求 Node ^22.19.0 || >=24.0.0，peer 依賴 @deepseek-ai/cordis ^4.0.2。
安裝與啓用¶
DSH 的 profile 用 pnpm 管理依賴（nodeLinker: hoisted）。日常使用建議裝 npm 正式包，不要手工往 node_modules 拷貝目錄。
在 desktop profile 下執行（版本號可按需替換）：
cd ~/.dsh/profiles/desktop
pnpm add dsh-docx2md@0.6.5
或使用 DSH 安裝器等價命令：
dsh plugin --profile desktop add dsh-docx2md@0.6.5
也可安裝與 npm 包字節一致的 GitHub Release tarball：
dsh plugin --profile desktop add https://github.com/stallenlu/dsh-docx2md/releases/download/v0.6.5/dsh-docx2md-0.6.5.tgz
package.json 需同時滿足兩點：dependencies 裏爲 npm 版本號（pnpm add 會寫入 lockfile）；在 dsh.profile.bundles 中加入 "dsh-docx2md"。包內已聲明 dsh.bundle.patch，不要再往 profile 的 cordis.patch.yml 手寫 insert，否則會重複註冊。
若希望改 bundles 後立即生效，可在 profile 的 package.json 配置：
"dsh": { "profile": { "patchReload": "live" } }
無此項時需重啓 DSH 進程後工具纔可用。僅開發插件源碼時才考慮 file: 或 github: 依賴，正式環境請繼續用 dsh-docx2md@0.6.5。
卸載時：
cd ~/.dsh/profiles/desktop
pnpm remove dsh-docx2md
並從 bundles 刪除對應條目後重啓 DSH。
典型用法¶
在 Agent 中¶
用自然語言交代路徑與要求即可，由技能驅動工具鏈。
三個工具（摘要）¶
只讀掃描：
docx2md_inspect(path)
抽取到目錄（可選 outDir、render）：
docx2md_extract(path, outDir?, render?)
生成 Markdown：
docx2md_build(workDir, latex, out, ...)
人工或模型需要爲 OLE、圖片公式填寫/校對 LaTeX 時，讀 png/ 與 eq_index.json；OMML 已在 extract 階段寫入 latex 字段。升級插件後，README 建議重啓 DSH 並跑一次 docx2md_inspect 覈對行爲。
適用場景與注意¶
適合：
- 論文、教材、技術規範等 Word 稿轉 Markdown，且公式不能丟編號與結構；
- 以 OMML 爲主、少量 OLE 或圖片公式的混排文檔（OMML 部分可自動化）；
- 需要在 DSH 工作流裏把「轉檔」拆成可檢查的中間步驟（inspect / extract 便於排錯）。
注意：
- 圖片公式與部分 OLE 依賴讀圖質量與人工校對，不能期望全自動零差錯；
- Linux / macOS 需自備 LibreOffice 等渲染能力；無頭瀏覽器缺失時畫布可能無法完整渲染，但會在
summary.json等處給出警告而非靜默丟圖； - 插件不替代你對文檔版權與敏感內容的審查；轉換在本地 profile 環境中執行，權限與 DSH 進程一致。
結尾¶
dsh-docx2md 把「含公式 Word → LaTeX Markdown」拆成可觀測的步驟：先分清 OLE、OMML、圖片三種載體，再按路徑轉換或讀圖，避免 Pandoc 式靜默殘缺。若你在 DSH 裏維護文檔工作流，可從 npm 0.6.5 裝入 profile，用 bundles 啓用後交給 Agent 調用。
