想象一个再普通不过的瞬间

你打开终端，敲下 pi，按下回车，输入："帮我把 README 翻译成中文"。

三秒钟后，AI 开始流式输出。代码被读取、被改写、被保存。一切自然得像魔法。

但魔法是骗人的。在那短短三秒里，你的 12 个字翻越了至少 5 道关卡。本课的目标是：把每一道关卡拆给你看。

本课的"解剖对象"

我们要拆的是 monorepo pi-mono（github.com/badlogic/pi-mono）—— 一个开源 AI 编程 Agent。

启动那一刻：5 个角色集合

当你敲 pi 回车的瞬间，pi 内部有一段类似这样的"开机自检"对话发生：

系统 prompt 是"现拼出来"的

大多数人以为系统提示词是一段写死的文字。其实在 pi 里，它是每次启动时，根据你当前项目动态拼接的。

let prompt = `You are an expert coding assistant operating inside pi,
a coding agent harness. You help users by reading files,
executing commands, editing code, and writing new files.

Available tools:
${toolsList}

Guidelines:
${guidelines}

Pi documentation (read only when the user asks about pi itself):
- Main documentation: ${readmePath}
- Additional docs: ${docsPath}`;

完整旅程：5 步看清一次对话

把上面所有片段串起来——你的一句话从输入到 AI 改完代码，要走这条路：

先测一下你的"地图意识"

下面 3 题不是考你记忆，是让你试着用刚才学的"5 角色 + Agent 循环"去推理新场景。错了也别气馁——每题的解释会教你新东西。

乐队是怎么排兵布阵的

把 pi 看作一支摇滚乐队。一首歌好听，不靠主唱一个人——靠分工：

贝斯打底（pi-ai 抗住所有 LLM 协议）、鼓手稳节奏（pi-agent-core 控制 Agent 循环）、主唱站台前（pi-coding-agent 是用户能看到的命令）、键盘手做特效（pi-tui 让终端流畅）、客串歌手（pi-web-ui 把同样的戏搬到浏览器）。

五张身份证

每个包都能 npm install 单独使用，下面是它们的"身份证"：

谁依赖谁？

这是 pi 内部的"乐队站位图"——上层依赖下层，下层不知道上层存在：

包之间的"自我介绍"

把 5 个包拟人化，让它们各自出来说一句：

真实代码：上层怎么用下层

不只是嘴上说"依赖"——下面是 pi-agent-core 真实代码的第一行，从 pi-ai 拿走它需要的所有类型：

import {
	type ImageContent,
	type Message,
	type Model,
	type SimpleStreamOptions,
	streamSimple,
	type TextContent,
	type ThinkingBudgets,
	type Transport,
} from "@mariozechner/pi-ai";
import { runAgentLoop } from "./agent-loop.js";

用"分层意识"拆 3 个真实场景

"换模型"为什么这么难？

大多数项目第一次"从 GPT-4 换 Claude"要花一周。原因：每家 LLM 服务商有自己的 API 协议——OpenAI 用 Chat Completions、Anthropic 用 Messages、Google 用 Generative AI、Bedrock 用 Converse……

每换一家，HTTP 请求格式、流式响应格式、工具调用语法都得重写。

pi-ai 把这件事变成一行代码：

// 用 OpenAI
const model = getModel('openai', 'gpt-4o-mini');

// 换成 Claude——只改 2 个字符串
const model = getModel('anthropic', 'claude-sonnet-4');

// 后面所有调用代码完全不变
const response = await complete(model, context);

11 种标准事件 = 一切的语言

不管底下是哪家服务商，pi-ai 最终只吐出 11 种事件。掌握这 11 种，你就掌握了 LLM 应用的 80% 脉搏：

"统一 API"的真相：7 行代码

你可能以为 stream() 函数内部有几千行复杂逻辑。打开源码，结果：

export function stream<TApi extends Api>(
	model: Model<TApi>,
	context: Context,
	options?: ProviderStreamOptions,
): AssistantMessageEventStream {
	const provider = resolveApiProvider(model.api);
	return provider.stream(model, context, options as StreamOptions);
}

一次调用的 6 步旅程

看一下 stream() 调用 Anthropic 时，事件是怎么"翻译"的：

惊艳的招数：跨模型接力对话

pi-ai 还有一招让人拍大腿的——你可以聊到一半换模型，对话不丢：

