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. 环境与实测设备

实测环境:

项版本/型号
Electron40.1.0(peer 依赖 ≥ 20;库核心也支持纯 Node 18+)
Node.js / TypeScript24.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)
hdcDevEco 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 解析等于依赖系统输出格式的稳定性;文件是设备侧自己写的,边界清楚。

把这个路径放进系列里对照一下:

端端侧能力怎么进应用传输层识别发生在
KMPKotlin/Native 走 C ABI + N-API进程内桌面进程
FlutterMethodChannel进程内桌面进程
React NativeTurboModule进程内桌面进程
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 读回来。

Logo

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。

更多推荐