# 运行时与智能体工具

**版本：** 0.1（当前 Runtime 契约）  
**状态：** 已确认  
**日期：** 2026-08-06  
**关联方案：** [LineUp App 最终设计方案](app_final_design.md)、[LineUp Runtime 与 App SDK 架构方案](lineup-runtime-sdk-architecture.md)、[第 04 次迭代：Runtime 工作区与 Pomodoro MiniApp](../../迭代/04.runtime_workspace/04.runtime_workspace.md)

---

## 0. 目的与权威范围

本文定义 Runtime 面向远端 Agent 的工具模型，以及它与本地 MiniApp 界面操作、Host 生命周期事件之间的边界。它是全局 Runtime 设计，Pomodoro 只是当前的具体例子，并不限制本文的适用范围。

本文确认的关键结论是：

> **Agent Tool 是 Runtime 发布给远端 Agent 的功能调用说明书。它不是用户点击界面的公共入口，也不是 MiniApp 内部函数的别名。**

用户通常通过 IM 表达自然语言意图，未来也可以通过 Voice 表达；远端 Agent 负责理解意图、选择可见 Tool 并向 Runtime 发起调用。Runtime 负责校验、路由、执行、持久化和回传结果。用户未来可以在 MiniApp 页面点击按钮，但那属于另一条本地 UI Action 入口，不能伪装成 Agent Tool 调用。

本文细化 [LineUp App 最终设计方案](app_final_design.md) 中 Runtime、Tool、状态和边界的结论。后续若修改本文已确认的语义，必须先更新正式方案，再调整迭代定义和技术规范。

## 1. 术语与对象

| 术语 | 定义 | 不是 |
|---|---|---|
| **远端 Agent** | 运行在 LineUp 设备外、通过 AppServer / IM Transport 与 Runtime 通信的智能体。它理解用户自然语言，并在可见能力范围内选择 Tool。 | 不是 Runtime 内的计时器、存储或 UI 控制器。 |
| **Agent Tool** | MiniApp 在 Manifest 声明、Runtime 校验并发布给远端 Agent 的远程调用契约。它包含名称、说明、输入输出 schema、调用模型、可见性和策略。 | 不是用户按钮，也不是 App 任意 JavaScript 函数。 |
| **Agent Inventory** | Runtime 根据 App、Host、权限、策略、会话和 Agent 范围计算出的 Agent Tool 清单及其 revision。 | 不是安装包内全部函数的列表。 |
| **Tool Call** | Agent 对 Inventory 内某个 Agent Tool 发起的一次远端调用，带有 call_id、参数和 inventory revision。它可先收到协议回执和进度，最后才收到业务结果。 | 不等于业务 operation，也不等于 App instance。 |
| **Tool 协议回执 / 进度** | Runtime 对一条已接受调用的可重放协议事实，例如 `accepted`、`starting`、`activation_ready`、`started`；用于告诉 Agent 调用是否已接收、MiniApp 是否已就绪、业务是否真正开始。 | 不是 Tool 的业务 result，不受业务 output schema 约束，也不等于一次完成记录。 |
| **Tool 业务结果** | Tool 的最终业务结论；必须符合该 Tool Manifest 的 output schema，并且对同一 call_id 只持久化、回传一次。 | 不是“请求已收到”或“正在启动”的临时状态。 |
| **Runtime 内部业务动作** | Runtime 为实现业务请求执行的受控命令，例如创建 deadline operation、改变焦点、写 outbox、关闭实例。多个入口可以复用同一个动作。 | 不是自动公开给 Agent 的 Tool。 |
| **UI Action** | 用户在本地 MiniApp 页面点击、输入或拖动后，经 SDK / Bridge 发送给 Runtime 的本地请求。 | 不发布给 Agent，也不带 Agent 身份。 |
| **Host 生命周期意图** | Host 或工作区产生的前后台切换、返回、关闭、恢复、锁屏等本地事实或请求。 | 不是 Agent Tool，也不应伪造成用户的 IM 指令。 |
| **MiniApp instance** | 一个 MiniApp 的运行实例；Runtime 管理其生命周期、作用域和启动状态。 | 不必然对应一次业务 operation。 |
| **App 子会话** | Interact 中围绕一个 MiniApp instance 保存的、面向人与 Agent 的交互记录。 | 不等于一次专注、计时或其他业务 operation。 |
| **MiniApp activation** | Runtime 管理的一次 MiniApp 启动过程：`starting → ready | failed | cancelled`。每个 Agent Tool 声明业务执行前要求的就绪条件。 | 不是 MiniApp 的业务数据，也不是 operation。 |
| **MiniApp session data** | Runtime 为当前 `app_scope + app_session_id` 持久化的通用 JSON 数据字典；内容和可变性由 MiniApp 自己定义。 | 不是 Runtime 可理解的 App 业务 schema，也不是 IM 记录或 operation Store。 |
| **operation** | Runtime 管理的实际业务执行单元，例如一次有 deadline 的专注。它有独立的状态机和终态。 | 不等于 Tool Call、App 子会话或界面实例。 |

