docx

docx 技能概览

docx 技能适合做什么

docx skill 用来帮助代理创建、检查和修改 Microsoft Word .docx 文件，相比泛用型提示词，在处理这类文件时盲区更少。它尤其适合需要真实 DOCX 工作流的用户：生成可直接交付的 Word 文档、提取内容供审阅、编辑现有文件、处理批注或修订记录，或在包级别直接操作 Office XML 结构来修复文件问题。

谁适合安装 docx

如果你经常需要以下能力，建议安装这个 docx skill：

• 生成 Word 文档，而不只是输出纯文本
• 在不手动打开 Word 点来点去的情况下编辑现有 .docx
• 保留标题层级、批注、修订等文档结构
• 在进一步处理前先转换老旧 .doc 文件
• 当普通文本提取不够用时，直接检查包内内容

对于 AI 辅助的文档处理场景，它尤其有价值：最终产物必须是一个可正常使用的 .docx，而不只是一个 markdown 草稿。

docx 和普通提示词的区别是什么

docx 的核心差异在于它对工作流有明确针对性。这个技能不会把 DOCX 当成“只是文本”。它知道 .docx 本质上是一个由 XML 文件组成的 ZIP 包，并会针对不同任务把代理引导到正确路径：

• 用 pandoc 做以文本为中心的读取与提取
• 通过 unpack/edit/repack 完成结构级编辑
• 用 LibreOffice 自动化处理部分格式转换和接受修订
• 在 XML 编辑可能把文件弄坏时，加入校验与修复步骤

因此，相比一句笼统的“写一份报告”，docx 在 DOCX 工作流里更靠谱，也更像真正可落地的方案。

最适合用 docx 处理的任务

当你的真实需求属于以下类型时，就应该用 docx：

• “生成一份分章节、格式专业的 Word 报告。”
• “读取这个 .docx 并做摘要，包括修订内容。”
• “替换或重组现有 Word 文件里的内容。”
• “以程序方式添加批注或处理修订。”
• “把 .doc 转成 .docx，以便后续安全编辑。”

采用前需要了解的重要限制

这个技能并不是万能办公套件。它最擅长的是目标明确指向 .docx 的任务。以下场景就没那么适合：

• PDF
• 以 Google Docs 为核心的协作
• 以电子表格为主的工作流
• 需要手动在 Word 桌面端反复校对的极致视觉排版
• 完全不能安装本地工具（如 pandoc 或 LibreOffice）的环境

实际取舍很明确：docx 提供了更强控制力，但一旦进入包级编辑，也意味着必须更谨慎。

如何使用 docx 技能

先看安装上下文，不要只找一条命令

仓库里的 SKILL.md 并没有提供一个正式的单一 docx install 命令，因此更准确的理解是：你是从 Anthropic skills 仓库中引入这个技能，然后配合本地辅助脚本和外部工具来使用它。实际评估 docx usage 时，通常应默认你可能需要：

• Python
• 用于读取和面向转换提取的 pandoc
• 用于 .doc 转换和接受修订的 LibreOffice soffice
• 能运行仓库内 Python 脚本的 shell 环境

如果你的环境对偏 GUI 的办公工具或原生 subprocess 调用有限制，最好先确认这一点。很多时候，这才是真正阻碍采用的地方。

先读这些文件，最快进入状态

如果想快速搞清楚这个技能怎么运作，建议按这个顺序读：

1. skills/docx/SKILL.md
2. skills/docx/scripts/office/unpack.py
3. skills/docx/scripts/office/pack.py
4. skills/docx/scripts/accept_changes.py
5. skills/docx/scripts/comment.py
6. skills/docx/scripts/office/soffice.py

这条阅读路径能直接揭示 docx skill 的实际运行模型：先读、再解包、编辑、校验、重新打包，并且只在 XML 方式不合适时才调用 LibreOffice。

按任务选择正确的工作流

一份靠谱的 docx guide，第一步不是直接开改，而是先选对路径：

• 读取或分析内容： 用 pandoc，或直接查看解包后的 XML
• 创建新文档： 走 SKILL.md 中提到的文档生成路径
• 编辑现有文档： unpack → 修改 XML/资源 → repack
• 把 .doc 转成 .docx： 先用 LibreOffice 做转换
• 接受修订： 使用仓库提供的 LibreOffice 宏辅助
• 添加批注： 用 comment 脚本，并正确写入对应 XML 标记

如果跳过这一步，直接进入编辑，质量通常会很快下滑。

想让 docx 输出稳定，需要提供哪些输入

想获得可靠的 docx usage 效果，给代理的信息不能只有“做个 Word 文档”。比较有效的输入通常包括：

• 如果是编辑任务，源文件路径是什么
• 期望输出文件路径是什么
• 任务属于 create、read、convert、annotate 还是 revise
• 格式要求，比如标题层级、页码、目录、表格、信头
• 是否必须保留 tracked changes 或 comments
• 文档里是否有图片、表格或模板，而且这些内容必须原样保留

