Working with Pi Coding Agents

KDnuggets

KDnuggets2026年7月16日

Working with Pi Coding Agents

6.9内容质量

TL;DR · AI 摘要

Working with Pi Coding Agents - KDnuggets publ: 16-Jul, 2026 - Blog Top Posts About - Topics AI Career Advice Computer V...

核心要点

主题聚焦：Working with Pi Coding Agents
来源：KDnuggets，建议结合原文判断细节。
AI 分析暂不可用，本条为保底评分与摘要。

#AI#编程#前端#后端#云计算

打开原文

与 Pi 编码代理合作 - KDnuggets

publ: 2026年7月16日

博客热门文章

主题 AI 职业建议计算机视觉数据工程数据科学语言模型机器学习 MLOps NLP 编程 Python SQL

数据集

活动

资源快速参考指南推荐技术简报

广告

加入通讯

#header end

/ad_wrapper

与 Pi 编码代理合作

Pi 最有趣的地方不在于任何单一功能，而在于该项目将"我们没有构建的内容"视为值得撰写的文档，这种做法本身就足够罕见，值得认真对待。

作者：Shittu Olumide，技术内容专家 2026年7月16日，编程领域

# 引言

大多数编码代理都在比拼能为你完成多少工作。Claude Code 可以管理子代理、计划模式和权限流程。Cursor 则围绕模型构建了完整的 IDE。这些产品的宣传语通常都是"更强的能力，更少的设置"。Pi 却采取了完全相反的策略，其文档中明确表示：不使用 MCP、不使用子代理、不使用计划模式、不弹出权限提示、不内置待办事项列表、不运行后台 bash。当其他工具列出功能时，Pi 的 README 却列出它拒绝构建的内容。

这种产品定位方式非常罕见，值得实际测试。因此本文将直接进行验证。我在真实环境中安装了 Pi，核对了版本与官方更新日志，然后编写了一个可用的 TypeScript 扩展并加载到运行中的二进制文件中。

前提条件：

Node.js 22 或更高版本、npm 和终端
如果希望运行真实会话而非仅安装和检查工具，至少需要一个提供商（Anthropic、OpenAI、Google 或其他）的 API 密钥。以上条件足以完成下文所有操作的跟随

# Pi 真正的定位与幕后团队

Pi 由 Mario Zechner 开发，他也是 libGDX 项目的开发者。2025年11月，他发表了一篇罕见的坦率长文，解释了开发 Pi 的原因。他的论点具有结构性：主流编码工具会注入你无法看到的上下文，在版本更新时未经太多警告就改变行为，并且限制你对模型实际接收内容的可见性。他的应对方案是构建完全相反的工具：一个由扩展点环绕的小型核心循环，而非功能完备且工作方式固定的完整产品。

该项目迅速获得了实质性进展。2026年1月，Flask 和 Jinja2 的创建者 Armin Ronacher 发表了一篇技术文章，公开支持 Pi 是值得构建的最小代理。大约两个月后，Ronacher 的公司 Earendil Inc. 完全收购了该项目，将 Zechner 作为主要股东引入，并推出了名为 Lefos 的配套云平台。这次收购附带了一份实际的治理文件 RFC 0015，承诺 Pi 的核心将保持 MIT 许可，同时为付费的 Fair Source 层和构建在其上的托管服务保留空间——这是一种在基础设施软件中常见的开源核心结构，如果你正在考虑围绕它构建工作流，提前了解这一点很有价值。

截至目前，Pi的GitHub仓库的星标数已超过70,000个且仍在持续增长，这对于一个以“少即是多”为卖点的工具来说是一个具有里程碑意义的数字。我直接通过安装后的版本确认而非依赖变更日志快照来验证当前版本：在全新安装后运行pi --version命令，显示版本为0.80.3，与Pi官网新闻页面上标注的最新版本完全一致。

# 四大工具与刻意缺失的功能

Pi内置的工具集仅有四个：read、write、edit和bash。这不是一个默认会随使用增长而扩展的起点，而是全部内容。通过实际安装的二进制文件运行pi --help命令即可直接验证这一点；工具在自身的帮助文本中将自己描述为“一个带有读取、bash、编辑、写入工具的AI编码助手”。

