第一章：Pi 项目概览与核心定位

1.1 Pi 是什么

1.1.1 一句话介绍

Pi 是 Mario Zechner（libGDX 游戏框架作者、Badlogic Games 创始人）打造的极简终端编码 Agent 工具集。它不是 IDE 插件，不是某个大模型的官方客户端，也不是对 ChatCompletion API 的简单包装——它是一个 Agent Harness（代理工具集），一个你可以完全掌控的编码助手底盘。

「如果我不需要它，它就不会被构建。」 ——Mario Zechner

Pi 将”极简”贯彻到极致：核心系统提示词仅 ~1000 tokens，只给你的模型 4 个工具（read、write、edit、bash）。没有内置 TODO 列表，没有 Plan 模式，没有子 Agent 系统，没有 MCP 协议支持，没有权限弹窗，没有后台 bash 进程——所有这些”功能”都被刻意拒之门外。替代它们的是一套高度可扩展的 TypeScript Extension 系统、基于文件的 Skill 规范和 Prompt Template，以及一个极其活跃的 Pi Package 生态（目前已有 4600+ 社区包）。

Pi 的许可证为 MIT，托管在 GitHub earendil-works/pi（原 badlogic/pi-mono），官方网站为 pi.dev，官方文档为 pi.dev/docs/latest。

1.1.2 Pi 的定位与”它不是什么”

要理解 Pi，最好的方式是先看清它不是什么：

• 不是 IDE 插件。 与 Cursor、Continue、Cline、GitHub Copilot Chat 等 IDE 插件完全不同。Pi 是一个独立运行的终端 CLI 程序，不依赖任何编辑器。你可以从命令行启动它、通过 RPC 协议嵌入自己的程序、甚至用 SDK 把它的 Agent 能力塞进 Node.js 应用。
• 不是某个大模型的官方客户端。 虽然 Pi 默认推荐使用 Claude 模型，但它本身与具体模型解耦。它内置了 Anthropic、OpenAI、Google、DeepSeek、xAI、Groq、Cerebras、OpenRouter、Mistral、Amazon Bedrock、Azure OpenAI、Cloudflare AI Gateway、Vercel AI Gateway、Hugging Face、Together AI、Fireworks、NVIDIA NIM、Kimi For Coding、MiniMax、小米 MiMo、ZAI Coding Plan、OpenCode Zen/Go 等 30+ 供应商的认证体系，支持订阅制（Claude Pro/Max、ChatGPT Plus/Pro、GitHub Copilot）和 API Key 两种认证方式。
• 不是简单的”包一层 API”。 Pi 底层有 pi-ai（统一多供应商 LLM API），内部处理了跨供应商上下文传递、结构化工具结果分片、增量 JSON 解析、token/成本追踪、缓存命中率统计等复杂工程问题；有 pi-agent-core 处理 Agent 循环、状态管理、消息队列、传输抽象；有 pi-tui 实现差异化渲染（differential rendering）的终端 UI 框架。这是一套从底层 LLM API 到顶层 UI 都自己做的”全栈”Agent 系统。
• 不是”只能跑在本地的玩具”。 Pi 虽然以终端为主要界面，但它同样支持 RPC 模式（通过 stdin/stdout JSONL 与外部进程通信）、JSON 事件流模式（适合日志管线与自动化管道）、Print 模式（-p 参数，一次性问答）、以及通过 SDK 嵌入到任意 Node.js 应用中。社区已经有人用 Pi 构建了浏览器 Web UI、Telegram Bot、后台批处理管线等。

那么 Pi是什么呢？官方 README 和 Mario 的博客给出了一个精确的定位：

Pi 是一个最小化核心、最大化可扩展性的终端编码 Agent 工具集。它不替你做工作流决策——子 Agent、Plan 模式、TODO 列表、权限弹窗、MCP 这些全部留给扩展系统和社区包去实现。它做的只有一件事：给你一个你可以完全观测、完全控制、完全按自己想法改造的 Agent 底盘。

