Electron 鸿蒙图像超分实战:把小图送进 NPU,把细节拿回桌面
一个只对 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-vision | 0.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.0 | ohpm 三方库(HAR,零依赖 import) | 同仓库 ohos/library |
| com.ohos.electronvision.agent | 0.3.0(versionCode 30000) | 设备代理 HAP(entry 模块,零权限) | 同仓库 ohos/example |
实测环境:
| 项 | 版本/型号 |
|---|---|
| Electron | 40.1.0(peer 依赖 ≥ 20;库核心也支持纯 Node 18+) |
| Node.js / TypeScript | 24.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×480 | 1070.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.0 | electron-ohos-ai-vision 0.3.0 | |
|---|---|---|
| 系统能力 | textRecognition | imageSuperResolution |
| 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.ts | 17 | 结果校验顺序、倍数换算、线协议解析容错 |
png.test.ts | 15 | 签名 / CRC、RGBA 往返、色彩类型 0/2/4/6、filter 0-4、调色板 / 16-bit / 隔行拒绝 |
resample.test.ts | 16 | Lanczos3 / 双三次 / 双线性核、预乘 alpha、尺寸上限、锐化、清晰度评分 |
local-backend.test.ts | 12 | 端到端本机放大、输出命名、目录创建、错误分支 |
device-backend.test.ts | 20 | hdc 输出解析、四步协议 argv、信封解析、超时、冷沙箱、bundle 缺失 |
engine.test.ts | 12 | 后端选择矩阵、自动回退、显式 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_DEVICE | hdc 可用但没有设备 |
AGENT_NOT_INSTALLED | 设备上没有 Agent HAP |
AGENT_TIMEOUT | 等结果文件超时 |
AGENT_ERROR | Agent 返回失败信封(如输入丢失) |
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
}
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。
更多推荐


所有评论(0)