HarmonyOS API 26 HMAF Skill 可解释任务计划与失败回退

适用版本：HarmonyOS API 26。 本文讨论 HMAF Skill 的应用侧任务编排：把自然语言意图拆成可审计动作，做权限与参数校验，再为超时、拒绝和部分成功提供明确回退。示例只描述 ArkTS 风格模型，不声称已完成 HarmonyOS 编译、系统解析、ArkUI 联调或真机测试。

CSDN-SERIES:HARMONYOS-BATCH-160

一、问题边界：Skill不等于系统能力

Skill 是应用侧可声明、可撤销、可观测的动作契约。平台 API 26 提供运行环境边界，但不会替应用决定参数来源、用户确认和失败补偿。

二、任务输入契约

export interface SkillIntent { readonly id: string; readonly action: string; readonly args: Readonly<Record<string, string>>; readonly deadlineMs: number }
export interface SkillPlan { readonly intentId: string; readonly steps: readonly SkillStep[]; readonly requiresConfirm: boolean }
export interface SkillStep { readonly id: string; readonly capability: string; readonly timeoutMs: number; readonly retryable: boolean }

输入先做字段白名单和截止时间校验，拒绝未知能力，避免自然语言参数直接穿透到系统调用。

三、动作图而不是黑盒调用

每一步都记录 pending、running、succeeded、failed 和 compensated，动作图才能回答“为什么执行”和“失败后做了什么”。

export type StepState = 'pending' | 'running' | 'succeeded' | 'failed' | 'compensated'
export interface StepEvent { readonly stepId: string; readonly state: StepState; readonly at: number; readonly reason?: string }

四、权限分层与确认点

只读查询可直接执行；写入、跨应用和涉及个人数据的动作必须标记 requiresConfirm。确认状态属于一次任务事务，不应使用全局布尔值代替。

五、超时与重试预算

export function nextRetry(attempt: number, maxAttempts: number, deadlineMs: number, nowMs: number): number | null {
  if (attempt >= maxAttempts || nowMs >= deadlineMs) return null
  return Math.min(250 * 2 ** attempt, Math.max(0, deadlineMs - nowMs))
}

重试只允许作用于幂等步骤；确认步骤、权限拒绝和契约不匹配不得自动重试。

六、失败分类

错误	是否重试	用户路径
TIMEOUT	有预算时	延迟后重试
PERMISSION_DENIED	否	展示授权或取消
CONTRACT_MISMATCH	否	修改输入
PARTIAL_SUCCESS	视步骤而定	查看已完成动作

七、部分成功与补偿

export interface PlanResult { readonly completed: readonly string[]; readonly failed: readonly string[]; readonly compensations: readonly string[] }
export function canCompensate(step: SkillStep, result: PlanResult): boolean { return result.completed.includes(step.id) && step.capability !== 'irreversible' }

补偿动作必须可审计、可取消，不能假设外部系统一定支持回滚。

八、端侧A2A边界

A2A 消息只携带意图 ID、动作 ID、能力名和最小参数，不传递无关上下文。接收方再次校验来源、有效期和权限，避免把上游信任当作本地授权。

九、UI状态映射

页面消费 planning、waitingConfirm、running、partial、error 和 success 六种状态。每个失败态都给出重试、修改输入或取消入口，不把异常吞成空白页。

十、可观察性字段

export interface PlanEvidence { readonly traceId: string; readonly intentId: string; readonly stepId: string; readonly state: StepState; readonly latencyMs: number; readonly reason?: string }

只记录必要的标识与指标，不记录原始隐私内容；日志留存周期和清理动作由应用策略决定。

十一、并发与去重

同一 intentId 的计划只能有一个活动实例。重复提交返回已有状态，不重复执行不可逆动作。

export function shouldJoin(intentId: string, active: ReadonlySet<string>): boolean { return active.has(intentId) }

十二、失败回退清单

执行器至少覆盖：参数缺失、权限拒绝、超时、下游不可用、用户取消和补偿失败。回退结果要带 reason，方便客服与开发复盘。

十三、API26版本与能力声明

本文目标版本是 HarmonyOS API 26（Version 26）。HMAF、Skill、A2A 均按应用侧概念建模，具体平台能力、权限和生命周期仍需对照官方文档确认，不能把示例接口当成系统内置 API。

十四、纯逻辑测试边界

本地测试只验证计划生成、权限分层、重试预算、去重和回退决策；未执行系统编译、ArkUI 联调、模拟器或真机验收。

十五、回归矩阵

覆盖空输入、未知能力、重复意图、权限拒绝、超时重试、部分成功、补偿失败、取消和小窗口状态切换。每条用例记录输入、动作图和最终状态。

十六、官方资料

• ArkTS 概览
• AbilityKit 概览

十七、小结

可解释 Skill 的关键不是让智能体“自动做更多事”，而是让每一步都有权限边界、超时预算、失败原因和可恢复路径。围绕 API 26 组织这些应用侧契约，才能在后续接入真实平台能力时保持可审计和可回归。

