骨架 —— 从空目录,到跑通第一个循环
前面的 Part A–D 都在读别人写的 Pi。从这一章起换成另一种姿势:你自己写。
目标很具体:从空目录开始,敲四个文件、318 行,node src/demo.ts 打印出一次
完整的「模型说话 → 调工具 → 模型收尾」。不 clone Pi,不配 API key,不打开任何
别人的源码。全部代码在本章里逐行给出,复制就能跑。
跑出来的样子(本机真实输出,后面 §五 会逐行拆):
[turn 1] 先看看文件。 -> read [ok][turn 2] (mock)读完了,文件已经在上下文里。[stop] turns=2 stop=stoproles: user → assistant → tool → assistant四个文件,职责一条一条对齐:
| 文件 | 行数 | 只负责一件事 |
|---|---|---|
src/types.ts |
106 | 四个契约:消息、工具、provider、事件 |
src/provider/mock.ts |
40 | 假模型:不联网,按三条规则吐 chunk |
src/loop.ts |
112 | 外层轮次 + 内层工具,三个出口 |
src/demo.ts |
60 | 入口:拼起来跑一条链路,把事件打成文字 |
| 合计 | 318 |
读完你应该能答三个问题:
- 模型说「我要调
read」,真正去执行它的是谁? - 循环凭什么说「停」?有几种停法?
- 为什么 provider 返回的是一串 chunk,而不是一条完整消息?
一、先定契约,再写逻辑
新手最常见的顺序是:先写 while,再补类型,然后卡在「工具结果该塞到哪」,
回头改类型,循环跟着改两遍。
反过来做:先花 106 行把契约钉死,后面三章都不再动它。
src/types.ts 全文:
/** * 四个契约:消息、工具、事件、provider。 * 这一层不 import 任何外部包,换 provider 也改不到它。 */export type StopReason = "stop" | "toolUse" | "length" | "maxTurns" | "error";export interface TextBlock { type: "text"; text: string;}export interface ToolCallBlock { type: "toolCall"; id: string; name: string; args: Record<string, unknown>;}export type ContentBlock = TextBlock | ToolCallBlock;export interface SystemMessage { role: "system"; content: string;}export interface UserMessage { role: "user"; content: string;}export interface AssistantMessage { role: "assistant"; content: ContentBlock[]; stopReason: StopReason;}export interface ToolResultMessage { role: "tool"; toolCallId: string; toolName: string; content: string; isError?: boolean;}/** 给模型看的只有这四种。 */export type Message = | SystemMessage | UserMessage | AssistantMessage | ToolResultMessage;/** 只给自己看的一种:display=false 时只进上下文,不上屏。 */export interface NoteMessage { role: "note"; kind: "summary" | "reminder"; text: string; display: boolean; timestamp: number;}export type AgentMessage = Message | NoteMessage;export interface ToolParameter { type: "string" | "number" | "boolean"; description: string;}export interface Tool { name: string; description: string; parameters: { type: "object"; properties: Record<string, ToolParameter>; required: string[]; }; execute(args: Record<string, unknown>): Promise<string> | string;}export type ProviderChunk = | { type: "text"; text: string } | { type: "toolCall"; id: string; name: string; args: Record<string, unknown>; } | { type: "done"; stopReason: StopReason };export interface Provider { name: string; stream( messages: Message[], tools: Tool[], signal?: AbortSignal, ): AsyncIterable<ProviderChunk>;}export type AgentEvent = | { type: "agent_start" } | { type: "turn_start"; turn: number } | { type: "text_delta"; text: string } | { type: "tool_start"; id: string; name: string } | { type: "tool_end"; id: string; isError: boolean } | { type: "turn_end"; turn: number; stopReason: StopReason } | { type: "agent_end"; stopReason: StopReason };106 行,五组。每组都在回答一个后面会反复用到的问题。
1. StopReason:先把「怎么停」定死
五种,一个不多:stop 模型说完了;toolUse 模型要调工具;length 被截断;
maxTurns 轮次用完;error 出错。
绝大多数 agent 的 bug 都能归到这一行上——用「循环结束了」表示成功。循环结束
有五种原因,maxTurns 和 error 都不算成功,但如果你只有一个 boolean,它们就
全变成「成功」。
2. ContentBlock:一条消息里能装什么
只有两种:文字、工具调用。注意它们是同一个数组里的元素,不是两个字段。真 模型的返回也是这样:先吐一句「我看看」,再吐一个 tool call,顺序有意义,所以必须 同一条 assistant 消息里共存、保序。
3. Message 四种 vs AgentMessage 五种
给模型看的只有四种。第五种 NoteMessage(role: "note")永远不发给模型,
它只进你自己的上下文——E02 会讲到它为什么必须存在。现在只要记住:「我记下的」
和「模型能看到的」是两层,AgentMessage 是上层,Message 是下层。这个分层
是后面省掉一大堆 bug 的关键。
4. Tool:描述是给模型看的
四个字段不是凑数:name 是模型回传时的唯一凭据;description 是模型决定要
不要用它的唯一依据;parameters 是 JSON Schema 的子集,模型照着填;execute
是唯一真正碰副作用的地方。
注意 execute 返回 string,不是对象。工具的输出必须是字符串——它会原样
变成一条消息塞回上下文,模型只认文本。
5. Provider:为什么返回 chunk 流,而不是一条消息
这是本章第一个真正的设计决定。三种做法都能跑,但只有一种是活的:
- 返回完整消息:调用方拿不到「正在打字」的中间态,UI 只能等
- 返回完整消息 + 回调:能打字了,但两次回调之间没法取消
- 返回 async 迭代器:要一个字给一个字,中途可以
return,也可以signal.abort()
真模型的工具调用参数还是分片到达的({"pa th": "RE ADME.md"}),
拼装必须发生在接收流的人手里。所以契约定成 AsyncIterable<ProviderChunk>,
E03 接真 SSE 时一行都不用改。
五个契约怎么串起来
这 106 行看着零散,其实是同一条流水线上五个工位的进出料规格:
Provider.stream() 出料:chunk(text / toolCall / done) | v loop.ts 收流拼装 进料:ContentBlock[] 出料:AssistantMessage | v loop.ts 执行工具 进料:Tool.execute(args) 出料:ToolResultMessage | v 下一轮再发 进料:Message[](四种) 出料:chunk …(回到第一行)而 AgentEvent 是旁路:循环往右边吐进度,不参与下一步计算。进料出料是数据,
event 是通知,混在一起就是后面所有难改的根源。
二、先写假模型
src/provider/mock.ts 全文:
import type { Provider } from "../types.ts";/** * 假模型:不联网、不随机、不看历史的情感。 * 规则只有三条,够把循环跑通,也够让实验刻意失败。 * 1. 第一次调用、问句里有「读」、且 read 有描述 → 发一条 toolCall * 2. 已经有 tool 结果 → 回一句总结,停 * 3. 其余 → 原样回显,停 */export function createMockProvider(): Provider { return { name: "mock", async *stream(messages, tools) { const last = [...messages].reverse().find((m) => m.role === "user"); const text = last && "content" in last ? String(last.content) : ""; const read = tools.find((t) => t.name === "read"); const usedTool = messages.some((m) => m.role === "tool"); const wantsRead = /读|read/i.test(text); if (!usedTool && read && read.description !== "" && wantsRead) { yield { type: "text", text: "先看看文件。" }; yield { type: "toolCall", id: "call_1", name: "read", args: { path: "README.md" }, }; yield { type: "done", stopReason: "toolUse" }; return; } if (usedTool) { yield { type: "text", text: "(mock)读完了,文件已经在上下文里。" }; yield { type: "done", stopReason: "stop" }; return; } yield { type: "text", text: `(mock)收到:${text}` }; yield { type: "done", stopReason: "stop" }; }, };}为什么第一版不接真模型,三个理由,都不是「省事」:
- 可复现:同样的输入永远同样的输出,测试才能断言
- 零成本:11 个测试跑完 272 毫秒,不花一分钱
- 故障可控:想让工具报错就报错,想让它不发 tool call 就不发,不用等模型心情
关键在于:它假的只是「决策」,不是「接口」。stream() 的签名、chunk 的
形状、done 里那个 stopReason,和 E03 的真模型完全一致。所以 loop.ts 一行
都不知道自己在跑假模型。
三条规则读一遍:
!usedTool && read && read.description !== "" && wantsRead:没调过工具、注册 了read、描述非空、这句里有「读」→ 发一条toolCall。四个条件少一个就 走空。usedTool为真(上下文里已经有role: "tool"的消息)→ 说一句总结就停。- 其余 → 回显。
read.description !== "" 这个看似多余的判断,是 E05 的实验钩子:把描述清空,
模型就不调它了。描述不是注释,是接口。
换成真模型,要改几行
零行。loop.ts 不知道 provider 是谁,demo.ts 只改一个构造调用:
| mock(本章) | 真模型(E03) | |
|---|---|---|
| 拿凭据 | 不需要 | OPENAI_API_KEY + BASE_URL |
| 拿 chunk | 硬编码 yield | fetch 读 SSE,逐帧 JSON.parse |
| 拼参数 | 一次给全 | 分片到达,按 index 累积 |
| 错误 | 不会错 | 429 退避、超时、abort |
| 接口 | Provider |
Provider(一模一样) |
这就是为什么第一章先写假的:你先把左边那列确定下来,右边那列才只有一个变量。 一开始就接真模型,跑不通时你分不清是自己循环写错了还是网络/凭据/报文错了。
三、循环本体
整个包最值钱的 112 行。先看骨架,再看代码:
while (turns < maxTurns) 收流 → 拼 content → assistant 入栈 没有 toolCall? → 停(stop) 有 → 逐个执行 → tool 消息入栈 工具连错 3 次? → 停(error) turns 用完? → 停(maxTurns)src/loop.ts 全文:
import type { AgentEvent, AgentMessage, ContentBlock, Message, Provider, StopReason, Tool,} from "./types.ts";const MAX_TOOL_ERRORS = 3;export interface RunOptions { provider: Provider; tools: Tool[]; messages: AgentMessage[]; maxTurns?: number; /** 把 AgentMessage 投影成给模型看的 Message;E02 才传入。 */ project?: (messages: AgentMessage[]) => Message[]; emit?: (event: AgentEvent) => void; signal?: AbortSignal;}export interface RunResult { messages: AgentMessage[]; stopReason: StopReason; turns: number;}export async function runAgent(options: RunOptions): Promise<RunResult> { const emit = options.emit ?? (() => {}); const project = options.project ?? ((all: AgentMessage[]) => all as Message[]); const maxTurns = options.maxTurns ?? 3; const messages = [...options.messages]; let turns = 0; let stop: StopReason = "maxTurns"; let errors = 0; emit({ type: "agent_start" }); while (turns < maxTurns) { turns += 1; emit({ type: "turn_start", turn: turns }); const content: ContentBlock[] = []; let reason: StopReason = "stop"; const llm = project(messages); const stream = options.provider.stream(llm, options.tools, options.signal); for await (const chunk of stream) { if (chunk.type === "text") { content.push({ type: "text", text: chunk.text }); emit({ type: "text_delta", text: chunk.text }); } else if (chunk.type === "toolCall") { content.push({ type: "toolCall", id: chunk.id, name: chunk.name, args: chunk.args, }); } else { reason = chunk.stopReason; } } messages.push({ role: "assistant", content, stopReason: reason }); const calls = content.filter((b) => b.type === "toolCall"); if (calls.length === 0) { emit({ type: "turn_end", turn: turns, stopReason: reason }); stop = reason; break; } for (const call of calls) { const tool = options.tools.find((t) => t.name === call.name); emit({ type: "tool_start", id: call.id, name: call.name }); let text = ""; let isError = false; if (!tool) { isError = true; text = `未知工具:${call.name}`; } else { try { text = await tool.execute(call.args); } catch (error) { isError = true; text = error instanceof Error ? error.message : String(error); } } errors = isError ? errors + 1 : 0; emit({ type: "tool_end", id: call.id, isError }); messages.push({ role: "tool", toolCallId: call.id, toolName: call.name, content: text, isError, }); } emit({ type: "turn_end", turn: turns, stopReason: reason }); if (errors >= MAX_TOOL_ERRORS) { stop = "error"; break; } if (turns >= maxTurns) { stop = "maxTurns"; break; } } emit({ type: "agent_end", stopReason: stop }); return { messages, stopReason: stop, turns };}六段,逐段看。
1. 参数为什么同时有 AgentMessage[] 和 Message[]
messages 收的是 AgentMessage[](含 note),但 stream() 收的是
Message[](不含 note)。中间那道转换由 project 做,默认是恒等函数——因为
E01 还没有 note。E02 会把压缩、过滤、重排全塞进这个函数,loop.ts 不用改。
这是全章最值得抄的一个模式:把「历史」和「这一轮发给模型的视图」分成两个 值。合成一个,后面每加一种只给自己看的东西,循环都得改。
2. 内层 for await:三个分支
text 进 content 并转发事件;toolCall 只进 content(工具没执行,只是记下
来);done 只改 reason。
注意第三个分支写的是 else,不是 else if (chunk.type === "done")。因为
ProviderChunk 只有三种,剩下的一定是 done——让类型收窄替你写判断,写错了
编译期就报。
3. reason 只有一个来源
let reason: StopReason = "stop" 是兜底:如果 provider 一个 done 都没吐就结束
了,这一轮按 stop 算。真模型断流时就是这种情况——兜底值决定了断流算成功还是
失败,这里选了成功,因为内容确实收到了。
4. assistant 消息必须在执行工具之前入栈
顺序不能反。模型下一轮要看到的是:自己说过「我要调 read」+ 工具结果。少任何 一半,真模型会重复调用同一个工具,或者干脆不认这个结果。
5. errors 是连续计数,不是总数
errors = isError ? errors + 1 : 0——成功一次就清零。理由:agent 死循环的典型
形态是同一个工具反复失败,那要拦;而一个长任务里零星几次失败然后自愈,是正常
现象,不该拦。
6. 三个出口,一张表
| 出口 | 条件 | stopReason |
谁负责 |
|---|---|---|---|
| 模型说完了 | 这一轮没有 toolCall | 原样透传(通常是 stop) |
模型 |
| 工具连续失败 | errors >= 3 |
error |
循环 |
| 轮次用完 | turns >= maxTurns |
maxTurns |
循环 |
while 外面还有一次 agent_end:不管从哪个出口出去,事件一定要收尾。少发
一条,订阅方就会永远等下去。
为什么外层是 while,内层是 for await
两个层次管两件事:外层管轮次预算(还能不能再来一轮),内层管这一轮的 流(chunk 还没收完)。
看得见的后果:内层 for await 中途 break,调用方就不能再 yield 了——所以
想把工具改成并发执行,不能在内层动手,得等流收完之后在主循环那一层动。那是
E04 的事,本章先按顺序执行,一行都不提前优化。
一个反直觉的细节:工具失败也是消息
工具抛错时,loop.ts 并没有往外抛,而是把错误文本当成 content、isError
置真,照常压进上下文。因为模型需要知道自己错了——不告诉它,它下一轮只会
用同样的参数再试一次。工具错误是给模型的信息,不是给程序的异常。
四、60 行入口
src/demo.ts 全文:
/** * E01 的终点:把四块拼起来,跑通一条完整链路。 * 运行:cd examples/mini-agent && node src/demo.ts */import { readFile } from "node:fs/promises";import { runAgent } from "./loop.ts";import { createMockProvider } from "./provider/mock.ts";import type { AgentEvent, Tool } from "./types.ts";/** * 工具就是这个形状:名字 + 描述 + 参数表 + 一个函数。 * 描述不是给人看的,是给模型看的——mock 也照着它决定要不要调用。 */const read: Tool = { name: "read", description: "读一个文本文件的前 5 行", parameters: { type: "object", properties: { path: { type: "string", description: "相对路径" } }, required: ["path"], }, async execute(args) { const text = await readFile(String(args.path), "utf8"); return text.split("\n").slice(0, 5).join("\n"); },};/** 事件是给人看的:循环自己不 print,谁消费谁决定怎么显示。 */function trace(event: AgentEvent): void { switch (event.type) { case "turn_start": process.stdout.write(`\n[turn ${event.turn}] `); break; case "text_delta": process.stdout.write(event.text); break; case "tool_start": process.stdout.write(`\n -> ${event.name} `); break; case "tool_end": process.stdout.write(event.isError ? "[err]" : "[ok]"); break; case "agent_end": process.stdout.write(`\n[${event.stopReason}] `); break; default: break; }}const result = await runAgent({ provider: createMockProvider(), tools: [read], messages: [{ role: "user", content: "读一下 README.md 的头几行" }], maxTurns: 3, emit: trace,});console.log(`turns=${result.turns} stop=${result.stopReason}`);console.log(`roles: ${result.messages.map((m) => m.role).join(" → ")}`);三个要点:
- 工具就是字面量:没有注册器、没有装饰器,一个对象就是一把工具。E04 会加 校验、并发、写锁,但形状不变。
- 循环不 print:
loop.ts只emit,trace决定怎么显示。所以同一份循环 能同时喂给终端、WebSocket、测试断言。 package.json里"type": "module":这样才能用顶层await和.ts后缀的 import(Node 24 直接擦类型,不需要 tsc)。
五、跑一遍
cd examples/mini-agentnode src/demo.ts[turn 1] 先看看文件。 -> read [ok][turn 2] (mock)读完了,文件已经在上下文里。[stop] turns=2 stop=stoproles: user → assistant → tool → assistant逐行对:
[turn 1] 先看看文件。:text_delta一路打出来,这是模型的第一句话-> read [ok]:tool_start+ 实际执行 + 成功[turn 2] …:第二次调模型,此时上下文里已经有role: "tool",mock 走规则 2roles: user → assistant → tool → assistant:四条的完整顺序。这个顺序就是 agent 的全部记忆,没有别的隐藏状态
两个故意做坏的实验
把工具列表清空再跑,结果完全不同:
A 没有工具: turns=1 stop=stop roles=user>assistantB 只给一轮: turns=1 stop=maxTurns roles=user>assistant>tool- A:
tools: [],mock 的规则 1 要求read存在,条件不成立 → 不发 tool call → 一轮就停,stop,只有两条消息 - B:
maxTurns: 1,工具执行完了,但没机会把结果交回模型 → 卡在tool上,stopReason是maxTurns。B 看起来「跑通了」,其实是半成品——这正是stopReason存在的意义
跑完这两个,你对「停」的理解就从一句话变成一张状态图了。
跑不通时先查这三处
按命中率排序,本章范围内的故障人都是在这三行里:
roles里没有tool:工具没执行。先看content里到底有没有toolCall, 再看tools.find是不是名字没对上turns=1就stop:模型没打算用工具。mock 的话看四个条件,真模型的话 看description写清楚没有stop=maxTurns但答案不完整:轮次给少了。一次「说一句 + 调工具」占一轮, 别按「一轮 = 一问一答」算
就这三条,能把本章 90% 的挫败省下来。
六、本章代码地图
| 文件 | 关键符号 | 下一章怎么用 |
|---|---|---|
src/types.ts |
AgentMessage / Message / Provider |
E02 靠这两层的差做投影 |
src/provider/mock.ts |
createMockProvider() |
E03 换成真 SSE,接口不变 |
src/loop.ts |
runAgent() / project 参数 |
E02 传投影,E04 换工具调度 |
src/demo.ts |
read / trace |
E08 长成 cli.ts |
本章 318 行跑通;到 Part E 结束共 1,252 行,每章加一块,顺序是: E02 消息投影 → E03 真模型与 fixture → E04 工具注册表与写锁 → E05 压缩 → E06 会话落盘 → E07 扩展钩子 → E08 命令行。每章末尾都有一个能直接跑的入口文件。
自检
- 把
mock.ts里stopReason: "toolUse"改成"stop",输出哪一行会变?loop.ts的哪个分支受影响? - 如果
loop.ts在for await之后、执行工具之前return,roles会是 什么?stopReason呢? demo.ts里把execute改成throw new Error("boom"),再跑一遍——会停在 哪?要跑几次才会变成error?
参考答案(先自己跑再看):
第 1 题:屏幕输出不变,只差最后一条 assistant 消息里的 stopReason 字段。
因为 mock 只在 done 里报原因,而那个原因此刻只用于写进消息和
result.stopReason。
第 2 题:roles: user → assistant,stopReason: "maxTurns"。注意不是
stop——stop 的初始值就是 maxTurns,这一轮没走到出口判断就被 return
截断了,兜底值直接生效。这就是为什么「提前 return」是天坑:你拿到的不是
「正常结束」。
第 3 题:停不下来,会像平常一样跑到第二轮就正常结束。工具报错被当成消息 吞了:
turns=2 stop=stopuser > assistant > tool(err) > assistant{"content":"boom","isError":true,"role":"tool",…}要连续三次失败才会变成 error,而 mock 拿到 tool 结果后不会再发 toolCall,
所以本章跑不出 error 出口——想看它,得让 provider 反复吐同一个 call,
那要到 E03 才会自然碰到。
与 Pi 的对照(可选,不需要打开源码)
你写的 112 行,在 Pi 里是 packages/agent/src/agent-loop.ts:外层
agent-loop.ts:188 一个 while (true),内层 agent-loop.ts:192 处理工具调用
与待发消息。结构同构,多出来的是并发、取消、流控和持久化。
真要看的时候再去看,现在你手上已经有一份能跑的了。
七、下一章
现在这个循环有个不舒服的地方:role: "note" 定义了却没用,project 参数一直
是空的。E02 就填这个洞——四种消息给模型,第五种给自己,以及为什么「把摘要
塞回上下文」这件事,一不小心就会变成「模型看见了自己不该看的东西」。