Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

mini-harness 教程:从一次请求读懂 Agent Harness

这是一份对照源码学习的教程。目标不是让你背下几个术语,而是让你能打开这个仓库,沿着一次真实请求走完代码,并解释每一个边界为什么存在。

你不需要先了解 Agent、事件溯源或分布式系统。只要会一点 Rust,愿意边读边运行命令,就可以从第 0 章开始。

这不是重写一个 Harness

你要学习的是当前仓库里的这份实现。教程不会要求你新建项目、复制一套代码,或在每章末尾得到一个“自己的 mini-harness”。

每章都采用同一个方法:

  1. 先从一个用户动作或一次故障开始;
  2. 找到当前代码处理它的入口;
  3. 顺着数据、事件和状态往下读;
  4. 用现有测试或一个只读命令验证理解;
  5. 再解释为什么这个边界必须这样设计。

教程中的“任务”统一指一次源码阅读、运行观察或测试验证。

先用一句话理解 Harness

模型只负责提出建议:回答用户,或者请求调用某个工具。

Harness 负责把建议变成受控的现实动作:检查权限、执行文件或进程、记录发生过的事实、处理取消与崩溃,并把结果重新交给模型。

可以把它想成一个有门卫、有账本、有急停按钮的工作台:

用户输入
   │
   ▼
Session / Turn ──▶ Provider(模型)──▶ Tool call(建议)
   │                                      │
   │                              Policy(能不能做)
   │                                      │
   │                              Executor(实际去做)
   │                                      │
   └──────────── Event log(发生过什么)◀─┘

这份教程怎样和源码对应

教程中的“第 3 章”等于当前仓库中的一个主题,不代表源码提交历史中的一天。每章都会明确列出:

  1. 先读哪些真实文件;
  2. 一次调用从哪个函数进入、经过哪些函数;
  3. 运行哪条命令或测试观察结果;
  4. 哪些代码是核心,哪些是为生产边界补上的细节。

源码地图

你要理解的东西当前源码先看什么
公共模块和导出src/lib.rs项目有哪些边界
ID、历史、会话状态src/runtime/ids.rs、src/runtime/state.rsSessionState、TurnState
事件模型src/durable/event.rsEventPayload、Event
reducersrc/durable/reducer.rsreduce 如何拒绝非法序列
事件存储src/durable/store.rs、src/durable/event_log.rstrait 与 JSONL 实现
模型抽象src/model/provider.rsModelRequest、ModelResponse、ModelProvider
主循环src/runtime/agent_loop.rsappend、run_turn_with_cancel
恢复和构造src/runtime/agent_loop_setup.rsrestore、restore_with_checkpoint
actorsrc/runtime/session.rs、src/runtime/session_actor.rs命令如何串行化
工具src/tools/Tool、ToolRegistry、read/edit/bash
执行器src/executor/文件和进程的真实副作用
协议src/protocol/jsonl.rs请求循环、事件通知、安全投影
UIsrc/ui/UI 如何只消费协议
CLI 组装src/main.rs各个模块怎样接起来

十分钟预览:先看一条真实链路

先不要从类型定义开始。先让程序跑一次离线演示:

cargo run -- demo read README.md

这个命令使用 src/main.rs::run_demo 组装组件:

  • MockProvider 按脚本返回一个 read 调用,再返回文本 read complete;
  • ToolRegistry 注册 ReadTool、EditTool、BashTool;
  • LocalExecutor 把工作区设为当前目录;
  • InMemoryEventStore 保存事件,所以不会改动磁盘上的会话日志;
  • Session::start_turn 启动一次 turn。

把输出看成一条时间线,大致会得到:

session.created
user.input.recorded
turn.started
provider.continuation.updated
model.response.recorded        # 模型先提出 read
tool.requested
tool.started
tool.completed                  # 文件内容回到历史
provider.continuation.updated
model.response.recorded        # 模型最后说 read complete
turn.completed

这几行已经包含了全项目的核心思想:模型的建议、工具的执行结果、最终回答,全部先成为事件,状态再从事件中推导出来。

想看完整 JSON,可以运行:

cargo run -- demo read README.md --json

第一次看到很长的工具输出是正常的。先只关注每个对象的 seq、payload.type 和 turn_id;字段含义会在第 1、2 章逐个解释。

你会学到什么

章节主题读完后能回答的问题
第 0 章先建立一张地图模型、工具、权限和持久化分别是谁负责?
第 1 章先读懂类型和事件为什么不同 ID 不能都用 String?
第 2 章EventStore 和 reducer——日志怎样变成状态重启后状态怎样从日志恢复?
第 3 章MockProvider、Session 和 actor怎样不联网先验证主循环?
第 4 章Tool、Policy 和 Executor——一次 read 怎样到达文件系统参数检查、权限检查和真实读文件为什么分层?
第 5 章AgentLoop——一轮 turn 怎样反复采样工具结果怎样回到下一次模型请求?
第 6 章进程、取消和原子编辑怎样避免进程泄漏、管道死锁和半个文件?
第 7 章崩溃恢复——系统怎样面对“不知道”为什么“失败”和“结果未知”不能混为一谈?
第 8 章真实 provider——Responses 与 Chat Completionsprovider 换了,主循环为什么不用改?
第 9 章CLI 和 JSONL 协议——把 runtime 放到进程边界外为什么 stdout 只能输出协议?
第 10 章事件查看器和 Ink TUI——UI 只是事件投影UI 崩溃时,runtime 怎样继续工作?
第 11 章Scheduler、durable 队列和全局并发输入队列怎样做到可恢复?并发上限放在哪里?
尾声把这份 Harness 读成一个系统怎样继续做 sandbox、PTY、MCP 或远程执行器?

术语不确定时,查术语表。

每章的阅读顺序

不要一开始就试图理解整章所有细节。每章按下面顺序读:

  1. 先看本章问题:知道这一章要解释哪个运行时行为;
  2. 再看源码对照:打开列出的文件,先找结构体和入口函数;
  3. 运行观察命令:把抽象概念变成输出或事件;
  4. 逐步读主路径:只追一条成功路径;
  5. 最后读失败路径和测试:理解边界是怎样被锁住的;
  6. 再做思考题:用自己的话解释“如果删掉这条检查会发生什么”。

每章的代码片段用于帮助你定位源码和理解关键步骤,不是另一份独立实现。源码中已经存在的实现才是最终事实;如果教程文字和源码不一致,以源码和对应测试为准,并把差异记下来。

文中的代码片段用于定位源码和解释关键步骤。先不要复制代码;只有当你想检验自己是否真的掌握时,才把某个函数改成小实验,再用测试恢复。

环境和常用命令

要求:Rust 1.85+,2024 edition。

rustc --version
cargo test
cargo test --test integration_agent_loop
cargo test --test recovery_classify
RUST_LOG=mini_harness=debug cargo run -- demo read README.md

cargo test 是离线的。只有第 8 章的真实 provider 部分需要 API key;教程会先用 mock HTTP server 讲清楚协议,因此不必一开始准备密钥。

学习中的三个约定

1. 看到 Event,先问它记录的是事实还是状态

tool.completed 是事实;“当前有没有正在运行的工具”是 reducer 推导出来的状态。这个区分会贯穿恢复、协议和 UI。

2. 看到 Arc,先问谁拥有写权限

共享读取很常见;会话状态和事件追加只有 actor 能改。后面看到 SessionCommand,把它理解为“请求唯一写者替我做一次状态迁移”。

3. 看到 Result,先问错误由谁处理

工具参数错误可以回给模型;策略拒绝要显示给用户;事件日志损坏通常要停止恢复。错误类型的边界就是模块边界的说明书。

准备好后,从第 0 章:先建立一张地图开始。

第 0 章:先建立一张地图

这一章不让你写代码。你要做的是用当前仓库跑出一条请求,然后知道每个文件在这条请求中扮演什么角色。

后面章节会反复回到这张地图。如果某一章看不懂,先回来问自己:它是在处理模型建议、工具副作用、事实记录,还是客户端显示?

一个只完成表面工作的 agent

下面的循环看起来很像 agent:

while True:
    reply = llm(messages, tools=TOOLS)
    if reply.tool_call:
        result = run_shell(reply.tool_call.command)
        messages.append(result)
    else:
        print(reply.text)
        break

它能在理想环境下回答问题,但没有定义:

  • Ctrl-C 是否杀掉子进程;
  • 500 MB 输出是否会撑爆内存;
  • 文件改了一半时崩溃怎样恢复;
  • workspace 外的路径谁来拒绝;
  • 两个调用同时修改同一个文件怎么办;
  • UI 退出后会话是否还活着。

harness 负责的就是这些模型循环之外的系统行为。模型提出建议,harness 决定怎样验证、授权、执行、记录和恢复。

先运行当前项目

在仓库根目录运行:

cargo test
cargo run -- demo read README.md

demo 是 src/main.rs 中的 run_demo。它使用 MockProvider、LocalExecutor、ToolRegistry、DefaultPolicy 和 InMemoryEventStore,完成一次不联网的 read 工具调用。

它不会把事件写到持久化 JSONL 文件,所以适合第一次观察。

想看到完整事件:

cargo run -- demo read README.md --json

把输出先看成一条时间线:

session.created
user.input.recorded
turn.started
provider.continuation.updated
model.response.recorded        模型提出 read
tool.requested
tool.started
tool.completed                  文件内容回到历史
provider.continuation.updated
model.response.recorded        模型给出最终文本
turn.completed

你不需要先理解每个字段。先确认这条因果链:

用户输入
  → 模型提出工具调用
  → runtime 记录请求
  → policy 允许
  → executor 读取文件
  → 结果进入历史
  → 模型再次响应
  → turn 完成

八个核心名词

名词当前项目中的含义
Session一段持续的会话和它的事件历史
Turn一次用户输入到最终回答、失败或取消
Stepturn 中的一次模型请求和处理
Provider把模型服务翻译成 ModelRequest 和 ModelResponse
Tool模型可以请求的操作,例如 read、edit、bash
Policy决定工具调用是 Allow、Ask 还是 Deny
Executor真正访问文件和进程的能力层
Event已经发生的事实
Statereducer 从事件推导出的当前视图

Session、Turn、Step 和 ToolExecution 是层次关系:

Session
  └─ Turn
       ├─ Step
       │    └─ ToolExecution
       ├─ Step
       └─ ...

一个模型响应可以没有工具调用,也可以包含一个或多个工具调用。一个工具调用有模型的 ToolCallId,实际执行还有 ExecutionId。第 1 章会解释这些身份。

当前项目的模块地图

先打开 src/lib.rs,确认项目导出的模块:

config
durable
error
executor
model
policy
protocol
runtime
scheduler
tools
ui

再按下面的角色理解每个目录:

src/main.rs
  └─ CLI 入口和组件组装

