做技术文档这些年我几乎每天都在跟AI生成的Markdown打交道。客户要的是Word领导要的是Word投标要的也是Word可AI大模型吐出来的默认都是Markdown。你也许有过这种经历把ChatGPT回答里排版漂亮的标题、列表、表格直接复制粘贴到Word里结果标题层级乱成一锅粥表格挤成一团代码块连换行都丢了。今天这篇文章就是把我自己摸索出来的一套“AI Markdown到可交付Word”完整工作流分享出来——以Pandoc为转换核心配合自定义Word模板和自动化脚本再讲清楚图片、表格、公式、代码块这些最容易翻车的地方怎么处理最后聊聊如何接到Coze工作流里让“AI生成 格式转换 文件交付”跑成一条流水线。1. AI输出很好但交付很痛为什么不能直接复制粘贴1.1 一次真实的交付翻车现场先说个真实案例。我接了一个内部系统的功能说明书AI生成了35页Markdown里面有6个一级标题、十几个二级标题还有三四张表格和若干代码片段。我一开始也图省事把内容直接CtrlC、CtrlV粘到Word里结果相当惨烈一级标题变成了普通加粗段落想用导航窗格跳转不存在的。二级、三级标题全部变成正文整份文档的层级感瞬间消失。表格虽然粘贴过来了但列宽完全不可控有的列窄得只剩一个字符。代码块没有灰底也没有等宽字体看起来跟普通段落没区别。项目符号的缩进全乱二级列表和一级列表混在一起。更离谱的是AI回答里有一张用Mermaid画的流程图复制到Word直接变成了一串代码文本完全没法看。那天下午我花了近四个小时手工调整这些格式才勉强能交付。后来我复盘发现这种“人肉排版”不仅效率低还极容易出错——你永远不知道哪一级标题漏改了哪张表的列宽又跑偏了。后来我学乖了不再直接复制粘贴而是走结构化转换。也就是从那一刻起我开始认真研究“把AI的Markdown变成可交付Word”这件事。1.2 复制粘贴丢掉的不是格式是结构为什么直接复制粘贴会乱根本原因在于Markdown和Word是两种完全不同的文档模型。Markdown是“标记语言”你写一个#它表达的语义是“这是一级标题”写一个-表达的是“这是一个无序列表项”。而Word是“所见即所得”的排版工具它靠的是“样式”这个概念——标题1、标题2、正文、列表段落等等。当你把Markdown文本粘进Word时Word只会机械地保留字符没法自动识别“这是一级标题该用标题1样式”更没法把|分隔的表格语法解析成真正的Word表格。换句话讲直接复制粘贴丢掉的不是表面的格式而是文档的结构。没有结构Word里的目录、导航窗格、样式批量修改全部失去意义。而一份真正“可交付”的Word恰恰最需要的就是结构客户要能一键生成目录领导要能在导航窗格里快速跳转法务要能批量调整所有标题的字体颜色。这些能力只有通过结构化转换工具才能实现。抱着这个想法我开始寻找能稳定把Markdown转成Word的方案。试了一圈之后最后锁定了Pandoc。2. 转换引擎选择Pandoc才是那个“瑞士军刀”2.1 Pandoc的转换逻辑与核心优势Pandoc是一个命令行文档转换工具在文档处理圈子里名气很大核心能力是能把Markdown转成Worddocx、PDF、HTML、LaTeX几乎你能想到的格式它都支持。它的转换逻辑基于AST抽象语法树先把Markdown解析成统一的文档结构再把这个结构输出成目标格式。这意味着Pandoc是“读懂”你的标题层级、列表、表格、代码块之后再做转换而不是像文本替换那样机械处理。最基础的一条命令就能完成转换pandoc input.md -o output.docx就这么一行80%的Markdown都能正确转成Word而且标题会映射成Word内置的“标题1”“标题2”表格会生成真正的Word表格代码块会成为带样式的段落。一开始我还不信直到我自己跑了一次打开生成的Word文件看到导航窗格里整整齐齐的标题层级我才真正意识到这才是正经的转换方式。Pandoc还有两个关键能力支持自定义Word模板通过--reference-doc参数可以让生成的文件符合公司的格式规范。支持命令行批量执行写个循环就能处理几十篇文档。这两个能力直接解决了“可交付”的核心痛点格式可控、批量可用。2.2 主流替代方案对比与我的取舍在确定Pandoc之前我也试过其他方案简单列个对比供你参考方案优势劣势适用场景Typora、小语文稿等高颜值Markdown编辑器界面友好写作体验好单篇手动导出不好批量导出样式依赖编辑器内置模板个人快速出稿VSCode Markdown插件预览方便插件生态好很多插件导出Word时底层还是在调用Pandoc写代码文档时的编辑器辅助在线转换服务零安装速度快隐私风险高格式不可控无法批量非敏感内容临时用PDF转Word保留排版大致形状会丢失文档结构需要先有PDF转换结果需大量清理万不得已的兜底方案python-docx自己写程序灵活性最高工作量大Markdown解析、样式映射要自己实现有特殊需求的定制场景我的结论很明确Pandoc作为核心引擎Typora这类编辑器用于写初稿和审视中间结果在线工具我基本不用——尤其是公司内部或客户交付的场景内容往往涉及敏感信息上传到在线转换站的风险太大。3. 从Markdown到Word的完整转换流程3.1 先把Markdown整理成“可交付级”很多人的Markdown源文件其实是不规范的AI生成的内容更是如此。转换之前我通常会先花几分钟把Markdown“清洗”一遍确保它是真正的“可交付级”。这一步能省掉后面大量的排错时间。我的检查清单是标题层级不要跳级。比如从##直接跳到####中间少了###Word里的标题结构会很难看目录也会出现断档。图片放在统一目录使用相对路径比如assets/01.png不要写成本地绝对路径C:/Users/xxx/Desktop/01.png不然换个环境就找不到图。表格每行列数保持一致使用标准的Github风格表格语法。AI生成时偶尔会少写分隔线导致整个表格解析错误。代码块统一标注语言类型比如python、javascript这样Pandoc才能在Word里为代码块保留语言标识。公式统一用LaTeX语法写法也就是$...$或$$...$$。清理掉AI生成时多余的横线分隔符---或三个连续星号***这些在Markdown里是分隔线转到Word后往往变成一条突兀的横线。清洗后的文件结构大概是这样的# 系统功能说明书 ## 1. 登录模块 ### 1.1 登录流程 用户输入账号密码后系统进行校验。  | 字段 | 说明 | |---|---| | 账号 | 员工工号 | | 密码 | 至少8位 | ## 2. 权限管理这一步看似繁琐但它是保证后续转换质量的关键。一个干净的Markdown源文件胜过后端排错半小时。3.2 Pandoc转换命令与自定义Word模板整理好Markdown后执行转换就很简单了。最基础的命令是pandoc input_ready.md -o output.docx --resource-path.--resource-path.的含义是告诉Pandoc当前目录下的资源文件也就是图片可以被引用。如果不加这个参数有时图片路径解析会出问题。如果你想控制生成Word的样式就需要自定义模板。Pandoc的模板机制其实很好理解你先让Pandoc生成一份“模板文档”然后你用Word打开这份模板修改里面“标题1”“正文”“表格”等样式的字体、字号、颜色、行距再保存。之后每次转换都把这份模板传给Pandoc它生成的Word就会套用这些样式。生成模板文件的命令pandoc -o custom-reference.docx --print-default-data-file reference.docx然后用Word打开custom-reference.docx修改样式保存。之后转换时指定模板pandoc input_ready.md -o output.docx --reference-doccustom-reference.docx但凡你见过一次用对模板和没用模板的差异你就知道这一步有多重要。我所在的团队要求正文用小四号宋体、行距固定值20磅、标题用黑体我把这些全配在模板里之后每一份生成的Word都自动符合要求再也不用手动微调。3.3 批量转换脚本一次处理几十篇文档单篇手动转换很简单但如果你手上有一堆AI生成的Markdown等着转Word批量脚本就成刚需了。我一般用Python写一个小脚本import subprocess from pathlib import Path template custom-reference.docx md_files list(Path(.).glob(*.md)) for md in md_files: out md.with_suffix(.docx) cmd [ pandoc, str(md), -o, str(out), f--reference-doc{template}, --resource-path., ] subprocess.run(cmd, checkTrue) print(f转换完成: {md.name} - {out.name})这个脚本会把当前目录下所有.md文件转换成同名.docx。你可以按需加功能比如按日期生成子目录、给文件名加版本号后缀、转换完自动用python-docx检查一下文件能不能正常打开等等。整套流程跑下来几十篇文档五分钟内全部搞定。4. 图片、表格、公式、代码块最容易翻车的四个场景4.1 图片路径与显示控制图片是我在实际转换中踩坑最多的地方。AI生成的Markdown里图片引用经常是网络URL或者是一长串经过编码的相对路径。Pandoc默认不会自动下载网络图片结果转到Word里就是一片空白只有个文件名。我的处理方式是先写个脚本把网络图片下载到本地再把Markdown里的URL替换成相对路径import re import requests from pathlib import Path md Path(input.md).read_text(encodingutf-8) urls re.findall(r!\[[^\]]*\]\((https?://[^)])\), md) assets Path(assets) assets.mkdir(exist_okTrue) for i, url in enumerate(urls, start1): ext url.split(.)[-1].split(?)[0] if ext not in (png, jpg, jpeg, gif, webp): ext png name fimage_{i}.{ext} r requests.get(url, timeout15) if r.status_code 200: (assets / name).write_bytes(r.content) md md.replace(url, fassets/{name}) Path(input_ready.md).write_text(md, encodingutf-8)图片全部下载到本地后转换时加--resource-path.Word里就能正常显示。另外图片大小也是个容易忽略的点。AI生成的图片通常尺寸参差不齐直接转进Word可能出现一张巨大的图把整页撑满的情况。我的做法是在Markdown里给图片加统一的宽度属性。Pandoc对带属性的图片转Word时会自动套用相应宽度{width14cm}或者是用百分比{width70%}不过要注意这种方式对Pandoc版本有要求旧版本对属性的解析不稳定。如果你发现宽度属性没生效可以先升级Pandoc再检查模板里图片样式的宽度约束。4.2 表格宽度与页面适配Markdown表格转成Word后最常见的两个问题是表格太宽超出页面以及列宽分配不合理。前者在长文本字段多的时候特别常见。先说原因Markdown表格本质上只有列数和对齐方式没有列宽概念。Pandoc转Word时会根据内容估算列宽遇到长文本就会撑宽某一列。我的经验是转换前先在Markdown里把表格内容控制在合理长度如果确实有一列要放很长的说明文字可以在引用模板里提前定义表格样式把表格整体宽度限制在页面内容区内并开启自动换行。实践中我更推荐在reference docx里设置表格样式具体操作是用Word打开模板文档右键点击表格选择“表格属性”把“指定宽度”勾上设为100%相对于页面再在“单元格”选项里勾选“自动换行”。这样所有通过Pandoc生成的表格都会继承这个样式。如果表格列数实在太多能拆就拆。一个超过8列的表格放进Word横版页面都未必排得开。我一般把“指标说明类”的宽表格拆成两三个窄表格可读性反而更好。4.3 数学公式的转换与后续微调数学公式是技术文档里躲不开的部分。Pandoc会把你在Markdown里写的LaTeX公式转换成Word原生的OMML公式也就是Word里那种可以双击进入公式编辑器直接编辑的公式对象。这一点我非常喜欢因为它不是图片而是可编辑的。最简公式写法质能方程 $E mc^2$。 独立成行的公式 $$ \int_0^\infty e^{-x^2} dx \frac{\sqrt{\pi}}{2} $$转换后Word里能看到公式并且按住Ctrl再点公式能进入编辑状态。我实测下来Pandoc对常见公式分式、积分、求和、上下标、希腊字母基本都能正确转换。但有两个坑要提醒你复杂的矩阵、多行对齐的分段函数偶尔会转换得不完整。转完后要手动在Word里检查。如果你的Word文档是双栏排版长公式很容易超出栏宽出现公式把栏宽撑破的情况。我当时也遇到“word双栏公式过长”这个经典问题解决办法是在公式编辑器里手动对长公式做换行或者把超长公式单独放一行并缩小字号。另外热词里还有人搜“mathtype word中对齐”。如果你后续要把公式交给用MathType的同事或客户建议在Word里直接使用MathType的“转换公式”功能把原生OMML公式转成MathType格式。这个过程虽然多一步但能避免对方打开文档后公式全都显示异常的尴尬。4.4 代码块样式等高亮保持代码块在Word里能不能保持“代码感”取决于两个地方一是Pandoc是否用了高亮主题二是reference docx里是否定义了“Source Code”样式。Pandoc默认会把代码块转成Word里的“Source Code”段落样式。如果模板里没有专门定义这个样式代码块看起来就跟普通正文一样。我的做法是在自定义模板里把“Source Code”样式设置为等宽字体中文用“等线”或“微软雅黑”西文用Consolas。字体大小比正文小一号。加浅灰色底纹比如F2F2F2。设置一定的段落间距和左右缩进。设置好后生成的Word里代码块干净、清楚一眼能看出是代码。同时Pandoc还支持语法高亮主题通过--highlight-style参数指定pandoc input.md -o output.docx --highlight-stylemonochrome可选的主题包括github、tango、kate、monochrome等。不过要提醒一句--highlight-style控制的是代码内关键字颜色如果在Word模板里已经有你要求的公司规范高亮主题反而不是重点我更推荐先用monochrome保证黑白打印不花哨。5. 在Coze工作流里落地从AI生成到Word输出一条龙5.1 为什么要把转换做进工作流现在很多人已经在用Coze这类AI工作流平台搭建自动化内容生产管线。通常的做法是让大模型生成Markdown生成完把内容复制出来再手动丢到Pandoc里转Word。这其实还是半自动——凡是需要人工搬运的地方就会变成瓶颈。尤其是你一周要产出几十份方案文档、周报、投标初稿的时候手动转换不仅慢还容易漏步骤。所以我把转换能力封装成一个HTTP服务接到Coze工作流里让整体流程变成大模型生成Markdown → 自动转Word → 自动保存或发送。这才是真正的“一条龙”。5.2 工作流节点设计与参数约定我先说一下整体设计。Coze工作流里一般会有大模型节点、代码节点或HTTP请求节点、文件输出节点。我走的方案是大模型节点输出Markdown文本然后交给HTTP请求节点调用我自己部署的转换服务转换服务返Word文件流。服务端我用Python Flask写了一个简单的接口from flask import Flask, request, send_file import subprocess import tempfile import os app Flask(__name__) TEMPLATE /data/custom-reference.docx app.route(/convert, methods[POST]) def convert(): data request.get_json() md_text data.get(markdown, ).replace(\r\n, \n) with tempfile.TemporaryDirectory() as tmp: md_path os.path.join(tmp, input.md) docx_path os.path.join(tmp, output.docx) with open(md_path, w, encodingutf-8) as f: f.write(md_text) subprocess.run( [pandoc, md_path, -o, docx_path, f--reference-doc{TEMPLATE}, --resource-path.], checkTrue, ) return send_file(docx_path, as_attachmentTrue, download_nameoutput.docx) if __name__ __main__: app.run(host0.0.0.0, port8000)Coze这边的HTTP节点只需配置请求URLhttp://你的服务地址/convert请求方法POSTBodyJSON格式{markdown: 大模型节点输出的内容}输出文件时把HTTP节点返回的文件字段传给文件输出节点Coze会自动将它作为可下载的文件附件。你也可以选择把文件保存到对象存储、上传到企业微信/钉钉机器人甚至直接通过邮件发送。这样整个流程就打通了。5.3 实际运行中的几个坑这个方案跑起来之后我也踩过几个坑列出来帮你避雷。第一个是换行符问题。Coze大模型节点输出的文本在不同浏览器和系统里可能携带\r\n。如果服务端不去管它Pandoc在解析时偶尔会把这些空白字符当成多余内容。所以服务端拿到Markdown后一定要先做标准化处理把\r\n统一替换成\n。第二个是图片问题。大模型生成的Markdown里很少带真实图片但万一带了网络URL服务端这边不处理生成出来的Word客户端打开就是没有图。我的建议是如果内容里需要图片尽量在Coze工作流里预先设计好插图列表转成Markdown时用本地相对路径引用再由服务端把图片和文本一起处理。第三个是超时。Pandoc单篇文档转换通常在1到2秒内完成但如果你一次往服务端扔一个超长Markdown或者服务端机器性能一般转换可能超过Coze HTTP节点的超时时间。我的经验是单次转换控制在20页以内超过20页拆成多个文档分别转换再在Word里合并。第四个是文件名中文乱码。send_file里的download_name如果是中文有些老版本浏览器的下载文件名会乱码。可以用urllib.parse.quote转成URL编码或者干脆统一用output.docx这种英文文件名等下载下来再本地改名。6. Word文件打不开、样式不对、中文乱码排查链路复盘6.1 文件损坏的排查顺序有一段时间我经常收到同事反馈“你转的Word打不开提示文件已损坏。”遇到这种问题我的排查顺序非常固定先在命令行手动执行一次Pandoc看有没有报错。如果命令行里就报错问题很可能出在Markdown源文件本身比如表格语法错误、括号没闭合。检查输出路径是否有中文或特殊字符。Windows下有些中文路径加模板文件路径组合起来会让Pandoc输出异常。检查reference docx是否被其他程序占用。尤其是你用Word打开模板时正在生成文件文件占用会导致写不进去。升级Pandoc到最新版。旧版本处理某些新Markdown语法时会出问题。用python-docx直接打开输出文件确认基本结构是不是完整的。大部分“文件损坏”问题最后都指向两个原因模板文件被占用或Pandoc版本太旧。模板占用问题尤其隐蔽因为Pandoc命令行可能不报错但生成的文件就是打不开。所以我后来在自动化脚本里加了一个规则生成文件之前先复制一份模板到临时目录再用临时副本转换。cp custom-reference.docx /tmp/custom-reference.docx pandoc input.md -o output.docx --reference-doc/tmp/custom-reference.docx这个改动之后模板占用导致文件损坏的情况几乎绝迹了。6.2 默认模板自定义与样式统一说到样式统一很多团队都有自己的一套格式规范正文几号字、标题什么字体、行距多少、页边距多大。如果你不把这些配置到模板里Pandoc生成的Word只能算“能打开”谈不上“可交付”。我第一次自建模板时犯了个错我直接在空Word文档里敲了几个标题、几段正文改好字体然后把这个文档当成reference docx用。结果转换出来所有文字都变成正文样式标题样式全丢了。后来我才明白Pandoc在套用reference docx时找的是文档里的“样式定义”不是“具体文字示例”。你得通过Word的样式面板把“标题1”“标题2”“正文”“Source Code”“表格”等样式本身改好而不是手动选中文字改格式。具体操作步骤用pandoc -o custom-reference.docx --print-default-data-file reference.docx生成默认模板。用Word打开这份模板打开“样式”面板。右键“标题1”选择“修改”设置字体、字号、颜色、缩进。同样的方式修改“标题2”“标题3”“正文”“Source Code”等样式。通过“布局”选项卡设置页边距。保存关闭。之后每次转换都用这份模板输出文件的样式就完全符合团队规范。我还会在模板里把标题1设置为“段前分页”这样每个一级标题都自动从新的一页开始省去了手动插入分页符的麻烦。6.3 目录生成、中文CJK字体与分页控制最后说三个附加功能它们能让你的Word更接近“可交付”状态。第一个是自动目录。在转换命令里加上--toc和--toc-depth即可pandoc input.md -o output.docx --toc --toc-depth2生成的Word会在文档开头插入一个目录。注意这个目录是基于Word域生成的。如果你在Word里人工修改了标题文字想更新目录需要全选后按F9更新域。第二个是中文字体问题。Pandoc转Word时默认样式里的字体可能不含中文字体导致中文显示成了奇怪的默认字体。解决办法还是在模板里定义检查“正文”样式的“字体”设置把中文字体设为宋体或微软雅黑西文字体设为Times New Roman或Calibri。这样转换出来中英文都能正常显示。第三个是分页控制。Markdown本身没有分页概念如果你想在某些章节前强制分页除了在模板里把标题1设为段前分页之外也可以利用Pandoc的原始OpenXML插入分页符{openxml} w:pw:rw:br w:typepage//w:r/w:p不过我试下来这个办法在复杂模板里偶尔会失效。最稳妥的方式还是让模板里的标题样式自带分页属性或者转换完成后在Word里手动调整。大多数情况下标题样式分页已经能满足需求。 这套流程我在实际项目中跑了将近一年最深的体会是AI负责内容生成Pandoc负责格式转换我负责在关键节点做人工确认三者各管一段才能真正做到“可交付”。如果你也经常被AI的Markdown和客户的Word双重夹击强烈建议先把这套管线搭起来。最后一个小建议保存一个干净的reference.docx模板别用别人传给你的改花了的版本否则各种样式问题会反反复复浪费你大把时间。