Pi Agent 源码级教程
E01

骨架 —— 从空目录,到跑通第一个循环

3,307 字 · 含 352 行代码 · 约 20 分钟

前面的 Part A–D 都在读别人写的 Pi。从这一章起换成另一种姿势:你自己写。

目标很具体:从空目录开始,敲四个文件、318 行,node src/demo.ts 打印出一次 完整的「模型说话 → 调工具 → 模型收尾」。不 clone Pi,不配 API key,不打开任何 别人的源码。全部代码在本章里逐行给出,复制就能跑。

跑出来的样子(本机真实输出,后面 §五 会逐行拆):

text
[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

读完你应该能答三个问题:

  1. 模型说「我要调 read」,真正去执行它的是谁?
  2. 循环凭什么说「停」?有几种停法?
  3. 为什么 provider 返回的是一串 chunk,而不是一条完整消息?

一、先定契约,再写逻辑

新手最常见的顺序是:先写 while,再补类型,然后卡在「工具结果该塞到哪」, 回头改类型,循环跟着改两遍。

反过来做:先花 106 行把契约钉死,后面三章都不再动它。

src/types.ts 全文:

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 行看着零散,其实是同一条流水线上五个工位的进出料规格:

text
  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 全文:

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 一行 都不知道自己在跑假模型。

三条规则读一遍:

  1. !usedTool && read && read.description !== "" && wantsRead:没调过工具、注册 了 read、描述非空、这句里有「读」→ 发一条 toolCall。四个条件少一个就 走空。
  2. usedTool 为真(上下文里已经有 role: "tool" 的消息)→ 说一句总结就停。
  3. 其余 → 回显。

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 行。先看骨架,再看代码:

text
while (turns < maxTurns)  收流 → 拼 content → assistant 入栈  没有 toolCall?  → 停(stop)  有             → 逐个执行 → tool 消息入栈  工具连错 3 次?  → 停(error)  turns 用完?     → 停(maxTurns)

src/loop.ts 全文:

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 全文:

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)。

五、跑一遍

bash
cd examples/mini-agentnode src/demo.ts
text
[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 走规则 2
  • roles: user → assistant → tool → assistant:四条的完整顺序。这个顺序就是 agent 的全部记忆,没有别的隐藏状态

两个故意做坏的实验

把工具列表清空再跑,结果完全不同:

text
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 存在的意义

跑完这两个,你对「停」的理解就从一句话变成一张状态图了。

跑不通时先查这三处

按命中率排序,本章范围内的故障人都是在这三行里:

  1. roles 里没有 tool:工具没执行。先看 content 里到底有没有 toolCall, 再看 tools.find 是不是名字没对上
  2. turns=1 就 stop:模型没打算用工具。mock 的话看四个条件,真模型的话 看 description 写清楚没有
  3. 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 命令行。每章末尾都有一个能直接跑的入口文件。

自检

  1. 把 mock.ts 里 stopReason: "toolUse" 改成 "stop",输出哪一行会变? loop.ts 的哪个分支受影响?
  2. 如果 loop.ts 在 for await 之后、执行工具之前 return,roles 会是 什么?stopReason 呢?
  3. 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 题:停不下来,会像平常一样跑到第二轮就正常结束。工具报错被当成消息 吞了:

text
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 就填这个洞——四种消息给模型,第五种给自己,以及为什么「把摘要 塞回上下文」这件事,一不小心就会变成「模型看见了自己不该看的东西」。