本篇技术封面

图:本篇 AI 智能应用主题封面。

在设计“智会行动”时,最早的产品需求很诱人:点一下录音,结束后自动出现转写、会议纪要和待办事项。页面草图只有三步,工程里却至少有四个不同时钟:录音设备的状态、语音识别任务的状态、模型生成任务的状态,以及用户在界面上对内容的编辑状态。若用一个 loading 加一段字符串贯穿全部流程,示例时很顺畅,遇到权限拒绝、重试、应用切后台或用户连续点击,数据就会相互覆盖。

本系列围绕一个具体应用“智会行动”展开。会议数据保存在应用本地;语音识别优先研究 HarmonyOS 的 Core Speech Kit 离线能力,生成式摘要则通过可替换的模型适配器接入。这里不把某一家云模型写成系统自带能力,也不假定所有设备、系统版本都支持相同模型。第一篇先解决“哪些数据是事实,哪些只是过程产物”,后面八篇逐步处理每种失败链路。

一、一个 status 不应该包揽所有业务

典型的问题是界面显示“转写完成”,但后台摘要任务仍在处理。用户以为会议已经可归档,关闭页面后只保存了最后一次增量片段;再次进入看到一份缺少后半段内容的纪要。这个错误并非模型理解能力不足,而是业务层没有定义每一步可以输入什么、产生什么、什么时候可被下一步消费。把“页面显示完成”作为数据一致性标志,是最先要消除的设计误区。

我建议将会议记录视作一个带版本的数据聚合:id 是不可重复的会议标识;audio 指向录音产物;segments 保存按时间顺序归并后的最终识别片段;summary 是待审核的模型输出;actions 是可单独确认的候选行动项。每一部分都需要独立的来源信息、生成时间和错误状态。视图不直接拼接这些对象,而是读取持久化后的稳定快照。这样一来,用户在编辑标题时,不会无意触发转写重新执行。

此外必须区分“录音停止”和“录音文件可用”。调用停止接口成功,只说明设备结束当前操作,文件是否已经完整落盘、媒体格式是否匹配识别器输入,需要单独检查。若后续流程假设任何音频都必然能转成文字,一旦遇到空文件或不支持的格式,最后会把设备问题包装成“AI 生成失败”,给用户极差的排障提示。

二、用合法状态迁移堵住错误路径

一个可维护的状态机不需要复杂框架,关键是把允许的跳转写出来。例如从 recording 可以进入 recorded,却不能越过识别直接成为 review;从 review 可以重新生成摘要,但不应在没有重新录音的情况下回到 recording。这些约束不是为了让代码好看,而是给重复点击、异步回调和异常恢复提供统一裁决规则。

// 来源:示例源码/src/meeting.mjs(独立可测试的业务模块)
export const STEPS = Object.freeze([
  'created', 'recording', 'recorded', 'transcribing',
  'transcribed', 'summarizing', 'review', 'archived'
]);

export function createMeeting(id, title, startedAt) {
  if (!id || !title || !Number.isFinite(Date.parse(startedAt))) {
    throw new TypeError('invalid meeting metadata');
  }
  return {
    schemaVersion: 1, id, title, startedAt,
    phase: 'created', audio: null, segments: [],
    summary: null, actions: [], version: 1
  };
}

export function transition(meeting, next) {
  const legal = {
    created: ['recording'], recording: ['recorded'],
    recorded: ['transcribing'], transcribing: ['transcribed'],
    transcribed: ['summarizing'], summarizing: ['review'],
    review: ['archived', 'summarizing'], archived: []
  };
  if (!legal[meeting.phase]?.includes(next))
    throw new Error(`illegal transition ${meeting.phase} -> ${next}`);
  return { ...meeting, phase: next, version: meeting.version + 1 };
}

示例的 createMeeting 会校验最基本的会议信息,transition 以明确的邻接关系检查状态。代码放在 示例源码/src/meeting.mjs,可用 Node.js 独立测试;它属于跨平台业务层,不是 HarmonyOS 官方 API。真正落到 ArkUI 时,界面只在动作成功后更新当前状态,而不是先改 UI 再期待底层调用一定成功。

