zerox

Zerox 是一款基于 Node.js 的文档转换工具技能，核心功能是利用 GPT-4o 的视觉识别能力，将 PDF、Word、PPTX 及各类图片转换为结构化的 Markdown 文本。该技能提供了前台快速转换和后台异步处理两种模式，前者适合 30 秒内可完成的小文件，后者通过 convert-bg.mjs 脚本实现大文件或扫描 PDF 的后台处理，避免终端阻塞并支持 macOS 通知提醒。

该技能的显著优点在于其强大的 OCR 能力和广泛的格式兼容性。依托 zerox 库和 GPT-4o vision，即使是扫描版 PDF 或图片中的文字也能被准确提取，且能较好保留文档的版面结构和格式。后台处理模式对大型文档友好，通过日志监控和进程脱离设计，确保长时间转换任务的稳定性。输出为标准 Markdown，便于后续的内容编辑、知识库构建或 AI 训练数据处理。

然而，该技能也存在一定局限性。首先，转换过程依赖外部 OpenAI 兼容 API（通过 API易中转），需要稳定的网络连接和 API 费用支出，且文件内容需上传至第三方服务器处理，存在隐私泄露风险。其次，作为 T3 来源（个人/社区维护）的代码型资产，虽代码本身规范，但长期维护和支持存在不确定性。此外，输入路径验证不够严格，存在潜在的路径遍历风险，尽管目前未构成实际漏洞。

该技能适合需要批量处理文档数字化的内容创作者、学术研究人员、开发者以及办公自动化场景。尤其适合处理扫描版论文、合同、书籍等需要 OCR 识别的场景，或需要将 legacy 文档转换为现代 Markdown 格式进行知识管理的用户。

使用风险主要包括：API 密钥管理不当可能导致密钥泄露；敏感文件上传至远程 API 存在数据隐私风险；缺少严格路径验证可能带来的文件系统安全风险；以及大文件转换可能产生较高的 API 调用费用。建议仅在处理非敏感文档时使用，并妥善保管 API Key。

核心用法

Zerox 是一款基于开源项目 getomni-ai/zerox 的文档转换工具，利用 GPT-4o 视觉模型将多种格式文档转换为 Markdown 文本。支持 PDF（含扫描件）、DOCX、PPTX、PNG、JPG 等格式。

两种运行模式：

• 前台模式 (convert.mjs): 适合小文件，直接执行，默认输出至 {baseDir}/output/document.md
• 后台模式 (convert-bg.mjs): 适合大型扫描文档，后台运行无超时，带进度日志和完成通知

使用示例：

# 基础转换
node {baseDir}/scripts/convert.mjs "/path/to/document.pdf"

# 后台处理大文件
node {baseDir}/scripts/convert-bg.mjs "/path/to/scanned-document.pdf"
tail -f {baseDir}/output/convert-bg.log  # 监控进度

显著优点

1. 扫描件识别能力强: 基于 GPT-4o vision，对扫描 PDF 和图片的 OCR 效果优于传统工具
2. 格式保留完整: 转换为 Markdown 时保留文档结构和层次
3. 使用便捷: 命令行直接调用，无需复杂配置
4. 后台容错: 大文件后台处理避免终端超时
5. 来源可信: 基于 GitHub 知名组织维护的开源项目，社区活跃

潜在缺点与局限性

1. 依赖外部 API: 文档内容需上传至 api.apiyi.com 处理，存在数据隐私顾虑
2. 成本敏感: 基于 GPT-4o 按量计费，大文档或批量处理成本较高
3. 网络依赖: 必须联网使用，无离线模式
4. 纯文本输出: 仅输出 Markdown，不保留原始排版样式
5. API 中转商风险: 使用 API易 作为中转服务，稳定性与数据安全依赖第三方

适合人群

• 需要将扫描文档、图片中的文字提取为可编辑 Markdown 的用户
• 处理混合内容 PDF（图文并存）的知识工作者
• 愿意用 API 成本换取高准确度 OCR 的场景
• 不适合: 处理含敏感/机密信息的文档，或需要完全离线环境的用户

常规风险

• 数据外泄: 文档内容离开本地至第三方服务器，需避免处理敏感信息
• 子进程安全: 后台模式使用 child_process.spawn，虽无命令注入但仍需注意路径校验
• 凭证管理: API Key 存储于环境变量或 ~/.openclaw/.env，需确保文件权限安全