DocTools · 文档批量处理

把一批中文文档拖进去，选一个操作，逐个文件给结果和产出路径 —— 规范化标点引号单位、 格式互转、按标题拆分、多份合并。原生 macOS app，全部在你自己的机器上跑，文件不出本机。 本页下半部分是它的只读那一半：把 .docx 拖进浏览器，当场出结构树、统计和终稿体检报告 —— 同样不上传，解析在你这个标签页里完成。

MIT 开源 macOS 15+ · Apple Silicon SwiftUI + Python 零上传 · 零账号

它替你解决什么

做中文正式文档的人，手上很少只有一个文件。一份报告常常是：十几篇 Markdown 草稿、 几个别人发来的 .doc、一叠导出的 Excel、还有几份 PPT。要交出去之前， 这堆东西得先被摆平三件事：

DocTools 把这三件事收进同一个窗口：拖一批文件进来 → 左边选操作 → 回车跑。 每个文件单独一行结果，成功的给产出路径，可以直接在 Finder 里定位；失败的告诉你为什么跳过， 不会因为其中一个文件不对就整批停住。

能做什么

下面 9 个操作是 app 启动时从后端读取并渲染成侧栏的全部内容 —— 不多不少。

格式转换矩阵

只有下表这些组合有对应引擎。选了没有引擎的组合，它会明确告诉你“这条转换没引擎，跳过”， 而不是产出一个坏文件。

“规范化”可以调到多细

规范化不是一个黑盒开关。它把“修哪些内容”和“改哪些范围”拆成两组独立选项， 由后端声明、前端渲染 —— 也就是说加旋钮只改后端脚本，不用重新编译 app。

在浏览器里真跑一遍 · 终稿体检

下面这个工具不是示意图：把 .docx 拖进来，浏览器会当场把它当成 ZIP 拆开 —— 用原生的 DecompressionStream('deflate-raw') 解压，配一个手写的 ZIP 中央目录读取器定位条目，取出 word/document.xml 与 word/styles.xml， 再用 DOMParser 解析出段落、样式、标题层级和表格。没有引任何第三方库， 也没有任何网络请求。.md / .txt 走纯文本路径，同样跑完整体检。

它查哪几件事

另一个演示：先看清它会怎么改字

这个小演示把“规范化”里的纯文本规则（引号 / 标点 / 单位）用 JavaScript 照着后端那份实现重写了一遍，直接跑在你这个浏览器标签页里。改动会高亮出来。 它只是让你在下载前先看清改字的分寸 —— 真正批量改写 docx / pptx 的，是你机器上的那个 app。

怎么用

装

• 系统要求：macOS 15 以上，Apple Silicon。
• 需要 uv（Python 运行器）：brew install uv。
• 从 Releases 下载 zip，解压，把 DocTools.app 拖进“应用程序”。
• 它是自签名的（没有付费的苹果开发者证书），所以下载后系统会隔离它。执行一次就好：

xattr -cr "/Applications/DocTools.app"

也可以右键点 app → 打开，然后在「系统设置 → 隐私与安全性」里放行。 或者装了 Xcode 的话直接从源码构建：./build.sh --install。

用 app

1. 把文件（或一整批混着不同格式的文件）拖进窗口。
2. 左侧侧栏选操作；“格式转换”这类还要在上方选目标格式。
3. 按 ⌘R 跑。⌘K 是命令面板，直接搜操作名跳过去。
4. 右侧逐文件出结果，点产出路径在 Finder 里定位。

用命令行

后端本身就是个可以单独调用的命令行程序，返回 JSON —— 这意味着你可以把它接进自己的脚本、 Makefile 或定时任务里，不必开 GUI。在仓库根目录：

# 看有哪些操作、每个操作支持哪些格式和选项
python3 backend/doc_gui_backend.py gui-ops

# 批量规范化，但这次不动单位、不动标点，只修引号
python3 backend/doc_gui_backend.py gui-run --op clean \
        --opt rule.units=0 --opt rule.punct=0 --files 甲.docx 乙.docx

# 只对正文和表格生效，跳过批注与修订
python3 backend/doc_gui_backend.py gui-run --op clean \
        --opt scope.comments=0 --opt scope.revision=0 --files 报告.docx

# Markdown 批量转 Word（套模板 + 自动文本修复）
python3 backend/doc_gui_backend.py gui-run --op convert --to word --files 第一章.md 第二章.md

还有一层更朴素的调度器接口，直接打动词，人看的彩色日志而非 JSON：

python3 backend/doc_dispatch.py convert --to md 汇报材料.pptx
python3 backend/doc_dispatch.py split  长文.md
python3 backend/doc_dispatch.py merge  01.md 02.md 03.md
python3 backend/doc_dispatch.py clean  草稿.md
python3 backend/doc_dispatch.py view   说明.md

技术上怎么做的

一壳两层。SwiftUI 那一层只做界面：侧栏、拖放区、文件列表、结果卡、命令面板。 它不解析任何文档格式，也不写业务逻辑 —— 所有真正的活都交给本机的一个 Python 进程， 双方靠一份 JSON 信封契约通信：前端启动时问一次“有哪些操作”，界面完全由这份回答渲染出来； 执行时把操作名、目标格式、选项和文件列表递过去，拿回逐文件的成败与产出路径。 结果就是：加一个新操作、给某个操作加一组选项，改的是 Python 脚本， app 不用重新编译。

后端本身是纯路由。docx 的 XML 改写、pptx 的母版遍历、xlsx 的 sheet 拆分、 Markdown 的标题解析各自是独立引擎，调度器只负责按文件后缀把活分给谁 —— 所以一个引擎出问题， 炸的是那一个文件那一行，不会掀翻整批。同理，批量执行时每个文件的输出被单独捕获， 互不干扰地汇总成一张结果表。

几个不显眼但决定成败的细节：写文件前先给原件留副本或走 _fixed 旁路， 默认不覆盖你的输入；Word 文本修复直接操作文档 XML 的文字片段， 因此能覆盖正文之外的表格、批注、修订、脚注、页眉页脚；单位替换和半角转全角都带边界守卫 （见上面那个演示）；GUI 程序看不到你 shell 里的 PATH， 所以它会去几个标准位置找 uv，找不到时直接说“找不到 uv”而不是静默失败。

本页那个体检器是怎么读 docx 的

为什么批量那一半没有在线版

这是最常被问的一句，所以直说。上面那个体检器是只读的 —— 读进来、看一眼、给一份报告， 不改你的文件，所以放在浏览器里没有代价。批量改写是另一回事。

整批改写搬到网页上会退化。网页版能给的流程只有“上传 → 处理 → 下载”。 一次处理三五个文件还行；几十个文件时，你要先把它们传上去，等，再把产物一个个下回来， 然后自己在下载文件夹里跟原始目录做对照 —— 这比在本机上拖进去、就地产出、 点一下在 Finder 里看要难用得多，不是好一点点的差距。

而且那意味着把没公开的稿子交给一台服务器。需要批量规范化的文档， 通常正是还没定稿、还不能外传的那一批。为了省一次安装，把它们上传到别人的机器上， 这笔账不划算。本机运行则根本不存在这个问题：没有账号，没有上传，没有服务端日志。

下载 / 源码