Core zh

核心

上游 Agent 循环、Agent 注册表和 turn 生命周期在 Edge 中的适配。

上游参考：Core

上游提供了什么

核心子系统提供每个组合都依赖的基础 Agent 基础设施：

• AgentRegistry（）— 创建、恢复和销毁 Agent。每个 Agent 拥有一个 session、一个 inbox（next-turn / next-step 消息队列）和一个作用域 cordis context。销毁器是一个能力——只有创建者能拆除 Agent。
  • AgentLoop — 实现 契约的具体驱动。通过 step 管线处理 inbox 消息：pre-step 验证 → 模型请求 → 流式 → 工具执行 → post-step。在 和 状态之间转换。
  • Agent 事件 — 作用域过滤分发：agent/created、agent/disposed、agent/status、turn/start、turn/end、goal/changed 和 inbox 事件。
  • Inbox 管理 — 两个有序消息列表（ 和 ），支持 append、prepend、replace、remove、clear 和 splice 操作，全部记录为持久化的 事件。

Edge 改了什么

直接复用 AgentRegistry + AgentLoop

两个插件原封不动安装。Agent 创建、session 绑定、inbox 管理、step 管线、模型流式和工具分发完全是上游代码。

传输桥 Turn 生命周期管理

上游的 agent loop 和调用者在同一个进程——turn 在调用者发消息时开始，Agent 空闲时结束。Edge 在此基础上加了传输层，因为调用者（浏览器）是远程的：

• activeTurns map — 追踪 DO 内哪些 session 有正在运行的 turn。防止交叉 HTTP 请求对同一 session 发起并发 turn。
  • claimAndOpenAgent() — 原子地占位 session 并在接受 prompt 前打开/恢复 Agent。确保没有两个请求同时拥有同一个 session。
  • runAgentTurn() — 用 flush-then-publish 管线包装上游 turn：监听 session/event，flush 到 DO SQL，然后通过 WebSocket 发布事件。在 turn 期间绑定 shell 后端。
  • 准入控制 — 在 persistence flush 之后才准入 prompt，确保用户消息在模型看到之前已持久化。 上游的 agent loop 在这个包装器内部原样运行——它不知道自己被观察并通过网络发布。

传输桥 状态广播

Turn 开始时，Edge 广播 。结束时广播 。上游直接从内存读 ；Edge 把这个翻译成网络帧。

Edge 没有改什么

• Agent 创建、session 绑定和销毁生命周期
  • Inbox 管理和消息队列语义
  • Step 管线（pre-step → request → streaming → tool execution → post-step）
  • 作用域过滤事件分发
  • 模型请求准备和重试策略
  • Turn-stopping 协商（ 瀑布）

性能特征

Turn 生命周期开销

Edge 在上游 turn 基础上增加三项代价：

• 占位检查：每个 prompt 一次 Map 查找验证无并发 turn — O(1)，亚微秒。
  • Flush 屏障：每个事件在 WebSocket 发布前 flush 到 DO SQL。每事件增加约 1ms 同步 SQL 写入。上游在检查点边界 flush；Edge 逐事件 flush 以提供更强的持久性保证。
  • Shell 绑定： 在 turn 期间关联 Computer VFS workspace 和 Agent — 一次 Map 插入，在 中释放。

并发 session

一个 Durable Object 实例（名为 ）管理所有 workspace 和 session——镜像了上游的单进程架构。 map 确保每个 session 最多运行一个 turn，不同 session 可在同一 DO 内交错执行。隔离来自应用层的作用域（cordis agent scope、VFS workspace 路径），而非独立的运行时实例。

Agent 跨 turn 复用

当 session 已有活跃 Agent（来自之前未销毁的 turn）， 复用它——无 Agent 创建开销。冷 session（DO 重启后）需要付 Agent 恢复代价：从 DO SQL 加载 session header + 事件日志 + 重建内存状态。

架构总结

组件	分类	Edge 代码
AgentRegistry	复用	一行 调用
AgentLoop	复用	一行 调用
Turn 生命周期包装	桥接	+
状态广播	桥接	WebSocket 帧

关键观察：核心 Agent 基础设施完全运行上游代码。Edge 用 claim → flush → publish 管线包装每个 turn 来桥接 DO 和浏览器之间的网络间隙。Agent loop 不知道自己运行在 Cloudflare 上——它看到的是同样的 cordis context、同样的 session 和同样的工具注册表。

已知限制与未来方向

当前的单 DO 架构镜像了上游的单进程设计，但受 Cloudflare 平台特有的天花板限制：

• 内存：每个 DO 128 MB，所有活跃 session 共享——限制大上下文窗口下的并发 turn 数量。

  • SQL 存储：每个 DO 10 GB，存放所有 session 的事件日志——长期使用的部署会逐渐逼近上限。
  • 并发：DO 是单线程的——多个 session 交错执行但无法真正并行。
  • Subagent 隔离：同一 DO 内的 Agent 共享内存，无法做资源隔离。 自然演进方向是 session-per-DO：每个 session 拥有独立的 Durable Object，独立的内存、存储和生命周期。这需要：

• 路由 DO（或入口 Worker）管理 workspace → session → DO-id 的映射。

  • 分层 VFS：Agent 级共享存储（workspace 代码、配置）可跨 session DO 访问，加上 session 本地存储（临时文件、spill、工具输出）隔离在各自 DO 内。共享层可用 R2 或专用 workspace DO。
  • Subagent via DO fork：子 Agent 作为独立 DO 启动，拥有自己的内存预算，通过 DO-to-DO fetch 将结果回传给父 Agent。