崩溃发生时进程已经退出，依赖当前页面回调上传诊断信息通常来不及。HiAppEvent能够提供系统事件及相关日志引用，工程侧需要在下次启动补采，并把读取、脱敏、入队、上传和清理拆成可恢复阶段。

方案面向HarmonyOS 6.1.1 Release SDK（API 24），系统Kit调用进入适配层，命令约束、状态归并和恢复策略进入可测试的业务层。范围包含状态与资源生命周期设计、失败恢复和验收合同，不包含业务内容生产、服务端协议改造以及特定厂商网页或媒体源的兼容承诺。

崩溃事件为何要在下次启动补采

方案为每个事件建立DiagnosticEnvelope，只保存eventId、eventName、occurredAt、bundleVersion、logRefs、redactionVersion和uploadState。Watcher负责从holder连续takeNext直到为空；事件原始参数先经过白名单提取，再进入本地有界队列。

状态数量不是越多越好。每个状态必须回答三个问题：当前允许哪些命令、收到迟到事件怎样处理、页面退出后是否还可以更新UI。下面的状态对象携带operationId，新的操作开始后，旧操作回调会被拒绝。

export enum DiagnosticEventState {
  REGISTERING = 'registering',
  COLLECTING = 'collecting',
  REDACTING = 'redacting',
  QUEUED = 'queued',
  UPLOADING = 'uploading',
  QUOTA_FULL = 'quota_full'
}

export interface DiagnosticEventSnapshot {
  state: DiagnosticEventState;
  progress: number;
  message: string;
  operationId: number;
  updatedAt: number;
}

export type DiagnosticEventEvent =
  | { type: 'START'; operationId: number }
  | { type: 'PROGRESS'; operationId: number; progress: number }
  | { type: 'SUCCESS'; operationId: number }
  | { type: 'FAIL'; operationId: number; message: string };

export function acceptEvent(
  snapshot: DiagnosticEventSnapshot,
  event: DiagnosticEventEvent
): boolean {
  return event.type === 'START' || event.operationId === snapshot.operationId;
}

Watcher与上传器不能共用生命周期

订阅注册在进程级服务，页面只读取统计快照。external_log逐个检查规范路径、大小和剩余配额，超限时优先保留最新未上传故障。上传采用事件幂等键，服务端确认后再删除本地包和对应日志；网络失败只改变nextRetryAt，不重新生成事件ID。

这套分层把系统事实和产品行为分开：Kit适配器负责获得事实，领域对象决定是否接受事件，页面只渲染快照。更换API版本或加入真机能力时，只需要替换适配器；状态归并和异常策略仍可在模拟器中重复验证。

外部日志读取前先做配额判断

下面是主题专属的接入或核心算法代码。示例刻意保留资源创建、前置条件和清理逻辑，因为高频故障往往出现在成功调用之外。

import { hiAppEvent } from '@kit.PerformanceAnalysisKit';

export interface DiagnosticEnvelope {
  eventId: string;
  eventName: string;
  occurredAt: number;
  bundleVersion: string;
  logRefs: string[];
  redactionVersion: number;
  uploadState: 'QUEUED' | 'UPLOADING' | 'CONFIRMED';
}

export class EventCollector {
  private holder?: hiAppEvent.AppEventPackageHolder;
  private watcher?: hiAppEvent.Watcher;

  start(): void {
    if (this.holder) return;
    this.watcher = {
      name: 'stability_watcher',
      appEventFilters: [{
        domain: hiAppEvent.domain.OS,
        names: [hiAppEvent.event.APP_CRASH, hiAppEvent.event.APP_FREEZE]
      }]
    };
    this.holder = hiAppEvent.addWatcher(this.watcher);
  }

  drain(accept: (value: hiAppEvent.AppEventPackage) => void): number {
    if (!this.holder) return 0;
    let count = 0;
    let pkg: hiAppEvent.AppEventPackage | null = null;
    while ((pkg = this.holder.takeNext()) !== null) {
      accept(pkg);
      count++;
    }
    return count;
  }

