Umi-OCR 命令行手册详解：从截屏 OCR、二维码到高级模块调用的完整实战指南

本文基于 Umi-OCR 官方命令行手册 docs/README_CLI.md 展开，系统讲解通过 umi-ocr 命令驱动离线 OCR 的完整方法：软件操控、截屏/粘贴/路径识别、二维码识别与生成、结果输出控制，以及面向开发者的页面/模块/函数级高级指令。读完本文，你可以脱离图形界面，用一条命令行完成截图识别、批量图片 OCR 和 PDF 文档任务，并借助 HTTP /argv 接口在程序间可靠地调用 Umi-OCR。

基础说明：命令行入口与 HTTP 服务前置条件

命令行调用入口就是主程序 Umi-OCR.exe（Windows）或 umi-ocr.sh（Linux，见 README.md 的工程结构说明）。文档特别指出：如果你使用的是备用启动器（如 UmiOCR-data/RUN_GUI.bat），可能无法使用命令行。

命令行并非独立进程运行，而是依赖 Umi-OCR 的 HTTP 接口进行跨进程通信——你输入的命令行指令会传递给后台的 Umi-OCR 处理进程。这个通信过程仅在系统内部的本地环回进行，不会泄露到外部（不经过物理网卡）。因此有一个硬性前置条件：

• 在全局设置页中必须允许 HTTP 服务（默认开启）；
• 主机选择 仅本地 即可满足命令行使用需求。

全局设置页的界面如下（HTTP 服务相关选项位于"全局设置"标签页中）：

查看完整帮助：

umi-ocr --help

软件操控指令

以下指令用于直接控制已运行的 Umi-OCR 软件本身：

指令	作用
umi-ocr --show	弹出主窗口
umi-ocr --hide	隐藏主窗口
umi-ocr --quit	关闭软件
umi-ocr --reload	重新加载配置文件（v2.1.5 以上版本支持，见 CHANGE_LOG.md）

关于 --reload：Umi-OCR 的配置文件是 ./UmiOCR-data/.settings，ini 格式，软件界面上设置的参数会保存到此文件。你可以手动修改该配置文件，然后用 --reload 指令重新加载配置并刷新软件设置界面。这一机制使得"批量脚本改配置 → 重载生效"的自动化工作流成为可能。

OCR 指令

鼠标截屏

umi-ocr --screenshot

执行后弹出鼠标划选框，划选区域进行截图识别。按 Esc 可中断截图操作（该快捷键机制在 README.md 中也有说明）。

范围截屏（无需鼠标划选）

自动对指定屏幕、指定区域进行截屏，适合脚本化、定时化场景：

umi-ocr --screenshot screen=0 rect=x,y,w,h

范围截屏控制参数：

• screen：要截图的显示器编号（多个显示器时有效），从 0 开始，缺省为 0。
• rect：截图范围矩形框，x坐标,y坐标,w宽度,h高度，缺省为全屏。

注意：

• 这两个参数的前面无需加 --。
• 这两个参数至少要填一个才能触发范围截图；没有任一参数时执行的是鼠标截屏。

示例 1：截取第 1 个显示器的全屏：

umi-ocr --screenshot screen=0

示例 2：截取第 2 个显示器，从左上角 (50,100) 开始、大小 300x200 的矩形区域：

umi-ocr --screenshot screen=1 rect=50,100,300,200

示例 3：与 HotkeysCMD 工具配合，实现"按快捷键进行范围截图"。向 HotkeysCMD 的配置文件添加以下一行，表示按下 F10 时进行范围截图：

F10 umi-ocr --screenshot screen=0 rect=50,100,300,200

粘贴图片

umi-ocr --clipboard

识别当前剪贴板中的图片。

指定路径

umi-ocr --path "D:/xxx.png"

• 可传入文件夹的路径：将搜索文件夹中所有图片（包括嵌套子文件夹），并输出所有识别结果。
• 可传入多个路径：请用双引号 "" 包裹单个路径，不同路径间用空格隔开。

多个路径示例：

umi-ocr --path "D:/img1.png" "D:/img2.png" "D:/image/test"

提示：

• 多图识别时耗时较长；一次命令结束前不要输入下一个命令。
• 对于截屏、粘贴、路径指令，OCR 参数（如识别语言、是否复制到剪贴板、是否弹出主窗口）采用 截图OCR 标签页的设定。如果不希望命令行任务弹出主窗口，请在 截图OCR 标签页中关闭该选项。