1.2 Pi 的设计哲学

Pi 的设计哲学可以用一句话概括：“原语而非功能”（Primitives, not Features）。核心本身保持极小，所有上层工作流行为全部通过 Extensions、Skills、Prompt Templates 和 Pi Packages 实现。这不是”功能残缺”，而是一种深思熟虑的设计取舍。下面逐条展开。

1.2.1 极简系统提示词（~1000 tokens）

以下是 Pi 的完整系统提示词（经过翻译和精简）：

你是一个专业的编码助手。你通过读取文件、执行命令、编辑代码和写入新文件来帮助用户完成编码任务。

可用工具：
- read: 读取文件内容
- bash: 执行 bash 命令
- edit: 精确替换文件中的文本
- write: 创建或覆写文件

准则：
- 使用 bash 执行文件操作，如 ls、grep、find
- 使用 read 检查文件后，再进行编辑
- 使用 edit 进行精确修改（旧文本必须完全匹配）
- 仅在创建新文件或完全重写时使用 write
- 总结你的操作时，直接输出纯文本——不要用 cat 或 bash 来显示你做了什么
- 保持回复简洁
- 操作文件时清晰地显示路径

文档：
- 你自己的文档（包括自定义模型配置和主题创建）位于：/path/to/README.md
- 当用户询问功能、配置或设置时阅读该文件

就这么点。注入到模型上下文尾部的内容只有你的 AGENTS.md 或 CLAUDE.md。与 Claude Code 动辄上万 token 的系统提示词相比，Pi 的提示词量大约是前者的 1/10 甚至更少。

这不是疯狂之举。Mario 的观察是：所有前沿模型都已经经过了充分的 RL 训练，它们天生就知道什么是”编码 Agent”。不需要一万个 token 的提示词来教会它们——相反，少即是多。把 token 预算留给用户真正的任务，而不是系统提示中的”噪音”，反而能获得更好的输出质量。Terminal-Bench 2.0 的基准测试结果也佐证了这一点：Pi + Claude Opus 4.5 的组合跑出来的成绩丝毫不逊于那些使用上万 token 原生提示词的 Agent。

1.2.2 极简工具集（4 个核心工具）

Pi 默认只暴露 4 个工具给模型：

此外还有三个只读工具（grep、find、ls）——但默认是不启用的。如果你想限制 Agent 只能读不能写，可以通过 --tools read,grep,find,ls 显式启用只读模式。

这套工具集的精妙之处在于：它恰好覆盖了编码 Agent 所需的全部原子操作，却没有任何冗余。模型可以用 bash 执行任何命令（ls、grep、find、git、npm、docker……），用 read 检查文件，用 edit 做精确的手术刀式修改，用 write 创建新文件。grep/find/ls 作为可选工具，让用户在只读模式下也能高效工作。

对比 Claude Code 的庞大工具定义（几十个工具、复杂的参数 schema、详细的用法示例），Pi 的工具定义总量同样保持在 ~1000 tokens 以内。

1.2.3 默认 YOLO 模式——无安全护栏

Pi 默认运行在完全的 YOLO 模式下：它对文件系统拥有无限制的读写权限，可以执行任意 shell 命令，没有任何权限弹窗或确认步骤。没有 Haiku 前置检查 bash 命令是否恶意，没有”是否允许执行此操作？”的打断。

Mario 对此的逻辑非常直白：

只要你允许 Agent 读数据、写代码、执行代码这三个能力同时存在，任何安全护栏都是安全表演（security theater）。Prompt 注入攻击、数据外泄、混乱代理攻击（confused deputy）——这些在 Agent 能读写文件又能联网的前提下几乎无法彻底防御。Simon Willison 的”双 LLM 模式”试图解决这个问题，但复杂度巨大，效果也有限。

