刷屏的11万星Agent，一篇搞懂它是干嘛的

原创

大白
大白

知白守黑1024

2026年10月8日 06:17
北京

在小说阅读器读本章

去阅读

在公众号小说中沉浸阅读

这两年的编程 Agent，默契地朝一个方向跑：功能越多越好。子智能体、计划模式、权限系统、几十个内置工具，谁加得少谁像落后。

Pi 反过来走。它默认只给你四个工具，没有子智能体，没有计划模式，连权限系统都不做。官方文档里写得很直白：「让 Pi 适应你的工作流，而不是反过来」。

结果这个「什么都少」的项目，拿了113,137 个 Star，npm 上周下载520 万次，1.0 版本发布当天冲到 Hacker News 榜首、拿到 1000 多分。它是 MIT 协议，仓库还在高频更新，我写这篇的时候主分支当天有提交。

这篇就拆两件事：它凭什么靠「少」赢，以及那个「少」到底够不够用。

01

先说清楚它是个什么物种

Pi 对自己的定义是agent harness——直译是「智能体挽具」。这个说法很准确：它自己不生产智能，干活的是你接进去的模型；它负责的是挽具该干的事，把模型的输出变成真能在你机器上跑起来的动作。

具体管四件事：根据当前对话和可用工具拼出请求；把模型返回的工具调用真正执行掉；把过程和结果存成会话；把这一切渲染在终端里。官方的说法是「一个你能改成自己的最小可扩展挽具」。

整套东西的构成，从你操作的入口到它干活的能力层，大致是这么分层的——最左边是三种入口（终端、Web 界面、脚本），中间是负责转圈的核心循环和会话管理，右边是模型和工具这些「能力」，最底下是插件化的运行时底座：

启动起来长这样——上半屏列出它加载了什么（上下文文件、技能、提示词模板、扩展、主题），中间是你的输入和它的动作，底下一行是状态栏：当前目录、模型、上下文用量、以及这次会话烧了多少钱（截图里是 0.076 美元）：

图1： 启动时会把它加载到的资源全部列出来

注意状态栏那行读数的密度：本会话累计读了多少 token、写回多少、缓存命中多少、上下文本轮用了几个百分点、折合多少钱，全部实时摆在一行里。截图里这个会话累计跑了 14k 输入、206 输出，花了 0.076 美元。把它拉长放在常显位置，好处是你随时知道这一轮有多贵。

02

谁在做它：libGDX 作者加 Flask 作者

Pi 的作者是奥地利开发者Mario Zechner，社区里更熟的名字是 badlogic——他是 Java 游戏框架 libGDX 的作者，也在 OpenClaw 项目里干活。Pi 最初是他一个人的项目。

2026 年春天，这个项目被Earendil收购。这家公司 2025 年成立，创始人是 Armin Ronacher（Python Web 框架 Flask 的作者，此前长期担任 Sentry 维也纳的工程负责人）和 Colin Daymond Hanna（此前在 Balderton 做投资）。Mario 作为收购的一部分成为股东和团队成员，继续负责技术方向。投资方名单里有 Accel、Balderton，以及 n8n、OpenClaw、Revolut、Sentry、Slack 的创始人。

收购后包名从@mariozechner/\换到了@earendil-works/\，核心保持 MIT 协议。公司的说法是核心会永久开源，付费的部分放在外围的云服务和附加组件上。

资本进来之后，Pi 也没被改成「什么都有」的样子。1.0 的新闻稿里有一句挺有意思：团队说候选的新功能讨论了几个月，「被砍掉的清单比留下的长得多」。这句话解释了它为什么到今天还只留 4 个工具——那是刻意守住的边界，不是没来得及做。

03

它的「少」，具体少在哪里

先看它的工具清单。仓库里一共内置了八个：read、bash、edit、write、grep、find、ls、powershell（Windows 用）。但默认只开四个——读、跑命令、改文件、写文件。

四个之外要自己开。设置里可以写+grep加上搜索，写-bash +powershell换掉命令执行。命令行也支持pi --tools read,grep,find,ls这样临时收窄，只给它看代码、不许它动手。

真正反直觉的是它主动不做的那几样。官方 README 里点名了：不做子智能体，不做计划模式。另一份安全文档里又明确写了：不含内置的权限系统，不会在每次工具调用前问你一句「这个能跑吗」。

这三样恰好是同类工具最爱宣传的卖点。Pi 的判断是：这些应该由使用者自己决定要不要，而不是硬塞进核心。想加就写扩展，或者装一个别人写好的包。

04

把「少」撑成「够用」的五层机制

「少」不等于「弱」，前提是得有一套让人自助加功能的梯子。Pi 给的梯子有五级，官方特意强调了一句使用原则：能用轻的解决就别上重的。