状态与版本管理开发过程界面

图:状态与版本管理的开发环境样式示意;非 DevEco Studio 实际运行截图,日志为界面示例内容。

三、写入顺序比按钮顺序更重要

录音产物、识别文本和摘要结论是不同等级的结果。录音文件是不可轻易重建的原始资料;转写文本可以在保留原音频的情况下重新产生;摘要和待办则是基于转写生成的派生资料。存储策略因此应该区别对待:优先确保存住原音频和完成的转写片段,摘要失败可以重新生成。不要因为一次总结错误而同时删除音频和所有文本,否则“重试”会变成让用户再开一次会。

写入时建议采用“先产生新版本,再原子替换索引”的思路。例如把本次转写生成 transcriptRevision=4,摘要必须明确声明 sourceRevision=4;当用户手动更正了说话人或转写内容,新文本版本提升到 5,旧摘要立即标成“基于旧文本”,而不是悄悄保持已完成状态。这个小设计能解决大量 AI 产品常见的“内容已经变了,旧结论还像新的一样展示”的问题。

存储位置也不能拍脑袋决定。音频是大文件,会议标题和状态则是小量结构化数据。把整段音频编码塞进 Preferences 或把所有转写都绑在单个页面状态里,不仅难以分页和清理,还会在页面重建时放大内存开销。HarmonyOS 的应用沙箱与文件生命周期管理有明确指导,具体目录选择应结合缓存是否可再生、是否需要备份、用户是否能够主动删除来决定。

四、把错误归因放进模型里

界面只弹一句“请求失败”无法定位到底是录音权限、引擎初始化、模型服务还是磁盘空间出了问题。建议每一阶段保存 stage、retryable、errorCode、occurredAt 和面向用户的操作建议,同时将原始堆栈限定在本地诊断日志中。隐私敏感的音频内容、完整会议原文不应默认写进普通日志。错误码如果来自外部服务,应先做归类映射再展示,而不是将供应商的整段技术提示直接暴露到界面。

需要注意一个看似方便的做法:失败后自动从头重跑所有步骤。对于音频转写,重跑有成本;对于已经人工修改过的纪要,自动覆盖甚至会损坏用户劳动成果。更合理的是“从失败阶段重试”:录音文件存在且校验通过,就跳过录音;最终转写齐全,就不要重复调用识别;如果只缺行动项,就用已确认的摘要版本重新提取。重试按钮的语义必须和数据版本绑定。

五、界面上给用户的三种完成态

“已录制”“已转写”“待确认”应该是能同时解释清楚的三种状态。列表页展示阶段,详情页展示材料是否完整,编辑页提示当前操作是否会使下游结论过期。不要追求一个看起来很漂亮的绿色“已完成”标签,因为会议纪要的完成包含两部分:机器已产出以及人已认可。我们将最终归档留给用户确认,避免把自动生成内容直接当作正式会议决议。

会议记录应用界面

图:会议记录的手机界面设计示意,页面数据用于说明交互,非真机截图。

页面交互还需要解决返回键和恢复问题。用户从会议详情进入另一页后返回,组件可能重新创建;这时先从持久化层取会议快照,再尝试恢复非关键的进度展示。若进度请求已经属于旧的 requestId,不能再把迟到结果写进当前会议。页面重建本身不应该触发新的录音,也不应该在未征得同意时启动网络上传。

六、上线前优先检查四条异常路径

第一条是创建会议后立即退出:应该保留一个空记录还是回滚?设计上可以保留草稿,但要有删除入口。第二条是录音已保存、转写尚未开始时强制退出:重新启动后应能找到文件,避免出现孤儿数据。第三条是转写文本被更正后再生成摘要:需要让旧结论显式失效。第四条是一个会议同时打开两个详情页:后提交的编辑不能无条件覆盖较新的版本,至少要执行乐观锁版本检查。