## 2. Agent 的角色、能力范围与边界

### 2.1 Agent 的职责

远端 Agent 是意图理解者和工具调用者，不是本地 Runtime 的替身。它的职责是：

1. 从用户 IM、Voice 或其他交互内容理解意图；
2. 根据 Runtime 已发布的 Agent Inventory 选择合适的 Tool；
3. 按 Tool schema 构造参数，并携带当前 inventory revision 发起调用；
4. 接收 Runtime 回传的受控结果，在用户会话中解释、追问或发起下一步调用。

当用户说“现在开始 20 分钟的冥想，帮我计时”时，正确链路如下：

~~~text
用户的 IM 消息
  → 远端 Agent 理解为启动专注
  → Agent 调用 pomodoro.start
  → Runtime 请求 Pomodoro 进入前台
  → Host 确认前台激活后，Runtime 才创建并管理专注 operation
  → Pomodoro MiniApp 用自身 session data 显示界面
~~~

Agent 不需要、也不能自己一秒一秒倒数。时间事实由 Runtime 持久化的 deadline 和本地时间裁决；MiniApp 仅根据 Runtime 投影显示剩余时间。

### 2.2 Agent 可做的事

- 调用当前 Agent Inventory 中、对当前 Agent 和 conversation 可见的 Agent Tool；
- 接收 Runtime 回传的 Tool 结果、进度和受控交互结果；
- 在会话范围内发送内容、交互或后续 Tool 请求；
- 在 Runtime 允许的范围内请求启动 Tool 所需的 MiniApp instance。

### 2.3 Agent 明确不能做的事

- 不能调用未在当前 Inventory 中声明的 Tool，或绕过 inventory revision、参数 schema、会话和策略校验；
- 不能直接读写 Runtime Store、MiniApp instance state、Conversation Store、operation Store、outbox 或审计记录；
- 不能直接调用 Tauri、文件、通知、麦克风、窗口或其他 Host 特权能力；
- 不能直接执行 MiniApp 的任意函数、修改其 DOM 或访问 Surface Bridge；
- 不能指定、伪造或跨会话操控任意 instance_id、operation_id、app_scope；
- 不能通过 Tool Call 绕过 App 安装、启用、权限确认、风险策略或 Host 能力限制。

Runtime 对 Agent 输入实行不信任原则：即使调用来自已认证 Agent，也必须重新验证可见性、作用域、幂等、生命周期和输出。

## 3. 三条独立入口

Runtime 可以接收不同来源的请求，但来源决定身份、校验、审计和可用能力。三者不是同一入口。

| 入口 | 发起者 | Runtime 接收的内容 | 是否进入 Agent Inventory | 主要校验 | 典型示例 |
|---|---|---|---|---|---|
| **Agent Tool** | 远端 Agent | 有 Agent 身份、call_id 和 inventory revision 的远端 Tool 调用 | 是 | Agent、Inventory、Tool schema、conversation、策略、幂等 | Agent 调用 pomodoro.start。 |
| **MiniApp UI Action** | 用户在本地 MiniApp 页面操作 | SDK / Bridge 发送的本地 Action | 否 | 当前 instance、App 权限、UI schema、业务前置状态、用户确认 | 用户未来点击开始计时。 |
| **Host 生命周期意图** | Runtime Shell、Host 或系统 | 前后台、返回、关闭、恢复、系统状态等本地事件 | 否 | instance 生命周期、焦点栈、系统策略、operation 收口规则 | 用户离开 Pomodoro 工作区。 |

