# Agent 工具与运行时边界

**版本：** 2026-08-07 整合版  
**主来源：** `01.当前有效设计/02.正式方案/运行时与智能体工具.md`  
**辅助来源：** `01.当前有效设计/APP架构设计.md`、`90.历史设计归档/01.前期分析与设计/tool-action-design.md`

## 1. 当前权威结论

当前最重要的结论是：

**Agent Tool 是 Runtime 发布给远端 Agent 的受控调用契约，不是用户按钮，也不是 MiniApp 内部函数的别名。**

这是当前设计相对于早期草案最重要的收敛之一。

## 2. Agent 当前扮演什么角色

远端 Agent 当前应该被理解为：

- 用户意图的理解者；
- Runtime 已发布能力的调用者；
- 结果解释与后续编排者。

它不应该被理解为：

- 本地 Runtime 的替身；
- MiniApp 内部状态的直接操作者；
- Host 权限的直接调用者；
- 任意前端函数的远程执行入口。

## 3. 三条入口必须分开

当前有效设计明确把三条入口区分开了：

### 3.1 Agent Tool

由远端 Agent 发起，经过 Runtime 校验、持久化、路由和回传。

### 3.2 本地 UI Action

由用户在 MiniApp 页面中的点击、输入、拖动等触发，经 SDK / Surface Bridge 进入 Runtime。

### 3.3 Host 生命周期意图

由前后台切换、返回、关闭、恢复、锁屏等本地环境事实触发，经 Runtime 的生命周期裁决进入状态机。

这三条入口可以复用内部业务动作，但不能混同身份。

## 4. 为什么早期工具三分法不能直接作为当前主模型

`agent_ops/设计/01.前期分析与设计/tool-action-design.md` 中的 `app / toolset / action` 三分法，在早期用于说明不同工具形态，很有价值；但它已经不能完整表达当前 Runtime 模型，原因是：

- 当前 Runtime 要管理 Inventory 可见性；
- 要管理 Tool Call 的幂等、状态、回执和终态；
- 要管理激活过程、App 就绪条件、前台要求和 operation；
- 要把 Tool、MiniApp instance、子会话、业务 operation 区分开。

因此，当前主模型应优先使用：

- Agent Tool；
- Agent Inventory；
- Tool Call；
- 协议回执 / 进度；
- 业务结果；
- MiniApp activation；
- operation。

## 5. 当前 Runtime 对 Tool 的唯一所有权

Tool 相关的这些职责都必须由 Runtime 统一承担：

- 发布 Inventory；
- 校验调用；
- 做幂等去重；
- 决定是否可见；
- 决定是否允许启动或复用 MiniApp；
- 持久化业务状态与 outbox；
- 回传协议回执与最终结果。

这意味着：

- MiniApp 不能自己向 Agent 宣传 Tool；
- Surface 不能直接把前端动作伪造成 Tool Call；
- Agent 不能绕过 Inventory 直接指定任意 instance 或内部函数；
- Host 事件也不能伪造成 Tool 调用。

## 6. 当前与项目实际情况一致的几个重点

结合当前 `lineup-app` 的实现方向，以下几个判断具有最高优先级：

- Tool 是 Runtime 语义的一部分，不是单独漂浮在外的协议层；
- Interact / MiniApp / Workspace / Focus / Lifecycle 与 Tool 调用之间已经形成一套统一模型；
- 长时业务行为需要区分“调用被接受”“激活已就绪”“业务已开始”“业务已完成”；
- 用户本地操作、Agent 远程调用和 Host 生命周期变化必须各自可审计、可恢复。

## 7. 对旧设计中仍可保留的部分

早期协议文档中这些认识仍然有价值：

- 结构化调用比自然语言裸发更稳定；
- 工具定义需要 schema 化；
- 消息需要统一信封与版本化；
- 调用与返回需要成对、可追踪。

但这些内容如今应作为当前 Runtime Tool 模型的背景，而不是替代它。

## 8. 本轮整合后的使用建议

如果后续在设计、实现或迭代文档里出现以下歧义，优先按本文判断：

- 某个按钮是不是 Agent Tool；
- 某个本地事件能不能当成 Tool 调用；
- 某个 MiniApp 能不能直接发消息给 Agent；
- 某个 operation 是否等同于一次 Tool Call；
- 某个实例 ID 是否能由 Agent 任意指定。

这些问题的默认答案，都应该先经过 Runtime 边界来裁决，而不是回退到早期直连协议思路。