从 pi-main 源码拆解:顶尖 AI Agent 的工程设计(17 维度全解)

如果让你从零写一个 AI Coding Agent，你会怎么设计核心循环？怎么处理上下文爆炸？怎么让人类在关键时刻踩一脚刹车？

pi（一个开源的 AI 编程引擎）用不到 5000 行核心代码回答了这些问题。它的代码不是最漂亮的，但它的工程决策异常扎实——17 个维度的设计选择，每一条都踩过坑。

今天我把这 17 个维度全部拆开讲，给你一张可直接照抄的 Agent 设计清单。

一、任务规划：单体还是多体，这是个伪命题

很多人一上来就纠结要不要做 Planner，要不要做 Router，要不要上多 Agent 架构。pi 告诉你：不要。

pi 默认是单体 ReAct Agent，没有内置的 Planner/Router 节点。它的任务规划能力是通过 Extension API 开放的——如果你想让 Agent 调用子 Agent，你把"调用子 Agent"这件事封装成一个普通工具，插进工具列表，剩下的交给 LLM 自己决定什么时候用。

这不是偷懒，这是最小化设计。多 Agent 协作带来的复杂度爆炸是真实存在的，在你没有 100% 搞清楚单 Agent 的边界在哪之前，不要用多 Agent 给自己挖坑。

抄什么：前期做单体，预留"能注册新工具的扩展口"。等单 Agent 实在 hold 不住了，再上多 Agent。

二、核心主循环：双层 while 里的工程美学

先看代码：

