标签：#WorkBuddy #Pandoc #Markdown #效率工具 适用：习惯用 Markdown 写作、但需要把成批文档导出成 Word（.docx）发给他人协作的场景。
目录
一、背景与痛点
二、方案选型：为什么用 Pandoc
三、环境准备
四、核心脚本（单文件版）
五、封装成 WorkBuddy Skill（一句话批量）
六、实战演示（占位示例）
七、踩坑记录与解决方案
八、积分节省效果
九、命令行参数版（更通用）
十、常见问题 FAQ
十一、小结
一、背景与痛点
Markdown 写起来轻快，但现实协作里对方往往只认 Word：
领导 / 同事 / 客户：」发我个 Word 版」
排版交付：Word 才能控样式、插批注、定页眉页脚
批量场景：几十上百个 .md 要统一转 .docx，手动点根本不现实
常见错误做法：
把 MD 内容复制进 Word 手动重排：格式全乱，上百个文件做到崩溃。
用云端工具逐个上传转换：每次消耗积分，量大了很贵，文件还可能外泄。
我的目标：批量、本地、免费、样式可控。下面这套用 Pandoc，转一整个文件夹成本 = 0 积分。
二、方案选型：为什么用 Pandoc
方案 中文支持 是否需联网 单次成本 样式可控
在线 MD 转 Word 网站 中 是 按次/按页 弱
云端大模型生成 docx 高 是 几十~上百积分 中
Pandoc 本地 高 否 0 强（模板）
Pandoc 是文档格式转换的事实标准，本地运行，支持上百种格式互转。搭配一个 .docx 模板，就能让所有输出文件统一字体、标题层级、页边距——比在线工具强太多。
三、环境准备
安装 Pandoc（一次即可）：
Windows：winget install pandoc 或官网下载安装包
macOS：brew install pandoc
Linux：sudo apt install pandoc
（可选）准备一个样式模板 template.docx： 用 Word 新建空白文档，设好中文字体（如宋体/微软雅黑）、标题样式、页边距，另存为 template.docx。之后所有输出都套用这套样式。
验证安装：
bash
pandoc --version
四、核心脚本（单文件版）
存成 md_to_docx.py，处理单个文件：
python
import subprocess
def md_to_docx(md_path: str, out_path: str, template: str = None):
"""用 Pandoc 把单个 Markdown 转成 Word。"""
cmd = ["pandoc", md_path, "-o", out_path]
if template:
cmd += ["--reference-doc", template]
subprocess.run(cmd, check=True)
print(f"[完成] {md_path} -> {out_path}")
if name == "__main__":
示例：把 示例文件夹/测试文档.md 转成同名 docx
md_to_docx("示例文件夹/测试文档.md",
"示例文件夹/测试文档.docx",
template="template.docx")
运行：
bash
python md_to_docx.py
生成的 测试文档.docx 就是排版好的 Word 文件了。
五、封装成 WorkBuddy Skill（一句话批量）
成批转换时，反复敲命令很烦。封装成 WorkBuddy Skill 后，说一句「把 示例文件夹 里的 MD 全转成 Word」，它就自动遍历、转换。
markdown
name: md-to-docx-batch
description: Markdown批量转Word(docx)。使用本地Pandoc，
零 token 消耗，支持模板统一样式。
Markdown 批量转 Word
触发词：MD转Word、批量转docx、markdown导出、md转文档
流程
- 用 glob 找到目标目录下所有 .md
- 对每个文件调用 md_to_docx.py
- 输出同名 .docx 到原目录（已有则跳过）
配合批量入口 batch_convert.py：
python
import os, glob
from md_to_docx import md_to_docx
def batch_convert(folder: str, template: str = None):
mds = glob.glob(os.path.join(folder, "", "*.md"), recursive=True)
print(f"找到 {len(mds)} 个 Markdown")
for md in mds:
out = md[:-3] + ".docx"
if os.path.exists(out):
continue # 跳过已转换的，避免重复
md_to_docx(md, out, template=template)
if name == "__main__":
batch_convert("示例文件夹", template="template.docx")
这样 WorkBuddy 一句话就能把整批 MD 转完，全程本地、零积分。
六、实战演示（占位示例）
假设 示例文件夹 里有三份文档：
示例文件夹/
├── 测试文档A.md
├── 测试文档B.md
└── 测试文档C.md
└── template.docx
执行 python batch_convert.py 后：
找到 3 个 Markdown
[完成] 示例文件夹/测试文档A.md -> 示例文件夹/测试文档A.docx
[完成] 示例文件夹/测试文档B.md -> 示例文件夹/测试文档B.docx
[完成] 示例文件夹/测试文档C.md -> 示例文件夹/测试文档C.docx
打开任意 .docx，标题层级、字体都已按 template.docx 统一，直接可发。
截图建议：放一张「终端输出 3 个完成」的图 + 一张「Word 里样式正确」的图。
七、踩坑记录与解决方案
坑 1：转换后中文显示成方框 / 乱码 原因：系统缺中文字体，或模板字体未嵌入。 解决：模板 template.docx 里显式指定中文字体（如「微软雅黑」）；Linux 服务器需装 fonts-noto-cjk。
坑 2：表格 / 代码块样式不对 原因：默认样式没覆盖这些元素。 解决：在 template.docx 里先定义好「普通表格」「代码」样式，Pandoc 会自动套用。
坑 3：图片路径丢失 原因：MD 里用了相对路径图片，但输出目录不同。 解决：图片放 MD 同目录；或转换时先 cd 到 MD 所在目录再跑 Pandoc。
坑 4：公式没渲染 原因：默认不启用数学引擎。 解决：加参数 --pdf-engine 无关（那是 PDF 用的）；docx 下公式用 --mathjax 不行，需装 pandoc-crossref 或转成图片插入。
坑 5：想保留 MD 里的目录 解决：在 MD 顶部写 [TOC]，转换时加 --toc 参数，Pandoc 会生成 Word 目录域。
八、积分节省效果
对比三种方式把 50 个 MD 转成 Word：
方式 成本
在线转换网站（约 0.02 元/次） 约 1 元现金
云端大模型逐文件生成 约 500~1500 积分
本方案（本地 Pandoc） 0 积分 / 0 元
文档越多省得越多——几百个文件就是 0 vs 上万积分。
九、命令行参数版（更通用）
把路径写死不方便分享。改成支持命令行参数，任意文件、任意模板都能跑，也更利于封装进 Skill：
python
import os
import argparse
import subprocess
os.environ.setdefault("PYTHONUTF8", "1")
def md_to_docx(md_path: str, out_path: str, template: str = None):
cmd = ["pandoc", md_path, "-o", out_path]
if template:
cmd += ["--reference-doc", template]
subprocess.run(cmd, check=True)
print(f"[完成] {md_path} -> {out_path}")
def main():
parser = argparse.ArgumentParser(description="Markdown 批量转 Word（零 token）")
parser.add_argument("md", help="输入 Markdown 路径（支持通配符）")
parser.add_argument("-o", "--output", default=None, help="输出 docx 路径")
parser.add_argument("-t", "--template", default=None, help="样式模板 docx")
args = parser.parse_args()
out = args.output or (args.md[:-3] + ".docx")
md_to_docx(args.md, out, template=args.template)
if name** == "__main__":
main()
用法：
bash
单文件，套用模板
python md_to_docx.py 示例文件夹/测试文档.md -t template.docx
批量（shell 展开通配符）
python md_to_docx.py 示例文件夹/*.md -t template.docx
十、常见问题 FAQ
Q1：Mac / Linux / Windows 都通用吗？ 通用。Pandoc 全平台一致，仅模板字体名因系统而异（Windows 用「微软雅黑」，macOS 用「苹方」）。
Q2：能反过来把 Word 转回 Markdown 吗？ 能。pandoc input.docx -o output.md 即可，适合把别人发来的 Word 归档成纯文本。
Q3：公式、脚注、交叉引用支持吗？ 公式和脚注原生支持；交叉引用需装 pandoc-crossref 过滤器，属进阶用法。
Q4：和 WorkBuddy 的「生成 PPT / 文档」有什么区别？ WorkBuddy 生成文档走云端模型，单次耗积分；本文方案本地 Pandoc，零积分、可批量、样式靠模板统一，适合已有 MD 源文件的规模化转换。
Q5：转换速度如何？ 单文件通常 < 1 秒，50 个文件几秒搞定，全程不联网。
Q6：能直接转 PDF 吗？ 能。pandoc input.md -o output.pdf，但 PDF 需本机有 LaTeX 引擎（如 TinyTeX）或走 --pdf-engine=weasyprint。
十一、小结
成批 MD 转 Word，本地 Pandoc 是最省钱（0 成本）且样式最可控的路。
核心就是一行 pandoc input.md -o output.docx，套模板即可统一排版。
封装成 WorkBuddy Skill，以后一句话批量转换，全程离线、零积分。
适合：写作归档、文档交付、知识库导出等任何 Markdown 规模化转 Word 的场景。