Hermes Agent的Word文档技能，踩坑后我整理了这份攻略

Hermes Agent的DOCX技能终于曝光：AI写Word文档居然有这么多坑

#AI工具 #Office自动化 #Hermes Agent

2026年7月22日

你有没有想过，让AI帮你写一份Word文档，结果它给你整出一堆黑色表格、乱码列表、还有怎么都对不齐的目录？

别笑，这事儿真不是段子。最近Hermes Agent（Nous Research搞的那个开源AI代理框架）把自己内置的DOCX技能文档给公开了，我仔细扒了一遍，好家伙——原来AI操作Word文档，踩的坑比咱们手动排版还多。什么”表格阴影一不留神就变纯黑”、”列表符号千万别手打”、”XML命名空间一碰就炸”……看完我整个人都不好了。

但话说回来，这份文档也是真·宝藏。它把AI创建、阅读、编辑Word文档的完整工作流讲得明清楚白，连那些”老手才知道”的暗坑都给你标出来了。今天咱就把它掰开了揉碎了，给你讲清楚。

─── ⋆⋅☆⋅⋆ ───

这技能到底是干嘛的？

说白了，Hermes Agent的DOCX技能就是一个”Word文档全能助手”。它能干的事儿包括：创建新文档（报告、备忘录、信函、信纸）、读取已有文档内容、编辑修改现有文档、插入目录、处理修订标记（就是Word里那个”追踪修订”）、添加批注……基本上你在Word里能干的事儿，它理论上都能干。

技术上怎么实现的呢？这里有个关键认知：.docx文件本质上就是一个ZIP压缩包，里面装着一堆XML文件。所以这个技能的工作方式分两条路——创建新文档走docx-js（一个npm库），编辑已有文档则直接解压、改XML、再打包。暴力但有效。

看到没，这玩意儿是默认安装的（Bundled），不用你额外折腾。而且它跟PDF、Excel、PPT技能是配套的，等于一整套Office自动化全家桶。

─── ⋆⋅☆⋅⋆ ───

创建文档：docx-js的八个”致命”暗坑

创建新文档用的是docx-js这个npm库。API本身不难，模型（AI）也知道怎么调用。但问题在于——这库有一堆”看起来应该这么写，实际上会翻车”的地方。文档里专门列了一个gotchas清单，我翻译成人话给你：

页面尺寸：默认是A4不是Letter

如果你要生成美式Letter尺寸的文档，必须手动设置 page: { size: { width: 12240, height: 15840 } }，单位是DXA（1440 DXA = 1英寸）。不设？默认给你出A4。对国内用户来说倒无所谓，但要是给美国客户出文档，这就尴尬了。

表格：宽度必须设两遍

这个坑真的绝了。你既要在表格级别设 columnWidths，又要在每个单元格上设 width，而且必须用 WidthType.DXA。用百分比？祝贺，Google Docs里直接给你裂开。列宽之和还必须等于表格总宽，差一个像素都不行。

表格阴影：用CLEAR别用SOLID

这个我看完直接笑出声。你给表格加个背景色，顺手写了个ShadingType.SOLID——好嘛，整个表格变纯黑。必须用 ShadingType.CLEAR，这命名谁设计的，出来挨打。

列表：永远别手打”•”

想加个项目符号？千万别直接插入一个”•”字符。正确做法是配置 numbering 并使用 LevelFormat.BULLET。手打的点在Word里就是一坨死文字，没有缩进、没有层级、没有自动编号，纯纯的灾难。

⚠️ 血泪教训：ImageRun必须指定type属性（”png”、”jpg”等）；PageBreak必须放在Paragraph里面；永远不要用
换行——用单独的Paragraph元素；目录（TOC）的标题必须用内置HeadingLevel.*，自定义样式得设outlineLevel否则目录里根本不显示。

还有个骚操作：右对齐制表符

想做那种”左边文字……右边页码”的目录样式？别用空格或点号硬凑。用 PositionalTab，设 alignment:
PositionalTabAlignment.RIGHT 加 leader: PositionalTabLeader.DOT，放在TextRun里面。优雅，且不会在不同字体下错位。

─── ⋆⋅☆⋅⋆ ───

✨ 编辑已有文档：拆ZIP改XML的”外科手术”

重点来了。docx-js这库有个致命限制——它打不开已有文件。所以编辑现有Word文档，走的是另一条路：解压、改XML、重新打包。听着原始，但这是目前最可靠的方案。

完整流程长这样：

DOCX编辑工作流（五步走）

Step 1：解压

unzip -q doc.docx -d unpacked/（如果是legacy .doc文件，先用LibreOffice转成.docx）

Step 2：清理 + 合并

