跳到内容
MagicFrog
目录

Computer ID 路由

每一个 OS 级工具调用如何绑定到一台显式的目标计算机。

agent 执行的每一个浏览器、命令、文件与桌面操作,都以 computerId 显式指名目标机器。没有有效且已授权目标的调用即失败;工具绝不回落到本地机器、「活跃」计算机或任何其他机器。


三个正交维度

决定工作在哪里运行,涉及三个互相独立的决策。任何一个都不蕴含另一个:

维度 选择 它不意味着什么
agent runtime 所在位置 本地或云端 不决定每次工具调用触碰哪台机器。
工具执行目标 必填的 computerId 不是 IP 地址、用户 ID、会话 ID 或代理客户端 ID。
网络 egress 直连,或选定的客户端代理 不搬移 runtime,也不授予对客户端机器的控制。

浏览器可以跑在 A 机上、经 B 机的网络出网——这是两个彼此独立、分别授权的选择。不需要隧道时,默认 direct egress 仍遵循执行机器自身的路由。一旦选定了客户端代理,egress 选择即失败即关闭(fail-closed):隧道不可达时调用失败,而不是静默回落到 direct;切换 egress 是显式的生命周期变更,不是留着旧隧道继续用的 UI 开关。


每次调用发生什么

每个 agent 工具调用都必须指名目标计算机;没有目标的调用直接失败:

  1. 缺少 computerId → 显式报错并指名该操作。这一层拒绝猜测目标,底层工具不会被调用。
  2. computerId: "local" → 调用直达本地实现,无路由开销。
  3. 任何其他 computerId → 系统核对计算机存在、在线、属于你且具备所需能力,然后把操作派发给它;在无桌面控制的机器上执行桌面动作会以能力错误失败。

路由决策

computerId 路径
"local" 在你面前的这台机器上直接执行。
其他任何 id 系统核对计算机存在、在线、属于你且具备所需能力,然后把操作派发给它。
空 / 缺失 以指名工具的错误拒绝。

调用在以下情况显式失败:

  • computerId 缺失或为空;
  • 计算机不存在、已销毁/已吊销,或处于离线状态;
  • 发起调用的账号不拥有该计算机;
  • 或该计算机不具备此工具所需的能力。

每一种都是附带原因的类型化错误——能力缺失错误同时携带所需能力集与实际可用能力集。其中没有任何一种会换一台机器重试。

授权执行两次

每次操作授权两遍:派发前在服务端校验一次,执行前在目标机器上再校验一次。超出目标能力的操作会被目标机器拒绝。

句柄与所属计算机绑定

会话、标签页、终端等资源句柄与创建它们的计算机绑定。来自 A 机的句柄在 B 机上无法解析;tabId 会校验确实属于配合使用的那个会话,跨任务使用句柄会被拒绝。句柄不是走到哪都能用的 bearer token。

审计

浏览器工具调用在执行前先审计。每次调用发出一条结构化记录,写明工具族、动作、目标 computerId 以及涉及的会话/标签页句柄,带毫秒级时间戳:

{ "tool": "browser", "action": "navigate", "computerId": "…", "sessionId": "…", "tabId": "…", "at": 1760000000000 }

这些记录会进入服务端日志,可以接到你现有的日志收集体系里。


范围

computerId 授权面只覆盖 OS 级工具:文件操作、浏览器操作、命令执行与原生桌面动作。MCP 服务器与插件市场的工具不绑定 computerId——它们是你自行安装并信任的扩展,不是 agent 驱动的机器操作。

关于计算机本身——托管创建(provisioning)、enroll 登记与生命周期——见云电脑。浏览器会话与标签页管理构建在这套路由之上,见浏览器会话。