三条入口的流程如下：

~~~text
一、远端 Agent Tool
用户 IM / Voice
  → 远端 Agent 理解意图
  → Agent Tool Call
  → Runtime 校验、路由和持久化
  → Runtime 内部业务动作
  → MiniApp 状态投影 / Agent 结果 outbox

二、本地 UI Action（未来可选）
用户点击 MiniApp 页面
  → SDK / Surface Bridge 的本地 Action
  → Runtime 校验和持久化
  → Runtime 内部业务动作
  → MiniApp 状态投影；必要时由 Runtime 产生 Agent 可见结果

三、Host 生命周期意图
返回 / 切换工作区 / 关闭 / 恢复 / 系统事件
  → Host Lifecycle Intent
  → Runtime 生命周期与焦点裁决
  → Runtime 内部业务动作 / operation 收口
  → MiniApp 状态投影 / 必要的 Agent 结果 outbox
~~~

后两条入口可以在 Runtime 内部复用与 Agent Tool 相同的业务服务。例如未来 UI 的开始按钮与 Agent Tool 的开始调用都可以请求同一个“创建专注 operation”动作。但复用内部动作不改变入口身份：UI Action 不会因此成为 Agent Tool，Host 生命周期也不会因此伪造成 Tool Call。

## 4. Agent Tool 的发布与调用

### 4.1 MiniApp 声明，Runtime 发布，Agent 调用

Agent Tool 的权威链条必须保持为：

~~~text
MiniApp 源码中的 SDK Tool 声明
  → 构建生成 Manifest 的不可执行 Tool 描述
  → Runtime 验证 Manifest、App 与 Host 条件
  → Runtime 计算并发布动态 Agent Inventory
  → 远端 Agent 看到 Inventory 后选择 Tool
  → Agent 发起 Tool Call
  → Runtime 验证、路由、执行并回传
~~~

MiniApp 只声明自己支持的候选能力，不能自行向 Agent 宣传、发送或执行 Tool Call。Runtime 是唯一的 Inventory 发布者、远端调用接收者和结果回传者。

Tool 声明的开发者入口是 MiniApp SDK，而不是第二份手写 Manifest：MiniApp 用 `defineAgentTools(...)` 同时声明
公开 method、schema、activation requirement 和 `miniapp_sdk` Tool 的本地 handler。SDK 源码声明是唯一真相；构建阶段
自动生成随 Bundle 安装的 Manifest Tool 描述。该描述供 Runtime 验证、Registry 和 Inventory 使用，但不包含 handler、
私有函数名或其他可执行内容。Bundle 内 SDK 保留 `method → handler` 映射，收到 Runtime 的统一 Tool 调用后在 MiniApp
内部分发。安装包仍可有 App 身份、版本、签名与 Host 能力等基础元数据，但开发者不再维护一份独立的 Tool 清单来重复
描述源码已经定义的能力。`runtime` Tool 只能引用 Runtime 内置的受控执行类型。这样既有类似 MCP Tool 描述文件的稳定
能力契约，也不让 Runtime 知道 MiniApp 的内部实现。

一个 Agent Tool Descriptor 至少应定义：

- 稳定的 app_scope、method、contract_version；
- 面向 Agent 的业务说明、输入 schema 和输出 schema；
- 调用模型，例如 query、command、interactive 或 operation；
- 幂等键、超时或终态规则；
- 启动就绪条件：`app_ready`（目标 MiniApp session 已 active、可接收方法调用）、`foreground_required`
  （在 app_ready 的基础上还必须已在前台），或 `activation_not_required`（只操作已有 Runtime 事实，不能因此
  启动或唤醒 MiniApp）；
- 所需权限、风险级别和对前台 / Host 的要求。

Runtime 实际发布给特定 Agent 的清单是动态交集：

~~~text
已验证的 Manifest Tool
  ∩ App 已安装并启用
  ∩ Host 当前支持
  ∩ 用户 / 组织策略允许
  ∩ 当前 Agent 与 conversation 可见
  ∩ 所需前置权限满足
~~~

### 4.2 Runtime 收到 Tool Call 后的职责

