同一个模型单任务成本相差两倍 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.jsbashnode --version本文写作时Pi npm 最新版为 0.84.3要求 Node.js 22.19.0 或更高版本。版本不够就先升级 Node.js再执行bashnpm install -g --ignore-scripts earendil-works/pi-coding-agent--ignore-scripts 会关闭依赖安装阶段的生命周期脚本。Pi 官方说明正常安装不依赖这些脚本因此建议带上。安装后确认版本bashpi --versionmacOS 或 Linux 也可以使用官网安装脚本bashcurl -fsSL https://pi.dev/install.sh | sh第一次使用不要在随便一个目录里直接输入 pi。先进入一个有 Git、没有生产凭据、改坏了也能恢复的小项目bashcd ~/projects/my-app git status piPi 会把当前目录当作工作目录但这不是访问边界。它的读取工具和 Bash 仍然可以访问当前系统账号有权访问的其他位置。“在某个项目目录启动”与“只能访问这个项目”是两回事。登录模型进入 Pi 后输入text/login如果你已经购买 Claude Pro/Max、ChatGPT Plus/Pro 或 GitHub Copilot可以直接选择订阅登录不必立刻改成 API 按量付费。按界面提示去浏览器完成授权回来后即可使用相应模型。如果使用 API Key也可以在 /login 中保存或在启动前设置环境变量bashexport 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 打开外部编辑器写完保存并退出内容会回到输入框。这比在终端里小心翼翼地改几十行提示词舒服得多。用 引用文件输入 可以搜索项目文件textsrc/auth.ts 检查令牌刷新逻辑有没有竞态问题先解释不要修改。也可以启动时传入bashpi src/auth.ts src/auth.test.ts 检查实现与测试是否一致引用文件不是强制模型只能看这些文件它只是把相关材料明确交给模型。若任务涉及其他依赖Pi 仍可能继续调查。粘贴截图macOS/Linux 通常使用 Ctrl VWindows/WSL 默认使用 Alt V。支持的终端也可以直接拖入图片。截图最好附上可验证的描述text截图中 390px 宽度下导航栏遮住了页面标题。 请找到 CSS 根因并修复不要顺手重做整套视觉。“这里不好看改一下”不是需求只是在邀请模型猜你的审美。! 和 !!都能跑命令只有一个会进入上下文在 Pi 里输入text!npm test命令会在当前界面运行输出也会送进模型上下文。测试失败后Pi 能直接读取报错继续排查。如果改成text!!git status命令由你自己运行输出不会加入模型上下文。可以记成!我看模型也看!!只有我看。但 !! 不是秘密保险箱。最稳妥的做法仍然是不要在 Agent 会话里打印密码、Token、.env 内容和私人凭据。四、Pi 最好用的交互不是某个插件而是 SteerAgent 执行长任务时最常见的问题不是它完全不会而是走到一半开始偏。比如你让它给现有项目加后端它却开始安装 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 Entertext当前修复和测试全部完成后再更新 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而不是每次都打开聊天界面有些任务只做一次不需要进入交互模式bashpi -p 总结当前项目的技术栈、启动方式和发布风险也可以通过管道传入内容或者明确限制工具只做只读审查bashpi --tools read,grep,find,ls -p 审查 src 目录列出高风险问题不要修改文件这里的关键不是提示词里的“不要修改”而是根本没有给模型开放 write、edit 和 bash。能力边界由工具决定比口头提醒更可靠。但它仍不是文件系统沙箱。只读工具默认并不保证只能读取项目目录读到的内容也可能被发送给模型服务商。真正敏感的环境仍然要靠容器、虚拟机、独立账号或受控沙箱隔离。这种模式适合 Shell 脚本、CI、一次性审查和批量处理。JSON 事件流、RPC 和 SDK 属于二次开发第一次上手不必管。七、别让每个新 Session 都重新猜项目写好 AGENTS.md新 Session 会清掉旧对话但项目里那些长期成立的约定不该跟着消失。Pi 会在启动时加载上下文文件。项目根目录建议使用textAGENTS.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 或本地路径安装bashpi install npm:包名 pi install git:github.com/作者/仓库 pi list pi remove npm:包名默认写入全局设置。只希望当前项目使用加 -lbashpi 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 启动后能对文件和命令做什么。更容易忽略的是即使你拒绝 TrustAGENTS.md、CLAUDE.md 等上下文文件默认仍可能加载除非明确关闭 context files。原生 Pi 没有内置沙箱。read、write、edit、bash 和第三方 Extension 都以启动 Pi 的系统账号权限运行。仓库里的代码注释、文档、构建输出也可能造成提示注入。实际使用至少守住四条第一重要项目必须使用 Git。开工前看工作区状态大改前做 checkpoint结束后审查 diff。第二不要把生产凭据放在 Agent 随手能读到的环境。能用短期 Key 就不用长期 Key能只挂载工作目录就不要把整个用户目录暴露进去。第三陌生仓库第一次调查时关闭项目资源、上下文文件、扩展和 Skills并只开放只读工具bashpi --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-upSession 管思路Git 管文件。十一、最后回答那个最现实的问题Pi、Claude Code、Codex 怎么选如果你看重 Anthropic 原生体验、成熟默认工作流和较完整的权限习惯Claude Code 仍然是合理选择。如果你主要使用 OpenAI 模型、ChatGPT 订阅、Codex 云端任务与沙箱体系继续使用 Codex 也没有任何问题。如果你想在一个终端里切换多家模型控制每个项目加载哪些能力复用 Skills研究或重写 Agent 工作流Pi 更值得花时间。它们也没必要三选一。我更建议把 Pi 当成工具箱里的另一把刀普通项目继续用熟悉的 Claude Code 或 Codex需要跨模型比较、一次性 CLI、精细控制工具、构建专属工作流时再打开 Pi。Pi 最吸引人的地方不是“只有四个工具”这个数字而是它拒绝替所有用户预设同一种正确工作流。它给你的不是一套更豪华的默认配置而是一块足够小、可以看懂、可以拆换的底座。这也是它最迷人的地方以及它最麻烦的地方。常用命令备忘textpi 启动交互模式 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-upWindows Terminal 需解除全屏快捷键冲突 Escape 中止当前任务 Ctrl O 展开或折叠工具输出 Ctrl T 展开或折叠思考内容 省Token又快速，新一代的Agent - Pi
同一个模型单任务成本相差两倍 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.jsbashnode --version本文写作时Pi npm 最新版为 0.84.3要求 Node.js 22.19.0 或更高版本。版本不够就先升级 Node.js再执行bashnpm install -g --ignore-scripts earendil-works/pi-coding-agent--ignore-scripts 会关闭依赖安装阶段的生命周期脚本。Pi 官方说明正常安装不依赖这些脚本因此建议带上。安装后确认版本bashpi --versionmacOS 或 Linux 也可以使用官网安装脚本bashcurl -fsSL https://pi.dev/install.sh | sh第一次使用不要在随便一个目录里直接输入 pi。先进入一个有 Git、没有生产凭据、改坏了也能恢复的小项目bashcd ~/projects/my-app git status piPi 会把当前目录当作工作目录但这不是访问边界。它的读取工具和 Bash 仍然可以访问当前系统账号有权访问的其他位置。“在某个项目目录启动”与“只能访问这个项目”是两回事。登录模型进入 Pi 后输入text/login如果你已经购买 Claude Pro/Max、ChatGPT Plus/Pro 或 GitHub Copilot可以直接选择订阅登录不必立刻改成 API 按量付费。按界面提示去浏览器完成授权回来后即可使用相应模型。如果使用 API Key也可以在 /login 中保存或在启动前设置环境变量bashexport 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 打开外部编辑器写完保存并退出内容会回到输入框。这比在终端里小心翼翼地改几十行提示词舒服得多。用 引用文件输入 可以搜索项目文件textsrc/auth.ts 检查令牌刷新逻辑有没有竞态问题先解释不要修改。也可以启动时传入bashpi src/auth.ts src/auth.test.ts 检查实现与测试是否一致引用文件不是强制模型只能看这些文件它只是把相关材料明确交给模型。若任务涉及其他依赖Pi 仍可能继续调查。粘贴截图macOS/Linux 通常使用 Ctrl VWindows/WSL 默认使用 Alt V。支持的终端也可以直接拖入图片。截图最好附上可验证的描述text截图中 390px 宽度下导航栏遮住了页面标题。 请找到 CSS 根因并修复不要顺手重做整套视觉。“这里不好看改一下”不是需求只是在邀请模型猜你的审美。! 和 !!都能跑命令只有一个会进入上下文在 Pi 里输入text!npm test命令会在当前界面运行输出也会送进模型上下文。测试失败后Pi 能直接读取报错继续排查。如果改成text!!git status命令由你自己运行输出不会加入模型上下文。可以记成!我看模型也看!!只有我看。但 !! 不是秘密保险箱。最稳妥的做法仍然是不要在 Agent 会话里打印密码、Token、.env 内容和私人凭据。四、Pi 最好用的交互不是某个插件而是 SteerAgent 执行长任务时最常见的问题不是它完全不会而是走到一半开始偏。比如你让它给现有项目加后端它却开始安装 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 Entertext当前修复和测试全部完成后再更新 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而不是每次都打开聊天界面有些任务只做一次不需要进入交互模式bashpi -p 总结当前项目的技术栈、启动方式和发布风险也可以通过管道传入内容或者明确限制工具只做只读审查bashpi --tools read,grep,find,ls -p 审查 src 目录列出高风险问题不要修改文件这里的关键不是提示词里的“不要修改”而是根本没有给模型开放 write、edit 和 bash。能力边界由工具决定比口头提醒更可靠。但它仍不是文件系统沙箱。只读工具默认并不保证只能读取项目目录读到的内容也可能被发送给模型服务商。真正敏感的环境仍然要靠容器、虚拟机、独立账号或受控沙箱隔离。这种模式适合 Shell 脚本、CI、一次性审查和批量处理。JSON 事件流、RPC 和 SDK 属于二次开发第一次上手不必管。七、别让每个新 Session 都重新猜项目写好 AGENTS.md新 Session 会清掉旧对话但项目里那些长期成立的约定不该跟着消失。Pi 会在启动时加载上下文文件。项目根目录建议使用textAGENTS.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 或本地路径安装bashpi install npm:包名 pi install git:github.com/作者/仓库 pi list pi remove npm:包名默认写入全局设置。只希望当前项目使用加 -lbashpi 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 启动后能对文件和命令做什么。更容易忽略的是即使你拒绝 TrustAGENTS.md、CLAUDE.md 等上下文文件默认仍可能加载除非明确关闭 context files。原生 Pi 没有内置沙箱。read、write、edit、bash 和第三方 Extension 都以启动 Pi 的系统账号权限运行。仓库里的代码注释、文档、构建输出也可能造成提示注入。实际使用至少守住四条第一重要项目必须使用 Git。开工前看工作区状态大改前做 checkpoint结束后审查 diff。第二不要把生产凭据放在 Agent 随手能读到的环境。能用短期 Key 就不用长期 Key能只挂载工作目录就不要把整个用户目录暴露进去。第三陌生仓库第一次调查时关闭项目资源、上下文文件、扩展和 Skills并只开放只读工具bashpi --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-upSession 管思路Git 管文件。十一、最后回答那个最现实的问题Pi、Claude Code、Codex 怎么选如果你看重 Anthropic 原生体验、成熟默认工作流和较完整的权限习惯Claude Code 仍然是合理选择。如果你主要使用 OpenAI 模型、ChatGPT 订阅、Codex 云端任务与沙箱体系继续使用 Codex 也没有任何问题。如果你想在一个终端里切换多家模型控制每个项目加载哪些能力复用 Skills研究或重写 Agent 工作流Pi 更值得花时间。它们也没必要三选一。我更建议把 Pi 当成工具箱里的另一把刀普通项目继续用熟悉的 Claude Code 或 Codex需要跨模型比较、一次性 CLI、精细控制工具、构建专属工作流时再打开 Pi。Pi 最吸引人的地方不是“只有四个工具”这个数字而是它拒绝替所有用户预设同一种正确工作流。它给你的不是一套更豪华的默认配置而是一块足够小、可以看懂、可以拆换的底座。这也是它最迷人的地方以及它最麻烦的地方。常用命令备忘textpi 启动交互模式 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-upWindows Terminal 需解除全屏快捷键冲突 Escape 中止当前任务 Ctrl O 展开或折叠工具输出 Ctrl T 展开或折叠思考内容