命令行结果输出

输出方式	指令
复制到剪贴板	--clip
输出到文件（覆盖）	--output "file.txt"
输出到文件（追加）	--output_append "file.txt"

也可以使用箭头符号：

• "-->" 等价于 --output
• "-->>" 等价于 --output_append

示例：

umi-ocr --screenshot --clip
umi-ocr --screenshot --output test.txt
umi-ocr --screenshot "-->" test.txt

关于管道重定向的限制：由于运行环境的一些限制，Umi-OCR 暂时无法重定向输出流，系统管道重定向符 >、管道操作符 | 可能失效。如果需要用程序调用命令行指令、但发现无法收到回传，可改用 HTTP 转发命令行接口（/argv）代替。

二维码指令

识别二维码

umi-ocr --qrcode_read "D:/xxx.png"

与 OCR 指令一致，二维码识别也支持传入多个图片与文件夹路径。

生成二维码

umi-ocr --qrcode_create "文本内容" "D:/输出图片.jpeg"

默认图片宽高为最小适配长度，也可以在指令后方加数字手动指定：

• 同时指定宽高为 128 像素： umi-ocr --qrcode_create "文本内容" "D:/输出图片.jpeg" 128
• 宽 128、高 256 像素： umi-ocr --qrcode_create "文本内容" "D:/输出图片.jpeg" 128 256

关于指令简写

• 所有指令支持用前几个字母替代。如 --screenshot、--clipboard 可分别简写为 --sc、--clipbo，具体可自己尝试。
• 对于大部分系统，支持使用小写文件名加省略 .exe 来调用程序，即 umi-ocr --sc 等价于 Umi-OCR.exe --sc。

进阶：用 HTTP /argv 接口可靠地获得回传

docs/http/argv.md 定义了 /argv 接口，用于命令行参数的跨进程传输，一般由程序内部自动调用，开发者也可手动调用：

• URL：http://127.0.0.1:1224/argv，方法 POST，参数为 JSON 列表。
• 命令行调用 Umi-OCR.exe --path "D:/xxx.png" 等价于向该接口发送 ["--path", "D:/xxx.png"]。
• 由于该接口较敏感（允许访问本机图片、关闭软件等），只允许本地环回 127.0.0.1 调用，局域网或外网无法访问。
• 与命令行重定向受限不同，该接口的 HTTP 响应直接返回识别结果文本（字符串），因此是程序化集成时的更可靠选择。

JavaScript 调用示例（等价于命令行 Umi-OCR --screenshot）：

const url = "http://127.0.0.1:1224/argv";
const data = ["--screenshot"];
fetch(url, {
        method: "POST",
        headers: {"Content-Type": "application/json"},
        body: JSON.stringify(data)
    })
    .then(response => response.text()) // 返回值是字符串
    .then(data => {
        console.log("screenshot text:\n", data)
    })
    .catch(error => {
        console.error(error);
    });

具体命令行规则仍以上文的 README_CLI.md 为准。HTTP 接口的完整清单见 docs/http/README.md，其中包含图片 OCR、文档识别、二维码等 Base64 识别接口（api_ocr.md、api_doc.md、api_qrcode.md）。

高级指令（仅供有经验的开发者使用）

高级指令允许通过命令行调用任意标签页（模块）上的任意函数，代表了无限的可能性。代价是用法较复杂：需要在一定程度上阅读本项目源码，才知道该调用哪个函数、传入什么参数。

页面指令

"页面模板"相当于收藏夹，可以从收藏夹中打开一个新页面；"已打开的页面"可以关闭。

• 查询当前已打开的页面及所有页面模板（可获取 [index]）：

umi-ocr --all_pages

• 创建新标签页，[index] 为页面模板序号：

umi-ocr --add_page [index]

• 删除已创建的标签页，[index] 为现有页面序号：

umi-ocr --del_page [index]

模块指令

每个标签页通常具有两个模块，一个是 py，一个是 qml；还可能存在一些不依附于标签页的独立 py 或 qml 模块。每个模块上都有可被调用的函数。 模块名 [name] 允许简写：如模块全称为 ScreenshotOCR_1，可用 ScreenshotOCR 代替。每次程序运行时，模块名（的后缀）不一定相同，请使用简写来忽略后缀。

查询当前存在的 py 和 qml 模块（可获取 [name]）：

umi-ocr --all_modules

函数指令

