Agent 拼装台 Pi｜从入门到榨干
如果你平时会刷 GitHub、X，或者关注那些整天折腾 Agent 的程序员，可能已经不止一次见过 Pi 这个名字。
奇怪的是，它很少被完整介绍。更多时候，别人只是顺手提一嘴，接着就开始聊扩展、工作流和自己的 Agent。再往里看，还有人给它做桌面版、接进 Telegram，甚至塞进智能眼镜。
那种感觉很像：一群人已经玩到下一层了，你却还没弄明白入口在哪。Pi 到底藏着什么，为什么这些最爱折腾工具的人愿意一直围着它造东西？
可真正第一次打开 Pi，你多半又会愣一下：就这？
没有塞满按钮的侧边栏，没有默认开启的计划模式和子 Agent，模型能直接使用的基础工具也只有四种。
但这正是 Pi 最有意思的地方。
Claude Code、Codex 更像装修好的工作室，打开就能干活。Pi 更像一张可以自己改造的工作台：今天接 Codex，明天换成本地千问；缺少一个工具，就让它给自己装上；同一个问题有两种思路，还能从中间分出两条路分别尝试。
Pi 自己不负责“变聪明”。真正思考的是背后的模型。它负责的是另一件事：让你决定模型在哪里工作、能用什么工具，以及这套工作方式最后长成什么样。
这篇按第一次使用的真实顺序来写：先看懂这张工作台，再跑通一个有用的任务，然后尝试多模型分叉，最后看看它怎样慢慢长成只属于你的 Agent。
目录
第一阶段｜认识 Pi：它为什么和常见的编程助手不一样
Pi 是模型干活的工作台
我们平时说“Codex 会写代码”“Claude 会读项目”，容易把模型和工具混在一起。
可以把模型理解成一个负责思考的人。它本身看不到电脑里的文件，也不能凭空点开终端。外面的 Agent 工具负责把文件递给它，再把它的决定变成读取、修改和运行命令。
模型是干活的人，Pi 就是它面前的工作台。
专业资料里会把这类东西叫作 Agent Harness。英文不用背，记住“模型干活的工作台”就够了。
这也解释了一个常见误会：Pi 不是一颗比 Claude 或 Codex 更强的新模型。它更像一个中立的外壳，可以接入 OpenAI、Anthropic、Gemini、Kimi、MiniMax、Hugging Face、本地模型等不同选择。
四件工具，为什么反而跑得更轻
Pi 默认只给模型四种基础动作：
- 读取文件；
- 写入文件；
- 修改文件；
- 运行终端命令。
读取、修改和运行命令，已经覆盖了 Coding Agent 最常用的工作循环。搜索文件、执行测试、调用其他程序，也可以通过终端继续完成。Pi 没有把每一种动作都做成常驻工具。
这会直接影响模型怎样干活。每轮对话开始前，Agent 都要把自己的规则、工具说明和聊天记录交给模型。工作台越重，这本“使用说明书”越厚；真正留给项目的注意力和上下文就越少。
这项取舍已经在真实代码任务里表现出了差距。
Databricks 用自家数百万行代码库里的真实改动做测试。固定同一模型和思考档位，只更换 Claude Code、Codex 与 Pi 这些工作台，部分组合的单任务成本相差超过两倍，质量却基本相同；Pi 每轮送给模型的上下文大约少三倍。
Fullscript 的工程团队又用同一颗 Sonnet 跑了 36 个任务。Pi 完成 22 个，Claude Code 完成 18 个；输入 Token 从 6190 万降到 3530 万，总成本从 35.28 美元降到 22.66 美元。代价也很明确：Pi 平均更慢。
两次测试的任务和方法都有限，不能替所有人宣布冠军。它们至少证明了一件值得重视的事：模型没有变化，外面的工作台依然会改变成本、速度和结果。Pi 的“轻”因此有了实际价值。
核心很小，上限却很高
Pi 把模型、工具、规则、界面和工作流拆成了可以替换的零件。默认核心保持干净，需要计划模式、子 Agent、联网搜索或权限确认时，再安装现成功能，或者让 Pi 按你的要求做一个。
这套思路已经长出了真实生态。Pi 官方支持 15 家以上的模型服务和数百个模型；Pi 作者 Earendil 表示，使用者已经互相分享了 5000 多个 Extension；开源仓库也已经获得超过 10 万 Star、1.2 万次 Fork。
·
·
这些数字更像一张上限证明：四件工具只是出厂状态。你可以在同一张工作台里换模型、保留分叉会话、加入自己的 Skill 和 Extension，再把整套配置打包带走。
官方把这种设计叫作“Primitives, not features”。说人话就是：先给通用零件，具体要装成什么，由你决定。
先判断它适不适合你
如果你有下面这些需求，Pi 很值得研究：
- 想在云模型和本地模型之间自由切换；
- 不希望每次换工具都重新交代整个项目；
- 想把经常重复的工作方法保存下来；
- 希望工具能按自己的习惯继续生长。
如果你只想登录后立即得到一套安排好的体验，Claude Code、Codex 等成品会更省心。
Pi 最适合那些已经开始形成自己工作习惯、又不想被现成工具限制的人。只想登录后立即开工，前面的成品工具反而更轻松。
第二阶段｜跑通 Pi：先拿到一份有用结果
安装 Pi，并接上一颗模型
Pi 需要 Node.js 才能运行。先从
安装长期支持版，重新打开终端，再依次运行：
1 | node --version |
不用理解每个英文单词。四行分别是在检查运行环境、安装 Pi、确认版本、打开 Pi。看到版本号，才算安装成功。
Pi 是工作台，还要接上一颗真正负责回答的模型。
本文走最容易复刻的一条路：打开 Pi 后输入 /login，选择 ChatGPT Plus/Pro (Codex)，再按浏览器提示完成登录。回到 Pi 输入 /model，选中 Codex；底部出现模型名称，说明它已经接通。
没有 ChatGPT Plus 或 Pro，也可以选择自己已经拥有的模型服务。第一次只接一颗，先别把精力耗在模型大全上。
第一次只认三个位置
打开 Pi 后，先认三处：
- 中间的输入区：在这里说你想做什么；
- / 命令入口：在这里换模型、找回会话和打开其他功能；
- 底部状态栏：在这里确认当前使用的是哪颗模型。
这时候不用背快捷键。先让它替你完成一件本来就想做的事。
在项目文件夹里，直接打开 Pi
Pi 不需要你上传或导入项目。在哪个项目文件夹里启动，它就从哪里开始工作。
最快的打开方式只有两步：先在项目文件夹里打开终端，再输入 pi。
- macOS：在访达里右键项目文件夹，选择“服务 → 新建位于文件夹位置的终端窗口”；
- Windows：在资源管理器里打开项目文件夹，点击顶部地址栏，输入 powershell 后按回车。
Pi 打开后，当前文件夹里的代码、文档和项目命令就成了它的工作现场。你可以直接说想解决什么，不用复制文件，也不用重新介绍目录结构。
第一次进入重要项目，先留一份备份或 Git 提交。Pi 拥有真实的修改和命令权限，接下来就可以让它正式干活了。
先看方案，再允许它修改
第一次别让它直接“大改整个项目”。挑一个边界清楚、完成后能亲眼看见的需求，例如修复一个已经发现的问题、调整一个页面，或者补上一项缺失的小功能。
先这样告诉它：
我想让这个项目做到：____。请先找到直接相关的文件，用通俗中文告诉我现在的问题、准备修改哪里，以及改完以后我去哪里确认。先不要修改，等我确认。
一份靠谱的方案，至少要说清楚三件事：准备动哪些文件、为什么要改、改完去哪里看结果。
方案没跑偏，再让它开始修改：
按刚才的方案执行，只动已经列出的文件。完成后告诉我具体改了什么，以及我应该去哪里检查。
让 Pi 把改动和检查结果摆出来
Pi 会把读取文件、修改内容和运行命令的过程留在会话里。任务完成前，再让它主动跑一遍检查：
完成后请运行项目已有的检查，并在最后告诉我三件事：改了哪些文件、运行了什么检查、结果是否通过。如果改的是页面，再告诉我从哪里打开最终效果。
它可以自己运行 git diff –stat 列出真实改动，再运行项目测试，把结果直接显示出来。你不用逐个打开文件重新检查，只要看清改动清单、测试结果和最终入口。
最后再打开页面或实际功能看一眼。这里检查的是最终效果，无需重做 Pi 刚才的全部工作。
这样交到你手里的会是一组能核对的结果：哪些地方变了、检查有没有通过、最终成果在哪里。到了下一阶段，即使两颗模型都说自己完成了，你也能根据这些证据判断谁更可靠。
到这里，你已经跑通了 Pi 的基础用法。下面不再重复“让 Agent 读文件、改文件”，而是进入 Pi 更有辨识度的部分。
第三阶段｜用好 Pi：让不同模型从同一个起点出发
什么时候值得换一颗模型
不同模型擅长的事情不一样。
有的便宜、速度快，适合查文件和整理信息；有的更贵、更慢，但面对复杂判断更稳；本地模型不需要把内容交给云端，却更吃电脑性能。
Claude Code、Codex 这类厂商工具，通常围绕自家的模型设计。Pi 从一开始就把模型当成可以更换的发动机：同一张工作台，可以接 Codex、Claude、Gemini，也可以接电脑里的本地模型。
真正用久以后，还有两个很顺手的控制：
- 模型太多，可以输入 /scoped-models 选出常用名单，以后按 Ctrl+P 就能在几颗常用模型之间循环；
- 只想调整同一颗模型的思考力度，可以输入 /thinking 选择档位，按 Ctrl+S 保存为启动默认值；工作中按 Shift+Tab，还能随时切换档位。
换模型像换一个人，切换思考档位更像让同一个人快点回答，或者多想一会儿。查文件和小修改可以轻一点，架构判断、疑难故障再调高，不必每次都用最重的档位。
再记住四个日常动作就够了：Ctrl+L 打开模型列表，Ctrl+O 收起或展开工具过程，Ctrl+T 收起或展开思考过程，Alt+Enter 留下一条等当前任务全部做完再处理的后续消息。进入 /tree 后，Ctrl+O 才会改成循环切换会话树视图。想看完整清单，直接输入 /hotkeys；这些按键也都可以自行修改。
这次演示使用已经接入本机的 Qwen3 8B（本地） 和 Codex。你没有安装本地千问也没关系，只要 Pi 里有第二颗可用模型，操作逻辑完全相同。
怎样从同一个位置分出两条路线
有时事情确定要做，真正拿不准的是该走哪条路。直接让第一颗模型修改，之后再换模型，第二颗模型看到的已经是被改过的现场，比较就不公平了。
Pi 的 /tree 可以把会话变成一棵树：回到某条需求发送之前，再从那里长出另一条路线。前面的背景不用重新复制，第一条思路也不会消失。
会话变长以后，可以把 /tree 当成一张有路标的地图：
- 进入 /tree，选中真正重要的节点，按 Shift+L 标成“共同起点”“Codex 方案”或“千问方案”；
- 按 Ctrl+O，在默认、隐藏工具、只看用户、只看标签和全部内容之间循环切换；
- 分支太多时按 Ctrl+L，整棵树会收起杂讯，只留下标记过的检查点。
这篇的演示也可以照这个顺序来：先给共同需求加标签，再分别标记两颗模型的答案，最后折叠到只剩三个检查点。长对话不会再变成一堵找不到起点的文字墙。
我用一个真实问题演示：一张 AI 模型盘点长表格里，标题、留白和装饰占比太高，真正重要的表格反而太小。为了只比较判断，我还明确要求两颗模型不要调用工具、不要动文件。
先让 Codex 只给方案，不改文件：
请直接设计一张横屏表格截图，不调用工具、不查看文件、不执行命令。表格至少占画面高度的 80%，保留完整的 5 列 6 行，同时留下短标题和诺鸭 IP。只给一个最佳方案，并说清楚三个肉眼可见的验收结果。
Codex 回答后，输入 /tree，回到这段需求发送之前。再用 /model 换成本地千问，把同一句话重新发一次。
现在，两颗模型看到的是同一个项目、同一个问题、同一个起点。区别只剩下它们各自给出的路线。
选一条继续，另一条保留
这里不是给模型做排行榜，只判断哪条路线更适合眼前的任务。
对这张表格，我只看三个问题：谁真正抓住“表格必须是主体”；谁能保留表头和 IP 又不让它们抢空间；谁给出的检查方法更直观。
这次 Codex 给出了更具体的尺寸，而且没有多做动作；本地千问也抓住了“表格优先”，却顺手把答案写进了文件。分叉会把两种真实行为都留下，你可以看完再选更适合当前任务的一条。
选好以后，在 /tree 中回到那条分支，让对应模型继续修改。另一条路线仍然保留，以后随时可以回来查看。
这个方法不只适用于表格。写功能时可以比较两种实现，修故障时可以保留两种判断，策划内容时也可以让两颗模型从同一份资料出发。
还有一种更实用的组合：让一颗模型负责动手，再换另一家模型负责检查。不同厂商的模型有不同的习惯和盲区，交叉复核更容易发现第一颗模型漏掉的问题。项目、规则和前面的工作记录仍留在 Pi 里，不用重新搬家，也不用从头交代背景。
有一个边界必须记住：会话树能找回聊天路线，不能自动把电脑文件恢复到修改前。因此两条分支先比较方案，选定以后再真正动文件。
Pi 的价值来自两项能力的组合：模型可以换，工作现场又能回头和分叉。不同模型因此能从同一个起点出发，也能在同一件事上接力。
第四阶段｜榨干 Pi：让它慢慢长成你的 Agent
重复要求应该放在哪里
Pi 用久以后，你会不断重复三类话：这个项目有什么规矩、遇到这类任务该按什么步骤做、某些危险动作能不能自动拦住。
它们不该全部塞进一段越来越长的提示词。
先用最简单的方式区分：
- 项目规则：告诉 Pi“在这个项目里必须记住什么”，放进 AGENTS.md；
- Skill：告诉 Pi“这类事情通常应该怎样做”，适合跨项目重复使用；
- Extension：不再提醒模型，而是直接改变 Pi 的行为。
项目规则和 Skill 在其他 Agent 里也很常见。这里真正拉开差距的是最后一层：Pi 把自己的工具、界面和操作过程都开放了出来。
让 Pi 改造自己的工作方式
假设你经常担心 Agent 误删文件。
写一句“删除前记得问我”，只是提醒模型；它仍然可能忘记。Extension 更像在工作台上加一道真正的门锁：每次准备删除文件，Pi 先弹出确认；你选择取消，删除就不会发生。
初学者不需要读 TypeScript，也不用手写代码。你只需要把需求说清楚：
请给 Pi 增加一个保护：删除文件之前，先显示准备删除的文件并让我确认。先告诉我这个功能保存在哪里、以后怎样关闭；等我确认后再创建。
Pi 可以替自己写出这项改造。加载后，它面对任何模型都会继续生效。
重复流程还可以缩成自己的斜杠命令。比如把部署步骤做成 /deploy：它会出现在命令菜单里，输入环境名称时自动补全，确认后再运行真正的部署流程。背后的命令说明、参数补全和执行逻辑不需要初学者手写，也可以先让 Pi 按现有流程生成，再由你确认。
Shopify 的 David Cortés 做过一次更有说服力的实战。他直接让 Pi 为
制作 Extension。Pi 读取自己的扩展文档，不到半小时就搭出了第一版：提出假设、修改代码、测量指标，变快就保留，变慢或报错就撤回，然后继续下一轮。
Shopify 后来把这套循环用在 40 多项指标上，公开案例包括单元测试最高提速 300 倍、React 组件挂载提速 20%。这已经超出了“给 Pi 多装一个按钮”：使用者可以把一种新的工作方法做成 Pi 的能力，再交给整个团队复用。
删除确认只是最容易看懂的一种改造。社区里更成熟的玩法，已经开始改变整条工作方式。这次我没有只看 README，而是在同一个项目里真装了两个。
第一个是
。你可以先给每位帮手分好角色、模型、工具和 Skill，主 Agent 负责派工和收结果。这比多开几个聊天窗口更接近真实分工。
我给 Pi 添加了一位专门审稿的 Article-Auditor，并让它加载现有的 noah-write Skill。当主 Pi 请它检查“扩展项目有没有讲明读者收益”时，它自己读文章、完成审查，指出 Picot、智能眼镜和后台嵌入三处只有功能名，却没有获得感。
它最适合那些会重复出现的角色：研究员、执行者、审稿员。只是一次性的小任务，没必要为了“看起来像团队”硬拆；当你需要不同角色各自带着固定方法工作时，它才真正省事。
第二个是
。普通终端命令跑完就结束，但开发服务器、数据库、远程连接这些程序会一直开着，期间还可能等人输入。这个扩展会把它们放进一个看得见的窗口：Pi 先盯着，你想接手时直接敲键盘。
我让它启动练习项目的本地预览服务。界面里能看到真实命令、运行状态和“随时接管”的入口：
它让 Pi 能处理“需要等、需要看、中途还可能需要人接手”的工作，开出的这个窗口只是人机交接处。
则更适合已经稳定接入多个模型的人：先用快速便宜的模型扫描，遇到复杂问题再自动升级。我这次没有急着装，因为本地千问仍放在演示项目的独立配置里，日常 Pi 只接了 Codex。只有一条稳定路线时，先装“自动切换”并不会带来真实收益。
所谓“可改造工作台”，就是 Pi 既能改项目，你也能改它接活、分工和行动的方式。
但也别把“可以改”理解成“可以随便装”。Extension 能直接操作电脑。自己写的要测试，别人发来的要先看来源；越强的能力，越需要清楚它会碰什么。
把改造好的工作台打包带走
当一套 Extension、Skill、提示词和界面样式已经配合顺手，可以把它们装进一个 Pi Package。
Package 可以理解成“整箱工具”。换一台电脑、换一个项目，或者分享给团队时，不必再把零件一个个装回去。
社区里已经出现了两种很有代表性的整箱方案。它们适合的起点不同，选一种就够了。
适合已经深度使用 Claude Code 的人。项目里已经写好的规则、命令、Skill、Hook、MCP 和 Agent，可以继续交给 Pi 使用。换工作台时，过去积累的方法不用全部重建。
更适合从零开始、想先拿到一套完整工作台的人。它像 Pi 版的 oh-my-zsh，一次装进任务管理、后台任务、子 Agent、远程会话、界面组件和现成 Skill。代价是你会一次接手很多别人的选择；如果你已经有自己的 Skill 和工作方法，反而应该先少量安装。
这也形成了一个很有意思的生态：Pi 故意把核心保持得很轻，社区因此开始分享一整套工作方法。单独一段提示词已经装不下这些东西，完整方案可以直接从
继续找。
Pi 还可以住进别的软件里
终端只是 Pi 自带的入口。开发者可以把同一套模型、工具和会话能力放在后台，再为它换一层适合具体场景的外壳。这样就能复用 Pi 的 Agent 后端，不必从零再写一套。
已经有人通过
把 Pi 接进 VS Code。它能知道你正在看哪个文件、选中了哪几行、编辑器报了什么错，你不必再把这些内容复制进聊天框。
不喜欢终端的人，可以看
。它把 Pi 变成桌面应用，用聊天窗口发任务，用修改对比审查代码，还能把不同思路留在多个会话与分叉里。终端门槛因此低了很多，Pi 内核本身没有改变。
则解决了另一个问题：人离开电脑后，仍然可以在 Telegram 里派活、传文件和收结果。
最夸张的
实验把 Pi 放进了智能眼镜：回答显示在镜片上，戒指负责输入，电脑里的 Pi 继续调用模型和工具。这更像一个“Pi 能被塞到哪里”的边界实验，而不是普通用户现在就应该安装的推荐。
这些项目使用的是同一套 Pi 内核，只是换了不同的入口。普通读者记住这一点就够了：以后遇到某个 Agent 产品时，你看到的界面可能只是外壳，下面负责干活的也可以是 Pi。
最后：为什么有人会越用越离不开 Pi
Pi 最容易被误解成“一个功能不太完整的 Claude Code”。
换一个角度，它更像 Agent 世界里的乐高底板。
刚装好时，它只是一张有四件工具的工作台；接入不同模型以后，它能更换负责思考的人；用会话树保留不同路线以后，它能容纳探索；加入项目规则、Skill 和 Extension 以后，它才慢慢长成你的工作方式。
它不一定是第一次使用 Agent 时最省心的选择，却可能是产生了自己方法以后，最不愿意被工具限制的人会喜欢的选择。
这就是我对 Pi 最准确的定位：
一张不替你决定工作方式，却能陪你长出自己工作方式的 Agent 工作台。
