一个只对 ArkTS 开放的端侧 AI 能力、一条四步 hdc 通道、一个 1.8 MP 的模型输入上限——这篇文章用一个双后端引擎、一份可复用的 HAR 和一个零权限代理,说明小图怎么进设备、结果怎么回桌面、超过输入上限时怎么回退。代码和排查记录都在仓库里。

仓库地址:https://atomgit.com/oh-tpc/electron-ohos-ai-vision
Electron 版本:https://github.com/electron/electron/releases/tag/v40.1.0
三方库框架:https://atomgit.com/oh-tpc

0. 环境与实测设备

三方库适配信息:

三方库版本 / 基线形态仓库地址
electron-ohos-ai-vision0.3.0(Electron ≥ 20,本机 40.1.0;未发布公共 npm registry)npm 形态桌面库,零运行时依赖https://atomgit.com/oh-tpc/electron-ohos-ai-vision
electron-ohos-ai-vision(鸿蒙侧)0.3.0ohpm 三方库(HAR,零依赖 import)同仓库 ohos/library
com.ohos.electronvision.agent0.3.0(versionCode 30000)设备代理 HAP(entry 模块,零权限)同仓库 ohos/example

实测环境:

项版本/型号
Electron40.1.0(peer 依赖 ≥ 20;库核心也支持纯 Node 18+)
Node.js / TypeScript24.12.0 / 5.9.3(CommonJS + d.ts 产物)
测试Vitest 3.2.7,6 个文件 92 项用例(模型 / PNG / 重采样 / 本机后端 / 设备协议 / 引擎)
DevEco Studio自带 hvigor 6.26.4、SDK 26.0.0.105(apiVersion 26)
设备HUAWEI MateBook Pro S(MOR-M1),HarmonyOS 7.0.0.111(SP15C00E101R9P2),API 26
系统能力SystemCapability.AI.Vision.VisionBase = true;imageSuperResolution 自 API 26 起提供,仅 Stage 模型
模型输入边界实测约 1.8 MP(直接喂 analyzer):1536×1152 通过,1600×1152 / 1600×1200 / 3120×2080 返回 401;HAR 的预缩盒更保守:1536 px / 1.75 MP
设备输出模型固定 4×,长边上限约 6400 px;HAR 按输出尺寸选 PNG / JPEG q95
本机回退自带 PNG 编解码 + Lanczos3 + unsharp mask,无原生模块
实测419×600 → 1676×2400,4.00×,348 ms(第 2 节截图);480×360 → 1920×1440,4×,251 ms;3120×2080 → 6144×4096,1.97×,1308 ms;本机 480×360 → 960×720,1006 ms

有一个数字要先说清楚:设备结果的 durationMs 是设备侧的超分加编码时间,不含 hdc 传输;本机结果的 durationMs 是整条本机管线(解码、重采样、锐化、编码、写盘)的墙钟时间。走设备时,桌面端从推图到拿到文件的总耗时更长,取决于图片大小和 USB / TCP 的链路。截图里的 348 ms 是设备侧口径,不要拿它当“点一下按钮到出图”的端到端时间。

1. 从“取字”到“放大”:这个仓库为什么换了方向

严格说,这个仓库不是从零开始的。它的上一版叫 electron-ohos-ocr 0.2.0,做的是端侧文字识别:hdc 把图片推进设备,代理调 textRecognition,再把结果 JSON 拉回桌面。那条链路跑通之后,我盯着 Core Vision Kit 的能力列表看了很久——textRecognition 只是其中一个,旁边还有 imageSuperResolution(图像超分)。

OCR 是“把字取出来”,超分是“把图变清楚”。听起来都是图片进、结果出,真做起来差别不小:OCR 的结果是一段 JSON,几 KB,失败路径简单;超分的结果是一张几 MB 的图,要拉两次(信封 + 图),还要处理编码、内存和输入尺寸。所以 0.3.0 把能力整个换掉,仓库名沿用 electron-ohos-ai-vision,这是一次 breaking release——旧的 OCR API 没有留兼容层,想用的人请回到仓库历史里的 0.2.0 提交(9ddd6f4)。

为什么是超分?桌面端要做放大,选项其实不多:

  • Lanczos / bicubic 是插值。放大 4 倍只是增加像素数量,边缘还是糊,细节不会增加;
  • sharp / libvips 要编译原生依赖,Electron 的 macOS / Windows / Linux 打包矩阵会变得很难受;
  • waifu2x / Real-ESRGAN 这类方案要带模型权重、要 GPU,装完包体直接上一个量级,首启还要等模型加载。

设备端这套是系统自带模型,图片不出设备、不需要鉴权、不需要下载权重,正好补上桌面的短板。当然,它也不是万能的:模型不接受倍数参数,超过约 1.8 MP 的输入会 401(HAR 会先预缩),输出倍数固定 4×,文本和 UI 还可能被“重画”。这些限制后面都会讲,先把链路跑通。

所以这个题目的边界很清楚:设备负责推理,桌面负责推图和拉图,本机负责回退。具体拆成三件事:

  • 四步协议怎么设计(推图、起 Ability、轮询信封、拉图,比 OCR 多一步);
  • 模型输入上限和真实倍数怎么算(1.8 MP、1.97× 这些数字不是拍脑袋);
  • 本机回退怎么做(Lanczos3 + 自带 PNG 编解码,明确不是 AI,也不假装是)。

下面是跑通之后的记录,包括几次把设备跑出 401 的过程。

2. 效果展示

先看效果。这张是“放大 Agent”在一台 2in1 设备上手动跑的状态页:

在这里插入图片描述

窗口标题 放大 Agent,页头 放大 · 设备代理,副标题 HarmonyOS Core Vision Kit · 端侧图像超分。右上角状态 已安装、任务 暂无。工具栏一行:铁锈红的 选择图片并超分、文字按钮 清空,最右边是 完成 · 348 ms · 4.00×。

原图是 IMG_20261113_213845.webp,419×600;超分结果 1676×2400,正好 4 倍。左右并排的是原图和结果——在这个尺寸下,两张图看起来都“还行”,更值得看的是下半部分的 细节对比 100%。

同一块区域,左边是模型输入(UI 把它按 4× 插值放大到和右边一样大),右边是系统超分。左边能明显看到方块状的像素台阶,右边的草叶、树皮和落叶边缘被重新画过,过渡更连续,连高光旁边那圈模糊区域也补上了纹理。放大前后的差别在缩略图里看不出来——这也是我后来在状态页里加 100% 对比的原因:只放两张并排缩略图不够。

说实话,第一次看到这个对比时我有点意外:模型做的是重新画纹理。

页面底部一行小字:图片只在本机解码并交给系统能力处理,结果留在应用沙箱,不上传云端。

说明一下:这张是手动启动状态页、用系统相册选图跑的(右上角任务还是“暂无”),走的是同一个 HAR 和同一个 imageSuperResolution;Electron 通过 hdc 触发的任务只是多了推图和拉图,识别本身没有区别。

再看一张“超限”的:

在这里插入图片描述

3120×2080 的桌面截图,结果 6144×4096,截图这次是 1650 ms,倍数 1.97×。为什么不是 4×?因为 3120×2080 已经超过模型输入上限,HAR 会先把它按比例缩到 1536×1024 再推理;模型的 4× 是按“模型输入 → 输出”算的;scale 记录的是原图到输出的倍数,所以这里是 1.97。同一台设备上,不同次运行会在一千三到一千七百毫秒之间波动,这个也正常。

这张图也暴露了模型的短板:它擅长照片和纹理,对界面文字就没那么客气。验证记录里,状态栏的“已安装”被重画成了方块状符号——模型在按先验“猜”笔画,并没有识别文字。所以 UI 截图这类素材,我一般用本机 Lanczos3 或者干脆不超分。这一点后面第 6 节还会展开。

