Cordova OpenHarmony框架仓 · 诊断包复核完整源码 · 鸿蒙 PC 开发者社区

前言

交班时收到一份诊断 ZIP,解压器弹出成功,接班人还得确认日志、清单和交接说明有没有完整拿回来。只看归档大小,连丢的是哪份文件都无从知道。我在鸿蒙 PC 上用 Cordova 做了一个诊断包复核台,让同一份回执记录源字节、解压后的字节和实际对比结果。三个文件都是程序生成的固定样例,测试不会接触现场设备的数据。

我把故意失败的一次检查放进同一套验收。先让正常包出一张全绿回执,再交给系统一个不是 ZIP 的样例,最后回到正常包。这样既能检查解压接口确实报告失败,也能看到界面有没有继续显示上一份通过结果。失败后的回执如果不干净,值班人员就可能把旧结果转发给接班人。

先让上一张回执失效

在 MateBook 14 本机编译并签名的 1.0.1 中,点「生成 ZIP」,顶部得到原文件合计 2,934 B 和归档 539 B。此时第三项仍是破折号,说明压缩完成后还没有作逐文件承诺。点「解压并比对」,右侧数字才变成 3 / 3。表里分别核对传感器日志、JSON 清单和交接文本,源文件和恢复文件都是 2,800 B、55 B、79 B。

然后点「检查无效包」。系统返回 900003,表格撤下三行已通过的旧回执,只留下这次没有逐文件结果的提示。原文件体积和正常 ZIP 体积继续显示,因为它们属于本轮已生成的归档,和这次解压是否通过是两个字段。再次点「解压并比对」时不需要重做 ZIP,原归档仍能返回 3 / 3。换成窄窗,再执行一次失败和一次恢复,日志同样先报 900003,再报 bytesMatch=true 和 archiveRoot=flat。

本机环节

检查的证据

生成正常归档

样例原文件 2,934 B,正常 ZIP 539 B

解开并读取

输出为 flat,三个恢复文件分别为 2,800、55、79 B,与源文件逐字节一致

检查无效包

错误 900003,无恢复结果,当前通过数清空

回到正常归档

仍使用原 ZIP,三个文件重新比对通过

早期 1.0.0 的模拟器记录中,原文件仍是 2,934 B,ZIP 为 536 B,文件也都能恢复。在这次本机复测里,只核对了 539 B 的实际产物和恢复结果。那三字节没有做 ZIP 容器层面的差异追溯,不能反推是哪一项压缩元数据不同。做交接验收时先清楚本次要证明的是内容恢复还是归档逐字节一致,这两个指标应分别设计数据。

下方保留两端早期实录和 GIF,验证的是当时 1.0.0 的功能。上面的截图、数值和错误日志来自本次 MateBook 14 的本机重建版。

MateBook 14 真机压缩、解压和失败后恢复。平均 4.86 fps,业务段有效帧率 5.00 fps,无音轨。依次显示 ZIP 体积、三份回执、错误码和正常回执。

MateBook Pro 模拟器 ZIP 复核实录。使用连续截图,平均 3.57 fps,业务段有效帧率 3.56 fps,无音轨。保留与真机相同的四步操作。

新的连续演示先生成归档,随后看三行逐字节通过。接着检查无效样例:900003出现,旧的3/3和三行绿字都撤下。最后直接复核原来的正常ZIP,三行再次通过。三份源样例没有重写,失败只影响本次解压回执。

录制请求上限60 fps,实际可变帧率录像平均13.25 fps。GIF保留120帧、9.14秒,平均13.13 fps,没有复制帧或插帧。主要变化是回执替换,两次点击之间的阅读停留按真实时间保留。

本轮也把同一本机构建目录的1.0.1 HAP装进模拟器,重新生成、比对、失败和恢复。模拟器这次生成536B ZIP,真机为539B,但两端恢复出的三份文件均为2800、55、79B且逐字节一致。这里只确认内容恢复一致,仍没有对ZIP容器的三字节差异作原因归属。下图是本轮实测,不借用早期视频来证明当前包。

