Pi：证明少即是多的极简编程代理

AI 辅助编程领域正在发生一场静默的革命。当整个行业竞相构建更大、更复杂的代理框架——塞入数千 token 的系统提示、数十种专用工具和不透明的内部编排——一位开发者选择了相反的道路。这改变了一切。

Pi 是由 Mario Zechner 创建的编程代理框架，他是 libGDX 游戏框架的开发者。Pi 驱动着 OpenClaw，该项目在不到三个月内从零增长到超过 250,000 个 GitHub 星标，成为 GitHub 上星标最多的软件仓库——甚至超过了 React。

这不是一篇摘要。这是一份涵盖 Pi 每一层的全面技术指南——从哲学到数据包结构，从 ReAct 循环到自扩展的扩展系统。如果你在使用 AI 代理进行开发，这篇文章将改变你对它们的思考方式。

起源：以挫折为设计原则

Mario Zechner 的挫折感是具体且技术性的。Claude Code——他每天使用的工具——用他的话说，已经变成了*"一艘有 80% 功能我完全用不到的太空船。"*问题很具体：

• 系统提示不稳定：提示和工具定义在每次发布时都会改变，悄然破坏精心设计的工作流程。
• 上下文工程盲区：框架在上下文窗口中注入内容，却不在界面中显示，使得理解模型实际看到的内容变得不可能。
• 工具泛滥：数十个重叠的工具争夺模型的注意力，仅描述本身就消耗了上下文预算。

他的论点是：如果你将编程代理精简到绝对最低限度——一个极小的系统提示、四个工具和完全的上下文透明度——前沿模型的表现会更好，而不是更差。训练数据已经包含了模型需要知道的关于成为编程代理的一切。

结果证明他是对的。Pi 配合 Claude Opus 在 Terminal-Bench 2.0 上取得了与 Codex、Cursor 和 Windsurf 相竞争的结果——仅凭不到 100 token 的系统提示和恰好四个工具。

Pi 与世界——定位

这种定位是刻意的。Pi 占据了一个没有其他工具声称的空间：最小核心的最大可扩展性。它不是在功能上与 Claude Code 竞争——它在论证那些功能大部分根本不应该存在于框架中。

上面的图表直观地讲述了这个故事。当你的系统提示消耗 10,000 个 token 时，那就是模型无法用于你实际代码的 10,000 个 token。Pi 的方法是：给模型工具，给它你的项目上下文（AGENTS.md），然后让它工作。

单体仓库：分层架构

Pi 位于 badlogic/pi-mono——一个使用 npm workspaces 且严格执行分层依赖的 TypeScript 单体仓库。依赖图是一个 DAG：基础包有零内部依赖，每一层只能向下依赖。

这种架构不是偶然的。每个包都可以独立使用。你可以单独使用 pi-ai 进行批量 LLM 处理，无需任何代理基础设施。你可以使用 pi-agent-core 在你自己的应用中嵌入 ReAct 循环，无需 TUI。各层是可组合的，而非单体的。

pi-ai：统一 LLM API

一切的基础。pi-ai 将 15 多个 LLM 提供商映射到单一的统一接口——它通过认识到一个基本事实来做到这一点：

API 接口

import { complete, completeStreaming } from "@mariozechner/pi-ai";
 
// Simple completion
const response = await complete({
  provider: "anthropic",
  model: "claude-sonnet-4-6",
  messages: [{ role: "user", content: "Explain Pi in one sentence." }],
});
 