删除符号链接条目（外部文档不可信），然后跑 merge_runs.py 把碎片化的文本runs合并成连续字符串

Step 3：编辑XML

直接修改
unpacked/word/document.xml，注意：不要格式化、不要美化打印

Step 4：重新打包

cd unpacked && rm -f ../out.docx && zip -Xr ../out.docx .（必须从目录内部打包，且先删旧文件）

Step 5：验证

python
scripts/office/validate.py out.docx –original doc.docx（XSD校验 + 关系检查 + 内容类型检查）

这里有个特别有意思的细节：Word会把一段连续文字拆成无数个 <w:r> 标签（由于修订ID、拼写检查标记等缘由）。所以你在文档里明明看到一句话，在XML里搜它——搜不到。由于它被切成了七八个碎片。merge_runs.py 就是干这个的：把格式一样的相邻runs合并，让文本变得”可搜索”。

关于追踪修订（Redlining）：验证时加上 –author “你的名字” 参数，它会检查你改的每一处文字是否都被 <w:ins>/<w:del> 包裹了。漏掉一个？在”接受修订”视图里完全看不出来，但文档结构已经坏了。另外，<w:del> 里面的文本元素是 <w:delText>，不是 <w:t>，这个搞错直接schema报错。

─── ⋆⋅☆⋅⋆ ───

批注系统：六个文件联动的”精密手术”

你以为在Word里加个批注就是插一行文字？Too young。在OOXML规范里，一条批注需要六个相互交叉引用的文件同时正确才能显示：comments.xml、commentsExtended.xml、commentsIds.xml、commentsExtensible.xml、关系文件、内容类型覆盖文件。

好消息是，Hermes提供了一个 helper 脚本（comment.py），帮你自动处理这六个文件的创建和关联。你只需要告知它批注内容，它就把所有底层XML都写好，然后打印出一段 <w:commentRangeStart>/<w:commentRangeEnd>/<w:commentReference> 代码片段——你把这段塞到document.xml里对应位置，批注就锚定到具体文字上了。

支持两种模式：对已解压目录操作（推荐，省一次打包），或者直接对.docx文件操作。还能加 –parent 参数实现批注回复（嵌套批注）。

# 对已解压目录添加批注 python scripts/comment.py unpacked/ “费用上限太低了” # 添加回复批注 python scripts/comment.py unpacked/ “同意” –parent 0 # 直接对.docx操作 python scripts/comment.py contract.docx “这个条款有问题” -o annotated.docx

─── ⋆⋅☆⋅⋆ ───

️ 避坑指南 + 验证流程

最后这部分是精华中的精华。文档里列了几个”碰了就会死”的雷区：

常见翻车场景 vs 正确做法

第一个大坑：千万别用Python标准库的 xml.etree.ElementTree 来处理OOXML。这玩意儿会重写命名空间前缀，直接把文件搞坏。正确选择是 defusedxml.minidom。你品品，一个解析器选错，整个文档报废。

第二个大坑：打包必须从解压目录内部执行。命令是 cd unpacked && zip -Xr ../out.docx .，而且必须先rm掉目标文件。不然你删掉的部件还会残留在压缩包里，像个幽灵一样跟着你。

验证环节也不能省：生成完文档后，先用validate.py跑一遍schema检查，再用LibreOffice把docx转成PDF，然后用pdftoppm把PDF转成图片，最后用视觉分析逐页检查——看表格有没有裂、图片有没有丢、间距有没有跑偏、有没有残留的占位文字。

温馨提示：pdftoppm生成的图片文件名会按总页数补零。列如12页的文档，图片名是 page-01.jpg 到 page-12.jpg，不是 page-1.jpg。写脚本遍历的时候注意这个细节，不然会漏文件。

─── ⋆⋅☆⋅⋆ ───

写在最后

看完这份技能文档，我最大的感受是：AI操作Office文档这件事，远没有我们想象的”智能”。它更像是一个极其听话但完全没有常识的实习生——你让它加个表格阴影，它不会告知你”SOLID会变黑哦”；你让它编辑个XML，它不知道ElementTree会搞坏命名空间。

但反过来说，Hermes团队把这些坑全部文档化、脚本化、自动化了。merge_runs.py解决文本碎片问题，comment.py解决六文件联动问题，validate.py解决schema校验问题，accept_changes.py解决修订接受问题。每一个脚本背后，都是无数次翻车换来的经验。

所以如果你也在折腾AI+Office自动化，这份文档值得收藏。不是由于它多高深，而是由于它够诚实——把那些”文档里不会写但你会踩”的坑，全都摊开给你看了。

“一个好的工具文档，不是告知你怎么用，而是告知你怎么不用错。” —— 某个被ShadingType.SOLID坑过的开发者（大致）