从 Web 按钮到沙箱里的三份文件

业务页面等 deviceready 后开放「生成 ZIP」,因为之前 Cordova 桥还没就绪。每个按钮给原生插件的只是自己对应的动作名。动作进到 DiagnosticArchive 后,原生插件在应用的缓存目录创建本次工作目录,按固定模板写入三份源文件,同时生成正常 ZIP 和作为失效对照的文本文件。这里不用让页面提交路径,也不用浏览用户目录。需要导入真实诊断包时,应另做文件选择入口,并给文件来源、允许的大小与输出位置设置明确范围。

原生写文件使用 UTF-8 字节数据,并核对实际写入长度。读取则先查磁盘文件长度,然后分配缓冲区,核对 read 的返回数量。任何一次短读或短写都不能作一致通过。文本包含中文也按 UTF-8 第一个字节到最后一个字节核对,实际 79 B 不是页面上看见的字符数。比较过程先判断字节数,再逐位置检查相等。同长度只是前置条件,里面有一个字节内容不同也应返回差异。

每次复核先单独创建 verify-序号 目录,再把 ZIP 解出。首个文件失败时,清理的只是本次输出目录,源文件和已生成 ZIP 仍可做下一次验证。代码分别读取最外层有 source 目录和直接平铺的两种结构。实际本机返回的是 flat。这个区别在日志里留档,免得原生 zlib 已经正常解出文件,复核却固定从错误的子目录去找。此次验证针对三份已知小样例,比较时一次读完整文件。常规产品要处理很大的日志,适合复用读取循环分段比对,并对整个任务设定可见的上限。

import { common } from '@kit.AbilityKit';
import { util } from '@kit.ArkTS';
import { BusinessError, zlib } from '@kit.BasicServicesKit';
import { fileIo } from '@kit.CoreFileKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { CallbackContext, CordovaPlugin } from '@cordova-ohos/ohos/Index';

interface Fixture {
  name: string;
  content: string;
}

interface FileCheck {
  name: string;
  sourceBytes: number;
  restoredBytes: number;
  identical: boolean;
}

const tag = 'DiagnosticArchive';
const fixtures: Fixture[] = [
  { name: 'sensor.log', content: '2026-11-14T09:16:30 sensor=P03 status=normal value=26.4\n'.repeat(50) },
  { name: 'manifest.json', content: '{"batch":"DG-240","operator":"fixture","sensor":"P03"}\n' },
  { name: 'handover.txt', content: '模拟设备巡检记录\n检查编号 DG-240\n核对传感器与交接清单。\n' },
];

export class DiagnosticArchive extends CordovaPlugin {
  private workDir = '';
  private running = false;
  private attempt = 0;

  execute(action: string, _args: ESObject[], callback: CallbackContext): boolean {
    if (action !== 'pack' && action !== 'verify' && action !== 'verifyInvalid') {
      return false;
    }
    if (this.running) {
      callback.errorByString('BUSY');
      return true;
    }
    this.running = true;
    this.perform(action, callback);
    return true;
  }

  private fileBytes(path: string): Uint8Array {
    const handle = fileIo.openSync(path, fileIo.OpenMode.READ_ONLY);
    try {
      const size = fileIo.statSync(handle.fd).size;
      const buffer = new ArrayBuffer(size);
      if (fileIo.readSync(handle.fd, buffer) !== size) {
        throw new Error('SHORT_READ');
      }
      return new Uint8Array(buffer);
    } finally {
      fileIo.closeSync(handle);
    }
  }

  private write(path: string, content: string): void {
    const encoded = new util.TextEncoder().encodeInto(content);
    const bytes = new ArrayBuffer(encoded.byteLength);
    new Uint8Array(bytes).set(encoded);
    const file = fileIo.openSync(path, fileIo.OpenMode.CREATE | fileIo.OpenMode.WRITE_ONLY | fileIo.OpenMode.TRUNC);
    try {
      if (fileIo.writeSync(file.fd, bytes) !== bytes.byteLength) {
        throw new Error('SHORT_WRITE');
      }
    } finally {
      fileIo.closeSync(file);
    }
  }

