浏览器里的 AI agent 工具调用：从前端按钮到 microVM PTY 的完整链路

目录

• 为什么一次「看目录」不只是一次命令执行
• 链路全景：从 React 到 guest-agent
• 前端：按钮、SSE、WS 与 typed client 的边界
• 后端：Axum 把聊天流和工具执行拆开
• sandbox：为什么是 vsock，不是 TCP
• PTY：为什么不是直接 exec
• 错误与回流：stdout、exit、error 都是协议
• 业界正在做什么
• 一个可复用的工程框架

为什么一次「看目录」不只是一次命令执行

用户在浏览器 chat 输入「帮我看一下当前目录」，表面上只是 pwd && ls。但在 agent 产品里，它同时穿过四个边界：浏览器进程、Rust server、sandbox runtime、microVM guest。每一层都可能丢事件、阻塞、错认工作目录，或者把错误包装成一段模型看不懂的文本。

真正难的不是执行命令，而是让一次工具调用具备这些性质：用户能看到流式反馈；模型拿到结构化结果；命令运行在隔离环境；刷新页面后状态还能恢复；超时、退出码、stderr 都能被解释；交互式 shell 和一次性命令不能互相污染。

这里还有一个容易被忽略的产品问题：用户以为自己在和「一个助手」对话，但系统实际由很多异步参与者组成。LLM 可能还在思考，SSE 已经断线；命令可能已经退出，消息缓存还没 flush；sandbox 可能刚被重建，旧的 PTY tab 还在尝试写 stdin；用户切换 agent 后，工作目录、技能开关、模型参数都要跟着换。如果这些边界没有清晰协议，最后出现的 bug 往往不是「命令跑错了」，而是「结果跑对了，但出现在错误的会话、错误的窗口、错误的工作目录」。

┌──────────────┐   POST /chat/send    ┌──────────────┐
│ Browser Chat │ ───────────────────▶ │ Axum AI API  │
│ React + SSE  │ ◀── data: AgentEvent │ ChatService  │
└──────┬───────┘                      └──────┬───────┘
       │                                     │ tool: Bash
       │ WS: app events / terminal          ▼
       │                              ┌──────────────┐
       │                              │ AgentSandbox │
       │                              │ per-agent cwd│
       │                              └──────┬───────┘
       │                                     │ spawn_shell
       │                                     ▼
       │                              ┌──────────────┐
       └────────────────────────────▶ │ microVM guest│
                                      │ vsock + PTY  │
                                      └──────────────┘

Agent 工程的本质，是把「模型想做一件事」变成跨进程、跨协议、跨权限边界的可恢复事务。

链路全景：从 React 到 guest-agent

当前代码里，AI chat 的入口主要在 packages/web/src/apps/ai-chat/。AiChatContext.tsx 维护 agent、conversation、panel 状态；useSendMessage.ts 把编辑器内容、附件和模型选择组装成发送输入；useChatSSE.ts 负责先连 /api/apps/ai/chat/{conversationId}/events，再 POST /api/apps/ai/chat/send，避免服务端广播时前端还没订阅。

服务端路由集中在 packages/rust-server/src/apps/ai/router.rs：stream::chat_events 提供 SSE，stream::chat_send 触发 ChatService::stream_completion。工具层落在 packages/rust-server/src/apps/ai/tools/，其中 Bash 工具最终会走 LocalToolExecutor::exec_bash_streaming；正常情况下 sandbox always-on，executor 进入 AgentSandbox::exec，由 tokimo-package-sandbox 的 Auto backend 决定 Linux CH / bwrap 等实际路径。只有当 sandbox boot 进入 cached Failed state 时，chat 才按 6432e4ab 的策略退回 host execution，避免每次请求都卡 multi-second timeout；/api/apps/ai/sandbox/restart 用于清掉 failed runtime 并重试。

这篇文章按「理想的一次看目录工具调用」来讲链路，但会保留当前代码的真实边界：chat send 不是 generated client 的 mutation，而是 authFetch 手写；packages/web/src/lib/api/ 这个旧路径不存在，真实 typed client 在 generated/rust-api/；packages/tokimo-guest-agent/ 也不是独立 package，而是 sandbox 包里的 binary。写技术随笔最怕把架构图画得很顺，代码却不是这么跑的，所以这里宁可把这些不那么优雅的过渡态写出来。