const claude = getModel('anthropic', 'claude-sonnet-4-20250514');
const context: Context = { messages: [] };

context.messages.push({ role: 'user', content: 'What is 25 * 18?' });
const claudeResponse = await complete(claude, context, {
  thinkingEnabled: true
});
context.messages.push(claudeResponse);

// 换 GPT-5——上下文里的 Claude 思考块自动转成文字
const gpt5 = getModel('openai', 'gpt-5-mini');
context.messages.push({ role: 'user', content: 'Is that calculation correct?' });
const gptResponse = await complete(gpt5, context);

pi-ai 的 4 个秘诀

用"统一 API"思维拆 3 个场景

手术室里发生的事

你跟 Cursor 说"帮我重构这个文件"，AI 不是一口气写完——它read 一下、write 一下、再 read、再 edit、再 bash、再问你一句。这一连串动作背后只有一件事：Agent 循环。

把它想成手术室：模型是主刀医生（"我现在需要 read 这个文件 / 现在需要 write 那段代码"），Agent 循环是器械护士（递工具、收回器械、记录每一步、随时听主刀的下一句话）。

循环的真身：一段简单的伪代码

真实代码 700 多行（在 packages/agent/src/agent-loop.ts 里），但骨架就是这样的：

while (true) {
  let hasMoreToolCalls = true;

  while (hasMoreToolCalls || pendingMessages.length > 0) {
    // 1) 把"打断消息"插进上下文
    if (pendingMessages.length > 0) {
      for (const message of pendingMessages) {
        currentContext.messages.push(message);
      }
      pendingMessages = [];
    }

    // 2) 调一次 LLM，拿到模型回复
    const message = await streamAssistantResponse(currentContext, ...);

    // 3) 看模型有没有调用工具
    const toolCalls = message.content.filter((c) => c.type === "toolCall");

    hasMoreToolCalls = false;
    if (toolCalls.length > 0) {
      const batch = await executeToolCalls(currentContext, message, ...);
      hasMoreToolCalls = !batch.terminate;
    }

    // 4) 用户在工具运行时按 Enter 插的话——steering
    pendingMessages = (await config.getSteeringMessages?.()) || [];
  }

  // 5) 看用户排队的下一句话——follow-up
  const followUp = (await config.getFollowUpMessages?.()) || [];
  if (followUp.length > 0) { pendingMessages = followUp; continue; }
  break;
}

"工具"长什么样：三件套

每一个工具就是一个对象，由三件套组成：名字 + 参数 schema + execute 函数。下面是 read_file 工具的真实定义：

const readFileTool: AgentTool = {
  name: "read_file",
  label: "Read File",
  description: "Read a file's contents",
  parameters: Type.Object({
    path: Type.String({ description: "File path" }),
  }),
  executionMode: "sequential",
  execute: async (toolCallId, params, signal, onUpdate) => {
    const content = await fs.readFile(params.path, "utf-8");

    onUpdate?.({ content: [{ type: "text", text: "Reading..." }] });

    return {
      content: [{ type: "text", text: content }],
      details: { path: params.path, size: content.length },
    };
  },
};

手术室对话现场

把"模型主刀 + Agent 循环护士"拟人化，看一台典型的"读文件 → 改文件"手术：

三种"插队"方式

Agent 循环的厉害不只是基础结构，还在于打断 / 排队 / 拦截三种插队机制：

练 4 个真实调试场景

你见过会闪的命令行吗？

大多数老式终端工具刷新整屏时——文字会跳一下，光标会乱蹦，上面的内容会被滚走。pi 不会。它能在 80 列宽的终端里画 Markdown、彩色 diff、流式打字机效果，全程不闪烁。

秘密只有 80 行 JavaScript 的差分算法。

差分算法的"心脏"

下面是 pi-tui 真实代码（packages/tui/src/tui.ts 第 985-1014 行），找出"哪几行变了"的核心逻辑：

// Find first and last changed lines
let firstChanged = -1;
let lastChanged = -1;
const maxLines = Math.max(newLines.length, this.previousLines.length);

for (let i = 0; i < maxLines; i++) {
  const oldLine = i < this.previousLines.length ? this.previousLines[i] : "";
  const newLine = i < newLines.length ? newLines[i] : "";

  if (oldLine !== newLine) {
    if (firstChanged === -1) {
      firstChanged = i;
    }
    lastChanged = i;
  }
}

