117 lines
4.2 KiB
Markdown
117 lines
4.2 KiB
Markdown
# 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 边界来裁决，而不是回退到早期直连协议思路。
|