Electron 鸿蒙取字实战:把图片送进沙箱,把文字拿回桌面
Electron 没有鸿蒙运行时、Core Vision Kit 只对 ArkTS 开放、桌面上也不一定插着设备——这篇文章用一个 TypeScript 双后端引擎、一份可复用的 HAR 和一个零权限代理 HAP,把"图怎么进去、字怎么回来、失败怎么兜底"这三件事一次讲透。
仓库地址:https://atomgit.com/oh-tpc/electron-ohos-image-text
框架版本:https://atomgit.com/CPF-Electron/Electron/tree/v40.1.0-openharmony
组织仓库:https://atomgit.com/CPF-Electron
0. 环境与实测设备
实测环境:
| 项 | 版本/型号 |
|---|---|
| Electron | 40.1.0(peer 依赖 ≥ 20;库核心也支持纯 Node 18+) |
| Node.js / TypeScript | 24.12.0 / 5.9.3(CommonJS + d.ts 产物) |
| 测试 | Vitest 3.2.7,4 个文件 56 项用例(模型 / hdc 协议 / 本机后端 / 引擎降级) |
| DevEco Studio | 内置 SDK API 26.0.0.105,hvigor 随 IDE 自带 |
| ohos 工程基线 | compatibleSdkVersion 5.0.5(17) · targetSdkVersion 6.0.0(20) |
| hdc | DevEco SDK toolchains 自带;失败路径 target 127.0.0.1:5555(2in1 模拟器,API 26);设备侧成功路径的 74 行截图来自已装模型的 HUAWEI MateBook Pro S |
| 设备侧识别 | Core Vision Kit textRecognition(API 12 起可用,端侧离线) |
| 本机后端 | tesseract.js 6.x(WASM,跑在 Electron 主进程) |
| 实测设备 | HUAWEI MateBook Pro S(MOR-W52),HarmonyOS 7.0.0.111(SP15C00E101R9P2),API 26 |
1. 识别在设备上,调度在桌面上
端侧 OCR 这个系列已经覆盖了五个端:KMP 用 Kotlin/Native 走 C ABI + N-API,Flutter 用 MethodChannel,React Native 用 TurboModule,Electron 把设备当远程后端,Qt 用同进程的回环 HTTP 桥。Electron 这一支的库版本之前还停在 0.1.0:能跑、能识别、能回退,但设备侧的 OCR 代码焊死在示例 HAP 里,桌面示例也只是个验证窗口,窗口标题还叫 ElectronOcrAgent。
后来这个仓库更新到 0.2.0,名字改成 electron-ohos-ocr,做的事是一次"拆":设备侧拆成 ohos/library(HAR)和 ohos/example(代理 HAP);桌面示例重做成"取字"工作台;失败路径全部结构化(错误码 + 中文提示),界面不再把设备显示成可用。这篇不再从零讲 hdc,而是把一条已经跑起来的链路拆开,看这三步为什么这样组合。
起因很简单。桌面端要识别截图里的文字,我最初的想法很直接:找个 Electron 能用的 OCR 库,tesseract.js 一装就完事。但跑了几个中文界面截图就发现不对——端侧文字识别 能识别成 端 侧 文 字 识 别,小字号图标文字、中英混排、AppScope、ohos_hap 这种带下划线的词错得很有规律。而与此同时,手边的鸿蒙设备里装着一套端侧离线、中文识别质量极好的引擎(Core Vision Kit)。桌面与设备之间隔着一根 USB 线,这根线能不能把设备的识别能力借过来?
动手之前先做调研,两个结论直接决定了架构。
第一,Electron 上游(官方)没有 OpenHarmony / HarmonyOS 运行时。社区承接的 v40.1.0-openharmony 基线(CPF-Electron)是把 Electron 跑在鸿蒙 PC 上,不是把鸿蒙的 ArkTS 能力塞进 Chromium。为一个识别能力引入整套鸿蒙运行时,代价与收益不成比例。
第二,Core Vision Kit 的 textRecognition 只对 ArkTS 开放。这一点在 Qt 那一篇里已经撞过一次墙:没有 NDK、没有 C++ 绑定,N-API 的方向是 ArkTS → C++,没有"从别的运行时反向调 ArkTS"的官方机制。桌面进程里再怎么折腾,也调不到这个函数。
换个角度,方案就清楚了:桌面应用不需要自己拥有鸿蒙运行时,它只需要能驱动一台具备这套能力的设备。hdc(HarmonyOS Device Connector)本来就能向设备推文件、唤起 Ability、拉回文件——把图片推进设备上一个极简 ArkTS 代理,让它用 Core Vision Kit 识别完再把 JSON 拉回来,设备的识别能力就成了 Electron 应用的一个远程后端。
所以这个题目的边界很清楚:设备负责识别,桌面负责调度,协议负责两边不互相污染。具体拆成三件事:
- 三个 hdc 步骤怎么设计(
file send→aa start→file recv轮询,job id 是主键); - 双后端怎么降级(auto 探测、运行中失败回退、界面如实显示);
- 产物怎么分层(HAR 给所有鸿蒙应用、代理只负责沙箱与调度、Electron 库只暴露
OcrResult)。
2. 效果展示
先看设备侧——这是"取字 Agent"跑在一台 2in1 设备上的实拍:

