md-to-word

# md-to-word（Markdown 转 Word） ## 目标 将一个或多个 Markdown 文档转换为格式优美的 Word（.docx），基于 Pandoc + 内置 reference.docx 模板（可选自定义模板），并确保不修改任何原始 Markdown 文件。内置模板已修复命名空间兼容性问题，支持 RGBA 图片自动转换。 ## 流程 ### 输入 输入为一个或多个 Markdown 文件；可选输入包括内置或自定义 `reference.docx`、输出目录、Pandoc 参数和图片处理选项。转换不得修改原始 Markdown，输出路径须在用户授权范围内。 ### 执行步骤 #### 你要解决的问题 用户给你一个或多个标准 Markdown 文档，希望把它们转换成**排版美观、可审查、可交付**的 Word（`.docx`），并且能在不同项目里复用同一套转换流程与样式模板。 **常见问题解决方案**： - **RGBA PNG 导致 Word 警告**：使用 `--fix-images` 自动转换为 RGB 模式 - **图片路径问题**：脚本自动处理相对路径资源引用 - **中文排版问题**：使用 `--template cn-modern` 获得更好的中文样式 #### 内置模板（Pandoc reference.docx） 内置模板文件位于 `assets/`： - `default`：`assets/reference-default.docx` - `cn-modern`：`assets/reference-cn-modern.docx`（中文更友好字体/样式） - `compact`：`assets/reference-compact.docx`（更紧凑段落间距） #### 推荐执行方式 优先运行确定性脚本 `scripts/md_to_word.py`，避免 AI 手写 Pandoc 命令导致参数缺失或误覆盖。 示例： ```bash python3 md-to-word/scripts/md_to_word.py \ --template cn-modern \ --output-dir /path/to/out \ /path/to/a.md /path/to/b.md ``` 如用户需要自定义样式，允许： - 使用 `--reference-doc /path/to/reference.docx` 覆盖内置模板（用户自带）。 - 需要用同一份 Markdown 生成多套风格时，使用 `--output-suffix` 避免覆盖（默认不覆盖）。 - 用户不确定模板可选项时，先运行 `python3 md-to-word/scripts/md_to_word.py --list-templates`。 #### 核心工作流 ##### 步骤 0：预检查（不写任何输出前） 1. 校验 `md_files` 均存在且为文件。 - 默认仅接受 `.md/.markdown`；如用户确实给了其他扩展名，必须显式使用 `--allow-any-extension`。 2. 确认 Pandoc 可用（默认执行 `pandoc --version`）；不可用时给出明确安装提示，并停止。 3. 选择模板： - 优先 `--reference-doc`（用户显式指定）； - 否则使用 `--template`（默认 `default`）。 4. 计算输出路径： ...