一个弱提示词：

• “Edit this Word document.”

一个更强的提示词：

• “Open contract_review.docx, preserve tracked changes, summarize all comments, then create a new executive_summary.docx with H1/H2 headings, a short risks table, and a final recommendations section.”

用户真正关心的实用命令

仓库里直接体现了几类高价值操作：

先把老旧 .doc 转换掉，再做后续处理：

python scripts/office/soffice.py --headless --convert-to docx document.doc

提取文本，同时保留修订上下文：

pandoc --track-changes=all document.docx -o output.md

解包 DOCX，进入 XML 级编辑：

python scripts/office/unpack.py document.docx unpacked/

编辑完成后重新打包：

python scripts/office/pack.py unpacked/ output.docx --original document.docx

这些命令体现的正是 docx for DOCX Workflows 的真实价值：不只是“写文字”，而是能相对安全地操作 Word 包结构。

如何写提示词，才能正确触发 docx

当你的请求把文件类型和操作说清楚时，这个技能更容易被正确触发。最好明确写出：

• .docx
• 期望的最终结果
• 是基于现有文件修改，还是从零开始创建
• 哪些内容必须保留

比较好的触发示例：

• “Create a polished .docx board memo from these notes.”
• “Read this .docx and extract text including tracked changes.”
• “Unpack and update the title page, then repack the .docx.”
• “Add review comments to specific paragraphs in this Word document.”

如果你真正需要的是包级安全编辑，就不要只说“make a document better”这类模糊表达。

什么时候用 pandoc，什么时候直接改 XML

这是最关键、也最实际的判断之一。

当你要做的是以下事情时，用 pandoc：

• 可读性较好的文本提取
• 转成 markdown
• 更方便地审查 tracked changes
• 重点在内容分析，而不是布局层面的“手术”

当你需要这些能力时，用 unpack/edit/repack：

• 批注
• 感知修订状态的结构化编辑
• 替换图片或其他包内部件
• 对 word/ 下 XML 和 relationships 做底层修复

如果你的目标是语义层面的阅读理解，直接改 XML 往往过头了；但如果目标是精确修改 DOCX 文件本身，单纯文本提取又远远不够。

涉及修订和批注时，docx 的优势更明显

这个仓库在这方面提供了非常实用的支持：

• scripts/accept_changes.py 可借助 LibreOffice 接受修订
• scripts/comment.py 可帮助你向解包后的文档中插入批注
• scripts/office/helpers/ 下的辅助代码处理了 run 合并与 redline 简化

这很重要，因为一旦文档里有 revisions，原始 DOCX XML 会变得明显更复杂。如果你的文件涉及法务审阅、编辑批注或多轮谈判稿，docx skill 会比普通文档生成器更有吸引力。

docx 常见的 XML 质量陷阱要提前注意

有些失败模式非常容易被忽略：

• comment 标记必须正确插入 document.xml
• comment 文本需要做 XML 转义
• 对 DOCX 的修改可能破坏 relationships 或 schema 有效性
• run 片段化会让 search/replace 变得不可靠
• tracked changes 会扭曲你看到的“表面文本流”

仓库内置的 pack/validate 路径能降低风险，但并不意味着你可以不用认真界定任务。

可能阻碍采用的环境细节

在评估 docx install 时，一个现实障碍就是办公自动化环境。仓库中的 soffice.py 明确包含了对受限沙箱环境的处理逻辑，例如 Unix socket 可能失效、某些情况下可能需要 LD_PRELOAD shim。这说明作者默认预期：真实环境里确实会有不少摩擦。

如果你的部署环境不能运行 LibreOffice，部分工作流仍然可用，但会受到这些影响：

• .doc 转换会更困难
• 无法使用仓库提供的脚本来接受修订
• 某些“像自动化 Word 一样处理文件”的需求，可能必须换一套工具链

想要结果稳定，建议采用这套默认流程

一套比较稳妥的 docx guide 默认流程是：

1. 先确认源文件是 .doc 还是 .docx。
2. 如有需要，先把 .doc 转成 .docx。
3. 判断任务属于文本提取还是包级编辑。
4. 只有在确实需要结构级修改时才解包。
5. 做有针对性的修改，不要用大范围 regex 式 XML 重写。
6. 重新打包时尽量结合原文件做校验。
7. 最后在 Word 或 LibreOffice 中打开，做一次视觉层面的 smoke test。

这套流程能避免最常见的损坏和结果偏差问题。

docx 技能 FAQ

docx 适合新手吗？

适合，前提是你的需求明确且范围有限，比如转换、提取或做小改动。但更深入的 docx usage 很快就会进入包级 XML 处理。新手也能用好它，只要遵循清晰的工作流，不要把 Word 文件当成普通文本块来处理。

什么情况下 docx 比普通写作提示词更合适？

