ocr-cli

输入一张图片或一份 PDF，通过 OpenAI Chat Completions 多模态协议识别文字，并将结果写到标准输出。 它不依赖任何企业平台，也不包含供应商 SDK。

安装

npm install -g @moziaverse/ocr-cli

使用

export OCR_CLI_BASE_URL="https://mzsjai.com/v1"
export OCR_CLI_API_KEY="..."
export OCR_CLI_MODEL="baidu/unlimited-ocr"

ocr-cli ./invoice.png
ocr-cli ./invoice.jpg --format json
ocr-cli ./invoice.pdf --format json
ocr-cli ./invoice.pdf --format json --verbose
ocr-cli ./invoice.pdf --model baidu/unlimited-ocr --format json
ocr-cli doctor
ocr-cli --version

也可以持久化配置，不再依赖 Shell 启动文件：

ocr-cli configure \
  --base-url http://192.168.92.225:8083 \
  --api-key unused \
  --model glm-ocr

# 查看配置；API Key 只显示是否已配置，不显示明文
ocr-cli configure

配置完成后可以一键检查实际生效的配置、服务连通性和模型：

ocr-cli doctor
ocr-cli doctor --format json

doctor 会显示 API Key、Base URL 和模型分别来自环境变量、配置文件还是内置默认值； 如果环境变量正在覆盖配置文件，也会明确警告。它只请求 OpenAI 兼容服务的 GET /v1/models，不会上传图片、执行真实 OCR 或显示 API Key。服务不支持模型列表接口时 返回警告而不是失败；缺少配置、认证失败、连接失败或模型列表明确不包含当前模型时返回失败， 进程退出码为 1。JSON 格式适合 Agent 和自动化脚本消费。

配置文件默认位于 Linux/macOS 的 ~/.config/ocr-cli/config.json 或 Windows 的 %APPDATA%\ocr-cli\config.json，也可以用 OCR_CLI_CONFIG 指定路径。配置优先级为： 命令行参数、环境变量、配置文件、内置默认值。API Key 会以明文保存在仅当前用户可访问的 配置文件中，不应在共享账号或共享设备上使用该方式。

OCR_CLI_BASE_URL 可以是 HTTP 或 HTTPS API 基础地址，也可以是完整的 https://example.com/v1/chat/completions。HTTP 适合本机或受信任内网；它不会加密 API Key 和文档内容，跨不可信网络时应使用 HTTPS。默认输出纯文本；--format json 返回文件名、 类型、模型和文字。PDF 会按页顺序识别；纯文本使用页码标题分隔，JSON 额外返回 pageCount 和 pages，图片 JSON 格式保持不变。--model 只覆盖本次调用使用的模型， 优先级为命令行参数、OCR_CLI_MODEL、内置默认值。

当 Base URL 只有主机和端口时，CLI 会自动补全 /v1/chat/completions；/V1 等大小写错误 也会自动纠正为小写 /v1。如果配置了 /api 等自定义路径，CLI 会保留该路径，只补充 /chat/completions。

CLI 支持 PNG、JPEG、WebP 和 PDF，按文件内容识别类型，单文件最大 20 MiB，PDF 最多 20 页。PDF 使用内置 MuPDF WASM 在本地以 200 DPI 逐页渲染，包含表单字段，再顺序 请求 OCR；Windows、macOS 和 Linux 使用同一实现，不依赖 Python、PyMuPDF、Poppler、 ImageMagick 等外部运行时或命令。加密、损坏或超出安全上限的 PDF 会 在联网前失败。正常 OCR 调用的 API Key 从 OCR_CLI_API_KEY 环境变量或持久化配置读取； 文件识别命令不接受 --api-key，避免密钥进入 Shell 历史。CLI 不读取 OPENAI_API_KEY、OPENAI_BASE_URL 等 Agent 模型变量，OCR 与 Agent 可以使用完全独立的 服务地址、密钥和模型。

--verbose 会把 PDF 当前页和总页数写入标准错误，例如 PDF 第 3/10 页；标准输出仍然只 包含 OCR 文本或 JSON，适合继续通过管道和程序消费。

ocr-cli 的边界保持为“文件输入、OCR 文本输出”。发票号、税号、日期、金额等字段化抽取 依赖具体业务规则，应由 Agent 或 Skill 在 OCR 结果之上完成，不在 CLI 中内置 --schema invoice。

CLI 每 24 小时最多检查一次 npm 最新版本，发现新版本时在标准错误中显示更新命令， 不会污染纯文本或 JSON 标准输出。离线环境或自动化任务可以设置 NO_UPDATE_NOTIFIER=1 关闭检查。

如果服务返回 404，错误会包含实际请求 URL。请重点检查 OCR_CLI_BASE_URL 中的路径大小写； 例如服务只提供小写 /v1/chat/completions 时，配置成大写 /V1 会直接返回 404。

需要 Node.js 20.19+、22.13+ 或 24+。

许可证

本项目使用 GNU Affero General Public License v3.0 or later（AGPL-3.0-or-later）。 PDF 渲染由同许可证模型下的官方 MuPDF.js 提供。

开发

npm install
npm test
npm run typecheck

生成 npm 包：

npm pack