为了不只凭肉眼判断,我用 Laplacian 方差做了个粗测(越高越锐),拿设备桌面截图裁 640×480 的人像 / 图标区域作为真值,缩到 160×120 再跑设备 4×:

图像Laplacian 方差
真值 640×4801070.6
双线性放大 4×10.5
系统超分 4×270.2

同一方法在 2560×1920 的 UI 区域:双线性 5.4、系统超分 124.7、真值 411.9。系统超分确实把高频能量拉回来了(10.5 → 270.2,高了一个数量级),但离真值 1070.6 还差得远;它在重建纹理,并没有还原原始细节。这个数字也解释了为什么文字会走样:模型有“画纹理”的先验,遇到笔画这种强结构,先验不一定对。

桌面侧的示例叫“放大”:左边原图、右边结果,中间一条可拖动的分割线;右边显示真实尺寸、实际倍数、耗时、文件大小和输出路径,“保存结果…”可以把图复制到别处。倍数下拉只对本机后端生效——设备模型不接受倍数参数,这一点在界面上写得很直白。后端徽标会写 设备 · 系统超分 (target) 或 本机 · Lanczos3 回退,与实际选择一致。

3. 四步 hdc:超分链路到底怎么走

写代码之前先把链路捋清楚。一次设备超分是四步,比 OCR 多一步:

┌──────────────────────── Electron 主进程 ────────────────────────┐
│  OhosSuperResolutionEngine(prefer: 'auto')                    │
│    ├─ DeviceSuperResolutionBackend                              │
│    │    HdcRunner → spawn('hdc', argv[])  无 shell 字符串        │
│    │      ① file send -b   → 沙箱 sr/in/<job>.png                │
│    │      ② shell aa start → SrAgentAbility(--ps job <id>)    │
│    │      ③ file recv -b   ← 沙箱 sr/out/<job>.json(轮询)      │
│    │      ④ file recv -b   ← 沙箱 sr/out/<job>.out.png          │
│    └─ LocalSuperResolutionBackend                                │
│         decode → Lanczos3 → unsharp → encodePng                  │
└──────────────────────────┬───────────────────────────────────────┘
                           │ USB / TCP(hdc)
┌──────────────────────────▼───────────────────────────────────────┐
│ HarmonyOS 设备:com.ohos.electronvision.agent                    │
│   SrAgentAbility(零权限,exported 只为 aa 能启动)              │
│     └─ SrAgent.runJob → HAR SrEnhancer                           │
│          ImageSource → PixelMap → ImageSRAnalyzer.process()      │
│          → ISPResponse.pixelMap → ImagePacker → PNG / JPEG       │
└──────────────────────────────────────────────────────────────────┘

第一步:把图送进沙箱。 hdc file send -b 的 -b 把远端路径解释成 bundle 沙箱相对路径,不需要 run-as、不需要 root、不需要公共存储权限。图片被放进代理自己的 filesDir/sr/in/<job>.png。

注意文件名统一叫 <job>.png,但内容可以是 WebP、JPEG、HEIF——系统解码器看的是字节,不是扩展名。状态页里那张 IMG_20261113_213845.webp 是相册直接选的,走 hdc 时它也会被命名成 <job>.png。这个“名字和内容不一致”后面还会在输出侧出现一次,先记住。

第二步:启动 Ability。 hdc shell aa start -b <bundle> -a SrAgentAbility --ps job <id> 把任务 id 塞进 Want。代理在 onCreate / onNewWant 里读参数,识别完写结果、terminateSelf()。requestPermissions 是空数组——超分在内存 PixelMap 上完成,图片通过自己的沙箱进来,确实不需要任何权限。

第三步:等待结果信封。 hdc file recv -b 轮询 sr/out/<job>.json,直到文件出现或 agentTimeoutMs 到期。信封里有尺寸、倍数、耗时、mimeType、字节数;它出现的含义是“图也已经写好”。

第四步:把图拉回来。 hdc file recv -b 把 sr/out/<job>.out.png 拉到调用方指定的输出路径;没指定就按输入名和 mimeType 拼一个默认名。

为什么多这一步?因为结果是一张几 MB 的图。为什么先写图再写信封?这是整个协议里最容易被忽略的顺序问题:如果先写信封,宿主看到信封就去拉图,可能拉到一个还没写完的文件;反过来,图先落盘、信封后落盘,“信封存在”就等价于“两个文件都就绪”,宿主不需要再做一次存在性探测,也不需要靠 sleep 猜。这个顺序在 SrAgent 里是硬编码的,不是约定。

模型输入有明确的像素上限。 这是超分和 OCR 最大的区别:OCR 对输入尺寸没有这么明显的硬上限,超分模型会直接拒绝。实测边界如下(同一台 MOR-M1,直接喂 analyzer,不经过 HAR 的预缩):

输入尺寸结果
480×360(0.17 MP)通过,输出 1920×1440
1024×768(0.79 MP)通过
1280×960(1.23 MP)通过
1536×1152(1.77 MP)通过,输出 6144×4608
1600×1000(1.60 MP)通过,输出 6400×4000
1600×1152(1.84 MP)失败,401
1536×1536(2.36 MP)失败,401
3120×2080(6.49 MP)失败,401

这个 1.8 MP 的限制比较麻烦,但它是模型给的,库绕不过去,只能把大图先缩到上限以内。注意 1600×1000 能过、1600×1152 不能过,说明模型看的是总像素,长边只是其中一个约束;表里的输出是直接喂 analyzer 的 4× 结果。

HAR 最终采用的输入上限比模型边界更保守:1536 px / 1.75 MP。1600×1000 这种能过模型的图也会被缩到 1536×960,输出 6144×3840、3.84×。多缩一点换稳定,我不想让用户在 401 的边缘反复试探。inputWidth/Height 仍然报原图尺寸,scale 是原图到输出的真实倍数——所以大图会看到 1.97×、3.05×、3.84× 这种“不是 4”的数字。

输出编码按输出尺寸分两种。 模型的输出是 PixelMap,要编码才能过 hdc。这里有一个尺寸阈值:6000×4500 级别的 PNG 会让 ImagePacker 报 Packing failed,同尺寸 JPEG q95 稳定。HAR 现在的策略是 ≤4 MP 用 PNG(无损,方便对比),更大的用 JPEG q95;mimeType 如实上报,宿主按它决定落盘扩展名。沙箱里的中间文件固定叫 <job>.out.png,但内容可能是 JPEG——名字只是协议占位,别拿扩展名判断格式。这个细节我第一次看代码时也愣了一下。

回退是可观测的。 prefer 有三种语义:

prefer设备可用行为
auto(默认)是设备;运行中失败回退本机一次
auto否本机
device是设备;失败直接抛错
device否UNSUPPORTED
local—始终本机

“设备可用”的定义是:hdc 存在 + 有 target + bm dump -n 没有明确判定 bundle 缺失。注意最后一条:agentInstalled === null(探测不出来)也算健康,让真实任务去失败,而不是在探测阶段就拦住任务。

把这个链路和上一版 OCR 对照一下,会更清楚哪些地方变了:

electron-ohos-ocr 0.2.0electron-ohos-ai-vision 0.3.0
系统能力textRecognitionimageSuperResolution
hdc 步数3(推图 / 起 Ability / 拉 JSON)4(多一步拉图)
设备输出JSON 文本JSON 信封 + 二进制图
设备侧编码无PNG ≤4 MP / JPEG q95 >4 MP
本机回退tesseract.js自带 Lanczos3 + unsharp mask
设备要求API 12+API 26+,仅 Stage,模拟器不行
输入限制无明确像素上限约 1.8 MP,超了 401

