一次 README 读取请求怎样走完 Agent 闭环

#你将看到什么

用户说：“读取 README.md，用一句话告诉我这个项目做什么。”这句话进入系统后，模型 不会立刻给出最终回答。它先请求 read 工具，等读取结果回来，再根据这项新事实回答 用户。

这一章跟随这次请求经过的七个可见里程碑。我们暂时不实现模型和工具，也不要求你先 理解 TypeScript。读完以后，你应该能说明每个里程碑记录了什么、这条事实来自谁，以及 为什么工具请求和工具结果要使用同一个 toolCallId。

用户消息
  → 第一次模型调用
  → 模型提出 read 工具调用
  → 循环开始调度 read
  → read 返回 README 内容
  → 第二次模型调用
  → 模型给出最终回答

这条路径有一项始终成立的约束：一旦 assistant message 中出现 tool call，transcript 里最终就要出现一条使用相同 toolCallId 的 tool result。请求说明“模型想做什么”， 结果才说明“环境实际返回了什么”。

#七个里程碑

课程中的离线演示固定产生下面七条记录。owner 直接写在每条记录上：

01 user_message       owner=user   detail="读取 README.md，并概括项目"
02 model_start        owner=model  detail="turn=1"
03 assistant_message  owner=model  detail="stopReason=toolUse name=read"
   toolCallId=call_1
04 tool_start         owner=loop   detail="name=read" toolCallId=call_1
05 tool_result        owner=tool   detail="README fixture" toolCallId=call_1
06 model_start        owner=model  detail="turn=2"
07 assistant_message  owner=model  detail="stopReason=stop"

#01 · 用户消息确定本次目标

user_message 保存用户给出的目标：“读取 README，并概括项目。”此时系统只有请求， 还没有 README 的内容，也没有最终答案。

#02 · 第一次模型调用开始

model_start 表示模型开始处理当前消息。它是运行过程中的一个可见信号。这里还没有 assistant message，也没有环境动作发生。

#03 · 模型提出 read 工具调用

第一条 assistant_message 的 stopReason 是 toolUse。模型没有把这轮当作最终回答， 而是在 content 中提出一项请求：调用 read，参数是 { "path": "README.md" }。

工具调用的 id 是 call_1。这个 id 会跟着请求进入后面的调度和结果，让系统知道哪条 结果回答了哪次调用。到这一步为止，模型只表达了读取意图；它还没有接触文件系统。

#04 · 循环开始调度 read

tool_start 记录循环已经开始处理 call_1。模型提出动作，Agent loop 决定执行顺序， 真正的环境访问则属于工具。把这三项责任分开后，“提出请求”和“开始执行”就不会被 误写成同一件事。

#05 · 工具结果成为新的环境事实

tool_result 继续使用 call_1，并带回固定的 README 观察结果。下文把它写进 canonical transcript 时，会用 isError=false 标出读取成功，并把文件内容放进消息。只有这条结果 出现以后，后续模型调用才有依据使用文件内容。

这一章播放的是固定 fixture。README 的结果已经写在演示数据中，固定 fixture 不执行 真实的文件读取，也不会修改你的工作区。真实系统到了同一位置时，read 工具才会访问 文件。

#06 · 第二次模型调用看到新增结果

第二个 model_start 表示循环再次调用模型。这次输入中已经包含原来的用户目标、模型 提出的 call_1，以及与它配对的 tool result。模型因此可以根据读取结果继续回答。

#07 · 最终回答结束这次运行

最后一条 assistant_message 的 stopReason 是 stop。它不再请求工具，而是给出一句 概括：“这是一个用于学习 Agent 内核的 TypeScript 项目。”七个里程碑到这里闭合。

#Owner 回顾：三条容易混淆的记录

轨迹中的 user_message 和 assistant_message 已经直观标出消息来自用户还是模型。下面 三条更容易混淆，因为发起调用、调度动作和访问环境分别由不同对象完成：

owner 表示这条事件记录所对应的动作来自谁，不等于最外层调用的发起者。

loop 发起模型调用时，model_start 记录的仍是模型生命周期。模型提出 read 后， tool_start 只说明 loop 已开始调度；README 内容要等 tool_result 才出现。

model_start 和 tool_start 都是运行轨迹事件，不是之后会保存进 transcript 的 AgentMessage。它们适合显示进度，却不会成为下一轮模型必须读取的长期事实。

#Transcript 保存下一轮仍需要的事实

七个里程碑中，进入 canonical transcript 的是 user message、完成的 assistant message 和 tool result。把它们按顺序放在一起，可以看到第二次模型调用所依据的内容：

user
  content: "读取 README.md，并概括项目"

assistant
  stopReason: toolUse
  toolCall: { id: "call_1", name: "read", arguments: { path: "README.md" } }

toolResult
  toolCallId: "call_1"
  toolName: "read"
  isError: false
  content: "# tiny-pi ..."

assistant
  stopReason: stop
  text: "这是一个用于学习 Agent 内核的 TypeScript 项目。"

同一份 AgentMessage[] 可以显示在终端、写入 JSONL，或变成下一次模型请求。界面颜色、 日志前缀和折叠状态不属于消息语义，所以 transcript 保存结构化消息，不保存终端渲染 后的字符串。

后续章节会逐步实现这些消息以及运送它们的部件。无论内部代码怎样展开，README 请求 仍沿着同一条可观察路径前进：

用户给出读取目标
  → 模型开始第一轮并提出 read
  → loop 把 call_1 交给工具
  → 工具返回 README 内容
  → call_1 的结果加入对话
  → 模型在第二轮读到新增结果
  → 模型给出最终回答

后续代码会给其中几项动作加上组件名。它们与上面的轨迹逐项对应：

第 01–05 章会建立消息、事件流、离线模型和 Provider 边界；第 06–08 章接入工具与 Agent loop；第 09–11 章让运行可取消、可保存、可恢复，并按预算重建 context；第 12–14 章 再加入资源、产品入口和系统评测。每一部分都会回到这次 README 请求，把其中一个固定 部件换成可以运行的实现。

#本章验收

#小结

同一条 README 请求提供了两种观察角度。owner 标出当前事实由谁产生；canonical transcript 则保留下一轮仍要读取的 user message、完整 assistant message 和 tool result。model_start 与 tool_start 适合显示进度，不需要进入长期消息。

call_1 把模型的读取意图与工具返回的环境事实配成一对。后续章节会继续使用这条固定 轨迹，逐件换入消息、事件流、模型、工具、循环和持久化实现。