Pi Coding Agent 是一个极简的开源终端编程框架，默认仅携带四个工具，将大部分行为交给扩展、技能包和你的工作流来处理。

大多数 AI 编程智能体正在变得越来越大。它们添加了规划模式、子智能体、权限层、IDE 集成、后台工作进程，以及围绕模型日益复杂的编排逻辑。Pi 则采取了几乎完全相反的做法：默认智能体从四个基础工具开始——read、write、edit 和 bash——而大多数有趣的行为则被刻意留给了扩展、技能包、第三方包和你自己的工作流。

本评测对应 Pi v0.84.2，发布于 2026 年 8 月 14 日。Mario Zechner 创建了该项目；它于 2026 年 5 月转移至 Earendil Works，这也是当前包使用 @earendil-works 作用域而非旧的 @mariozechner 名称的原因。Pi 一直在快速变化，因此在团队中标准化配置和扩展 API 之前，建议先做版本校验。

同样重要的注意事项是：Pi 比许多编程智能体提供了更多的控制权，但也相应地带来了更多责任。它没有内置安全沙箱，也没有开发者从 Claude Code 或类似工具中可能期望的那种权限系统。下文将涵盖快速入门、架构、模型支持、扩展、会话模型、安全影响，以及我认为 Pi 在现代 AI 编程工具中如何定位。

什么是 Pi Coding Agent？

最好将 Pi 理解为一个智能体框架（agent harness），而不是一个成品、定制好的编程环境。这个区别很重要：编程模型响应提示词，而智能体框架决定该模型看到什么上下文、可以调用哪些工具、工具结果如何返回给它、会话如何持久化，以及两次交互之间发生什么。Pi 让几乎所有这些层级都可以访问，这就是为什么它位于 AI 开发者工具领域的套件构建（kit-building）端，而不是功能完备的编程产品之列。

使用 Pi 最强的理由不是它比竞品有更多功能——实际上它没有。真正的理由是 Pi 暴露了更多智能体本身的东西。这使得它对高级开发者、平台工程师、AI 工具团队，以及任何已经达到"编程智能体的局限性来自框架而非底层模型"这个阶段的人特别有吸引力。对于想安装一个智能体、批准几个安全的默认值然后再也不考虑其架构的人，Pi 的说服力就没那么强了：它的极简主义只有在你重视这种极简主义所带来的控制权时才是高效的。

Pi 实际提供的内容

默认面向模型的工具集有意做得很小：

read
write
edit
bash

其他只读工具如 grep、find 和 ls 也可以使用，最近的 Pi 版本还允许配置初始内置工具选择。

默认配置看起来很稀疏，但这就是要点。每个额外的工具都会增加模型必须做出的决策数量，扩展系统提示词，并产生另一个可能需要调试的行为面。Pi 选择从一个能用的原始工具集出发，让你只有在工作流真正需要时才添加专门的工具。

这个理念在工具之外还有更深入的延伸。Pi 刻意不把内置子智能体或强制性的规划模式作为产品核心；这些行为可以通过扩展或安装的包来实现。这使得 Pi 开箱即用时不够便捷，但让开发者更好地控制这些机制的实现方式。如果你习惯了 Claude Code 的内置子智能体，Claude Code 子智能体指南是很好的参考，可以了解你需要重新实现什么。我发现这种方法略微令人耳目一新：Pi 没有假装有一种正确的操作 AI 编程智能体的方式。

如何安装 Pi Coding Agent 并启动会话

从 @earendil-works 作用域安装当前包。旧的教程可能仍然显示 2026 年 5 月之前的 @mariozechner 包；那些名称对新安装已经过时。

这个名称也与 oh-my-pi 冲突——oh-my-pi 是 Oh My Opencode 框架的社区分支。该项目与此编程智能体无关；如果你访问了错误的 Pi，Oh My Opencode 评测中有对该分支的说明。

安装和认证

用 npm 全局安装 Pi：

   npm install -g --ignore-scripts @earendil-works/pi-coding-agent

--ignore-scripts 在安装期间禁用依赖的生命周期脚本。Pi 在正常 npm 安装时不需要这些脚本，跳过它们可以减少一种常见的供应链风险。