4. 工程怎么搭:一份 npm 库 + 一份 HAR + 一个代理 HAP

先看整体结构。根目录是 npm 库,ohos/library 是 HAR,ohos/example 是代理 HAP,外加 example/ 的桌面工作台:

electron-ohos-ai-vision/
├─ src/                          # Electron 侧库(npm 包,零运行时依赖)
│  ├─ engine.ts                  # OhosSuperResolutionEngine:双后端选择、回退、IPC
│  ├─ backends/device-backend.ts # hdc 四步协议 + 冷启动预热
│  ├─ backends/local-backend.ts  # Lanczos3 本机后端
│  ├─ imaging/png.ts             # 自带 PNG 编解码(8-bit RGBA)
│  ├─ imaging/resample.ts        # Lanczos3 / 双三次 / 双线性 + 锐化
│  ├─ imaging/native.ts          # 可选 nativeImage 解码(JPEG/WebP/HEIF)
│  ├─ preload.ts                 # contextBridge 白名单(4 个 channel)
│  ├─ types.ts                   # SrResult 契约 + envelope 解析
│  ├─ index.ts                   # 公共出口
│  └─ cli.ts                     # electron-ohos-ai-vision-doctor
├─ test/                         # 6 个文件 92 项 Vitest
├─ example/                      # 「放大」Electron 工作台(前后对比滑块)
├─ ohos/
│  ├─ library/                   # HAR:SrEnhancer / SrResult / SrJson
│  └─ example/                   # 代理 HAP:SrAgentAbility / SrAgent / 状态页
├─ docs/                         # API / 架构 / 验证 / 截图
└─ dist/                         # tsc 构建产物(CommonJS + d.ts)

在这里插入图片描述

这次设计里最关键的决定,是把“能测”前置。92 个用例分在 6 个文件:

文件数量覆盖点
models.test.ts17结果校验顺序、倍数换算、线协议解析容错
png.test.ts15签名 / CRC、RGBA 往返、色彩类型 0/2/4/6、filter 0-4、调色板 / 16-bit / 隔行拒绝
resample.test.ts16Lanczos3 / 双三次 / 双线性核、预乘 alpha、尺寸上限、锐化、清晰度评分
local-backend.test.ts12端到端本机放大、输出命名、目录创建、错误分支
device-backend.test.ts20hdc 输出解析、四步协议 argv、信封解析、超时、冷沙箱、bundle 缺失
engine.test.ts12后端选择矩阵、自动回退、显式 prefer、IPC 通道名

覆盖率主要来自把外部依赖做成注入点:

  • DeviceSuperResolutionBackend 接受 spawnFn 和 fileOps,测试里用一个假 ChildProcess 就能把 file send → aa start → file recv → file recv 整条协议跑完,不需要设备、不需要 Electron;
  • LocalSuperResolutionBackend 只依赖自带的编解码和重采样,fs 之外没有外部依赖;
  • PNG 测试用手工拼的 chunk 覆盖坏签名、截断、调色板、16-bit、隔行,外加 CRC 参考值;
  • 引擎测试把两个后端的行为缩成几个 promise,专门覆盖“什么时候该回退、什么时候不该”。

HAR 和代理分开也是有意的:

  • ohos/library 不认识 hdc、不认识 job,只提供“给我一张图,我还你 SrRun”;
  • ohos/example 只处理应用沙箱、任务 id、信封和生命周期;
  • 第三方鸿蒙应用可以直接依赖 HAR,不需要安装代理。

两侧 API 一一对应:

Electron 版鸿蒙侧 HAR
engine.enhanceFile(path, options)SrEnhancer.enhanceBytes(bytes, source) / enhanceUri(uri)
engine.enhanceBytes(bytes, options)SrEnhancer.enhancePixelMap(pixelMap, source, preview)
SrResult(interface)SrResult(class,同字段、同校验顺序)
parseAgentEnvelope(raw, job)resultToWire(result) / resultToJson(result)
getBackendInfo()无对应 API:状态页用 AppStorage 展示

Electron 侧的完整链路长这样:

渲染进程                                主进程
─────────                              ────────
drop / 选择图片
  └─ window.exampleSr.imageInfo() ──ipc──▶ nativeImage → data URL(长边 1600)
  └─ window.electronOhosSuperResolution.enhanceFile(path, { scale })
                                          └─ OhosSuperResolutionEngine.enhanceFile()
                                               ├─ resolveBackend():device → local
                                               ├─ device:spawn hdc ×4 / local:Lanczos3
                                               └─ 返回 SrResult(尺寸 / 倍数 / 耗时 / 输出路径)
  └─ 渲染对比滑块、真实尺寸、保存按钮

对使用方来说,最终看到的 API 是这样的:

// 主进程
import {
  OhosSuperResolutionEngine,
  registerSuperResolutionIpcHandlers,
} from 'electron-ohos-ai-vision';

const sr = new OhosSuperResolutionEngine({
  // macOS 上 DevEco Studio 自带的 hdc:
  hdcPath: 'hdc',
});
registerSuperResolutionIpcHandlers(sr);

// preload
import 'electron-ohos-ai-vision/preload';

// 渲染进程
const info = await window.electronOhosSuperResolution.getBackendInfo();
const result = await window.electronOhosSuperResolution.enhanceFile('/path/to/photo.webp', {
  scale: 2, // 只对本机后端生效;设备模型固定 4×
});
console.log(result.outputPath, result.width, result.height, result.scale);

OhosSuperResolutionEngine 把选项原样交给两个后端;registerSuperResolutionIpcHandlers 只注册四个 channel,配套 preload 只暴露 window.electronOhosSuperResolution,渲染进程看不到 ipcRenderer。示例的 BrowserWindow 用 contextIsolation: true、nodeIntegration: false;因为示例 preload 直接 require 库模块,sandbox 暂时是 false,不需要 Node 能力时可以改成纯 IPC 转发并打开 sandbox: true。

还有一个容易被忽略的点:这个包的 dependencies 是空的。tesseract.js、sharp、canvas 都没有,PNG 编解码和 Lanczos3 都是仓库里的纯 TypeScript。npm install 不会触发原生编译,CI 和没有开发机的人都能跑——这对一个“桌面兜底”功能来说比性能更重要。

5. 把代码讲透

5.1 引擎:auto 的边界条件

整个引擎最核心的两段逻辑很短。第一段是“这次该用谁”:

// src/engine.ts - resolveBackend()
private async resolveBackend(): Promise<SuperResolutionBackend | 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 - enhanceFileWithFallback()
const backend = await this.pickBackend();
try {
  return await backend.enhanceFile(imagePath, options);
} catch (error) {
  if (backend.kind === SrBackendKind.Device && this.prefer !== 'device') {
    const localOk = await this.local.isAvailable().catch(() => false);
    if (localOk) {
      try {
        return await this.local.enhanceFile(imagePath, options);
      } catch (fallbackError) {
        throw decorate(SrBackendKind.Local, fallbackError);
      }
    }
  }
  throw decorate(backend.kind, error);
}

几个取舍值得说明:

prefer 是三种语义,不只是“优先级”。 auto 允许回退;device 和 local 是严格模式。显式选了 device 但设备不可用,就应该报 UNSUPPORTED,而不是悄悄用本机放大再告诉你“成功了”。调用方选严格模式,通常是因为业务上不能接受“换了个算法”。

getBackendInfo() 和 SrResult.backend 要分开暴露。 getBackendInfo() 返回的是“下一次 auto 会用谁”,它可能说 device,但这次运行失败了、回退到了 local。界面同时看这两个字段才不会误判。