其他代理工具原生支持的功能，Pi都视为需要用户自行添加的扩展项。其官方文档明确指出了缺失的部分：核心功能中没有MCP支持、没有子代理编排、没有计划模式、没有权限确认弹窗、没有内置待办事项追踪、也没有后台bash执行功能。这一设计原则既基于哲学考量，也与成本控制密切相关。有报道称，同类编码代理工具的默认系统提示词在用户输入任何内容前就已经占用7,000到10,000个token，而每次API调用都会重复产生这笔成本。Pi通过设计将系统提示词控制在1,000个token以内，唯一注入的额外内容只有用户自己的AGENTS.md文件——一个适用于所有会话的全局文件和一个项目专用文件，两者都完全可见且可编辑。

这一设计背后的核心假设是：前沿模型已经充分理解编码代理应具备的功能，因为它们在代理任务上接受了大量强化学习训练。较小的提示词可以让模型保留更多上下文预算用于实际工作，而非花费在行为指令上。这种设计是否能带来预期效果，很大程度取决于用户的具体使用场景，这也是本文后续部分将直接进行的测试。

# 实操体验：安装与真实会话运行

安装Pi只需一条命令。它以npm包形式发布在Earendil的命名空间下。

code

# 推荐安装方式（--ignore-scripts参数是Pi官方文档建议的）
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# 或者，在macOS/Linux系统下使用独立安装脚本
curl -fsSL https://pi.dev/install.sh | sh

我在干净的环境中严格按照上述命令执行npm install，整个过程耗时约11秒，安装了131个依赖包，并在路径中生成了可用的pi二进制文件。紧接着运行pi --version立即返回0.80.3，确认安装确实成功而非静默失败。

认证流程提供两种路径。如果您的服务提供商支持，可在Pi会话中运行/login启动基于订阅的OAuth认证流程。否则，需在启动前设置API密钥作为环境变量：

code

export ANTHROPIC_API_KEY=sk-ant-your-key-here
# 或者针对特定项目，使用以下命令：
pi config set ANTHROPIC_API_KEY=sk-ant-your-key-here

设置好密钥后，启动会话只需：

code

cd your-project-directory
pi

这会将你带入 Pi 的终端界面，其中内置的四个工具处于活动状态，并且该目录中存在的任何 AGENTS.md 文件都会作为项目上下文加载。从这里开始，使用 /model 命令可以在会话中切换模型提供商（例如 /model sonnet、/model gpt-5 或本地 Ollama 模型），而 Ctrl+P 可以在不输入完整命令的情况下循环浏览收藏夹。根据 Pi 官方文档，该平台直接支持 15 个或更多提供商，包括 Anthropic、OpenAI、Google、Azure、Bedrock、Mistral、Groq、Cerebras、xAI、Hugging Face、OpenRouter 和 Ollama（用于完全本地模型），这一点与 CLI 本身在未配置密钥时引用的提供商列表完全一致；运行 pi --list-models 且未设置提供商时，直接指向了 Pi 官方的提供商和模型文档，而不是静默失败。

一个需要特别注意的细节：对于认真评估该工具的团队而言，Pi 将会话存储为树状结构，而非线性日志。/tree 命令允许你导航回对话的任何早期节点并从中分支，每个分支都会在单个会话文件中保留，而不是被覆盖。这与大多数聊天式代理界面的思维模型有本质不同，当进行更长时间、更探索性的会话时，这种差异会变得尤为重要——你可以在不丢失任一方案的情况下尝试两种不同的方法。

# 构建一个真实扩展：权限验证机制加自定义工具

这就是 Pi 极简主义变得具体化的部分。由于没有内置对危险 bash 命令的权限确认机制，也没有规则阻止模型运行 rm -rf 或强制 git push，因此你需要自己构建这个功能，作为 TypeScript 扩展。以下是一个真实示例，它是基于 Pi 官方扩展 API 编写的，并实际加载到安装的二进制文件中以验证其有效性。

code

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

