同一个模型，单任务成本相差两倍 Pi 只用 4 个核心工具 省 Token，工作流还能自己搭 10 分钟跑通你的第一个任务
Claude Code 和 Codex 已经够强了，为什么还要认识 Pi？
一个上线一年左右的终端 Coding Agent，能在 GitHub 上获得接近 10 万个 Star，已经很难再把它当成少数极客的个人玩具。
它叫 Pi。
和不断增加默认功能的 Claude Code、Codex 不同，Pi 只保留一套极简核心，再把模型、工具和工作流的选择权交还给用户。
比热度更值得关注的是它的实际表现。
Databricks 在自家数百万行代码库中测试不同 Coding Agent：使用相同模型和思考强度时，部分 Claude Code/Codex 与 Pi 组合的单任务成本相差超过两倍，任务质量却保持相同。
这不能证明 Pi 永远更强，却说明了一个经常被忽略的事实：决定 Coding Agent 表现的，不只有模型，还有模型外面的 Agent Harness。
一、这些差距从哪来？
Agent Harness，就是包在模型外面的那层系统：它决定给模型什么指令、开放哪些工具，以及如何管理上下文。同一个模型放进不同 Harness，表现可能完全不同。
Pi 把这层系统做得很薄。默认只有读文件、写文件、精确修改和执行 Bash 四个主要工具；Plan Mode、MCP、Sub-Agent、Todo 等功能，需要时再通过 Skill、Extension 或 Pi Package 添加。
这也是 Pi 与 Claude Code、Codex 最根本的区别：后两者提供完整的成品，Pi 提供一套可以自己组装的底座。
如果你已经会用 Claude Code 或 Codex，并且开始在意上下文、模型选择和工作流控制，Pi 值得一试。它的代价也很明确：默认没有内置沙箱和逐条命令审批，安全隔离需要自己负责。
下面直接从安装开始。先用 Pi 跑通一个真实任务，再决定它是否适合你。
二、先用 10 分钟跑通：安装、登录、第一次任务
Pi 是终端程序，支持 macOS、Linux 和 Windows。最稳妥的安装方式是 npm。
先检查 Node.js：
bash
node --version本文写作时，Pi npm 最新版为 0.84.3，要求 Node.js 22.19.0 或更高版本。版本不够就先升级 Node.js，再执行：
bash
npm install -g --ignore-scripts @earendil-works/pi-coding-agent--ignore-scripts 会关闭依赖安装阶段的生命周期脚本。Pi 官方说明正常安装不依赖这些脚本，因此建议带上。
安装后确认版本：
bash
pi --versionmacOS 或 Linux 也可以使用官网安装脚本：
bash
curl -fsSL https://pi.dev/install.sh | sh第一次使用不要在随便一个目录里直接输入 pi。先进入一个有 Git、没有生产凭据、改坏了也能恢复的小项目：
bash
cd ~/projects/my-app git status piPi 会把当前目录当作工作目录，但这不是访问边界。它的读取工具和 Bash 仍然可以访问当前系统账号有权访问的其他位置。“在某个项目目录启动”与“只能访问这个项目”是两回事。
登录模型
进入 Pi 后输入：
text
/login如果你已经购买 Claude Pro/Max、ChatGPT Plus/Pro 或 GitHub Copilot，可以直接选择订阅登录，不必立刻改成 API 按量付费。按界面提示去浏览器完成授权，回来后即可使用相应模型。
如果使用 API Key，也可以在 /login 中保存，或在启动前设置环境变量：
bash
export ANTHROPIC_API_KEY="你的 Key" pi真实 Key 不要写进会提交到 Git 的配置，不要贴进对话，也不要通过命令输出给模型看。
登录完成后输入：
text
/model或者按 Ctrl + L 打开模型选择器。Shift + Tab 可以循环切换当前模型支持的思考强度。
别默认拉到最高。查文件、改文案、小修复用 low 或 medium；跨模块重构、复杂 Bug、架构设计再用 high。更高思考强度通常意味着更慢和更贵，不保证更准。
第一条任务怎么写
刚进入一个项目，不要扔一句“帮我优化一下”。先让 Pi 调查，暂时不要修改：
text
先不要改代码。 请阅读 README、package.json 和 src 目录，完成以下调查： 1. 这个项目做什么； 2. 如何启动、测试和构建； 3. 当前 Git 工作区是否干净； 4. 最值得先处理的三个问题，以及判断依据。 输出调查结果后停下来。这条提示词不神秘。它只做了三件事：限制动作，规定调查范围，写明停止点。
确认方向后再让它改：
text
修复登录页在手机端按钮溢出的问题。 约束： - 不改变桌面端布局； - 不新增 UI 依赖； - 只做与这个问题直接相关的修改。 验收： - 运行现有测试和类型检查； - 检查手机和桌面两个宽度； - 最后列出根因、修改文件、验证结果和剩余风险。换了 Agent，需求表达的基本功没有变。目标、约束、验收条件写得越清楚，返工越少。
三、几个不起眼、但每天都会用到的操作
多行输入与外部编辑器
Pi 里按 Enter 会直接发送。需要换行时按 Shift + Enter。提示词很长，可以按 Ctrl + G 打开外部编辑器，写完保存并退出，内容会回到输入框。
这比在终端里小心翼翼地改几十行提示词舒服得多。
用 @ 引用文件
输入 @ 可以搜索项目文件：
text
@src/auth.ts 检查令牌刷新逻辑有没有竞态问题，先解释，不要修改。也可以启动时传入：
bash
pi @src/auth.ts @src/auth.test.ts "检查实现与测试是否一致"引用文件不是强制模型只能看这些文件，它只是把相关材料明确交给模型。若任务涉及其他依赖，Pi 仍可能继续调查。
粘贴截图
macOS/Linux 通常使用 Ctrl + V；Windows/WSL 默认使用 Alt + V。支持的终端也可以直接拖入图片。
截图最好附上可验证的描述：
text
截图中 390px 宽度下，导航栏遮住了页面标题。 请找到 CSS 根因并修复，不要顺手重做整套视觉。“这里不好看，改一下”不是需求，只是在邀请模型猜你的审美。
! 和 !!：都能跑命令，只有一个会进入上下文
在 Pi 里输入：
text
!npm test命令会在当前界面运行，输出也会送进模型上下文。测试失败后，Pi 能直接读取报错继续排查。
如果改成：
text
!!git status命令由你自己运行，输出不会加入模型上下文。
可以记成：
!：我看，模型也看；
!!：只有我看。
但 !! 不是秘密保险箱。最稳妥的做法仍然是：不要在 Agent 会话里打印密码、Token、.env 内容和私人凭据。
四、Pi 最好用的交互，不是某个插件，而是 Steer
Agent 执行长任务时，最常见的问题不是它完全不会，而是走到一半开始偏。
比如你让它给现有项目加后端，它却开始安装 Express；你真正想要的是 Next.js Route Handlers。很多工具里，你会先中断，再重新解释，前面的工作也跟着断掉。
Pi 允许你在它工作时直接输入：
text
后端不要用 Express，沿用现有 Next.js Route Handlers；数据库使用 PGlite。按 Enter 后，这条消息进入 Steering 队列。当前 assistant turn 完成它已经发出的工具调用后、下一次模型调用前，Pi 才会把消息交给模型。它像开车时转方向盘：任务不必整段推倒，但路线会在下一个模型回合修正。
适合 Steer 的消息通常很短：
不要新增依赖；
你找错目录了，入口在 apps/web；
先验证根因，不要直接重构；
保留我现有的未提交修改。
如果当前方向没错，你只是想让它做完后追加一项工作，就使用 Follow-up。
默认按 Alt/Option + Enter：
text
当前修复和测试全部完成后，再更新 docs/troubleshooting.md。Follow-up 不会打断当前工作。它要等 Agent 完成本轮任务后，才进入下一轮。
Windows Terminal 默认把 Alt + Enter 用作全屏快捷键。需要先在终端设置里解除或重映射这个冲突，也可以在 Pi 的 keybindings.json 中自定义 Follow-up 按键。不同版本和终端可能有差异，直接输入 /hotkeys 核对最可靠。
两者的区别非常清楚：
现在方向错了：Steer；
现在没错，做完还有下一件事：Follow-up；
整个任务都不该继续：按 Escape 中止。
Steer 背后是一个很朴素的双层循环。内层负责“模型调用—执行这一回合的工具—返回结果—继续判断”；Steering 在下一次模型调用前插入。Follow-up 则等当前工作结束后，再开启下一轮。
所以 Steer 不是紧急停止按钮：它不会在 Bash 命令执行到一半时改变命令，当前 assistant turn 中已经发出的整批工具调用也可能继续完成。真正需要立刻停下时按 Escape。
五、Session 才是 Pi 与普通终端聊天工具拉开差距的地方
Pi 会把 Session 自动保存为 JSONL 文件，默认放在 ~/.pi/agent/sessions/，并按工作目录组织。常用命令不多：
text
/new 新建 Session /resume 选择历史 Session /name 名称 给当前 Session 命名 /session 查看当前 Session 信息 /compact 压缩旧上下文退出后运行 pi -c，继续最近一次 Session；运行 pi -r，从历史记录里选择。重要任务最好一开始就命名，例如 /name 修复支付回调重复入账。三天后恢复时，这比一段被截断的开场提示词好找得多。
什么时候该 /new，什么时候该 /compact
任务目标已经换了，就开新 Session。不要让“排查登录异常”的十几轮日志继续陪你写首页文案。
任务还没结束，但上下文快满了，再考虑 /compact。压缩会把旧内容总结成更短的文本，能腾出空间，但总结必然有损；具体报错、失败路径和细节可能被折叠掉。
“清空优于压缩”不是宗教。更准确的规则是：换目标就清空，目标没换但装不下了才压缩。
/tree：回到旧思路，代码不会跟着倒带
Pi 的 Session 不是一条直线，而是一棵树。输入：
text
/tree你可以跳回过去某个节点，从那里继续，形成新分支。一个分支试 SQLite，另一个分支试 PostgreSQL；两条对话路线都能保留。
还有两个相关命令：
text
/fork 从过去某条用户消息创建新 Session /clone 把当前活动分支复制成新 Session这里藏着一个非常危险的误解：会话树只改变模型看到的对话历史，不会回滚文件系统。
Pi 已经删掉一个文件后，你在 /tree 里跳回删除之前，文件不会自动回来。想让对话和代码同时回到某个节点，必须配合 Git、分支、提交或其他 checkpoint。
原视频里演示了 git reset --hard。这个命令确实能回退代码，但不适合作为教程里的默认答案，因为它会直接丢弃未提交修改。更稳妥的习惯是：开工前看 git status，大改前建立分支或提交 checkpoint，需要回退时先确认哪些改动必须保留。
把 Session 当作“思路的版本管理”，把 Git 当作“文件的版本管理”，两者不要混为一谈。
六、把 Pi 当成普通 CLI，而不是每次都打开聊天界面
有些任务只做一次，不需要进入交互模式：
bash
pi -p "总结当前项目的技术栈、启动方式和发布风险"也可以通过管道传入内容，或者明确限制工具，只做只读审查：
bash
pi --tools read,grep,find,ls -p "审查 src 目录，列出高风险问题，不要修改文件"这里的关键不是提示词里的“不要修改”，而是根本没有给模型开放 write、edit 和 bash。能力边界由工具决定，比口头提醒更可靠。
但它仍不是文件系统沙箱。只读工具默认并不保证只能读取项目目录；读到的内容也可能被发送给模型服务商。真正敏感的环境仍然要靠容器、虚拟机、独立账号或受控沙箱隔离。
这种模式适合 Shell 脚本、CI、一次性审查和批量处理。JSON 事件流、RPC 和 SDK 属于二次开发，第一次上手不必管。
七、别让每个新 Session 都重新猜项目：写好 AGENTS.md
新 Session 会清掉旧对话，但项目里那些长期成立的约定不该跟着消失。
Pi 会在启动时加载上下文文件。项目根目录建议使用：
text
AGENTS.md注意是大写、复数，不是视频转录里出现的 agent.md。
一个够用的版本可以很短：
markdown
# Project Instructions - 项目使用 Next.js、TypeScript 和 pnpm。 - 不要直接编辑生成文件。 - 修改代码后运行 pnpm test 和 pnpm typecheck。 - 数据库迁移只生成文件，不要连接生产库执行。 - 保留用户已有的未提交修改。 - 不读取或输出 .env、密钥与凭据。Pi 默认会读取：
全局的 ~/.pi/agent/AGENTS.md；
当前目录及父目录中的 AGENTS.md 或 CLAUDE.md；
同目录存在 AGENTS.override.md 时，优先加载 override 文件。
修改后重新启动 Pi，或输入 /reload。
AGENTS.md 应该写模型猜不到的隐性知识：哪些文件不能改、哪里需要联动、用什么命令验收、哪些操作必须确认。不要塞项目百科；内容越长越容易过期，关键规则也越容易被淹没。
另外必须说清楚：AGENTS.md 是给模型看的指令，不是强制权限系统。写一句“禁止读取 .env”有帮助，但模型出错、扩展绕过或 Bash 间接访问时，它并不能提供真正的隔离。
Pi 还支持 .pi/SYSTEM.md 和 .pi/APPEND_SYSTEM.md，用于替换或追加系统提示词。多数项目写好 AGENTS.md 就够了。
八、Skill、Extension、Package：三个名字，三种用途
Pi 本体刻意做小，扩展能力主要靠三层。
Skill：教模型一套做事方法
Skill 是按需加载的操作手册，通常包含 SKILL.md、脚本、参考资料和模板。例如“发布前检查”Skill 可以规定测试、类型检查、Git 状态与汇报格式。
Pi 启动时只放入 Skill 的名称和描述，任务匹配后再读取全文，避免所有操作手册一直占着上下文。
常见目录是：
text
~/.pi/agent/skills/ Pi 全局 Skills ~/.agents/skills/ 跨 Agent 共享的全局 Skills .pi/skills/ Pi 项目级 Skills .agents/skills/ 跨 Agent 共享的项目级 Skills已经在 Claude Code 或 Codex 中维护 Skills，不必复制。可以在 Pi 设置中加入已有目录：
json
{ "skills": [ "~/.claude/skills", "~/.codex/skills" ] }已有流程知识可以继续用，不必从零重建。
Extension：直接改变 Pi 的运行方式
Extension 是 TypeScript 模块。它能注册新工具和命令、拦截工具调用、修改状态栏和界面、加入 Plan Mode、MCP、Sub-Agent、权限确认，也能把工具执行转发到 SSH、容器或沙箱。
最简单的判断方法是：
只是告诉模型“遇到这类任务怎么做”：写 Skill；
需要新增工具、界面、事件或强制拦截：写 Extension。
Pi Package：把扩展打包分发
Package 可以把 Extensions、Skills、提示词和主题装在一起，通过 npm、Git 或本地路径安装：
bash
pi install npm:包名 pi install git:github.com/作者/仓库 pi list pi remove npm:包名默认写入全局设置。只希望当前项目使用，加 -l：
bash
pi install npm:包名 -l项目设置会写入 .pi/settings.json。项目被信任后，Pi 可以自动补装团队配置里缺少的 Package。
先用原生 Pi，遇到明确缺口再补：需要规划才装 Plan Mode，要接 MCP 才加 Adapter，反复执行同一流程才做 Skill。每个扩展都会增加依赖和故障面，还可能拥有完整系统权限。
九、安全部分不能略过：Trust 不是沙箱
这是 Claude Code、Codex 用户迁移到 Pi 时最容易判断错的地方。
Pi 的 Project Trust 只决定是否加载项目里的 .pi/settings.json、Extensions、Skills、Packages、系统提示词等本地资源。它不限制 Agent 启动后能对文件和命令做什么。
更容易忽略的是：即使你拒绝 Trust，AGENTS.md、CLAUDE.md 等上下文文件默认仍可能加载，除非明确关闭 context files。
原生 Pi 没有内置沙箱。read、write、edit、bash 和第三方 Extension 都以启动 Pi 的系统账号权限运行。仓库里的代码注释、文档、构建输出也可能造成提示注入。
实际使用至少守住四条：
第一，重要项目必须使用 Git。开工前看工作区状态，大改前做 checkpoint，结束后审查 diff。
第二，不要把生产凭据放在 Agent 随手能读到的环境。能用短期 Key 就不用长期 Key，能只挂载工作目录就不要把整个用户目录暴露进去。
第三，陌生仓库第一次调查时，关闭项目资源、上下文文件、扩展和 Skills，并只开放只读工具：
bash
pi --no-approve --no-extensions --no-skills --no-context-files \ --tools read,grep,find,ls这条命令降低了风险，但仍不是沙箱，因为只读工具可能访问项目外路径。
第四，无人值守、来源不明或带高价值凭据的任务，放进容器、虚拟机、微型虚拟机或远程沙箱，只挂载真正需要的文件，只提供最低限度的凭据和网络访问。
你也可以写 Extension，在读取 .env、执行 sudo、rm -rf 或危险 Git 命令前阻止或弹窗。但这类扩展属于工作流护栏，不是安全边界。路径变体、符号链接、Bash 间接访问都可能绕过一段写得不严密的拦截逻辑。
Pi 的自由度是真自由，系统权限也是真权限。不要把“极简”误读成“天然安全”。
十、从 Claude Code 或 Codex 迁移，按这个顺序最省时间
不要第一天就复制所有配置，更不要先装十几个 Package。
在一个小项目里只用原生 Pi，跑通登录、模型切换、@、截图、!、Steer、Follow-up 和 Session；
写一份短 AGENTS.md，只放长期有效、模型猜不到、做错会付出代价的规则；
接入 Claude Code 或 Codex 中真正高频的 Skills，不要重复维护三份；
记录几天内反复出现的缺口，再决定写 Skill、装 Extension，还是继续用原来的 Agent 完成那类任务；
有高安全要求，从一开始就在受控环境运行，不要幻想靠提示词补成沙箱。
日常工作只要守住一条主线：先调查并停下来，确认后做最小修改；方向错了用 Steer，当前工作完成后再做的事用 Follow-up；Session 管思路，Git 管文件。
十一、最后回答那个最现实的问题：Pi、Claude Code、Codex 怎么选？
如果你看重 Anthropic 原生体验、成熟默认工作流和较完整的权限习惯，Claude Code 仍然是合理选择。
如果你主要使用 OpenAI 模型、ChatGPT 订阅、Codex 云端任务与沙箱体系，继续使用 Codex 也没有任何问题。
如果你想在一个终端里切换多家模型，控制每个项目加载哪些能力，复用 Skills，研究或重写 Agent 工作流，Pi 更值得花时间。
它们也没必要三选一。
我更建议把 Pi 当成工具箱里的另一把刀：普通项目继续用熟悉的 Claude Code 或 Codex；需要跨模型比较、一次性 CLI、精细控制工具、构建专属工作流时，再打开 Pi。
Pi 最吸引人的地方，不是“只有四个工具”这个数字，而是它拒绝替所有用户预设同一种正确工作流。
它给你的不是一套更豪华的默认配置，而是一块足够小、可以看懂、可以拆换的底座。
这也是它最迷人的地方，以及它最麻烦的地方。
常用命令备忘
text
pi 启动交互模式 pi --version 查看版本 pi --help 查看参数 pi --list-models 查看模型目录 pi -c 继续最近 Session pi -r 选择历史 Session pi -p "任务" 一次性执行 pi config 管理 Package 资源 /login 登录模型提供商 /model 选择模型 /thinking 选择思考强度 /scoped-models 管理常用模型范围 /new 新建 Session /resume 恢复 Session /name 名称 命名 Session /session 查看 Session 信息 /tree 打开会话树 /fork 从历史消息创建新 Session /clone 复制当前活动分支 /compact 压缩旧上下文 /reload 重载扩展、Skills 和上下文文件 /hotkeys 查看快捷键 Ctrl + L 打开模型选择器 Shift + Tab 切换思考强度 Ctrl + G 打开外部编辑器 Ctrl + V 粘贴图片/文本（Windows/WSL 默认 Alt + V） Enter 提交；工作中作为 Steering 排队 Alt/Option + Enter Follow-up（Windows Terminal 需解除全屏快捷键冲突） Escape 中止当前任务 Ctrl + O 展开或折叠工具输出 Ctrl + T 展开或折叠思考内容
