md-to-word — Markdown 转 Word

将 Markdown 转换为排版规范的 Word 文档：标题层级、表格、图片、Mermaid 流程图、真正的 Word 目录（TOC 域）、中文字体（黑体标题 / 宋体正文）。

设计原则

"原文档没出现的内容，不出现"：

转换辅助数据（图片原始路径、尺寸）写入独立的 <md名>.meta.json 辅助文件，只给技能读，不进入 md / docx
TOC 域无占位文字（begin → instrText → end 最小结构），Word 打开时自动生成目录
不做画蛇添足的内容（如无「目录」标题的文档不主动插入目录）

何时使用

用户要求把 md 转成 Word / docx（含批量）
用户要求导出正式报告、需求文档、方案、论文为 Word
用户要求"保留图片 / 流程图 / 目录"的转换

前置条件（一次性安装）

bash scripts/setup.sh

脚本会创建隔离环境并安装依赖（幂等，可反复执行）。

pandoc 自动安装（默认行为）：执行转换时若未检测到 pandoc，技能会自动从 GitHub Releases 下载适配当前平台的版本并解压到隔离环境（$HOME/.venv-md-to-word/pandoc/），无需任何手动操作。可用 --no-auto-install 关闭自动下载（走纯 Python 引擎降级）。

可选增强（未安装时自动降级，不阻塞）：

| 依赖 | 作用 | 缺失时 | 免安装方式 | |------|------|--------|-----------| | pandoc | 主转换引擎（样式保真最高） | 自动下载安装 / 降级纯 Python 引擎 | 自动（或手动下载平台包放 vendor/）| | mermaid-cli (mmdc) | 渲染 ```mermaid 流程图 | 流程图保留为代码块 + warning | npm install -g @mermaid-js/mermaid-cli |

手动预装 pandoc 也可（三选一）：

自动：什么都不用做，转换时自动下载（推荐）
平台包：下载 pandoc zip 放 vendor/，setup.sh 自动解压（离线/内网环境）
系统安装：winget install JohnMacFarlane.Pandoc / brew install pandoc / apt install pandoc

macOS 注意：pandoc 官方仅提供 .pkg（需 sudo），无法自动免安装；建议 brew install pandoc。

使用步骤

1. 定位输入输出

输入：<input.md> 或 <input.docx>（必填）
输出（默认，自动隔离目录避免覆盖）：
- input.md → input_word_output/input.docx（与输入同目录）
- input.docx → input_md_output/input.md（含 .media/ 图片目录 + .meta.json 元数据）
可用第 2 个参数显式指定输出路径（如 out/自定义名.docx）

2. 执行转换

# CLI
"${MD2WORD_VENV:-$HOME/.venv-md-to-word}/Scripts/python.exe" scripts/md2word/cli.py input.md output.docx [options]

# 或 API
python -c "
from md2word import convert, ConvertOptions
r = convert('input.md', 'output.docx', ConvertOptions(preset='formal-report'))
print(r.success, r.warnings)
"

3. 常用选项

| 选项 | 说明 | |------|------| | --preset <name> | 风格预设：formal-report（默认）/ minimal | | --engine <auto/pandoc/python> | 强制指定引擎 | | --no-auto-install | 禁用 pandoc 缺失时的自动下载安装 | | --no-mermaid | 禁用流程图渲染 | | --no-toc | 禁用目录域插入 | | --keep-temp | 保留中间产物（调试） | | --json | 输出机器可读 JSON 结果 |

4. 验证输出

图片应全部嵌入（无 [图片不存在] 占位）
打开 docx：目录应在 Word 打开时自动生成（TOC 域无占位文字）
标题应用黑体、正文宋体、表格全边框、图片居中
转换后同目录生成 <md名>.meta.json（图片元数据辅助文件，仅技能使用）

处理流程

input.md (+ 可选 <md名>.meta.json 已有元数据)
  → 预处理：front-matter 提取 / mermaid → PNG / 图片属性提取到 meta / 图片路径绝对化
  → 引擎：pandoc（主）或 python（兜底）
  → 后处理：TOC 域（无占位）/ 中文字体 / 表格样式 / 图片居中 / 图片原始尺寸还原
  → output.docx + <md名>.meta.json（图片尺寸/溯源，md 保持干净）

已知限制

往返有损：docx→md→docx 永远无法完美还原（md 表达力上限）
损坏的表格（如 liteparse 摊平）无法自动重建（Phase 2 支持启发式重组）
Mermaid 渲染依赖 mmdc（有系统 Chrome 时自动复用，免下载 chromium）
复杂合并单元格表格、LaTeX 公式、脚注：Phase 2 支持

错误处理

| 场景 | 行为 | |------|------| | md 不存在 | success=false + 明确错误 | | pandoc 缺失 | 自动降级 python 引擎 + warning | | mmdc 缺失 | mermaid 保留代码块 + warning，不中断 | | mermaid 语法错误 | 保留代码块 + warning（含错误摘要） | | 图片缺失 | 保留引用 + warning | | 转换失败 | success=false + 错误信息 + warnings |