src/runtime/
  ├─ agent_loop.rs       一次 turn 的主循环
  ├─ agent_loop_setup.rs 构造和恢复 AgentLoop
  ├─ session.rs          Session、SessionHandle、SessionCommand
  ├─ session_actor.rs    单写者命令循环
  ├─ context.rs          给模型的有限快照
  └─ state.rs            SessionState 和派生生命周期

src/model/
  ├─ provider.rs         Provider trait 和模型类型
  ├─ mock.rs             确定性 mock
  ├─ openai.rs           HTTP provider
  └─ openai_protocol.rs  两种 wire format 的转换

src/tools/
  ├─ spec.rs             Tool、ToolSpec、ToolContext
  ├─ registry.rs         工具注册和查找
  └─ read.rs/edit.rs/bash.rs

src/executor/
  ├─ trait.rs            文件、进程、编辑的能力接口
  ├─ local.rs            本地 executor
  ├─ process.rs          进程组、排空、输出上限
  └─ filesystem.rs       路径和原子编辑

src/durable/
  ├─ event.rs            Event 和 EventPayload
  ├─ reducer.rs          事件到状态
  ├─ store.rs             EventStore trait
  ├─ memory.rs            内存事件日志
  ├─ event_log.rs         JSONL 事件日志
  ├─ recovery.rs          崩溃分类
  └─ checkpoint.rs        快照和重放

src/protocol/
  ├─ jsonl_transport.rs  有界 JSONL 传输
  ├─ jsonl.rs             serve --stdio
  └─ event_projection.rs  安全事件投影

目录不是学习顺序。学习顺序应该跟着一条数据流:

main.rs 组装组件
  → Session.start_turn
  → AgentLoop.run_turn_with_cancel
  → Provider.complete
  → ToolRegistry.lookup
  → Tool.execute
  → Executor
  → AgentLoop.append
  → EventStore
  → reducer

六条设计边界

模型边界

Provider 只看到 ModelRequest,返回 ModelResponse。它不修改 runtime state,也不决定权限。

工具边界

Tool 解释模型输入,生成模型可读结果。它通过 ToolContext 获得能力,不持有 Session 或 EventStore。

执行边界

Executor 处理文件和进程等外部副作用。它有结构化错误、取消、超时和输出限制。

持久化边界

Event log 保存事实。SessionState 是 reducer 产物,checkpoint 是加速重放的缓存。

并发边界

每个 session 的状态和追加由一个 actor 负责。其他线程或进程通过命令和 durable store 参与。

客户端边界

CLI、TUI 和 Ink UI 通过 JSONL 协议发命令和消费事件投影。它们不直接调用 provider 或 executor。

这一章的阅读动作

现在打开 src/main.rs 的 run_demo,按以下顺序跳转:

  1. 找 MockProvider 的脚本;
  2. 找三个工具如何注册;
  3. 找 Session::new_with_policy;
  4. 找 Session::start_turn;
  5. 找 AgentLoop 的 begin_turn 和 continue_turn;
  6. 找 tool completed 后 history 如何变化;
  7. 找事件最终从 InMemoryEventStore 读出并打印的位置。

每跳到一个函数,只记两句话:

它拿到什么?
它把什么交给下一层?

不要在这一步停留在 tokio、泛型或 serde 的细节。先弄清数据流,再在后面的章节回头理解实现细节。

第 0 章检查

你能做到下面四件事,就可以继续:

  • 用一句话解释 harness 和“给模型加几个工具函数”的区别;
  • 从 run_demo 追到 ReadTool 和 LocalExecutor;
  • 说出 Event、State、Policy 和 Executor 各自负责什么;
  • 从 demo 输出指出 tool.requested、tool.completed 和 turn.completed 的先后关系。

思考题

  1. 为什么 UI 只消费事件投影,而不是直接拿 SessionState?
  2. 如果 provider 直接执行 bash,Policy 和 Executor 还剩下什么意义?
  3. 如果只保存 SessionState,不保存事件,崩溃恢复会失去什么?
  4. 一个新的远程 executor 应该替换哪一层?为什么 AgentLoop 不应该跟着重写?
  5. 如果允许两个工具并行执行,当前“单写者 + 顺序事件”要重新回答哪些问题?

下一章:先读懂类型和事件。

第 1 章:先读懂类型和事件

这一章回答一个问题:这份 harness 用什么类型描述“谁在做什么”,又用什么事件记录“已经发生了什么”?

你暂时不需要理解异步,也不需要理解模型 API。先把项目的词汇读懂,后面每个模块都会复用这些词汇。

这一章在整条链路中的位置

一次工具调用至少涉及四个身份:

SessionId    哪个会话
TurnId       哪一轮用户请求
ToolCallId   模型提出的哪一次工具调用
ExecutionId  runtime 实际启动的哪一次执行

它们都会出现在事件里,但含义不同。把四个 ID 都写成 String,代码可以编译,错误却会在运行时才暴露。当前项目在 src/runtime/ids.rs 里用同一个宏生成这些 newtype。

先打开这个文件的底部。你会看到 SessionId、TurnId、StepId、ToolCallId、ExecutionId、EventId 和 TaskId。每个类型内部都包着一个 UUID,但显示和序列化时会带前缀,例如 sess_、turn_、call_。前缀是给日志和人看的,newtype 是给编译器看的。

从一个 ID 读出 Rust 的边界意识

src/runtime/ids.rs 中的宏为每个 ID 提供了四类能力:

  1. new:生成随机 UUID;
  2. Display:打印带前缀的字符串;
  3. parse 和 FromStr:拒绝错误前缀或坏 UUID;
  4. Serialize 和 Deserialize:JSON 中仍然保持同样的格式。

因此协议收到 turn_... 时,解析成 TurnId;同一个字符串不会因为“长得像”就自动成为 ToolCallId。

src/runtime/types.rs 放的是更高层的值类型:

类型表示什么常见位置
UserInput用户给出的文字history 和 user.input.recorded
ModelText模型产生的文字assistant history 和最终回答
ToolResult工具给模型的结果tool history
ToolName工具注册名ToolSpec、ToolCall
EventSeq会话内单调递增的序号Event
ByteLimit一个字节上限工具和执行器配置

这些类型不一定解决安全问题,但能让函数签名说清楚数据的用途。看到一个 String 时,你要问它是不是应该变成更明确的类型。

Event 有两层

打开 src/durable/event.rs。EventPayload 表达“发生了什么”,Event 表达“这件事属于哪个会话、发生在什么时候、排在第几条”。

EventPayload
  └─ SessionCreated
  └─ UserInputRecorded
  └─ TurnStarted
  └─ ToolRequested
  └─ ToolStarted
  └─ ToolCompleted
  └─ TurnCompleted
  └─ ...

Event
  ├─ schema_version
  ├─ event_id
  ├─ seq
  ├─ timestamp
  ├─ session_id
  ├─ turn_id
  └─ payload

把它类比成账本:

  • payload 是“取款”或“存款”这类事实;
  • seq 是账本行号;
  • session_id 是账户;
  • event_id 是这条记录自己的身份证;
  • timestamp 是观测信息;
  • turn_id 说明这条事实属于哪一次用户请求。

Reducer 只根据事件内容和顺序改变状态。它不能因为当前时间、网络结果或随机数而得到不同结果。

从 demo 找到事件

运行:

cargo run -- demo read README.md --json

把 JSON 数组中每个对象的 payload.type 记下来。当前项目的最小 read 演示通常会出现:

session_created
user_input_recorded
turn_started
provider_continuation_updated
model_response_recorded
tool_requested
tool_started
tool_completed
provider_continuation_updated
model_response_recorded
turn_completed

这里的两个 model_response_recorded 分别对应模型提出工具调用和模型给出最终文本。provider_continuation_updated 保存 provider 续传所需的事实;它仍然属于同一个 turn。

错误类型也在描述边界

打开 src/error.rs。HarnessError 把错误按处理者分组:

  • Durable:事件日志或 checkpoint 有问题;
  • Provider:模型服务或响应格式有问题;
  • Tool:工具参数或模型可见的工具错误;
  • Execution:文件、进程和操作系统错误;
  • Policy:策略拒绝;
  • ApprovalPending:等待用户决定;
  • Cancelled 和 Timeout:控制流;
  • InvariantViolation:代码认为不可能发生的状态;
  • QueueLimitExceeded:输入队列已满。

读到一个错误时,先问“谁能处理它”。模型可以看到工具输出形式的错误,用户可以批准或拒绝工具,runtime 必须停止处理损坏的日志。

对照测试阅读

先运行:

cargo test ids_are_round_tripable_and_type_scoped
cargo test jsonl_reopens_and_replays

然后打开对应测试,按这个顺序看:

  1. 测试创建了哪一种 ID;
  2. 它打印和解析的字符串是什么;
  3. 它如何构造 Event;
  4. 它最后断言了哪些字段相等。

测试不是额外知识,它是当前实现对这些类型做出的承诺。

你这一章应该能说清楚

  • ToolCallId 为什么不能传给只接受 ExecutionId 的函数;
  • EventPayload 和 Event 的职责差异;
  • timestamp 为什么可以进事件,但 reducer 不应读取它;
  • 一个错误为什么要区分 Policy、Provider、Execution 和 Durable。

思考题

  1. 如果把所有 ID 改成 String,哪一类错误会从编译期推迟到运行期?请举一个具体函数调用。
  2. 为什么 EventId 和 seq 都存在?如果只保留其中一个,诊断或并发追加会失去什么信息?
  3. ToolResult 和 ModelText 都包着 String。你会在哪些函数边界拒绝它们互换?
  4. 一个 provider 自己返回的 call_id 应该在哪一层转换成 ToolCallId?为什么不让 reducer 负责?
  5. timestamp 被篡改会影响状态重放吗?它会影响哪些诊断能力?

下一章:EventStore 和 reducer——日志怎样变成状态。

第 2 章:EventStore 和 reducer——日志怎样变成状态

第 1 章介绍了事件的形状。这一章追问:事件写在哪里?重启后,系统怎样知道当前会话进行到哪一步?

当前项目把答案拆成两个模块:

  • EventStore 负责保存和读取事件;
  • reducer 负责把事件应用到 SessionState。

这两个模块分开,是整个恢复能力的基础。

先看三个真实文件

按这个顺序打开源码:

  1. src/runtime/state.rs:SessionState、TurnState、HistoryItem;
  2. src/durable/reducer.rs:reduce;
  3. src/durable/store.rs、src/durable/memory.rs、src/durable/event_log.rs:EventStore 及实现。

不要一开始读 event_log.rs 的所有文件锁和缓存。先理解下面的纯数据流:

事件日志
  └─ Event 1
  └─ Event 2
  └─ Event 3
       │
       ▼
reduce(state, event)
       │
       ▼
SessionState
  ├─ status
  ├─ active_turn
  ├─ history
  ├─ pending_inputs
  ├─ provider_continuation
  └─ last_seq

SessionState 是“从日志计算出来的当前视图”。它很重要,但它不是唯一事实。进程崩溃后,runtime 可以重新从事件构造它。