while (true) { // 外层：等待 followUp，维持会话let hasMoreToolCalls = true;while (hasMoreToolCalls || pendingMessages.length > 0) { // 内层：ReAct 闭环if (pendingMessages.length > 0) {      currentContext.messages.push(...pendingMessages); // 注入 Steering 消息      pendingMessages = [];    }const message = awaitstreamAssistantResponse(...);const toolCalls = message.content.filter(c => c.type === "toolCall");const executedToolBatch = awaitexecuteToolCalls(...);    hasMoreToolCalls = !executedToolBatch.terminate; // 工具可主动喊停  }const followUpMessages = await config.getFollowUpMessages?.() ?? [];if (followUpMessages.length === 0) break; // 无后续则退出会话  pendingMessages = followUpMessages;}

双层 while 不是炫技。外层解决的是"会话什么时候真正结束"，内层解决的是"这一轮 ReAct 什么时候做完"，两个退出条件分离，逻辑就干净了。

最容易被忽视的细节：terminate 信号。工具执行完后可以返回 terminate=true，告诉引擎"别再调模型了，这一轮到此为止"。这比让 LLM 自己输出"done"要可靠 100 倍——LLM 的 done 识别错误率在复杂任务里高得吓人。

抄什么：双层分离 + terminate 信号，这是做 HITL 的最小化模板。

三、反思与自我纠错：别急着写 Critic Agent

很多人觉得 Agent 要有自我纠错能力，就得写一个 Critic Agent 专门挑错。pi 告诉你：不必须。

pi 的纠错机制藏在统一返回结构里：

try {const result = await prepared.tool.execute(...);return { result, isError: false };} catch (error) {return {result: { content: [{ type: "text", text: String(error) }], details: {} },isError: true, // LLM 看到这个标志，会自动触发重试推理  };}

工具的"成功"和"失败"都是数据。LLM 在 ReAct 循环里看到 isError: true 或者 text 里包含 Error，会自动触发反思："刚才哪一步出问题了？我怎么修？"——这是 LLM 自己的推理能力在驱动纠错，不需要额外的 Critic。

抄什么：统一 { content, isError } 返回格式，这是最低成本的自修复方案。

四、工具系统：三件事决定 Agent 体验上限

第一件事：Schema 用 TypeBox，不是 if-else。

const bashSchema = Type.Object({command: Type.String({ description: "Bash command to execute" }),timeout: Type.Optional(Type.Number()),});

声明式 Schema 的好处是：参数校验是自动化的，工具文档是自描述的，LLM 拿到工具列表就知道怎么用。

第二件事：大输出必须截断，附上 Temp 文件路径。

Agent 的上下文窗口是有限的，当一个命令输出几 MB 时，必须截断。但截断不等于丢失信息：

text += `\n\n[Showing lines ${start}-${end} of ${total}. Full output: ${fullOutputPath}]`;

LLM 知道完整的在哪，如果它真的需要，可以再用 read 工具去读。这是防爆炸 + 保可追溯的标准操作。

第三件事：并行还是串行，让工具自己声明。

const hasSequentialTool = toolCalls.some(tc => tool.executionMode === "sequential");if (hasSequentialTool) returnexecuteToolCallsSequential(...);returnexecuteToolCallsParallel(...);

每个工具声明自己的 executionMode，引擎自动判断这一批工具调用应该并行还是串行。设计良好的工具集里，大多数可以并行，只有少数有状态依赖的必须串行。

抄什么：TypeBox Schema + 大输出截断 + executionMode 字段，这三样是工具系统的最小必要集合。

五、输出格式：Provider 原生 Function Calling 的局限

pi 在输出解析上完全信任 Provider 原生 Function Calling，没有额外的 Schema 校验层。

这意味着：主流模型（Claude GPT-4）足够稳定，但如果接入国产小模型，这里会成为故障点——小模型的 Function Calling 格式经常飘，参数填错位是常态。

pi 的参数校验失败后走 isError 路径，LLM 会重试。但重试几次能修好，取决于模型本身的能力。

抄什么：如果只用大厂模型，原生 Function Calling 够用；如果要兼容小模型，在 validateToolArguments 前面加一层宽松解析（从自然语言中提取 JSON 意图）。

六、记忆与上下文压缩：被严重低估的设计

pi 的记忆系统分两层：JSONL 事件流 + 结构化压缩摘要。

事件流是 append-only 的 JSONL，每行一个事件（message / model_change / compaction 等）。崩溃不丢数据，天然支持回放和分支，会话重放时模型上下文完全一致。这是工程上最可靠的持久化方式。

压缩摘要才是精髓。触发条件：

return contextTokens > contextWindow - settings.reserveTokens; // 默认留 16384 Token

触发后不是简单截断，而是强制结构化提取：

## Goal / ## Constraints## Progress (Done + InProgress + Blocked)## Key Decisions / ## Next Steps / ## Critical Context

注意 Progress 分三种状态：Done / InProgress / Blocked。这是让 LLM 持续跟踪任务状态的视觉锚点，比让它自己自由发挥要稳定得多。

更精妙的是迭代更新逻辑：

const basePrompt = previousSummary ? UPDATE_SUMMARIZATION_PROMPT : SUMMARIZATION_PROMPT;promptText += `<previous-summary>\n${previousSummary}\n</previous-summary>`;

有旧摘要用 UPDATE prompt，保留历史信息；没旧摘要用全量 SUMMARIZATION prompt。实测迭代更新比全量重写节省 50%+ Token。

抄什么：JSONL 事件流 + 结构化摘要格式 + 迭代更新逻辑，这是记忆系统的最佳实践。

七、状态管理与会话分支：JSONL 的工程魅力

pi 的会话以 JSONL 格式持久化，每行是一个独立事件。这种格式有三个好处：

追加写入
，崩溃不丢数据
天然支持回放
，从头读到尾就是完整会话
支持分支
，从任意历史节点 rehydrate 出来就是新分支

分支时会产生 BranchSummaryMessage：

exportinterfaceBranchSummaryMessage {role: "branchSummary";summary: string;fromId: string;    // 记录分支来自哪个历史节点timestamp: number;}

这是做"实验性探索"的工程基础——让 Agent 尝试一个方向，失败了可以回到主分支重来，而不用重来整个会话。

抄什么：会话存 JSONL，不要存 JSON 数组。append-only 的设计是工程可靠性的基石。

八、人机协同：异步方向盘的正确姿势

很多 Agent 做 HITL 就是弹框让用户点"继续"或"终止"，然后主循环被卡住。pi 的做法完全不一样：消息异步注入，不阻塞主循环。

asyncsteer(text: string): Promise<void> {this.agent.steer({ role: "user", content: [{ type: "text", text }] });}

消息被塞进 pendingMessages，主循环在当前 tool call 执行完毕后自动 pickup，继续运行。用户感知上就是"我发了条消息，Agent 立刻响应"，而不是"我点了继续 Agent 才动"。

停止也是异步的，靠 AbortController：

signal.addEventListener("abort", () => {if (child.pid) killProcessTree(child.pid); // 连根拔起}, { once: true });

关键：AbortController 从顶层 Session 一路透传到最底层工具，不是层层封装，是直接传递引用。这样停止信号才能真正生效，不会出现"主循环停了但子进程还在跑"的尴尬。

抄什么：steer 是异步的，AbortController 必须透传到底层。这两件事做对了，HITL 就对了一半。

九、提示词结构：时空锚点是零成本的防幻觉

pi 的 system prompt 分区非常清晰：

Available tools: ${toolsList}     // 仅列出已启用的工具Guidelines: ${guidelines}         // 规则随工具动态生成Current date: ${date}             // 时空锚点，防幻觉Current working directory: ${cwd}

最容易忽视的是时空锚点——"Current date"和"Current working directory"。LLM 在没有时间锚点的情况下容易产生时间幻觉（比如把昨天的 bug 当成今天的 bug），加上时间戳之后幻觉率显著下降。这是零成本的优化，但很多人不做。

Guidelines 随工具动态生成意味着：禁用了某个工具，对应的规则也从 prompt 里消失，LLM 不会被无效规则干扰。

抄什么：时空锚点必须加，Guidelines 必须按工具动态生成。

十、提示词动态组装：Skill 命令是提效利器

pi 支持一种叫 Skill 的机制：用户在输入框里敲 /skill:debug，系统自动展开为对应的 Prompt 模板。

let expandedText = this._expandSkillCommand(text); // /skill:debug → 读取文件内容expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);// 展开后包裹在 XML 标签中传给 LLM// <skill name="debug" location="/path/to/skill.md">...</skill>

这让用户的输入成本大幅降低，同时保证了 Prompt 的标准化——不用每次都复制粘贴一长串提示词，敲一个斜杠命令就搞定了。

抄什么：Skill/模板系统是降低用户输入成本、提升 Prompt 标准化的关键机制，值得投入。

十一、多模态支持：优雅降级比报错更重要

pi 的 read 工具原生支持图片：

if (!model || model.input.includes("image")) {const resized = awaitresizeImage({ type: "image", data: base64, mimeType });return [{ type: "image", data: resized.data, mimeType: resized.mimeType }];}return"[Current model does not support images. The image will be omitted.]";

两个关键细节：

自动 resize
：图片缩放到 2000x2000 以内再输入，防止上下文爆炸
优雅降级
：不支持图片的模型返回提示文本，而不是报错，Agent 继续运行不受影响

抄什么：图片必须检查 model.input.includes("image")，不支持就降级，不报错。

十二、模型路由：中途热切换的秘密

pi 支持在对话中途热切换模型，不需要重启会话：

this.sessionManager.appendModelChange(model.provider, model.id); // 写入事件流this.settingsManager.setDefaultModelAndProvider(model.provider, model.id);

模型切换事件会写入 JSONL，确保重放时模型上下文一致。

还有一个关键细节：自动重试逻辑。当 LLM 返回特定错误时，自动重试：

return/overloaded|rate.?limit|429|500|502|503|504|timeout/i.test(errorMsg);

这个正则覆盖了所有常见的服务端错误，重试策略是指数退避还是立即重试，可以按需配置。

抄什么：模型切换写入事件流，确保重放一致性；错误重试正则要覆盖全。

十三、安全与权限：pi 最大的设计缺口

pi 在安全上是有明显短板的。

它有进程树清理——当 AbortSignal 触发时，整个进程树被连根拔起，不会留孤儿进程。它有超时保护——命令执行超过 timeout 直接抛错。

但它没有：

文件路径 Jail（Agent 理论上可以操作任意目录）
命令白名单/黑名单（rm -rf / 这种危险命令没有拦截）
敏感信息脱敏（API Key 等不会自动过滤）

pi 的安全策略是：依赖沙盒执行环境（Docker/容器）或用户自律。这不是工程失误，是设计选择——把安全责任交给基础设施层，引擎本身不做过多假设。

抄什么：如果你的 Agent 要在生产环境跑，bash 工具层必须加 allowedPaths 校验，禁止操作敏感目录。引擎不做假设，基础设施来兜底。

十四、可观测性：JSONL 是基础，结构化才是目标

pi 的可观测性停留在 JSONL 回放阶段，没有 OTEL，没有结构化成本追踪。

JSONL 事件流可以完整回放一次会话，这是好的。但每次 LLM 调用花了多少 Token、多少钱，是黑盒。

exportfunctioncalculateContextTokens(usage: Usage): number {return usage.totalTokens || usage.input + usage.output + cacheRead + cacheWrite;}

Token 有计算，但没有格式化输出到日志或 UI。开发者在调试时不知道一次对话烧了多少钱，这是真实的需求缺口。

抄什么：即使不上 OTEL，也要每次 LLM 响应后计算并展示费用，格式化为 {model, inputTokens, outputTokens, cost}，写入日志文件。

十五、扩展性：两个钩子定义了整个插件系统

pi 的 Extension API 核心只有两个生命周期钩子：

beforeToolCall: async ({ toolCall, args }) => {returnawait runner.emitToolCall({ toolName: toolCall.name, input: args });},afterToolCall: async ({ toolCall, result, isError }) => {returnawait runner.emitToolResult({ toolName: toolCall.name, content: result.content, isError });}

beforeToolCall
：工具审批的插入点。想让 LLM 调用危险命令前先过审批？在这里拦截。
afterToolCall
：结果二次处理的插入点。想让输出自动脱敏？想对结果做额外验证？在这里处理。

SubAgent 模式（调用子 Agent）就是通过这两个钩子封装成普通工具来实现的，不是核心引擎内置，是插件自己扩展的。这验证了"轻核心、重扩展"的设计哲学。

抄什么：beforeToolCall + afterToolCall 是插件系统的最小必要集合，值得投入。

十六、评估体系：pi 最致命的短板

整个 pi 代码库里，找不到自动化 Evals，没有 Golden Set，没有回归测试框架。

这不是小问题。每一次改 Prompt，都有可能是改对了，也可能是改错了但测试恰好过了。没有 Golden Set，你根本不知道。

10-20 个黄金用例（一个任务 + 期望的工具调用序列）是用最低成本防止退化的方案。很多人觉得"我们团队小，不需要 Evals"，实际上是"没有 Evals，每次 prompt 改动都是赌博"。

抄什么：从第一天起建立 Golden Set，哪怕只有 10 条。这件事越早做越低成本，越晚做越要命。

十七、成本控制：压缩是核心，其他靠估算

pi 的成本控制主要靠自动上下文压缩：

exportconstDEFAULT_COMPACTION_SETTINGS: {enabled: true,reserveTokens: 16384,   // 模型上下文窗口保留 16K Token 空间keepRecentTokens: 20000, // 压缩后保留最近 20K Token 历史}

reserveTokens 是触发压缩的阈值，keepRecentTokens 是压缩后保留的历史长度。这两个参数配合，确保上下文永远不会爆炸。

但 Token 消耗的精确估算和展示是缺失的。cacheRead 和 cacheWrite 有记录，但没有换算成美元/人民币展示给用户。对于需要控制成本的项目来说，这是真实痛点。

抄什么：参考 pi 的压缩策略作为成本控制核心；补充每次 LLM 响应后计算费用 (inputTokens * price + outputTokens * price) 并展示。

总结：一张可直接照抄的 Agent 设计清单

维度	推荐做法	优先级
核心循环	双层 while + terminate 信号	⭐⭐⭐⭐⭐
错误处理	统一 `{ content, isError }` 返回	⭐⭐⭐⭐⭐
记忆系统	JSONL 事件流 + 结构化摘要	⭐⭐⭐⭐⭐
工具系统	TypeBox Schema + 输出截断 + executionMode	⭐⭐⭐⭐⭐
人机协同	异步方向盘 + AbortController 透传	⭐⭐⭐⭐⭐
会话管理	JSONL 持久化 + Branch 支持	⭐⭐⭐⭐⭐
Prompt 结构	时空锚点 + 动态 Guidelines	⭐⭐⭐⭐
插件系统	beforeToolCall + afterToolCall	⭐⭐⭐⭐
多模态	自动 resize + 优雅降级	⭐⭐⭐⭐
模型路由	中途热切换 + 事件流记录	⭐⭐⭐⭐
任务规划	单体 Agent + Extension 扩展口	⭐⭐⭐
输出解析	主流模型够用，兼容小模型需加容错层	⭐⭐⭐
安全边界	生产环境加路径白名单校验	⭐⭐⭐
可观测性	JSONL 回放 + 费用估算展示	⭐⭐⭐
成本控制	自动压缩 + Token 费用展示	⭐⭐⭐
评估体系	建立 Golden Set	⭐⭐⭐
成本控制	—	⭐⭐

pi 的设计哲学很简单：轻核心、重扩展。核心引擎只做最小必要的事情，复杂能力通过 Extension API 交给插件。

这不是偷懒，这是工程上最聪明的取舍。把核心做轻，稳定性才有保障；把扩展口留足，未来演进不需要重构。