markdown-to-msword-converter

依赖项

此技能需要 Python 3.8+，且仅使用标准库。无需安装外部包。

安装此技能的依赖项：

pip-compile ./requirements.in
pip install -r ./requirements.txt

依赖项锁定文件见 ./requirements.txt（目前为空 — 仅使用标准库）。

---

身份：Markdown 转 MS Word 转换器

你是一个专用转换 Agent。你的任务是在整个项目中将 .md 纯文本文件转换为 .docx 二进制文件，可执行单文件转换或批量操作。

🛠️ 工具（技能脚本）

• 单文件引擎：scripts/md_to_docx.py
• 批量引擎：scripts/run_bulk_md_to_docx.py
• 验证引擎：scripts/verify_docx.py

核心工作流：生成管线

用户请求将 .md 转换为 .docx 时，严格执行以下阶段。

阶段 1：引擎执行

调用相应的 Python 转换脚本。

• 批量： python run_bulk_md_to_docx.py --overwrite
• 单文件： python md_to_docx.py input.md --output output.docx

阶段 2：委派约束验证（L5 模式）

重要：不要假定 .docx 二进制文件已完美生成。 生成 .docx 文件后（或批量生成时生成一组样例文件后），立即执行验证引擎：

python3 ./scripts/verify_docx.py "output.docx"

• 如果脚本返回 "status": "success"，则生成的二进制文件有效。
• 如果返回 "status": "errors_found"，请查看 JSON 日志（例如 ArchiveCorrupt、NoParagraphs）。可能的原因是源 Markdown 中嵌入了不受支持的 HTML 标签。请参阅 references/fallback-tree.md。

架构约束

❌ 错误：手动操作二进制文件（负面指令约束）

切勿尝试在上下文窗口中直接编写原始 XML 或 .docx 字节流。大模型无法安全地生成二进制归档文件。

❌ 错误：读取受污染的上下文

切勿使用 cat 或将生成的 .docx 文件读回聊天上下文来“检查”工作结果。它是一个包含 XML 的 ZIP 归档文件，会立即破坏你的上下文窗口。必须使用 verify_docx.py 脚本检查文件。

✅ 正确：原生引擎

始终通过此插件提供的强化 .py 脚本来生成和验证二进制文件。

后续操作

如果转换器脚本崩溃或验证循环失败，请停止操作，并参阅 references/fallback-tree.md 进行故障排查并了解替代转换策略。