Agent 与端侧交互
本文说明 Agent 与端侧协作时的执行主体、数据方向和生命周期。完整接入示例见端工具开发和全页开发。
两条独立链路
图中的两条路径分别验证。工具结果不会自动更新已打开页面;页面事件也不会自动回传 Tool Result。
端工具运行时
Kit 从 app.config.ts.tools 收集入口,生成端工具注册和启动代码;业务不手动调用 bootstrap。端工具产物与 App、Page / Widget 入口分开,不能依赖另一入口的模块变量、组件 state 或生命周期已经执行。
handler 必须默认导出函数,签名为 (input: Record<string, unknown>) => unknown | Promise<unknown>。Framework 对输入执行以下规范化:
- 缺省输入变为
{}; - 对象输入直接传给 handler;
- JSON 字符串先解析为对象;非对象或解析失败按调用错误处理;
业务始终按对象接收,再校验字段及业务约束。调用只向 handler 传入这一个对象参数。
返回值需要满足当前端工具结果契约:
content 必须存在,目前仅支持文本块。运行时检查结果外形,不替代对 outputSchema 和业务数据的完整校验。成功的实体数组会逐项补充 entity_type: <tool name>;对象形式的 structuredContent 不做该补充。
返回 isError: true 表示业务失败;handler 抛错、返回不合法结果或工具不存在,则通过宿主调用结果反馈错误。不要假设端工具错误一定进入 Page 的 useError 或 App 的生命周期回调。
端工具使用函数默认导出。调用宿主能力前,先确认端工具 JSB 白名单。端工具不能使用白名单之外的 JSB,包括路由能力;声明权限不能扩大白名单,已放行的接口仍需满足授权、宿主支持和限流条件。需要页面当前状态时,使用事先约定的数据通信方式。
事件接收与订阅生命周期
events.json 描述可发出的业务事件,Skill 中的 {{event:<name>}} 暴露对应事件。模型生成事件后,由宿主投递;Framework 的接收顺序是:
- 如果 App 定义了
onAgentEvent(name, payload),调用它; - 将 payload 分发到应用事件通道中对应的业务事件;
useAgentEvent(name, callback)的订阅者执行回调,由业务更新状态;
未定义 App 回调不影响订阅分发。手动重复转发会造成重复处理。App 回调适合应用级处理或观察;页面回调适合更新当前页面展示。
Hook 通过 Effect 注册订阅,事件名变化或组件卸载时取消旧订阅,并使用最近一次渲染的 callback。它不按页面栈顶、业务 ID 或可见性筛选,也不存储和重放历史 payload。因此:
- 先打开并挂载页面,再发送更新事件;
- 使用业务对象或任务标识检查目标归属;一个任务有多个实例时进一步区分实例;
- 隐藏但仍挂载的页面可能继续收到事件,必要时结合显示与隐藏生命周期限制处理;
- 重复投递不能重复扣款、提交订单或累加状态;需要此类操作时使用具有业务幂等性的服务接口;
- 重建页面时从可信数据源恢复状态,不依赖错过的事件;
payload 类型是 Record<string, unknown>。同步回调错误由事件通道交给 App 错误处理,不阻断其他监听器;异步请求应自行捕获 rejection,并处理页面销毁或请求过期。