授权门禁与设备能力|日程草稿被直接写入系统:授权、提醒限制和能力降级 —— HarmonyOS Agent×Skill 实战 06 封面

图 01:AI 生成的技术主题封面。

一、先看故障现象

AI Agent 最容易越界的瞬间,是把“帮我想好”理解成“替我执行”。用户让行旅助手安排周五出行事项,界面生成时间卡片是一个结果,直接向系统日历写入事件却是另一个结果。两者之间应该存在明确、可重复验证的确认步骤;不能让一句模型提示词成为授权凭证。

二、问题为什么会出现

本篇采用两个层级的操作模型。只读或本地草稿类可以直接执行,例如生成出行清单、计算费用、创建可编辑的日程草稿;写入系统日历、发送通知、共享给其他应用属于有副作用的动作,即使是用户主动提到,也应展示对象、时间、内容和将受影响的数据。用户确认的是这一次具体操作,不是对某个通用 Agent 的永久无限授权。

我们为写操作增加 confirmation token。它绑定 taskId、skill 名称和参数摘要,用户只批准这一份确定内容;如果日期或目的地改变,旧 token 自动失效。执行器检查 token 后仍使用 idempotencyKey 拦截重复提交。这个门禁处于模型与系统 API 之间,不能绕过:模型只能建议创建日程,不能给自己发“已批准”的状态,也不能通过改写自然语言骗过执行器。

HarmonyOS 的系统能力接入还存在版本、权限和设备差异。比如官方的代理提醒文档明确指出,手机、平板和 PC/2in1 设备可能受管控,符合条件的应用需要按要求申请权益,或者考虑 Calendar Kit 等替代路径。代理提醒不是通用的“任何第三方都能随手使用”的后台能力。示例项目没有对系统日历真正写入,只给出适配接口的设计边界,避免文章教读者绕过审核或假设所有设备行为一致。

用户拒绝授权后,应当将任务状态变成 declined 或 waiting_approval,而不是进入自动重试。权限不足与网络超时是两类不同问题。网络超时可以依据幂等规则谨慎重试,权限不足必须先解释原因并等待用户主动操作;反复弹出权限请求既影响体验,也可能触发平台合规问题。系统权限声明应与实际功能一致,不以“未来可能用到”为由一次性申请大批敏感权限。

如果关联日历的能力在当前设备不可用,正确降级并不是偷偷保存到其他位置,而是把可复制的日程内容展示出来,让用户自行确认或手动导入。降级后的页面应明确“已生成草稿,未创建系统日历事件”,并保留重试入口,但不得伪造成功状态。一个可靠的 Agent 能清晰说明没做成什么,这往往比硬凑出完成文案更能建立用户信任。

还有一个常被忽视的撤销场景:用户点击“确认”后立刻修改行程,可能出现授权前后的参数不一致。后端应将授权票据与参数摘要绑定,真正执行前重新计算摘要;不一致就重新询问。不要保存一枚长期有效、可用于任意日程的 token。敏感数据日志也不应该包含完整日程标题、家庭地址、联系人手机号等内容,只保留必要的 traceId 与状态。

三、实现取舍和系统边界

架构上将 DeviceAdapter 与 AgentPolicy 分开。DeviceAdapter 检查具体系统能力是否可用、是否持有许可并执行调用;AgentPolicy 判断当前动作是否允许、是否已获确认。即使平台 API 调用成功,未通过 AgentPolicy 的操作也不应发生。审批标记应写入可恢复的事务状态,用户修改参数后重新审查,并对外展示结果究竟处于“草稿”“等待授权”还是“已创建”。

本篇不会教读者假定某个 HarmonyOS 权限从所有版本开始都开放,更不会为了文章效果编造成功通知。接入 Calendar Kit、系统授权或代理提醒时,应再查询目标设备与当前版本的官方开发文档,按实际 AppGallery Connect 申请条件实施。

四、关键代码与实现路径

以下代码对应下载包中的 项目源码,业务层代码可使用 Node.js 18+ 运行;涉及 scriptManager 的片段需要集成到 Stage 模型并按目标 SDK 验证。所给例子并不包含任何实际订票、真实支付或自动写入系统日历的实现。

import { Gate } from './agent-core.mjs';
const gate = new Gate();
const request = gate.request('trip-123', 'schedule_draft', 'hash-abc');
// 未获用户确认时拒绝写入
console.log(gate.execute(request.token, 'trip-123:schedule_draft'));
gate.approve(request.token); // 必须由用户确认事件触发
console.log(gate.execute(request.token, 'trip-123:schedule_draft'));
console.log(gate.execute(request.token, 'trip-123:schedule_draft')); // replayed

这段实现重点在于将“模型或系统提出的意图”与“程序真正允许执行的业务动作”分开:参数先经校验,再交给业务函数,最后用明确状态或错误码回报。不能直接用一句“执行成功”作为真实设备操作的证据。

授权门禁与设备能力 开发环境

图 02:AI 生成的 DevEco Studio 风格开发界面,代码窗口、调试状态与项目名称用于讲解本文排查位置。

五、四类高频踩坑与修复证据

坑 1:用户只想看草稿,系统日历却新增了事件

表现:用户只想看草稿,系统日历却新增了事件。

原因:将模型语言中的“安排”当作不可撤销的写入授权。

处理:将草稿生成与系统写入拆成两步,写入前展示详细确认卡片。

复验:未点击确认时核对系统日历没有任何新增记录。

坑 2:点了两次确认,出现两条重复提醒