SessionState 里最值得先读的字段

src/runtime/state.rs 中的 SessionState 有几个字段:

字段含义
session_id这份状态属于哪个会话
statusIdle、Running、Failed 或 Closed
active_turn当前是否有正在处理的 turn
history给后续模型请求使用的对话历史
pending_inputsturn 运行时排队的用户输入
provider_continuation下一次 provider 请求需要的续传信息
last_seq已应用到状态的最后一条事件序号

TurnState 再记录某一轮内部发生的事情:模型最近的响应、工具调用 ID、每个工具的 ExecutionState、审批状态和最终文本。

注意“当前有几个工具正在运行”没有单独存成一个事实字段。它由 active_turn.executions 中的 Running 状态推导出来。

reducer 既是更新器,也是验证器

打开 src/durable/reducer.rs 的 reduce。它一开始就做三类检查:

1. event.session_id 必须等于 state.session_id
2. event.seq 必须等于 state.last_seq + 1
3. 空状态的第一条事件必须是 SessionCreated

然后它按 EventPayload 分支处理。例如:

  • UserInputRecorded 把用户输入写进 history,并加入 pending_inputs;
  • TurnStarted 从 pending_inputs 取出一条,创建 active_turn;
  • ToolRequested 创建 Pending execution;
  • ToolStarted 把 Pending 变成 Running;
  • ToolCompleted 把 Running 变成 Completed,并把工具结果放进 history;
  • TurnCompleted 关闭 active_turn;
  • TurnFailed、TurnCancelled 和 TurnTimedOut 结束当前 turn。

这些分支同时验证状态迁移是否合法。因此以下事件顺序会被拒绝:

ToolCompleted 出现在 ToolStarted 之前
同一 call_id 被完成两次
TurnCompleted 时仍有 Running 工具
另一个 session 的事件混进来
seq 从 41 跳到 43

严格拒绝的好处是:恢复时不需要猜日志作者想表达什么。一个能被打开的日志就是一个通过状态机检查的日志。

EventStore 的两个实现

EventStore trait 只有三个核心操作:

append(event)      追加事实,并返回最终保存的事件
read_from(seq)     从某个序号开始读取
last_seq()         查询最后一个序号

InMemoryEventStore 把事件放在 Vec 中,适合测试和 demo。JsonlEventStore 把每个事件写成一行 JSON,适合持久化会话。

两者对调用方提供同一套语义,但职责不完全相同:

  • AgentLoop 在 append 前会计算自己期待的序号,并检查 store.last_seq;
  • EventStore 在自己的锁内重新分配最终 seq;
  • AgentLoop 检查 store 返回的 seq 是否与期待值一致;
  • JsonlEventStore 负责文件锁、半行检测、大小上限和缓存。

这也是为什么 EventStore::append 返回 Event,而不是只返回成功或失败。

JSONL 为什么选择“一行一个事件”

JSONL 的每一行都是一个可以独立解析的 Event。它有几个直接好处:

  • 追加新事件很简单;
  • 崩溃后可以定位最后一行;
  • 读日志时可以逐行验证;
  • shell 和普通工具容易观察;
  • 读取路径可以报告具体行号。

当前 JsonlEventStore 对文件有严格规则:

  1. 空文件可以打开;
  2. 完整行必须能解析成 Event;
  3. 文件末尾没有换行时,读取报半行损坏;
  4. 中间损坏行不能自动修复;
  5. 每行 seq 必须与行号一致;
  6. 超过事件数量或总字节上限要拒绝。

半行修复是显式命令 repair_partial_tail 的工作。读取时静默丢掉最后半行,会把“崩溃残留”误当成“没有发生过”。

一次 append 的事务顺序

src/runtime/agent_loop.rs 中的 append 是理解整个 runtime 的关键函数。它大致这样工作:

旧 state
  │
  ├─ 计算 expected_seq
  ├─ 检查 store.last_seq
  ├─ 组装 event,检查事件大小
  ├─ clone 出 next_state
  ├─ reduce(next_state, event)
  │       └─ 失败:不写盘
  ├─ store.append(event)
  │       └─ 失败:状态不提交
  ├─ 检查 store 返回的 seq
  └─ self.state = next_state

“验证 → 持久化 → 提交”这条顺序解决两个风险:

  • 非法事件不会污染日志;
  • 内存状态不会领先于持久化事实。

但它不能让外部世界拥有 exactly-once 语义。文件已经改了、进程已经发出网络请求,随后日志追加失败,这个窗口会在第 7 章讨论。

用测试观察重放

运行:

cargo test jsonl_rejects_sequence_gaps_and_middle_corruption
cargo test jsonl_rejects_partial_tail
cargo test reducer_allows_recovery_input_after_failure_but_not_close
cargo test --test property_replay

阅读 property replay 测试时,关注两个断言:

  • 同一事件序列重复 reduce,结果完全相等;
  • 非法序列会返回错误,而不是 panic。

这两个性质分别对应“可恢复”和“可诊断”。

这一章读完后

你应该能从一条事件回答:

  • 它会改变 SessionState 的哪些字段;
  • 它要求当前状态满足什么前置条件;
  • 它能否被重放;
  • 它失败时应该阻止追加,还是生成一个终态事件。

思考题

  1. 如果 reducer 在处理 ToolCompleted 时读取当前文件内容,会破坏什么性质?
  2. 为什么 JsonlEventStore 不能在读取时自动丢掉末尾半行,却可以提供单独的 repair_partial_tail?
  3. 如果 append 已经把事件写入文件,但进程在 self.state = next_state 之前崩溃,重启时会发生什么?
  4. 为什么 SessionState 的 pending_inputs 要从事件推导,而不是只存在 actor 的 VecDeque 中?
  5. 你会把 checkpoint 当成事实,还是当成缓存?如果 checkpoint 损坏,正确的退路是什么?

下一章:MockProvider、Session 和 actor。

第 3 章:MockProvider、Session 和 actor

这一章把前两章的类型和事件放进一次真实 turn。重点不是模型回答得多聪明,而是看 runtime 怎样在没有网络的情况下验证自己的语义。

当前项目有两种使用 Session 的方式:

  • 直接使用 Session:适合测试、CLI 和库调用;
  • 使用 SessionHandle:背后启动 session actor,适合协议、TUI 和需要中途取消的调用方。

先看 Provider trait

打开 src/model/provider.rs。最重要的类型是:

ModelRequest
  ├─ model
  ├─ system_instructions
  ├─ history
  ├─ tools
  └─ continuation

ModelResponse
  ├─ Text
  ├─ ToolCall
  ├─ ToolCalls
  └─ TextWithToolCalls

ModelProvider
  └─ complete(request, cancel) -> ModelResponse

Provider 只负责把请求送给模型并把响应翻译成统一类型。它不应该:

  • 直接修改 SessionState;
  • 直接追加事件;
  • 直接执行工具;
  • 决定一个工具是否有权限执行。

这些行为属于 runtime、policy 和 executor。

ModelRequest 是拥有所有权的值。Provider 收到它之后,可以把它交给 HTTP client、mock 脚本或别的实现,但不会拿到 AgentLoop 的可变引用。这样 provider 可以替换,主循环不用跟着变。

MockProvider 为什么重要

打开 src/model/mock.rs。MockProvider 通常包含两部分:

script
  └─ 按顺序取出的 MockResponse

requests
  └─ 保存每次收到的 ModelRequest,供测试检查

例如 demo 的 read 脚本是:

1. ToolCall(name = read, input = {"path":"README.md"})
2. Text("read complete")

它模拟模型先请求工具,再看到工具结果后给出最终文本。脚本耗尽时返回结构化 provider 错误,不应该 panic。

requests 让我们能观察上下文是否正确:

第 1 次 request.history
  └─ 用户输入

工具完成之后的第 2 次 request.history
  ├─ 用户输入
  └─ HistoryItem::Tool { result: ... }

如果第二次请求没有工具结果,runtime 的闭环就没有完成。

直接使用 Session 的路径

打开 src/runtime/session.rs 中的 Session 和构造函数。直接使用 Session 的调用大致是:

Session::new_with_policy(...)
  └─ 内部创建 AgentLoop

Session::start_turn(input)
  └─ AgentLoop::run_turn(input)
      └─ 返回 (TurnId, final_text)

这种方式简单,适合单线程式的库调用。它的限制也很明确:start_turn 正在运行时,调用方没有另一个命令入口可以发送 cancel。

这就是为什么 CLI 中的简单 run 可以使用 Session,而 TUI、JSONL server 和跨进程操作通常使用 actor handle。

actor 的路径

SessionHandle 背后是一个 tokio task。调用方不直接碰 AgentLoop,而是发 SessionCommand:

调用方
  │
  ├─ mpsc::Sender<SessionCommand>
  │
  ▼
session_actor::run_actor
  │
  ├─ 唯一持有 AgentLoop
  ├─ 唯一追加事件
  └─ oneshot::Sender 返回本次命令的结果

当前 SessionCommand 包含 StartTurn、CancelTurn、ApproveTool、WaitTurn、Checkpoint、QueryState 和 Shutdown。

mpsc 传命令,oneshot 回结果。mpsc 适合连续接收请求,oneshot 适合“一条命令对应一个回复”。

一个文本 turn 怎样走完

对于 MockProvider 返回 Text 的情况,主路径可以简化成:

Session::start_turn
  → begin_turn
      → user.input.recorded
      → turn.started
  → ContextSnapshot::from_state
  → ModelProvider::complete
  → provider.continuation.updated(有变化时)
  → model.response.recorded
  → turn.completed
  → 返回文本

错误路径同样要记录事实。例如 provider 失败时,不能只把 Err 返回给调用方;runtime 还要追加 turn.failed。否则日志会停在 Running,恢复系统无法知道这是一个已经结束的失败 turn,还是进程在执行中崩溃。

actor 为什么不是 Arc<Mutex>

共享一个 Mutex 也能让代码运行,但它会把几个问题混在一起:

  • 谁可以在 await 期间持有锁;
  • 状态迁移和事件追加是否同时发生;
  • cancel 和 start 谁先修改状态;
  • 一个命令失败后,锁内状态是否已经改变。

actor 的规则更直接:只有 actor 能修改 AgentLoop,其他组件只能发命令。逻辑上的原子性由命令顺序和 append 事务保证。

当前 actor 在活跃 turn 期间会 select 命令通道:

  • CancelTurn 会触发 turn token;
  • WaitTurn 会保存 waiter;
  • StartTurn 会暂存,等 AgentLoop future 释放可变借用后再 durable 地排队;
  • Checkpoint 会延迟到安全点;
  • Shutdown 会取消并等待清理。

“收到命令”和“马上修改 state”不是同一个时刻。这个区别是读 session_actor.rs 时最容易漏掉的地方。

读测试的方式

运行:

cargo test mock_script_exhaustion_is_a_provider_error
cargo test provider_error_records_turn_failed
cargo test wait_turn_observes_provider_failure_after_start_ack
cargo test session_actor

读 actor 测试时,画两条时间线:

StartTurn 的 ack 什么时候返回
WaitTurn 的结果什么时候返回

这两个时间点不一定相同。StartTurn 说明请求已经被接受,WaitTurn 说明 turn 已经有最终结果。

这一章读完后

你应该能解释:

  • MockProvider 为什么不只是测试替身;
  • ModelRequest 为什么必须是拥有所有权的快照;
  • Session 和 SessionHandle 的使用场景差异;
  • actor 如何保证只有一个写者;
  • provider 错误为什么也要留下 turn.failed。

思考题

  1. 如果 Provider trait 接收的是 &mut SessionState,会出现哪两种边界混乱?
  2. 为什么 StartTurn 和 WaitTurn 要分开?把它们合成一个阻塞调用会让哪个客户端难以实现?
  3. actor 在执行模型请求时仍然需要接收 CancelTurn。取消信号经过哪些对象到达 provider?
  4. 如果 MockProvider 的 script 耗尽后 panic,为什么会让恢复语义变差?
  5. 直接使用 Session 的测试很方便。你会在什么条件下把它改成 SessionHandle?

下一章:Tool、Policy 和 Executor——一次 read 怎样到达文件系统。

第 4 章:Tool、Policy 和 Executor——一次 read 怎样到达文件系统

这一章回答:模型提出了一个工具调用后,谁验证参数,谁决定权限,谁真正碰文件系统?

当前项目刻意把这三个角色拆开。读懂 read 以后,edit 和 bash 就有了共同的框架。

一次 read 的完整路径

以 demo 中的 read 为例:

ModelResponse::ToolCall
  │ name = "read", input = {"path":"README.md"}
  ▼
ToolRegistry::lookup("read")
  ▼
ToolPolicy::decide(...)
  ▼
ReadTool::execute(input, ToolContext)
  ▼
Executor::read_file(ReadFileRequest)
  ▼
LocalExecutor 的文件访问
  ▼
ReadTool 把结果包装成模型可读 JSON

四层分别回答不同问题:

层主要问题当前文件
Tool参数表示什么,结果怎样给模型src/tools/read.rs
Registry这个名字是否注册,spec 是什么src/tools/registry.rs
Policy这次调用能不能开始src/policy/mod.rs
Executor怎样实际访问文件或进程src/executor/

如果把四层合成一个函数,任何一层的职责都会变得含糊:工具可能绕过权限,policy 可能开始执行进程,executor 可能开始理解模型消息。

Tool trait 和 ToolContext

打开 src/tools/spec.rs。Tool trait 有两个核心方法:

spec() -> ToolSpec
execute(input, ToolContext) -> Result<String, String>

ToolSpec 是给模型看的描述:

  • name:模型要填的工具名;
  • description:模型要理解的用途;
  • parameters:JSON Schema;
  • risk:Read、Write 或 Execute。

ToolContext 是这次调用获得的最小能力集:

executor
cancel
workspace
tool_call_id
execution_id
output_limit

工具拿不到 SessionState、EventStore 或 SessionHandle。它只能通过 executor 做被允许的系统操作,然后返回一个模型可读字符串。执行器仍然使用类型化错误;只有在 Tool 这一层,错误才被序列化成 JSON 字符串。

ReadTool 具体做了什么

打开 src/tools/read.rs 的 execute,按顺序读:

  1. parse_input:确认输入是对象;
  2. 拒绝未知字段;
  3. 确认 path 是非空字符串;
  4. 检查 start_line 和 end_line 是从 1 开始的整数;
  5. 通过取消令牌调用 executor;
  6. 把字节结果切成行窗口;
  7. 限制最多 200 行;
  8. 返回文本和截断信息。

这个顺序说明了两种不同的保护:

  • 参数保护:防止模型传入无法解释的 JSON;
  • 资源保护:防止一个合法文件把模型上下文撑爆。

LocalExecutor 还会处理目录、不存在、权限、二进制和 workspace 外路径等系统错误。ReadTool 不需要知道这些错误如何从操作系统产生,只负责把它们转换成模型能理解的结构化结果。

Policy 是执行前的门

打开 src/policy/mod.rs。DefaultPolicy 的决定依赖 ToolSpec 的风险等级和这次 input:

Read
  workspace 内 → Allow
  workspace 外或没有 workspace → Deny

Write
  workspace 内 → Ask
  workspace 外 → Deny

Execute
  被识别为只读命令 → Allow
  其他命令 → Ask

Allow、Ask、Deny 都只是决定,不是执行结果:

  • Allow:runtime 追加 tool.started,然后调用工具;
  • Ask:runtime 追加 tool.approval.requested,等待用户;
  • Deny:runtime 追加 tool.policy_denied,不启动工具。

当前 DefaultPolicy 会识别一部分只读 shell 命令,例如 ls、cat、grep 和 pwd;遇到重定向、命令替换、串联等可能产生副作用的写法,会要求审批。

Policy 应该 fail closed:缺少 workspace、缺少 path 或无法判断风险时,不能因为“看起来可能没事”就允许。

workspace 边界要看两次

路径安全不是简单地把 root 和 path 拼起来。当前实现至少要考虑:

notes.txt                 workspace 内
../outside.txt            词法逃逸
/absolute/path            绝对路径
symlink → /etc/passwd     解析后逃逸

LocalExecutor 会做词法和规范化检查;更底层的安全文件操作还在 executor/filesystem_secure.rs 中针对不同操作系统处理。Linux 上可以使用 openat2 等能力缩小检查与打开之间的窗口,其他平台有不同的保护程度。

读实现时不要把“拒绝明显的 ../”误读成“完全解决 TOCTOU”。安全边界通常是多层防线,文档和代码要明确每层解决什么。

Registry 解决模型可见性

src/tools/registry.rs 的 ToolRegistry 使用 BTreeMap 保存工具:

  • 空名称拒绝;
  • 重复名称拒绝;
  • 序列化后的 spec 超过 16 KiB 拒绝;
  • specs 返回稳定顺序;
  • lookup 未知名称返回结构化错误。

稳定顺序让相同的工具集合生成相同的 ModelRequest,也让测试和诊断更容易比较。

用 demo 和测试观察这条链

运行:

cargo run -- demo read README.md --json
cargo test --test executor_read
cargo test --test read_tool
cargo test --test policy

读 JSON 时注意:

  • ToolRequested 保存完整调用输入;
  • ToolStarted 才表示真的进入执行;
  • ToolCompleted 才表示 executor 返回了结果;
  • Policy 拒绝不会出现 ToolStarted。

你可以把 path 改成 ../outside,或请求一个不存在文件,比较“策略拒绝”和“执行器报 NotFound”的差异。两者发生的时间和责任人不同。

思考题

  1. 为什么 ReadTool 不直接接收 LocalExecutor,而是接收 Executor trait?
  2. workspace 外的 read 为什么直接 Deny,而不是 Ask?
  3. 一个 path 在词法上位于 workspace 内,但通过 symlink 指向外部,哪一层应该拒绝?
  4. Tool 返回字符串错误,为什么 Executor 仍然保留类型化错误?
  5. ToolRegistry 的 spec 大小上限保护的是哪一个资源?
  6. 如果你要加入一个列出环境变量的工具,它的 RiskClass 应该是什么,DefaultPolicy 是否足够?

下一章:AgentLoop——一轮 turn 怎样反复采样。

第 5 章:AgentLoop——一轮 turn 怎样反复采样

前几章分别讲了事件、provider 和工具。这一章把它们放在同一个控制循环里。

读完以后,你应该能从 src/runtime/agent_loop.rs 解释:用户输入怎样变成第一次模型请求,工具结果怎样进入下一次请求,一轮 turn 在什么情况下完成或失败。

先找真正的入口

当前 AgentLoop 的主要入口分布在两个文件:

  • src/runtime/agent_loop_setup.rs:构造新 loop、从日志恢复 loop;
  • src/runtime/agent_loop.rs:append、开始 turn、继续 turn、取消和限制。

先看方法之间的关系:

run_turn(input)
  └─ run_turn_with_cancel(input, token)
       └─ run_turn_with_reason(...)
            ├─ begin_turn(...)
            └─ continue_turn(...)
                 └─ continue_turn_with_reason(...)

begin_turn 负责把用户输入和 turn.started 变成事实。continue_turn_with_reason 才是反复请求 provider、处理工具调用和判断终态的循环。

主循环的每一轮

把实际代码压缩成伪代码:

while turn 还没有终态:
    检查 cancel、step、turn time、tool time
    从 SessionState 构造 ContextSnapshot
    转成 ModelRequest
    调 provider,得到 ModelCompletion

    如果 continuation 改变:
        append provider.continuation.updated

    如果响应是 Text:
        append model.response.recorded
        append turn.completed
        返回最终文本

    如果响应是 ToolCall 或 ToolCalls:
        检查是否为空、是否重复、是否超过 batch 上限
        append model.response.recorded
        对每个 call:
            append tool.requested
            通过 policy
            Allow → append tool.started → 执行 → append tool.completed/failed
            Ask → append tool.approval.requested,暂停
            Deny → append tool.policy_denied,结束或继续
        回到下一轮采样

这段循环没有直接修改 history。所有改变都经过 append,再由 reducer 更新 state。

ModelResponse 为什么也会记录工具调用

一个模型响应可以是文本,也可以是工具调用。当前实现把工具调用转换成一个可观察的 model.response.recorded,内容类似:

tool call: read
tool calls: read, bash

它不是工具结果,也不替代 tool.requested。它表示“模型这次说了什么”;tool.requested 表示“runtime 接受了哪个调用并开始处理状态机”。

工具调用执行后,ToolCompleted 才会把 ToolResult 加入 history,供下一次 ModelRequest 使用。

ContextSnapshot 是模型看到的窗口

打开 src/runtime/context.rs。ContextSnapshot 是拥有所有权的、不可变的模型输入:

SessionState
  ├─ history
  ├─ provider_continuation
  └─ tools
       │
       ▼
ContextSnapshot
  ├─ 有限 history
  ├─ 有限的每项文本
  ├─ tools
  └─ continuation
       │
       ▼
ModelRequest

它有两个重要限制:

  • 单条 history item 默认最多 16 KiB;
  • provider 看到的 history 总量默认最多 512 KiB。

截断只发生在 ContextSnapshot,不会删除 durable history。日志保留完整事实,模型请求只携带当前预算允许的部分。

如果有 provider continuation,history_start 会根据 history_cursor 选择需要发送的历史窗口。续传 provider 和完整回放 provider 都通过同一个 ModelRequest 接口工作。

append 是主循环的安全边界

AgentLoop::append 的顺序必须牢记:

1. expected_seq = state.last_seq + 1
2. 确认 store 没被其他进程追加
3. 检查事件序列化后的大小
4. 在 next_state 副本上调用 reduce
5. store.append(event)
6. 检查 store 返回 seq
7. 提交 self.state = next_state

如果先修改 self.state,再写日志,进程在中间崩溃,内存曾经看到过一个事实,日志却没有它。恢复时就会出现两个世界。

如果 provider 响应产生空工具批次、重复 call_id、超过 max_batch_tool_calls 或超过 step 上限,runtime 会先记录 turn.failed,再返回错误。错误路径也必须是事件路径。

取消、超时和审批

取消和超时有不同的事件:

用户取消
  └─ turn.cancel_requested
  └─ turn.cancelled

时间预算耗尽
  └─ turn.timed_out

工具的取消还要等 executor 收尾。审批则是另一种暂停:

tool.requested
  → tool.approval.requested
  → turn 保持 active
  → 用户批准
  → tool.approval.responded
  → tool.started
  → 工具完成
  → 回到采样

审批不是 provider 错误。它是一个已经持久化的控制状态,所以 UI 或协议客户端重启后仍然可以看到“正在等待审批”。

建议的阅读实验

运行:

cargo test --test integration_agent_loop
cargo test agent_loop_passes_system_instructions_through_snapshot
cargo test --test agent_loop_limits

在 integration_agent_loop.rs 中找一个脚本为 ToolCall、Text 的测试,画出两次 ModelRequest:

request 1: user history + tool specs
request 2: user history + tool result + tool specs

再找一个 max_steps 或空批测试,看它在事件日志里记录哪个终态。

思考题

  1. 为什么工具结果必须进入下一次 ModelRequest,而不能只存在 ToolCompleted 事件里?
  2. ContextSnapshot 截断 history 后,为什么 durable log 仍然要保留完整文本?
  3. 如果模型一次返回 100 个工具调用,最早应该在哪一层限制?
  4. append 的副本 reduce 能防止哪些问题,不能防止哪些外部副作用?
  5. 为什么 turn.cancel_requested 和 turn.cancelled 要分成两个事实?
  6. 审批暂停时,Session actor 为什么可以处理新输入;工具执行期间又为什么会延迟处理?

下一章:进程、取消和原子编辑。

第 6 章:进程、取消和原子编辑

前一章说明 AgentLoop 如何启动工具。这一章进入最容易出真实事故的地方:操作系统。

bash 会启动进程,进程会产生输出,也可能再启动子进程。edit 会改用户文件,可能和另一个进程同时修改同一个路径。当前项目把这些副作用集中在 executor 层,并用 cancellation、timeout、输出上限和 hash guard 保护它们。

从 BashTool 追到 process executor

按这个顺序读源码:

src/tools/bash.rs
  └─ 解析 command、timeout_ms、输出预算
      ▼
src/executor/trait.rs
  └─ ProcessRequest
      ▼
src/executor/local.rs
  └─ 委托给 run_process
      ▼
src/executor/process.rs
  └─ spawn、读管道、取消、回收和汇总结果

BashTool 面向模型,负责输入格式和 JSON 结果。ProcessRequest 面向 executor,负责时间和字节预算。process.rs 才直接处理 Child、stdout、stderr 和进程组。

为什么 stdout 和 stderr 必须并发读取

子进程的 stdout 和 stderr 都是有容量的管道。如果父进程只读 stdout,子进程持续写满 stderr,就会卡在写 stderr 上,父进程等待它退出也会一直等。

当前实现为两条流分别启动排空任务:

child.stdout ──▶ stdout reader ──▶ 保留上限内的文本
child.stderr ──▶ stderr reader ──▶ 保留上限内的文本
                         │
                         └─ 超过上限仍继续读取,只是不再保存

“停止保留”和“停止读取”不是一回事。停止读取会让子进程被管道反压,最终造成死锁。

三层输出上限

ProcessRequest 包含:

  • max_stdout_bytes;
  • max_stderr_bytes;
  • max_combined_bytes。

单独的 stdout 和 stderr 上限防止某条流占满内存;combined 上限防止两条流各自没有超限、合计却绕过限制。

ProcessOutput 会告诉模型:

text
truncated
original_bytes
retained_bytes

这样模型知道收到的是完整结果,还是被截断的结果。UTF-8 截断必须退回到字符边界,不能直接在任意字节位置构造 String。

进程组和子孙进程

只杀掉 shell 的父进程不够。命令可能启动 sleep、编译器或后台子进程。Unix 平台上当前实现把命令放进独立进程组;取消或超时时按进程组清理。

ProcessGroupGuard 的思路是:

启动后 armed
  └─ 任何提前返回都尝试杀进程组
正常 wait 并完成收尾
  └─ disarm

Drop 是最后一道保险。测试里常见的 sleep 与后台子进程场景,就是为了验证“取消后没有孤儿进程”。

取消、超时和结果未知

AgentLoop 给每个 turn 一个 CancellationToken,工具可以使用它,进程执行器再把取消翻译成杀进程组。

三个时间概念要区分:

  • turn wall clock:整个 turn 的墙钟预算;
  • cumulative tool time:所有工具累计执行时间;
  • process timeout:单个 bash 命令的时间预算。

用户取消记录 turn.cancel_requested 和 turn.cancelled。时间预算耗尽记录 turn.timed_out。

如果工具开始执行后,进程被杀或清理超时,runtime 可能无法知道外部副作用是否完成。这时记录 tool.outcome_unknown。它和 tool.failed 的差异是:

Failed
  → 可以确定工具没有完成预期操作

OutcomeUnknown
  → 本地日志无法证明外部操作是否发生

第 7 章会把这个状态交给恢复系统处理。

edit 为什么要 hash guard

打开 src/executor/filesystem.rs 和 src/tools/edit.rs。一次编辑大致是:

解析 workspace 路径
  → 获取 advisory lock
  → 读取当前文件
  → 计算 old_hash
  → 校验 expected_hash(如果提供)
  → 要求 old_text 恰好匹配一次
  → 写同目录临时文件
  → flush / fsync
  → rename 原子替换
  → 返回 old_hash、new_hash、replacements

hash guard 防止模型基于旧内容做编辑,把用户刚才的修改覆盖掉。精确匹配防止“替换错位置”或“同时替换多个位置”。

临时文件和 rename 解决的是崩溃完整性:进程在写入期间崩溃,原文件仍然存在;只有完整的新文件准备好后才替换。

取消检查放在编辑事务边界上。rename 事务内部不能被随意劈开,否则就可能留下半个写入。

运行哪些测试

还可以观察一个离线的 edit → bash 闭环:

cargo run -- demo edit-bash README.md

demo 使用 AllowAllPolicy 只是为了演示完整链路;真实会话默认仍由 DefaultPolicy 决定是否需要审批。

cargo test --test process_executor
cargo test --test bash_tool
cargo test --test edit_tool
cargo test --test session_cancel
cargo test cross_process_cancel

先读大输出测试,再读取消测试,最后读 edit 的 hash conflict 测试。每个测试都问“它在防止哪个现实中的事故”。

思考题

  1. 为什么达到 stdout 上限后仍要继续读取管道?
  2. kill 父进程后,为什么子进程可能继续存在?进程组解决了哪一层关系?
  3. 非零 exit code 为什么通常是模型可以处理的结果,而无法回收进程是 executor 错误?
  4. 取消一个 edit 时,为什么要把取消检查放在 rename 前,而不是每写一行都检查?
  5. read 的结果未知通常可以重试,bash 的结果未知为什么默认要人工决定?
  6. 如果两个 harness 实例同时编辑一个文件,advisory lock 和 hash guard 各自解决什么问题?
  7. 输出上限、历史上限和事件大小上限分别保护哪个边界?

下一章:崩溃恢复——系统怎样面对“不知道”。

第 7 章:崩溃恢复——系统怎样面对“不知道”

前几章已经有 durable event log,也能取消进程。现在考虑一个无法回避的时刻:

tool.started
进程崩溃
没有 tool.completed

本地日志只能证明工具开始了,不能证明外部世界最后发生了什么。当前项目没有假装自己拥有 exactly-once,而是把这种窗口明确表示为 OutcomeUnknown,并交给恢复流程分类。

恢复的三个动作

打开 src/durable/recovery.rs。恢复流程只做三件事:

  1. 读取并重放已有事件;
  2. 生成 RecoveryFinding;
  3. 在显式 recover 命令中追加恢复事实和 action required。

它不会执行 read、edit、bash,也不会自动重新发送 provider 请求。

这条边界很重要。恢复代码运行时,外部世界可能已经改变;它只能解释日志,不能凭空确认副作用是否发生。

RecoveryFinding 的含义

当前实现可能报告:

Finding日志说明
ActiveTurnturn 没有到达终态
PendingModelResponse模型请求可能在进程停止时仍未返回
PendingApproval工具等待用户审批
PendingTool工具请求已记录,但还没有开始
UnknownTool工具可能已经产生副作用,但结果没有 durable

PendingTool 和 UnknownTool 不同:

tool.requested
  └─ PendingTool:可能尚未启动

tool.requested → tool.started
  └─ UnknownTool:已经进入执行窗口

恢复系统会为工具选择保守策略:

  • read → RetryRead;
  • edit → InspectEditHash;
  • 其他工具,例如 bash → RequireUserDecision。

RecoveryPolicy 描述下一步该怎样处理,不代表系统已经替你处理了。

inspect 和 recover 的区别

CLI 的 inspect 只读:

读日志 → replay → classify_state → 打印 RecoveryReport

recover 会追加事实:

recovery.started
tool.outcome_unknown(如果有已经开始的工具)
recovery.action_required
recovery.completed

recover 本身要幂等。重复运行时,不能每次都追加一套新的 recovery 事件。当前代码会检查已有 recovery batch 和 completed 事实。

abandon-turn 是人的显式决定。它追加 turn.failed,并让会话可以继续接受新的输入。恢复系统负责发现问题,人负责决定是否放弃。

先手工想象三种日志尾部

A:
tool.requested
<EOF>
→ PendingTool

B:
tool.approval.requested
<EOF>
→ PendingApproval

C:
tool.started
<EOF>
→ UnknownTool

读 src/durable/recovery.rs 的 classify_state,观察它是如何从 TurnState.executions、approvals 和 tool_names 推导这些 finding 的。分类本身是纯函数,不读文件,也不调用 executor。

checkpoint 是缓存,不是事实

打开 src/durable/checkpoint.rs。Checkpoint 包含:

  • schema_version;
  • session_id;
  • last_seq;
  • reducer state;
  • state_digest。

它的作用是跳过很长日志的前缀。恢复时仍然要验证:

checkpoint 的 session_id 正确
checkpoint 的 last_seq 存在于日志前缀
checkpoint marker 与快照相符
state_digest 能重新计算出来
后续事件可以继续 reduce

任何校验失败,replay_with_checkpoint_fallback 都应该从 event log 全量重放。删除或损坏 checkpoint 不应改变最终状态,只会变慢。