agentInstalled === null 不等于失败。 bm dump 的输出格式在不同版本上会变,有时只能判断“没明确说缺失”。把 null 当健康,让真实任务去失败,比在启动时误报“Agent 未安装”要好。

dispose() 是空实现。 两个后端都没有需要释放的原生资源(没有 worker、没有长连接),除了设备后端那个预热 promise 之外没有缓存;保留这个钩子只是为了让宿主在 will-quit 里有个统一的调用点,以后加缓存不用改调用方。

IPC 部分没有额外逻辑,四个 channel,参数先校验再过桥:

// src/engine.ts - registerSuperResolutionIpcHandlers()(节选)
ipcMain.handle(SR_IPC_CHANNELS.enhanceFile, async (_event, imagePath: unknown, options = {}) => {
  if (typeof imagePath !== 'string' || imagePath.trim().length === 0) {
    throw new Error('enhanceFile requires a non-empty image path string');
  }
  return engine.enhanceFile(imagePath, options);
});

5.2 四步协议:job id 贯穿全程,信封是完成信号

设备后端最底层是一个 promise 化的 spawn 包装,和 OCR 版几乎一样:拼 argv、接超时、把 ENOENT 翻译成 HDC_NOT_FOUND。这里不重复贴,直接看四步本身:

// src/backends/device-backend.ts - enhanceFile()(节选)
const jobId = newJobId();

await this.pushImage(imagePath, jobId);
await this.startAgent(jobId);
const envelope = await this.collectResult(jobId);

if (!envelope.ok) {
  const code = envelope.error.code === 'SR_SERVICE_ERROR' ? 'SR_ERROR' : 'AGENT_ERROR';
  throw new SrError(code, `Device super-resolution failed: ${envelope.error.message}`);
}

const outputPath =
  options.outputPath ??
  path.join(
    this.outputDir ?? path.dirname(imagePath),
    `${stripExtension(path.basename(imagePath))}.x${formatScale(envelope.result.scale)}` +
      extensionForMime(envelope.result.mimeType),
  );
await this.pullOutput(jobId, outputPath);

newJobId() 还是 randomUUID().replace(/-/g, '').slice(0, 16),输入文件、输出图、信封、Want 参数全部以它命名。JOB_ID_PATTERN = /^[0-9a-z-]{8,64}$/ 在 startAgent 里再校验一次。所有 hdc 参数走 spawn 的 argv 数组,没有 shell 字符串——这一点在超分里更重要,因为输出路径是调用方给的,可能带空格、中文、引号。

第三步的轮询:

// src/backends/device-backend.ts - collectResult()(节选)
const deadline = Date.now() + this.agentTimeoutMs;
let lastError = '';
for (;;) {
  const run = await this.runner.run(['file', 'recv', '-b', this.agentBundle, remote, localPath], 15000);
  if (run.code === 0 && this.fileOps.existsSync(localPath)) {
    break;
  }
  lastError = (run.stderr || run.stdout).trim();
  if (Date.now() >= deadline) {
    throw new SrError(
      'AGENT_TIMEOUT',
      `Agent did not write ${remote} within ${this.agentTimeoutMs} ms (last hdc error: ${lastError})`,
    );
  }
  await sleep(this.pollIntervalMs);
}

agentTimeoutMs 默认 120 秒,比 OCR 版的 60 秒长。原因很实际:大图预缩后模型输入仍有 1.5~1.75 MP,推理加编码要一秒多,编码和写入又要时间,hdc 拉图还受链路影响。超时太短会把正常的慢任务误判成失败。

第四步 pullOutput 会重试,最多 30 秒:

// src/backends/device-backend.ts - pullOutput()(节选)
const deadline = Date.now() + Math.min(this.agentTimeoutMs, 30000);
for (;;) {
  const run = await this.guard('file recv (image)', () =>
    this.runner.run(['file', 'recv', '-b', this.agentBundle, remote, outputPath], this.commandTimeoutMs),
  );
  if (run.code === 0 && this.fileOps.existsSync(outputPath)) {
    return;
  }
  if (Date.now() >= deadline) {
    throw new SrError('AGENT_ERROR', `Agent reported success but ${remote} could not be pulled: ...`);
  }
  await sleep(this.pollIntervalMs);
}

为什么信封已经出现还要重试?因为信封只保证“Agent 写完了”,不保证 hdc 的文件同步已经对宿主可见。实际上很少触发,但重试一次比给用户报一个假的“成功”便宜。

默认输出名的扩展名由 mimeType 决定,这是协议里少见的“内容优先于文件名”:

// src/backends/device-backend.ts - extensionForMime()
function extensionForMime(mimeType: string): string {
  if (mimeType === 'image/jpeg' || mimeType === 'image/jpg') {
    return '.jpg';
  }
  if (mimeType === 'image/webp') {
    return '.webp';
  }
  return '.png';
}

所以同一张输入,设备返回 JPEG 时默认输出是 photo.x4.jpg,返回 PNG 时是 photo.x4.png。scale 用实际输出宽度除以输入宽度算,不信任调用方传的值。顺带一提,默认文件名里的倍数是给本机 2/3/4 设计的,设备返回 1.97 时会被写成一位小数(photo.x2.0.jpg);真实倍数以 SrResult.scale 为准,文件名只是个提示。

冷启动那段和 OCR 版是同一套:应用没跑过时沙箱里没有 sr/in、sr/out,hdc file send -b 会报 Invalid bundle name 或 No such file or directory。后端会发一次 throwaway 的 aa start(job id 加 boot 前缀),让 Agent 建目录、写一个输入缺失的错误信封,确认目录存在后重试原来的 file send。warmupSandbox() 用一个 promise 缓存,并发任务只预热一次;失败时清空缓存,允许下一次重试。

5.3 鸿蒙侧:ImageSRAnalyzer 与 1.8 MP 的输入上限

HAR 里的核心是 SrEnhancer。它先算这张图该以多大尺寸进模型,再调模型:

// ohos/library/src/main/ets/sr/ImageSuperResolution.ets - modelInputSize()
static modelInputSize(width: number, height: number): Size {
  if (width <= 0 || height <= 0) {
    return { width: width, height: height };
  }
  const byEdge: number = MODEL_MAX_EDGE / Math.max(width, height);
  const byPixels: number = Math.sqrt(MODEL_MAX_PIXELS / (width * height));
  const factor: number = Math.min(1, byEdge, byPixels);
  if (factor >= 1) {
    return { width: width, height: height };
  }
  // Floor (not round) and back off by one pixel when needed: a single pixel
  // over the box is enough for the analyzer to answer 401.
  let scaledWidth: number = Math.max(1, Math.floor(width * factor));
  let scaledHeight: number = Math.max(1, Math.floor(height * factor));
  while (scaledWidth * scaledHeight > MODEL_MAX_PIXELS) {
    if (scaledWidth >= scaledHeight) {
      scaledWidth -= 1;
    } else {
      scaledHeight -= 1;
    }
  }
  return { width: scaledWidth, height: scaledHeight };
}

MODEL_MAX_EDGE = 1536、MODEL_MAX_PIXELS = 1750000。为什么用 floor 而不是 round,为什么还要 while 再减?因为 401 是参数检查失败,超一个像素也算超。这个细节看起来抠,实际是拿 1600×1152 撞出来的。

拿到 modelSize 后,解码时用 desiredSize 让系统直接缩到上限以内,而不是先解全尺寸再自己缩:

// ohos/library/src/main/ets/sr/ImageSuperResolution.ets - enhanceBytes()(节选)
imageSource = image.createImageSource(SrEnhancer.toArrayBuffer(bytes));
const sourceInfo: image.ImageInfo = await imageSource.getImageInfo();
const modelSize: Size =
  SrEnhancer.modelInputSize(sourceInfo.size.width, sourceInfo.size.height);