Runtime 收到远端 Agent Tool Call 后，按以下顺序处理：

1. 验证远端 Envelope、Agent 身份、conversation 关联和 Inventory revision；
2. 验证目标 Agent Tool 当前可见，且参数符合已发布 schema；
3. 用 call_id 执行幂等去重，持久化调用记录和审计；
4. 解析 Tool 所允许的作用域，不接受 Agent 任意指定跨会话目标；
5. 创建或复用 MiniApp activation，并在 Tool 所需的 `app_ready` 或 `foreground_required` 条件满足后，选择内部
   执行路径：直接处理、将 method 与已验证参数投递 App SDK、创建 operation 或拒绝；Runtime 不解释参数的
   MiniApp 业务含义，也不直接写 MiniApp 的 session data；
6. 原子持久化业务状态、operation 终态与需要回传的 outbox；
7. 仅向相关 MiniApp 投递经过裁剪的状态或调用投影；
8. 将协议回执 / 进度与最终业务结果分别持久化并经 outbox 回传：前者不使用业务 output schema；后者必须通过该 schema 校验。

Tool Call 的成功接收不等于业务已经完成。对于长期 operation，Runtime 可以先确认接受调用，业务真正开始时再报告
进度，之后只在进入唯一终态时回传最终结果。相同 `call_id` 重放时，Runtime 返回已持久化的**最新协议回执或最终
业务结果**，不重新执行业务，也不追加新的 outbox 消息。

### 4.3 activation 就绪通知与提前到达的后续调用

当 Agent 的一个 Tool 调用使 MiniApp 进入 `starting`，Runtime 必须把 activation 的受控状态作为与该 `call_id`
关联的协议进度通知给发起 Agent：

```text
accepted / starting
  = Runtime 已接受调用，MiniApp 正在准备

activation_ready
  = MiniApp 已 active / ready；后续要求 app_ready 的 Tool 现在可以接收

activation_failed / activation_cancelled
  = 本次启动不能继续；依赖它的等待中调用将得到受控失败结果
```

这些通知是 Runtime 持久化 activation 后，经 Runtime outbox 发出的事实；MiniApp、Surface 和 Host 只能向 Runtime
报告自己的就绪或失败，不能直接向 Agent 发送通知。公开通知只携带 `call_id`、`app_scope`、状态和受控 reason，不能
把 `instance_id`、`app_session_id` 变成 Agent 可指定或跨会话操控的目标。

Agent 收到 `activation_ready` 后再发送有依赖关系的后续 Tool，是推荐的编排方式；但它不是 Runtime 接收调用的硬前提。
若一条合法、同 conversation / app scope 的 `app_ready` 或 `foreground_required` Tool 在目标 activation 仍为
`starting` 时提前到达，Runtime 必须持久化该调用并把它挂到同一 activation 的等待队列，在 ready 后按已持久化的到达
顺序投递。activation 失败或取消时，Runtime 不执行这些 handler，而为各调用回传稳定的 `app_activation_failed` 或
`app_activation_cancelled`。`activation_not_required` Tool 不进入等待队列，仍立即处理；因此 Pomodoro 在启动中收到
`pomodoro.interrupt` 时可以立即取消启动。

某些 Tool 的业务进度比通用 activation 状态更强时，不应重复发两条没有新增信息的通知。第 04 次的
`pomodoro.start` 在 Host 确认前台的同一提交中同时得到 `activation = ready`、创建 operation 并开始计时，因此只向
Agent 发 `started`；它语义上已包含“Pomodoro ready”，且额外保证“前台已确认、计时已真实开始”。

## 5. 状态、身份与生命周期不得混同

本节是 Runtime 状态模型的一部分。下列对象可以互相关联，却不能共享语义或被一个 ID 替代。

~~~text
Conversation（人与主 Agent 的协作范围）
  ├── App 子会话（MiniApp 启动后可在 Interact 中保存的交互记录）
  ├── MiniApp instance（实际运行的界面 / SDK 上下文）
  │     ├── activation（starting / ready / failed / cancelled）
  │     └── session data（该 App 子会话的通用、MiniApp 自解释 JSON 数据）
  ├── Agent Tool Call（远端调用与其幂等、审计和回执）
  └── operation（实际业务执行；可无，也可独立于界面按规则收口）