验证安装：

   pi --version

进入项目并启动：

   cd /path/to/project
   pi

Pi 需要 bash 环境。在 Windows 上，使用 WSL 或 Git Bash，而非 cmd.exe。

Pi 支持交互式订阅认证以及基于 API key 的提供商。在 Pi 内部，最简单的路径是：

/login

认证后，用以下命令选择模型：

/model

你也可以通过环境变量提供提供商凭证。例如：

export ANTHROPIC_API_KEY="your-api-key"
pi

Pi 目前支持广泛的模型提供商，包括 OpenAI、Anthropic、Google、Azure OpenAI、Amazon Bedrock、NVIDIA NIM、DeepSeek、Mistral、Groq、Cerebras、Cloudflare、xAI、OpenRouter 以及其他几个。llama.cpp 路由器也支持本地服务的模型：llama.cpp 快速入门涵盖了使用 OpenAI 兼容 API 服务 GGUF 模型，而 LLM 托管指南则映射了周围本地、自托管和云运行时的完整情况——如果你想将那条路径与 Ollama、vLLM 或托管提供商进行比较的话。支持自定义 API 的自定义提供商可以通过 ~/.pi/agent/models.json 添加，自定义 API 或 OAuth 流程可以通过扩展来接入。

这种多提供商设计是 Pi 的实际优势之一。模型和编程框架是独立的变量：使用 Pi，你可以在保持基本相同的工具和会话环境的同时更换模型，这让模型比较比比较完全不同的编程产品有意义得多。

从受控的第一次会话开始

我不会让你的第一个 Pi 提示词是"重构我的应用程序"。先从检查而非修改开始：

pi --tools read,grep,find,ls -p "Inspect this repository. Explain its architecture, identify the main entry points, and list the commands you would run before making a change. Do not modify files."

当我在一个现有仓库上运行这个只读提示词时，有用的结果不是一篇聪明的架构论文，而是模型是否命名了真正的入口点，以及在我授予写权限之前我会实际运行的命令。这让你在不让选定模型立即获得普通工具集的写路径的情况下，观察它如何导航你的目录树。

对于交互式工作，我也建议先创建一个一次性使用的 Git 分支：

git switch -c ai/pi-evaluation
pi

Pi 可以修改工作目录中的文件，也可以通过 bash 执行 shell 命令，所以 Git 仍然是评估它时最简单实用的回滚层之一。如果你想要一个不持久化的测试会话，pi --no-session 以临时模式运行。

项目指令应放在 AGENTS.md 中。一个有用的起始文件可能如下所示：

# Project Instructions

- Read the existing implementation before modifying files.
- Keep changes narrowly scoped to the requested task.
- Run `npm test` after code changes.
- Run `npm run lint` before declaring the task complete.
- Do not modify database migrations unless explicitly requested.
- Do not access production infrastructure.
- Explain any destructive command before running it.

Pi 在遍历项目目录时也理解 CLAUDE.md，而 AGENTS.override.md 可以覆盖正常情况下该目录的项目指令。

然后给它一个具体的任务：

Read the authentication module and its tests.

Find one maintainability problem that can be fixed without changing public behaviour. Explain the proposed change first, then implement it and run the relevant tests.

这是一个比让它生成一个新的玩具应用程序更好的智能体评估方式。现有代码会迫使智能体发现约束条件、保留行为、选择相关文件并验证其工作。

为什么 Pi Coding Agent 是一个可编辑的框架

Pi 最重要的架构理念是：编程智能体本身应该保持可编辑。扩展系统使用 TypeScript 模块，可以注册工具、订阅生命周期事件、拦截工具调用、注入或转换上下文、添加命令并修改终端界面。项目本地的扩展也可以用 /reload 重新加载，这让在这个框架上进行实验变得出奇地即时。

简化后，Pi 的结构如下：

flowchart TD
    U[Developer] --> P[Pi Agent Harness]
    P --> M[Selected LLM Provider]

M --> P

P --> R[read] P --> W[write] P --> E[edit] P --> B[bash]

X[TypeScript Extensions] --> P S[Skills] --> P C[Project Context] --> P PKG[Pi Packages] --> P