const options: image.DecodingOptions = {};
if (modelSize.width !== sourceInfo.size.width ||
  modelSize.height !== sourceInfo.size.height) {
  options.desiredSize = { width: modelSize.width, height: modelSize.height };
}
pixelMap = await imageSource.createPixelMap(options);
if (options.desiredSize !== undefined) {
  modelPreview = await SrEnhancer.encode(pixelMap, 'image/png', 100);
}
return await SrEnhancer.run(
  pixelMap, source, bytes, sourceInfo.size.width, sourceInfo.size.height, modelPreview,
);

modelPreview 是给状态页做 100% 对比用的:如果图被预缩过,原图字节和真正喂给模型的图不是同一张;没有这个字段,状态页就只能拿原图去比,左侧的“模型输入”会不对。这个字段后来确实用上了,第 5.5 节的裁剪代码就靠它。

推理在 analyze 里,分析器一次一建、finally 销毁,PixelMap 和 Packer 也都在 finally 里释放:

// ohos/library/src/main/ets/sr/ImageSuperResolution.ets - analyze()(节选)
const analyzer: imageSuperResolution.ImageSRAnalyzer =
  await imageSuperResolution.ImageSRAnalyzer.create();
try {
  const inputData: visionBase.ImageData = { pixelMap: pixelMap };
  const request: visionBase.Request = { inputData: inputData };
  const response = await analyzer.process(request);
  const outputPixelMap: image.PixelMap = response.pixelMap;
  try {
    const info: image.ImageInfo = await outputPixelMap.getImageInfo();
    const packer: image.ImagePacker = image.createImagePacker();
    try {
      const pixels: number = info.size.width * info.size.height;
      const lossless: boolean = pixels <= 4000000;
      const packing: image.PackingOption = lossless
        ? { format: 'image/png', quality: 100 }
        : { format: 'image/jpeg', quality: 95 };
      const buffer: ArrayBuffer = await packer.packing(outputPixelMap, packing);
      return {
        output: new Uint8Array(buffer),
        width: info.size.width,
        height: info.size.height,
        mimeType: lossless ? 'image/png' : 'image/jpeg',
      };
    } finally {
      await packer.release();
    }
  } finally {
    await outputPixelMap.release();
  }
} finally {
  await analyzer.destroy();
}

写 ArkTS 的 native 资源时,finally 不能省。ImageSRAnalyzer.create() 会占一个 NPU 会话,destroy() 必须走 finally——任务失败、用户取消都要走到这里;进程被强杀没法保证,但那种情况下 NPU 会话随进程结束。outputPixelMap 和 packer 也是同样的道理。ArkTS 没有 GC 兜底这种原生资源,写起来确实啰嗦,但漏一次就是一次泄漏。

代理本身只做流程封装。SrAgent.runJob 负责沙箱路径、输入清理和信封:

// ohos/example/src/main/ets/sr/SrAgent.ets - runJob()(节选)
const filesDir: string = context.filesDir;
const inDir: string = `${filesDir}/sr/in`;
const outDir: string = `${filesDir}/sr/out`;
const inPath: string = `${inDir}/${jobId}.png`;
const imagePath: string = `${outDir}/${jobId}.out.png`;
const outPath: string = `${outDir}/${jobId}.json`;

await SrAgent.ensureDir(inDir);
await SrAgent.ensureDir(outDir);
SrAgent.pruneOutputs(outDir).catch((): void => {});

// 输入缺失分支略:先写 AGENT_INPUT_MISSING 信封再抛
const bytes: Uint8Array = SrAgent.readImage(inPath);
try {
  const run: SrRun = await SrEnhancer.enhanceBytes(bytes, `${jobId}.png`);
  SrAgent.writeBinary(imagePath, run.output);          // 先写图
  await SrAgent.writeText(outPath, SrAgent.okEnvelope(jobId, run.result)); // 再写信封
} catch (error) {
  const message: string = srErrorMessage(error as Object);
  await SrAgent.writeText(outPath, SrAgent.errorEnvelope(jobId, 'SR_SERVICE_ERROR', message));
  throw new Error(message);
} finally {
  await SrAgent.removeFile(inPath);
}

Ability 只处理 Want 和生命周期:冷启动 onCreate 记下 job,onWindowStageCreate 里 loadContent('pages/Index') 完成后再执行;热启动 onNewWant 直接复用实例。任务结束(成功或失败)都 terminateSelf(),设备上不会留下常驻进程。

module.json5 里没有声明任何权限,exported: true 只为了让 aa 能启动 Ability:

{
  "module": {
    "name": "entry",
    "mainElement": "SrAgentAbility",
    "deviceTypes": ["phone", "tablet", "2in1"],
    "requestPermissions": [],
    "abilities": [
      {
        "name": "SrAgentAbility",
        "srcEntry": "./ets/entryability/SrAgentAbility.ets",
        "exported": true
      }
    ]
  }
}

5.4 本机兜底:Lanczos3、预乘 alpha 与自带 PNG

本机后端的定位要说清楚:它是软件放大,不是 AI。结果 id 是 lanczos3-local,做的是可分离卷积 + unsharp mask,不加载任何模型。它用于在没有设备时仍能出图,效果不等同于 NPU。

重采样是两趟卷积。先把 RGBA 预乘,再做水平和垂直两趟:

// src/imaging/resample.ts - resize()(节选)
const sw = image.width;
const sh = image.height;
const src = image.data;

const premul = new Float32Array(sw * sh * 4);
for (let i = 0; i < sw * sh; i += 1) {
  const a = src[i * 4 + 3] / 255;
  premul[i * 4] = src[i * 4] * a;
  premul[i * 4 + 1] = src[i * 4 + 1] * a;
  premul[i * 4 + 2] = src[i * 4 + 2] * a;
  premul[i * 4 + 3] = src[i * 4 + 3];
}

// 水平方向
const horizontal = new Float32Array(width * sh * 4);
const xTaps = buildTaps(sw, width, kernel);
for (let y = 0; y < sh; y += 1) {
  for (let x = 0; x < width; x += 1) {
    let r = 0, g = 0, b = 0, a = 0;
    for (let k = 0; k < xTaps.count[x]; k += 1) {
      const weight = xTaps.weights[x][k];
      const offset = (y * sw + xTaps.start[x] + k) * 4;
      r += premul[offset] * weight;
      g += premul[offset + 1] * weight;
      b += premul[offset + 2] * weight;
      a += premul[offset + 3] * weight;
    }
    const out = (y * width + x) * 4;
    horizontal[out] = r;
    horizontal[out + 1] = g;
    horizontal[out + 2] = b;
    horizontal[out + 3] = a;
  }
}

垂直方向同理,最后再反预乘:

const alpha = Math.max(0, Math.min(255, Math.round(a)));
if (alpha === 0) {
  output[out] = 0;
  output[out + 1] = 0;
  output[out + 2] = 0;
  output[out + 3] = 0;
} else {
  const unpremul = 255 / alpha;
  output[out] = clampByte(r * unpremul);
  output[out + 1] = clampByte(g * unpremul);
  output[out + 2] = clampByte(b * unpremul);
  output[out + 3] = alpha;
}

为什么非要预乘?不预乘的话,透明像素的 RGB 可能是任意值(很多截图工具会留 0 或白),卷积会把它们的颜色渗到边缘上,放大后的透明边缘会有一圈脏色。这个问题在纯色背景上看不出来,在贴纸、图标、带 alpha 的 PNG 上很明显。

taps 的预计算也不复杂,但有两个细节:放大时核半径保持自然大小,缩小时把核按比例拉宽充当低通,避免混叠;权重最后要归一化,总和为 1。