~~~

| 对象 | 最小职责 | 应有的状态 / 身份 | 不能承担的事实 |
|---|---|---|---|
| Conversation | 用户与主 Agent 的协作边界 | conversation_id | 不能表示某次业务执行。 |
| App 子会话 | 保存围绕 MiniApp 的可见交互与历史 | app_session_id 或等价记录 | 不能替代 MiniApp instance 或 operation。 |
| MiniApp instance | 管理运行、焦点、挂起、关闭和 SDK scope | instance_id、生命周期状态 | 不自动代表一次业务 operation。 |
| MiniApp activation | 将 App 准备为 active / ready 的过程；某些 Tool 还要求成为前台 | instance_id、app_session_id、starting / ready / failed / cancelled | 不是业务 operation，不能自行产生 deadline 或终态。 |
| MiniApp session data | MiniApp 自己的业务 / 展示数据 | app_scope 加 app_session_id 加 revision | Runtime 不理解内容；不能裁决 deadline、Tool 终态或 outbox。 |
| Agent Tool Call | 一次远端请求、幂等与审计 | call_id、Tool key、inventory revision | 不能替代长期 operation。 |
| operation | 实际业务过程、deadline、进度和唯一终态 | operation_id、业务状态机 | 不等于一次 MiniApp 启动或 App 子会话。 |

因此，一个 MiniApp 会话或 instance 启动时未必启动业务 operation；一个 operation 也不应靠 UI 是否存在来判断是否完成。Tool 可以声明其业务开始是否需要前台：例如 `pomodoro.start` 只有在用户确实进入前台专注界面后才创建 operation；未来 `todo.add` 则可以在后台数据上下文就绪后完成。具体 Tool 的就绪条件不能上升为 Runtime 的统一前台要求。

Runtime 可以在一个原子事务中同时更新 operation、activation、session data 和 outbox，但它们仍保留各自的事实来源和恢复规则。

## 6. 各层能力边界

| 主体 | 负责什么 | 可以请求什么 | 明确禁止 |
|---|---|---|---|
| **用户** | 通过 IM / Voice 表达意图；未来可直接操作 MiniApp UI。 | Agent 对话；本地 UI Action。 | 不直接调用 Agent Tool 协议或 Runtime 内部 Store。 |
| **远端 Agent** | 意图理解、Tool 选择、调用参数和会话回复。 | 当前 Inventory 中的 Agent Tool。 | 直接访问 Host、Store、MiniApp DOM 或任意 App 函数。 |
| **Runtime** | Agent 通信、Tool Registry、校验、路由、状态、operation、生命周期、持久化、outbox、审计。 | 通过 Host Provider 使用受控系统能力；向 App 投递受限 SDK 投影。 | 将 Transport、密钥或跨 App 数据直接暴露给 Agent / MiniApp。 |
| **MiniApp** | 自己的界面、已声明业务处理和当前 App 子会话的 session data。 | SDK 提供的投影、声明性 Action、Capability request。 | 自行连接 Agent / AppServer、直接写 Runtime Store、直接使用 Tauri / Host。 |
| **Surface / UI** | 渲染和收集本地用户事件。 | 受限 Surface Bridge。 | 假冒 Agent、构造 Agent Tool Call、直接操作 Host DOM 或特权 API。 |
| **Host** | 提供窗口、通知、文件、音频等运行环境和系统事实。 | 向 Runtime 报告生命周期意图。 | 直接改变 MiniApp 业务状态、直接向 Agent 发布工具或交付特权能力。 |

特别地，Host 只报告本地事实或意图，最终如何改变业务状态由 Runtime 的业务规则裁决。例如“用户离开专注工作区”可触发 Runtime 中断当前专注，但 Host 不是在调用 pomodoro.interrupt，也不能假装成 Agent。

## 7. Pomodoro：第 04 次迭代的具体应用

第 04 次迭代用 Pomodoro 验证的是第一条入口，即 Agent Tool 到 Runtime 再到 MiniApp 投影。其冻结模型为：

~~~text
用户在 IM 中说：现在开始 20 分钟的冥想，帮我计时
  → 远端 Agent 调用 pomodoro.start
  → Runtime 创建 Pomodoro instance、App 子会话和 activation(starting)
  → Host 确认 Pomodoro 已成为当前前台 App
  → Runtime 创建 deadline operation，Pomodoro 进入 focusing 并被动显示