R --> FS[Project Workspace] W --> FS E --> FS B --> OS[Shell and Toolchain]

这个架构图简洁是因为 Pi 试图保持控制平面的简单性。这带来了一个不寻常的选择：当智能体缺少某个能力时，你不必等待 Pi 维护者来添加它——你可以自己动手添加。扩展可以创建一个新的可被模型调用的工具，检查拟议的 bash 调用并阻止符合你自定义策略的命令，在每次对话前插入动态项目信息，改变压缩行为，或在终端 UI 中暴露自定义命令。这比修改系统提示符要深入得多。

MCP 集成并未被当作 Pi 最小化核心的必选内置部分。它可以通过相同的扩展性模型添加，这与更广泛的设计理念一致：专业化的集成位于小型默认框架之上，而非永久性地扩展它。

同一个框架也可以在交互式终端之外重复使用。Pi 提供了一个用于将智能体会话嵌入 Node.js 应用程序的 SDK，以及一种 RPC 模式（`pi --mode rpc`），通过 stdin/stdout 的 JSON 通信，可用于非 Node 宿主、IDE 和自定义 UI。

四工具理念比看起来更加严肃

我最初将编码智能体工具分为两组。第一组包含原语：读取文件、修改文件、执行命令。第二组包含便利功能：仓库搜索、测试运行器、问题追踪器、浏览器工具、部署工具、数据库助手、代码智能和专业化规划器。Pi 将原语层保持精简，同时允许便利层保持可选。

这有一个架构上的优势。负责 Kubernetes 基础设施的团队可以构建一个与维护 TypeScript 单体仓库的团队截然不同的 Pi，而两支团队不必在同一个默认智能体中携带对方的工具。这正是 Pi 开始看起来不像一个精简版 Claude Code 替代品、而是变成构建你自己的编码智能体框架的时刻。

代价是维护。一旦你依赖自定义扩展，它们的行为就成了你开发者平台的一部分：你需要审查它们、版本化管理它们，偶尔还需要随着 Pi 的演进更新它们。这就是隐藏的 Pi 税——你获得了智能体的所有权，而所有权伴随着维护。

Skills 和 Packages 保持定制模块化

并非所有自定义行为都需要成为扩展。Pi 支持将指令、脚本和参考材料围绕某个能力打包成 skills。Skills 使用渐进式披露：Pi 可以向模型广告可用的 skill，而只在需要该能力时才加载完整指令。这对于部署审查、数据库迁移、发布准备或框架特定代码审查等工作流很有用；与其将大量指令永久注入每次对话，不如让智能体按需加载专业化指导。如果你已经构建过 Claude Skills，操作方式会很熟悉——参见 Claude Skills 和 SKILL.md for developers 了解 SKILL.md 布局和触发器调优。

Pi Packages 走得更快，将扩展、skills、提示模板和主题打包在一起。Packages 可以从 npm 或 Git 仓库安装，并且可以固定到特定版本：

pi install npm:@foo/pi-tools@1.2.3 pi list

包模型很强大，但要将包视为可执行的开发者工具，而不是无害的提示集合。Pi 扩展可以用 Pi 进程的权限执行代码，skill 也可以指示模型执行代码，所以安装未知包本质上应该和安装未知的开发依赖一样受到怀疑。

Pi Coding Agent 中的会话树

许多编码助手将对话视为大部分线性的记录。Pi 将会话存储为树结构，这意味着你可以返回到更早的时间点，尝试另一种方法，并保留会话中的两条路径，而不是销毁一段历史或创建一堆不相关的聊天记录。

主要命令很简单：

/resume /tree /fork /clone /compact

`/tree` 让你在当前会话树中导航。`/fork` 从更早的用户消息创建一个新会话，而 `/clone` 将当前活跃的分支复制到一个独立的会话中。从命令行，`pi -c` 继续最近的会话，`pi -r` 浏览过去的会话。