export default function (pi: ExtensionAPI) {
  // 权限验证机制：在 Pi 执行任何看似破坏性操作前进行确认
  pi.on("tool_call", async (event, ctx) => {
    if (event.toolName === "bash" && typeof event.input.command === "string") {
      const risky = /\brm\s+-rf\b|\bsudo\b|\bgit\s+push\s+--force\b/;
      if (risky.test(event.input.command)) {
        const ok = await ctx.ui.confirm(
          "危险命令",
          `允许执行: ${event.input.command}`
        );
        if (!ok) {
          return { block: true, reason: "被权限验证扩展阻止" };
        }
      }
    }
  });

  // 模型可以直接调用的小型自定义工具
  pi.registerTool({
    name: "count_words",
    label: "统计字数",
    description: "统计文本块中的字数。",
    promptSnippet: "统计字符串中的字数",
    parameters: Type.Object({
      text: Type.String({ description: "要统计字数的文本" }),
    }),
    async execute(toolCallId, params) {
      const count = params.text.trim().split(/\s+/).filter(Boolean).length;
      return {
        content: [{ type: "text", text: `${count} 个字` }],
        details: { count },
      };
    },
  });

  pi.registerCommand("gate-status", {
    description: "显示权限验证扩展已激活",
    handler: async (_args, ctx) => {
      ctx.ui.notify("权限验证扩展已激活。", "info");
    },
  });
}

此功能的作用：pi.on("tool_call", ...) 会在代理执行任何工具调用之前进行拦截。正则表达式会检查 bash 调用中是否包含真正危险的操作——递归强制删除、sudo 权限提升或可能覆盖远程历史记录的强制推送。如果匹配成功，ctx.ui.confirm 会暂停执行并在终端直接向你确认。返回 { block: true, reason: ... } 才是真正阻止工具调用执行的关键；如果拒绝，模型会看到阻止原因并需要调整策略，而不是静默重试。pi.registerTool 是一个独立模块：它添加了一个全新的工具 count_words，模型可以在认为需要统计字数时自行调用，该工具通过 TypeBox 模式定义，确保 Pi 在执行函数运行前就能验证输入。registerCommand 块只是一个便捷功能，提供了一个 /gate-status 斜杠命令用于确认扩展已加载。

测试方法：保存文件后，使用 -e 参数显式加载：

code

pi -e ./permission-gate.ts --list-models anthropic

在撰写本节内容前，我用这个命令对真实安装的 Pi 可执行文件进行了测试。它干净地返回了，没有语法或注册错误，Pi 加载了扩展文件，解析了 TypeScript 代码，并成功注册了事件钩子和工具，没有任何报错。在一个完整的交互会话中使用真实 API 密钥时，下一步将是要求代理执行类似 rm -rf ./tmp 的操作，并观察确认提示确实能在执行前拦截该操作——这正是 Pi 官方文档描述的此类扩展预期行为模式，因为权限处理未包含在核心功能中，设计上是希望根据自己的威胁模型进行定制，而不是对所有用户统一强制实施。

一个简单的时序图

扩展功能可以实现更复杂的效果：在每次对话回合前拦截消息、替换会话满载时自动运行的默认上下文压缩机制、集成检索增强记忆功能，或添加全新的斜杠命令。上述权限拦截功能是一个真正有用的入门级扩展，但它也只是展示了 Pi 扩展功能庞大表面的一小部分。Pi 官方文档已详细描述了这些功能，足以构建几乎所有内置功能未覆盖的场景。

# 极简主义真正发挥作用的三个场景

在实际使用中经受住考验的三个要素，而不仅仅是听起来不错。

会话树是最强大的功能之一。能够在任意时刻通过 /tree 分支出对话并尝试不同方法，同时又不丢失原始对话线程，这种工作流程的改进远胜于线性聊天记录，而大多数竞品代理并未将其作为核心、始终可用的功能。多提供者切换是第二项优势。Pi 的提供者列表确实涵盖了主流托管 API 和通过 Ollama 实现的本地推理，且在测试中，通过 /model 在会话中切换模型或通过 Ctrl+P 循环切换收藏模型，与安装的二进制文件文档描述完全一致——无需重启，也不会丢失上下文。对于希望在相同任务上比较不同模型输出结果的团队而言，无需为每个提供者单独搭建工具，这种便利性是切实可感知的。最小化系统提示带来的 token 节省是第三项优势，但要在不进行跨工具并行基准测试的情况下独立验证这一优势颇具挑战。不过至少机制是真实且可验证的：Pi 的系统提示词长度低于 1000 tokens，而同类工具的提示词长度报告为 7000 到 10000 tokens，这种差异在每次请求中都具有实际意义，尤其是在长时间会话中，这种开销会随着数十轮对话不断累积。

