HarmonyOS Agent×Skill 实战(第8篇):弱网恢复与并发幂等【共创稿事节】

图 01:AI 生成的技术主题封面。
一、先看故障现象
第八篇的故障看上去最像普通网络问题:Agent 显示“正在准备出行事项”,用户锁屏再解锁,发现页面进度倒退;随后点一次重试,清单突然出现两份。若未来接入系统日程,这种重复就可能变成两条提醒或多次通知。问题在于任务状态与网络请求没有统一的身份。
二、问题为什么会出现
不要把网络连接当成任务本身。一次用户任务应该有稳定 taskId,一次具体执行有 stepId,每次发起外部请求则有 attemptId。前两者用来识别业务动作,后者只描述网络尝试。不能因为网络请求重新发起就创建新业务任务,也不能让一个 attempt 的回包覆盖后来已经更新的任务版本。对于只读查询,重试通常相对安全;对于写入动作,即使网络超时也可能已经完成,必须先确认幂等状态再考虑重放。
在行旅助手里,页面显示只是执行状态的投影。用户把应用切到后台,再回到前台,UI 可以重新订阅 taskId 对应的状态,但不能重新执行全部步骤。持久化内容至少要包含计划版本、已完成节点、待审批节点、最后一次可用结果和错误码。外部回包到达时,先比较是否仍属于当前活跃任务、是否符合最新计划版本;不匹配的回包只能被丢弃或记录为过期,不能直接刷新页面。
超时需要分级,不是一条 catch 统一写“重试”。网络层超时表示当前尝试没有得到完整响应,但不一定代表服务器没做事;业务层超时表示操作超过用户可接受的等待周期;整体计划超时则意味着应停止后续节点。不同层次对应不同处理:安全的只读请求可有限重试,用户已取消的任务永远不能自动恢复,权限拒绝和非法参数不重试,已经产生副作用的动作通过业务唯一键确认结果。
并发还有竞态条件。比如用户先输入“杭州出发”,立即改成“苏州出发”,旧请求稍后才返回。如果页面只是“谁最后返回就显示谁”,就会用杭州的清单覆盖苏州的任务。修复要点是为每次输入生成版本号,每次响应都附上相应版本;只有与当前活跃版本一致才能更新视图。即使 UI 框架支持响应式状态,也不能自动解决这种异步先后顺序错误。
持久化还必须考虑崩溃窗口。若写操作成功后进程在保存“已完成”状态之前被终止,恢复时可能不知道它已经执行。仅靠客户端内存集合无法解决跨进程或跨设备的“恰好一次”语义。真正的外部副作用应由目标服务或持久存储配合幂等键提供重复提交防护。本系列 Node.js Gate 是业务规则示例,不能代替正式后端的事务存储。把这个限制在文章里明确写出来,才能避免误导开发者直接用于生产付款或日历写入。
网络恢复后也要分清继续与重做。若已生成清单并保存了输入版本,展示旧结果并标明时间可以接受;若即将执行的是需要授权的写操作,应重新核对 token 是否对应当前参数,不应自动接着上次的确认继续操作。用户明确取消时要使后续执行路径不可再进入,即使异步回调迟到也不改变任务状态。
三、实现取舍和系统边界
我更倾向使用“有限重试+可见状态+幂等键”的组合,而不是追求网络永远无感。短时失败后显示当前完成到哪一步、下一步是否安全重试,比持续转圈更有意义。示例中 boundedRetry 最大次数为二,权限错误、非法输入和取消直接停止。该次数是项目策略,并不是 HarmonyOS 对网络重试的默认限制。
对用户来说,点击“再试一次”应有明确语义:如果是预算计算,可以再次计算;如果是创建日程,系统应先查询是否已经有同一操作的完成记录。无法确认结果时,宁可展示“请核对日历后再操作”,也不要以成功文案掩盖不确定性。
四、关键代码与实现路径
以下代码对应下载包中的 项目源码,业务层代码可使用 Node.js 18+ 运行;涉及 scriptManager 的片段需要集成到 Stage 模型并按目标 SDK 验证。所给例子并不包含任何实际订票、真实支付或自动写入系统日历的实现。
import { boundedRetry } from './agent-core.mjs';
const state = { attempts:1, cancelled:false };
console.log(boundedRetry(state,'TIMEOUT')); // retry, attempts:2
console.log(boundedRetry(state,'PERMISSION_DENIED')); // stop
console.log(boundedRetry({attempts:2,cancelled:false},'TIMEOUT'));
// stop: retry_limit,真实写操作还需持久化幂等键
这段实现重点在于将“模型或系统提出的意图”与“程序真正允许执行的业务动作”分开:参数先经校验,再交给业务函数,最后用明确状态或错误码回报。不能直接用一句“执行成功”作为真实设备操作的证据。

