mini-harness 教程:从一次请求读懂 Agent Harness
这是一份对照源码学习的教程。目标不是让你背下几个术语,而是让你能打开这个仓库,沿着一次真实请求走完代码,并解释每一个边界为什么存在。
你不需要先了解 Agent、事件溯源或分布式系统。只要会一点 Rust,愿意边读边运行命令,就可以从第 0 章开始。
这不是重写一个 Harness
你要学习的是当前仓库里的这份实现。教程不会要求你新建项目、复制一套代码,或在每章末尾得到一个“自己的 mini-harness”。
每章都采用同一个方法:
- 先从一个用户动作或一次故障开始;
- 找到当前代码处理它的入口;
- 顺着数据、事件和状态往下读;
- 用现有测试或一个只读命令验证理解;
- 再解释为什么这个边界必须这样设计。
教程中的“任务”统一指一次源码阅读、运行观察或测试验证。
先用一句话理解 Harness
模型只负责提出建议:回答用户,或者请求调用某个工具。
Harness 负责把建议变成受控的现实动作:检查权限、执行文件或进程、记录发生过的事实、处理取消与崩溃,并把结果重新交给模型。
可以把它想成一个有门卫、有账本、有急停按钮的工作台:
用户输入
│
▼
Session / Turn ──▶ Provider(模型)──▶ Tool call(建议)
│ │
│ Policy(能不能做)
│ │
│ Executor(实际去做)
│ │
└──────────── Event log(发生过什么)◀─┘
这份教程怎样和源码对应
教程中的“第 3 章”等于当前仓库中的一个主题,不代表源码提交历史中的一天。每章都会明确列出:
- 先读哪些真实文件;
- 一次调用从哪个函数进入、经过哪些函数;
- 运行哪条命令或测试观察结果;
- 哪些代码是核心,哪些是为生产边界补上的细节。
源码地图
| 你要理解的东西 | 当前源码 | 先看什么 |
|---|---|---|
| 公共模块和导出 | src/lib.rs | 项目有哪些边界 |
| ID、历史、会话状态 | src/runtime/ids.rs、src/runtime/state.rs | SessionState、TurnState |
| 事件模型 | src/durable/event.rs | EventPayload、Event |
| reducer | src/durable/reducer.rs | reduce 如何拒绝非法序列 |
| 事件存储 | src/durable/store.rs、src/durable/event_log.rs | trait 与 JSONL 实现 |
| 模型抽象 | src/model/provider.rs | ModelRequest、ModelResponse、ModelProvider |
| 主循环 | src/runtime/agent_loop.rs | append、run_turn_with_cancel |
| 恢复和构造 | src/runtime/agent_loop_setup.rs | restore、restore_with_checkpoint |
| actor | src/runtime/session.rs、src/runtime/session_actor.rs | 命令如何串行化 |
| 工具 | src/tools/ | Tool、ToolRegistry、read/edit/bash |
| 执行器 | src/executor/ | 文件和进程的真实副作用 |
| 协议 | src/protocol/jsonl.rs | 请求循环、事件通知、安全投影 |
| UI | src/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 Completions | provider 换了,主循环为什么不用改? |
| 第 9 章 | CLI 和 JSONL 协议——把 runtime 放到进程边界外 | 为什么 stdout 只能输出协议? |
| 第 10 章 | 事件查看器和 Ink TUI——UI 只是事件投影 | UI 崩溃时,runtime 怎样继续工作? |
| 第 11 章 | Scheduler、durable 队列和全局并发 | 输入队列怎样做到可恢复?并发上限放在哪里? |
| 尾声 | 把这份 Harness 读成一个系统 | 怎样继续做 sandbox、PTY、MCP 或远程执行器? |
术语不确定时,查术语表。
每章的阅读顺序
不要一开始就试图理解整章所有细节。每章按下面顺序读:
- 先看本章问题:知道这一章要解释哪个运行时行为;
- 再看源码对照:打开列出的文件,先找结构体和入口函数;
- 运行观察命令:把抽象概念变成输出或事件;
- 逐步读主路径:只追一条成功路径;
- 最后读失败路径和测试:理解边界是怎样被锁住的;
- 再做思考题:用自己的话解释“如果删掉这条检查会发生什么”。
每章的代码片段用于帮助你定位源码和理解关键步骤,不是另一份独立实现。源码中已经存在的实现才是最终事实;如果教程文字和源码不一致,以源码和对应测试为准,并把差异记下来。
文中的代码片段用于定位源码和解释关键步骤。先不要复制代码;只有当你想检验自己是否真的掌握时,才把某个函数改成小实验,再用测试恢复。
环境和常用命令
要求: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 | 一次用户输入到最终回答、失败或取消 |
| Step | turn 中的一次模型请求和处理 |
| Provider | 把模型服务翻译成 ModelRequest 和 ModelResponse |
| Tool | 模型可以请求的操作,例如 read、edit、bash |
| Policy | 决定工具调用是 Allow、Ask 还是 Deny |
| Executor | 真正访问文件和进程的能力层 |
| Event | 已经发生的事实 |
| State | reducer 从事件推导出的当前视图 |
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,按以下顺序跳转:
- 找 MockProvider 的脚本;
- 找三个工具如何注册;
- 找 Session::new_with_policy;
- 找 Session::start_turn;
- 找 AgentLoop 的 begin_turn 和 continue_turn;
- 找 tool completed 后 history 如何变化;
- 找事件最终从 InMemoryEventStore 读出并打印的位置。
每跳到一个函数,只记两句话:
它拿到什么?
它把什么交给下一层?
不要在这一步停留在 tokio、泛型或 serde 的细节。先弄清数据流,再在后面的章节回头理解实现细节。
第 0 章检查
你能做到下面四件事,就可以继续:
- 用一句话解释 harness 和“给模型加几个工具函数”的区别;
- 从 run_demo 追到 ReadTool 和 LocalExecutor;
- 说出 Event、State、Policy 和 Executor 各自负责什么;
- 从 demo 输出指出 tool.requested、tool.completed 和 turn.completed 的先后关系。
思考题
- 为什么 UI 只消费事件投影,而不是直接拿 SessionState?
- 如果 provider 直接执行 bash,Policy 和 Executor 还剩下什么意义?
- 如果只保存 SessionState,不保存事件,崩溃恢复会失去什么?
- 一个新的远程 executor 应该替换哪一层?为什么 AgentLoop 不应该跟着重写?
- 如果允许两个工具并行执行,当前“单写者 + 顺序事件”要重新回答哪些问题?
下一章:先读懂类型和事件。
第 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 提供了四类能力:
- new:生成随机 UUID;
- Display:打印带前缀的字符串;
- parse 和 FromStr:拒绝错误前缀或坏 UUID;
- 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
然后打开对应测试,按这个顺序看:
- 测试创建了哪一种 ID;
- 它打印和解析的字符串是什么;
- 它如何构造 Event;
- 它最后断言了哪些字段相等。
测试不是额外知识,它是当前实现对这些类型做出的承诺。
你这一章应该能说清楚
- ToolCallId 为什么不能传给只接受 ExecutionId 的函数;
- EventPayload 和 Event 的职责差异;
- timestamp 为什么可以进事件,但 reducer 不应读取它;
- 一个错误为什么要区分 Policy、Provider、Execution 和 Durable。
思考题
- 如果把所有 ID 改成 String,哪一类错误会从编译期推迟到运行期?请举一个具体函数调用。
- 为什么 EventId 和 seq 都存在?如果只保留其中一个,诊断或并发追加会失去什么信息?
- ToolResult 和 ModelText 都包着 String。你会在哪些函数边界拒绝它们互换?
- 一个 provider 自己返回的 call_id 应该在哪一层转换成 ToolCallId?为什么不让 reducer 负责?
- timestamp 被篡改会影响状态重放吗?它会影响哪些诊断能力?
下一章:EventStore 和 reducer——日志怎样变成状态。
第 2 章:EventStore 和 reducer——日志怎样变成状态
第 1 章介绍了事件的形状。这一章追问:事件写在哪里?重启后,系统怎样知道当前会话进行到哪一步?
当前项目把答案拆成两个模块:
- EventStore 负责保存和读取事件;
- reducer 负责把事件应用到 SessionState。
这两个模块分开,是整个恢复能力的基础。
先看三个真实文件
按这个顺序打开源码:
- src/runtime/state.rs:SessionState、TurnState、HistoryItem;
- src/durable/reducer.rs:reduce;
- 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 | 这份状态属于哪个会话 |
| status | Idle、Running、Failed 或 Closed |
| active_turn | 当前是否有正在处理的 turn |
| history | 给后续模型请求使用的对话历史 |
| pending_inputs | turn 运行时排队的用户输入 |
| 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 对文件有严格规则:
- 空文件可以打开;
- 完整行必须能解析成 Event;
- 文件末尾没有换行时,读取报半行损坏;
- 中间损坏行不能自动修复;
- 每行 seq 必须与行号一致;
- 超过事件数量或总字节上限要拒绝。
半行修复是显式命令 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 的哪些字段;
- 它要求当前状态满足什么前置条件;
- 它能否被重放;
- 它失败时应该阻止追加,还是生成一个终态事件。
思考题
- 如果 reducer 在处理 ToolCompleted 时读取当前文件内容,会破坏什么性质?
- 为什么 JsonlEventStore 不能在读取时自动丢掉末尾半行,却可以提供单独的 repair_partial_tail?
- 如果 append 已经把事件写入文件,但进程在 self.state = next_state 之前崩溃,重启时会发生什么?
- 为什么 SessionState 的 pending_inputs 要从事件推导,而不是只存在 actor 的 VecDeque 中?
- 你会把 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。
思考题
- 如果 Provider trait 接收的是 &mut SessionState,会出现哪两种边界混乱?
- 为什么 StartTurn 和 WaitTurn 要分开?把它们合成一个阻塞调用会让哪个客户端难以实现?
- actor 在执行模型请求时仍然需要接收 CancelTurn。取消信号经过哪些对象到达 provider?
- 如果 MockProvider 的 script 耗尽后 panic,为什么会让恢复语义变差?
- 直接使用 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,按顺序读:
- parse_input:确认输入是对象;
- 拒绝未知字段;
- 确认 path 是非空字符串;
- 检查 start_line 和 end_line 是从 1 开始的整数;
- 通过取消令牌调用 executor;
- 把字节结果切成行窗口;
- 限制最多 200 行;
- 返回文本和截断信息。
这个顺序说明了两种不同的保护:
- 参数保护:防止模型传入无法解释的 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”的差异。两者发生的时间和责任人不同。
思考题
- 为什么 ReadTool 不直接接收 LocalExecutor,而是接收 Executor trait?
- workspace 外的 read 为什么直接 Deny,而不是 Ask?
- 一个 path 在词法上位于 workspace 内,但通过 symlink 指向外部,哪一层应该拒绝?
- Tool 返回字符串错误,为什么 Executor 仍然保留类型化错误?
- ToolRegistry 的 spec 大小上限保护的是哪一个资源?
- 如果你要加入一个列出环境变量的工具,它的 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 或空批测试,看它在事件日志里记录哪个终态。
思考题
- 为什么工具结果必须进入下一次 ModelRequest,而不能只存在 ToolCompleted 事件里?
- ContextSnapshot 截断 history 后,为什么 durable log 仍然要保留完整文本?
- 如果模型一次返回 100 个工具调用,最早应该在哪一层限制?
- append 的副本 reduce 能防止哪些问题,不能防止哪些外部副作用?
- 为什么 turn.cancel_requested 和 turn.cancelled 要分成两个事实?
- 审批暂停时,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 测试。每个测试都问“它在防止哪个现实中的事故”。
思考题
- 为什么达到 stdout 上限后仍要继续读取管道?
- kill 父进程后,为什么子进程可能继续存在?进程组解决了哪一层关系?
- 非零 exit code 为什么通常是模型可以处理的结果,而无法回收进程是 executor 错误?
- 取消一个 edit 时,为什么要把取消检查放在 rename 前,而不是每写一行都检查?
- read 的结果未知通常可以重试,bash 的结果未知为什么默认要人工决定?
- 如果两个 harness 实例同时编辑一个文件,advisory lock 和 hash guard 各自解决什么问题?
- 输出上限、历史上限和事件大小上限分别保护哪个边界?
下一章:崩溃恢复——系统怎样面对“不知道”。
第 7 章:崩溃恢复——系统怎样面对“不知道”
前几章已经有 durable event log,也能取消进程。现在考虑一个无法回避的时刻:
tool.started
进程崩溃
没有 tool.completed
本地日志只能证明工具开始了,不能证明外部世界最后发生了什么。当前项目没有假装自己拥有 exactly-once,而是把这种窗口明确表示为 OutcomeUnknown,并交给恢复流程分类。
恢复的三个动作
打开 src/durable/recovery.rs。恢复流程只做三件事:
- 读取并重放已有事件;
- 生成 RecoveryFinding;
- 在显式 recover 命令中追加恢复事实和 action required。
它不会执行 read、edit、bash,也不会自动重新发送 provider 请求。
这条边界很重要。恢复代码运行时,外部世界可能已经改变;它只能解释日志,不能凭空确认副作用是否发生。
RecoveryFinding 的含义
当前实现可能报告:
| Finding | 日志说明 |
|---|---|
| ActiveTurn | turn 没有到达终态 |
| 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 输出为什么要脱敏工具输入。
思考题
- 为什么恢复流程不能自动重试 read,即使 read 通常没有副作用?
- tool.started 后没有结果时,为什么不能直接记录 tool.failed?
- checkpoint 损坏时全量 replay 能恢复什么,不能恢复什么?
- recovery.completed 为什么需要成为事实,而不能只在 CLI 返回成功?
- 如果工具是“发送邮件”,policy_for_tool 应该返回什么?
- abandon-turn 之后,为什么新的 user.input.recorded 可以把会话从 Failed 拉回 Idle?
- 如果 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 不是靠“接口看起来一样”证明可替换,而是要通过相同的文本、工具调用、错误、取消和续传场景。
思考题
- 为什么 runtime 不直接保存 provider 的 native call_id?
- 如果换 model 后旧 response_id 失效,provider 应该怎样构造下一次请求?
- 429 的 Retry-After 为什么比固定 sleep 更可靠?
- 响应 JSON 不合法时为什么不建议直接重试?
- API key 只出现在 provider 内部,为什么仍然要测试 Debug 输出和事件日志?
- “请求已发出但进程在收到响应前崩溃”属于 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 |
| 协议和 UI | serve、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。测试顺序对应协议从输入可靠性到业务语义的层次。
思考题
- stdout 混入一行 tracing 日志时,为什么客户端无法“跳过它继续解析”?
- 为什么超长行必须被完整吞掉,而不是立即返回错误?
- 请求 response 和事件 notification 都写 stdout,怎样保证一条 JSON 不会被另一条写到一半插入?
- UI 想显示完整 bash 输出,应该直接扩大安全投影,还是增加受控读取接口?
- UI 在 turn.start 后断开连接,runtime 应该自动 cancel 吗?你会把“连接断开”和“用户取消”记录成同一个事实吗?
- 跨进程 cancel 的 out-of-sync 保护避免了什么,恢复流程又要补上什么?
第 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 可以改变显示,但不能改变事实。
思考题
- UI 为什么不能直接读取和解析 event log?
- 如果通知丢了一条,seq 怎样帮助客户端发现问题?
- 为什么 WaitingApproval 应该由事件投影推导,而不是只看 turn.wait 的错误码?
input_summary为什么不能直接等于工具的完整输入?- 想显示实时 stdout 增量,需要在协议中增加什么;安全投影边界会怎样变化?
- 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 会:
- 取队首;
- begin_queued_turn;
- 运行完整 turn;
- 把结果写入 outcomes;
- 唤醒对应的 deferred_waiters;
- 继续处理下一条。
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 不需要自己维护一套状态。
思考题
- 为什么 queued = true 必须晚于 user.input.recorded 的持久化?
- 审批暂停时输入可以 steer 当前 turn,工具执行时输入却延迟到下一个 turn,这个差异来自什么借用和状态约束?
- 如果 Scheduler 自己保存一份 history,会产生什么不同步场景?
- 为什么并发上限放在 policy 会让“等待资源”和“禁止执行”混在一起?
- 排队输入如果需要优先级,你需要追加哪些事实才能在恢复时重建顺序?
- 一个 session 关闭时,queue 中的输入和 deferred_waiters 应该分别得到什么结果?
- 为什么 semaphore permit 必须使用 RAII,而不能手动记得 release?
尾声:把这份 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 不需要重新理解这些外部差异。
回到源码做一次总复盘
建议重新打开这几个入口:
- src/main.rs 的 run_demo:组件怎样被接线;
- src/runtime/agent_loop.rs 的 append:一条事实怎样进入日志;
- src/durable/reducer.rs 的 reduce:日志怎样变成状态;
- src/runtime/session_actor.rs 的 run_actor:谁拥有唯一写权限;
- src/protocol/event_projection.rs 的 project_event:哪些事实能安全地给客户端;
- 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_inputs | AgentLoop |
| tool.requested | 模型要求哪个工具 | Pending execution | Policy / Tool |
| tool.started | 工具真的开始 | Running execution | Executor |
| tool.completed | 工具返回了什么 | Completed、history | Provider |
| 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。
选择下一步时,继续使用本教程的阅读方法:先找事实和边界,再找失败路径,最后让测试固定语义。
最后的思考题
- 新 provider 增加一种工具调用协议时,哪些文件应该变化,哪些文件应该保持不动?
- 如果把 event log 换成数据库,哪些 reducer 和恢复语义仍然必须保留?
- 如果 UI 要显示实时 stdout,哪一条安全边界会被重新设计?
- 如果允许并行工具调用,事件顺序、取消和并发上限需要新增什么事实?
- 哪一个模块最容易变成“第二个 runtime”?你会用什么接口边界阻止它?
- 你能否从一次 tool.outcome_unknown 事件,说明系统知道什么、不知道什么、下一步由谁决定?
到这里,教程的目标就完成了:你可以从用户输入追到外部副作用,再从事件日志反向追到恢复状态,也能判断一个新功能应该放在哪一层。
术语表
按主题整理。每条给出最短定义和对应的源码位置;读教程遇到不熟的词,先回这里查。
运行时结构
| 术语 | 含义 | 相关位置 |
|---|---|---|
| Harness | 模型循环之外的全部系统:授权、执行、持久化、恢复、协议与 UI | 第 0 章 |
| Session | 可恢复的长期会话,包含历史、配置和多个 turn | src/runtime/session.rs |
| Turn | 一次用户输入到最终回答、失败、取消或暂停 | src/runtime/state.rs |
| Step | 一次模型请求及其结果处理,一个 turn 可以包含多个 step | src/runtime/agent_loop.rs |
| ToolExecution | 一个具体工具调用实例,有独立 ID、状态和执行策略 | src/runtime/state.rs |
| ContextSnapshot | 拥有所有权、不可变的模型输入窗口,负责预算截断 | src/runtime/context.rs |
| 事实(fact) | 已经发生的事情,只追加、不修改,进入 event log | src/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 |
| ProviderContinuation | provider 自己维护的续传数据,重启后仍可继续响应链 | src/runtime/state.rs |
| Wire style | 线上格式;项目同时支持 Responses 与 Chat Completions | src/model/openai_protocol.rs |
工具、策略与执行
| 术语 | 含义 | 相关位置 |
|---|---|---|
| Tool / ToolSpec / ToolContext | 工具声明、给模型的 schema、执行时的最小能力集 | src/tools/spec.rs |
| RiskClass | 工具风险等级:Read / Write / Execute | src/tools/spec.rs |
| PolicyDecision | 授权决策:Allow / Ask / Deny | src/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 |
| Steer | turn 运行期间提交的新输入,按事实排队 | src/runtime/session_actor.rs |
| durable 输入队列 | 排队输入先持久化再确认,崩溃后可恢复 | src/runtime/session_actor.rs |
| Scheduler | 组合多个 session 的任务生命周期,不复制会话状态 | src/scheduler/mod.rs |
协议与 UI
| 术语 | 含义 | 相关位置 |
|---|---|---|
| JSONL 协议 | stdin 请求、stdout 响应与事件、stderr 诊断,一行一个 JSON | src/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 TUI | ui/ 下的 TypeScript 协议客户端,UI 只消费事件 | ui/src/client.ts |
明确不做的事(非目标)
| 术语 | 含义 |
|---|---|
| exactly-once | 外部副作用不承诺恰好执行一次;宁可标记 OutcomeUnknown |
| 排队输入取消 | 队列中的输入不单独取消,要么等它开始,要么 abandon-turn |
| OS 级 sandbox | 路径检查不等于 sandbox;真实隔离是后续深度专题 |