创建 checkpoint 时,marker 由 session actor 追加,快照文件通过临时文件、flush、sync 和 rename 原子替换。这样事件序列不会被旁路 writer 插入,也不会留下一个已经领先日志的快照。

restore 如何重建 AgentLoop

src/runtime/agent_loop_setup.rs 中有两条路径:

  • restore:从头读取事件并 reduce;
  • restore_with_checkpoint:优先使用 checkpoint,校验失败时回退全量 replay。

两条路径最后都必须确认 state.last_seq 与 store.last_seq 一致。恢复成功后的 AgentLoop 拥有新的内存状态,但事实仍然来自原来的日志。

注意预算的语义:重启后的 turn 会获得新的运行时预算,原来的 turn_steps 和 tool_time_used 不直接从进程内计时器恢复。durable 事实恢复了状态,实时计时器需要重新开始。

读测试

cargo test --test recovery_classify
cargo test --test recovery_cli
cargo test --test checkpoint
cargo test repair_partial_tail

重点关注:

  • 五种 finding 是如何构造的;
  • recover 第二次运行为什么不重复追加;
  • 损坏 checkpoint 为什么回退;
  • 半行修复为什么只允许操作最后一行;
  • inspect 输出为什么要脱敏工具输入。

思考题

  1. 为什么恢复流程不能自动重试 read,即使 read 通常没有副作用?
  2. tool.started 后没有结果时,为什么不能直接记录 tool.failed?
  3. checkpoint 损坏时全量 replay 能恢复什么,不能恢复什么?
  4. recovery.completed 为什么需要成为事实,而不能只在 CLI 返回成功?
  5. 如果工具是“发送邮件”,policy_for_tool 应该返回什么?
  6. abandon-turn 之后,为什么新的 user.input.recorded 可以把会话从 Failed 拉回 Idle?
  7. 如果 checkpoint 写入失败但 marker 已追加,下一次创建 checkpoint 应该怎样处理?

下一章:真实 provider——Responses 与 Chat Completions。

第 8 章:真实 provider——Responses 与 Chat Completions

前面一直用 MockProvider,是为了先把 runtime 语义固定下来。这一章看真实 HTTP provider 怎样适配同一套 ModelProvider 接口。

当前项目的 provider 代码同时支持:

  • OpenAI Responses wire format;
  • DeepSeek、Kimi、Qwen、vLLM、Ollama 等兼容的 Chat Completions wire format。

教程先讲共同的数据流,再看两个协议的差异。

先看三层代码

src/model/provider.rs
  ModelRequest / ModelResponse / ModelCompletion

src/model/openai_protocol.rs
  纯函数:runtime 类型 ↔ JSON body / JSON response / SSE

src/model/openai.rs
  配置、HTTP 请求、超时、取消、重试、attempt 观察

runtime 只依赖 ModelProvider。它不知道 endpoint 的 JSON 字段,也不知道 function_call_output 放在 input 还是 message 里。

这就是 provider 可替换的实际含义:只要返回相同的 ModelResponse 和 ModelCompletion,AgentLoop 就能继续执行。

两种 wire format 的共同闭环

工具调用会形成两次模型请求:

请求 1:用户历史 + tools
响应 1:工具调用

runtime 执行工具
  └─ 产生 ToolResult

请求 2:原来的对话 + 工具结果 + continuation
响应 2:最终文本或下一批工具调用

Responses 可能使用 previous_response_id 和 function_call_output;Chat Completions 可能把 assistant tool_calls 和 tool message 放在 messages 中。字段不同,但 runtime 要的行为相同。

ProviderContinuation 是翻译桥

打开 src/runtime/state.rs。ProviderContinuation 中的字段大致包括:

provider
response_id
model
endpoint
native_call_ids: runtime ToolCallId → provider call id
history_cursor
reasoning_content(兼容思考模型)

runtime 的 ToolCallId 属于自己的命名空间。provider 的 call_id 属于 provider。native_call_ids 负责把两边映射起来。

continuation 会作为 provider.continuation.updated 事件持久化。重启后,provider 还能知道当前响应链走到哪里;如果 model 或 endpoint 变化,provider 会回放规范化历史,而不引用旧 response_id。

history_cursor 表示续传需要的历史位置。它让 provider 能发送增量上下文,也让实现明确知道“已经交给 provider 的历史从哪里结束”。

读请求构造函数

打开 src/model/openai_protocol.rs,先看纯函数而不是 HTTP:

  • build_request_body:Responses body;
  • build_cc_request_body:Chat Completions body;
  • parse_json_response 和 parse_cc_json_response:解析文本与工具调用;
  • parse_stream_response 和 parse_cc_stream_response:聚合 SSE 增量。

纯函数的优点是:你可以用固定 JSON fixture 检查协议转换,不需要网络,也不需要 API key。

解析器需要逐字段校验:

响应 id 是否存在
output 或 choices 是否是预期数组
文本与工具调用是否能互相区分
call_id、name、arguments 是否完整
usage 是否能安全解析

schema 不合法是 provider 实现或服务响应问题,不应该靠无限重试掩盖。

配置和安全边界

打开 src/model/openai.rs 的 OpenAiProviderConfig 和 WireStyle。配置阶段会检查:

  • model 不为空;
  • max_retries 在合理范围;
  • endpoint 只允许可信 URL;
  • 公共地址使用 HTTPS;
  • API key 不进入 Debug、事件或协议;
  • 响应体和单次请求有大小、时间限制。

API key 只在 provider 内部使用。日志里可以记录 request id、response id、attempt 号和 usage,但不能记录密钥或完整错误 body。

重试怎样和事件结合

provider 可能遇到网络抖动、408、429 或 5xx。当前实现会区分可重试和不可重试:

网络抖动 / 408 / 429 / 5xx
  → 有限次数重试,必要时读取 Retry-After

400 / 401 / 响应 schema 错
  → 记录失败并返回

每次尝试都可以通过 ProviderObserver 记录 ProviderAttempt。Session actor 只有在 attempt 事件追加成功后才确认给 provider,保证“日志里看到的尝试”与 runtime 观察一致。

取消从哪里进入

ModelProvider::complete 接收 CancellationToken。OpenAiProvider 在 HTTP 请求等待期间 select 取消信号;取消后立即返回 provider 错误或取消错误,AgentLoop 再根据 turn 的原因追加终态事件。

这条路径和 MockProvider 的 Delay 脚本共享同一行为契约。先在 mock 中验证取消,再看真实 HTTP client 如何实现。

离线测试怎么读

cargo test --test openai_provider
cargo test --test provider_contract

这些测试用 tokio TcpListener 启动本地 mock server。读测试时先找 server 收到的 request body,再找 provider 解析的 ModelResponse,最后看 AgentLoop 是否按同一语义继续。

契约测试的价值在于:MockProvider 和 OpenAiProvider 不是靠“接口看起来一样”证明可替换,而是要通过相同的文本、工具调用、错误、取消和续传场景。

思考题

  1. 为什么 runtime 不直接保存 provider 的 native call_id?
  2. 如果换 model 后旧 response_id 失效,provider 应该怎样构造下一次请求?
  3. 429 的 Retry-After 为什么比固定 sleep 更可靠?
  4. 响应 JSON 不合法时为什么不建议直接重试?
  5. API key 只出现在 provider 内部,为什么仍然要测试 Debug 输出和事件日志?
  6. “请求已发出但进程在收到响应前崩溃”属于 provider 失败、结果未知,还是另一种事实?你会把它放在哪一层处理?

下一章:CLI 和 JSONL 协议——把 runtime 放到进程边界外。

第 9 章:CLI 和 JSONL 协议——把 runtime 放到进程边界外

这一章解释:为什么 TUI、TypeScript 客户端和其他程序不能直接共享 AgentLoop,而要通过 stdio JSONL 和 session actor 通信。

进程边界会强迫系统明确三个问题:

  • stdout 上什么是协议,什么是诊断;
  • 请求和异步事件如何同时发送;
  • UI 断开时,runtime 的会话是否继续。

CLI 负责组装,库负责语义

打开 src/main.rs。main 的主要工作是:

解析 clap 参数
  → 加载 TOML 配置
  → 初始化 stderr tracing
  → 选择 provider、executor、tools、policy、store
  → 调用库中的 Session、recovery 或 protocol

main.rs 不应该包含 reducer 规则、工具执行细节或恢复分类。这些属于库模块,所以测试可以直接调用库,也可以启动真正的二进制验证进程边界。

CLI 命令可以按用途分成三类:

类别命令
运行会话run、resume、cancel
协议和 UIserve、events、tui
恢复和诊断inspect、recover、abandon-turn、sessions、doctor

JSONL transport 的两个核心承诺

打开 src/protocol/jsonl_transport.rs。它处理的是字节流,不是“每次 read_line 就完事”。

write_json_line 要保证:

  • 序列化成一行;
  • 不超过单行上限;
  • write_all 完整写入;
  • flush;
  • 不能把诊断日志写到 stdout。

read_bounded_line 要保证:

  • 逐块寻找换行;
  • 超过上限时标记 TooLarge;
  • 继续读取直到整行结束;
  • 下一条消息不会从上一条超长消息的半截开始。

因此坏 JSON、超长输入或缺少换行不会污染后续请求。

请求响应和事件通知

打开 src/protocol/jsonl.rs。协议服务器有两个方向:

stdin
  → 请求循环
      → session.create / turn.start / turn.wait / ...
      → 一个 request id 对应一个 response

event store
  → 事件泵
      → event notification
      → 带 seq,客户端可以去重和检测缺失

请求响应回答“我发的命令是否被接受或完成”。事件通知回答“会话后来发生了什么”。turn 运行时间可能很长,不能让请求循环只靠一个阻塞响应传递全部进度。

典型协议路径

session.create
  → 返回 session_id

turn.start
  → 返回 turn_id 和 queued 状态

event notification
  → tool.started / approval.requested / turn.completed ...

turn.wait
  → 完成时返回最终文本
  → timeout 时返回 turn_pending
  → 失败时返回稳定错误码

Approval.respond 只有在决策真正追加到事件日志后才应该报告 persisted。客户端拿到成功响应,就可以相信这个决定已经成为事实。

安全事件投影

durable Event 中的 ToolRequested 可能包含完整 command、old_text 或工具输入。协议通知不能直接把完整 payload 广播出去。

打开 src/protocol/event_projection.rs。v2 projection 保留白名单字段,例如:

type
event_id
timestamp
schema_version
tool_call_id
execution_id
tool
approved
reason
input_summary

input_summary 是给审批界面看的短摘要:

  • bash 显示 command 的有限前缀;
  • read 和 edit 显示 path 或 text edit;
  • 其他输入显示 opaque input;
  • 完整输入仍留在 event log。

这是一个实际的信任边界:客户端能显示“正在请求什么”,但不自动获得所有工具原始内容。

跨进程 cancel 的故事