既然三个能力（读数据、执行代码、网络访问）的”不可能三角”无法在 Agent 层面解决，Pi 选择不假装自己能解决。它把隔离的责任交还给操作系统层面：如果你需要安全边界，请使用容器（Docker）、微虚拟机（Gondolin）、或策略控制沙箱（OpenShell）。Pi 官方文档提供了完整的容器化方案，包括三种模式：Gondolin 扩展（路由工具调用到本地 Linux 微 VM）、纯 Docker（整个 pi 进程跑在容器里）、OpenShell（策略控制沙箱）。

此外，Pi 默认没有内置 web 搜索和 fetch 工具，减少了部分攻击面——但它仍然可以通过 curl 发起网络请求，这一点和其他所有编码 Agent 一样。

1.2.4 为什么 Pi 不内置这些功能

Pi 刻意不内置以下功能，每一项背后都有具体的理由：

不内置 MCP（Model Context Protocol）

Mario 曾专门撰文讨论这个问题。核心论点：MCP 服务器的上下文开销太大。以流行的 Playwright MCP 为例，一个 server 就带 21 个工具，工具描述总计 13,700 tokens——光加载工具定义就吃掉 7%-9% 的上下文窗口，而这些工具在大多数会话中根本不会被用到。

Pi 的替代方案：用 CLI 工具 + README 文件代替 MCP Server。当 Agent 需要某个能力时，它读取那个 CLI 工具的 README，按需付出 token 成本（渐进式披露）。CLI 工具天然可组合（管道、输入/输出重定向）、易于扩展（加一个脚本即可）。Mario 自己维护了一个工具集合 github.com/badlogic/agent-tools，每个工具都是一个带 README 的简单 CLI 脚本。

如果社区真的需要 MCP，可以装 pi-mcp-adapter 或 @tintinweb/pi-mcp 等第三方扩展——这正是 Pi”原语而非功能”哲学的体现。

不内置子 Agent（Sub-Agent）

Mario 认为子 Agent 有两大问题：可观测性为零（你看不到子 Agent 内部做了什么）和上下文传递差（编排 Agent 自行决定给子 Agent 传什么）。Claude Code 中的子 Agent 是一个”黑盒中的黑盒”，一旦出错极难调试。

Pi 的做法：直接用 bash 工具 spawn 一个新的 pi 进程。你可以把它放进 tmux session 里获得完全的可观测性，甚至能直接 tmux attach 进去和子 Agent 协同调试。

更深层的问题是：很多人用子 Agent 是因为没提前规划好上下文。如果你需要收集上下文，应该先在独立的 session 里做这件事，产出一个制品（artifact），然后在新的 session 中引用该制品。这样一来，上下文干净、可观测、可复用——下一次做类似功能时可以直接用同一个制品。

不内置 Plan 模式

Pi 不内置 Plan 模式，因为”让 Agent 和你一起思考问题，但不修改文件、不执行命令”本身就是一个足够好的 Planning 流程。如果你需要跨 session 的持久化计划，写成 PLAN.md 文件即可——Agent 可以读取、更新、引用它。

Mario 吐槽 Claude Code 的 Plan 模式：”基本上是只读分析，最终还是会写一个 markdown 文件到磁盘。不用 Plan 模式的话，你还得批准一大堆命令调用，因为不做这些调用就根本没法做 Planning”。而 Pi 的做法是：把 Planning 做成一个你完全可观测的过程——你看到 Agent 读了哪些源文件、漏了哪些、它写的 markdown 文件长什么样、你可以和 Agent 协同编辑这个文件。

如果你需要一个能和 Claude Code Plan 模式媲美的功能，可以通过 --tools read,grep,find,ls 启动只读模式来完成探索和规划，或者安装 @plannotator/pi-extension 等社区扩展。

不内置 TODO 列表

