HarmonyOS Agent×Skill 实战(第5篇):多步规划与执行状态【共创稿事节】

图 01:AI 生成的技术主题封面。
一、先看故障现象
用户希望“整理行李、估算预算,再把出发时间做成提醒草稿”,这是一条带依赖关系的请求。最初尝试把全部步骤一次扔给模型,返回里有时先生成了提醒草稿,有时跳过预算,有时重复创建了同名清单。文本回答无论多流畅,也无法替代可恢复、可审计的执行计划。
二、问题为什么会出现
多步任务的第一道边界是计划,而不是工具。我们先把任务分解为 packing、budget、schedule_draft 三类白名单节点,每个节点都有独立 ID、依赖项和状态。最简单的计划可以按顺序执行,但仍需要显式记录 dependsOn,未来有并行步骤才不会无法判断哪一步依赖哪个输出。这里使用“有向无环图”的有限子集:新增节点只能依赖已经存在的节点,发现前向依赖或环就拒绝,而不是猜测执行顺序。
业务状态至少包括 pending、waiting_input、waiting_approval、running、succeeded、failed、cancelled。某个节点结束不代表整次任务已经结束。比如预算需要用户输入车票金额,系统应该将预算节点停为 waiting_input;此时行李清单若独立可以继续,但日程草稿若需要准确出发时间,则不得提前落地。把所有节点简单设为“完成”会让页面看起来漂亮,却抹掉真正的风险。
计划输出必须经过规则引擎检查。模型生成“先订票、再创建日程”的计划时,订票不属于白名单,整段计划应被拒绝或要求用户改为只生成建议。即使第一步是合法的 packing,第二步也不能因模型说“必须使用任意 shell 工具”而获得系统权限。规划者建议做什么与执行器允许做什么要严格分离,执行器只接受经过校验的 Skill 名、参数与授权票据。
为了防止循环调用,给每次请求设置最多节点数、每节点最大执行次数与整体超时。失败重试不应该原封不动把上一轮全部上下文再送进模型,否则可能出现新的计划、重复步骤和自我引用。我们在业务层将失败分成可重试和不可重试:短时网络失败可能有限重试;参数非法、用户拒绝与权限不足要立即停止并解释;用户取消后必须保证任务不再偷偷恢复。
每个节点还需记录输入快照和版本。用户在执行中途把目的地从杭州改成苏州,原计划不能继续用旧城市拼出新的预算。做法是把计划看成不可变版本,输入变更后生成新版本并令旧节点失效;这样无需追着每条 UI 状态补丁修修补补。结果若是只读数据可以被替换,若是有副作用的操作则还要检查是否已经执行,不能随意重放。
本文示例的 createPlan 是有限规则计划器,不是通用 LLM 思维链。它保证节点类型、ID 唯一、依赖顺序和数量约束;真正接入模型时,只允许模型提出候选计划,由这层规则判断能否进入调度队列。这个安排让异常有清晰归属:模型提出非法节点是规划问题;依赖未满足时执行是调度问题;接口结果与契约不符是工具问题。只有分开,线上才能定位而非猜测。
三、实现取舍和系统边界
任务页面不应只用一个旋转加载框表示全过程。最好把已完成、等待补充、等待用户确认和执行失败分成不同视觉状态,尤其要保留失败节点的错误说明。一个任务运行到一半并非一定需要全部重做,条件是前序结果未改变、操作可重入且用户授权仍然有效。对出行准备这种低风险场景,可以保留已生成的行李清单;对系统日程写入类动作,则必须把审批状态与幂等键一起复核。
计划也不是越长越好。实际项目里,把“旅行准备”拆成二十个意义不大的节点只会增加调度复杂度和可失败表面。我们限定最多八个节点,目的就是逼迫应用把粒度控制在可观察的业务动作上。这个限制属于示例的自定义策略,不是 HarmonyOS 平台限制,接入真实业务可根据任务复杂度重新衡量。
四、关键代码与实现路径
以下代码对应下载包中的 项目源码,业务层代码可使用 Node.js 18+ 运行;涉及 scriptManager 的片段需要集成到 Stage 模型并按目标 SDK 验证。所给例子并不包含任何实际订票、真实支付或自动写入系统日历的实现。
import { createPlan } from './agent-core.mjs';
const planned = createPlan([
{id:'s1', skill:'packing', dependsOn:[]},
{id:'s2', skill:'budget', dependsOn:['s1']},
{id:'s3', skill:'schedule_draft', dependsOn:['s2']}
]);
if (!planned.ok) throw new Error(planned.code);
// 真正的执行器还要分别维护 running、waiting_input、
// waiting_approval、succeeded、failed、cancelled 状态。
这段实现重点在于将“模型或系统提出的意图”与“程序真正允许执行的业务动作”分开:参数先经校验,再交给业务函数,最后用明确状态或错误码回报。不能直接用一句“执行成功”作为真实设备操作的证据。

