> For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt.

# Agent 与端侧交互

本文说明 Agent 与端侧协作时的执行主体、数据方向和生命周期。完整接入示例见[端工具开发](/apps-plugin/docs/frontend-development/client-tools.md)和[全页开发](/apps-plugin/docs/frontend-development/full-page.md)。

## 两条独立链路

| 能力          | 数据流向                               | 入口与执行主体                                                 | 成功证据                      |
| ----------- | ---------------------------------- | ------------------------------------------------------- | ------------------------- |
| Client Tool | Agent → 宿主 → handler → Tool Result | `app.config.ts.tools` 注册的默认函数在端工具运行时执行                  | 调用记录、真实返回值，绑定卡片时还需检查实体与渲染 |
| Agent Event | Agent → 宿主 → App → 页面订阅者           | Framework 接收事件，调用可选 `onAgentEvent` 并分发到 `useAgentEvent` | 事件记录、订阅回调、页面状态变化          |

```mermaid
flowchart LR
  Agent -->|tool call| Tool[Client Tool runtime]
  Tool -->|Tool Result| Agent
  Agent -->|business event| Host[Host and Framework]
  Host -->|useAgentEvent| Page
```

图中的两条路径分别验证。工具结果不会自动更新已打开页面；页面事件也不会自动回传 Tool Result。

## 端工具运行时

Kit 从 `app.config.ts.tools` 收集入口，生成端工具注册和启动代码；业务不手动调用 bootstrap。端工具产物与 App、Page / Widget 入口分开，不能依赖另一入口的模块变量、组件 state 或生命周期已经执行。

handler 必须默认导出函数，签名为 `(input: Record<string, unknown>) => unknown | Promise<unknown>`。Framework 对输入执行以下规范化：

- 缺省输入变为 `{}`；
- 对象输入直接传给 handler；
- JSON 字符串先解析为对象；非对象或解析失败按调用错误处理；

业务始终按对象接收，再校验字段及业务约束。调用只向 handler 传入这一个对象参数。

返回值需要满足当前端工具结果契约：

```ts
interface ClientToolResult {
  content: { type: 'text'; text: string }[];
  structuredContent?: Record<string, unknown> | Record<string, unknown>[];
  isError?: boolean;
  _meta?: Record<string, unknown>;
}
```

`content` 必须存在，目前仅支持文本块。运行时检查结果外形，不替代对 `outputSchema` 和业务数据的完整校验。成功的实体数组会逐项补充 `entity_type: <tool name>`；对象形式的 `structuredContent` 不做该补充。

返回 `isError: true` 表示业务失败；handler 抛错、返回不合法结果或工具不存在，则通过宿主调用结果反馈错误。不要假设端工具错误一定进入 Page 的 `useError` 或 App 的生命周期回调。

端工具使用函数默认导出。调用宿主能力前，先确认[端工具 JSB 白名单](/apps-plugin/docs/frontend-development/client-tools.md#jsb-调用限制)。端工具不能使用白名单之外的 JSB，包括路由能力；声明权限不能扩大白名单，已放行的接口仍需满足授权、宿主支持和限流条件。需要页面当前状态时，使用事先约定的数据通信方式。

## 事件接收与订阅生命周期

`events.json` 描述可发出的业务事件，Skill 中的 `{{event:<name>}}` 暴露对应事件。模型生成事件后，由宿主投递；Framework 的接收顺序是：

1. 如果 App 定义了 `onAgentEvent(name, payload)`，调用它；
2. 将 payload 分发到应用事件通道中对应的业务事件；
3. `useAgentEvent(name, callback)` 的订阅者执行回调，由业务更新状态；

未定义 App 回调不影响订阅分发。手动重复转发会造成重复处理。App 回调适合应用级处理或观察；页面回调适合更新当前页面展示。

Hook 通过 Effect 注册订阅，事件名变化或组件卸载时取消旧订阅，并使用最近一次渲染的 callback。它不按页面栈顶、业务 ID 或可见性筛选，也不存储和重放历史 payload。因此：

- 先打开并挂载页面，再发送更新事件；
- 使用业务对象或任务标识检查目标归属；一个任务有多个实例时进一步区分实例；
- 隐藏但仍挂载的页面可能继续收到事件，必要时结合显示与隐藏生命周期限制处理；
- 重复投递不能重复扣款、提交订单或累加状态；需要此类操作时使用具有业务幂等性的服务接口；
- 重建页面时从可信数据源恢复状态，不依赖错过的事件；

`payload` 类型是 `Record<string, unknown>`。同步回调错误由事件通道交给 App 错误处理，不阻断其他监听器；异步请求应自行捕获 rejection，并处理页面销毁或请求过期。