Mario 从经验出发：”TODO 列表通常会迷惑模型多于帮助它。它们增加了一个模型必须追踪和更新的状态，这引入更多出错机会”。如果你需要任务追踪，写一个 TODO.md 文件即可——Agent 可以读它、更新它。用 checkbox（- [ ] / - [x]）跟踪完成状态。简单、可见、完全在你的掌控之下。

如果社区需要内置 TODO，有 @juicesharp/rpiv-todo、pi-codex-goal 等第三方扩展。

不内置权限弹窗

理由和”YOLO 模式”相同：在 Agent 拥有读写文件 + 执行代码 + 网络访问能力的条件下，权限弹窗提供的安全感是虚假的。如果你真的需要权限控制，请使用容器。如果你想要特定行为的确认（比如 rm -rf 前确认），写一个 Extension 即可——一个包含 tool_call 事件监听器的 TypeScript 文件，不超过 20 行代码。

社区已有 @gotgenes/pi-permission-system、cc-safety-net 等权限控制扩展。

不内置后台 bash

Pi 的 bash 工具是同步的——命令执行完毕才返回结果。没有内置的方式启动 dev server 并让它在后台运行、或者在命令执行期间与 REPL 交互。

理由：用 tmux 更好。后台进程管理本身引入了巨大的复杂性——进程追踪、输出缓冲、退出清理、向运行中进程发送输入……Claude Code 实现过这些功能，但可观测性很差，Agent 经常忘记自己有哪些后台进程。而 tmux 天然支持：tmux new-session -d 启动后台 session，tmux capture-pane 查看输出，tmux send-keys 发送输入，人类随时可以 tmux attach 进去和 Agent 协同操作。完全可观测，完全可控。

1.2.5 上下文工程优先：精确控制进入模型上下文的内容

这是 Mario 反复强调的核心洞见：上下文工程（Context Engineering）是一切。”精确控制进入模型上下文的内容，会让你获得更好的输出质量——尤其是在编码场景。”

大多数现有的 Agent 工具集让上下文工程变得极其困难或根本不可能——它们在背后偷偷注入东西，这些内容甚至不会在 UI 中显示出来。Pi 则正好相反：你可以通过 AGENTS.md（全局 + 项目多层）、SYSTEM.md（替换默认提示词）、APPEND_SYSTEM.md（追加内容）、--system-prompt CLI 参数、before_agent_start 扩展事件等多种方式精确控制进入模型的每一个 token。

1.2.6 渐进式披露：按需加载工具文档

如果不使用 MCP，Agent 如何知道它能调用哪些外部工具？答案是渐进式披露（Progressive Disclosure）。

每个外部工具都是一个独立的 CLI 脚本，带有一个 README.md 文件描述其功能。Agent 在需要时通过 read 工具读取这个 README，只付出这一次的 token 成本，而不是在每次会话开始时就把所有工具定义全部塞进上下文窗口。这种方式天然支持工具的按需发现和懒加载。

Skills 机制（遵循 agentskills.io 标准）进一步强化了这一点：每个 Skill 是一个 Markdown 文件，描述了”何时使用该技能”和”如何执行”。Agent 在启动时只看到技能名称和一句话摘要，完整文档在首次使用时才加载。

1.2.7 完全可观测性：你可以看到 Agent 的每一个操作

Pi 不给 Agent 任何”黑盒”空间。所有操作都是可见的：

• 模型思考过程（thinking traces）会流式显示（可折叠）
• 工具调用和返回值完整展示
• bash 命令执行结果原样输出（包括 ANSI 转义序列）
• 会话完整保存在 JSONL 文件中，可事后审计、导出为 HTML、分享给他人
• 通过 /tree 可以跳到会话历史的任意位置，从那里重新开始
• 通过 before_provider_request、after_provider_response 等扩展事件可以检查发给提供商的原始 payload

对比 Claude Code 的子 Agent（你看不到子 Agent 内部做了什么）和 Plan 模式（规划过程不可见），这种完全透明是 Pi 最鲜明的特质之一。

