架构与设计依据
本文按主题说明 Open Agent API 的架构:每个设计决定是什么、为什么这样做、证据到哪里为止。接口字段与错误码见 protocol.md,工程约定见 engineering.md。
目录:
1. 产品边界
Open Agent API 对外提供的是智能体的能力,而不仅仅是模型端点。稳定的 oaa/1 调用契约位于内核与外部智能体适配器之上,位于 HTTP / OpenAI 兼容层、MCP 桥与管理控制台之下。智能体与它的模型线路(智能体可选用的一个模型及其提供方)可以分别选择。
三者的关系:
- 智能体是被调用的单位,调用时用它的调用名称(填在
model字段里)。 - 模型线路是智能体可用的模型及提供方,一个智能体可以有多条,由发布者声明。
- 能力是智能体可以使用的工具、技能与文件,同样在发布时声明;外部智能体自带工具。
内核负责调度、审批、执行状态、事件与产物。外部智能体是不透明的执行单元:它们内部的工具图、账号权限、只在桌面端可用的插件,都无法从一个 CLI 退出码或一次安装探测中推断出来。当前支持情况在 README 的「能接入哪些智能体」与「现状与边界」中逐项列出。
2. 分层与目录
src/ 下除命令行入口 src/cli.ts 外,每个文件都在一个分层目录里(src/<目录>/<文件>.ts)。层级定义在 test/architecture.test.ts 的 LAYERS:
| 目录 | 层级 | 职责 |
|---|---|---|
core/ | 0 | 公共定义与基础:契约(contracts)、工具函数、schema、内建工具、错误 / 事件 / 限额目录、运行状态转移表 |
config/ | 1 | 配置与智能体预设 |
lang/ | 2 | OAA-Lang 编译器、执行图、不可变能力包(bundle) |
store/ | 2 | 持久化:事件与检查点存储、输出投影、有界查看、审计 |
providers/ | 2 | 模型提供方驱动与共享的流读取器 |
engines/ | 3 | 外部智能体接入(内层 Harness):原生、ACP、A2A、适配器、子进程与沙箱 |
fabric/ | 4 | 分发网络:节点放置、WSS 租约任务、执行机器、MCP 连接、工具导入、本机后端 |
kernel/ | 5 | 内核(外层 Harness):执行与审批状态、调度、委托、交接、备选智能体、调用方工具 |
gateway/ | 6 | 网关与协议:鉴权入口、各兼容协议、目录与发现、流、时间线与活动统计、控制台静态资源 |
client/ | 7 | 客户端与 MCP 桥 |
依赖规则由架构测试强制:只能引用同目录或层级更低的目录,同层不同目录互不引用;文件之间不允许循环引用(import type 也算);任何文件不能引用 cli.ts;超过 600 行的文件登记行数预算且只许调低;src/ 里 any 的数量上限为 0。细则见 engineering.md 第 2 节。
存储层是事件与检查点的权威来源(SQLite)。每个会话同一时间只有一个活跃运行,由部分唯一索引保证。
变更记录:2026-11-10 起源码按层分目录(此前平铺在 src/ 顶层),并加入架构测试。
3. 内核
3.1 职责
内核是外层 Harness:由 Open Agent API 自己驱动模型轮次、执行工具、管理审批与运行状态,并把执行交给内置内核或外部智能体。按职责分为准入与提交、模型轮次(选路与意图分析在 kernel/routing.ts)、工具阶段、审批停车、外部智能体回合、委托(kernel/delegate.ts)、交接(kernel/handoff.ts)、备选智能体(kernel/fallback.ts)、调用方工具桥接与文本输出写入(RunTextSink,kernel/text-sink.ts)。具体文件见 src/kernel/。
失败后的终态归类是 src/kernel/run-state.ts 里按优先级排列的规则表(有单元测试),行为与此前的 if 串等价:只要已超时,错误码一律是 run_timeout。
变更记录:2026-11-10 终态判定改为规则表;工具批次成为独立的工具阶段,execute 从约 690 行降到约 520 行;选路从协议解析文件分离为 kernel/routing.ts,gateway/protocol.ts 只保留线上兼容层;core/builtins.ts 解除了语言编译器与 bundle.ts 的循环依赖。
3.2 运行状态机
Run.status 的合法转移登记在 src/core/run-status.ts 的 RUN_TRANSITIONS(src/kernel/run-state.ts 再导出 canTransition / assertTransition)。表由全量测试实测得出:在存储层写入运行状态的入口记录每一次 (from → to),跑完 449 项测试后与内核代码逐条对照。
| 从 | 到 | 触发条件 |
|---|---|---|
| (新建) | queued | 提交(submit);测试夹具可以直接种下任意状态,createRun 不经过转移表 |
| queued | in_progress | 拿到运行槽,开始执行 |
| queued | cancelled | 排队中或调度挂起中被取消 |
| queued | failed | 调度挂起期间审批被拒或过期 |
| queued | incomplete | 调度挂起期间到达截止时间 |
| in_progress | completed | 正常结束(同时 phase = 'done') |
| in_progress | queued | 让出运行槽(调度挂起),或换用备选智能体重新排队 |
| in_progress | requires_action | 发起审批(含挂起等待审批) |
| in_progress | failed / cancelled / incomplete / interrupted | 失败归类(classifyFailure);启动时 recover 转 interrupted |
| requires_action | in_progress | 外部智能体在进程内等完审批后继续 |
| requires_action | queued | 挂起的运行发现审批已批准,重新入场 |
| requires_action | failed / cancelled / incomplete | 审批被拒或过期、取消、截止(finishParked),或进程内等待后失败归类 |
| requires_action | interrupted | 关机时仍在等审批,或启动时 recover |
| interrupted | queued | 操作员显式恢复(resume) |
规则:
- 相同状态的重复写入(
from === to)总是合法,那是检查点更新。 completedfailedcancelledincomplete是终态,不可离开;interrupted只能经resume回到queued(terminal()仍把它算作「已结束」,用于展示与统计)。- 进入
completed时checkpoint.phase必须是done。 - 存储层所有写运行状态的入口(
save、checkpoint、checkpointStep、checkpointReassigned、recover)都经过同一个UPDATE:允许的来源状态折进WHERE status IN (…),不增加 SQL 往返、事务或 fsync;没写进去时才读一次当前状态,抛invalid_run_transition(500),整个事务回滚,事件、步骤与摘要都不写入。
变更记录:0.2.0 新增。
3.3 准入、运行槽与公平让出
网关不在每次工具执行外面加一把全局队列锁:可运行的节点工作是异步的,按资源划分的写入串行执行,节点任务随等待时间提高优先级。内核运行在确认的检查点处、有其它运行在等待时,也会在网关准入队列里轮转。不存在对任意模型推理或 shell 命令的实时抢占。
只在节点层面做公平,帮不了还没拿到网关运行槽的请求。内核执行在一轮模型调用结束或一批工具全部收尾时,如果有其它运行在等待,就交还运行槽:提交一个 queued 检查点和 reason: "fairness" 的 run.queued 事件,然后排到 FIFO 队尾。没有竞争的执行仍走原来的短路径,不增加让出检查点。这是按运行轮转,不是按租户加权的调度,也不保证 CPU 时间上的公平。
依赖图在相邻的就绪批次之间提供同样的边界。已完成叶子的结果与产物引用已经落盘,重新入场时复用。重建这些结果不算新进展,不会触发一直让出却不执行下一步的循环。网关交还运行槽之前,所有已经启动的同级调用都必须收尾,并行图也一样。结果未知的副作用与硬失败优先于让出和审批挂起。
原来的截止时间、模型线路、智能体版本、用量与轮次预算在重新入场后保持不变。排队中的已让出运行保留一个截止 / 审批定时器,并计入 owner 的准入上限。取消会把它移出队列;审批被拒或过期会在下一个工具开始前结束它。网关可以恢复已提交的排队让出而不重放已确认的工作;而执行到一半被打断的运行仍然需要操作员显式恢复。让出没能提交就是失败,不能据此从未提交的状态继续派发。
外部智能体会话以及单次模型 / 工具调用不可分割。一个很长的不透明调用在返回之前会一直占着运行槽;调度器不会假装取消请求就能安全抢占任意外部副作用。
准入队列按运行去重:换用备选智能体重新排队时,旧任务的清理不会误删新登记的任务。网关关闭时仍在挂起的运行,错误码统一为 shutting_down。
变更记录:协作式准入的加入日期原文未记录;2026-11-11 准入队列去重、关闭时的错误码统一(T06c)。
3.4 模型轮次与工具批次
模型一次返回多个工具调用时,工具批次是就绪即补位的:最多同时执行 toolConcurrency 个,任何一个结束就立刻启动下一个(此前按 toolConcurrency 切成固定分块,一块里最慢的调用会拖住整块)。保持不变的语义:硬失败(含结果未知的副作用)出现后不再启动新调用,等已启动的全部收尾再抛出,结果未知优先于普通失败;等待审批的调用不阻塞其它调用;第一窗口之后的每次补位都是公平让出点;结果按模型给出的调用顺序回填;「已排队」记录仍按窗口合并成一次提交。实测「1 个 80 ms + 7 个 5 ms、并发 2」从约 103 ms 降到约 85 ms(理论最优 80 ms)。
执行图使用按依赖索引的就绪队列,而不是等一整批里最慢的那个。一个节点完成后立即解锁依赖它的节点。foreach 的各项共享图的并发预算,返回数组保持输入顺序;并行图与嵌套工作流还在每个运行片段内共享一个叶子执行池。图 / 工作流容器本身不持有叶子许可,所以嵌套不会让这个池死锁。独立分支可以绕过待审批的步骤继续运行。
失败、取消和协作式让出会停止接纳新的图节点,并在返回前让已接纳的操作收尾。结果未知的副作用优先于普通错误、调度让出与审批,在 map 内部也一样。每个已确认的叶子保留原有的持久步骤 ID 与检查点。展开后的 map / fallback ID 与其它步骤冲突的图在派发前就被拒绝,而不是意外共用一个检查点。fallback 校验会沿传递关系传播工作流的副作用;委托视为不透明 / 未知;一个组合的写工作流不会仅仅因为其中每个工具都是幂等的就被当作幂等。
步骤级重试与超时、失败自动换智能体的写法见 language.md 与 protocol.md。
上面的数字来自 bench/kernel-core.ts(进程内模拟模型与工具,不代表真实模型或网络耗时),同一台机器上基线版本与当前版本先后运行。其余场景持平:零延迟单次运行约 1 ms、16 步执行图约 16 ms 等没有明显变化;宽批次和执行图受测试环境里执行机器的并发上限约束,不是内核开销。
变更记录:2026-11-10 工具批次改为就绪即补位。
3.5 检查点与落盘
排队、开始、缓存命中与失败状态和对应的审计事件一起提交。running 状态和 tool.started 事件必须在派发前提交。成功结果、新的产物引用、运行检查点和 tool.completed 在同一个事务里提交;观察者只在此后得到通知。并行的同级步骤看不到另一个步骤暂存的产物。产物的字节与文件记录先准备好,因此一次失败的完成可能留下未被引用的文件,但绝不会留下一个被错误发布的运行产物。
非只读的派发会在执行前使读缓存失效,包括结果会变成未知的操作。如果写操作或影响未知的操作已经返回,但结果校验或持久化失败,这一步就变成 uncertain,需要显式的人工确认结果,而不是自动重放。本地崩溃测试会在完成事务之中和之后终止自己拥有的子进程。它们不证明主机断电或远端副作用方面的保证。事务合并减少了提交次数,但没有改变 synchronous=FULL、输出增量的持久性或存储结构。
文本增量合并落盘。同一轮事件循环里到达的多个文本增量,由内核攒成一次 recordOutput 调用(一个事务)。事件条数、内容、顺序和线上字节都不变;存储层「先提交、后同步通知观察者」的契约没有改动;合并只发生在本轮循环之内,由 setImmediate 或下一个需要一致状态的操作(非文本事件、收尾、检查点)触发,没有基于定时器的延迟窗口。落盘失败仍然以 persistence_failed 停止生成且不报告成功。实测 2000 个增量从约 102 ms 降到约 9 ms(bench/kernel-core.ts,测量条件同 3.4)。曾尝试在存储层做跨调用的延迟提交,因为会破坏 recordOutput 返回即已提交并已通知的契约而放弃。
未知的外部写入结果会阻止恢复。有权限的操作员必须先显式记录 completed(附结果)或 not_executed,再单独恢复内核运行。这是操作员的断言,在步骤历史里可见地保留,不是一次新的工具测量。
恢复与计费(lifecycle.ts resume、gateway/key-usage.ts):
- 恢复前按提交时的规则重新检查运行所属的密钥(
run.checkpoint.keyId),而不是发起恢复的密钥:原密钥自己恢复时,检查的就是它自己(过期与吊销在鉴权阶段已被拒绝);owner 的管理员密钥在控制台里恢复别人的运行时,网关按 ID 找到原密钥,原密钥已过期、被吊销或已删除时拒绝(run_key_inactive)。随后检查:原密钥是否仍授予这个智能体(平台账号密钥即「是否仍上架」,scope_denied)、平台账号是否停用(account_disabled)、收费智能体的余额(insufficient_balance),以及密钥配额(并发、token、运行次数;恢复的是同一个运行,不另算一次运行)。任何一项不通过,运行保持interrupted,不写入任何东西。 - 密钥的并发计数只在内存里。恢复的运行、网关启动时重新入队的
queued/requires_action运行,都重新计入所属密钥的并发,但不增加「已用运行次数」。 - 一个运行可能多次收尾(中断、恢复后再结束),每次带来的是累计 token。
api_key_run_tokens表记下每个运行已计入密钥的 token 数,只累加差额。第一次建这张表时,按升级前的行为(中断时已整体计入)为已中断的运行补记,因此这些运行恢复后不再重复计。升级前已经重复计入的历史用量不回改;需要时 owner 可以在密钥上重置用量。 - 平台流水:
interrupted是终态,中断时就按已用 token 结算(不收每次费用);运行被恢复时这一行改回in_progress,完成后按差额补结。网关崩溃(没有经过收尾)留下的in_progress行由启动对账结算;已经结算过的行,即使运行之后被清理,对账也不再改动。
变更记录:2026-11-10 文本增量合并落盘;2026-11-12 恢复重新检查资格、恢复计入密钥并发、密钥 token 按差额累加。
3.6 审批停车
内核的工具审批是持久的挂起点,而不是占着全局运行槽的常驻循环。所有已经启动的并行工作收尾之后,内核保存待处理的调用图与审批 ID,交还运行槽,用一个截止定时器等待。获批的运行排到现有准入队列的队尾。它复用同一个不可变运行检查点里已完成的步骤结果与产物,不重复模型轮次,也不重复已确认的工具。
独立的图分支可以绕过被阻塞的审批继续运行。失败的并行步骤优先于挂起,结果未知的副作用优先于普通失败。部分批准只解锁对应的就绪工作;拒绝、取消、过期与关机会使待决审批失效,而不会隐含地批准它们。与停车过程竞争的审批决定会在执行体退出后再检查一次。
原来的运行截止时间在停车与重新入场之后保持不变;中断后由操作员显式恢复会开始一个新的执行截止时间。停车的请求仍计入每个 owner 32 个未完成请求的上限。在这个上限下,已有的幂等重放仍可读取,但新的幂等键不能绕过它。maxActiveRuns 限制的是正在执行的执行体,停车的内核运行只保留持久状态和一个很小的定时器条目。控制台概览的「进行中请求」总数包括排队中与等待审批的请求,而不仅仅是占着执行槽的请求。
外部智能体的审批仍然占着它的宿主进程和全局运行槽,因为这些不透明后端没有经过验证的暂停协议。它们的审批通知是事件驱动的而不是轮询的,但不把它们描述为可挂起或可迁移。
调用方工具桥接复用同一条停车路径,见 harness.md。
3.7 委托与子智能体一致性
副作用等级。把任务委托给子智能体的步骤,原先一律登记为只读;后台服务意外重启后,只读步骤会被自动重跑,这会让能改文件的子智能体把同一件事再做一遍。现在按子智能体的实际情况登记:外部智能体(内部做了什么看不见)和还会继续委托的智能体是「影响未知」,只带只读工具的内置智能体是只读,只带只读与可安全重试工具的是「可安全重试的修改」。「影响未知」的步骤在重启后停下来等人工确认,不会自动重跑。内建的记忆工具在 kernel/memory-tools.ts。
委托一致性(kernel/delegate.ts):
- 子运行提交成功后、开始等待前,子运行 ID 登记在步骤记录的
childRunId上。恢复重放到这一步时先找这个子运行:已完成就直接用它的结果(用量与步骤在同一个检查点里提交,只累加一次);仍在排队、执行或等审批就继续等;已中断或结果未知时,等级不是只读的步骤记为uncertain,等人工确认;以失败、取消或未完成结束时,只读与可安全重试的步骤重新委托,「影响未知」的步骤等人工确认。人工核对为「未执行」后,恢复时重新委托。 - 等待被父运行取消或网关关闭打断时,子运行照旧被取消;步骤等级不是只读就记
uncertain(子运行可能已经做了事),只读记failed。网关关闭时父运行因此成为interrupted/effect_outcome_unknown,恢复被拦在人工确认;父运行被取消时仍以cancelled结束。子运行以interrupted或effect_outcome_unknown结束、且步骤等级不是只读时,父运行同样进入人工确认流程。 - 委托自己管理超时:超时报
delegate_timeout(504),子运行被取消,定时器在结束时清理。 - 运行槽:父运行等子运行时借出自己的运行槽,让子运行能入场。按父运行计数,无论并行多少个委托只借出一个(0→1 借出,1→0 领回;领回时没有空位就等到有空位,中止或关闭时直接领回)。不变量:执行中的运行数 = 占用运行槽的运行数 + 借出运行槽的父运行数,且占用数在
[0, maxActiveRuns]内(只在中止拆除时可能短暂超出)。 - 网关启动恢复排队运行时,父运行已经不活跃(不在
queued/in_progress/requires_action)的排队子运行不再执行,以cancelled结束,错误码parent_interrupted(状态机不允许queued直接到interrupted)。 - 子运行的产物不并入父运行,只在委托结果的
artifacts里给出引用(文件 ID、名称、sha256 与下载地址)。
变更记录:2026-11-10 委托步骤的副作用等级;2026-11-11 委托一致性。
3.8 交接与备选智能体
智能体交接见 protocol.md 的「智能体交接」与 src/kernel/handoff.ts。交接只带对话层面的上下文,不带上一个智能体的工具调用细节、系统指令、原生会话句柄或 provider 轮次状态。
备选智能体(oaa.agent_fallback,kernel/fallback.ts):主力在开始做事之前失败时,同一个请求换下一个候选重新排队。候选按真实可用性(执行机器、调用方自带模型密钥 BYOK、沙箱条件)与完整的执行级别检查选取,不合格的候选被跳过。哪些错误不触发换人,由错误目录的 fallbackExempt 标记决定(见第 9 节)。
变更记录:2026-11-10 新增交接与备选智能体;2026-11-11 备选按真实可用性选取(T06c)。
4. 双层 Harness
调用方自己也是智能体(Cursor、Cline、Claude Code 等)时,请求里会带上它自己的 tools:外层是调用方的 Harness,内层是 OAA 智能体的 Harness。模式由请求选择,请求没选时由网关在知道智能体之后决定:auto(缺省)对能接管工具的智能体(内核智能体与 ACP 外部智能体)按 bridge 处理(调用方的工具以标准 tool_calls 交回调用方执行,同一个运行接着做),否则做该入口原来做的事;managed(调用方的工具不执行,响应头是 X-OAA-Client-Tools: ignored)、bridge、reject(报 client_tools_unsupported)可以显式选择。契约与支持矩阵见 harness.md。
内核里的入口在 kernel/harness.ts 与 kernel/client-tools.ts,网关侧在 gateway/client-tools.ts 与 gateway/bridge.ts。
5. 外部智能体接入
外部智能体(Codex、Claude Code 等原生智能体、ACP 智能体、oaa/1 / oaa/1-stream 适配器、A2A 远程智能体)在 engines/ 里接入,四种方式共用 engines/shared.ts。接入契约、各方式的流式 / 审批 / 取消 / 续接能力差异与 conversion 画像见 adapters.md。
入口约束:内核在入口统一约束外部智能体的进度(字段白名单、字符串截断、加 source: "agent")与审批详情(超过 256 KiB 直接拒绝);外部智能体的产物全部校验落盘后才标记步骤完成。详见 adapters.md「外部智能体事件的入口约束」。
6. 持久化与流
6.1 文本日志
文本日志在 schema v2 引入,此后的版本(当前 v4)都保留;它存放有序的输出事件,这些事件在通知观察者或 SSE 客户端之前提交。完整的模型 / 上下文快照在执行检查点写入,而不是每个文本增量都写。输出完成与对应的检查点是原子的;终止状态、摘要与终止事件也一起提交。不存在基于定时器的持久化空窗,也没有调低 SQLite 的同步级别。为了协议兼容,最终的消息事件仍然包含完整文本。
读取时把一个基线与其后的输出事件合并;一个有界的、128 个运行的投影缓存避免每次读取都重放。返回的消息是副本,投影之前先检查归属。控制台查询使用按 owner / 智能体划分的小摘要,而不是加载所有历史上下文。同步 HTTP 调用等待生命周期事件,而不是轮询 SQLite。这些改动不会在 owner 或会话之间缓存或共享模型对话。
被中断的生成会保留已提交的部分文本,消息状态为 incomplete;只有已确认的模型 / 工具检查点可以恢复。进程被突然杀死的情况由一个本地独立进程测试覆盖。这不能证明主机断电时的行为、磁盘可用性,也不是真实的跨机器验收。
6.2 检查点
工具检查点的提交顺序见 3.5;运行状态写入的校验见 3.2。
6.3 迁移
从 v1 / v2 的迁移在取得单网关租约之后以事务方式执行。它们保留已有的文本、事件、用量、时间戳、发布记录与凭据记录。Schema v3 加入了权威的节点策略及其审计,使旧版网关无法在忽略吊销的情况下重新打开数据库。schema v4 加入调用方数据隔离(见 protocol.md)。失败的迁移会回滚它的版本号和租约。更新的、无法识别的 schema 会被拒绝。升级已有部署之前,先保留一份私有的 SQLite 备份;不要降级数据库,也不要随意恢复旧的授权状态。
6.4 上游流与兼容流
providers/http-stream.ts 是 Anthropic / Gemini 模型驱动、A2A 与 HTTP 适配器共用的有限响应读取器。从 2026-11-10 起它用自己的增量解析器解析 SSE(同一文件里的 SseParser,按 WHATWG 规则编写;原先引用的 eventsource-parser 已移除),带流式 UTF-8 解码、CR/LF 规范化、有界的事件缓冲和总线上字节上限。EOF 时未结束的 SSE 帧被丢弃,而不是当作终止的证据,依据是 WHATWG event-stream 规则。中止、消费方提前返回与解析失败都会取消响应体并释放读取器;这一层从不重连,也从不重试一个可能有副作用的智能体调用。
Anthropic 的完成要求内容块已关闭且收到 message_stop,而不只是之前见过 stop_reason。不支持的 pause / refusal / 未知原因是显式的 upstream_incomplete 失败;token / 上下文上限仍是被截断的结果,不带可派发的工具调用。这依据的是文档中的 message lifecycle 与 stop reasons,不是一次真实提供方的验收声明。Gemini 要求显式的 finishReason:只有 STOP 是正常完成,MAX_TOKENS 是截断;被拦截的提示与其它所有原因都不算成功,也不触发级联重试。提供方的思考文本不放进公开回答。见 GenerateContent 契约。
A2A 在消费下一个事件或返回成功之前等待本地事件接收端完成,因此持久化失败不会被吞掉。非流式响应体与 agent card 检查在读取过程中就受限,而不是在无界缓冲之后再检查。
模型驱动不依赖厂商 SDK。OpenAI Responses / Chat Completions 驱动(OpenAIModel)直接用 fetch 发请求、用本项目的 SSE 读取器解析流,与 Anthropic、Gemini 驱动一致:不自动重试、不跟随重定向,请求体里只有代码里明确写出的字段,上游错误正文不会透传给调用方。连接超时只覆盖到收到响应头为止(与此前 SDK 的行为一致),已经开始的长回答不会被超时掐断。重放上一轮 Responses 条目时自行去掉输出专有字段,遇到不认识的条目类型仍报 invalid_provider_state。openai 包只在测试里用来验证兼容入口,在 devDependencies;eventsource-parser 不再被本项目代码引用,已从直接依赖里移除(它仍作为 MCP SDK 的间接依赖存在)。
兼容流的编码在 gateway/compat-stream.ts,其中每个字节都是兼容契约;逐字节测试见第 8 节、第 10 节与 engineering.md 第 7 节。
变更记录:2026-11-10 自有 SSE 解析器、OpenAI 驱动改用 fetch;server.ts 从约 2500 行降到约 1700 行(目前约 1540 行)(线上流编码移到 compat-stream.ts,OpenAPI 静态描述移到 openapi.ts,本机智能体管理、记忆、审计与密钥三组路由分别移到 local-backend-routes.ts、memory-routes.ts、key-routes.ts),这些都是不改变行为的移动,全量测试结果不变。
7. 分发网络
7.1 节点与放置
fabric/ 负责按能力与数据位置放置任务、WSS 租约任务、执行机器上的本地工具、提供方 SDK 与原生进程。执行机器主动向外连接;调度器不会把任务内容广播给每个节点。节点线协议见 protocol.md「Node wire protocol」。
7.2 选定工具导入与 MCP 连接
fabric/tool-import.ts 只解析显式选定的执行机器 / MCP 服务器与工具。发现阶段发送初始化与 tools/list,从不发送 tools/call;owner 配置的服务器仍可能有它自己的启动行为。准备阶段把公开的能力绑定与私有的执行机器覆盖配置分开。节点凭据仍需要对应的能力授权。一个审阅过的能力包可以在不重新读取可变源目录的情况下发布。
fabric/mcp-connections.ts 按 owner、会话与能力包摘要租用连接。凭据 / 配置变更时,旧条目对新调用方退役,活跃的租约逐个排空。普通的 MCP 领域错误不会让传输对其它调用方失效;有副作用的失败仍按保守方式处理。空闲连接有上限且是临时的。它目前针对的是仓库所用 MCP SDK v1 / 2025-11-25 握手配置,不声称只支持新协议的 2026 服务器已被验收。
导入的 schema 在 MCP 描述省略方言时显式选择 JSON Schema 2020-12。已有的、不带 $schema 的非 MCP 定义保留 draft-07 行为。2019-09 与显式的 draft-07 schema 也受支持。校验器有界并按 schema 内容划分作用域,因此复用的 $id 不会混淆新旧契约;外部引用不会被下载,异步 schema 被拒绝。元数据扫描会拒绝可识别的凭据模式和字面凭据字段,但这不能证明任意内容不含私密信息。
本地的 super-backend-codecraft 技能样本在不调用真实模型的情况下检查过:五个选定文件、一个有作用域的 MCP 源读取器,以及一个源哈希与选定文件一致的产物。它引用的个人归档既没有被解析也没有被复制。样本留在一个专用的仅本地节点上,没有改动主网关或全局技能。这是接线证据,不是技能语义质量或第三方账号集成的证明。
7.3 读缓存一致性
读缓存条目按会话 / 能力包 / 工具 / 输入划分作用域,并包含产物内容哈希。写操作开始与收尾时的代数栅栏,防止一个更早的、仍在进行的读取回填已经失效的缓存。与写操作重叠的读取不缓存;有写操作在进行时禁用缓存命中。产物发布同样会使待回填的条目失效。进程内 LRU 同时受 1,000 个条目与 16 MiB 序列化键值字节的限制;过大或不可缓存的值不会把一个已提交的工具结果变成失败。不可缓存的调用跳过键的哈希计算。这是保守的缓存失效,不是对外部系统的事务隔离,也不证明一个未知的远端写入已经停止。
7.4 目录与发现
gateway/catalog.ts、gateway/streams.ts 提供按作用域划分的目录失效视图、有界的重连历史、共享的 SSE 生命周期以及实时的凭据吊销。gateway/discovery.ts 提供发布修订号守卫、按字节限制的摘要 / 详情分页,以及显式的公开元数据投影;提示词、文件与私有处理器不在这个投影里。契约见 protocol.md。
8. 可观测性
目标是让一次运行「时间花在哪里」「为什么还在等」可以解释,同时不改变任何已有的持久化或线上语义。
- 只从持久化状态推导。时间线(
src/gateway/timeline.ts)读取三类数据:生命周期事件(response.created/in_progress/终止、run.queued/parked/requires_action、approval.resolved、tool.*、subagent.*),执行步骤,以及检查点里的模型轮次标记。输出增量不会被读取;response.*事件的大载荷在 SQL 里被替换为空对象。活动脉搏(src/gateway/activity.ts)读取运行摘要,并聚合最近已结束运行的时间线。 - 模型轮次标记放在检查点,而不是事件日志。原有日志里没有「模型轮次开始/结束」事件。新增事件会推移后续事件 ID:UAP NDJSON 帧携带
seq: <事件 ID>,id:行和sequence_number也一样,ID 跨越位数边界时线上字节数会变化。因此标记{turn, attempt, route, start, dispatched, end, status, calls}写在模型调用前后本来就会提交的检查点里:不增加事务,不增加 fsync,也不增加事件。原生执行的开始时间写在本来就会写入的原生步骤记录里(startedAt)。测试会逐字节核对兼容流(10,238 / 55,219 字节),并确认事件日志里没有新的事件类型。 - 依赖与关键路径:主线(排队、模型、原生、审批)按时间串联;工具依赖发起它的模型轮次、它的审批和执行图的
$ref/depends_on;下一轮模型依赖期间完成的整批工具。关键路径(决定总耗时的那条链)从最晚结束的 span 沿最晚结束的依赖回溯;时间拆分沿关键路径归因,空隙计入other,因此各项之和恒等于总时长,并行工具不会重复计时。 - 缓存与成本:时间线 ETag 绑定最后事件 ID;活动结果按概览修订号缓存,已结束运行的时间线按运行缓存(最多 1024 个)。活动统计在运行摘要的
(owner, ordinal)索引上分块倒序扫描,到窗口起点即停止,成本为 O(窗口内运行数)。 - 排队透明:内核准入队列与节点队列分别给出原因和估计值;数量类字段只统计同一 owner 的运行,避免泄露其它租户的负载。
- 未做的事:没有改 SQLite 结构,没有加索引(实测不需要),没有改 worker 线协议。
接口见 protocol.md「可观测内核」,控制台用法见 console.md。
变更记录:2026-11-08 新增。
9. 三份目录:错误、事件、限额
- 错误目录(
src/core/errors.ts):网关、执行节点与客户端会产生的全部稳定错误码,含类别、HTTP 状态、是否可重试、中文说明与下一步建议,通过GET /v1/errors对外提供(/health的features含error-catalog-v1)。三个调度标记也登记在目录里:routeRetryable(第一轮模型调用失败时可以换一条线路重试)、fallbackExempt(不触发换用备选智能体)、uncertainWhenStarted(外部执行已经开始后出现这个错误时,结果按未知处理),GET /v1/errors会带出这些标记。 - 事件目录(
src/core/events.ts):全部运行事件类型RUN_EVENT_TYPES,以及终止事件、输出事件与时间线事件三个子集。 - 限额目录(
src/core/limits.ts):集中命名的上限常量。外部智能体入口的上限单独放在AGENT_LIMITS。
怎么新增错误码与事件见 engineering.md 第 4 节;错误码表见 protocol.md「错误码」。
变更记录:0.2.0 新增三份目录;2026-11-11 三个调度标记并入错误目录(T06c)。
10. 证据与性能
各项测试与基准分别证明了什么、没证明什么:
npm test覆盖内核、真实的本地文件、真实的本地 HTTP / WebSocket / MCP 传输、官方 OpenAI SDK 兼容性,以及受控的原生子进程夹具。它不调用付费模型。npm run bench在同一运行时里用确定性延迟比较串行与并发调度。它特意把自己的测量标注为调度器微基准,而不是相对 OpenAI 或 AgentScope 的加速。node dist/bench/kernel-graph.js NEW_REPORT.json检查一个固定的异构 DAG、精确的结果哈希、工具调用次数与峰值并发,分别报告冷启动与热启动耗时。它拒绝覆盖已有报告。这是一个不含模型调用、SQLite 或远程执行机器的确定性调度器微基准,不是端到端的提供方性能结果。bench/kernel-core.ts:进程内模拟模型与工具,数字与测量条件见 3.4、3.5。bench/agent-stream.ts对一个进程内、无凭据的夹具测量一个固定的分片 A2A 响应,并拒绝覆盖报告;它是解析器 / 适配器基准,不是真实模型或网络延迟。npm run bench:stream -- --label NAME --out NEW_REPORT.json [--compare BASELINE.json]测量固定的本地流式工作负载。SQLite TEMP 触发器统计实际的快照写入次数与序列化快照字节数;运行器检查完整输出与游标重放,记录源码 / 工作负载哈希,并拒绝覆盖报告。它测量的是带插桩的本地内核 / 存储路径(含生命周期等待开销),不是提供方延迟。保留改动前的报告,改动后用另一个路径。bench/paired/增加了一个独立的 AgentScope 2.0.11 SDK 配置,不是模仿品,也不是改了名的 OAA 驱动。两个适配器使用同一个脚本化 I/O 控制器,并拒绝轨迹不一致的结果。它测试的是一个通用的推理 / 工具循环;不涉及图融合、真实的模型推理或等价的产品级持久化。报告保留了两者不同的持久化与系统提示语义、启动 / 首个事件 / 文本 / 最终耗时、依赖、源码快照与失败的尝试。不从框架名称或更早的单运行时基准推断任何正面比较。见 bench/paired/README.md。- 兼容流逐字节测试:
test/observability.test.ts按bench/protocol-speed.ts的同一工作量核对 UAP NDJSON 10,238 字节、OpenAI Chat SSE 55,219 字节。
真正的目标仍然是:在质量与成本不退化的前提下,并行信息源工作负载的端到端中位数提升至少 30%,简单任务的退化不超过 10%。这需要获得授权的配对提供方工作负载、相同的模型 / 工具、分开报告的冷 / 热测量,以及真实的远程机器。本地夹具的数字不声称达到了这样的结果。
11. 已知限制
单一网关;执行机器需要显式信任;对导入的原生运行时或 owner 注册的脚本没有操作系统沙箱。WSS 校验对端证书,但网关 / 执行机器的凭据是 bearer token 而不是双向 TLS。没有正在执行的原生智能体状态的迁移,不拥有推理的 KV 缓存,也不做投机性的重复外部写入。上下文是有界的信封,而不是一个未经验证的语义摘要器。原生账号访问、模型枚举的准确性、提供方定价以及已安装桌面连接器的一致性,都需要单独验证。
说明:「没有操作系统沙箱」一句保留原文。之后加入了可选的沙箱执行等级(见 sandbox-design.md 与 protocol.md「执行等级」),它的适用范围与局限以那两份文档为准。
12. 参考与来源
应用的研究(不声称是新发明)
- Nalar v2, September 2026:感知工作流的运行时元数据,以及分离的全局 / 局部决策。它的 KV 缓存管理需要控制推理基础设施,对远程提供方 API 没有实现。
- AgentWeave, October 2026:在安全的执行边界避免队头阻塞。论文要求声明流的语义;本项目同样不假设任意应用可以被自动切分。
- LLMCompiler:感知依赖的工具并行。这里的图要对照已发布的工具与副作用 / 资源约束做校验,而不是信任自由生成的代码。
- AgentScope 2.0:有用的功能与服务基线。较早的 AgentScope Runtime 仓库正在并入 2.0。它的真实模型基准没有在这里运行。
- OpenAI latency guidance:减少不必要的请求、并行执行独立工作、稳定的前缀。快速确认与实际任务完成分开测量。
Sub2API 的影响
阅读了 Sub2API 及其 composite model route contract,源码检查基于提交 d851a38477597157e78450d30af2d8504764d085。
采纳的设计思想是显式的模型别名、感知作用域的分发键、粘性会话、负载 / 健康信息以及有界的冷却。这里的单位是智能体加上能力与执行位置,而不只是一个账号。没有复制任何 Sub2API 源码;没有实现订阅凭据提取、隐藏的账号端点、支付系统或账号共享池。
署名
src/config/agent-presets.ts 文件头与 THIRD_PARTY_NOTICES.md 中的 Apache-2.0 署名保留。
附:未实现的提案
W3C Trace Context
建议分三步,且只在每一步风险可控时推进:
- 调用入口(
/v1/responses、/v1/chat/completions、/v1/messages、/v1/uap、/v1/invoke、Gemini 端点)接受并校验traceparent(00-<32 hex>-<16 hex>-<2 hex>,非法值忽略)和tracestate(长度上限 512),记在运行的独立字段上,而不是metadata,避免改变幂等指纹与响应对象;在时间线和state中回显trace: {trace_id, parent_id}。 - 子智能体运行继承
trace_id并生成新的 parent id;时间线的子智能体 span 带上子运行的 trace。 - 向 worker 透传需要在
WorkContext中新增可选字段。远程 worker 的协议解析需要先确认能容忍未知字段,并通过welcome.features协商(例如trace-context-v1),否则旧 worker 可能拒绝任务。这一步改变节点线协议,应单独评审。
不实现的原因:第 1、2 步需要把新参数穿过所有调用入口和 kernel.submit;第 3 步会改变节点线协议。当前优先保证可观测接口的正确性,并且不改变任何线上字节。
变更记录:2026-11-08 提出。