图 02:AI 生成的 DevEco Studio 风格开发界面,代码窗口、调试状态与项目名称用于讲解本文排查位置。
五、四类高频踩坑与修复证据
坑 1:用户重试一次,却出现两份日程草稿
表现:用户重试一次,却出现两份日程草稿。
原因:网络 attempt 与业务 task 混用,每次重试都生成新的业务主键。
处理:稳定 taskId/stepId,写入动作配套幂等键,重复调用返回已处理。
复验:同一任务连续执行两次,应只有第一次产生新结果。
坑 2:改成苏州后突然又显示杭州的结果
表现:改成苏州后突然又显示杭州的结果。
原因:旧请求迟到却直接覆盖最新界面状态。
处理:每个请求绑定输入版本,回包版本与当前不一致则丢弃。
复验:故意让旧请求延迟返回,最新目的地必须始终保持正确。
坑 3:权限拒绝也被自动重试多次
表现:权限拒绝也被自动重试多次。
原因:把所有异常塞入统一 catch,缺少可重试错误分类。
处理:对权限、参数、取消立即停止,网络短暂失败才有限重试。
复验:执行相同失败注入,检查 attempts 上限与用户提示一致。
坑 4:退后台后任务从头开始
表现:退后台后任务从头开始。
原因:UI 重新 mount 时无条件触发起始动作,未恢复执行状态。
处理:页面只订阅 taskId,任务状态由持久化仓库和执行器共同维护。
复验:后台前记录完成节点,重新打开后应继续显示现有结果而不是新增动作。
六、深入复盘:工程上还要补什么
为什么客户端“只执行一次”不是绝对保证
内存里保存一个 Set 可以挡住当前进程内重复的幂等键,但应用被系统回收、重新安装或者任务切换设备后,这个集合就不存在。若要对真正的系统日程或云端写入实现可靠去重,需要持久化存储或目标服务提供业务唯一约束。比如在创建前查询既有记录、用确定的业务键保存执行结果,并让服务端在同一事务中完成写入与去重。否则网络在“提交成功但响应丢失”时,客户端仍然不知道结果已产生。
对于原生平台的后台与恢复场景,系统可能终止进程,这是移动端的正常环境约束,不能把 onPageShow 之类的回调当成可靠任务队列。页面生命周期适合更新视图,不适合充当执行器所有状态的唯一保存处。更可靠的安排是任务本身在持久化仓库维护,页面回来后读取并渲染状态,只有用户明确发起新任务才生成新的 taskId。这样即使 UI 被重建,也不会因为组件初始化而重复调用创建接口。
处理旧回包、请求取消与数据版本
考虑两个请求:A 使用目的地杭州,B 使用目的地苏州。用户先发起 A,随后修改成苏州发起 B;B 网络快先返回,A 网络慢后返回。如果没有 requestVersion,A 迟到的回包会覆盖 B,让页面显示杭州。解决办法不是禁止用户快速输入,而是把每个请求绑定输入版本与 traceId,收到结果时先确认版本仍然有效。已过期的结果可以记录为 stale_response,但不得直接修改当前界面状态。
取消也不只是结束加载动画。真正的取消应让执行器在每个副作用操作前检查 cancelled 状态;已经发出去的请求如果无法撤销,至少要停止后续步骤,并在结果返回时判断是否需要给用户显示“操作可能已完成,请核对”。用户明确取消后再次自动重试,会破坏操作可控性。特别是多步任务,前一步已经成功、后一步尚未运行时,取消应有局部完成的可见状态。
把重试策略写成表,而不是埋在 catch 里
推荐把错误按可重试性分类:连接重置、短暂服务不可达可以有限次重试;参数非法、授权拒绝、能力不支持应立即停止;外部写入超时则先核对结果再决定是否允许重试。每次尝试要记录次数、下一次动作和失败原因。退避策略可以减少网络抖动期间的无意义请求,但不能代替业务去重。某些错误即使重试一百次也不会消失,例如缺少系统权限。
本系列示例的重试次数是业务自定值,不能推断系统自带相同保证。通过这些测试之后,下一篇仍需在真实设备、系统入口和审核环境重新验证,因为弱网表现、后台回收和系统权限都是环境相关行为。
七、运行、验证与边界检查
验证可以用延迟回包和手动断网来做,或先在纯业务测试中构造不同顺序的结果。让任务 A 比任务 B 晚返回,检查最终界面仍显示 B;在第一次成功后重发同一幂等键,确认没有重复新增;在取消后到达成功回包,确认 UI 不会重新进入 running。测试断网、重连、后台恢复时需分别记录 taskId、版本与 attempts,避免只用时间戳猜测。
恢复策略失效时,排查请求标识是否稳定、落盘是否在恰当阶段、超时类型是否区分、后台回来是否无条件新建任务。下一篇把所有这些条件纳入发版闸门,说明为什么本机业务测试通过仍不意味着 Skill 已经具备审核和上架条件。

图 03:AI 生成的 HarmonyOS 风格手机操作界面,所有页面数据用于功能说明。
为了让重试行为可被测试和审计,建议把错误码表独立维护,明确哪些条件允许重试、最长重试多少次、何时需要人工核对结果。短暂网络波动不能直接被解释为业务失败,接口超时也不能被解释为任务一定未执行。遇到跨系统写入结果不确定时,把状态标为待确认,比假设失败并再次写入更负责任。
八、本篇小结与下一篇预告
本篇将具体问题限定在可观察的调用链、可复现的业务规则与明确的拒绝分支中,给出了代码与手动验证顺序。尚未在目标设备上验证的系统行为应继续按当前 SDK 与官方文档核实。下一篇将以上规则转化为完整评测集,核对 Skill 真机导入、审核资料和版本回滚。
官方核对资料
更多推荐
所有评论(0)