企业官网建设流程全解析

kordoc批量转换提速指南：--jobs并行 + parse-worker长驻进程，实测2.8倍加速

【免费下载链接】kordoc모두 파싱해버리겠다 — HWP·HWPX·PDF·Office 문서를 Markdown으로. 양식 자동 채우기와 신구대조를 갖춘 CLI·MCP 서버 | Convert Korean documents (HWP, HWPX, PDF, Office) to Markdown — CLI and MCP server with form filling and diff项目地址: https://gitcode.com/gh_mirrors/ko/kordoc

kordoc是一款把 HWP、HWPX、PDF、Office 等韩文文档批量转换为 Markdown 的开源工具，自带 CLI 与 MCP 服务器，支持表单自动填写和文本质检。当你要一次性转换几十份甚至上百份文档时，逐个串行跑会非常耗时。本文介绍两种官方提速方案：--jobs文件级并行转换与parse-worker长驻解析进程，并附上实测加速数据，帮你把批量转换速度提升近 3 倍。

为什么批量转换需要提速 💡

kordoc 的默认行为是逐个文件串行转换——解析、排版、提取图片都在同一个进程里排队执行。文档解析是典型的 CPU 密集型任务，单线程跑完 100 份 HWPX，每份 10 秒就要等 17 分钟。

两种提速思路：

一键开启 --jobs 并行转换

最快上手：一条命令

并行转换只需在批量命令后加--jobs参数和输出目录-d：

npx kordoc *.pdf --jobs 4 -d ./转换结果/

这条命令会拉起 4 个常驻 Node.js 进程，每个进程独立持有自己的解析器和 OCR 初始化状态，文件"来一个转一个、转完领下一个"，父进程不缓存任何文档内容，内存开销可控。相关实现在 src/cli/batch.ts，完整说明见官方文档 docs/parallel-batch.md。

内置的并行安全保护 🛡️

kordoc 对并行模式做了多重防坑设计，新手可以放心使用：

• 文件名冲突预检：多个输入文件的去扩展名主名（不区分大小写）必须互不相同，冲突会在转换开始前直接拒绝，避免输出文件互相覆盖。
• 部分失败不中断：某个文件转换失败时，其余任务照常跑完，最终退出码标记为失败，失败详情以 JSON 输出。
• 信号安全清理：Ctrl+C（SIGINT）或 SIGTERM 会关闭所有工作进程，实测零残留进程。

这些行为均有集成测试覆盖，见 tests/cli-batch.test.ts。

实测数据：4 进程 2.8 倍加速 📈

官方基准测试（bench/batch.mjs，Intel i7-10700 8 核，Linux）用 24 份约 1.2 万段的 HWPX 和 24 份 40 页 PDF 各跑了 3 轮取中位数：

后续在 v4.17.x 上的独立复测中，HWPX 在 8 进程下进一步达到3.23×；而输出 SHA-256 哈希与串行结果逐字节一致——提速不牺牲转换质量。

parse-worker：程序化调用的长驻进程

如果你的场景不是"命令行跑一批"，而是"应用里持续喂文件"，kordoc parse-worker是更优解：进程常驻，通过 stdin 每收一行 NDJSON 请求就回一行 JSON 结果，彻底省掉了每个文件都启动一次 node 的开销。协议源码见 src/cli/commands-worker.ts。

kordoc parse-worker

交互协议极简（协议版本 1）：

启动 {"ready":true,"version":"4.18.8","protocol":1} 请求 {"id":1,"file":"문서.hwpx","images":false,"ocr":"off"} 响应 {"id":1,"rss":183500800,"result":{...}} 退出 {"cmd":"quit"}

两个实用细节：

• 请求支持ocr（"off"/"auto"/"force"）、formulaOcr、password等字段，能力与 CLI 对齐；
• 每次响应附带rss（进程内存），你的宿主程序可据此决定何时重启 worker 防止内存膨胀。

选对进程数：不是越多越好 ⚖️

实测数据揭示了几个关键规律，选型前请阅读 docs/usage.md 的 CLI 章节：

1. 默认仍是--jobs 1：官方基准显示，24 份几 KB 的小文件，4 进程反而比串行慢（0.375 s vs 0.222 s）——worker 启动开销压过了解析本身。小文件请保持串行。
2. 内存随进程数线性增长：4 进程 HWPX 批次峰值约 1.4 GiB，8 进程升至 1.75 GiB。
3. OCR 工作负载注意超订：内置 OCR 本身使用原生多线程，进程数超过物理核心数可能相互抢 CPU。
4. 经验法则：核心文档批量任务从--jobs 4起步，用官方脚本实测后再调：

npm run build BATCH_JOBS=1,2,4 BATCH_REPS=3 node bench/batch.mjs # 或换成你自己的文件： node bench/batch.mjs /path/to/documents/*.hwp

写在最后

kordoc 用两个轻量特性解决了文档批处理的提速问题：--jobs让你一条命令获得近 3 倍的吞吐提升，parse-worker则为程序化集成消除了进程启动税。两者都不改变转换结果——所有基准中并行与串行的输出哈希完全一致。文档批量转换提速，从加一个--jobs 4开始就好。

【免费下载链接】kordoc모두 파싱해버리겠다 — HWP·HWPX·PDF·Office 문서를 Markdown으로. 양식 자동 채우기와 신구대조를 갖춘 CLI·MCP 서버 | Convert Korean documents (HWP, HWPX, PDF, Office) to Markdown — CLI and MCP server with form filling and diff项目地址: https://gitcode.com/gh_mirrors/ko/kordoc