graph TD
  A[ChatInput / Send button] --> B[useSendMessage]
  B --> C[useChatSSE]
  C --> D[authFetch /api/apps/ai/chat/send]
  C --> E[SSE /api/apps/ai/chat/:id/events]
  D --> F[Axum stream::chat_send]
  E --> G[React Query message cache]
  F --> H[ChatService::stream_completion]
  H --> I[BashTool]
  I --> J[LocalToolExecutor]
  J --> K{sandbox runtime healthy?}
  K -->|yes| L[AgentSandbox::exec]
  K -->|boot failed / Failed cached| M[host process fallback]
  L --> N[tokimo-package-sandbox Auto backend]
  N --> O[tokimo-sandbox-init / guest bash]
  R[/api/apps/ai/sandbox/restart] --> K

一次调用的时序条带

Browser        Axum             Agent runtime        Sandbox host        Guest
  |             |                    |                    |                |
  |--SSE open-->| chat_events        | subscribe bus      |                |
  |<--initial---|                    |                    |                |
  |--POST------>| chat_send          | stream_completion  |                |
  |             |------------------->| model/tool loop    |                |
  |             |                    | BashTool           |                |
  |             |                    |------------------->| spawn_shell    |
  |             |                    |                    |--vsock JSON--->|
  |             |                    |                    |<--frames-------|
  |<--SSE data--|<-------------------| AgentEvent         |                |

这条链路不是单向 RPC，而是「触发通道 + 事件通道 + 执行通道」三条线并行协作。

前端：按钮、SSE、WS 与 typed client 的边界

前端有两类网络通道。第一类是 AI chat 自己的 SSE：useChatSSE.ts 用 authFetch(rustUrl(...)) 手动读取 response body，解析 data: 行，再用 applySSEEvent patch React Query cache。这里没有直接使用浏览器原生 EventSource，因为代码需要精确控制「先订阅、再发送」以及 AbortController 生命周期。

第二类是全局 WS：packages/web/src/system/events/ws.tsx 定义 JSON envelope：{ type, data, reqId, error }；useJobEvents.ts 明确把 app-wide 的 job_update、person_scraped、download:progress 放到 WS 上，并替代旧 SSE。也就是说，chat token 和工具事件偏 SSE，系统级广播偏 WS。

typed client 的真实位置不是旧路径 packages/web/src/lib/api/，而是生成目录 packages/web/src/generated/rust-api/。例如 ai.ts 里有 api.ai.agents.*、api.ai.conversations.*、api.ai.messages.*、sandbox status、terminal URL 等。chat send 当前仍是手写 authFetch，但 agent/conversation/message 的 CRUD 已经由 generated client 承担。

这个边界值得保留：不是所有请求都应该强行塞进同一个 client 抽象。普通 CRUD 追求类型、缓存键和失效策略一致；chat stream 追求连接时序、增量解析和取消语义可控。把二者分开，反而能让「控制面」和「数据面」各自简单，也方便后续把 stream 协议单独演进，不牵动普通查询接口，并保持可测试、可回放、可追踪。

graph LR
  subgraph React
    Input[ChatInput]
    Hook[useSendMessage]
    SSE[useChatSSE]
    Cache[React Query Cache]
    WS[WsProvider]
  end
  Input --> Hook --> SSE
  SSE -->|POST trigger| Send[/chat/send/]
  SSE -->|read stream| Events[/chat/:id/events/]
  Events --> Cache
  WS --> Jobs[job_update etc]
  API[generated rust-api] --> Cache

前端不是「发一个请求等结果」，而是在维护一个可断线重连的 agent 运行投影。

后端：Axum 把聊天流和工具执行拆开

router.rs 里有三组关键路由：/api/apps/ai/chat/send 触发运行；/api/apps/ai/chat/{conversationId}/events 输出 SSE；/api/apps/ai/agents/{id}/terminal/ws 给用户打开同一个 sandbox 内的交互式终端。stream.rs 的 chat_send 把 user、conversation、provider、model、attachments 和 sandbox_runtime 一起传进 ChatService::stream_completion。

工具执行上下文由 ServerToolExt 描述。它把 workspace 级资源（DB、HTTP、ConversationJournal、MCP、sandbox manager）和 per-agent 资源（agent id、cwd、模型参数、tool whitelist、sandbox handle）拆开。这样 DispatchAgent、Skill、session memory extractor 都能继承同一个逻辑 sandbox，而不是复制一个可能已经死掉的 Arc。