1.2.8 文件即状态：用文件代替内置功能

Pi 的另一个核心设计原则：如果某个状态可以用一个文件表达，那就不要把它做成内置功能。这不是”简陋”，而是一种深思熟虑的简化策略。

这种”文件即状态”的哲学带来的最大好处是：一切都可以被 git 跟踪、可以被编辑器打开、可以被脚本批量处理、可以被 Agent 本身读取和修改。没有任何一比特的状态藏在你看不到的地方。

1.2.9 Extension 系统：所有”缺失功能”的出口

Pi 的 Extension 系统是 TypeScript 模块，它们可以：

• 注册自定义工具（LLM 可调用）
• 注册自定义命令（/mycommand）
• 监听生命周期事件（工具调用前后、Agent 启动/结束、会话切换等）
• 注入或修改系统提示词
• 构建自定义 TUI 组件（对话框、状态栏、编辑器替换）
• 实现权限控制、Git checkpointing、路径保护
• 集成 MCP server、SSH 远程执行、浏览器自动化
• ……以及你能想到的任何东西

一个典型的 Extension 长这样：

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";

export default function (pi: ExtensionAPI) {
  pi.on("tool_call", async (event, ctx) => {
    if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
      const ok = await ctx.ui.confirm("危险操作！", "确认执行 rm -rf？");
      if (!ok) return { block: true, reason: "用户拒绝" };
    }
  });

  pi.registerTool({
    name: "greet",
    label: "问候",
    description: "按名称问候某人",
    parameters: Type.Object({
      name: Type.String({ description: "要问候的名字" }),
    }),
    async execute(toolCallId, params) {
      return {
        content: [{ type: "text", text: `你好，${params.name}！` }],
        details: {},
      };
    },
  });
}

这种”核心极小，功能由扩展实现”的模式，让 Pi 拥有了几乎无限的灵活性——同时又确保核心本身永远保持简洁和可维护性。

1.3 Pi 与同类产品的对比

1.3.1 与 Claude Code 的对比

1.3.2 与 Cursor/Cline 的对比

1.3.3 与 Aider 的对比

1.3.4 与 opencode 的对比

1.3.5 Pi 的差异化竞争力

总结下来，Pi 的独特优势在于：

1. 极致简约的核心——~1000 tokens 系统提示词 + 4 个工具。没有任何你不需要的”功能”挤占上下文窗口。
2. 真正的模型自由——30+ 供应商原生支持，对自托管模型（Ollama、vLLM、llama.cpp、LM Studio）的兼容性极好。不依赖 Vercel AI SDK 等第三方库，直接调用各供应商的原生 API。
3. 完全的上下文工程能力——多层 AGENTS.md、自定义 SYSTEM.md、Extension 事件拦截、按需 Skill 加载——你对进入模型的每一个 token 有绝对控制权。
4. 高度可扩展——4600+ 社区包、TypeScript Extension 系统、Agent Skills 标准、Prompt Template、Pi Package——把”缺失的功能”变成”你可以安装的功能”。
5. 完全可观测——没有黑盒子 Agent，没有隐藏的系统提示词注入，没有你看不到的子 Agent 内部操作。一切都在你的屏幕上、JSONL 文件中、HTML 导出中。
6. MIT 开源——完全开放，可以 fork、修改、商用，没有任何限制。

1.4 项目概况

1.4.1 基本信息

1.4.2 技术架构：TypeScript monorepo，5 个核心包

Pi 是一个 TypeScript monorepo，根目录下 packages/ 包含了 5 个核心包：

此外还有一个独立的配套仓库 earendil-works/pi-chat，提供 Slack/聊天自动化和工作流集成。

1.4.3 运行时要求

1.4.4 安装方式

多种安装方式详见 第二章：安装与环境配置。

1.4.5 供应链安全

Pi 对 npm 依赖的安全性有严格要求：