表现:点了两次确认,出现两条重复提醒。

原因:提交按钮、网络重试和异步回调未共享幂等键。

处理:把 taskId、操作类型和参数摘要关联成稳定 idempotencyKey。

复验:连续提交、断网恢复和页面重建后检查只执行一次。

坑 3:权限不够时不断弹窗或循环重试

表现:权限不够时不断弹窗或循环重试。

原因:把权限拒绝误判成短时网络失败,重复请求不会改变授权状态。

处理:权限错误直接停止并说明手动授权路径,允许用户主动重试。

复验:关闭权限后连续操作,应只产生受控的失败提示而非弹窗风暴。

坑 4:系统能力不支持却展示“安排成功”

表现:系统能力不支持却展示“安排成功”。

原因:业务层没有区分草稿、系统成功和降级完成三种状态。

处理:设备不可用时只返回草稿,系统事件 ID 只有实际成功后才能记录。

复验:在不支持的设备或测试配置里检查没有伪成功事件和未声明的数据写入。

六、深入复盘:工程上还要补什么

授权不是一句“好的”,而是可验证的具体对象

在聊天窗口中,用户可能说“没问题”,但这句话到底批准了哪项操作?如果上一轮同时展示了预算估算、清单生成和两个不同时间的日程草稿,模糊肯定无法证明用户同意了某个确定的写入。授权页面应列出目标操作、时间、地点、内容及影响范围,让用户明确选择确认或取消。授予授权后,还需将该次授权与参数摘要绑定;只要任意关键字段修改,就要求再次确认。

对于真正有副作用的操作,系统权限与用户业务同意是两条不同防线。应用即使获得日历写入权限,也不代表用户授权 Agent 在任何时间创建任何事件;反过来,用户点击确认也不代表应用已经具备系统权限。只有两层条件都满足,设备适配层才尝试执行。异常时应该准确告知“需要系统授权”“本设备不支持”或“日程草稿待确认”,而不是用单一“失败了”覆盖全部情况。

设备限制不应该成为欺骗用户的理由

官方代理提醒能力受到设备类型、管控条件与应用类别限制。对于工具、效率、旅游等可能符合申请条件的场景,也仍然要按照当前官方流程申请并验证。开发者不能只看到一个示例 API 就推断所有新系统设备均可用。如果没有权益或者用户拒绝通知权限,页面只保留草稿和手动方式,这是可接受的产品降级。对新设备和不同版本,应该重新检查支持矩阵,而不是照搬某个旧系统的代码与结论。

真正接入系统日历时还可能涉及时区变化、重复事件和事件更新。比如用户在北京生成周五 8:30 的提醒,出发前跨越时区,再编辑日程,不能依赖界面里的字符串直接判断系统事件 ID 是否相同。设备层应返回可验证的外部记录标识,业务层保存该标识与用户可见操作的对应关系。示例项目暂未实现这一层,因此只能声称“具备预留的设备适配接口与确认门禁”,不能声称“已创建日历事件”。

把拒绝路径当成正常使用路径

用户可能明确点击“暂不允许”,这应该是正常业务结果,不是程序崩溃。拒绝后不要原地重复弹窗、再次尝试秘密调用或者把任务标记为成功。更好的状态是“已保存草稿,未写入系统”,并提供撤回、修改、复制草稿的能力。若用户稍后改变主意,应重新读取当前草稿、重新核对待提交参数,并启动一轮新的明确授权。这样做可以避免旧 token 在改过日期之后继续生效。

此处的 Gate 类仅示例确认与幂等业务规则,不提供系统权限申请,也不能代替权限审核。开发者把示例接入现有 HarmonyOS 应用时,需要针对真正使用的 Calendar Kit 或其他系统能力查看最新权限要求,并在设备上验证系统交互。

七、运行、验证与边界检查

核心测试包括:未审批写操作应拒绝;审批后第一次执行成功;同一幂等键再次提交只返回已处理状态;用户修改参数后旧授权不可使用;拒绝授权时绝不自动重试。再补一组平台侧手动核对:权限是否属于系统授权、是否存在申请权益、设备是否支持、失效后的 UI 是否明确。项目代码中的 Gate 类可验证前半部分,但不能证明设备级授权已经接入。

线上排查时先看“审批是否存在”和“参数是否匹配”,再看系统 API 的错误码,最后才研究网络和生命周期。把这几层顺序颠倒,可能使开发者在日志里寻找根本不存在的系统缺陷。下一篇关注另一类越界:外部文本本来只是资料,却试图操纵 Agent 直接执行指令。

授权门禁与设备能力 手机效果

图 03:AI 生成的 HarmonyOS 风格手机操作界面,所有页面数据用于功能说明。

在产品设计中,可以把确认门禁做成一个复用组件:它接收操作摘要、风险级别、预计影响和取消回调,由业务层生成具有唯一标识的授权票据。不同能力共用门禁,但不会共用永久授权。这样的设计方便未来接入更多 Skill,也能让测试人员用同样的方法验证每个有副作用的操作。若未完成系统 API 接入,门禁仍可独立测试,这就是把业务安全与设备环境分离的价值。

八、本篇小结与下一篇预告

本篇将具体问题限定在可观察的调用链、可复现的业务规则与明确的拒绝分支中,给出了代码与手动验证顺序。尚未在目标设备上验证的系统行为应继续按当前 SDK 与官方文档核实。下一篇讨论外部网页和历史资料如何污染 Agent 上下文,并给出隔离办法。

官方核对资料

Logo

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

更多推荐