窗口标题 取字 Agent,页头 取字 · 设备代理、副标题 HarmonyOS Core Vision Kit · 端侧文字识别,右上角状态 已安装、任务 暂无。工具栏两个动作:铁锈红的 选择图片并识别 和文字按钮 清空,最右侧一行小字 识别完成。
左栏预览的图本身就是一张 3120×2080 的桌面截图(文件名 screenshot_20261112_222838_com.huawei.hmos.filemanager.jpg):文件管理器、一个"文档包裹"窗口、上层还叠着上一轮的取字窗口和系统文件选择框——套娃。右栏是识别结果,标题旁一行 74 行 · 738 ms · 3120×2080 px,逐行编号:01 Õ、02 3、03 口此电脑、04 8 electron、05 ohos_hap、06 项目、07 ^C ohos_hap、08 >□.bitfun、09 >■.hvigor、10 >Cn account_quick_login、11 > AppScope、12 > docs、13 >In electron……
这些行来自一张桌面截图里的文件树、窗口标题、图标文字和缩进符:小字号、中英混排、下划线,还有窗口边框和上一轮结果的残影。74 行、738 ms,全部在设备本地跑完——这张截图是代理状态页的相册冒烟测试(右上角"任务 暂无",走的是 VisionOcr.pickAndRecognize),它和 Electron 通过 hdc 触发的任务共用同一个 textRecognition 入口;hdc 任务路径下,图片还会被推进代理沙箱、识别完立即删除。页面底部那行小字说明了整条链路的边界:图片只会发送到当前连接的设备,识别结果在设备本地生成。
桌面侧(example/,macOS)是同一份契约的另一个后端,也是"取字"这个名字的由来——它只做一件事:把图拖进来,把字取走。

窗口是"取字"工作台:暖纸色底、宋体标题、一条铁锈红强调色,没有渐变、玻璃和发光卡片。左栏图片 1000×760 px;右栏 识别结果 7 行 · 237 ms · 本机,逐行带置信度(95%、81%、94%、93%、94%、96%、96%),下面是"完整文本"和"复制全文"。右上角徽标是 本机 · Tesseract,状态栏写着 设备已连接,但端侧识别失败,已回退本机 · Core Vision Kit / Tesseract.js,右下角一行 npx electron-ohos-ocr-doctor。
这张截图的重点是状态一致性:设备确实连着,Agent 确实装着,但 2in1 模拟器镜像里没有 Core Vision Kit 的 OCR 模型,recognizeText 返回 1001400001;引擎在 auto 下回退到本机 Tesseract,界面把"为什么回退"写在了状态栏里。真机上徽标会是 设备 · Core Vision Kit,结果行里的置信度变成 ———Core Vision Kit 不返回逐行置信度,我们选择不编一个数字出来。
两张图合起来,能看到这个库的两条路径:成功时把整屏截图发给设备,失败时在界面里写明已回退本机。
3. 一次识别要几步:hdc 与双后端
写代码之前得先把原理捋好。
和"在应用里塞一个 OCR 库"相比,这套路径的区别是:识别不在桌面进程里发生。链路从下往上是这样:
┌──────────────────── Electron 主进程 ────────────────────┐
│ OhosOcrEngine(prefer: 'auto') │
│ ├─ DeviceOcrBackend │
│ │ HdcRunner → spawn('hdc', argv[]) 无 shell 字符串│
│ │ ① hdc file send -b → 沙箱 ocr/in/<job>.png │
│ │ ② hdc shell aa start → OcrAgentAbility │
│ │ ③ hdc file recv -b ← 沙箱 ocr/out/<job>.json│
│ └─ TesseractOcrBackend │
│ lazy import('tesseract.js') → worker(按语言) │
└──────────────────────────┬──────────────────────────────┘
│ USB / TCP(hdc)
┌──────────────────────────▼──────────────────────────────┐
│ HarmonyOS 设备:com.ohos.electronocr.agent │
│ OcrAgentAbility(零权限,exported 只为 aa 能启动) │
│ └─ OcrAgent.runJob → HAR VisionOcr │
│ ImageSource → PixelMap → textRecognition │
│ → OcrResult → JSON envelope │
└─────────────────────────────────────────────────────────┘
第一步:把图送进沙箱。 hdc file send -b 里的 -b 会把远端路径解释成 bundle 沙箱相对路径,所以不需要 run-as、不需要设备 root、也不需要申请公共存储权限——图片被放进代理自己的 filesDir/ocr/in/<job>.png。
第二步:叫醒 Ability。 hdc shell aa start -b <bundle> -a OcrAgentAbility --ps job <id> --ps lang CHINESE 把任务 id 和语言提示塞进 Want;代理在 onCreate / onNewWant 里读参数,识别完写结果、terminateSelf()。Ability 声明 exported: true 只是为了让 aa 工具能拉起它;requestPermissions 是空数组,因为静图识别不需要任何权限。
第三步:把结果拿回来。 hdc file recv -b 轮询 ocr/out/<job>.json,直到文件出现或 agentTimeoutMs 到期。成功和失败都写同一个结果文件——这是整条协议里容易忽略的一条约定(第 6 节会讲为什么)。
为什么不用 aa start 的退出码当结果?因为 aa 只负责把 Ability 拉起来,识别是异步的,进程退出码不等于识别完成。为什么不用 stdout 传结果?因为 hdc shell 的输出里混着设备日志和 aa 的提示,拿 stdout 解析等于依赖系统输出格式的稳定性;文件是设备侧自己写的,边界清楚。
把这个路径放进系列里对照一下:
| 端 | 端侧能力怎么进应用 | 传输层 | 识别发生在 |
|---|---|---|---|
| KMP | Kotlin/Native 走 C ABI + N-API | 进程内 | 桌面进程 |
| Flutter | MethodChannel | 进程内 | 桌面进程 |
| React Native | TurboModule | 进程内 | 桌面进程 |
| Electron(本库) | hdc 驱动设备上的 ArkTS 代理 | 进程外 · USB/TCP | 设备 |
| Qt | 同应用内回环 HTTP 桥 | 进程内 | 桌面进程(ArkTS 半边) |
前三条能进程内直调,是因为框架本身就是原生进程;Electron 的渲染进程和主进程都是 Chromium + Node,没有 ArkTS 运行时,所以只能把数据送到设备上处理,不能把设备能力加载进桌面进程。代价是每次识别多三次 hdc 往返(推图、起 Ability、轮询取结果)和一次设备调度;收益是识别质量直接等于系统能力,而且图片不出设备。
边界也要说清楚:这套路径依赖 hdc、依赖代理 HAP 已安装、依赖设备有 OCR 模型。当前 2in1 模拟器镜像就缺模型(textRecognition.init() 超时、recognizeText 返回 1001400001),所以 auto 必须能回退;这条路径要能用,回退是前提。
4. 工程怎么搭:一份 npm 库 + 一份 HAR + 一个代理 HAP
先看整体结构。这个仓库是三形态工程:根目录是 npm 库,ohos/library 是同一套模型的鸿蒙 HAR,ohos/example 是代理 HAP,外加 example/ 的桌面演示:
electron-ohos-ocr/
├─ src/ # Electron 侧库(npm 包)
│ ├─ engine.ts # OhosOcrEngine:双后端选择、降级、IPC 注册
│ ├─ backends/device-backend.ts # hdc 三步 + 冷启动预热
│ ├─ backends/tesseract-backend.ts
│ ├─ preload.ts # contextBridge 白名单(4 个 channel)
│ ├─ types.ts # OcrResult 契约 + envelope 解析
│ ├─ index.ts # 公共出口
│ └─ cli.ts # electron-ohos-ocr-doctor
├─ test/ # 4 个文件 56 项 Vitest
├─ example/ # 取字:Electron 工作台(main / preload / renderer)
├─ ohos/
│ ├─ library/ # HAR:OcrModels / VisionOcr / OcrJson
│ └─ example/ # 代理 HAP:OcrAgentAbility / OcrAgent / 状态页
├─ docs/ # api / architecture / verification / 截图
└─ dist/ # tsc 构建产物(CommonJS + d.ts)