当输出必须是真正可用的 Word 文件，或者你必须保留现有 .docx 的结构时，就该用 docx。普通写作提示词可以帮你起草内容，但通常不会告诉代理该如何安全地转换、解包、校验，或处理批注与修订。

docx skill 能从零创建新文档吗？

可以，但从仓库现有内容来看，它最强的证据主要集中在实用的文件操作和编辑工作流上，而不只是生成文本本身。如果你的核心需求只是“写内容”，很多工具都能做到；但如果你的需求是“交付或编辑一个可正常使用的 .docx”，这个技能会更匹配。

docx 能处理旧版 .doc 文件吗？

可以间接处理。老旧 .doc 文件应先用 LibreOffice 转成 .docx。这是一个很关键的边界：docx skill 面向的是 .docx 工作流，而不是原生 .doc 编辑。

docx 适合法务或高审阅强度文档吗？

有可能适合，因为仓库本身就把 tracked changes、comments 和 validation 当作核心能力来处理。不过，这类高审阅强度文档在生成或修改后，仍然应该打开检查，确认它在 Word 兼容编辑器中的可见表现是否正确。

什么情况下不应该使用 docx？

如果满足以下任一条件，就建议跳过这个 docx skill：

• 你只需要纯文本输出
• 目标格式是 PDF，而不是 Word
• 工作流以 Google Docs 为主
• 你无法运行它依赖的本地工具
• 你更在意像素级桌面排版，而不是可编辑的 DOCX 结构

如何改进 docx 技能的使用效果

给 docx 明确的输出约束

想提升 docx 效果，最快的方法就是明确说明最终产物，而不是只给一个主题。最好包含：

• 目标文件名
• 源文件名
• 保留哪些内容、重写哪些内容
• 必须包含的章节
• 样式约束
• comments、revisions、images 或 tables 是否必须完整保留

这样能显著减少工具选择错误，也能避免代理默认走纯文本路径。

执行前先让代理说明将采用哪条工作流

要获得更好的 docx usage，可以先要求代理说清楚它打算走哪条路径：

• pandoc
• unpack/edit/repack
• LibreOffice conversion
• comment 或 revision tooling

例如：

• “Before editing, tell me whether this task should use pandoc extraction or unpack/repack, and why.”

这一步很简单，但能提前拦下很多走错路的情况。

做搜索替换时，最好补充结构位置信息

如果你要做替换，请明确内容所在位置：

• 正文
• headers/footers
• comments
• tables
• title page
• 指定章节标题下

原因很实际：DOCX 中的文本往往会被拆散到多个 run 里。如果只是模糊地说“把所有提及都替换掉”，很容易漏改，也可能破坏格式。

处理批注时，要特别注意 XML 转义

添加 comments 时，最好提供干净、XML-safe 的文本。仓库里明确提到，comment 文本应该先做转义。如果你的批注中包含 ampersand、智能引号或特殊符号，最好明确说明必须先转义或规范化。

这看似是小细节，但会直接影响最终文件能否正常打开。

能带原文件校验时，尽量带上

重新打包时，如果你手头有源文件，就尽量加上 --original。这样校验器能拿到更多上下文，也会让 docx skill 在编辑现有文档时更安全。这是整个工作流里性价比极高的习惯之一。

首次输出后，用“文件感知型反馈”继续迭代

不要只说“看起来不对”。更有效的后续反馈是：

• “The document opens, but comments do not appear in Word.”
• “Tracked changes were flattened; preserve them instead.”
• “The body text updated, but header branding stayed old.”
• “The XML packed, but formatting broke in the table section.”

这种反馈能帮助代理判断下一步该怎么修，而不是盲目重试。

这些常见失败模式要尽早排查

在把工作流放大到更大批量前，先检查这些问题：

• 文件能打开，但 comments 不显示
• tracked changes 被意外接受或丢失
• 修改只作用于可见正文，没有覆盖 headers/footers
• 智能引号或特殊符号破坏 XML
• 重新打包后的文件虽然能 zip 成功，但在 Word 中打不开

在小文档上先做一次快速 smoke test，通常比直接处理大批量更划算。

处理复杂 docx 文件时，怎样得到更稳的结果

对于复杂的 docx for DOCX Workflows 场景，建议把任务拆开：

1. 先提取并检查内容
2. 决定具体修改点
3. 每次只应用一种类型的修改
4. 重新打包并校验
5. 做可视化验证

这当然比一次性提示更慢，但面对模板、合同、报告以及修订很多的文档时，成功率会高得多。

如果你要扩展 docx skill，本身该优先改进什么

如果你评估的是如何改进这个 docx skill 本身，最有价值的增强方向会是：

• 为常见任务提供更清晰的 documented entrypoints
• 给每条工作流路径配上示例提示词
• 提供更紧凑明确的安装/前置条件清单
• 更明确地区分“创建新文档”和“编辑现有文档”的操作指引
• 为 comments、redlines 和 image replacement 提供端到端示例

相比继续增加泛泛的说明性文字，这些改进更能降低采用门槛。