sequenceDiagram
  participant U as Browser
  participant A as Axum stream.rs
  participant C as ChatService
  participant T as BashTool
  participant E as LocalToolExecutor
  participant S as AgentSandbox
  participant G as sandbox-init / guest bash

  U->>A: POST /api/apps/ai/chat/send
  A->>C: stream_completion(input, sandbox_runtime, bus)
  C-->>U: SSE AgentEvent conversation:start
  C->>T: model requests Bash
  T->>E: exec_bash(args)
  E->>S: exec(cmd, timeout)
  S->>G: spawn argv=[/bin/bash,-lc,cmd]
  G-->>S: stdout/stderr/exit/error frames
  S-->>E: ExecResult
  E-->>T: ToolOutput
  C-->>U: SSE message/tool_result/end

Axum 层只负责把运行接上轨道，真正的复杂度在「事件 journal」和「工具 executor」之间。

sandbox：为什么是 vsock，不是 TCP

tokimo-package-sandbox 是跨平台 sandbox 包，公开 Sandbox、ShellOpts、Event、JobId 等 API。Linux 现在不应只写 Cloud Hypervisor：默认是 Auto backend，先探测 CH，失败时回退到 bubblewrap。CH 分支仍通过 Cloud Hypervisor hybrid-vsock UDS 连接 guest；bwrap fallback 则用 namespaces + socketpair 承载同一套 init / RPC / netstack 语义。对 Bash tool 来说，关键变化是 guest 里应有真 /bin/bash，同时有大量 busybox applet symlinks 补齐常用命令。

Guest 侧并没有独立的 packages/tokimo-guest-agent/，而是 packages/tokimo-package-sandbox 里的 binary：src/bin/tokimo-guest-agent/。main.rs 默认在 1024 开 one-shot RPC，在 1025 开 PTY；server.rs 读一行 JSON request，返回多行 JSON frames；exec.rs 定义 Spawn/Ping/QueryMount；pty.rs 用 forkpty() 处理交互式会话。

graph TD
  Host[Sandbox host process] --> UDS[Cloud Hypervisor vsock UDS]
  UDS -->|CONNECT 1024| RPC[guest-agent RPC listener]
  UDS -->|CONNECT 1025| PTY[guest-agent PTY listener]
  RPC --> Spawn[Command::output]
  PTY --> Forkpty[forkpty + exec]
  Spawn --> Frames[stdout/stderr/exit/error]
  Forkpty --> PtyFrames[stdin/resize/stdout/exit]

vsock 的价值不是更快，而是把「只允许宿主机和 guest 说话」变成默认拓扑。 但这句话只适用于 VM backend：Linux CH、macOS VZ、Windows Hyper-V 分别对应 AF_VSOCK / virtio-vsock / HvSocket。Linux bwrap fallback 不走 vsock，而是用 socketpair 承载同一类 frame / RPC 语义；文中后续提到“vsock”时，应理解为 VM backend 的 transport，而不是所有 backend 的唯一传输。

PTY：为什么不是直接 exec

一次性工具调用和交互式终端是两种协议。GuestRpc::spawn_command_with_options 每次连接只发一个 spawn request，guest 用 Command::output() 等命令结束后再返回 stdout/stderr/exit。这适合「帮我看目录」这种短命令，因为模型需要的是完整结果。

但用户打开 terminal 或 agent 运行交互式程序时，直接 exec 不够。TTY 程序会检查是否有终端、需要窗口尺寸、需要 Ctrl-C、需要 resize、会输出 ANSI 控制序列。AgentSandbox::open_pty 传 ShellOpts { pty: Some((rows, cols)), argv, env, cwd }；terminal_ws.rs 再把浏览器 WS 的 binary/text 输入转成 write_stdin 和 resize_shell，把 sandbox Event::Stdout 广播给所有 attach 的浏览器 tab，并保留 scrollback。

PTY 不是「exec 多一个参数」，而是一条活的终端电路：

Browser xterm
   │ key bytes / resize
   ▼
terminal_ws.rs
   │ PtyInput::Data / Resize
   ▼
Sandbox::write_stdin / resize_shell
   │ VM: vsock JSON frame / bwrap: socketpair frame
   ▼
sandbox-init pty.rs
   │ forkpty master fd
   ▼
/bin/bash -l（Bash tool 语义）或 ShellOpts 指定的交互式 shell ❓