// src/imaging/resample.ts - buildTaps()(节选)
const scale = dstSize / srcSize;
const radius = KERNEL_RADIUS[kernel];        // lanczos3 = 3
const filterScale = scale < 1 ? scale : 1;
const support = radius / filterScale;
for (let i = 0; i < dstSize; i += 1) {
  const center = (i + 0.5) / scale - 0.5;
  const first = Math.max(0, Math.ceil(center - support));
  const last = Math.min(srcSize - 1, Math.floor(center + support));
  // ... 计算窗口内每个源像素的权重,累加后归一化
}

锐化是 3×3 的 box blur 加回差值,amount 默认 0.35。它不改变尺寸,只在卷积结果上增加一点局部对比,让 Lanczos 的放大看起来没那么“软”。它不会补出原本不存在的笔画和细节——这一点和设备的 AI 模型不同。

PNG 编解码是另一块自己写的。解码支持 8-bit 色彩类型 0/2/4/6、filter 0-4、多 IDAT;调色板、16-bit、隔行直接报 UNSUPPORTED_FORMAT,不做隐式转换——16-bit 转 8-bit 会丢精度,隔行要走 Adam7,调色板还要处理 PLTE/tRNS,与其猜,不如明确拒绝。解码时跳过 CRC 校验(编码时认真算),输入来自本地文件或设备输出,inflate 和长度校验已经能兜住明显的损坏;这是有意的取舍。

解码的 filter 还原是标准的五分支,Paeth 预测器照抄 PNG 规范:

// src/imaging/png.ts - unfilter()(节选)
switch (filter) {
  case 0:
    decoded = value;
    break;
  case 1:
    decoded = value + left;
    break;
  case 2:
    decoded = value + up;
    break;
  case 3:
    decoded = value + Math.floor((left + up) / 2);
    break;
  case 4:
    decoded = value + paeth(left, up, upLeft);
    break;
  default:
    throw new SrError('UNSUPPORTED_FORMAT', `Unsupported PNG filter type ${filter}`);
}
out[rowStart + x] = decoded & 0xff;

编码则逐行试五种 filter,选残差绝对值之和最小的那个,再 deflate(9):

// src/imaging/png.ts - encodePng()(节选)
for (let y = 0; y < height; y += 1) {
  const row = data.subarray(y * stride, (y + 1) * stride);
  const previous = y === 0 ? zeroRow : data.subarray((y - 1) * stride, y * stride);
  let bestFilter = 0;
  let bestCost = Number.POSITIVE_INFINITY;
  let bestRow: Uint8Array | null = null;
  for (let filter = 0; filter <= 4; filter += 1) {
    const candidate = applyFilter(filter, row, previous, 4);
    const cost = filterCost(candidate);
    if (cost < bestCost) {
      bestCost = cost;
      bestFilter = filter;
      bestRow = candidate;
    }
  }
  const offset = y * (stride + 1);
  raw[offset] = bestFilter;
  raw.set(bestRow ?? row, offset + 1);
}
const idat = new Uint8Array(zlib.deflateSync(Buffer.from(raw), { level: 9 }));

这个启发式和 libpng 给照片用的策略基本一致。它不会把 PNG 压到 WebP 那么小,但对“放大后的图”这种高频内容已经够用,而且没有依赖。

输入不是 PNG 时,本机后端会尝试 nativeImage。这里有一个纯 Node 环境的坑:require('electron') 在 Electron 主进程里返回 API 对象,在普通 Node(比如 vitest)里返回的是 Electron 可执行文件的路径字符串。所以不能直接 .nativeImage,要先判断类型:

// src/imaging/native.ts - electronNativeImage()(节选)
const electron = require('electron') as unknown;
if (electron !== null && typeof electron === 'object') {
  const candidate = (electron as { nativeImage?: unknown }).nativeImage;
  if (candidate !== null && typeof candidate === 'object' &&
      typeof (candidate as NativeImageModule).createFromBuffer === 'function') {
    return candidate as NativeImageModule;
  }
}
return null;

nativeImage.toBitmap() 返回的是 BGRA,不是 RGBA,红色和蓝色要换一下:

const bitmap = image.toBitmap(); // BGRA, one byte per channel
const rgba = new Uint8Array(width * height * 4);
for (let i = 0; i < width * height; i += 1) {
  const offset = i * 4;
  rgba[offset] = bitmap[offset + 2];     // B → R
  rgba[offset + 1] = bitmap[offset + 1];
  rgba[offset + 2] = bitmap[offset];     // R → B
  rgba[offset + 3] = bitmap[offset + 3];
}

如果没有 Electron、输入又不是 PNG,decodeImage 会抛一个明确的 UNSUPPORTED_FORMAT,并在消息里告诉调用方“安装 Electron 示例,或先把图转成 PNG”,而不是给一个空白结果。

安全上限也不能少:单边 16384 px、总计 64 MP,超出报 OUTPUT_TOO_LARGE。但别真拿 64 MP 去试——预乘缓冲按 4 通道 Float32 算就是 1 GB 量级,再大就会直接 OOM。

5.5 契约与两个界面:SrResult、信封和 100% 对比

两侧共享同一份 SrResult 契约。TypeScript 侧的校验顺序是固定的:

// src/types.ts - createSrResult()
export function createSrResult(init: SrResultInit): SrResult {
  requireCondition(!isBlank(init.id), 'Result id must not be blank');
  requireCondition(
    isPositiveInt(init.inputWidth) &&
      isPositiveInt(init.inputHeight) &&
      isPositiveInt(init.width) &&
      isPositiveInt(init.height),
    'Dimensions must be positive integers',
  );
  requireCondition(Number.isFinite(init.scale) && init.scale > 0, 'Scale must be positive');
  requireCondition(Number.isFinite(init.durationMs) && init.durationMs >= 0, 'Duration must be non-negative');
  requireCondition(!isBlank(init.outputPath), 'Output path must not be blank');
  return {
    id: init.id,
    source: init.source,
    backend: init.backend,
    inputWidth: init.inputWidth,
    inputHeight: init.inputHeight,
    width: init.width,
    height: init.height,
    scale: init.scale,
    durationMs: Math.round(init.durationMs),
    mimeType: init.mimeType,
    byteLength: init.byteLength,
    outputPath: init.outputPath,
  };
}

ArkTS 侧的 SrResult 构造函数按同样的顺序校验,错误文本一字不差:

// ohos/library/src/main/ets/sr/SrModels.ets - SrResult 构造函数(节选)
if (id.trim().length === 0) {
  throw new Error('Result id must not be blank');
}
if (!SrResult.isPositiveInt(inputWidth) || !SrResult.isPositiveInt(inputHeight) ||
  !SrResult.isPositiveInt(width) || !SrResult.isPositiveInt(height)) {
  throw new Error('Dimensions must be positive integers');
}
if (!(scale > 0)) {
  throw new Error('Scale must be positive');
}
if (!(durationMs >= 0)) {
  throw new Error('Duration must be non-negative');
}

JSON 边界不依赖类的序列化,而是手写:

// ohos/library/src/main/ets/sr/SrJson.ets - resultToWire()
const wire: Record<string, Object> = {
  'id': result.id,
  'source': result.source,
  'inputWidth': result.inputWidth,
  'inputHeight': result.inputHeight,
  'width': result.width,
  'height': result.height,
  'scale': result.scale,
  'durationMs': result.durationMs,
  'mimeType': result.mimeType,
  'byteLength': result.byteLength,
};

信封的成功和失败两种形态如下:

{
  "ok": true,
  "job": "6f0d2e1a9b3c4d5e",
  "backend": "image-sr",
  "result": {
    "id": "vision-sr-on-device",
    "source": "6f0d2e1a9b3c4d5e.png",
    "inputWidth": 480,
    "inputHeight": 360,
    "width": 1920,
    "height": 1440,
    "scale": 4,
    "durationMs": 251,
    "mimeType": "image/jpeg",
    "byteLength": 405545
  }
}