这次设计的一个决定是把"能测"前置:
device-backend.ts的DeviceOcrBackend接受注入的spawnFn与fileOps——测试里用一个假 ChildProcess 就能跑完file send → aa start → file recv,不需要设备、不需要 Electron;tesseract-backend.ts接受注入的loader与clock——WASM 不启动也能测置信度归一化、去重、CJK 空格、worker 复用与释放;types.ts全是纯函数:createOcrResult的校验顺序、ocrResultFromWire的容错、parseAgentEnvelope的失败分支;- 56 项用例分布在 4 个文件(models 7 / device 18 / tesseract 19 / engine 12),
npm run verify一次跑完 typecheck + test + build。
HAR 与代理分开也是有意的:
ohos/library不认识 hdc、不认识 job,只提供"输入一张图,输出OcrResult";ohos/example只处理应用沙箱、任务 id、envelope 和生命周期;- 第三方鸿蒙应用可以直接依赖 HAR,不需要安装代理。
两侧 API 一一对应:
| Electron 版 | 鸿蒙侧 HAR |
|---|---|
engine.recognizeFile(path, options) | VisionOcr.recognizeBytes(bytes, source, language) |
engine.recognizeBytes(bytes, options) | VisionOcr.recognizeUri(uri, language) / pickAndRecognize |
OcrResult(interface) | OcrResult(class,带 fullText()) |
parseAgentEnvelope(raw, job) | resultToWire(result) / resultToJson(result) |
getBackendInfo() | 无对应 API:代理状态页用 AppStorage 展示 |
Electron 侧的完整链路如下:
渲染进程 主进程
───────── ────────
drop / 选择图片
└─ window.exampleOcr.imageInfo() ──ipc──▶ nativeImage → data URL(长边 1400)
└─ window.electronOhosOcr.recognizeFile(path, { language })
└─ OhosOcrEngine.recognizeFile()
├─ resolveBackend():device → local
├─ device:spawn hdc ×3 / local:worker
└─ 返回 OcrResult(blocks / durationMs)
└─ 渲染逐行结果、置信度与完整文本
对使用方来说,最终看到的 API 是这样的:
// 主进程
import { OhosOcrEngine, registerOcrIpcHandlers } from 'electron-ohos-ocr';
const engine = new OhosOcrEngine({
// macOS 上 DevEco Studio 自带的 hdc:
hdcPath: 'hdc',
});
registerOcrIpcHandlers(engine);
// preload
import 'electron-ohos-ocr/preload';
// 渲染进程
const result = await window.electronOhosOcr.recognizeFile('/path/to/receipt.png', {
language: 'CHINESE',
});
console.log(result.blocks.map((block) => block.text).join('\n'));
OhosOcrEngine 把选项原样传给两个后端,两个后端各自持有长生命周期资源(hdc 调用封装、tesseract worker)。registerOcrIpcHandlers 只注册四个 channel,配套的 preload 只暴露 window.electronOhosOcr——渲染进程看不到 ipcRenderer。示例的 BrowserWindow 用 contextIsolation: true、nodeIntegration: false;因为示例 preload 直接 require 库模块,sandbox 暂时是 false,不需要 Node 能力时可以改成纯 IPC 转发并打开 sandbox: true。
下面把库内部拆开讲:双后端、三个 hdc 步骤、本机兜底、契约,最后是鸿蒙侧的 HAR 与代理。
5. 把代码讲透
5.1 双后端:一个 API,两条路径
整个引擎的两段主要逻辑都很短。第一段是"这次该用谁":
// src/engine.ts - resolveBackend()
private async resolveBackend(): Promise<OcrBackend | null> {
if (this.prefer === 'local') {
return (await this.local.isAvailable()) ? this.local : null;
}
if (this.prefer === 'device') {
return (await this.device.isAvailable()) ? this.device : null;
}
if (await this.device.isAvailable()) {
return this.device;
}
return (await this.local.isAvailable()) ? this.local : null;
}
// 探测结果算不算"健康":hdc 在、设备在、Agent 没有被明确判定为缺失
private deviceHealthy(probe: DeviceProbe): boolean {
return probe.hdcFound && probe.deviceConnected && probe.agentInstalled !== false;
}
第二段是"跑到一半失败了怎么办":
// src/engine.ts - recognizeFileWithFallback()
const backend = await this.pickBackend();
try {
return await backend.recognizeFile(imagePath, options);
} catch (error) {
if (backend.kind === OcrBackendKind.Device && this.prefer !== 'device') {
const localOk = await this.local.isAvailable().catch(() => false);
if (localOk) {
try {
return await this.local.recognizeFile(imagePath, options);
} catch (fallbackError) {
throw decorate(OcrBackendKind.Local, fallbackError);
}
}
}
throw decorate(backend.kind, error);
}
几个设计上的取舍:
prefer 是三种语义,不只是"优先级"。 auto 允许回退,device 和 local 是严格模式:显式选了 device 却拔了线,就应该报 UNSUPPORTED,而不是悄悄用本机识别再报"成功"。调用方选严格模式,通常是因为业务上不能接受"换了个引擎"。
探测是建议,运行是事实。 getBackendInfo() 返回的是"下一次 auto 会用谁",它可能说 device,但这次运行失败了、回退到了 local。这两个信息必须分开暴露——BackendInfo 里有 active,OcrResult 里有 id(vision-on-device / tesseract-local),界面同时看这两个字段,显示才会和实际状态一致(见第 6 节坑四)。
错误要能分层。 设备失败后本机也失败,抛的是 local 的错——因为用户最后一次看到的是本机在跑;如果本机也救不了,OcrError.code 会区分 VISION_ERROR 和 UNSUPPORTED,而不是一个笼统的"识别失败"。
isAvailable() 和 getBackendInfo() 都承诺不抛错。 探测本身就是最容易出错的环节(hdc 没装、设备没连、bm dump 输出格式变了),让探测函数抛错等于让 UI 在启动时就崩。所有异常都被收进 BackendInfo 的字段里,界面想展示就展示,不想展示也不影响主流程。
5.2 三个 hdc 步骤落成代码:job id 是主键
设备后端最底层是一个 promise 化的 spawn 包装。它只做三件事:拼 argv、接超时、把 ENOENT 翻译成 HDC_NOT_FOUND:
// src/backends/device-backend.ts - HdcRunner.run()(节选)
const argv = [this.hdcPath, ...this.buildArgs(args)];
child = this.spawnFn(argv[0], argv.slice(1), {
stdio: ['ignore', 'pipe', 'pipe'],
});
// ...
child.on('error', (error: NodeJS.ErrnoException) => {
if (error.code === 'ENOENT') {
reject(
new OcrError(
'HDC_NOT_FOUND',
`hdc not found at "${this.hdcPath}" — install the DevEco Studio toolchains or pass OcrEngineOptions.hdcPath`,
error,
),
);
}
});
注意这里没有任何 shell 字符串:设备名、bundle、沙箱路径、job id 全部是 argv 数组里的独立元素。hdc 的参数里混进一个空格或分号,都不会变成第二条命令。
job id 是整条协议的主键。每次识别生成一个 16 位、无连字符的 id,输入文件、输出文件、Want 参数都以它命名:
// src/backends/device-backend.ts - newJobId()
export function newJobId(): string {
return randomUUID().replace(/-/g, '').slice(0, 16);
}
// 代理侧接受的格式:小写字母/数字/横线,8–64 位
const JOB_ID_PATTERN = /^[0-9a-z-]{8,64}$/;
这三个步骤本身没有花活,就是把三个命令按顺序发出去,第三步循环到文件出现:
// src/backends/device-backend.ts - 三步(省略 guard 与超时参数)
await this.runner.run(['file', 'send', '-b', this.agentBundle, localPath, remote]);
await this.runner.run([
'shell', 'aa', 'start',
'-b', this.agentBundle, '-a', this.agentAbility,
'--ps', 'job', jobId, '--ps', 'lang', language,
]);
for (;;) {
const run = await this.runner.run(['file', 'recv', '-b', this.agentBundle, remote, localPath]);
if (run.code === 0 && this.fileOps.existsSync(localPath)) {
break;
}
if (Date.now() >= deadline) {
throw new OcrError('AGENT_TIMEOUT', `Agent did not write ${remote} within ${this.agentTimeoutMs} ms`);
}
await sleep(this.pollIntervalMs);
}
有一个小细节:设备侧写进 envelope 的 source 是 <job>.png——对它来说只知道这个文件名。桌面侧在返回前把它覆盖成调用方传的 source 或原始文件名:
const source = options.source ?? path.basename(imagePath);
return source === envelope.result.source
? envelope.result
: { ...envelope.result, source };
不然界面上会出现一个随机 id,用户不知道那是哪张图。
轮询的默认参数是 agentTimeoutMs: 60000、pollIntervalMs: 500——设备端识别通常几十到几百毫秒,但冷启动、低端设备、大图都会更慢;超时给到 60 秒,失败时错误信息里会带上最后一次 hdc 的 stderr,排查时不用猜。
5.3 本机兜底:tesseract.js 与那些空格
本机后端的职责是"没有设备时也能用",所以它必须懒加载、复用 worker、失败可解释:
// src/backends/tesseract-backend.ts - getWorker()(节选)
const lang = (this.options.languageMap ?? TESSERACT_LANGUAGES)[language];
const cached = this.workers.get(lang);
if (cached) {
return cached;
}
const created = (async () => {
const tesseract = await this.loadModule();
return await tesseract.createWorker(lang, undefined, workerOptions);
})();
this.workers.set(lang, created);
created.catch(() => this.workers.delete(lang));
return created;
dispose() 会在 Electron 的 will-quit 里调用,把缓存的所有 worker 终止掉。语言映射是 CHINESE → chi_sim、ENGLISH → eng、JAPANESE → jpn、KOREAN → kor。
从 tesseract 的结构到我们自己的 OcrResult,中间有一层"翻译":data.blocks[].paragraphs[].lines[] 展平、trim、去重;置信度从 0…100 归一化到 0…1 并 clamp;如果当前 tesseract.js 构建不返回 blocks,就退化成整页文本按行拆。去重是必须的,因为 OcrResult 要求 block 文本唯一——同一张票据上两个 $0.00,只能留一个(这是家族契约的已知取舍,第 7 节会写进限制)。
中文空格处理起来更麻烦。tesseract 的 chi_sim 模型经常给每个汉字之间插空格,识别结果是 端 侧 文 字 识 别,直接显示像乱码:
// src/backends/tesseract-backend.ts - normalizeCjkSpacing()
const CJK_RANGE = '\\u3400-\\u4DBF\\u4E00-\\u9FFF\\uF900-\\uFAFF';
const CJK_GAP = new RegExp(
`([${CJK_RANGE}])[ \\t]+(?=[${CJK_RANGE}\\u3000-\\u303F\\uFF00-\\uFFEF])`,
'g',
);
export function normalizeCjkSpacing(text: string): string {
let current = text;
let previous = '';
while (current !== previous) {
previous = current;
current = current.replace(CJK_GAP, '$1');
}
return current;
}
这里有两个容易写错的地方。第一,只折叠两个汉字之间的空格,项目 HarmonyOS OCR 接入 里的空格要保留——把所有空格都删掉会把拉丁词粘在一起,比原来更糟。第二,正则用 lookahead 匹配后一个汉字但不消耗它,所以 端 侧 文 字 这类连续汉字一次扫描就能收敛;代码里仍然写成 while (current !== previous) 跑到不动点,属于防御性写法,正常输入下一次替换就够,字符集以后再放宽也不会留下新的可匹配间隙。
本机后端还有一个"默认语言"的细节:recognizeBytes 在没传 language 时默认 English,而设备后端默认 Chinese。这不是 bug——设备端由 Core Vision Kit 自己判断语种,字段只是元数据;本机端需要选 traineddata,英文模型更小更常见。但调用方最好显式传语言:示例里那个 语言提示 下拉框就是干这个的,同一张图用中文和英文各跑一次,结果会不一样。
最后是置信度的显示原则。本机后端的置信度是真实数字(界面显示 95%),设备端没有逐行置信度(界面显示 — 并带 tooltip)。我们本来可以给设备端编一个固定值,但那就等于告诉用户"这一行 95% 可信"——Core Vision Kit 根本没给这个数。宁可少一个数字,也不要多一个假数字。
5.4 契约:OcrResult 与 envelope 的字段约定
这个系列里每一端都共享同一份 OcrResult 契约。Electron 侧的类型和校验函数刻意对齐 Kotlin 的 require 顺序与错误文本:
// src/types.ts - createOcrResult()
const blocks = init.blocks.map((block) =>
createOcrBlock(block.text, block.confidence),
);
requireCondition(!isBlank(init.id), 'Result id must not be blank');
requireCondition(init.durationMs >= 0, 'Duration must be non-negative');
const texts = new Set(blocks.map((block) => block.text));
requireCondition(texts.size === blocks.length, 'Block texts must be unique');
五条校验、五句英文错误,和 flutter_ohos_ocr、react-native-ohos-ocr、kmp-ohos-ocr 一字不差:空文本是 Block text must not be blank,置信度越界是 Confidence must be between 0.0 and 1.0,空 id 是 Result id must not be blank,负时长是 Duration must be non-negative,重复 block 是 Block texts must be unique。跨端对比的时候,同一个坏输入应该在所有语言里得到同一句话,否则排查只能靠猜。
鸿蒙侧的 OcrResult 是一个 ArkTS class,校验写在构造函数里;JSON 边界则不依赖类的序列化,而是手写 resultToWire,保证字段顺序稳定:
// ohos/library/src/main/ets/ocr/OcrJson.ets - resultToWire()
const wire: Record<string, Object> = {
'id': result.id,
'source': result.source,
'language': jsonName(result.language),
'blocks': blocks,
'durationMs': result.durationMs,
};
return wire;
envelope 是协议的外层 JSON 封装,成功和失败的格式如下:
{
"ok": true,
"job": "<job>",
"backend": "vision-kit",
"result": {
"id": "vision-on-device",
"source": "<job>.png",
"language": "CHINESE",
"blocks": [{ "text": "有光咖啡", "confidence": 0.0 }],
"durationMs": 142
}
}
{ "ok": false, "job": "<job>", "error": { "code": "OCR_VISION_ERROR", "message": "… (code 1001400001)" } }
桌面侧用 parseAgentEnvelope 解析:先看 ok,失败就抛 AGENT_ERROR;成功就用 ocrResultFromWire 逐字段容错。durationMs 兼容 elapsedMs 这个别名——上游有些实现叫后者,解析器两个都认,避免因为一个字段名让整条链路失效。
这套契约有一条硬性约定:envelope 永远会写。设备端不管成功、识别失败、输入丢失,都会在 ocr/out/<job>.json 落一份文件。宿主不需要区分"再等等"和"永远不会来",只等文件;超时逻辑也只有一条路径。
5.5 鸿蒙侧:HAR 提供能力,代理负责沙箱与生命周期
ohos/library 里的 VisionOcr 把"字节 → 文字"这条链路封成三个动作:解码、识别、收敛:
// ohos/library/src/main/ets/ocr/VisionOcr.ets - recognizeBytes()(节选)
imageSource = image.createImageSource(VisionOcr.toArrayBuffer(bytes));
pixelMap = await imageSource.createPixelMap();
const info: image.ImageInfo = await pixelMap.getImageInfo();
const visionInfo: textRecognition.VisionInfo = { pixelMap: pixelMap };
const output: textRecognition.TextRecognitionResult =
await textRecognition.recognizeText(visionInfo);
const blocks: OcrBlock[] = VisionOcr.collectBlocks(output);
// ...
} finally {
if (pixelMap !== null) {
await pixelMap.release();
}
if (imageSource !== null) {
await imageSource.release();
}
}
两个 ArkTS 特有的点。第一,createImageSource 收的是 ArrayBuffer,不能直接把 Uint8Array 的 .buffer 递过去——Uint8Array 可能只是大 buffer 上的一个视图,.buffer 会把视图外的字节一起交出去,偏移和长度都对不上;toArrayBuffer 显式复制一份。第二,PixelMap 和 ImageSource 都必须 release(),放在 finally 里,否则连续识别几十张图之后内存会一直涨。
collectBlocks 把 blocks[].lines[].value 展平、trim、去重,每个 block 的置信度写 0.0——Core Vision Kit 不提供这个数,envelope 里如实写 0,界面显示 —。
代理这一层只负责沙箱路径、输入清理和 envelope,识别仍由 HAR 完成:
// ohos/example/src/main/ets/ocr/OcrAgent.ets - runJob()(节选)
const filesDir: string = context.filesDir;
const inDir: string = `${filesDir}/ocr/in`;
const outDir: string = `${filesDir}/ocr/out`;
await OcrAgent.ensureDir(inDir);
await OcrAgent.ensureDir(outDir);
OcrAgent.pruneOutputs(outDir).catch((): void => {});
try {
const run: VisionRun = await VisionOcr.recognizeBytes(bytes, `${jobId}.png`, language);
await OcrAgent.writeText(outPath, OcrAgent.okEnvelope(jobId, run.result));
} catch (error) {
await OcrAgent.writeText(
outPath,
OcrAgent.errorEnvelope(jobId, 'OCR_VISION_ERROR', visionErrorMessage(error as Object)),
);
throw new Error(visionErrorMessage(error as Object));
} finally {
await OcrAgent.removeFile(inPath);
}
Ability 则只处理生命周期和 Want 参数:
// ohos/example/src/main/ets/entryability/OcrAgentAbility.ets - onNewWant()
onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
const job: string | null = wantString(want, 'job');
if (job === null) {
return;
}
this.pendingJob = job;
this.pendingLanguage = languageFromWire(wantString(want, 'lang') ?? '');
this.runPendingJob();
}
冷启动时 onCreate 只记下任务,onWindowStageCreate 里 loadContent('pages/Index') 完成后再执行;热启动走 onNewWant,直接复用已经存在的 Ability 实例。任务结束(成功或失败)都 terminateSelf(),设备上不会留下一个常驻进程。
module.json5 里没有声明任何权限,exported: true 只为了让 aa 工具能启动 Ability:
{
"module": {
"name": "entry",
"type": "entry",
"mainElement": "OcrAgentAbility",
"deviceTypes": ["phone", "tablet", "2in1"],
"requestPermissions": [],
"abilities": [
{
"name": "OcrAgentAbility",
"srcEntry": "./ets/entryability/OcrAgentAbility.ets",
"exported": true
}
]
}
}
状态页(pages/Index.ets)和桌面工作台共用一套视觉语言:暖纸色 #F2EFE9、墨色 #211F1B、铁锈红 #A5432A、1px 发丝线、2–4px 小圆角。手动启动应用时,它是一个相册冒烟测试页:左边预览、右边逐行结果、右上角状态本地化(已安装 / 暂无),失败时保留 Core Vision Kit 的数字错误码;每一行的 Text 都开了 copyOption(CopyOptions.LocalDevice),识别出来的字可以直接在设备上长按复制。这张页面就是第 2 节截图里那个窗口——它和 Electron 侧的"取字"是同一套排版,只是实现从 HTML/CSS 换成了 ArkUI。
6. 踩坑与经验
这一节的坑全部来自这次开发的真实排查记录。
坑一:冷启动时 hdc file send -b 找不到沙箱。 第一次把图片推进设备,hdc 报 Invalid bundle name;把 bundle 换成正确的之后又报 no such file or directory。报错的原因和路径无关:代理还没跑过。ocr/in、ocr/out 这两个目录是 OcrAgent.runJob 里创建的,冷启动时它们根本不存在,hdc 的 -b 路径解析自然失败。修复:识别这两类报错,先做一次 throwaway 的 aa start 预热(job id 加 boot 前缀),轮询到一个 bootstrap envelope 确认目录已建好,再重试原来的 file send。warmupSandbox() 用一个 promise 缓存,并发任务只预热一次;失败时清空缓存,允许下一次任务重试。教训:-b 的路径不是"应用私有目录"这么简单,它要求 bundle 沙箱已经存在,而沙箱里的目录是应用自己建的。
坑二:结果文件永远不出现。 第一版只在识别成功时写 JSON。设备端返回 1001400001 时,宿主什么也拿不到,只能一直轮询到 AGENT_TIMEOUT——用户看到的是"卡了一分钟然后超时",而不是"设备缺少 OCR 模型"。修复:所有终态都写 envelope。成功写 { ok: true, result },失败写 { ok: false, error: { code, message } },输入丢失也写 AGENT_INPUT_MISSING。桌面侧只判断文件在不在,再解析 ok;aa start 的返回码只代表"Ability 被拉起",不参与结果判断。教训:异步任务的结果通道必须覆盖失败,否则"失败"和"还没好"在宿主看来是一样的。
坑三:aa start --ps 的参数会被当成命令的一部分。 Want 参数只接受短字符串,job id 里如果带空格、引号、分号,行为不可预期。修复分两层:newJobId() 生成的是纯十六进制 id(去掉 UUID 的横线,截 16 位),startAgent 里再用 ^[0-9a-z-]{8,64}$ 校验一次;同时所有 hdc 参数都走 spawn 的 argv 数组,全程没有 shell 拼接。教训:任何要经过 hdc shell 的字符串,都当成不可信输入处理——包括你自己生成的 id。
坑四:界面显示和运行结果不一致。 最初的徽标只看 getBackendInfo().active:探测说 device 健康,就显示"设备 · Core Vision Kit"。但 2in1 模拟器镜像缺模型,实际运行会回退到 Tesseract,界面却仍然写着设备识别——用户以为设备在识别,实际设备只返回了错误。修复:渲染层同时看 info.active 和 result.id;当 result.id === 'tesseract-local' 且 active === 'device' 时,显示"设备已连接,但端侧识别失败,已回退本机"。状态栏、徽标、结果元信息三处口径统一。教训:探测结果和本次运行结果是两个事实,界面必须能同时表达。
坑五:为了去掉中文空格,把英文空格也删了。 tesseract 的 chi_sim 会给汉字之间插空格,识别成 端 侧 文 字 识 别,最初图省事直接 text.replace(/\s+/g, ''),结果 项目 HarmonyOS OCR 接入 变成 项目HarmonyOSOCR接入,2026-11-13 12:20 也粘成一坨。修复:正则只匹配"两侧都是汉字"的空白,用 lookahead 保住后一个汉字;拉丁词、数字、标点周围的空格原样保留。normalizeCjkSpacing 再循环到不动点,作为防御。教训:文本清洗的删除范围要尽可能窄,"看起来更干净"往往意味着信息被删掉。
坑六:fileIo.mkdir 不递归,EEXIST 也不是"错误"。 ocr/in 的父目录 ocr 不存在时,mkdir 直接抛错;已经存在时又抛 13900015(errno 17)。第一版把 EEXIST 当失败,导致第二次识别永远起不来。修复:ensureDir 逐段 mkdir,非 EEXIST 时再用 stat().isDirectory() 区分"已存在"和"真的失败(比如 EACCES)",只有后者才抛。教训:ArkTS 的文件 API 没有幂等语义,目录创建要自己写对。
坑七:预览图不能用 file:// 直出。 渲染进程拿到的是用户拖进来的 File,路径得靠 webUtils.getPathForFile 解析;直接拼一个 file:// URL 塞给 <img>,在 CSP 和沙箱组合下时好时坏,路径里带空格或中文还会二次编码。修复:主进程用 nativeImage.createFromPath 解码,长边压到 1400 px,回一个 data URL;渲染进程只负责显示。nativeImage 解不出来时给明确的"Unsupported or unreadable image",而不是一个空白框。教训:跨进程传图片,传像素(data URL)比传路径稳;路径是权限和编码问题的集合。
7. 现在怎么用:从 三方库 到依赖
经过上面的整理,这个工程是三形态交付:npm 库给 Electron 桌面端,HAR 给鸿蒙端,代理 HAP 给设备侧。0.2.0 还没有发布到公共 npm registry(Electron 由宿主以 peer dependency 提供),目前直接从仓库安装:
npm install git+https://atomgit.com/oh-tpc/electron-ohos-image-text.git
发布到 registry 之后,同样的位置就是 npm install electron-ohos-ocr。
鸿蒙侧在工程 oh-package.json5 里加一条本地依赖(或把 ohos/library 拷入工程引用):
{
"dependencies": {
"electron-ohos-ocr": "file:../library"
}
}
构建、安装、启动(仓库的 signingConfigs 是空占位,签名材料不入库,用 DevEco Studio 自动生成调试签名):
cd ohos/example
ohpm install
cd ..
export DEVECO_SDK_HOME="<DevEco SDK 路径>"
export NODE_HOME="<DevEco Node 目录>"
hvigorw \
--mode module -p product=default -p module=library@default assembleHar --no-daemon
hvigorw \
--mode module -p product=default -p module=entry@default assembleHap --no-daemon
hdc install -r ohos/example/build/default/outputs/default/entry-default-signed.hap
hdc shell aa start -a OcrAgentAbility -b com.ohos.electronocr.agent
接入代码在第 4 节已经给过,核心就是 new OhosOcrEngine() + registerOcrIpcHandlers(engine)(桌面)或 VisionOcr.pickAndRecognize()(鸿蒙应用直接 import HAR)。环境自检(仓库内跑 npm run doctor;包发布后就是 npx electron-ohos-ocr-doctor):
npm run doctor
它会依次检查 hdc、连接目标、Agent 安装情况与本机 tesseract.js,并打印 auto 会选择的后端。更完整的 API 表、安全模型和排错说明在仓库的文档里:
- 完整 API、协议、HAR 与构建命令;
- Electron API、错误码、preload、HAR API;
- hdc 协议、envelope、后端选择、失败矩阵;
- 2026-11-13 的构建/测试/模拟器与端到端记录;
example/与ohos/example/:桌面工作台与设备代理的状态页。
当前版本(0.2.0)在 2026-11-13 的验证结果:npm run verify 全绿——tsc --noEmit 通过、Vitest 4 个文件 56 项全部通过、tsc 构建产出 dist/;ohos/library 与 ohos/example 用 DevEco 自带 hvigor 构建成功(library.har 17 KB、entry-default-unsigned.hap 130 KB);代理 HAP 安装到 2in1 模拟器后,一次真实 hdc 任务返回结构化 OCR_VISION_ERROR(1001400001),证明三个 hdc 步骤、沙箱、错误 envelope 都通;Electron 示例在 auto 下自动回退本机,7 行 / 237 ms,界面如实显示回退原因。设备侧成功路径的截图来自另一台已装模型的真机:74 行 / 738 ms / 3120×2080 px。
也得把限制写清楚,免得后来人踩同样的坑:
- device 后端依赖
hdc与已安装的代理 HAP;Electron 上游没有鸿蒙运行时,这一点短期不会改变; - Core Vision Kit 不返回逐行置信度,device 结果的
confidence为0.0,界面显示—; - 当前 2in1 模拟器镜像缺 OCR 模型(
1001400001),换真机即可;auto会回退本机; OcrResult要求 block 文本唯一,重复行(小票上的两个$0.00、文件列表里的多个"文件夹")会被去重,这是家族契约的取舍;- 本机 Tesseract 的中文准确率仍取决于图片质量,CJK 空格归一化只解决排版,不解决识别。
如果要留一条结论给下次:让图片进沙箱,让文字出 JSON,让界面如实显示。 桌面应用不需要拥有鸿蒙运行时,它只需要知道怎么把图送过去、再把 JSON 读回来。
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。
更多推荐

所有评论(0)