这个区别在我用 Pi 做调试而非新提示时变得显而易见。我让它沿着缓存层的假设去追踪一个失败的集成测试，然后从选择该假设的消息处 fork，创建了第二条关于事务隔离的分支。这段失败的调查仍然可用作对比，而不是污染新路径或强制开启一个全新聊天——这是对调试实际工作方式的有用表征：多个合理的解释往往同时存在。

Pi 将会话持久化为 JSONL，并在对话接近模型上下文限制时自动压缩较旧的内容；分支也可以在你移动时进行摘要。我会将其排在几个更显眼的编码智能体功能之上：良好的上下文管理通常比界面中再多一个按钮更重要。

上下文工程是一等公民能力

Pi 还使得自定义传递给模型的内容成为可能。扩展可以在对话前注入信息、修改历史并参与压缩。默认压缩系统会在保留近期对话的同时摘要旧材料，但这个机制可以被替换或自定义。

对于高级团队，这开辟了有趣的可能性。大型单体仓库可以仅向智能体当前操作的文件注入所有权信息。后端项目可以在数据库文件进入上下文时呈现模式元数据。长期运行的迁移智能体可以在对话外维护结构化状态，而不是反复让模型重新发现它。这是我认为 Pi 真正的长期优势：编码智能体的质量越来越受到上下文工程、工具设计和编排的约束，而不是原始模型智能体，而 Pi 让开发者异常直接地访问这些层面。

Pi Coding Agent 安全性：无内置沙箱

这篇评测中最重要的负面点很简单：Pi 不提供内置的安全沙箱。默认情况下，Pi 以启动它的用户和进程的权限运行。它的工具可以读取和修改可访问的文件，并在该操作系统上下文中执行 shell 命令。

Pi 确实有项目信任，但项目信任不是沙箱。项目信任控制是否加载项目本地的 Pi 设置、扩展、skills、提示和类似资源。一旦你在一个项目中工作，它不会在模型导向的工具调用周围创建文件系统、网络、进程或凭证边界。我实际上很欣赏 Pi 文档对这一区别的明确说明：一个弱小的伪沙箱可能比没有沙箱更危险，因为用户可能信任一个实际上并不存在的边界。Pi 转而期望有意义的隔离来自容器、虚拟机、微虚拟机或其他策略控制的运行时。

对于一次性的个人项目，你可能认为 Git 和正常的操作系统权限就足够了。对于不受信任的仓库、无值守的智能体、包含生产凭证的工作站或处理外部提供内容的智能体，我会使用更强的隔离。Pi 文档描述了三种模式：

重要的边界不仅仅是源代码目录。可以运行 shell 命令的智能体可能潜在地与 SSH 配置、云凭证、包注册表、本地服务、浏览器状态以及进程可访问的任何其他内容交互。因此，一个生产级别的设置需要同时考虑文件系统挂载、环境变量、网络访问和凭证。我偏好的评估模式是：

flowchart TD H[Host] --> T[Terminal and Git] H --> SB[Sandbox] SB --> P[Pi] SB --> RC[Repository copy] SB --> BT[Build tools] SB --> MC[Minimum provider credentials]

将真实仓库以读写方式挂载到容器中仍然允许智能体修改该仓库；容器仅在其挂载、凭证、能力配置和网络访问确实受到约束时才有用。Gondolin 有一个相关的警告：自定义扩展工具仍在主机上运行，除非它们也委托到 VM 中。

还有一个值得记住的安全面：扩展和包。第三方扩展是在智能体环境内部运行的代码。安装前请审查它，固定重要依赖项，不要将公共包仓库当作隐式的安全审查。

在重要机器上运行 Pi 之前，有两个实用的检查：

确认你实际拥有的版本

pi --version

禁用启动时的网络操作（更新检查和安装遥测）

export PI_OFFLINE=1 pi

`PI_OFFLINE=1` 会禁用所有启动时的网络操作，包括更新检查、包更新检查和安装/更新遥测。如果需要更细粒度的控制，`PI_SKIP_VERSION_CHECK=1` 只关闭版本检查，而 `PI_TELEMETRY=0` 禁用安装/更新遥测但保留更新检查。

这种安全模型是我在大规模工程组织中作为非托管默认值推广 Pi 之前会犹豫的主要原因。Pi 提供了构建强安全环境的组件，但它有意将大部分环境配置留给你自己。