这个成功示例来自架构文档,当时设备统一输出 JPEG;现在 ≤4 MP 会走 PNG,mimeType 会变成 image/png,字段和顺序不变。

{ "ok": false, "job": "<job>", "error": { "code": "SR_SERVICE_ERROR", "message": "The parameter check failed. (code 401)" } }

宿主用 parseAgentEnvelope 解析信封,再由设备后端把 SR_SERVICE_ERROR 映射成 SR_ERROR、其它错误码映射成 AGENT_ERROR;成功则用 srResultFromWire 逐字段容错。scale 缺失时用 width / inputWidth 兜底,mimeType 缺失时默认 image/jpeg,durationMs 非法时归零——这些容错的目的是让一个字段缺失不至于让整次任务作废。

状态页里值得单独讲的是 100% 对比。它没有把两张图整体缩到面板大小再比——那样差异会被缩放抹平。它裁同一块区域,按原生尺寸解码:

// ohos/example/src/main/ets/pages/Index.ets - runPickerTest()(节选)
const outW: number = run.outputWidth;
const outH: number = run.outputHeight;
const cropW: number = Math.min(460, outW);
const cropH: number = Math.min(345, outH);
const ox: number = Math.floor((outW - cropW) / 2);
const oy: number = Math.floor((outH - cropH) / 2);
const factor: number = outW / run.modelWidth;
const inW: number = Math.max(1, Math.round(cropW / factor));
const inH: number = Math.max(1, Math.round(cropH / factor));
const inX: number = Math.min(Math.max(0, run.modelWidth - inW), Math.floor(ox / factor));
const inY: number = Math.min(Math.max(0, run.modelHeight - inH), Math.floor(oy / factor));

const inputCrop: image.PixelMap =
  await SrEnhancer.decodeRegion(run.modelPreview, inX, inY, inW, inH);
await inputCrop.scale(cropW / inW, cropH / inH);
detailInput = inputCrop;
detailOutput = await SrEnhancer.decodeRegion(run.output, ox, oy, cropW, cropH);

factor = outW / modelWidth 通常是 4。输入侧的裁剪区域是输出裁剪区域除以 4,所以一张 460×345 的输出细节对应 115×86 左右的模型输入;UI 再把这个 115×86 的小图 scale 到 460×345,就是你看到的“模型输入按 4× 插值”的方块感。右边直接裁输出的原生像素,是模型生成的结果。两边放在同样的 300×225 盒子里,才能公平对比。

这段代码还说明了一个 ArkUI 的坑:@Builder 的参数是按值传递的,PixelMap 到达时不会刷新。所以状态页里那两块对比图是内联写的,不是抽成 @Builder:

// 注释原文:Inline (not @Builder): ArkUI @Builder parameters are by value and
// would not refresh when the pixel maps arrive.
Column({ space: 0 }) {
  if (this.inputPixels !== undefined) {
    Image(this.inputPixels)
      .width('100%')
      .layoutWeight(1)
      .objectFit(ImageFit.Contain)
  } else {
    this.emptyFrame()
  }
}

桌面侧的对比滑块是另一套实现。它不需要裁图,直接把结果图和原图叠在同一个盒子里,用 clip-path 切左图:

.compare img { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: contain; }
.compare .before { clip-path: inset(0 calc(100% - var(--split, 50%)) 0 0); }
// example/src/renderer/renderer.js - 拖动分割线(节选)
dom.compare.addEventListener('pointerdown', (event) => {
  dragging = true;
  dom.compare.setPointerCapture(event.pointerId);
  setSplit(pointerToPercent(event));
});
dom.compare.addEventListener('pointermove', (event) => {
  if (dragging) setSplit(pointerToPercent(event));
});

function setSplit(percent) {
  const clamped = Math.max(4, Math.min(96, percent));
  state.split = clamped;
  dom.compare.style.setProperty('--split', `${clamped}%`);
  dom.divider.setAttribute('aria-valuenow', String(Math.round(clamped)));
}

两张图必须用同样的 object-fit: contain 和同样的盒子尺寸,否则滑块位置和像素位置对不上。这看似是 CSS 细节,但它决定了对比是否成立:用户在拖滑块时看到的必须是同一块区域,不能是两张各自缩放的图。

preload 这边还是四个 channel 的白名单,参数在过桥前校验:

// src/preload.ts(节选)
const ALLOWED_CHANNELS: readonly string[] = [
  SR_IPC_CHANNELS.isAvailable,
  SR_IPC_CHANNELS.backendInfo,
  SR_IPC_CHANNELS.enhanceFile,
  SR_IPC_CHANNELS.enhanceBytes,
];

async function invoke(channel: string, ...args: unknown[]): Promise<unknown> {
  assertChannel(channel);
  if (channel === SR_IPC_CHANNELS.enhanceFile) {
    const [imagePath] = args;
    if (typeof imagePath !== 'string' || imagePath.trim().length === 0) {
      throw new Error('enhanceFile requires a non-empty image path string');
    }
  }
  return ipcRenderer.invoke(channel, ...args);
}

错误码都收在 SrError.code 里;跨 IPC 之后自定义属性可能丢,示例从 message 末尾的 (CODE) 把它取回来:

code场景
HDC_NOT_FOUND找不到 hdc
NO_DEVICEhdc 可用但没有设备
AGENT_NOT_INSTALLED设备上没有 Agent HAP
AGENT_TIMEOUT等结果文件超时
AGENT_ERRORAgent 返回失败信封(如输入丢失)
SR_ERROR系统超分 / 本机管线失败(设备侧原样返回 BusinessError 文本,如 401)
INVALID_INPUT空字节、文件缺失、非法倍数
UNSUPPORTED_FORMAT本机解码不了(非 PNG 且无 Electron 解码能力)
OUTPUT_TOO_LARGE输出超过 16384 px 边或 64 MP
BACKEND_FAILED后端异常崩溃
UNSUPPORTED两个后端都不可用

6. 我踩过的坑(真实报错与排查记录)

这一节是坑清单,以下每一条都来自这次开发和真机验证的排查记录。

坑一:401 不是图片坏了,是输入超了 1.8 MP。 第一次拿 3120×2080 的桌面截图直接跑,设备返回 The parameter check failed. (code 401)。我一开始以为是格式问题,把 WebP 换成 JPEG、把 JPEG 换成 PNG,还是 401;又怀疑是权限,翻了半天文档才发现是输入尺寸。逐档试出来的边界:1536×1152(1.77 MP)能过,1600×1152(1.84 MP)就挂;1600×1000(1.60 MP)又能过。所以上限约为 1.8 MP,长边 1536 只是约束之一。修复:SrEnhancer 在解码前算 modelInputSize,按长边 1536、总像素 1.75 M 取更严的那个,floor 后再用 while 减到不超;解码时用 desiredSize 直接缩放。先量出边界,再决定怎么改。

坑二:4× 指的是模型输入的 4×,原图倍数要按输入尺寸换算。 3120×2080 跑出来是 6144×4096,宽度看着很大,一算只有 1.97×;因为原图先被缩到 1536×1024 才进模型。如果接口里写“保证 4 倍”,用户会以为你偷工减料。修复:SrResult.scale = width / inputWidth,记录原图到输出的真实倍数;状态页显示 4.00× 只在输入没被预缩时出现,大图会显示 1.97×。设备后端也不接受 scale 参数,模型不支持倍数参数。对外承诺的倍数必须是实际倍数,不能是请求倍数。

