---
name: md-to-docx
description: 将 Markdown 文档转换为 Word .docx，保留常见标题、段落、列表、表格、代码块、链接和本地图片。适用于需要可编辑 Word 版本的 Markdown；修订留痕、复杂排版复刻或旧版 .doc 不应触发本 Skill。
---

# Markdown 转 Word

使用 `scripts/convert.py` 生成可编辑的 `.docx`。转换以语义结构清晰为目标，不承诺像素级复刻 Markdown 渲染结果。

## 执行边界

- 只接受存在的 `.md` 或 `.markdown` 文件。
- 默认在输入文件旁生成同名 `.docx`；文件已存在时停止，只有用户明确同意覆盖后才传入 `--force`。
- 用户提供 `.docx` 模板时可传入 `--template`，转换器沿用模板样式并在文档末尾追加内容，不替换模板中的占位符。
- 转换依赖 Python 包 `python-docx`。优先使用 Codex 工作区依赖运行时；环境缺失时停止并给出提示，不自动安装依赖。
- 不自动下载图片或字体；远程图片保留为文字提示，本地缺失图片产生警告。
- 不伪造修订记录、批注或目录。需要人工审阅留痕时应使用独立的文档修订流程。

## 转换流程

1. 确认输入、输出位置和是否使用模板。
2. 使用工作区依赖运行时执行：

   ```text
   python scripts/convert.py <input.md> [--output <file.docx>] [--template <template.docx>] [--force]
   ```

3. 重新打开生成文件，检查标题、列表、表格和图片统计。
4. 如当前环境具备 DOCX 渲染能力，渲染页面并目视检查；否则明确说明只完成了结构校验。
5. 报告输出路径、转换统计和降级内容。

## 支持范围

转换器支持 ATX 标题、普通段落、粗体、斜体、行内代码、链接、图片、引用、围栏代码块、水平线、无序列表、有序列表和基础 Markdown 表格。

嵌套混合列表、原始 HTML、脚注、公式、任务列表、复杂表格合并和主题级样式可能降级。输入依赖特定 Markdown 扩展时，应先说明差异，不得声称无损转换。