  private async openArchive(action: string, callback: CallbackContext): Promise<void> {
    if (!this.workDir) {
      throw new Error('PACK_FIRST');
    }
    const folder = this.workDir + '/verify-' + (++this.attempt).toString();
    fileIo.mkdirSync(folder);
    const zip = this.workDir + (action === 'verifyInvalid' ? '/invalid.zip' : '/diagnostics.zip');
    try {
      await zlib.decompressFile(zip, folder);
      const entries = fileIo.listFileSync(folder);
      const root = entries.includes('source') ? folder + '/source' : folder;
      const files: FileCheck[] = [];
      for (const item of fixtures) {
        const expected = this.fileBytes(this.workDir + '/source/' + item.name);
        const restored = this.fileBytes(root + '/' + item.name);
        files.push({
          name: item.name, sourceBytes: expected.length, restoredBytes: restored.length,
          identical: expected.length === restored.length &&
            expected.every((byte: number, index: number) => byte === restored[index]),
        });
      }
      const passed = files.every((item: FileCheck) => item.identical);
      hilog.info(0, tag, 'action=%{public}s count=%{public}d bytesMatch=%{public}s archiveRoot=%{public}s',
        action, files.length, passed ? 'true' : 'false', root === folder ? 'flat' : 'source');
      callback.successByString(JSON.stringify({ state: passed ? 'verified' : 'different', files }));
    } finally {
      this.cleanup(folder);
    }
  }

  private async perform(action: string, callback: CallbackContext): Promise<void> {
    try {
      if (action === 'pack') {
        const context = this.cordovaWebView?.getUIContext().getHostContext() as common.UIAbilityContext;
        if (!context) {
          throw new Error('NO_CONTEXT');
        }
        if (this.workDir) {
          this.cleanup(this.workDir);
          this.workDir = '';
        }
        this.workDir = context.cacheDir + '/diagnostic-zip-' + Date.now().toString();
        fileIo.mkdirSync(this.workDir + '/source', true);
        const source = this.workDir + '/source';
        let rawBytes = 0;
        for (const item of fixtures) {
          const path = source + '/' + item.name;
          this.write(path, item.content);
          rawBytes += fileIo.statSync(path).size;
        }
        const zip = this.workDir + '/diagnostics.zip';
        await zlib.compressFile(source, zip, { level: zlib.CompressLevel.COMPRESS_LEVEL_DEFAULT_COMPRESSION });
        this.write(this.workDir + '/invalid.zip', 'This fixture is plain text, not a ZIP archive.\n');
        const zipBytes = fileIo.statSync(zip).size;
        hilog.info(0, tag, 'packed rawBytes=%{public}d zipBytes=%{public}d', rawBytes, zipBytes);
        callback.successByString(JSON.stringify({ state: 'packed', rawBytes, zipBytes }));
      } else {
        await this.openArchive(action, callback);
      }
    } catch (error) {
      const detail = error as BusinessError;
      hilog.error(0, tag, 'action=%{public}s code=%{public}d %{public}s', action, detail.code ?? 0, detail.message);
      if (action === 'pack' && this.workDir) {
        this.cleanup(this.workDir);
        this.workDir = '';
      }
      callback.errorByString(JSON.stringify({ action, code: detail.code ?? 0, message: detail.message }));
    } finally {
      this.running = false;
    }
  }

  private cleanup(path: string): void {
    try {
      fileIo.rmdirSync(path);
    } catch (error) {
      const detail = error as BusinessError;
      hilog.warn(0, tag, 'cache cleanup returned %{public}d', detail.code ?? 0);
    }
  }