还有一个容易忽略的失败注入:同一按钮快速连点五次。在没有互斥门禁时,很可能生成多份转写请求或者多个标题相同但 ID 不同的会议记录。单纯给按钮加 300 毫秒防抖不能解决后端幂等问题,真正需要的是业务操作 ID、当前阶段合法性与持久层唯一约束。下一篇录音状态机将把这种保护推进到设备资源层。

七、如何验证这篇设计,而不是只看页面

先使用本地测试数据创建会议,检查初始阶段确实是 created;按规则推进到 recording,确认版本号递增;直接请求从 created 跳到 archived,应收到非法迁移错误。其次,设计一条带重复回调的事件序列,确认同一动作不会重复生成稳定状态。最后,故意将转写版本从 1 改为 2,验证系统会标出旧摘要过期。这里只能把它们写为建议验证项,不能据此声称已完成 HarmonyOS 真机检验。

跨端业务代码可以在普通 JavaScript 环境先测试,但系统录音、权限弹窗、前后台调度仍必须在真实设备按目标 API 版本核对。这个区分极其重要:业务逻辑测试通过只能说明基本状态转换符合预期,并不能保证设备麦克风或离线语音模型可用。用“逻辑通过”冒充“端到端通过”,正是智能应用交付时最容易掩盖风险的坑。

八、再往下挖:状态正确却仍然会发生并发覆盖

即便加了状态机,两个页面同时修改同一份会议仍可能产生“最后写入获胜”的数据丢失。一个详情页把标题从“产品例会”改成“版本评审”,另一个页面随后保存了旧快照中的行动项,若持久层执行整对象覆盖,标题就会变回旧值。应当使用带版本条件的写入:客户端提交预期 version,数据库只有在当前版本匹配时才接受;否则给出冲突提示,让用户选择合并改动或重新加载。这样比偷偷覆盖更符合会议资料的价值。

还有一种容易被误解的“重复”:在设备录音和转写之间,两个异步任务都报告了成功,页面各触发一次向下一阶段推进。合法状态迁移可以阻止第二次跳转,但若外部调用先于状态校验执行,仍可能多消费一次模型额度。因此门禁应在发起不可逆副作用之前完成,并将操作 ID 写入持久层。状态机管理允许做什么,幂等表管理同一件事是否已经做过,二者不是互相替代。

建议给会议详情设计一张故障时间线:每个阶段记录开始时间、稳定产物引用和可重试原因,但默认隐藏复杂字段。开发排查时从“用户最后确认保存的内容”倒推,找出对应的状态版本和来源 ID;必要时提供导出脱敏诊断信息的入口。这样用户说“昨晚生成的待办今天不见了”,工程师不必先猜是 AI 换了模型、列表筛选还是写入冲突,可以有顺序地核对事实。

最后强调一个接口设计习惯:summary=null 与 summary={claims:[]} 不能混为一谈。前者表示尚未生成,后者可能表示生成成功但没有明确决议。actions=[] 也未必表示失败,正常会议完全可能没有执行事项。把“空结果”当成异常重试,会让系统反复调用模型,最终为了结束循环而生造待办。信息不足时保持空白,是比“看起来总有内容”更可靠的智能交互。

还有一条值得放进团队代码评审规范:任何跨阶段的异步结果,落盘前必须重新核对会议 ID、来源版本与当前状态。只有这些条件同时满足,结果才能成为新的稳定产物。否则一次看似成功的 API 回调,可能只是来自几分钟前已取消的旧任务。把核对点固定到数据仓储层,比散落在各个页面回调里更不容易遗漏。

本篇结论:先确定数据的所有权、版本和合法阶段,再接入任何 AI 能力。下一篇将进入设备层,专门处理麦克风授权之后仍可能录不到音、录音状态不一致和退后台释放资源的问题。


资料核对说明:本系列部分涉及 HarmonyOS 原生能力,应以当前开发套件与华为官方文档为准;项目中的纯 JavaScript 代码属于业务示例,不等同于已完成端侧 SDK 对接。相关链接见根目录《官方资料索引.md》。

Logo

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

更多推荐