// No changes - just update cursor and exit
if (firstChanged === -1) {
  this.positionHardwareCursor(cursorPos, newLines.length);
  return;
}

第二个秘密：同步输出协议

找到要刷新的行只是一半。另一半是怎么把指令发给终端，让它一次性刷新而不是边发边画。pi-tui 用了一个鲜为人知的终端协议——CSI 2026：

let buffer = "\x1b[?2026h"; // 开启同步输出

// ...这里拼一堆"移动光标 / 清除一行 / 写新内容"的 ANSI 指令...
buffer += "\x1b[10;1H";     // 移到第 10 行第 1 列
buffer += "\x1b[2K";       // 清除整行
buffer += "新内容";          // 写新内容

buffer += "\x1b[?2026l"; // 关闭同步输出 = 一次性刷新
this.terminal.write(buffer);

翻译成大白话：\x1b[?2026h 是"终端，从这一刻起先别画了，把我后面发的所有指令统一处理"。中间不管发多少 ANSI 转义序列（移动 / 清除 / 写入），终端都暂存。\x1b[?2026l 是"好了，可以画了，一次性刷新"。

没有这一对包装：用户会看到屏幕一格一格地刷新（闪烁感）。包了之后：所有变化一帧出现，视觉上就是 GUI 的丝滑感。

看一个真实例子：三种渲染策略

同样一段终端输出"loading..."变"done"，pi-tui 会根据情况选不同策略：

$ pi --print "hello"
[模型启动…]
读取 README.md…
loading...

[终端窗口被拖大了！宽度从 80 变成 120]
$ pi --print "hello"
[模型启动…]
读取 README.md…
loading...

$ pi --print "hello"     ← 不动
[模型启动…]              ← 不动
读取 README.md…          ← 不动
done ✓                   ← 只重画这一行

极简工具集：4 件做天下

pi 默认只给模型 4 个工具。看似少，组合起来威力惊人：

极简到震撼：bash 工具的全部参数

你以为"能执行任意命令"的工具会有几十个参数？看 pi 实际的 bash schema：

const bashSchema = Type.Object({
  command: Type.String({
    description: "Bash command to execute"
  }),
  timeout: Type.Optional(Type.Number({
    description: "Timeout in seconds (optional, no default timeout)"
  })),
});

3 题检验你的"终端工程"思维

"我刚才那个分支思路其实是对的"

你和 AI 聊了 2 小时，准备 commit。突然想：30 分钟前那个分支思路其实更好。

普通工具：完蛋，得重打。

pi：/tree → 选 30 分钟前那条 → 从那里继续 —— 历史一根都没丢。

秘密：会话存成"树状 JSONL"

大多数聊天工具把会话存成一根线（一条消息接一条）。pi 不一样——它把每条消息存成带父节点的节点，整体是一棵树：

// session-2024-05-05-abc.jsonl 文件内部
{"id":"m1","parentId":null,"role":"user","content":"重构这个文件"}
{"id":"m2","parentId":"m1","role":"assistant","content":"先 read 一下..."}
{"id":"m3","parentId":"m2","role":"toolResult","content":"..."}
{"id":"m4","parentId":"m3","role":"assistant","content":"我用方案 A"}
// 你回到 m3，从这里开新分支
{"id":"m5","parentId":"m3","role":"assistant","content":"我用方案 B"}
{"id":"m6","parentId":"m5","role":"toolResult","content":"..."}

/tree 操作现场

看一下用户怎么"穿越回过去"：

长对话工具箱：4 件武器

扩展点：给 pi 装上自己的能力

pi 的另一个工程巧思——你不需要 fork pi 改源码，就能加新工具、新命令、新 UI。一个 extension = 一个 TypeScript 文件：

export default function (pi: ExtensionAPI) {
  pi.registerTool({ name: "deploy", ... });
  pi.registerCommand("stats", { ... });
  pi.on("tool_call", async (event, ctx) => { ... });
}

三层定制：从轻到重

pi 提供了三层定制能力，按需选用：

// 一个 Skill 的真实样子（一段 Markdown）
<!-- ~/.pi/agent/skills/code-review/SKILL.md -->
# Code Review
Use this skill when the user asks for a code review.

## Steps
1. Run the linter and tests first
2. Look for security issues, performance, and clarity
3. Group findings by severity

最后一关：4 题检验全套理解

恭喜，你已经能拆开任何 AI 编程 Agent

回头看这 6 个模块，你现在掌握了 pi 的全部内脏：