exec 给模型结果，PTY 给用户现场；把两者混成一个接口，最后会两边都难用。

错误与回流：stdout、exit、error 都是协议

错误不能只靠字符串。当前链路里至少有三种错误：请求错误（POST 失败，前端 onError）、运行错误（AgentEvent 里的 conversation/message/turn error）、sandbox 错误（Event::Error { fatal, message } 或 guest Response::Error { msg }）。这里需要删除 caller-owned JobId 的叙述：该 race fix 已被 b797c2975 revert，exec() 回到 spawn-then-subscribe。项目组判断原始竞态并不存在，因为事件发布路径要经过 guest fork+exec / vsock / HCS pump，远晚于 host 侧 synchronous insert；反而是只在 ChBackend 实现 spawn_shell_with_id、其他 backend 走 trait 默认 fallback，导致 Windows/macOS/bwrap 丢弃 job_id，最终让 Bash tool 在 Windows 卡 120s。

这个 revert 的教训比 race 本身更重要：跨平台 sandbox 的 API 不能只在一个 backend 上实现，然后依赖 trait 默认实现“看起来编译通过”。如果 API 改动影响 job id、事件订阅、stdin/stdout 语义或 host-exec response，就必须让 CH、bwrap、macOS、Windows 全部显式实现或显式报错；静默 fallback 会把 bug 推迟到最难调的平台上爆炸。

输出回流也分层：guest-agent 把 stdout/stderr/exit/error 变成 JSON lines；ch/backend.rs 映射成 tokimo_package_sandbox::Event；AgentSandbox::exec 收集成 ExecResult；Bash tool 格式化成 ToolOutput；ChatService 再投影成前端可消费的 AgentEvent。对于 chat，前端以 SSE patch message cache；对于 terminal，WS 直接推原始字节给浏览器。

好的 agent 运行时不会隐藏错误，而是让每一层都能保留自己的错误类型和恢复策略。

业界正在做什么

OpenAI Code Interpreter 的路线是「托管沙箱 + 文件挂载 + 结果工件」，用户不关心底层 VM，但工具调用被严格关在会话环境里。Cursor agent 更像「IDE 内本地代理」，强调 workspace 上下文、diff、终端和用户确认。Claude Code 则把 terminal、文件系统、任务子代理和工具权限做成 CLI 里的长期会话，重点是把工程项目当运行现场，而不是把 prompt 当唯一上下文。

Tokimo 这条链路更接近「浏览器桌面 OS 里的 agent runtime」：前端是窗口和消息投影，后端是 agent orchestrator，sandbox 是可共享但 per-agent 隔离的执行层。它不是复制某一家产品，而是在浏览器、Rust server、microVM 三者之间明确切边界。

业界共识正在形成：强 agent 不是一个模型接口，而是一套带 UI、状态、沙箱和权限的运行时。

一个可复用的工程框架

如果把这条链路抽象出来，我们会得到一个四层框架：UI projection、run orchestration、tool execution、isolation transport。UI projection 负责把运行状态变成用户可理解的消息、spinner、terminal；run orchestration 负责模型循环、工具调度、取消和恢复；tool execution 负责 cwd、env、timeout、输出裁剪；isolation transport 负责把命令送进受控环境。

graph TB
  L1[UI Projection\nReact Query / SSE / WS] --> L2[Run Orchestration\nChatService / ConversationJournal]
  L2 --> L3[Tool Execution\nBashTool / LocalToolExecutor]
  L3 --> L4[Isolation Transport\nAgentSandbox / Sandbox / vsock]
  L4 --> L5[Guest Runtime\nguest-agent / exec / PTY]

  L5 --> L4
  L4 --> L3
  L3 --> L2
  L2 --> L1

这也是为什么「帮我看一下当前目录」值得被认真拆解。它不是 demo，而是 agent 产品最小但完整的工程切片：一次用户意图，被模型转成工具调用，被 server 约束成执行计划，优先被 sandbox backend 执行，再被事件流还原成用户能看懂的状态。只有当 sandbox boot 已进入 cached Failed state 时，chat 才退回 host execution；这是一条可用性 fallback，不应被写成常规执行路径。

Framework-level 结论：浏览器里的 AI agent 工具调用，应该被设计成事件驱动的分层运行时，而不是从按钮一路硬连到 shell 的远程命令。

版权属于：一名宅。

本文链接：https://zhaiyiming.com/archives/87.html

转载时须注明出处及本声明