• 查询某个 py 模块上可调用的函数（[name] 为模块名）：

umi-ocr --call_py [name]

• 查询某个 qml 模块上可调用的函数：

umi-ocr --call_qml [name]

• 调用 py 模块上的函数。[name] 为模块名，[function] 为函数名，[..paras] 为任意个参数：

umi-ocr --call_py [name] --func [function] [..paras]

• 调用 qml 模块上的函数：

umi-ocr --call_qml [name] --func [function] [..paras]

参数 [..paras] 输入的是字符串，会根据文本结构自动转换为 4 种变量类型：int、float、list、dict。

示例——调用二维码页 qml 模块的路径扫码函数，传入路径列表：

umi-ocr --call_qml QRCode --func scanPaths '[\"D:/Pictures/Screenshots/test/二维码/1111.png\",\"D:/Pictures/Screenshots/test/二维码/2222.png\"]'

同步调用函数（--thread）

命令行解析器运行在子线程。为了确保线程安全，命令默认转到主线程执行，对你来说这就是异步执行，无法取得函数返回值。 如果要获取函数返回值，可传入 --thread 指令同步执行命令。 这种操作较不安全，可能导致功能不正常甚至程序崩溃。

umi-ocr --call_qml [name] --func [function] --thread [..paras]

高级指令完整示例：批量生成双层可搜索 PDF

示例目标：将一些 PDF 文档添加到软件，生成双层可搜索 PDF。（提示：此例只演示高级指令的能力边界，PDF 文档识别也可直接调用 HTTP 接口。）

第 1 步（可选）：如果当前没有打开 批量文档 标签页，就打开它。

1.1 查询当前所有页面模板：

umi-ocr --all_pages

1.2 已知 BatchDOC 标签页的 template_index 为 3，创建该标签页：

umi-ocr --add_page 3

1.3 检查 BatchDOC 模块是否已存在：

umi-ocr --all_modules

在 Qml modules 中发现已存在 BatchDOC_1，即为正确。

第 2 步：将多个文档的路径输入软件。假设要添加以下文件：

C:\Users\My\Desktop\111.epub
C:\Users\My\Desktop\222.pdf

使用以下指令输入文档路径（路径中 \ 需要改为 /）：

umi-ocr --call_qml BatchDOC --func addDocs '[ \"C:/Users/My/Desktop/111.epub\", \"C:/Users/My/Desktop/222.pdf\"]'

关于 addDocs 后面路径参数的引号格式，这是 Windows 解析命令行参数的规则限制，与 Umi-OCR 自身的设计无关：

• 在 PowerShell 中，最外层为单引号 '，且左双引号前面必须有空格。即：'[■\"path_1\",■\"path_2\",■\"path_3\"]'（将 ■ 替换为空格 ）。单个路径为 '[■\"路径1\"]'。
• 在 Terminal（终端）中，最外层为双引号 "。即："[\"path_1\",\"path_2\",\"path_3\"]"。

第 3 步：启动任务：

umi-ocr --call_qml BatchDOC --func docStart

注意：暂时无法通过 CLI 更改保存文件的类型（默认为双层可搜索 PDF）。想要添加其他保存类型，必须在软件界面中勾选。

快速参考汇总

类别	指令	说明
帮助	umi-ocr --help	获取完整说明
操控	--show / --hide / --quit / --reload	弹出/隐藏/关闭主窗口、重载配置（v2.1.5+）
OCR	--screenshot [screen=N rect=x,y,w,h]	鼠标截屏或范围截屏
OCR	--clipboard	识别剪贴板图片
OCR	--path "p1" "p2" ...	识别图片/文件夹，支持多路径
输出	--clip / --output f / --output_append f / "-->" / "-->>"	复制/覆盖/追加输出
二维码	--qrcode_read "p"	识别二维码，支持多路径
二维码	--qrcode_create "text" "out" [w] [h]	生成二维码，可指定宽高
高级	--all_pages / --add_page i / --del_page i	页面查询/创建/删除
高级	--all_modules	查询 py/qml 模块
高级	--call_py/--call_qml [name] --func [f] [..paras]	调用模块函数
高级	追加 --thread	同步执行以获取返回值（慎用）

适用前提再强调两点：其一，命令行依赖全局设置中默认开启的 HTTP 服务（主机为"仅本地"即可）；其二，--reload 指令要求 v2.1.5 及以上版本。更多接口细节可结合 docs/http/README.md 与 docs/http/argv.md 查阅。