• 直接外部依赖锁定精确版本。内部工作区包保持版本范围。
• .npmrc 设置 save-exact=true 和 min-release-age=2。
• package-lock.json 是依赖的权威来源，pre-commit 钩子防止意外提交 lockfile 变更。
• 发布包包含 npm-shrinkwrap.json 以锁定传递依赖。
• 发布前进行隔离安装烟雾测试（Node + Bun）。
• CI 定期运行 npm audit --omit=dev。

1.5 学完本教程能做什么

本教程共 15 章，循序渐进。学完之后你应当能够：

1. 理解 Pi 的极简设计哲学与核心定位，把握”原语而非功能”背后的技术决策逻辑，能自主判断什么应该做成 Extension、什么应该用文件解决。
2. 完成 Pi 的安装与环境配置：包括选择 Node.js 版本（>= 22.19.0）、安装 Pi、配置 API Key、通过 /login 接入订阅制供应商、运行 pi --list-models 验证安装。
3. 独立完成首次 Pi 交互：启动 / 退出交互模式、发起首次 prompt、观察工具调用的完整流程、理解消息流（prompt → 模型响应 → 工具调用 → 结果反馈 → 后续响应）。
4. 精通模型供应商与认证体系：理解订阅制（Claude Pro/Max、ChatGPT Plus/Pro、GitHub Copilot）和 API Key 两种认证方式，配置 30+ 供应商中的任意一个，添加自定义 OpenAI/Anthropic/Google 兼容端点。
5. 掌握配置体系：全局设置（~/.pi/agent/settings.json）、项目设置（.pi/settings.json）、主题配置、快捷键配置（keybindings.json）、项目信任机制（trust.json），能精确控制 Pi 在任意项目中的行为。
6. 熟练使用交互式 TUI：斜杠命令（/model、/resume、/new、/tree、/fork、/compact、/export 等）、编辑器高级功能（@ 模糊文件搜索、Tab 路径补全、Shift+Enter 多行、图片粘贴、!/!! bash 指令）、消息队列（steering / follow-up）、快捷键（模型切换、思考级别切换、工具输出折叠）。
7. 深入理解工具系统：4 个核心工具（read、write、edit、bash）的精确语义、3 个可选只读工具（grep、find、ls）、通过 CLI 参数控制工具白名单/黑名单、通过 Extension 拦截和修改工具调用。
8. 构建 Skills 技能系统：创建遵循 Agent Skills 标准的 SKILL.md、理解渐进式披露机制、组织全局和项目级 Skills、使用 /skill:name 手动唤起技能。
9. 开发 TypeScript Extension：掌握 Extension 生命周期事件（session_start、tool_call、before_agent_start、context 等 20+ 事件）、注册自定义工具和命令、构建自定义 TUI 组件和对话框、实现权限控制、Git checkpointing、路径保护等常见扩展模式。
10. 管理 Pi Package 的安装与分发：通过 npm 或 git 源安装包（pi install npm:xxx）、启用/禁用包的特定资源（Extensions/Skills/Prompts/Themes）、更新包（pi update --extensions）、创建和发布自己的 Pi Package。
11. 使用 SDK 嵌入 Pi：用 createAgentSession 将 Pi 的 Agent 能力嵌入到自己的 Node.js 应用中，理解 AgentSessionRuntime 的高级用法。
12. 通过 RPC 模式集成外部进程：使用 stdin/stdout JSONL 协议与非 Node.js 程序集成，理解 RPC 模式的严格 LF 分隔 JSONL 协议细节。
13. 实施容器化与安全沙箱：配置 Gondolin 微 VM 扩展、用 Docker 运行完整隔离的 Pi 进程、使用 OpenShell 策略控制沙箱，理解项目信任机制与进程级隔离之间的区别。
14. 理解核心架构：深入 pi-ai（统一 LLM API 层的 4 种 API 适配、跨供应商上下文传递、token 追踪）、pi-agent-core（Agent 循环、工具验证、事件流）、pi-tui（保留模式 UI、差异化渲染、同步输出的终端 UI 框架）的源码级设计。
15. 将 Pi 整合进日常开发工作流：用 AGENTS.md 建立项目规范、用 Skills 沉淀团队最佳实践、用 Extensions 自动化重复性操作、用 tmux + Pi 实现协同编码和长时运行任务、用 /share 和 HTML 导出分享和审计工作 Session。

