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