用户在 IM 中说：停止或结束这次专注
  → 远端 Agent 调用 pomodoro.interrupt
  → 若仍在 starting，Runtime 取消启动；若已 focusing，Runtime 原子收口当前 operation
  → Pomodoro 只接收通用 lifecycle 关闭通知
~~~

本迭代的 pomodoro.start 把“Pomodoro 已成为用户当前前台界面”作为开始专注的前提：Runtime 接受调用并创建
`starting` activation 后，先向 Agent 回传 `accepted / starting` 协议回执；这只能表示“正在进入专注模式”，不能说
“已经开始计时”。Host 前台确认与 operation 创建成功后，Runtime 再回传 `started` 进度，此时 Agent 才能说“已开始
为你计时”。确认之前不存在 operation、倒计时或专注 IM 记录；最终无法前台激活时，Runtime 回传符合 start output
schema 的 `not_started` 业务结果并恢复 Interact。pomodoro.interrupt 由 Agent 调用，而不是 Runtime 私下调用 Pomodoro：
它可取消当前启动尝试，或收口当前 focusing operation。Runtime 根据调用所在 conversation 定位目标，不接受 Agent 指定
或伪造 instance_id、operation_id 等目标。

当前 Pomodoro Surface 不实现开始、暂停、继续、停止等业务按钮。未来如果引入“用户先让 Agent 设定时长、随后自己点击开始”之类的 UI，按钮的 onClick 应产生独立的本地 UI Action；Runtime 可以让它复用创建 operation 的内部动作，但不得改变当前 Agent Tool 的含义，也不要求为第 04 次迭代提前加入两阶段 Tool 模型。

用户切回 Interact、切至其他 MiniApp 或关闭 Pomodoro 属于 Host 生命周期意图。Runtime 按 Pomodoro 的业务规则将其收口为 interrupted，但不伪造一条 Agent Tool Call；自动暗屏、锁屏和 Surface 重载则不等于离开专注。

## 8. 对协议与实现的约束

1. Agent Inventory 只能包含 Agent Tool Descriptor；不得包含 UI Action、Host 生命周期事件或 MiniApp 任意内部方法。
2. Runtime 必须分别记录 Agent Tool Call、UI Action 和 Host 生命周期意图的来源、身份、关联 ID 与审计类型；不得用一种来源伪造另一种。
3. UI Action 的本地 Bridge 协议可在后续版本独立设计，但其入口、权限和审计不得依赖远端 Agent 身份或 inventory revision。
4. Runtime 内部业务服务可由多个入口复用，但每个入口都必须先完成自己的授权、作用域和幂等校验。
5. MiniApp session data 只能保存当前 App 子会话的 MiniApp 自定义 JSON 数据；不能借此完成 Tool、operation、outbox、焦点或 Host Capability 的特权动作。
6. Agent Tool 的调用结果必须由 Runtime 校验 schema、持久化并经 outbox 回传；MiniApp 不得直接向 Agent 或 Transport 发送结果。
7. 在没有明确产品决议前，不得为了未来 UI 的可能性改变已发布 Agent Tool 的语义，或向当前 Inventory 额外加入预设、打开、准备等 Tool。
8. 对 operation、activation、session data、Tool receipt、outbox 和工作区目标的同一次业务变更，Runtime 必须先原子持久化事实，
   再让 Lifecycle、Host 和 Surface 对账；持久化失败不得改变任何层，提交后的 UI / Host 失败不得回滚已提交事实。

## 9. 非目标

本文不定义：

- Voice 的具体协议或语音识别实现；它未来只需复用“用户表达意图，再由 Agent 调用 Tool”的语义；
- UI Action 的具体事件名称、Bridge 线协议或按钮设计；
- 允许用户绕过 Agent 调用远端 Agent Tool；
- 允许 MiniApp 直接与 Agent、AppServer、Tauri 或任意系统能力通信；
- 将所有 MiniApp 都强制设计为有 operation 的应用；
- 因未来 UI 交互扩展而修改第 04 次 Pomodoro 已冻结的直接开始模型。