cancel 可以由另一个进程打开同一个 event log 并追加 turn.cancel_requested 和 turn.cancelled。正在运行的进程下一次 append 时发现 store.last_seq 已经变化,就会以 out-of-sync 停止,避免覆盖另一个 writer 的事实。

这会留下一个现实窗口:

工具可能已经产生副作用
当前进程却无法把结果追加进同一日志

恢复命令负责分类这个窗口。协议层不能把它伪装成普通成功。

读协议测试

cargo test --test stdio_protocol
cargo test --test protocol_compat
cargo test --test jsonl_cross_process
cargo test --test cli

先看坏 JSON 和超长行,再看 create → start → wait,最后看跨进程 cancel。测试顺序对应协议从输入可靠性到业务语义的层次。

思考题

  1. stdout 混入一行 tracing 日志时,为什么客户端无法“跳过它继续解析”?
  2. 为什么超长行必须被完整吞掉,而不是立即返回错误?
  3. 请求 response 和事件 notification 都写 stdout,怎样保证一条 JSON 不会被另一条写到一半插入?
  4. UI 想显示完整 bash 输出,应该直接扩大安全投影,还是增加受控读取接口?
  5. UI 在 turn.start 后断开连接,runtime 应该自动 cancel 吗?你会把“连接断开”和“用户取消”记录成同一个事实吗?
  6. 跨进程 cancel 的 out-of-sync 保护避免了什么,恢复流程又要补上什么?

下一章:事件查看器和 TUI——UI 只是事件投影。

第 10 章:事件查看器和 Ink TUI——UI 只是事件投影

这一章不再讨论 runtime 怎样执行工具,而是讨论客户端怎样观察 runtime。

项目里有两个现成的客户端:

  • Rust 写的 events 事件查看器:最小、可脚本化,用来观察事件流;
  • ui/ 下的 TypeScript Ink TUI:面向真实使用,支持多轮对话和审批。

它们共享同一个 mini-harness serve --stdio 后端,走同一套 JSONL 协议。读这章时,把 UI 当成协议客户端,而不是第二个 agent。

UI 不应该拥有的东西

一个 UI 可以拥有输入框、滚动位置、折叠开关和最后一次看到的 seq。它不应该拥有:

  • provider client;
  • executor;
  • policy 决策;
  • event log 的写权限;
  • 对 unknown outcome 的猜测;
  • 一份自认为权威的 SessionState。

把 UI 进程 kill 掉后,runtime 的会话仍然应该能恢复。这个性质是判断边界是否正确的简单方法。

UI 只看到安全投影

打开 src/protocol/event_projection.rs。durable Event 里的 tool.requested 可能包含完整 command、old_text 或工具输入,协议通知不能直接把完整 payload 广播出去。

v2 projection 只保留白名单字段,例如:

type
event_id
timestamp
schema_version
tool_call_id
execution_id
tool
approved
reason
input_summary

input_summary 是给审批界面看的短摘要:bash 显示 command 的有限前缀,read/edit 显示 path,其他输入显示 opaque。完整输入仍留在 event log 里。

客户端因此能显示“正在请求什么”,却拿不到全部原始内容。这是一个信任边界,不是遗漏。

事件查看器:最小的协议客户端

打开 src/ui/event_viewer.rs。它的流程很短:

启动 serve --stdio
  → 协商协议版本
  → session.create
  → turn.start
  → turn.wait 或持续接收通知
  → 按 seq 去重
  → 打印事件摘要

事件查看器的价值在于它把协议问题和终端渲染问题分开。先运行:

cargo test --test events_viewer

然后找到它处理 notification 的地方。注意它不是从 event log 读取事实,而是消费服务器发送的安全投影。

Ink TUI 的三层结构

打开 ui/src 目录,它只有三个文件,职责分得很清楚:

main.tsx    入口:解析参数、启动 serve、session.create、挂载 React
client.ts   协议客户端:spawn 子进程、按 id 路由响应、转发通知
ChatApp.tsx 渲染:React state、输入框、审批提示、消息列表

main.tsx 每次启动都创建一个新 session,并把 event log 放到临时目录,避免“日志非空”的冲突。它还会检查 stdin 是不是 TTY:不是就报错退出,并提示改用 mini-harness run。

client.ts 怎样路由消息

打开 ui/src/client.ts。它 spawn 出 mini-harness serve --stdio,stderr 直接继承给终端,stdout 交给 readline 逐行解析。每条消息只有两种命运:

有 id、且 pending 里有它
  └─ response,resolve 对应的 Promise

method = event
  └─ notification,发给 EventEmitter

这和 Rust 事件查看器里的路由是同一件事:如果客户端只读自己的 response,就会漏掉事件;如果把 notification 当 response,等待命令的 Promise 永远不会 resolve。

request() 给每条命令分配递增的 id,把 resolve/reject 存进 Map,再写到子进程 stdin。onEvent() 返回一个取消订阅函数。整个类不持有任何会话状态——它只负责转发命令、关联响应、转发通知。

一次 turn 的交互

打开 ui/src/ChatApp.tsx。用户按下回车后的顺序是:

turn.start        → 返回 turn_id 和 queued
(后台持续接收 event notification)
turn.wait         → 完成返回最终文本
                  → timeout 返回 turn_pending
                  → 需要审批返回 approval_pending
approval.respond  → 用户按 y/n 后,把决定变成事实

关键点在审批:turn.wait 收到 approval_pending 并不代表失败。它对应一条已经收到的 tool.approval.requested 通知;UI 等用户按 y/n,再调 approval.respond,然后继续 turn.wait。

UI 自己不执行工具,也不决定权限。如果 Ink TUI 自己调用模型或 bash,协议边界就被绕开了。

UI 如何推导生命周期

屏幕上的 Running、WaitingApproval、RunningTool 和 Idle 都来自事件投影。src/runtime/state.rs 中的 run_state 会检查:

  • 是否有 pending approval;
  • 是否有 Running execution;
  • 是否有 active turn。

UI 不应该看到一次 tool.approval.requested 后永远显示审批中;它要处理后续的 tool.approval.responded、tool.started 和终态事件。

重新连接或 resume 时,客户端应以事件 seq 为版本依据补齐缺失通知,而不是相信旧的内存列表。

读测试

cargo test --test events_viewer
cargo test --test tui_line_mode
cd ui && npm run typecheck

先看事件到生命周期的投影和按 seq 去重,再看 Ink 客户端的类型检查。每个检查都在说明同一件事:UI 可以改变显示,但不能改变事实。

思考题

  1. UI 为什么不能直接读取和解析 event log?
  2. 如果通知丢了一条,seq 怎样帮助客户端发现问题?
  3. 为什么 WaitingApproval 应该由事件投影推导,而不是只看 turn.wait 的错误码?
  4. input_summary 为什么不能直接等于工具的完整输入?
  5. 想显示实时 stdout 增量,需要在协议中增加什么;安全投影边界会怎样变化?
  6. UI 重启后,哪些信息可以从事件恢复,哪些纯粹是 UI 本地状态?

下一章:Scheduler、durable 队列和全局并发。

第 11 章:Scheduler、durable 队列和全局并发

这一章解释当前项目最后一组运行时语义:

  • 一个 turn 运行时,新的用户输入怎样排队;
  • 排队输入怎样在崩溃后保留;
  • 多个 session 如何共享进程并发上限;
  • Scheduler 为什么只做组合,不再复制 runtime 状态。

先看单 session 的队列

打开 src/runtime/session_actor.rs。actor 里有三个与队列相关的东西:

queue
  └─ 已接受但尚未开始的 (TurnId, input)

deferred_waiters
  └─ 等待排队 turn 终态的回复通道

outcomes
  └─ 最近结束的 turn 结果,保留有限数量

当 active_turn 不存在时,StartTurn 直接开始;当 active_turn 存在时,actor 检查 max_queued_inputs,然后把输入 durable 地记录,再把它放入 queue。

输入被确认的时刻很重要:

超出上限
  → QueueLimitExceeded
  → 没有 user.input.recorded

未超限
  → append user.input.recorded 成功
  → 回复 queued = true
  → 等前一个 turn 结束后自动开始

因此“客户端收到 queued = true”意味着输入已经成为事件事实。它不是一个只存在内存里的愿望。

两种 steer 时序

审批暂停时,turn future 已经让出了一部分控制权,actor 可以马上持久化新输入:

turn A 等待审批
  → 输入 B 被记录
  → A 恢复采样时,history 已经看得到 B
  → A 终止
  → B 作为新的 turn 开始

模型采样或工具执行期间,AgentLoop future 暂时持有可变借用。actor 会先收下 StartTurn,等 future 结束后再 append:

turn A 正在执行
  → 收到输入 B
  → 暂存 reply 和 input
  → A 终态,future 释放
  → append B
  → 回复 queued = true
  → B 开始

这两个场景都叫排队,但 B 对 A 的可见时间不同。tests/actor_queue_edges.rs 把这个差异固定成了测试。

FIFO 和 WaitTurn

queue 是 FIFO。前一个 turn 结束后,drain_queued_turns 会:

  1. 取队首;
  2. begin_queued_turn;
  3. 运行完整 turn;
  4. 把结果写入 outcomes;
  5. 唤醒对应的 deferred_waiters;
  6. 继续处理下一条。

WaitTurn 如果收到一个还没开始的 turn_id,会把 reply 放入 deferred_waiters。它不会返回“unknown turn”,也不会忙等。

outcomes 只保留最近的一小段结果,防止内存无限增长。旧结果仍可以从 event log 和恢复工具中获得。

队列取消为什么没有默认支持

排队输入还没有开始,没有一个正在执行的副作用可取消。要取消它,需要记录一个“丢弃了哪条输入、为什么丢弃”的新事实,并让 reducer、恢复和协议都理解它。

当前项目选择的语义更简单:排队输入不单独取消;要么等它开始后取消,要么通过 abandon-turn 处理整个未完成工作。清晰的不支持比半成品的取消更容易恢复。

Scheduler 的责任边界

打开 src/scheduler/mod.rs 和 src/scheduler/task.rs。Scheduler 组合多 session:

Scheduler
  ├─ register_session
  ├─ submit
  ├─ wait
  ├─ cancel
  ├─ respond_approval
  ├─ run_state
  └─ shutdown

它不拥有 history、active_turn 或 event seq。真正的会话状态在每个 actor;Scheduler 只是把任务 ID 和对应的 SessionHandle 连接起来。

SchedulerTask 用 session id 和 turn id 标识一个工作项。它不是第二份状态机。

全局进程并发放在 executor

如果并发上限放在某个 turn 里,两个 session 各自允许 1 个进程时,全局仍然可能同时跑很多进程。

当前 LocalExecutor 可以共享 Semaphore:

Session A ─┐
Session B ─┼─▶ shared LocalExecutor ─▶ max_concurrent_processes
Session C ─┘

