docx-convert

用途

docx-convert 用于在 Microsoft Word（.docx）与 Markdown 之间进行双向转换。它通过一个统一入口脚本 scripts/convert.cjs 提供两个转换方向，适合需要把 Word 文档转为 Markdown 以便版本管理或发布，或把 Markdown 转为可编辑 Word 文档的场景。

主要能力

DOCX → Markdown（--to markdown）

GFM 表格：Word 表格转换为 Markdown 表格
图片：内嵌图片可提取为 base64 内联，或写入指定文件夹
列表：保留有序与无序列表
代码块：等宽文本转换为代码块
链接与标题：保留超链接与标题层级

Markdown → DOCX（--to docx）

GFM 支持：表格、删除线、任务列表
代码块：以等宽字体保留语法
图片：嵌入本地与 URL 图片
数学公式：默认渲染 LaTeX 公式（$...$、$$...$$）
Frontmatter：YAML 元数据提供文档标题
无系统依赖：纯 JavaScript，无需 Chrome

两个方向均可在 Windows、macOS 和 Linux 上运行。

使用方式

安装

每个方向需单独安装依赖，只安装所需方向：

# DOCX -> Markdown
cd .claude/skills/docx-convert/to-markdown
npm install

# Markdown -> DOCX
cd .claude/skills/docx-convert/to-docx
npm install

ck init（运行 install.sh）可一次性处理所有技能。

快速开始

# DOCX -> Markdown
node .claude/skills/docx-convert/scripts/convert.cjs --to markdown --input ./document.docx

# DOCX -> Markdown，将图片提取到文件夹而非内联 base64
node .claude/skills/docx-convert/scripts/convert.cjs --to markdown -i ./doc.docx --images ./images/

# Markdown -> DOCX
node .claude/skills/docx-convert/scripts/convert.cjs --to docx --input ./README.md

# Markdown -> DOCX，使用自定义主题
node .claude/skills/docx-convert/scripts/convert.cjs --to docx -i ./doc.md --theme ./theme.json

--to=markdown 与 --to markdown 等价。缺失或未知的 --to 会打印有效方向并以退出码 1 结束。

CLI 选项

调度器：

--to：转换方向，markdown 或 docx（必填）

--to markdown（DOCX → Markdown）：

--input / -i：输入 DOCX 文件路径（必填）
--output / -o：输出 Markdown 文件路径，默认 {input}.md
--images：提取图片的目录，默认内联 base64
--help / -h：显示帮助

--to docx（Markdown → DOCX）：

--input / -i：输入 Markdown 文件（必填）
--output / -o：输出 DOCX 路径，默认 {input}.docx
--theme / -t：自定义主题 JSON，默认内置
--title：文档标题，默认文件名
--help / -h：显示帮助

运行 scripts/convert.cjs --to <direction> --help 可查看某方向的完整帮助。

转换流程（--to markdown）

DOCX → mammoth → HTML → turndown → Markdown。该两阶段转换遵循 mammoth 官方推荐以获得最佳效果。

输出

两个方向成功时均返回 JSON：

{
    "success": true,
    "input": "/path/to/input.docx",
    "output": "/path/to/output.md",
    "stats": {
        "images": 3,
        "tables": 2,
        "headings": 5
    }
}

--to docx 不包含 stats。失败时两者均返回 { "success": false, "error": "..." } 并以退出码 1 结束。

兼容性（--to docx）

生成的 DOCX 文件可在 Microsoft Word（2007+）、Google Docs、LibreOffice Writer 和 Apple Pages 中打开。

限制

复杂布局（分栏、文本框）可能无法保留结构
合并的表格单元格会生成基础 Markdown 表格
批注和修订会被剥离
部分格式（字体、颜色）在转换中丢失

故障排查

缺少依赖时，错误输出会附带针对所调用方向的确切 cd … && npm install 命令提示。

测试

cd .claude/skills/docx-convert && node tests/dispatcher.test.cjs   # 路由与 --to 校验
cd .claude/skills/docx-convert/to-markdown && node tests/run-tests.cjs
cd .claude/skills/docx-convert/to-docx && node tests/run-tests.cjs