十八、明确验证边界

本文未执行 HarmonyOS 编译、系统解析、ArkUI 联调或真机测试；本地结果仅覆盖纯逻辑策略。接入真实 HMAF、Skill 或 A2A 能力时，应先核对官方 API 26 文档、权限声明和生命周期，再按同一回归矩阵补齐设备证据。

十九、计划版本与幂等键

计划应携带 planVersion 和 intentId。服务端或端侧执行器看到相同幂等键时返回已有结果，不重复触发写入动作；计划版本变化则重新做权限与参数校验。

export interface PlanKey { readonly intentId: string; readonly planVersion: number }
export function samePlan(a: PlanKey, b: PlanKey): boolean { return a.intentId === b.intentId && a.planVersion === b.planVersion }

二十、可恢复路径的用户提示

错误提示应说明“已完成什么、还剩什么、下一步能做什么”。例如部分成功时展示已完成动作列表，并提供继续、撤销或重新规划按钮；权限拒绝时提供设置入口或安全取消，不循环弹窗。

export function userAction(state: StepState): 'retry' | 'confirm' | 'cancel' | 'done' {
  if (state === 'failed') return 'retry'
  if (state === 'pending') return 'confirm'
  if (state === 'succeeded') return 'done'
  return 'cancel'
}

二十一、端到端复盘问题

复盘时按 traceId 回答四个问题：意图是否被正确解析、权限是否在执行前确认、失败是否落在可重试边界、用户是否能看到并控制回退。任何一个问题没有证据，就把它列为下一轮工程任务，而不是用“执行成功”概括。

二十二、最小落地顺序

第一步只接入纯函数计划器，固定输入和输出结构；第二步接入本地权限策略与确认 UI；第三步接入可取消的执行器；最后才接入跨能力或 A2A 通道。每一步都保留上一阶段的回退路径，避免一次性把解析、授权、执行和日志耦合在同一回调中。这个顺序也方便在 API 26 版本变化时替换单个适配层，而不影响上层动作图和用户提示。

二十三、交付前检查表

交付前逐项核对：标题是否写明 API 26 版本；动作图是否有唯一 traceId；权限拒绝是否可解释；超时是否受截止时间约束；重复意图是否幂等；部分成功是否展示已完成动作；日志是否去除原始隐私内容；页面是否提供取消和重试。检查表通过后，再进入真实平台能力的单点接入和人工验收。

二十四、接入前检查清单

HarmonyOS AP正式接入前，工程侧要过一遍检查清单：SDK 版本与目标 API 版本匹配、权限在清单中声明且按需申请、能力开关在专用配置层管理、包体积增量符合预算。任何一项不过就先停，带着不匹配的版本往上冲，排错成本会翻倍。

interface PrecheckItem { name: string; pass: boolean; note?: string }
const checklist: PrecheckItem[] = [
  { name: 'SDK/API版本匹配', pass: false },
  { name: '权限声明完整', pass: false },
  { name: '开关集中管理', pass: false },
  { name: '包体积增量<预算', pass: false },
]
const allPass = checklist.every(x => x.pass)

检查清单跑通的标志是：新建工程按清单接入一次成功，且不依赖任何口头经验。做不到，说明文档还缺关键步骤。

二十五、常见坑与版本适配记录

HarmonyOS AP最常踩的坑集中在三处：示例代码用的旧接口在新版本被拆分、默认配置与生产预期不一致、调试环境与真机行为有差异。每踩一个坑就记进版本适配表，注明坑点、影响版本、修复方式与验证方式。

interface Pitfall { issue: string; sinceApi: string; fix: string; verifiedOn: string[] }
const pitfalls: Pitfall[] = []
function knownPit(api: string): Pitfall[] { return pitfalls.filter(p => p.sinceApi === api) }

适配表的价值在升级时兑现：每次目标版本变更，先对照表过一遍已知坑，能省下一整轮盲目排查。

二十六、回归口径与停止线

HarmonyOS AP的任何改动合入前都要回答同一个问题：怎么证明没有把好的部分改坏。回归口径必须落在纸面：上一版通过的用例清单全量重跑、上一版记录的基线值全量对比、新增能力补一条专属用例。三件事缺一件，回归就是走过场。

interface RegressionGate { lastPassedCases: number; rerun: number; baselineCompare: 'PASS' | 'FAIL'; newCaseAdded: boolean }
function gateOk(g: RegressionGate): boolean { return g.rerun === g.lastPassedCases && g.baselineCompare === 'PASS' && g.newCaseAdded }

停止线同样要提前写明：同一问题打回三次、回归连挂两轮、或验证环境与目标环境指纹不一致，满足其一就停下来复盘流程，而不是继续硬修。把停止线当成流程的一部分，才能避免在小问题上耗掉整块的排期。