1.6 学习前的准备

1.6.1 基础知识要求

虽然每一章都会从基础讲起，但你最好具备以下前置知识：

• 基本的终端使用能力（bash/zsh/PowerShell 均可）。会执行命令、理解当前工作目录（cwd）、会设置环境变量。
• 了解 Markdown 语法。Pi 的 AGENTS.md、SKILL.md、Prompt Template 全部使用 Markdown 格式。
• 基础的 JSON 概念。配置文件和 Session 格式都是 JSON。不需要手写复杂 JSON，但至少能阅读和修改。
• 了解过任意一个 LLM 服务的 API Key 概念。如果你注册过 OpenAI、Anthropic 或 DeepSeek 的开发者账号并拿到过 API Key，就已经足够了。
• 基础的 TypeScript/JavaScript 知识（仅在开发 Extension 时需要）。日常使用 Pi 完全不需要写代码——但如果你要写自己的 Extension 或通过 SDK 嵌入 Pi，则需要了解 TypeScript 的基本语法（函数、类型注解、async/await、import/export）。
• 不要求了解 Node.js 生态（npm、package.json 等）——教程中会从零讲解。
• 不要求会 Python——Pi 是完全的 TypeScript/Node.js 工具链。
• 不要求有 AI Agent 开发经验——第一章就是你的起点。

1.6.2 硬件要求

Pi 对硬件的要求极低——毕竟它本身只是一个 Node.js 命令行程序，AI 推理的计算在远程服务器上完成：

操作系统方面：Linux、macOS、Windows WSL2、Android Termux 全部支持。注意：Pi 不支持 Windows 原生环境（PowerShell/CMD/Git Bash），Windows 用户必须通过 WSL2 运行（详见第二章）。

1.7 本章小结

本章我们建立了对 Pi 的整体认知：

• Pi 是 Mario Zechner 打造的 MIT 协议、极简终端编码 Agent 工具集，核心仅 ~1000 tokens 系统提示词 + 4 个工具。
• 它的核心理念是 “原语而非功能”（Primitives, not Features）——核心保持极小，所有上层工作流行为全部通过 Extensions、Skills、Prompt Templates 和 Pi Packages 实现。
• 它刻意不内置 MCP、子 Agent、Plan 模式、TODO 列表、权限弹窗、后台 bash，每一项都有具体的工程理由——要么可以用更简单的方式（tmux、TODO.md、PLAN.md）替代，要么属于”安全表演”而不如直接交给 OS 级隔离，要么造成了上下文膨胀和可观测性损失。
• 它的设计原则围绕 上下文工程优先（精确控制进入模型的内容）、渐进式披露（按需加载工具文档）、完全可观测性（没有任何黑盒操作）、文件即状态（JSON/MD 文件代替内置功能）展开。
• 它通过 Extension 系统 解决了”缺失功能”的问题——4600+ 社区包证明了这个模式的生命力。
• 它是一个 TypeScript monorepo，由 5 个核心包组成（pi-ai、pi-agent-core、pi-coding-agent、pi-tui、pi-orchestrator），同时支持 Node.js 和 Bun。
• 相比 Claude Code、Cursor/Cline、Aider、opencode 等同类工具，Pi 的差异化竞争力在于 极致简约 + 模型自由 + 上下文可控 + 高度可扩展 + 完全可观测 + MIT 开源。

下一章：第二章：安装与环境配置 将从零开始安装 Pi，完成环境配置，并跑通你的第一个 Pi 会话。