DOCX 批量转 Markdown

这个项目提供一个 Python CLI，用于把当前目录下的 .docx 文件批量转换为 Markdown，并输出 OpenAI、Anthropic、Gemini、DeepSeek 四个平台的 token 统计报告。

安装与运行

uv sync
uv run word-transfer

默认运行时会读取 input 目录中的 .docx 文件，并把 .md 文件和 token_report.json 写入 output。

常用参数：

uv run word-transfer --input-dir test_input --output-dir test_output
uv run word-transfer --input-dir test_input --output-dir test_output --recursive
uv run word-transfer --input-dir test_input --output-dir test_output --merge --merge-name combined.md
uv run word-transfer --recursive --merge --merge-name combined.md

转换规则

• 仅支持 .docx，非 .docx 文件会被跳过。
• 空文件或损坏的 .docx 会被跳过，错误原因会写入 token_report.json 的 errors 字段。
• Word 标题 1-4 分别转换为 Markdown #、##、###、####。
• Word 标题 5 及更深层级转换为单独一行加粗文字，例如 **五级标题**。
• 加粗、斜体、加粗斜体、删除线分别转换为 **text**、*text*、***text***、~~text~~。
• 字体、字号、颜色、下划线等 Markdown 无法稳定表达的样式会被忽略。
• 无序列表转换为 - item，有序列表转换为 1. item。
• 嵌套列表每层使用两个空格缩进。
• 假设源 Word 中没有图片；如果出现图片，脚本不会输出图片内容。

递归模式

默认只处理 input 目录第一层的 .docx 文件，不会进入子目录。

开启 --recursive 后，脚本会递归查找 input-dir 下所有子目录中的 .docx 文件。

• 非 merge 模式会在 output-dir 下创建相同的相对目录结构。
• 不包含 .docx 文件的目录不会在 output-dir 中创建。
• 例如 input/chapter/a.docx 会输出为 output/chapter/a.md。

Merge 模式

开启 --merge 后，所有 .docx 会按文件名排序后合并到一个 Markdown 文件中。

• 默认输出文件名是 merged.md，可用 --merge-name 修改。
• 每个源文件会先输出一级标题 # 文件名.docx。
• 与 --recursive 一起使用时，一级标题会包含相对路径，例如 # chapter/a.docx。
• 文件内原有标题整体顺延一级：原一级标题变为二级标题，原四级标题顺延后超过 Markdown 四级上限，因此会转为加粗文字。
• merge 模式下 token 报告只统计最终合并后的 Markdown 总 token。

Token 统计说明

脚本会在输出目录生成 token_report.json。

• OpenAI：使用 tiktoken 的 o200k_base 本地统计，模型标签为 gpt-5.5。参考 OpenAI latest model 与 tiktoken 文档。
• DeepSeek：使用 DeepSeek 官方 token usage 页面提供的 V3 离线 tokenizer 资源，并通过 tokenizers 本地统计，模型标签为 deepseek-chat。
• Anthropic：按要求使用离线近似，不调用官方 count_tokens API；报告中 estimated 为 true。
• Gemini：按要求使用离线近似，不调用官方 count_tokens API；报告中 estimated 为 true。

Anthropic 和 Gemini 的官方精确统计通常需要调用平台 API；本项目初版为了满足离线运行，明确将它们标记为估算值。

测试

uv run pytest

测试读取 test_input 中的样例 .docx，输出到被 git 忽略的 test_output。