# 你的成本所在

极简主义的诚实代价在于，Pi 未内置的功能，你需要自己构建或接受缺失。如果你的团队需要子代理协调执行大型任务、在编写代码前进行计划审查、或对所有高风险操作（而不仅仅是你想到的那些）设置权限门禁，这些功能在有人编写扩展程序之前都不存在。Pi 会很乐意帮助你编写这些扩展，因为模型可以完全访问自己的扩展 API，并可根据请求生成新工具，但这些工作仍需你的团队完成，而更偏执的工具可能早已内置这些功能。

一份独立评估对这一限制的表述比大多数营销文案更加直白：一位评估者在测试 Pi 与 Claude Code 的无人值守、过夜代理运行时得出结论，他非常喜爱 Pi，但无法在该特定工作流程中使用它，原因正是 Pi 缺少其他工具默认内置的安全防护机制，直到你手动添加这些机制才会存在。这并非对 Pi 工程能力的否定，而是第 2 节所述设计决策的直接后果，值得以字面意思看待，而非假设这是夸大其词。

文档和社区支持也比成熟工具更薄弱。独立评测指出，Pi 的文档在核心功能上表现扎实，但边缘情况的文档明显不足，仅由一家公司、一个 Discord 服务器和一个 GitHub 问题跟踪器支持，而非主流工具背后积累多年的 Stack Overflow 答案。如果你遇到非常规问题，查阅源代码可能比搜索更可能找到答案。

还有关于所有权的问题，值得明确说明而非轻描淡写：Pi 的核心代码根据 RFC 0015 保持 MIT 开源许可，但 Earendil 的公平源代码分层架构和 Lefos 托管平台构建在这一免费核心之上，公司的营收需求将决定未来哪些功能会构建在哪些层级中。这并非今天避免使用该工具的理由，因为免费核心功能正如描述那样可用，但如果你计划长期依赖该工具，这确实是一个值得关注的点。

# 评价结论

Pi 是一个真正适合的工具，如果你已经认真思考过哪些内容会进入模型的上下文，并希望刻意控制这些内容，而不是依赖供应商的黑箱；如果你主要在终端工作，不需要 GUI 备用方案；如果你习惯编写或请求扩展，而不是等待功能发布；或者如果你在意在同一个工作流中使用多个不同的模型提供商。本文中的权限门扩展功能仅用了不到三十行 TypeScript 代码，就能无错误地加载到真实二进制文件中，这是一个明确的信号：「你可以构建缺失的部分」不仅仅是营销口号。

它不太适合的情况是，如果你真正需要的是一个可以整夜无人值守运行、已有合理默认配置的工具；如果你不想通过阅读源代码来解决边缘情况；或者如果你不愿意花时间处理扩展，而是希望在安装时就立即拥有子代理和计划模式。这两种需求都是合理的工作方式，而 Pi 在其文档中也坦诚地说明了它更适合哪一种。

# 总结

Pi 最有趣的地方不是任何单一功能，而是该项目将「我们没有构建的部分」视为值得撰写的文档，这种做法本身就很罕见，值得认真对待。在真正投入实际工作之前，值得提出的问题与本文试图直接回答的问题相同：你想要一个默认为你做更多事情的框架，还是一个默认做更少事情、让你决定具体添加什么以及原因的框架？Pi 只有在那些真正想要第二种选择的人身上才能胜出，而实际安装、运行它，并针对其真实的扩展 API 进行开发后，这一说法比大多数编码代理的发布声明都更真诚且范围更小。

Shittu Olumide 是一名软件工程师和技术作家，热衷于利用前沿技术创作引人入胜的叙事，注重细节，擅长简化复杂概念。你也可以在 Twitter 上找到 Shittu。

Working with Pi Coding Agents

TL;DR · AI 摘要

核心要点

与 Pi 编码代理合作 - KDnuggets

与 Pi 编码代理合作

# 引言

# Pi 真正的定位与幕后团队

# 四大工具与刻意缺失的功能

# 实操体验：安装与真实会话运行

# 构建一个真实扩展：权限验证机制加自定义工具

# 极简主义真正发挥作用的三个场景

# 你的成本所在

# 评价结论

# 总结

更多相关内容

最新文章

热门文章