Md2word

工作流

1. 按模板来源三选一分流：
   • .mht：直接使用
   • .docx：先归一化导出为 .mht
   • 模板规格/文字描述：先生成可复用 .mht
2. 用 render_mht.py 把 Markdown 填进模板。
3. 调 Windows Word 打开 MHT，另存成 .docx。
4. 在 Word 内把 LaTeX 文本转换成 Office Math，输出 .wordmath.docx。

模板与样式

• 如果用户给模板文件，优先复用模板，不要重造
• 如果用户只给一句模板描述，先写成 template-spec.md 再传给 --template-spec
• 模板规格参考：resources/template-spec.md
• 当前内置样式预设：
  • default
  • academic-paper
• 静态模板、模板规格和样式预设统一放在 resources/
• 用户明确给出论文标题字号、标题层级、正文行距时，优先：
  • 在模板规格里写 style-preset: academic-paper
  • 调用时再显式传 --style-preset academic-paper

正文插入策略

• 如果模板里有 {{CONTENT}} 或 <!--MD_CONTENT-->，优先按占位符替换
• 如果模板里有 {{METADATA_TABLE}}，会把 Markdown 头字段渲染成信息表
• 如果模板里已有表格标签，例如 项目名称、电话、版本，会按行标签尝试填值
• 如果没有显式占位符，会推断 WordSection，优先替换最后一个正文 section
• 推断过程可通过 --template-report 输出报告

命令

使用内置默认模板：

<skill-dir>\scripts\md2word.cmd `
  --input disclosure.md

使用模板规格生成模板：

<skill-dir>\scripts\md2word.cmd `
  --input example.md `
  --template-spec template-spec.md `
  --template-out generated-template.mht `
  --template-report template-report.md

生成学术论文格式：

<skill-dir>\scripts\md2word.cmd `
  --input example.md `
  --template-spec template-spec.md `
  --template-out academic-paper.mht `
  --template-report academic-paper.report.md `
  --style-preset academic-paper

使用现成 Word 宏而不是内置公式转换：

<skill-dir>\scripts\md2word.cmd `
  --input disclosure.md `
  --macro-name "LatexToWordMath_Better"

直接调用 Python 主脚本：

py -3 <skill-dir>\scripts\md2word.py `
  --input disclosure.md `
  --style-preset academic-paper

兼容旧的 PowerShell 包装入口：

powershell -ExecutionPolicy Bypass -File <skill-dir>\scripts\md2word.ps1 `
  -Input disclosure.md `
  -StylePreset academic-paper

公式与 Mermaid

• render_mht.py 会把 Markdown 图片作为 MHT 关联资源打包进去
• 标准 Markdown 表格会转成正文 Word 表格，并保留基本对齐方式
• render_mht.py 会把 Mermaid 代码块渲染成图片插入 MHT
• 当前 Mermaid 渲染默认写入保守的 Puppeteer 配置，规避 headless shell 在受限环境下失败
• md2word.py 会在生成的 DOCX 中把 Markdown 标题映射回 Word Heading 样式和大纲级别
• word_mht_pipeline.ps1 会把常见块公式环境归一化后再交给 Word BuildUp
• 当前已覆盖这些块环境：
  • matrix
  • pmatrix
  • bmatrix
  • Bmatrix
  • vmatrix
  • Vmatrix
  • cases
• Word 不支持把 \begin{matrix}...\end{matrix} 原样直接 BuildUp；要先转成 \matrix{...} 或外层加分隔符

附带文件

• scripts/md2word.py：Python 主入口，统一编排模板分流、渲染和 Word 流水线
• scripts/md2word.cmd：Windows 命令行包装器，转发到 Python 主入口
• scripts/md2word.ps1：PowerShell 兼容包装器，转发到 Python 主入口
• scripts/pipeline_common.py：主入口共享的参数校验、路径规划和文件校验逻辑
• scripts/render_mht.py：渲染 MHT、处理正文和 Mermaid
• scripts/generate_template_mht.py：从模板规格生成可复用 MHT 模板
• scripts/style_presets.py：统一加载样式预设配置
• scripts/word_common.ps1：Word worker 共享的 COM 清理与路径 helper
• scripts/word_template_to_mht.ps1：DOCX 模板归一化为 MHT
• scripts/word_mht_pipeline.ps1：Word 导出与 Office Math 转换
• resources/template-spec.md：模板规格参考
• resources/style-presets.json：样式预设配置
• resources/专利交底书模板.mht：默认 fallback 模板

失败处理

• 如果 PowerShell、Python 或 Word COM 不可用，不要假装 Windows 之外能补全最终 Word 效果，直接报环境问题
• 如果 Mermaid 渲染失败，先看是否有本机 mmdc；没有的话确认是否允许 npx 下载
• 如果模板效果不对，先看 --template-report
• 如果公式异常，先区分：
  • 原始 .docx 已经错：问题在 MHT 或公式文本归一化
  • 原始 .docx 正常、.wordmath.docx 才错：问题在 Word BuildUp
• 如果矩阵类公式再次出问题，先检查传给 Word 的线性格式是否已经被归一化成 \matrix{...} 族，而不是残留 \begin{...} / \end{...}