坑三:PNG 编码 6000×4500 会 Packing failed。 模型推理成功,ImagePacker 编 PNG 却失败;同样的结果换 JPEG q95 就稳定。最早的做法是“全都用 JPEG”,后来发现小图用 PNG 无损更适合做前后对比,于是改成 ≤4 MP 用 PNG、更大的用 JPEG q95。mimeType 一直如实上报,所以宿主不需要知道这个阈值,按 mimeType 决定默认扩展名就行。编码器在尺寸上有失败阈值,不能只拿小图测试;输出格式由结果里的 mimeType 决定,调用方不用猜。

坑四:图还没写完,信封先到。 如果 Agent 先写 <job>.json 再写 <job>.out.png,宿主看到信封就去拉图,可能拉到一个还没写完的文件,或者干脆拉不到。现在的顺序是反的:图先落盘,信封后落盘;“信封存在”就等价于“两个文件都就绪”。pullOutput 还留了最多 30 秒的重试,防止 hdc 的文件同步慢半拍。两个文件的完成信号,要写在最后一个文件之后。

坑五:冷沙箱的 Invalid bundle name。 代理没跑过时,sr/in、sr/out 还不存在,hdc file send -b 会报 Invalid bundle name;bundle 换对之后又报 No such file or directory。修复:识别这两类输出,发一次 throwaway 的 aa start 预热(job id 加 boot 前缀),轮询到 bootstrap 信封确认目录建好,再重试 file send。warmupSandbox() 用 promise 缓存,并发任务只预热一次。-b 的路径要求沙箱已存在,而沙箱里的目录是应用自己建的。

坑六:bundle 改名后旧签名不匹配。 0.3.0 把 bundle 从 com.ohos.electronocr.agent 改成 com.ohos.electronvision.agent,直接构建会报:

The bundleName in app.json5/hvigorfile.ts does not match the bundleName in the generated SigningConfigs.

调试签名材料是绑定 bundle 的,换名字就要在 DevEco Studio 的 Signing Configs 里重新生成一次。仓库不提交签名材料,build-profile.json5 里也不含 signingConfigs。签名 profile 不只是密钥,它还是 bundle 身份的一部分。

坑七:纯 Node 里 require('electron') 返回路径字符串。 本机后端在没有 Electron 的 Node 进程(vitest、CI)里也要能跑。require('electron') 在 Electron 主进程里返回 API 对象,在普通 Node 里返回的是可执行文件路径字符串,直接 .nativeImage 会炸。修复:先判断 typeof electron === 'object',再检查 createFromBuffer 是不是函数;没有就返回 null,让 decodeImage 走明确的 UNSUPPORTED_FORMAT。可选的原生能力必须能降级,不能把“没有 Electron”变成异常。

坑八:透明边缘会串色。 直接在直通 alpha 上做卷积,透明像素的 RGB(可能是 0,也可能是任意值)会被卷进可见边缘,放大后的贴纸、图标周围会出现一圈脏色。修复:先预乘 alpha 再卷积,最后反预乘;alpha 为 0 的像素直接输出全 0。这个改动很小,但它修掉了一整类“边缘发黑/发白”的问题。带 alpha 的重采样要先预乘再算。

坑九:100% 对比被面板缩放抹平。 最早的状态页是把两张图都缩到 1400 px 再并排,结果看起来“差不多”,用户根本看不出超分做了什么。修复:用 decodeRegion 裁同一块区域的原生像素,把模型输入的小图按 4× 放大到和输出裁剪一样大,再并排。裁剪失败也不影响主结果(best effort),但成功时差异非常直观。对比 UI 要按 1:1 比像素;缩到同一个面板大小,差异就看不出来了。

坑十:文字和 UI 会被模型“重画”。 这是能力边界,不是 bug。模型擅长照片纹理,遇到笔画会按先验去“猜”,验证记录里“已安装”被重画成了方块状符号。我的处理是把限制写进文档和示例:UI 截图建议用本机 Lanczos3,或者干脆不超分;照片、纹理和低分辨率素材更适合超分。模型不擅长什么,和它擅长什么一样要写进文档。

还有一个 UI 层的坑顺手记一下:ArkUI 的 @Builder 参数按值传递,PixelMap 到达时不会刷新,所以状态页的对比图是内联写的,不是抽成 @Builder。这个坑不报错,只是“图不出来”,很容易查半天。

7. 现在怎么用:从 三方库 到依赖

经过上面的整理,这个工程是三形态交付:npm 库给 Electron 桌面端,HAR 给鸿蒙端,代理 HAP 给设备侧。0.3.0 还没有发布到公共 npm registry(dependencies 为空,Electron 由宿主以 peer dependency 提供),目前直接从仓库安装:

npm install git+https://atomgit.com/oh-tpc/electron-ohos-ai-vision.git

发布到 registry 之后,同样的位置就是 npm install electron-ohos-ai-vision。

主进程接入:

import {
  OhosSuperResolutionEngine,
  registerSuperResolutionIpcHandlers,
} from 'electron-ohos-ai-vision';

const sr = new OhosSuperResolutionEngine({
  // macOS 上 DevEco Studio 自带的 hdc:
  hdcPath: 'hdc',
});
registerSuperResolutionIpcHandlers(sr);

const result = await sr.enhanceFile('photo.webp', { scale: 2 });
console.log(result.width, result.height, result.scale, result.outputPath);

preload 和渲染进程:

// preload
import 'electron-ohos-ai-vision/preload';

// renderer
const info = await window.electronOhosSuperResolution.getBackendInfo();
const result = await window.electronOhosSuperResolution.enhanceFile('photo.webp', {
  scale: 4,
});

鸿蒙侧在工程 oh-package.json5 里加一条本地依赖(或把 ohos/library 拷入工程引用):

{
  "dependencies": {
    "electron-ohos-ai-vision": "file:../library"
  }
}

直接在鸿蒙应用里用 HAR:

import { SrEnhancer } from 'electron-ohos-ai-vision';

if (!SrEnhancer.isSupported()) {
  // 设备不支持 SystemCapability.AI.Vision.VisionBase
  return;
}

const run = await SrEnhancer.pickAndEnhance();
if (run !== null) {
  console.info(`${run.inputWidth}×${run.inputHeight} → ${run.outputWidth}×${run.outputHeight}`);
}

构建、安装、启动(仓库没有 signingConfigs,签名材料不入库,用 DevEco Studio 自动生成调试签名):

cd ohos
export DEVECO_SDK_HOME="<DevEco SDK 路径>"
export JAVA_HOME="<DevEco JBR 路径>"
export PATH="<DevEco Node 目录>:$JAVA_HOME/bin:$PATH"

hvigorw \
  --mode module -p module=entry@default -p product=default assembleHap --no-daemon

hdc install -r example/build/default/outputs/default/entry-default-signed.hap
hdc shell aa start -a SrAgentAbility -b com.ohos.electronvision.agent

环境自检和一次真实超分(仓库里先 npm run build,再跑 dist/cli.js;包发布后就是 npx electron-ohos-ai-vision-doctor):

npm run build
node dist/cli.js \
  --hdc hdc \
  --enhance photo.webp \
  --out photo.4x.png

输出大致是这样:

electron-ohos-ai-vision doctor — HarmonyOS image super-resolution
===============================================================
[OK] hdc executable
[OK] connected targets: 7QB0226705000325
[OK] agent "com.ohos.electronvision.agent" installed on device
[OK] sandbox dir used by file send/recv: ./data/storage/el2/base/haps/entry/files
[OK] local lanczos3 backend (no native dependency)

Active backend (auto): device
{
  "backend": "device",
  "source": "photo.webp",
  "input": "480×360",
  "output": "1920×1440",
  "scale": "4x",
  "outputPath": "photo.4x.png",
  "byteLength": 405545,
  "durationMs": 251
}
Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