run_process 先获取 OwnedSemaphorePermit,再启动进程;执行结束或出错时 permit 通过 RAII 释放。等待槽位本身也有预算,超时返回 ProcessError::ConcurrencyLimit,而不是无限排队。

这层限制属于 executor,因为它保护的是操作系统进程资源,而不是某个会话的策略决定。

生命周期投影

src/runtime/state.rs 的 run_state 会把 reducer state 投影成:

Idle
RunningTurn
WaitingApproval
RunningTool

这个状态适合 UI 和 scheduler 查询。它是派生值,不需要单独写一条 lifecycle event。

审批状态优先于 RunningTool,因为有些批量工具调用会让一个执行在运行、另一个调用等待审批。显示“等待审批”能让客户端知道下一步需要谁做决定。

读测试

cargo test --test scheduler
cargo test --test actor_queue_edges
cargo test --test agent_loop_limits

先读队列满的测试,再读 FIFO 和 steer 测试,最后读 shared executor 的并发测试。这样可以看出:

  • 上限检查发生在 append 前;
  • ack 发生在 durable 事实之后;
  • 共享 executor 才能限制跨 session 的真实进程;
  • Scheduler 不需要自己维护一套状态。

思考题

  1. 为什么 queued = true 必须晚于 user.input.recorded 的持久化?
  2. 审批暂停时输入可以 steer 当前 turn,工具执行时输入却延迟到下一个 turn,这个差异来自什么借用和状态约束?
  3. 如果 Scheduler 自己保存一份 history,会产生什么不同步场景?
  4. 为什么并发上限放在 policy 会让“等待资源”和“禁止执行”混在一起?
  5. 排队输入如果需要优先级,你需要追加哪些事实才能在恢复时重建顺序?
  6. 一个 session 关闭时,queue 中的输入和 deferred_waiters 应该分别得到什么结果?
  7. 为什么 semaphore permit 必须使用 RAII,而不能手动记得 release?

下一章:尾声:把这份 Harness 读成一个系统。

尾声:把这份 Harness 读成一个系统

你现在已经沿着一条完整路径读过项目:

用户输入
  → Session / actor
  → AgentLoop
  → Provider
  → ModelResponse
  → Policy
  → Tool
  → Executor
  → Event log
  → reducer
  → 下一次 ModelRequest
  → 最终回答

外围还有两条重要路径:

崩溃
  → replay
  → RecoveryFinding
  → 人的决定
  → 恢复事实

UI / CLI
  → JSONL 协议
  → SessionCommand
  → 安全事件投影

这两条路径让项目从“可以调用模型”变成“可以长期运行、可以观察、可以恢复的 runtime”。

用四个问题检查自己是否读懂

问题一:谁拥有写权限

会话状态和事件追加只有 AgentLoop 所在的 actor 能修改。Provider、Tool、UI 和 Scheduler 都通过明确接口请求它们。

问题二:什么是事实

用户输入、模型响应、工具请求、工具开始和完成、审批、取消、恢复和 checkpoint marker 都是事件。SessionState、run_state、UI 显示内容和 queue 的当前视图都是从事实推导出来的。

问题三:哪里可能不知道

工具或 provider 的外部副作用可能已经发生,但结果还没有进入日志。OutcomeUnknown 和 RecoveryFinding 让这个窗口显式存在,系统不会用“失败”假装知道结果。

问题四:哪个模块可以替换

Provider 可以换成新的 wire format;Executor 可以换成 sandbox 或远程实现;UI 可以换成另一个客户端。只要它们保持当前 trait 和事件语义,AgentLoop 不需要重新理解这些外部差异。

回到源码做一次总复盘

建议重新打开这几个入口:

  1. src/main.rs 的 run_demo:组件怎样被接线;
  2. src/runtime/agent_loop.rs 的 append:一条事实怎样进入日志;
  3. src/durable/reducer.rs 的 reduce:日志怎样变成状态;
  4. src/runtime/session_actor.rs 的 run_actor:谁拥有唯一写权限;
  5. src/protocol/event_projection.rs 的 project_event:哪些事实能安全地给客户端;
  6. src/durable/recovery.rs 的 classify_state:崩溃后的状态如何分类。

再运行一次:

cargo run -- demo read README.md --json
cargo test --test integration_agent_loop
cargo test --test recovery_classify
cargo test --test scheduler

这一次不要只看测试通过。把 demo 的每条事件放在下面这张表里:

事件它记录的事实reducer 改变的状态下一步谁消费
user.input.recorded用户说了什么history、pending_inputsAgentLoop
tool.requested模型要求哪个工具Pending executionPolicy / Tool
tool.started工具真的开始Running executionExecutor
tool.completed工具返回了什么Completed、historyProvider
turn.completed最终回答是什么active_turn 清空Session / UI

如果某个事件无法回答“谁产生、谁消费、状态怎样变化”,就回到对应章节继续读。

接下来读什么

当前代码已经为这些方向留下了边界:

  • sandbox:把 workspace 保护从尽力而为提升到操作系统能力;
  • PTY:支持交互式进程、终端尺寸和实时输出;
  • MCP:让工具从外部服务动态注册;
  • 远程 executor:把 Executor trait 换成网络实现;
  • 多 agent:让多个 Session 通过协议协作;
  • property tests:随机生成合法事件序列,验证 reducer 重放;
  • metrics:统计 turn latency、provider error、approval wait 和 unknown outcome。

选择下一步时,继续使用本教程的阅读方法:先找事实和边界,再找失败路径,最后让测试固定语义。

最后的思考题

  1. 新 provider 增加一种工具调用协议时,哪些文件应该变化,哪些文件应该保持不动?
  2. 如果把 event log 换成数据库,哪些 reducer 和恢复语义仍然必须保留?
  3. 如果 UI 要显示实时 stdout,哪一条安全边界会被重新设计?
  4. 如果允许并行工具调用,事件顺序、取消和并发上限需要新增什么事实?
  5. 哪一个模块最容易变成“第二个 runtime”?你会用什么接口边界阻止它?
  6. 你能否从一次 tool.outcome_unknown 事件,说明系统知道什么、不知道什么、下一步由谁决定?

到这里,教程的目标就完成了:你可以从用户输入追到外部副作用,再从事件日志反向追到恢复状态,也能判断一个新功能应该放在哪一层。

术语表

按主题整理。每条给出最短定义和对应的源码位置;读教程遇到不熟的词,先回这里查。

运行时结构

术语含义相关位置
Harness模型循环之外的全部系统:授权、执行、持久化、恢复、协议与 UI第 0 章
Session可恢复的长期会话,包含历史、配置和多个 turnsrc/runtime/session.rs
Turn一次用户输入到最终回答、失败、取消或暂停src/runtime/state.rs
Step一次模型请求及其结果处理,一个 turn 可以包含多个 stepsrc/runtime/agent_loop.rs
ToolExecution一个具体工具调用实例,有独立 ID、状态和执行策略src/runtime/state.rs
ContextSnapshot拥有所有权、不可变的模型输入窗口,负责预算截断src/runtime/context.rs
事实(fact)已经发生的事情,只追加、不修改,进入 event logsrc/durable/event.rs
派生状态(derived state)reducer 从事实计算出来的当前视图src/durable/reducer.rs

模型与 Provider

术语含义相关位置
Provider把模型服务差异翻译成 runtime 能理解的请求和响应src/model/provider.rs
ModelRequest一次模型请求的拥有所有权快照(历史、工具、continuation)src/model/provider.rs
ModelResponse归一化后的模型结果:文本、单个或多个工具调用src/model/provider.rs
MockProvider按脚本返回确定性响应的 provider,也是核心设计工具src/model/mock.rs
ProviderContinuationprovider 自己维护的续传数据,重启后仍可继续响应链src/runtime/state.rs
Wire style线上格式;项目同时支持 Responses 与 Chat Completionssrc/model/openai_protocol.rs

工具、策略与执行

术语含义相关位置
Tool / ToolSpec / ToolContext工具声明、给模型的 schema、执行时的最小能力集src/tools/spec.rs
RiskClass工具风险等级:Read / Write / Executesrc/tools/spec.rs
PolicyDecision授权决策:Allow / Ask / Denysrc/policy/mod.rs
fail-closed无法判断风险时默认拒绝,而不是默认放行src/policy/mod.rs
Executor真正访问文件与进程的能力层src/executor/trait.rs
LocalExecutor本地文件与进程实现,未来可替换为 sandbox 或远程src/executor/local.rs
进程组(process group)取消/超时时按进程组清理,避免遗留子孙进程src/executor/process.rs
三层输出上限分别限制 stdout、stderr 和合计输出src/executor/process.rs
OutcomeUnknown执行可能已产生副作用,但日志没有可靠结果src/runtime/state.rs

持久化与恢复

术语含义相关位置
Event / EventPayload一条事实及其内容src/durable/event.rs
seq / event_id / schema_version会话内序号、事件自身 ID、事件格式版本src/durable/event.rs
Reducer确定性函数 reduce(state, event),不接受外部输入src/durable/reducer.rs
append 事务先验证、再持久化、后提交状态src/runtime/agent_loop.rs
Checkpoint加速重放的派生快照,不是事实来源src/durable/checkpoint.rs
RecoveryFinding恢复时对未完成工作的分类结果src/durable/recovery.rs
RecoveryPolicy每类 finding 的保守恢复建议(重试 / 查 hash / 人工决定)src/durable/recovery.rs

取消与并发

术语含义相关位置
CancellationToken随请求传播的取消信号,沿 turn → child → executor 传递src/runtime/agent_loop.rs
单写者 actor只有唯一写者能修改会话状态和追加事件src/runtime/session_actor.rs
SessionCommand发给 actor 的操作请求(StartTurn、CancelTurn…)src/runtime/session.rs
Steerturn 运行期间提交的新输入,按事实排队src/runtime/session_actor.rs
durable 输入队列排队输入先持久化再确认,崩溃后可恢复src/runtime/session_actor.rs
Scheduler组合多个 session 的任务生命周期,不复制会话状态src/scheduler/mod.rs

协议与 UI

术语含义相关位置
JSONL 协议stdin 请求、stdout 响应与事件、stderr 诊断,一行一个 JSONsrc/protocol/jsonl.rs
response vs notification带 id 的命令回复,与无 id 的事件通知,必须分别路由src/protocol/jsonl.rs
安全投影只向客户端暴露白名单字段,隐藏工具原始输入输出src/protocol/event_projection.rs
input_summary给审批界面看的工具输入短摘要src/protocol/event_projection.rs
Ink TUIui/ 下的 TypeScript 协议客户端,UI 只消费事件ui/src/client.ts

明确不做的事(非目标)

术语含义
exactly-once外部副作用不承诺恰好执行一次;宁可标记 OutcomeUnknown
排队输入取消队列中的输入不单独取消,要么等它开始,要么 abandon-turn
OS 级 sandbox路径检查不等于 sandbox;真实隔离是后续深度专题