Pi Coding Agent 与 Claude Code 和 OpenCode 对比

Pi 最有意义的比较方式是按理念而非功能数量来对比。在终端智能体中，OpenHands 是更接近的同类：它同样从 CLI 运行，但它自带沙箱和更大的内置工作流，而不是要求你自己组装。Claude Code 拥有日益复杂的内置权限、钩子和子智能体。OpenCode 暴露可配置的 allow、ask 和 deny 规则以及内置的智能体或子智能体概念。Pi 在栈中处于更底层的位置。

这就是为什么把 Pi 称为"Claude Code 克隆"会错过有趣的部分。如果你对 Claude Code 的工作流满意，Pi 不会自动改善它：Claude Code 给你更多的安全性和智能体编排行为，而无需你自己组装这些组件。当你想要改变产品底层的假设时，Pi 才开始变得有趣。也许你想要在 Anthropic、OpenAI 和本地模型上使用相同的工具链。也许你的组织有自己的沙箱。也许你需要一个在每次交互前注入内部架构元数据的工具。也许你希望压缩（compaction）产生结构化的工程状态而不是通用的对话摘要。这才是 Pi 的领域。

OpenCode 从哲学上讲可以说更接近，因为它也提供了大量配置。即便如此，Pi 更像是一套用于构建工具链本身的套件，而 OpenCode 暴露的是更多现成的智能体和权限概念。

这里没有通用的赢家。对许多开发者来说，Claude Code 的 opinionated 默认值是一个优势。对另一些人来说，OpenCode 可能提供更好的中间地带。当"I wish my coding agent worked differently"比"I wish my coding agent had another feature"更重要时，Pi 是我推荐研究的选项。

你应该使用 Pi Coding Agent 吗？

Pi Coding Agent 是技术上更有趣的编码智能体之一，因为它拒绝隐藏工具链。默认实现故意做得很小，但扩展 API、skills、包、提供者层、SDK、RPC 模式和会话树给了它比四个默认工具所暗示的更大的有效表面。

我会最强烈地向喜欢构建自己工具链的资深开发者推荐 Pi。它对于 AI 平台工作、实验性编码智能体研究、专业工程工作流以及已有安全执行基础设施的团队特别有吸引力。对于想要在不改变整个编码环境的情况下比较模型的开发者也很有用。对于初学者和期望安装后立即获得企业级策略控制的组织，我会更加谨慎。

缺失的沙箱改变了 Pi 的部署方式，特别是当智能体被允许无人值守操作或可能遇到不受信任的指令时。将 Pi 视为一个强大的本地开发进程而不是安全边界：对于不受信任的仓库、无人值守操作或包含高价值凭证的环境，请使用操作系统、容器、VM 或基于策略的沙箱，只暴露任务所需的资源。

我的总体评分是 8.4/10。这是一个编辑性判断而非上表的平均分，对于合适的用户来说它很容易变得更高。Pi 最大的弱点和最大的优势是同一件事：它不会替你完成智能体。

你应该从 Claude Code 切换吗？不会自动切换。当 Claude Code 的内置权限、子智能体、钩子和工作流符合你已有的工作方式时，使用 Claude Code。当你想要更广泛地拥有工具链、提供者选择、上下文构建和工具架构时，评估 Pi。对于高级开发者，我甚至不会假设这个选择必须是互斥的：Claude Code 可以保留作为精致的日常驱动，而 Pi 成为可编程的智能体实验室。经过足够的自定义后，那个实验室可能会变成你实际更喜欢的工具。

Pi 本身是开源的，采用 MIT 许可证发布。但这不会让模型推理免费：你实际的成本取决于模型提供者、API 使用量、支持订阅认证、本地计算以及你选择运行的任何沙箱基础设施。

Pi Coding Agent 仓库：https://github.com/earendil-works/pi

Pi 网站和安装器：https://pi.dev

npm 包：https://www.npmjs.com/package/@earendil-works/pi-coding-agent

Gondolin micro-VM：https://github.com/earendil-works/gondolin

NVIDIA OpenShell：https://docs.nvidia.com/openshell/about/overview