  stop(): void {
    if (!this.watcher) return;
    hiAppEvent.removeWatcher(this.watcher);
    this.holder = undefined;
    this.watcher = undefined;
  }
}

代码迁入业务工程时，应把错误码转换为稳定的领域错误，不让页面直接判断系统错误字符串。对于异步回调，还要在写入状态前比较operationId或资源版本；仅检查组件是否存在，无法阻止旧任务污染新页面。

脱敏规则必须早于持久化

异常注入按钮用于稳定复现应用侧恢复路径。真实错误发生时，诊断记录同时保存错误码、权限结果、设备能力和用户可见状态；敏感原始数据不进入日志，截图只呈现与问题直接相关的结果。

上传确认后才允许删除日志

页面层不直接调用Kit，而是通过动作按钮驱动同一份状态模型。这样既能在系统能力可用时接真实适配器，也能在模拟器缺少硬件时验证错误页面、幂等逻辑和资源清理。

@Component
struct DiagnosticEventPanel {
  @State stateText: string = 'REGISTERING';
  @State progress: number = 0;
  @State logs: string[] = [];

  private append(message: string): void {
    const time = new Date().toLocaleTimeString();
    this.logs = [`${time}  ${message}`, ...this.logs].slice(0, 8);
  }

  private startDemo(): void {
    this.stateText = 'COLLECTING';
    this.progress = 20;
    this.append('开始：HiAppEvent崩溃订阅与日志配额治理');
  }

  private injectFailure(): void {
    this.stateText = 'QUOTA_FULL';
    this.append('已注入可恢复故障');
  }

  build() {
    Column({ space: 12 }) {
      Text('HiAppEvent崩溃订阅与日志配额治理').fontSize(24).fontWeight(FontWeight.Bold)
      Text(this.stateText).fontSize(18).fontColor('#2563EB')
      Progress({ value: this.progress, total: 100 }).width('100%')
      Row({ space: 12 }) {
        Button('开始实验').onClick(() => this.startDemo())
        Button('注入故障').onClick(() => this.injectFailure())
      }
      ForEach(this.logs, (item: string) => Text(item).fontSize(13))
    }.padding(20).width('100%')
  }
}

验收模拟上次启动遗留崩溃、连续三次故障、日志空间告警、离线启动、上传超时和确认后清理六种情况。诊断面板展示待处理数量、最旧事件时间、总日志字节、脱敏版本和最近上传结果；任何未确认事件重启后仍可继续，确认事件不再重复上传。

故障诊断数据本身可能含文件路径、页面参数和用户输入，白名单提取比事后查找敏感词更可靠。自定义参数只放版本、功能开关和匿名场景编号，不能加入账号、Token或完整业务内容。日志配额治理按照上传状态和时间清理，CONFIRMED最先删除，QUEUED在保留窗口内不可因空间紧张被静默抹除；确实无法继续采集时要增加丢弃计数。Watcher回调不执行压缩和网络上传，重任务交给后台队列。应用升级后redactionVersion变化时，旧事件必须重新经过当前脱敏器或直接放弃上传，不能把旧规则生成的包视为永久安全。

验收记录至少包括SDK版本、模拟器系统版本、操作顺序、预期状态、实际状态和截图编号。快速点击、返回再进入、故障后重试和页面销毁是必测项；涉及资源的主题还要显示活动对象计数，涉及异步任务的主题要验证迟到结果不会改变当前页面。

故障积压与断网恢复验收

这套方案的技术闭环由“输入约束—状态模型—Kit适配—异常恢复—可观察验收”组成。业务状态不持有系统对象，适配器不直接操作页面，异常路径有明确的恢复动作，后续SDK升级时可以分别回归每一层。

官方资料：HiAppEvent相关开发文档