理念一：极简主义——“如果我不需要它，它就不会被构建”#

这不仅仅是”少即是多”的口号，而是一套严格的工程决策体系。

系统 prompt 不到 1000 token（实际约 200 token），对比 Claude Code 的 ~10K token、OpenCode 的模型专属 prompt。Mario 的论点：前沿模型经过大量 RL 训练，天生就理解什么是 coding agent。10K token 的 prompt 更多是给人类看的”产品文档”而非模型必需品。Terminal-Bench 2.0 基准测试和几个月的实际使用验证了这一点——极简 prompt 并没有降低性能。

只有 4 个工具（read/write/edit/bash）。不需要 glob 工具——用 find via bash。不需要 grep 工具——用 rg via bash。不需要 web search 工具——用 curl via bash。每次增加工具都是在系统 prompt 里加 token，消耗上下文窗口。

没有 MCP、没有内置 Todo、没有 Plan Mode、没有 Background Bash、没有 Sub-agents。每个”不支持”都有明确的技术论据而非偷懒：

• MCP 的 token 开销：Playwright MCP 21 个工具吃 13.7K tokens（占上下文窗口 7-9%），Chrome DevTools MCP 26 个工具吃 18K tokens
• Todo 列表让模型追踪额外状态，反而增加出错机会
• Plan Mode 可以用文件实现（PLAN.md），且文件版跨 session 持久化、可版本控制
• Background Bash 用 tmux 天然解决，tmux 自带会话列表和附着功能

pi-ai 的四协议抽象：Mario 识别出所有 LLM provider 本质上只说四种协议（OpenAI Completions、OpenAI Responses、Anthropic Messages、Google Generative AI），在内部统一处理几十种 provider 特有的怪癖（Cerebras 不支持 store 字段、Mistral 用 max_tokens 而非 max_completion_tokens、Google 至今不支持 tool call streaming 等）。

核心 tradeoff：极简意味着更少的 token 开销（系统 prompt + 工具定义 < 1000 token），把上下文窗口留给真正的工作内容。代价是”开箱即用”的功能更少，需要用户自己构建。

理念二：可观测性——用户必须能看到一切#

这是 Mario 从 Claude Code 等工具中感到最痛的点：背后的黑箱操作。

完整的事件流：pi-agent-core 的 agent loop 对每一步都发出事件——agent_start、turn_start、message_update（含 text_delta）、tool_execution_start、tool_execution_end、agent_end。任何 UI 或监控都可以订阅这个事件流，看到模型在做什么。

Sub-agent 问题的核心：Mario 强烈反对 Claude Code 的 sub-agent 模式——“zero visibility into what that sub-agent does. It’s a black box within a black box”。如果 sub-agent 犯错，调试极其痛苦，因为你完全看不到完整对话。他的替代方案：用 bash 调用 pi 自身，这样输出是可见的。

Context 的完全控制：Pi 的扩展系统有一个 context 钩子，能在消息发送给 LLM 之前拦截和修改消息数组。你可以精确控制什么进入上下文窗口——不像其他 agent 在背后偷偷注入内容。

Session 文件完全可读：JSONL 格式，每行一个 JSON 对象。你可以直接 cat、jq、grep 来检查 session 的任何细节。

Steer 和 FollowUp：steer() 中断当前执行注入用户消息（跳过剩余 pending 工具），followUp() 在 agent 自然结束后排队消息。这两个机制让用户能实时引导 agent，而不是被动等待。

理念三：自修改性——Agent 可以修改自己的代码#

这是 Pi 最具革命性的特性。Armin Ronacher 对此有最好的阐述：

软件如黏土：Pi 的整个架构围绕”software that is malleable like clay”设计。当你需要 agent 做新事情时，不是下载扩展，而是让 agent 自己写扩展。

扩展系统的设计支撑：

• 扩展用 TypeScript 写，通过 jiti（运行时 TypeScript 加载）无需预编译
• 扩展有 20+ 生命周期钩子，可以注册工具、命令、键盘快捷键、UI 组件、持久化状态
• 扩展状态可持久化到 session 文件（不发给 LLM）
• 内置热重载——agent 写完代码，重载，测试，循环直到功能正常

Session 树使自修改安全：你可以在分支上修一个坏掉的扩展，修好后回退到主 session。Pi 自动总结分支上发生了什么。

Armin 的实践：他的所有扩展（/answer、/todos、/review、/files、/control）都是让 Pi 自己写的。“There is no MCP, there are no community skills, nothing. Don’t get me wrong, I use tons of skills. But they are hand-crafted by my clanker and not downloaded from anywhere.”

read#

读取文件内容或查看图片。支持文本文件和图片（jpg、png、gif、webp）。图片以附件形式发送。文本文件默认读取前 2000 行，大文件用 offset/limit 分段。

write#