// Streaming with abort support
const stream = completeStreaming({
  provider: "openai",

上下文切换——杀手级功能

Pi 最独特的能力：会话可以在同一对话中跨越多个 LLM 提供商。当你在会话中途从 Claude 切换到 GPT 时，整个上下文——包括思维链——会被序列化并重新格式化以适应新的提供商。

// Start with Claude for complex reasoning
const msg1 = await complete({
  provider: "anthropic",
  model: "claude-opus-4-6",
  messages: conversationHistory,
});
 
// Switch to a cheaper model for routine tasks
const msg2 = await complete({
  provider: "openai",
  model: "gpt-4.1-mini",
  messages: [...conversationHistory, msg1],
  // Thinking traces auto-converted to tagged text
});

这不仅仅是切换提供商——这是跨越根本不同的 API 格式的完整状态保存。没有其他统一 LLM 库实现了这一点。

分离式工具结果

Pi 的另一项创新：工具结果可以为 LLM 和界面返回不同的内容。模型接收简洁的文本摘要；TUI 接收结构化数据以进行丰富的可视化：

const tool = {
  name: "search_codebase",
  execute: async (args) => {
    const results = await searchFiles(args.query);
    return {
      llm: `Found ${results.length} matches in ${results.map(r => r.file).join(", ")}`,
      ui: { type:

pi-agent-core：约 200 行的 ReAct 循环

每个代理系统——从 Claude Code 到 OpenClaw 到 Pi——都实现了 ReAct（推理 + 行动）模式，由 Yao 等人于 2022 年在 Princeton/Google 提出。关键洞察：与单次响应相比，当 LLM 能够推理、行动、观察然后再次推理时，它们的表现会显著更好。

Pi 的实现是极简且完全可检查的。

简化版循环

// Pseudocode of Pi's agent loop (actual: ~200 lines of TypeScript)
async function agentLoop(messages, tools, model) {
  while (true) {
    // 1. REASON: Ask the LLM what to do
    const response = await complete({ model, messages, tools });
 
    // 2. Check: Is the model done? (text response, no tool calls)
    if (!response.toolCalls?.length) {
      return response.text; // Final answer
    }
 
    // 3. ACT: Execute each tool call
    const toolResults = await Promise

工具验证管道

每次工具调用都经过严格的验证管道。TypeBox 模式提供编译时类型安全和运行时验证，当工具参数失败时会给出详细的错误消息：

import { Type } from "@sinclair/typebox";
 
const ReadTool = {
  name: "read",
  description: "Read file contents",
  schema: Type.Object({
    path: Type.String({ description: "Absolute file path" }),
    offset: Type.Optional(Type.Number({ minimum: 0 })),
    limit: Type.Optional(Type

消息排队：引导 vs 跟进

当代理在流式传输时，用户可以在不等待的情况下注入消息。Pi 支持两种根本不同的注入模式：

**引导（Steering）**会中断当前的生成并重新引导代理。**跟进（Follow-up）**等待当前轮次完成，然后消息在下一轮中被处理。这种区别在实践中极为重要——它是"停下来，改做这个"和"另外，当你完成那个之后……"之间的区别。

4 个核心工具——以及为什么只有 4 个

没有 search_codebase。没有 get_git_history。没有 list_directory。模型使用 bash 处理一切非文件 I/O 的操作。这之所以有效是因为：

1. 前沿模型已经知道这些工具。它们在编程代理场景上经过了大量的 RL 训练。
2. 每个额外的工具都在争夺上下文空间。工具描述很昂贵——它们存在于每个请求中。
3. Bash 是通用的。grep -r、find .、git log——模型已经深谙这些命令。

可选的只读工具

对于安全的探索会话（例如，熟悉新的代码库），Pi 提供只读模式：

pi --tools read,grep,find,ls

这将禁用 write、edit 和 bash——代理可以探索但不能修改任何内容。非常适合代码审查或架构发现。

会话：JSONL 树

Pi 会话存储为追加式 JSONL 文件，其中每一行是一个带有 id 和 parentId 的节点。这创建了一个树结构，支持分支：你可以返回到任何之前的点并继续，在同一文件中创建新的分支同时保留所有先前的分支。

{"id":"a1","parentId":null,"role":"user","content":"Fix the auth bug"}
{"id":"a2","parentId":"a1","role":"assistant","content":"Let me read..."}
{"id":"a3","parentId

节点 b1 从 a2 分支，创建了一个替代时间线。两条路径共存于同一文件中。SessionManager API 提供了列出、创建、恢复和分支会话的操作。

压缩：无限会话长度

当会话接近上下文窗口的 80%（可配置）时，Pi 触发压缩。较旧的消息被一个由廉价模型（如 Claude Haiku）生成的摘要替代。这使得会话长度不受限制而不会降低质量：

压缩阈值是可配置的——而且摘要模型可以与主模型不同。在实践中，使用 Haiku 进行压缩摘要同时运行 Opus 进行推理，以最低成本提供出色的质量。

4 种运行模式

所有四种模式共享一个抽象：AgentSession。各模式仅在 I/O 层上有所不同。

SDK 模式：OpenClaw 如何使用 Pi

OpenClaw——超过 25 万星的个人 AI 助手——使用 Pi 的 SDK 模式。它不会将 Pi 作为子进程启动。它直接导入并实例化 Pi，获得完整的生命周期控制：

import { createAgentSession } from "@mariozechner/pi-agent-core";
 
const session = createAgentSession({
  provider: "anthropic",
  model: "claude-sonnet-4-6",
  tools: [...defaultTools, ...customTools],
  extensions: [securityAudit, messageFormatter],
  onMessage: (msg) => gateway.send(channel, msg),
});
 
// Handle incoming message from WhatsApp/Telegram/Slack

这就是使 OpenClaw 成为可能的模式。Peter Steinberger 的"周末黑客项目"将 Pi 的代理核心连接到多平台消息网关——结果迅速走红，因为底层代理引擎（Pi）足够稳固，能够处理真实世界的多渠道工作负载。

扩展系统

扩展是由 jiti 加载的 TypeScript 模块——一个无需构建步骤的运行时 TypeScript/ESM 转译器。这实现了热重载：编辑 .ts 文件，输入 /reload，更改立即生效。

扩展结构

// my-extension.ts
import { ExtensionAPI } from "@mariozechner/pi-coding-agent";
 
export default function (api: ExtensionAPI) {
  // Add a custom slash command
  api.addSlashCommand({
    name: "review",
    description: "Review staged changes",
    execute: async () => {
      const diff = await api.bash("git diff --staged");
      return api.sendMessage(

自扩展范式

这是 Pi 最激进的能力。因为扩展是无需构建步骤加载的 TypeScript，代理可以编写并热重载自己的扩展。工作流程：

1. 你描述你想要的："我需要一个运行我们 staging 管道的 /deploy 命令"
2. Pi 将扩展写为 .ts 文件
3. 你输入 /reload
4. Pi 测试新命令
5. 如果失败，Pi 读取错误，修复代码，重新加载并重试

Armin Ronacher（Flask 和 Jinja2 的创造者）将此描述为*"像粘土一样可塑的软件。"*他的所有 Pi 扩展——/answer、/todos、/review、/files——都是由 Pi 自己编写的，而不是 Armin。他描述了需求，指给代理一些示例，Pi 就自主地实现了它们。

系统提示：约 100 个 Token

这是从源代码中复制的 Pi 实际系统提示。与 Claude Code 的约 10,000 个 token 做对比：

You are an AI coding assistant. You help users with software engineering tasks.
Use the provided tools to accomplish tasks.

就这些。上下文预算的其余部分分配给：

加载层级按以下顺序：

1. 系统提示（约 100 token）
2. 工具定义（约 900 token）
3. AGENTS.md 文件（项目特定上下文，由用户控制）
4. 技能（渐进式披露——按需加载）
5. 对话历史（上下文的大部分）

用户通过 AGENTS.md 控制大部分上下文预算。这与 Claude Code 的方法相反，在那里框架控制大部分上下文，用户得到的是剩余的部分。

技能：agentskills.io 标准

Pi 实现了 agentskills.io——一个可移植技能包的开放标准。为 Pi 编写的技能在 Claude Code、Codex CLI、Amp 和 Droid 中同样可用。

SKILL.md 格式

---
name: code-review
version: 1.0.0
description: Automated code review with style checks
triggers:
  - /review
  - "review this"
---
 
# Code Review Skill
 
You are a code review assistant. When activated:
 
1. Read the staged git diff
2. Check for:
   - Security vulnerabilities
   - Performance issues
   - Style violations
   - Missing error handling
3. Provide actionable feedback with line references

技能使用渐进式披露：它们的完整内容仅在触发时才加载到上下文中，而不是在会话开始时。这保持了基线上下文的精简，同时按需提供深层功能。

官方技能仓库

代理模式：使用 Pi 的 5 种方式

模式 1：ReAct（默认）

默认行为。无需配置——模型根据上下文决定何时调用工具：

pi "Fix the failing tests in src/auth/"

模式 2：Plan-and-Execute

对于定义明确的多步骤任务，先生成计划再执行。研究表明，与顺序 ReAct 相比，完成率为 92%，速度提升 3.6 倍：

pi "Use /plan to refactor the payment module to use Stripe v3"

模式 3：Multi-Agent（编排器 + 专家）

使用 pi --print 子进程或 nicobailon/pi-subagents 包进行并行执行：

# agents/security-reviewer.md
---
name: security-reviewer
model: claude-sonnet-4-6
tools: [read, grep, find]
---
You are a security specialist. Review code for OWASP Top 10 vulnerabilities.

模式 4：Reflection

让专家代理在呈现之前审查主代理的输出：

pi "Implement the feature, then use /reflect to review your own work"

模式 5：动态工具加载

当你有 50 多个工具时，渐进式加载以避免准确性下降：

api.on("resources_discover", async () => {
  // Only load tools relevant to current context
  const packageJson = await readFile("package.json");
  if (packageJson.includes("prisma")) {
    api.addTool(prismaQueryTool);
  }
});

OpenClaw 的故事：从周末黑客到 25 万星

OpenClaw 始于奥地利开发者 Peter Steinberger 的一个"周末黑客项目"。概念是：一个运行在你自己设备上的个人 AI 助手，在你已经使用的渠道上回复——WhatsApp、Telegram、Slack、Discord、Google Chat、Signal、iMessage、IRC、Microsoft Teams、Matrix、LINE 等等。

架构很直接：OpenClaw 是一个消息网关，使用 Pi 的 createAgentSession() SDK 嵌入完整的编程代理。每个渠道获得自己的隔离会话。Docker 沙箱确保代理代码安全运行。定时事件实现类似 cron 的触发器。

为什么 Pi 使 OpenClaw 成为可能

1. SDK 模式：Pi 作为库嵌入，而非子进程——完全的生命周期控制
2. 提供商无关性：用户选择他们的 LLM（Claude、GPT、Gemini、通过 Ollama 的本地模型）
3. 扩展系统：OpenClaw 添加自定义扩展以实现平台特定功能
4. 会话持久化：JSONL 树格式意味着对话在重启后仍然存在
5. 最小占用：Pi 的微小核心意味着快速启动和低内存使用

Ollama 集成

2026 年 3 月，Ollama 正式在其 CLI 中添加了 ollama launch pi——使 Pi 成为第一个通过单条命令即可访问的代理框架。结合 Kimi K2.5（一个万亿参数的 MoE 模型），这意味着：

ollama launch pi --model kimi-k2.5:cloud

一个完整的编程代理，由万亿参数模型驱动，成本比 Claude Opus 低 9 倍。每百万输入 token $0.60。每百万输出 token $3.00。

TUI：保留模式 vs 即时模式

Pi 的终端界面（pi-tui）做出了一个与其他所有编程代理不同的基本架构选择：

保留模式方法意味着 Pi 的 TUI 永远不会闪烁。组件跨帧持久化，缓存其渲染输出，仅重新渲染发生变化的部分。这与 React 使用的差异化渲染模型相同——但用于终端。

扩展可以完全访问组件系统。你可以构建交互式界面——进度条、表格、选择菜单、语法高亮的代码块——与代理输出无缝集成。

代理的 7 种失败模式（及 Pi 的解决方案）

上下文经济学：为什么每个 Token 都重要

图表说明了为什么 Pi 的极简方法在经济上胜出。当你的框架在用户的第一条消息之前消耗 15,000 个 token 时，你在每一次 API 调用上都要为这些开销付费。在包含数百个轮次的长会话中，臃肿系统提示的累积成本是巨大的。

Pi 的方法：系统提示 + 工具约 1,000 个 token。剩余的预算是你的。

如何开始

第 1 步：安装

npm install -g @mariozechner/pi-coding-agent
# or
ollama launch pi

第 2 步：配置提供商

# Anthropic (recommended)
export ANTHROPIC_API_KEY=sk-ant-...
 
# OpenAI
export OPENAI_API_KEY=sk-...
 
# Local models via Ollama
# No API key needed — Pi auto-detects local Ollama

第 3 步：创建 AGENTS.md

# My Project
 
## Tech Stack
- Next.js 15, TypeScript, Tailwind CSS
- PostgreSQL with Drizzle ORM
- Deployed on Vercel
 
## Conventions
- Use conventional commits
- Tests required for all new features
- No direct database queries — use the ORM layer

第 4 步：运行

# Interactive mode (default)
pi
 
# With a specific model
pi --model claude-opus-4-6
 
# Print mode for scripting
pi --print "Generate a migration for adding user roles"
 
# Read-only exploration
pi --tools read,grep,find,ls "Explain the auth flow"

第 5 步：构建你的第一个扩展

// .pi/extensions/hello.ts
export default function (api) {
  api.addSlashCommand({
    name: "hello",
    description: "A warm greeting",
    execute: async () => "Hello from my first Pi extension!",
  });
}

在 Pi 中输入 /reload，然后 /hello。你的扩展已经上线。

为什么精简到基本的开源会赢

Pi 的教训不是极简主义总是更好。而是在正确的地方保持极简——系统提示、工具集、核心循环——为在重要的地方保持最大化创造了空间：用户对上下文、扩展和工作流程的控制。

Claude Code 是一个优秀的产品。Cursor 是一个优秀的产品。但它们是产品——为普通用户设计，为常见情况优化。Pi 是一个工具包——为那些想要理解和控制进入其代理上下文窗口的每一个 token 的开发者设计。

证据不言自明：

• 核心仓库 31,600+ 个 GitHub 星标
• OpenClaw 250,000+ 星标（基于 Pi 的 SDK 构建）
• 184 个版本在活跃开发中
• Ollama 集成使其成为单命令安装
• agentskills.io 建立了跨代理的技能标准
• 有竞争力的基准测试结果，复杂度仅为其他方案的一小部分

下次当你与一个做出意外行为的编程代理斗争时——注入你看不到的内容，调用你没有要求的工具，在你不使用的功能上消耗上下文——记住还有一个替代方案。一个信任模型、信任开发者、并且让开路的方案。

那个替代方案就是 Pi。它正在证明，在 AI 代理的时代，最好的框架是那个几乎不存在的框架。

Pi 在 MIT 许可证下开源。仓库：badlogic/pi-mono。官方网站：pi.dev。

OpenClaw：openclaw/openclaw。Armin Ronacher 的分析：Pi: The Minimal Agent Within OpenClaw。