  onDestroy(): void {
    if (!this.running && this.workDir) {
      this.cleanup(this.workDir);
      this.workDir = '';
    }
  }
}

页面只接收 packed、verified、different 或错误描述,用以更新数字和逐行回执。调用期间三个入口暂时禁用,插件自身也有运行中检查。这个设计的目的,是让一次按钮操作和一次回执建立对应关系;同一个归档的旧成功不要覆盖本次错误。解压无效时撤下表格行和通过计数,保留已准备的正常源文件和压缩包,这就是能立即回到正常包做复测的原因。

'use strict';

const byId = (id) => document.getElementById(id);
const pack = byId('pack');
const verify = byId('verify');
const invalid = byId('invalid');
const status = byId('status');
const listing = byId('files');
let packed = false;

function showStatus(message, error = false) {
  status.textContent = message;
  status.classList.toggle('error', error);
}

function setBusy(busy) {
  pack.disabled = busy;
  verify.disabled = busy || !packed;
  invalid.disabled = busy || !packed;
}

function fillRows(files) {
  listing.replaceChildren();
  for (const file of files) {
    const row = listing.insertRow();
    for (const value of [file.name, file.sourceBytes, file.restoredBytes]) {
      row.insertCell().textContent = value;
    }
    const match = row.insertCell();
    match.textContent = file.identical ? '一致' : '不一致';
    match.classList.add(file.identical ? 'ok' : 'bad');
  }
}

function run(action) {
  setBusy(true);
  showStatus(action === 'pack' ? '正在本地准备样例并压缩…' : '正在原生端解压…');
  cordova.exec((result) => {
    const data = JSON.parse(result);
    if (data.state === 'packed') {
      packed = true;
      byId('raw').textContent = data.rawBytes + ' B';
      byId('size').textContent = data.zipBytes + ' B';
      byId('passed').textContent = '—';
      listing.replaceChildren();
      const remaining = listing.insertRow().insertCell();
      remaining.colSpan = 4;
      remaining.textContent = '已生成 diagnostics.zip,仍需单独解压复核。';
      showStatus('生成完成,可选择正常包或无效样例。');
    } else {
      fillRows(data.files);
      const matched = data.files.filter((file) => file.identical).length;
      byId('passed').textContent = matched + ' / ' + data.files.length;
      showStatus(matched === data.files.length ? '三个文件全部通过逐字节复核。' : '部分解压文件与原本不同。');
    }
    setBusy(false);
  }, (result) => {
    let reason = result;
    try {
      const error = JSON.parse(result);
      reason = error.code + ' · ' + error.message;
    } catch { /* An ordinary Cordova error may already be text. */ }
    if (action === 'pack') {
      packed = false;
    }
    byId('passed').textContent = '—';
    listing.replaceChildren();
    const rejected = listing.insertRow().insertCell();
    rejected.colSpan = 4;
    rejected.textContent = '这次操作未得到逐文件结果。';
    showStatus((action === 'pack' ? '生成失败:' : '解压未通过:') + reason, true);
    setBusy(false);
  }, 'DiagnosticArchive', action, []);
}

document.addEventListener('deviceready', () => {
  setBusy(false);
  showStatus('就绪。先生成内置的三文件样例归档。');
  pack.onclick = () => run('pack');
  verify.onclick = () => run('verify');
  invalid.onclick = () => run('verifyInvalid');
}, { once: true });

华为 zlib 压缩与解压接口 · zlib 错误码说明

同一台鸿蒙电脑上的构建和安装记录

把 CordovaDiagnosticZip 源码归档放进 MateBook 14 的文档目录,本机解包并打开工程。用 DevEco Studio 查入口模块、Cordova 宿主和 entry/src/main 的资源目录。www 里有 index.html 和 archive.js,ArkTS 插件在 entryability 目录,原生 zlib 和文件读写调用均从这个工程编译。工程中 Cordova 的 HAR 子模块版本为 14.0.2;页面夹带的 cordova.js 内部构建标签显示 14.0.1。遇到版本记录不一致时,应当分别写出模块与网页资源的实际标签。