写入内容到文件。文件不存在则创建，存在则覆盖。自动创建父目录。

edit#

通过替换精确文本来编辑文件。oldText 必须完全匹配（包括空格）。用于精确、外科手术式的编辑。要求精确字符串匹配——不支持正则、不支持模糊匹配。如果搜索字符串不是精确匹配一次，会报出明确的错误。这迫使模型先读取文件再使用精确字符串。

bash#

在当前工作目录执行 bash 命令。返回 stdout 和 stderr。可选择提供超时（秒）。不支持后台进程——如果需要，使用 tmux。

特性一：跨 Provider 上下文交接#

这是 pi-ai 从设计之初就内建的能力。

问题有多难：每个 provider 有自己的 tool call 格式、thinking trace 格式、签名 blob 回放机制。切换模型时甚至同一 provider 内的不同模型也可能不兼容。

Pi 的解法：

• Anthropic 的 thinking trace 转换为 <thinking> 标签的文本块
• Tool call 和 tool result 格式统一为 Context.messages 数组
• 每个 provider 的签名 blob 在后台处理，用户无感
• Context 对象完全可序列化为 JSON，可以存储、传输、之后反序列化继续

实际使用场景：

1
// 开始用 Claude
2
const claude = getModel('anthropic', 'claude-sonnet-4-5');
3
// 中途切到 GPT — 它能看到 Claude 的 thinking 作为 tagged text
4
const gpt = getModel('openai', 'gpt-5.1-codex');
5
// 再切到 Gemini
6
const gemini = getModel('google', 'gemini-2.5-flash');
7
// 序列化，以后用任何模型继续
8
const serialized = JSON.stringify(context);

对 token 成本的影响：你可以在简单任务上用便宜模型（Groq 的 Llama、Gemini Flash），复杂任务切到 Opus，同一个 session 内。Pi 内建每 session 的 token 和成本追踪，让 provider 路由变成数据驱动的决策。

特性二：Session 树（非线性历史）#

这是 Pi 最独特的架构决策之一。

数据结构：Session 存储为 JSONL 文件，每条记录有 id 和 parentId，形成一个有向无环图（DAG）。切换分支只改变”叶指针”，不创建新文件。整个历史完整保留。

1
interface SessionEntry {
2
  id: string;
3
  parentId?: string;   // 形成树结构
4
  type: 'message' | 'tool_call' | 'tool_result' | 'meta';
5
  timestamp: number;
6
  data: unknown;
7
}

实际工作流：

• /tree 命令在 session 内导航，选择任何历史节点，从那里分支出去
• /fork 从任何分支点创建新 session
• 在分支上修 bug 或实验新方案，不影响主线
• 修好后回退主线，Pi 自动总结分支发生了什么
• 可以保存完整 session 为 HTML、分享到 GitHub gist

对比线性历史：Claude Code / Codex / 大多数 agent 的 session 是线性的。Claude Code 有 compaction（压缩旧消息释放上下文窗口），但没有真正的分支和回退。Pi 的树结构意味着你可以无风险探索——不满意就切回另一个分支。

自定义消息：Session 文件支持 meta 类型条目，扩展可以用它持久化状态（不发给 LLM）。OpenClaw 用这个做每通道的 session 隔离和崩溃恢复——JSONL 是追加写的，崩溃最多丢失一行。

特性三：差异渲染的终端 UI（pi-tui）#

Mario 不满意现有的 TUI 方案（Ink 要写 React、Blessed 无人维护、OpenTUI 明确标注不生产就绪），所以自己写了一个。

两种 TUI 路线的选择：

• 全屏 TUI（Amp、OpenCode 用）：接管终端视口，像像素缓冲区一样管理。缺点：丢失原生滚动缓冲区和搜索功能，鼠标滚动体验差
• 追加式 TUI（Claude Code、Codex、Pi 用）：正常输出到终端，只在需要时回退渲染光标重画动画。保留原生滚动和搜索

Pi 选择追加式，因为 coding agent 天然是线性对话，追加式有更好的信息密度。

差异渲染算法：

1. 首次渲染：直接输出所有行
2. 宽度变化：清屏完全重绘（因为软换行变了）
3. 正常更新：找到第一行不同的地方，移动光标到那一行，从那里重绘到末尾

防闪烁：用同步输出转义序列（CSI ?2026h / CSI ?2026l）包裹所有渲染，告诉终端缓冲所有输出然后原子显示。在 Ghostty/iTerm2 上效果极佳，VS Code 终端有轻微闪烁但比 Claude Code 少。

组件模型：保留模式（Retained Mode）——Component 有 render(width) 方法返回行数组，可以缓存已完成的渲染结果。Container 垂直排列子组件。TUI 类协调一切。

性能：存储整个滚动缓冲区的之前渲染行做比较，加上组件缓存，在 25 年内的任何计算机上都不是性能问题（几百 KB 内存用于非常大的 session）。

