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