图2 ：五级扩展梯子，越往下能改的东西越多、成本也越高

其中最有意思的是第四级的扩展（Extension）。它是一个 TypeScript 模块，跑在 Pi 自己的进程里，能注册工具、命令、快捷键，也能监听生命周期事件——比如「每次跑 bash 前拦一下，危险的命令先确认」。仓库里带了80 个扩展示例，从打招呼、状态栏、限流确认这种小玩意，到下面这个……

图3 ：一个把 DOOM 跑进终端面板的扩展，还能用 WASD 操作

对，有人在 Pi 的终端界面里开了个窗口玩 DOOM。同一套扩展 API，能写限流保护，也能写游戏。仓库里还有贪吃蛇、太空侵略者和井字棋——都是官方示例，用来演示「这个接口到底能伸多长」。

第五级的 Pi package 是把上面几样打包分发。声明pi-package关键字就能进官方包画廊，一条pi install npm:xxx装进别人的机器。到今年 5 月，社区里的第三方扩展已经有 2000 多个。

05

最值得看的一段：它公开拒绝过 MCP，后来又自己打脸

这是我觉得这个项目最诚实的地方。

如果你去年访问 pi.dev，会看到一句骄傲的声明：Pi 不支持 MCP。Mario 还专门写过一篇文章，标题就叫《What if you don't need MCP》。上播客聊到 MCP，他的态度是 dismissive——理由也站得住：MCP 的工具往上下文里一堆塞，token 消耗大，还不好组合。

今年 9 月 29 日，Earendil 发了一篇博客，标题直接把这句话甩回自己脸上：《You Said No MCP!》。里面解释了三件事。

第一，MCP 本身变了。协议进化了一年，今天的不再是去年那个。但这一条还不够，团队说：光靠这个不足以让它进核心。

第二，也是更关键的：让 Pi 支持 MCP 所需要的那套改造，本身就是有用的。为了接 MCP，Pi 需要造一个「解释器沙箱」来编排工具调用；而 Pi 想接另一类模型（比如只做分类、不聊天的模型），需要的恰好是同一个东西。两边需求撞在了一起，那就一起做。

这个东西叫Codemode。它是个跑在 harness 侧的 JavaScript 沙箱：模型不再一个一个调工具，而是写一段脚本，把多个工具调用组合起来一次性执行——在哪一步并行、怎么循环、结果怎么聚合，全由脚本决定。因为它跑在 harness 侧，状态跟着会话走，不落文件系统。

官方给了一个很能说明问题的例子：让它「用 Codemode 找出我们 issue 跟踪器里最暴躁的那批人」。它会拉出全部未关闭 issue，调一个分类模型给每条讨论的「情绪」打分，四个并发跑完，最后只把少数几条命中的返回给你——整个过程 331 次工具调用，主上下文里几乎没有被塞东西。

第三，是态度。博客里那句话我摘出来：「影响一件事最好的方式，是拥抱它。」他们承认 MCP 现在的服务器生态还有问题——很多服务器还在按「把工具全塞进上下文」的思路设计，返回一堆文本。他们的想法是 MCP 应该更接近 OpenAPI：工具返回结构化数据，并且能被文档和描述检索到。与其站在场边看，不如进去把它往小 harness 友好的方向推。

一个项目敢把自己一年前的公开立场翻出来检讨，还写清楚「为什么改」而不是含糊其辞，这件事本身就比 MCP 支不支持更值得关注。

06

安装和部署

前置条件只有两个：Node.js 22.19 以上（安装脚本会帮你装），以及一个模型的凭据。三条安装路径，按需要挑一条。

BASH

1) 官方安装脚本（macOS / Linux，依赖会锁定版本）

curl -fsSL https://pi.dev/install.sh | sh

Windows

powershell -c\"irm https://pi.dev/install.ps1 | iex\"

2) 或者走 npm（不锁定传递依赖）

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

3) Nix 用户（从源码构建）

nix profile add github:earendil-works/pi/stable

装完进到你要它干活的目录，直接敲pi就启动了。第一次要先连模型，在界面里敲/login，选服务商、走订阅或 API Key 都行。

BASH

验证安装

pi --version

进入项目目录启动交互界面

cd /path/to/project && pi

会话自动保存，下次接着上一次聊

pi --continue

一次性任务，跑完就退，适合接管道和脚本

git diff | pi --print\"帮我 review 这次改动\"

输出结构化事件流，给上层程序消费

pi--mode json\"看一下这个仓库的结构\"> events.jsonl