tar -xzf cordova-diagnostic-zip-source.tar.gz
cd CordovaDiagnosticZip
uname -m
ohpm install --all
hvigorw --mode module -p product=default -p module=entry@default -p buildMode=debug assembleHap --no-daemon
ls -l entry/build/default/outputs/default/*.hap

用 OhPM 准备本地依赖、Hvigor 组装 HAP,本次首次 43 项任务耗时 16.723 秒,未签名 HAP 为 23,174,828 字节。IDE 目标选择「此电脑」时直接装未签名包,系统返回 9568320。通过运行输出进入签名配置,生成本项目的调试签名,再由 DevEco 本机组装并安装 entry-default-signed.hap。签名包为 23,439,948 字节。装机查询 com.aasd23.ugccordovadiagzip 得到 1.0.1 和版本代码 1000001,入口启动后进入前面三组复测。

对象

版本及范围

本机开发和实测

HUAWEI MateBook 14(MNTXM-24B),HarmonyOS 7.0.0,软件版本 7.0.0.115(SP11C00E103R12P2patch01),API 26.0.0,aarch64

原生工具和框架

鸿蒙版 DevEco Studio 26.0.0.220,Cordova OpenHarmony 原生模块 14.0.2

工程目标

HarmonyOS 6.1.1(API 24),2in1,本机签名调试包

本轮模拟器1.0.1

MateBook Pro 2in1,管理器配置HarmonyOS6.1.1(API24);实际运行软件6.1.0.125(SP12DEVC00E47R1P3),API24,x86_64。同一本机构建1.0.1 HAP,536B归档恢复3/3,无效包900003后可恢复;旧视频仍为1.0.0。

回执想做到可复查,还要留意失败发生在哪个阶段。压缩后打不开时,原生错误描述能告诉接班人是压缩格式或文件不完整。能打开,但某份恢复文件长度与源数据不同,则应直接定位到表中的文件名。长度吻合但字节有差异也是另一种线索,应继续核对取到的是哪份源文件。在这个演示中最后一种结果由 identical 的布尔值表达,真机给定样例只覆盖了符合预期的三份恢复和无法解开的负对照。没有复测长度相同但字节被改动的输入,这个分支仍需用自己的数据验证。

应用为每次解压单独编号,新一轮生成则创建新的工作目录。排查重试时应同时检查原生动作名和写入顺序。比如日志明确写着 verifyInvalid 报 900003,说明失败发生在负对照这一步。下一条 verify 成功属于正常 ZIP 的另一轮尝试,即使界面重用了同一张表格,也不该把两条记录拼成一次操作。若要做批量导入,回执最好附上源归档标识和尝试序号,便于将错误、日志与实际归档对应。

FAQ

为什么只生成 ZIP 还没有 3 / 3? 生成阶段只负责写入与压缩。复核还要新建输出位置、解压、逐文件读取再比较。上游在打包完成后马上显示通过,会让接班人误以为归档已经展开核对。

900003 出现后,为什么可以用同一个正常包继续? 无效样例是另外一个文件,系统拒绝后清的是这一次尝试的输出,不会改正常 ZIP 和三份源文本。实际界面先撤掉旧回执,下一次正常归档能够重新给出三条新结果。

三份样例通过,能说明什么? 能确认这次列出的三个固定文件恢复后字节一致。当前回执只查这份固定清单,没有声明它验证了任意诊断包的所有条目。将来要接受外部归档时,应先定义清单与归档内容怎样一一对应,并为多项、少项和未知项目分别设计验收。

总结

生成压缩包、解压和核对各有一份自己的结果。真机上,539 B 的正常 ZIP 恢复出三份原字节,无效文件让当次回执失效,原归档随后还能通过。项目把这些不同状态放在同一窗口里,接班人能看出现在可以继续用哪些材料,也能看见发生错误时该回到哪一步。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