convert-word-to-md

将 Word 转换为 Markdown

何时使用此技能

只要遇到需要理解或处理的 .docx 文件，就触发此技能 —— 例如，用户附上一个 Word 文档并针对它提问、想要摘要、想要提取特定数据，或者想要处理某个文件夹中的多个 Word 文档。Word 原生的 .docx 格式是一个压缩的 XML 包，无法可靠地作为纯文本读取，因此请始终先使用此技能中的脚本将其转换为 Markdown，而不是尝试直接打开或解析该文件。

此技能仅支持 .docx。如果被要求转换旧版 .doc 文件，请告知用户不支持，并请他们先将其另存为 .docx（Word：文件 > 另存为 > Word 文档 (.docx)）。

混合文件类型： 当用户引用包含多种受支持文件类型（.pdf、.docx、.xlsx）的文件夹或一组文档时，此技能只处理 .docx 文件。Agent 还必须并行调用同级的技能：

• convert-pdf-to-md 用于处理任何 .pdf 文件
• convert-excel-to-md 用于处理任何 .xlsx 文件

切勿在处理文件夹时静默跳过某种受支持的文件类型。当存在混合类型时，必须同时调用这三个技能。

环境准备（每个环境一次）

在给定环境中进行首次转换之前，请逐步遵循 references/setup.md，确保已安装 Python、pip 和 markitdown 包。请主动执行此操作，而不是猜测环境是否就绪 —— 如果 markitdown 缺失，脚本本身也会失败并给出明确指引，指向该文件，因此如果你相当确信环境准备已完成，也可以先直接尝试转换。

用法

转换脚本位于 scripts/convert_word_to_md.py。

输出结构： MarkItDown 会将图像嵌入为截断的 data:image/png;base64... URI 占位符（并非真实的图像数据），因此脚本 会直接从 .docx 中提取真实图像，并为每个文档写出一个自包含的 文件夹，而不是一个单独的松散 .md 文件：

<name>/
    img/
        img001.<ext>
        img002.<ext>
        ...
    <name>.md          (image references are relative: img/imgNNN.ext)

如果文档没有嵌入图像，则不会创建 img/ 文件夹。

单个文件：

# Windows
python scripts\convert_word_to_md.py "C:\path\to\document.docx"

# macOS / Linux
python scripts/convert_word_to_md.py "/path/to/document.docx"

这会在源文件旁边创建一个 document\ 文件夹（包含 document.md，以及如果存在的话，document\img\）。要显式控制目标 文件夹：

python scripts\convert_word_to_md.py "C:\path\to\document.docx" -o "C:\path\to\output_folder"

一个包含 Word 文档的文件夹（批处理模式）：

python scripts\convert_word_to_md.py "C:\path\to\folder"

添加 --recursive 以同时包含子文件夹：

python scripts\convert_word_to_md.py "C:\path\to\folder" --recursive

默认情况下，找到的每个 .docx 都会在其旁边获得自己的 <name>\ 输出 文件夹。传入 -o "C:\path\to\output_parent" 可将所有生成的 <name>\ 文件夹收集到一个单独的父目录下（与 --recursive 结合使用时 会保留子文件夹结构）。

转换后，读取生成的 .md 文件以执行用户所要求的实际 分析 —— 脚本的职责只是生成准确的 Markdown（和图像），而不是解读内容。

决定输出去向

默认 —— 始终输出到源文件旁边。 <name>/ 文件夹 创建在源 .docx 所在的同一目录中。这是每种情况都必需的 默认行为。除非用户明确要求 其他位置，否则不要覆盖它。

仅在用户明确提供输出路径时（例如， “将输出保存到 C:\output”、“把结果放到 D:\work”）才使用 -o。不要 基于 Agent 的当前工作目录、会话状态 文件夹或任何暗示的位置传入 -o。

如果源文件路径无法完全解析 —— 例如， 用户只提供了文件名而没有目录，或路径有歧义 —— 请在运行转换前使用 ask_user 确认完整的绝对路径。切勿猜测或假定 目录。

疑难解答

现象	可能原因	修复方法
ModuleNotFoundError: No module named 'markitdown' / 退出码 2	未安装 MarkItDown	按照 references/setup.md 操作
ERROR: Unsupported file type '.doc' / 退出码 3	是旧版 .doc，不是 .docx	请用户重新保存为 .docx
ERROR: Input path not found / 退出码 3	路径错误，或文件已被移动	与用户确认正确的路径
批量输出中出现 FAILED <file> -> ...	该特定文件已损坏、受密码保护或无法读取	报告哪些文件失败；批量中的其他文件仍会成功
NOTE: skipped N non-.docx file(s)	文件夹中包含非 Word 文件	属于预期行为——这些文件会被有意忽略
WARNING: found N image placeholder(s) ... but extracted M image file(s)	MarkItDown 的占位符数量与 word/media/ 中找到的图片数量不一致（异常/格式错误的 docx）	宁可保留占位符不替换，也不冒险使用错误图片；如需图片，请手动检查源文件的媒体内容