除了交互界面，它还有三种用法：print 模式跑一次就退出，适合写进脚本；JSON 模式把整个过程打成事件流；RPC 模式用标准输入输出控制一个常驻进程。再加上一个 TypeScript SDK，可以把 Pi 整个嵌进你自己的应用里——OpenClaw 就是这么用它的。

07

几组能查到的硬指标

前面说的「少」，换个角度看就是下面这张表。工具只有 8 个，但接进来的模型服务商有 33 家——从 Anthropic、OpenAI、Google 到 DeepSeek、xAI、Mistral，再到国内的 Kimi、智谱、小米、MiniMax，还有本地的 llama.cpp 和任意兼容端点。它还支持 GitHub Copilot 的订阅登录。

整个仓库拆成七个包，各管一段：pi-ai管多模型统一接口，pi-agent-core管工具调用与状态，pi-coding-agent是那个 CLI，pi-tui负责终端渲染。想看这堆包怎么协作，读how-pi-works.md那一页就够了，十分钟能读完。

配套的Pi Durable是 1.0 同期发的另一个包，还在实验阶段。它解决的是「长跑」问题：每一步都存成检查点，进程崩了、笔记本合盖了、容器重启了，都能从断点接着跑；一个 harness 还能同时跑多段对话，并在任意点分叉。源码一共一万五千行左右——团队说故意压到这个体量，好让 AI 自己能把全量代码读完再改。

08

用之前必须知道：它没有权限系统

这一节是给要动手的人看的，比前面所有功能都重要。

Pi 的 README 里有一段写在很显眼的位置：它不含内置的权限系统，不会限制文件、进程、网络和凭据的访问范围，默认就用启动它的那个用户和进程的权限跑。它不会在每次工具调用前问你一次。

它有一个叫项目信任的机制，但那不是沙箱。项目信任管的只是「要不要加载这个目录里的配置和扩展」，防止随便 clone 一个仓库就被塞进一个可疑扩展。一旦启动完成，工具该有的权限一样不少。官方文档自己也承认：看着对话、授予信任、复查改动，这些都不构成安全边界——安全边界只能来自你给它圈出多大的活动范围。

官方给了四种圈法：整个进程丢进普通 Docker 容器、用 Docker 的托管沙箱（凭据留在宿主机，出沙箱时由代理替换）、用策略可控的 OpenShell，或者只把内置工具路由进一个本地 Linux 微虚拟机、Pi 本体留在宿主机。最省事的是第一种：

BASH

建镜像：Dockerfile.pi 里装好 pi，入口设为 pi

docker build -t pi-sandbox -f Dockerfile.pi .

只在当前目录里干活，凭据用环境变量传进去

docker run --rm -it -e ANTHROPIC\_API\_KEY -v\"$PWD:/workspace\"pi-sandbox

注意别把宿主机的~/.pi/agent挂进去——那里面有你的凭据、设置和历史会话。官方文档专门提醒了这一点。

会话本身值得看一眼。Pi 把每个会话存成一个 JSONL 文件，消息和事件组织成树，树上每条路径是一个分支，你正在走的那条叫活跃分支。从历史任意一点继续聊，就是在同一个文件里长出新分支：

图4：会话树视图，左侧竖线标出分支，每个动作都留痕

这个设计的好处是试错不要钱。一条路走歪了，从岔口重新长一条，原来那条不删；上下文快满了，它插一条摘要进去顶掉旧消息，但原始记录还在树里。可以导出成 HTML 分享，也能整个 fork 出去改。

09

该不该把它放进你的终端

Pi 值 11 万星的地方，不是它功能多，是它对「不加什么」有纪律。同类工具在比谁的斜杠命令更长、谁的默认行为更聪明，它选择了把决策权还给使用者——代价是使用者得自己承担配置和边界的责任。

三类人用它会比较顺手。一是已经在用 Claude Code、Codex，但嫌它们管得太多、想自己定规矩的人；二是要把 Agent 嵌进自己系统、或者接一串本地模型和私有端点的人，33 家服务商加自定义端点这条通路确实宽；三是纯粹想读一个干净 Agent 实现的人，一万五千行的how-pi-works.md加上七个边界清晰的包，比很多同类项目好读。

反过来说，如果你要的是开箱就有十几种内置工具、每步操作都有确认弹窗、或者开箱即用的计划模式，Pi 会让你觉得什么都要自己拼。它不是那种装上就能用的产品，是那种装上之后需要你花一个下午调成自己想要的样子。

最后把那句提醒再说一遍，因为它真的会咬人：Pi 默认不设权限边界。它会在你的机器上以你的身份跑命令，而且不会每次都问你。让它碰真实项目之前，先进容器；给它用的凭据，尽量是短期、小范围的。这一条守住了，剩下的才是享受它「少」带来的爽感。