Mario 甚至在 pi-tui 里跑过 Doom——不是为了实用，而是证明如果能在 TUI 里跑 Doom，你一定能构建有用的 dashboard 或调试界面。

特性四：结构化工具结果分离#

这是一个在其他统一 LLM API 中很少见的抽象。

设计：每个工具返回两个东西——

• content：发给 LLM 的内容（文本/JSON）
• details：给 UI 渲染的结构化数据（不发到模型）

1
interface ToolResult {
2
  output: string;        // 模型看到的
3
  details?: {            // UI 可以渲染的
4
    type: 'file' | 'diff' | 'terminal' | 'error';
5
    data: unknown;
6
  };
7
}

为什么重要：

• 模型的上下文保持干净——不需要为了 UI 显示在文本里塞结构化信息
• UI 可以渲染丰富内容（diff 高亮、文件树、终端输出着色）而不需要解析文本
• 工具还可以返回图片附件，以 provider 原生格式发送

partial JSON 解析：tool call 参数在流式传输时就被渐进解析，UI 可以在调用完成前显示部分结果——比如 edit 工具的 diff 可以一边流一边显示。

对比：大多数统一 API 只返回文本给模型和 UI 共用。Pi 的分离让模型看到精简信息，UI 看到丰富信息，各取所需。

特性五：扩展系统（20+ 生命周期钩子）#

扩展系统是 Pi 自修改能力的载体。

运行时加载：用 jiti 做 TypeScript 运行时加载，无需预编译。Agent 写完扩展代码，热重载立即生效。

核心钩子分类：

扩展能做的事：

• 注册自定义工具（registerTool）
• 注册命令（registerCommand）
• 注册键盘快捷键
• 注册 UI 组件（spinner、progress bar、文件选择器、数据表、预览面板）
• 持久化状态到 session
• 拦截 bash 命令（比如 Armin 的 pip → uv 重定向）
• 替换系统 prompt、切换模型、修改工具集

分发模型：

• npm 包：pi install npm:@foo/bar
• Git 仓库：pi install git:github.com/user/repo
• 本地路径：直接引用
• 单次使用：pi -e npm:@foo/bar（ephemeral）
• 可组合：多个扩展堆叠，互不干扰

Skills 系统的渐进披露：Skill 是 YAML-frontmatter 的 Markdown 文件。关键设计——只有 description 常驻上下文，完整内容按需加载。Armin 用 skill 让 Pi 自动维护 uv 替代 pip 的行为、自动生成 commit message、更新 changelog。甚至添加了一个扩展拦截 pip 和 python 调用重定向到 uv。

YOLO 模式——默认全部放行#

Pi 默认以完全 YOLO 模式运行。没有权限检查，没有安全围栏。完整的文件系统访问。可以用你的用户权限执行任何命令。

Mario 的论点：“Security in coding agents is mostly security theater. As soon as your agent can write code and run code, it’s pretty much game over.” 核心问题：如果 LLM 有能力读取私人数据和发起网络请求的工具，你在攻击向量上玩的是打地鼠游戏。

不支持 MCP——设计如此#

MCP 服务器在每次会话时将整个工具描述 dump 到上下文中。Playwright MCP：21 个工具，13.7k tokens。Chrome DevTools MCP：26 个工具，18k tokens。那是上下文窗口的 7-9% 在你开始之前就没了。

替代方案：构建带 README 文件的 CLI 工具。Agent 需要工具时读取 README，只在必要时支付 token 成本（渐进披露）。Mario 维护了 agent-tools 在 github.com/badlogic/agent-tools。

不支持 Background Bash#

使用 tmux 代替。tmux 提供会话列表、附着和完全的可观测性。Claude Code 的 background bash 可观测性差，早期版本甚至在上下文压缩后忘记进程的存在。

不支持 Sub-agents#

“zero visibility into what that sub-agent does. It’s a black box within a black box”

如果你需要 pi 生成自身，只需要求它通过 bash 运行自身。你甚至可以让它在 tmux session 内生成自身以获得完全的可观测性。

Mario 的核心洞察：“Using a sub-agent mid-session for context gathering is a sign you didn’t plan ahead.” 相反，应该先在自己的 session 中收集上下文，创建一个 artifact，然后在新的 session 中使用这个 artifact。

Terminal-Bench 2.0#

Mario 使用 Claude Opus 4.5 运行了 Terminal-Bench 2.0。尽管工具远少于其他 agent，Pi 排名接近榜首，接近或超过 Codex、Cursor、Windsurf。

值得注意的是，Terminus 2（Terminal-Bench 团队自己的最小 agent，只给模型一个 tmux session）也表现良好。这证明了极简方法的有效性。

Pinggy 排名（2026）#

Pi 被描述为”最有趣的新入场者”。