第一天 —— 一条请求的八分钟
这一章不需要你先懂 Pi。要动手的话,只需要三样东西:
装好的 pi 命令(npm i -g @earendil-works/pi-coding-agent,
或者直接 clone 源码跑,见 M01 §8)、一个 cd 进去的仓库、
以及一句你本来就想让它干的活。
不装也能读。下面每一步都给了行号,你可以只看代码块不看终端。
晚上九点半,你在一个仓库里敲下 pi "给 config.ts 加一个重试次数",回车。
屏幕上先是转了两秒的圈,然后模型开始吐字,第一句是「先看一下
config.ts 的结构」。它读了文件、改了两行、跑了一遍测试,报告完成。
你接受了结果,关掉终端。整个过程八分钟。
这八分钟里发生了什么?从你敲下那句话,到模型看到它的第一眼, 中间隔了大约二十个函数、五次 I/O、两个包边界。 绝大多数教程会在这里直接跳到「agent loop 长什么样」, 把入口那一层当成不必细看的管道。
但入口那一层恰好是最容易出错的地方。如果你只是用 Pi,
出问题时你要判断黑屏是网络、认证还是权限;如果你要改 Pi,
main.ts 是你第一个必须读对的文件;如果你要写自己的 agent,
这一段是唯一能照着搬的骨架。
所以第 0 章只做一件事:把这条路径从头走到尾,一站不停。 不切分支,不讲例外,不提另一个 provider,不提 RPC。 遇到岔路只标一句话:那一条去哪章。
八分钟按顺序拆开,是下面这么多站:argv → parseArgs → 模式判定 → 装配 runtime → 造 session → 拿到那一句 → prompt → loop → 拼 payload → HTTP → SSE → 回到 terminal。
这份顺序和 M01 §七 那张九站图是同一件事的两个切面。那边从
UserMessage 开始数到 turn_end,切的是「一轮对话的生命周期」;
这边从 argv 开始数到你屏幕上出现第一个字,切的是「一次进程的启动」。
本章正文按十个站走,再加上第十一站的工具循环,总共十二节。
重叠的只有中间四站:prompt → loop → 拼 payload → 流式回来。
两头各多一截:启动在这里,收尾在那边。两者不冲突,但别混着数。
一、第一站:参数
程序的入口在 packages/coding-agent/src/main.ts。终端里的 pi 是个 bin
包装,真正跑的只有这一句:
// coding-agent/src/main.ts:574export async function main(args: string[], options?: MainOptions) {进来第一件事是判命令。pi login、pi config、pi mcp、pi install
这些是「子命令」,各自在 main.ts 里走各的门口就返回了,不进入会话。
pi "给 config.ts 加一个重试次数" 没有子命令,于是落到参数解析:
// coding-agent/src/main.ts:634const parsed = parseArgs(args);解析器在 cli/args.ts。它不认识「提示词」这个概念,
只把没有 - 前缀的东西当成位置参数:
// coding-agent/src/cli/args.ts:265-266} else if (!arg.startsWith("-")) { result.messages.push(arg);所以那一整句 给 config.ts 加一个重试次数,此刻的身份是
parsed.messages[0]。它是一个字符串数组的一项,
还没有被当成用户的任何意图。
这里有个容易读错的细节:parsed.messages 是多个位置参数,
不是一条消息。引号让 shell 把整句塞进一个 argv 项,所以长度是 1。
不加引号敲 pi 给 config.ts 加一个重试次数,长度就是 4,
Pi 会把它们当成四条独立的消息依序发出去。
这个歧义在 shell 层就产生了,Pi 只是如实按 argv 个数理解。
参数里真正影响这条路径的只有几项:--print(-p)、--mode、
--model、--session-dir。其余几十个开关在这一站只被记录,不被使用。
二、第二站:判定你是「交互」还是「一次性」
Pi 有五套运行形态:交互 TUI、print 文本、JSON 事件流、RPC、SDK。 判定逻辑很短:
// coding-agent/src/main.ts:112-123function resolveAppMode( parsed: Args, stdinIsTTY: boolean, stdoutIsTTY: boolean,): AppMode { if (parsed.mode === "rpc") return "rpc"; if (parsed.mode === "json") return "json"; if (parsed.print || !stdinIsTTY || !stdoutIsTTY) return "print"; return "interactive";}你在终端里直接敲 pi ...,stdin 和 stdout 都是 TTY,
--print 也没给,所以得到 interactive。
这不是无关紧要的分类。它决定了两件后面才会显形的事: 谁来画屏幕,以及第一条消息从哪来。
interactive 走 TUI,屏幕由 tui 包接管,滚动、重绘、光标都归它管;
print 走 runPrintMode,只往 stdout 写字,没有任何屏幕状态。
同一个 AgentSession,外面套的壳不同,行为就完全不同。
此刻还有第二件事要确定:参数里带的那句话, 是「启动时就发出去」,还是「启动后等你再敲」。 答案是前者,但它的落地位置在十几行之后。
三、第三站:装配(这一段最长,也最值得看)
判完模式,main.ts 开始造东西。造的顺序是有讲究的,
因为它沿着一条依赖链从上往下走:
// coding-agent/src/main.ts:606-607const agentDir = getAgentDir();const bootstrapSettingsManager = SettingsManager.create(cwd, agentDir, { projectTrusted: false,});agentDir 是 Pi 自己的家目录,认证令牌、全局设置、会话文件都在这里,
和你的仓库无关。注意 projectTrusted: false:
这一步故意不信任项目。项目里的设置文件(.pi/settings.json)
可能含有 shell 命令,在没用之前不能读。这就是为什么它叫 bootstrap——
它只够用来找会话目录,不够用来跑项目配置。
接着是会话:
// coding-agent/src/main.ts:703-707const sessionDir = (parsed.sessionDir ? normalizePath(parsed.sessionDir) : undefined) ?? (envSessionDir ? expandTildePath(envSessionDir) : undefined) ?? startupSettingsManager.getSessionDir();const sessionManager = await createSessionManager( parsed, cwd, sessionDir, startupSettingsManager,);三条来源依次退化:命令行 → 环境变量 → 设置。
SessionManager 代表的是「这一次对话存在哪」:
它管一个追加写的 JSONL 文件、一个 leafId 指针、
以及把它们读回成消息列表的方法。此刻它还是空的。
真正的重活在一个工厂函数里。main.ts 没有直接 new 出 session,
而是定义一个「怎么造」的闭包,交给 runtime 去调:
// coding-agent/src/main.ts:744const createRuntime: CreateAgentSessionRuntimeFactory = async ({ cwd, agentDir, sessionManager, ...}) => {这个间接层是为了热重载:同一个工厂可以在不重启进程的前提下 再造一个 session(M12 讲这套机制)。在这一章里,它只会被调用一次。
工厂里第一件正事是解析项目信任:
// coding-agent/src/main.ts:757-759const projectTrusted = shouldResolveProjectTrust ? false : (cachedProjectTrust ?? parsed.projectTrustOverride ?? trustStore.get(cwd) ?? !hasTrustRequiringResources);第一次进一个陌生仓库,trustStore 里没有记录,而你又不带 --approve,
所以这里会弹一个确认框问「是否信任这个目录」。你点了「信任」,
值被写进 projectTrustByCwd,后面所有资源都按已信任来加载。
然后是服务层:
// coding-agent/src/main.ts:761const services = await createAgentSessionServices({ ... });它一口气造出四样东西:settingsManager(合好的配置)、
modelRuntime(有哪些模型、认证在哪)、
resourceLoader(读扩展、技能、AGENTS.md),
以及一组 diagnostics(加载过程中攒下的告警)。
四样都到位了,才轮到 session。这里的顺序不可调换: session 需要模型,模型需要认证,认证来自配置。
模型和工具的选择在工厂的后半段:
// coding-agent/src/main.ts:822-825const modelPatterns = parsed.models ?? settingsManager.getEnabledModels();const scopedModels = modelPatterns && modelPatterns.length > 0 ? await resolveModelScope(modelPatterns, modelRuntime, { signal: AbortSignal.timeout(15_000), }) : [];resolveModelScope 是一个 15 秒超时的网络调用。
这解释了启动时那两秒停顿的大部分来源:它要去取模型目录,
确认你选的那个模型名字还有效。
超时设了 15 秒而不是 3 秒,是因为慢网络下的失败比慢更糟—— 宁可多等,也不要误判成「模型不存在」。
工具则是另一个维度:
// coding-agent/src/main.ts:858-860tools: sessionOptions.tools,excludeTools: sessionOptions.excludeTools,noTools: sessionOptions.noTools,三个字段分别对应「明确列出」「从默认里去掉」「一个都不要」。
你没给任何一个,所以走默认:read、bash、edit、write 四个,
外加扩展注册进来的。
四、第四站:造一个 session
工厂的产出交给 runtime,runtime 再把它包成 AgentSessionRuntime:
// coding-agent/src/main.ts:875const runtime = await createAgentSessionRuntime(createRuntime, { cwd: sessionManager.getCwd(), agentDir, sessionManager,});// coding-agent/src/core/agent-session-runtime.ts:429-431assertSessionCwdExists(options.sessionManager, options.cwd);const result = await createRuntime(options);return new AgentSessionRuntime( result.session, result.services, createRuntime, result.diagnostics, ...);一路往下,工厂里最终调用的是 createAgentSession。
这个函数是 SDK 的公共入口,CLI 和外部集成共用它,
所以它写的每一句都同时服务两个读者。它的核心是造一个 Agent:
// coding-agent/src/core/sdk.ts:403-411const agent = new Agent({ initialState: { systemPrompt: "", model, thinkingLevel, tools: [], messages: existingSession.messages, }, convertToLlm: convertToLlmWithBlockImages, streamFn: async (model, context, options) => { ... },四处空白值得看清楚:systemPrompt 是空串、tools 是空数组。
一个刚造出来的 agent 是个空壳子,系统提示和工具都是后来填的。
messages 反而有内容——如果你 --continue 续上一个会话,
历史在这里就进来了。
streamFn 是这一层的接口点:
// coding-agent/src/core/sdk.ts:412-422streamFn: async (model, context, options) => { const requestOptions = buildRequestOptions(options); if (options?.sessionId === sessionManager.getSessionId()) { cacheWarmer.start({ model, context, options: requestOptions }, cacheContextIsCurrent(model)); } return modelRuntime.streamSimple(model, context, requestOptions);},Agent 不需要知道你在用哪个厂家的模型。它只需要一个函数:
给它模型、上下文、选项,它还你一条事件流。
这一行 modelRuntime.streamSimple 是整本书里最重要的接口之一,
M04 整章都在拆它。
Agent 造完,紧接着是会话对象:
// coding-agent/src/core/sdk.ts:455-461const session = new AgentSession({ agent, sessionManager, settingsManager, cwd, scopedModels: options.scopedModels, resourceLoader,Agent 和 AgentSession 不是同一层。Agent 是「循环 + 上下文 + 事件」
这套通用机制,不到 2,600 行;AgentSession 在此之上加了持久化、压缩、
扩展、重试、模型切换,4,480 行。
本章要走的路径全在 Agent 里,AgentSession 负责的是把它接上
真实的磁盘和真实的用户。两层的分工,M03 开头有一张图。
五、第五站:系统提示是这时候才填的
上一站注意到 systemPrompt 是空串。它在 AgentSession 构造时被填上:
// coding-agent/src/core/agent-session.ts:1741-1748private _rebuildSystemPrompt(toolNames: string[]): void { const validToolNames = toolNames .filter((name) => this._toolRegistry.has(name)); const toolSnippets: Record<string, string> = {}; for (const name of this._toolRegistry.keys()) { const snippet = this._toolPromptSnippets.get(name); if (snippet) toolSnippets[name] = snippet; }它做的事是把已经注册的工具反查成提示词:工具的 promptSnippet
和 promptGuidelines 就写在工具定义里,这里只是收拢。
所以系统提示里那句「你可以用 bash 执行命令」不是写死的一段文字,
而是被 bash 工具自己贡献的——工具不在,那句话就自动消失。
拼装本身在 core/system-prompt.ts,产出是分节的结构,
而不是一整块字符串:
// coding-agent/src/core/system-prompt.ts:155-160promptSections.preamble = "You are a coding assistant running inside pi, a coding agent harness. ...";const visibleTools = declaredTools.filter((name) => !!toolSnippets[name]);const tools = visibleTools.length > 0 ? visibleTools.map((name) => `- ${name}: ${toolSnippets[name]}`).join("\n") : "(none)";promptSections.tools = `${tools}\n\nAdditional tools may be available.`;分节这件事不是为了好看。后面每一节会被包成同名标签
(<tools>、<rules>、<cwd>),这样中途某个标签变了,
只需要发一个补丁,不用把整块系统提示重发一遍。这个设计在 M08 展开。
一处具体的规则值得看,因为它体现了「提示词跟着环境走」:
// coding-agent/src/core/system-prompt.ts:110-115addRule( "Use bash or PowerShell for file operations like " + "listing, searching, and finding files",);} else if (hasPowerShell) { addRule( "Use PowerShell for file operations like listing, searching, " + "and finding files", );} else { addRule("Use bash for file operations like ls, rg, find");}你在 Windows 上,系统里有没有 PowerShell, 会改变模型被允许使用哪个 shell。这条规则产生时,模型请求还没发出去。
六、第六站:那一句话落地
回到 main.ts。到这一步为止,parsed.messages[0] 还只是一个字符串。
在启动 TUI 之前,它被交给一个专门的函数:
// coding-agent/src/main.ts:916const { initialMessage, initialImages } = await prepareInitialMessage( parsed, stdinContent,);initialMessage 和 initialImages 分开返回,是因为它们后来的去处不同:
文字进消息内容,图片走另一条处理链(缩放、格式转换,见 M06)。
stdinContent 也存在,那是 echo "..." | pi 的管道输入,本章不涉。
然后是运行形态的分派:
// coding-agent/src/main.ts:962-974} else if (appMode === "interactive") { const interactiveMode = new InteractiveMode(runtime, { migratedProviders, startupDiagnostics, modelFallbackMessage, autoTrustOnReloadCwd, initialMessage, initialImages, initialMessages: parsed.messages, ... });注意 interactiveMode.run() 是在后面才 await 的。构造和运行分开,
是为了让 TUI 能先把屏幕搭好、把终端切到 raw mode,再发第一条消息——
否则模型的第一个字会打在你还没画完的屏幕上。
InteractiveMode 的核心是下面这个循环,它是整个交互形态的骨架:
// coding-agent/src/modes/interactive/interactive-mode.ts:1277-1285while (true) { const userInput = await this.getUserInput(); try { await this.session.prompt(userInput); } catch (error: unknown) { const errorMessage = error instanceof Error ? error.message : "Unknown error occurred"; this.showError(errorMessage); }}一个 while (true),一次 await。你敲一句,它发一句;
你敲下一句,得等这一句彻底结束。
这一点和很多人对 agent 的直觉不同:交互循环本身是严格串行的。
所谓的「边说边改」,靠的是在流式输出期间把新输入塞进队列,
不是并发跑两个 prompt。
启动时带的那句话,走的是同一件事的另一条边:
// coding-agent/src/modes/interactive/interactive-mode.ts:1256-1262if (initialMessage) { try { await this.session.prompt(initialMessage, { images: initialImages }); } catch (error: unknown) { this.showError( error instanceof Error ? error.message : "Unknown error occurred", ); }}在 run() 的开始处,initialMessage 就绪,session.prompt
被调用一次。这就是你回车后那八分钟真正的起点。
七、第七站:从 prompt 到 loop
AgentSession.prompt 有 84 行,但要走的只有一个入口。
前面几段是给扩展和斜杠命令留的闸门:/ 开头先问扩展要不要接管,
扩展输入钩子先过一遍,技能和模板在此展开,流式期间则变成入队。
我们的输入什么都没命中,于是走到:
// coding-agent/src/core/agent-session.ts:2174-2180if (!this.model) { throw new Error(formatNoModelSelectedMessage());}const hasConfiguredAuth = this._modelRuntime.hasConfiguredAuth(this.model.provider) || (await this._modelRuntime.checkAuth(this.model.provider)) !== undefined;程序化地确认两件事:有模型,且这个模型的厂家有可用凭证。 这解释了为什么「没登录」不会在你敲完一大段话之后才告诉你—— 它在发请求之前就抛了。
顺带说一个容易忽略的分工:AgentSession.prompt 检查认证,
但 packages/agent 里的 Agent.prompt 完全不检查。
内核不知道「认证」这个概念,这是上层的事。
内核对下层只要求一件事:streamFn 要么给流,要么抛错。
过闸之后:
// coding-agent/src/core/agent-session.ts:2193await this._startRun({ messageType: "user", prompt: expandedText, images: currentImages });_startRun 准备消息、发出事件,然后交棒给 agent:
// coding-agent/src/core/agent-session.ts:1920-1925await this.agent.prompt(messages);while (!this._agentRunAbortRequested) { if (await this._handlePostAgentRun()) { if (this._agentRunAbortRequested) break; await this.agent.continue(); continue; }这就是「两层循环」里外面那一层。内层在 packages/agent,
外层在这里,外层的职责是处理内层结束后还要不要再来一轮
(重试、压缩后重发、待办消息)。
内核那一层:
// packages/agent/src/agent.ts:382-389async prompt(input: string | AgentMessage | AgentMessage[], images?: ImageContent[]): Promise<void> { if (this.activeRun) { throw new Error("Agent is already processing a prompt. ..."); } const messages = this.normalizePromptInput(input, images); await this.runPromptMessages(messages);}再往下就进入真正的循环:
// packages/agent/src/agent-loop.ts:111-133export async function runAgentLoop( prompts, context, config, emit, signal, streamFn,) { const initialMessages = declareToolChanges(context, prompts); const newMessages: AgentMessage[] = [...initialMessages]; const currentContext = { ...context, messages: [...context.messages, ...initialMessages] }; await emit({ type: "agent_start" }); await emit({ type: "turn_start" }); for (const message of initialMessages) { await emit({ type: "message_start", message }); await emit({ type: "message_end", message }); } await runLoop(currentContext, newMessages, config, signal, emit, streamFn ?? getDefaultStreamFn()); return newMessages;}四行代码里藏着三个决定:新消息进上下文用新的数组
(不改调用方那份),事件在发请求之前就发了
(agent_start 比模型的第一个字节还早),emit 是同步等完的
(上层要能阻塞住循环,这是扩展能拦截工具的前提)。
八、第八站:拼 payload
循环核心在 runLoop,第一次迭代里最关键的一行是:
// packages/agent/src/agent-loop.ts:251const message = await streamAssistantResponse( currentContext, config, signal, emit, streamFunction,);这个函数负责把内部的 AgentMessage[] 翻译成厂商要的 Message[]:
// packages/agent/src/agent-loop.ts:398-406let messages = context.messages;if (config.transformContext) { messages = await config.transformContext(messages, signal);}const llmMessages = await config.convertToLlm(messages);const llmContext = normalizeContext({ messages: llmMessages });三次改写,顺序不能换:扩展先看一遍(transformContext),
再做格式转换(convertToLlm),最后规范化。
扩展看到的是 Pi 的内部消息格式,而不是某个厂商的格式——
这是扩展能跨厂商复用的原因。
转换之后是发请求:
// packages/agent/src/agent-loop.ts:412-417const response = await streamFunction(config.model, llmContext, { ...config, apiKey: resolvedApiKey, identity: mergeClientIdentity(DEFAULT_AGENT_IDENTITY, config.identity), signal,});注意 streamFunction 是同步返回的,返回的是一个流对象而不是 Promise。
真正的 HTTP 请求在流被迭代的时候才发生。
这个细节决定了后面的时序:请求还没发,事件已经在路上了。
流往下走到 AgentSession 给的实现:
// coding-agent/src/core/model-runtime.ts:752-756return lazyStream(model, async () => { assertChatModel(model); const prepared = await this.prepareRequest(model, options); return prepared.provider.streamSimple( prepared.model, transcript, prepared.options as SimpleStreamOptions, );});prepareRequest 是 Pi 和厂商之间那层「十级翻译」的入口
(M04 的主线)。provider.streamSimple 最终落到 packages/ai
里某个具体实现,本章假设是 Anthropic:
// packages/ai/src/api/anthropic-messages.ts:954export const streamSimple: StreamFunction< "anthropic-messages", SimpleStreamOptions> = (到了这一层,请求才真正被构造:
// packages/ai/src/api/anthropic-messages.ts:644-648const requestOptions = { ...(options?.signal ? { signal: options.signal } : {}), ...(options?.timeoutMs !== undefined ? { timeout: options.timeoutMs } : {}), maxRetries: 0,};maxRetries: 0 值得停一下。SDK 自己是能重试的,这里被显式关掉,
因为重试被挪到了上层:
// packages/ai/src/api/anthropic-messages.ts:660-668response = await retryProviderRequest( () => client.beta.messages.create(params, requestOptions).asResponse(), { maxRetries: options?.maxRetries, maxRetryDelayMs: options?.maxRetryDelayMs, signal: options?.signal, },);这一行 asResponse() 是整条路径上唯一一次网络 I/O。
它拿到的是 HTTP 响应头还没读完的响应对象,body 是个 ReadableStream。
到这一刻,八分钟里最不可控的一段开始了。
九、第九站:字节变字
响应回来之后,第一件被推出去的事件是 start:
// packages/ai/src/api/anthropic-messages.ts:692-693await options?.onResponse?.({ status: response.status, headers: headersToRecord(response.headers) }, model);stream.push({ type: "start", partial: output });output 是一个空的 assistant 消息骨架:content: [],
stopReason: "pending",所有计数归零。它先被推出去,再被填充。
所以下游拿到的第一个 assistant 消息是个空壳——这不是 bug,
而是让 UI 可以立刻挂上「正在输出」的组件。
SSE 是逐字节来的。把字节切成事件,是两层生成器:
// packages/ai/src/api/anthropic-messages.ts:481-505const reader = body.getReader();const decoder = new TextDecoder();const state: SseDecoderState = { event: null, data: [], raw: [] };let buffer = "";try { while (true) { if (signal?.aborted) { throw new Error("Request was aborted"); } const { value, done } = await reader.read(); if (done) break; buffer += decoder.decode(value, { stream: true }); let consumed = consumeLine(buffer); while (consumed) { buffer = consumed.rest; const event = decodeSseLine(consumed.line, state); if (event) yield event; consumed = consumeLine(buffer); } }三处细节都是为了「网络不按行来」这件事:TextDecoder 带
stream: true 是因为一个汉字可能被切在两个 chunk 之间;
buffer 保留残余是因为一个 SSE 事件可能横跨多次 read();
while (consumed) 内层循环是因为一次 read() 可能带回几十行。
外层再筛一遍事件类型:
// packages/ai/src/api/anthropic-messages.ts:547-563for await (const sse of iterateSseMessages(response.body, signal)) { if (sse.event === "error") throw new Error(sse.data); if (!ANTHROPIC_MESSAGE_EVENTS.has(sse.event ?? "")) continue; try { const event = parseJsonWithRepair<RawMessageStreamEvent>(sse.data); if (event.type === "message_start") sawMessageStart = true;parseJsonWithRepair 这个名字是这层唯一的妥协:某些厂商会在 JSON
里塞进非法字符,直接 JSON.parse 会整条流崩掉,所以尝试修复一次。
你没遇到过,是因为它在替你兜底。
真正把文本拼起来的地方只有几行:
// packages/ai/src/api/anthropic-messages.ts:771-782} else if (event.type === "content_block_delta") { const open = openBlock(event.index); if (event.delta.type === "text_delta") { if (open?.block.type === "text") { open.block.text += event.delta.text; stream.push({ type: "text_delta", contentIndex: open.contentIndex, delta: event.delta.text, partial: output, }); } }+=。一个增量、一次拼接、一次推送,循环几百次,
屏幕上就是你看到的那段话。
十、第十站:回到你的屏幕
字节已经变成了 text_delta 事件。它要经过两层才到你眼前。
内核这一层把厂商事件翻译成 agent 事件:
// packages/agent/src/agent-loop.ts:442-450if (partialMessage) { partialMessage = event.partial; context.messages[context.messages.length - 1] = partialMessage; await emit({ type: "message_update", assistantMessageEvent: event, message: { ...partialMessage }, });}这里有个容易滑过去的动作:context.messages[...] = partialMessage。
流式期间,插在上下文末尾的那条 assistant 消息每一帧都被替换。
如果此时有人读到 agent.state.messages,他拿到的是半成品。
这是事件机制的前提,也是 F10 与附录 E 里几条裂缝的共同源头之一。
事件往上,AgentSession 只做一件事:落盘。
// coding-agent/src/core/agent-session.ts:1163-1182if (event.type === "message_end") { let entryId: string | undefined; if (event.message.role === "custom") { entryId = this.sessionManager.appendCustomMessageEntry( event.message.customType, event.message.content, event.message.display, event.message.details, ); } else if ( event.message.role === "system" || event.message.role === "user" || event.message.role === "assistant" || event.message.role === "toolResult" ) { entryId = this.sessionManager.appendMessage(event.message); }只在 message_end 落盘——不是 message_update。所以「流到一半崩溃,
历史里有没有这半句话」的答案是:没有。这是刻意的,M10 有一节专门算这笔账。
落盘是同步追加:
// coding-agent/src/core/session-manager.ts:1187appendFileSync(this.sessionFile, `${JSON.stringify(entry)}\n`);一行 JSONL,一次 appendFileSync。没有缓冲,没有批量,没有事务。
一条消息写完就真的在盘上了,代价是每条消息一次系统调用。
最后一层是 UI:
// coding-agent/src/modes/interactive/interactive-mode.ts:3585-3588case "message_update": if (this.streamingComponent && event.message.role === "assistant") { this.streamingMessage = event.message; this.streamingComponent.updateContent(this.streamingMessage, true);它没有「追加文本」,而是整条消息重新渲染。updateContent
的第二个参数 true 表示还在流式,组件据此跳过一部分代价高的处理
(比如完整的 markdown 解析)。最后落到重绘调度:
// packages/tui/src/tui.ts:1067-1073private scheduleRender(): void { if (this.stopped || this.renderTimer || !this.renderRequested) { return; } const elapsed = performance.now() - this.lastRenderAt; const delay = Math.max(0, TuiBase.MIN_RENDER_INTERVAL_MS - elapsed);MIN_RENDER_INTERVAL_MS 是 16。60 帧每秒。
到这里,路径走完了。第一行字出现在你屏幕上的那一刻,Pi 一共做了这些事: 读 argv、判模式、装配服务和会话、拼系统提示、过认证、进两层循环、 把内部消息翻译成厂商格式、发一次 HTTP、解析 SSE、把字节拼成字符串、 发事件、写 JSONL、重绘屏幕。
十一、八分钟的另一半:工具
上面的路径只解释到「模型说了第一句话」。真正的八分钟里, 模型说完话之后还要读文件、改代码、跑测试。这一段不在本章展开, 因为它的每条边都会引出分支,但主干只有一条:
// packages/agent/src/agent-loop.ts:268-279const toolCalls = message.content.filter((c) => c.type === "toolCall");const toolResults: ToolResultMessage[] = [];hasMoreToolCalls = false;if (toolCalls.length > 0) { const executedToolBatch = message.stopReason === "length" ? await failToolCallsFromTruncatedMessage(toolCalls, emit) : await executeToolCalls(currentContext, message, config, signal, emit);模型吐出 toolCall,循环执行它,把结果塞回上下文,
然后再发一次请求。这就是「内层循环」:一次用户消息对应 N 次模型请求。
上文那一句「说的第一句话」,其实是第 1 次请求的产物;
读到文件之后的第二句话,是第 2 次请求的产物。
八分钟里你看到的是一段连续的对话,机器这边是七次独立的 HTTP 请求, 每次都带着更长一点的上下文。这是理解 agent 成本曲线最直接的方式, M09 会把它算成钱。
十二、这一章漏掉了什么,去哪里补
本章是一条直路。现实里每一步都有分叉,下面这张表把它们对到章节:
| 你可能想知道的 | 去哪 |
|---|---|
| 为什么 loop 有两层,各自边界在哪 | M03 |
| 那「十级翻译」具体是哪十级 | M04 |
| 工具的参数校验、并发、中止怎么做 | M05 |
AgentMessage 和厂商 Message 有什么区别 |
M06 |
| 十九种事件什么时候发,谁订阅 | M07 |
| 系统提示怎么分节、怎么增量更新 | M08 |
| 上下文快满了,先截断还是先摘要 | M09 |
| 这个 JSONL 会话文件长什么样、怎么恢复 | M10 |
崩溃之后怎么接着跑(durable) |
M11 |
改代码怎么不重启(chord) |
M12 |
| MCP 和 codemode 是什么 | M13 |
| 屏幕上那些块、卡片、表格是怎么画的 | M14 |
| 一份工具声明为什么要给五个读者看 | M15 |
| 十个包的体积和依赖 | M02 |
| 只想改配置、写扩展,不想读源码 | F01–F10 |
| 照着造一个自己的 agent | E01–E08 |
| 换一个模型商要动哪几行 | 附录 A |
| 包成一个 HTTP 服务 | 附录 C |
| Pi 自己没修干净的坑 | 附录 E |
读这张表的正确姿势是:先在脑子里留一条完整的直路,再回头补分叉。 反过来做,你会读到一个由四十个特例拼起来的框架, 每个特例都对,合起来不知道在干什么。
十三、源码索引
本章只用到五个文件。行数是 split(/\r?\n/).length 口径,
和全书其它章一致(wc -l 会少算 1)。
| 文件 | 行数 | 本章用到的地方 |
|---|---|---|
coding-agent/src/main.ts |
1,011 | 入口 :574、解析 :634、装配 :744 |
coding-agent/src/cli/args.ts |
481 | 位置参数 :265-266 |
coding-agent/src/core/sdk.ts |
482 | new Agent :403-411 |
agent/src/agent-loop.ts |
960 | 外壳 :111-133、请求 :398-417 |
ai/src/api/anthropic-messages.ts |
1,687 | SSE 解码 :481-534 |
coding-agent/src/cli/initial-message.ts |
44 | 拼第一句 :34-37 |
AgentSession(4,480 行)与 interactive-mode.ts(7,212 行)只在
第五站和第十站各露一行,读它们的时机在 M03 与 M14。
十四、本章小结
三句话:
- 一句提示词从 argv 到屏幕,中间没有魔法,只有十站可以被逐行指认的代码。
- 交互循环是串行的;「边聊边干」靠队列,不靠并发。
- 一次用户消息对应 N 次模型请求,N 由工具调用决定—— 这就是 agent 和聊天机器人的全部差别。
刚才那条路,你已经能在脑子里从头到尾走一遍了。但它脚下踩的是 十几个文件,而这些文件属于十二个包中的一个。
接下来 M01 回答的是下一个问题:这一条路为什么会散在这么多包里? 每条边值多少行?哪一块你不必读。它不重复这条路径,它给这条路径称重。