用途
light-ocr 用于在本地对图像和 PDF 进行离线 OCR 文字识别。它面向 Node.js 与 C++ 项目，可直接识别 PDF、JPEG、PNG 或原始图像数据中的文字，结果按阅读顺序返回文本行，并附置信度分数和四边形坐标。所有处理都在本机完成，图像、PDF 和 OCR 结果不离开用户设备。
主要能力
- 基于 PP-OCRv6，npm 包内置 PP-OCRv6 Small 模型、PDFium、中文回退字体以及 macOS、Linux、Windows 预编译组件。
- 支持 Core ML / WebGPU 硬件加速；默认 createEngine() 使用 Auto 模式，在 macOS 15+ Apple Silicon 上优先尝试 Core ML，在 Linux 和 Windows 构建上优先尝试 WebGPU。
- 应用可通过 execution 选项显式选择 auto、cpu、apple 或 webgpu。
- recognize() 除图像文件外，也接受 GRAY8、RGB8、BGR8、RGBA8 像素数据。
- PDF 与多页文档 OCR 内置于包中，匹配的 PDFium 二进制与校验和固定的 Noto Sans SC 回退字体随平台 npm 包一起提供，无需 postinstall 脚本、运行时下载、编译器、系统字体或单独安装。
- 识别在 JavaScript 主线程之外运行，支持队列、取消和显式清理；可选分块模式可保留高分辨率图像中的小字和密集文字。
- 输出使用带版本的 schemaVersion: 1 契约；EXIF 方向自动校正。
使用方式
支持 Node.js 22 或更新版本，22 和 24 LTS 为 Tier 1（完整测试）；稳定的 Node-API ABI 允许较新的 Node 版本加载同一预编译二进制而无需发布新库。CommonJS 通过 require("@arcships/light-ocr") 使用相同导出。安装后可用 light-ocr 命令，无需额外设置。 图像命令包括 recognize（默认）、detect（仅检测框）、info（版本诊断）、doctor（系统诊断）。传入 .pdf 路径直接进入文档 OCR；document 命令处理显式多源任务。 平台加速：npm 包提供八种构建；需要显式控制的应用可通过 execution 选项选择 auto、cpu、apple 或 webgpu。Small 是稳定默认；Tiny 和 Medium 是 next 标签下的可选预览包，三者暴露相同 API、类型、结果结构和错误模型，但每次安装仅包含所选模型。NPU 支持通过 @arcships/light-ocr-openvino-linux-x64-gnu 或 @arcships/light-ocr-amdnpu-linux-x64-gnu 单独安装，并需显式选择 provider；默认安装不包含这些 provider 的库或编译模型。 C++ 项目从源码构建静态库并链接 light_ocr::core CMake 目标，API 接受已解码的 GRAY8、RGB8、BGR8、RGBA8 像素。
适用场景
- 在 Node.js 或 C++ 应用中本地识别图像与 PDF 文字。
- 需要置信度和坐标的 OCR 结果，例如字段提取、版面分析。
- 大图中包含小字或密集文字的识别，可使用分块模式。
- 为可调用本地命令的 AI 代理提供工作流：项目包含 Agent Skill，提供场景驱动工作流、命令选择指南和退出码参考，涉及何时使用 OCR 与多模态模型、大图的先检测后识别流程、收据与表单的 ROI 字段提取、用确定性 OCR 验证多模态输出。
限制与说明
- 支持 Node.js 22 或更新版本；22 和 24 LTS 为 Tier 1（完整测试）。
- 默认安装仅包含 Small 模型；Tiny 和 Medium 为 next 标签下的可选预览包。
- NPU 支持需单独安装对应包并显式选择 provider，默认安装不包含。
- macOS 下游打包者可重新签名本地二进制，加载器在签名验证通过且签名身份与宿主应用匹配（相同 TeamIdentifier，或均为 ad-hoc 签名）时接受重新签名的 Mach-O；其他平台和未签名变更仍保持严格的大小 + SHA-256 校验。
- 性能数据来自 0.3.0 在三台真实设备上的同机 CPU 路径对比，结果随工作负载和硬件变化；Apple 运行通过锁定的 CPU 同等阈值，两次 WebGPU 运行在全部 14 张图像上与 CPU FP32 字节完全一致。
- 项目采用 Apache License 2.0。
- 价格、收费模式等信息暂未提供。