图 02:AI 生成的 DevEco Studio 风格开发界面,代码窗口、调试状态与项目名称用于讲解本文排查位置。
五、四类高频踩坑与修复证据
坑 1:预算还没填,提醒草稿已经生成
表现:预算还没填,提醒草稿已经生成。
原因:没有显式依赖关系,调度器把所有节点当成可并行执行。
处理:给节点定义 dependsOn,依赖未成功不得进入 running。
复验:人为阻断预算节点,检查后置任务保持 pending 或 waiting_input。
坑 2:模型建议调用不存在的“购买酒店”工具
表现:模型建议调用不存在的“购买酒店”工具。
原因:规划器把自然语言中的所有动作都信任为可调用能力。
处理:只接受已注册的 Skill 白名单,并对计划节点数量和 ID 做约束。
复验:提交含未知工具、循环依赖和重复 ID 的计划,应全部拒绝。
坑 3:失败后点重试,行李清单出现两份
表现:失败后点重试,行李清单出现两份。
原因:没有记录节点级执行状态和输入版本,重复从第一步运行。
处理:保存步骤状态与去重键,只重做满足重试条件的失败节点。
复验:第一次成功后诱发后续失败,再重试;成功节点不应重复新增。
坑 4:用户已经取消,后台仍继续生成
表现:用户已经取消,后台仍继续生成。
原因:取消只改变界面按钮,不影响调度层的取消标识。
处理:将 cancelled 传入执行状态机,后续工具调用前再次检查。
复验:在任务排队和网络等待期间分别取消,确认没有新副作用产生。
六、深入复盘:工程上还要补什么
DAG 的意义不在复杂算法,而在可解释的停止点
如果业务只有一项清单生成,顺序函数就能胜任;多步 Agent 的困难在于某一步可能需要用户补充信息,另一项可能需要系统权限,还有一项可能在断网后晚到结果。显式依赖关系让系统知道每个节点能否前进。计划图应向用户呈现为清楚的步骤,而不是把所有内部技术节点暴露成晦涩术语。用户只需要知道“行李清单已完成、预算等待金额、日程草稿待时间确认”。
计划执行器必须保证输入不可被中途悄悄改变。模型可能因为新消息重新规划,但旧计划仍在后台执行。如果没有版本号,两份计划都可能向同一目标写入。给计划附上输入摘要和版本,任何关键槽位变化都触发失效判断;新计划生成后,旧计划的后续写操作应该被拒绝。对于已经完成的只读任务,可以按规则复用结果,但复用必须依赖相同输入和规则版本。
面对部分成功,最忌讳把结果写成全成功
用户要求三个步骤,前两个完成、最后一步失败,正确状态应是 partial_success 或明确的节点状态集合,不应只有一个全局“完成”标签。清单已经生成,用户可以先使用;日程还没创建,必须明示。特别是和系统能力相关的步骤,回包成功也要有相应的结果证据,否则只是执行器自我宣布成功。必要时可以提供“导出草稿”作为降级,而不是假定系统服务一定可用。
错误重试还要考虑副作用边界。重做一项纯计算和重做一项已提交的写操作,风险完全不同。让调度器根据工具元数据识别只读、创建、更新、删除等类型;危险级别较高的操作必须检查是否已有相同任务记录,以及用户授权是否仍覆盖当前参数。这个元数据表来自开发者业务定义,而不是由模型在运行时随意决定。
代码审查时可以问的四个具体问题
第一,某个节点失败会不会错误解锁依赖它的下一步?第二,用户取消之后,仍未到达的异步响应是否能改变任务?第三,两个同名但不同 taskId 的请求是否会互相覆盖?第四,某一步返回空数据但状态为成功时,后续是否会静默接受?这四种问题都与是否使用高性能大模型无关,属于业务控制流的基础责任。
为后续写入系统日程预留操作确认节点,是这一章最重要的设计决定。它把“模型建议创建”与“执行器被授权创建”分开,让多步任务可以停在有意义、用户能够理解的位置。下一篇会围绕这个停止点继续深入。
七、运行、验证与边界检查
建议设计五个回归:正常三步计划、重复 ID、引用不存在的节点、包含未注册 Skill 的节点、超过最大节点数的计划。只有第一类应当执行,其余必须返回明确拒绝原因。再人为让第二步因缺预算数据停下,观察第一步结果是否保留、第三步是否被禁止;最后在页面退出后恢复任务状态,确认不会重新运行已经成功的写入动作。
排查顺序先看计划是否合法,再看节点状态机,再看授权,最后看外部工具日志。不要只盯着模型回答是否流畅;一个看似连贯的“我已经帮你安排好”可能只是总结文案。下一篇专门讨论用户确认与设备权限,把“草稿已生成”和“系统日程已写入”彻底拆开。

图 03:AI 生成的 HarmonyOS 风格手机操作界面,所有页面数据用于功能说明。
执行器不需要知道模型“思考过程”里为什么选择这些步骤,只需要验证计划结构与业务规则是否允许。这样可以减少对模型输出格式变动的依赖,也更有利于测试人员构造非法计划。每次版本变更都要检查已完成节点的重用条件,尤其是修改预算或出发日期后,哪些结果必须重新计算。让流程正确停止,比让流程盲目走到底更重要。
八、本篇小结与下一篇预告
本篇将具体问题限定在可观察的调用链、可复现的业务规则与明确的拒绝分支中,给出了代码与手动验证顺序。尚未在目标设备上验证的系统行为应继续按当前 SDK 与官方文档核实。下一篇专门处理授权门禁与设备能力限制,确保草稿不被误写入系统。
官方核对资料
更多推荐


所有评论(0)