夜雨聆风为什么 Pi 最近这么火
视频版：https://www.bilibili.com/video/BV139bD6gEa8
Pi 是近期热度很高的 AI Agent。如果只用四个字概括它的特点，就是“大道至简”。
它默认只有四个基础工具，系统提示词也只有约 1000 Token。随便打个招呼，上下文占用大约 1100 Token，只占模型窗口的很小一部分。相比之下，不少 Coding Agent 还没真正开始工作，就已经消耗了大量上下文。
这种极简设计直接带来两个好处：速度更快，成本更低。根据 Composio 的一组基准测试，Pi Agent 完成编程任务的速度比其他主流 Coding Agent 快 1.5 到 2 倍，任务成本也更低。
代码质量方面，Databricks 曾在一个百万行代码仓库上做过基准测试。横轴是任务成本，纵轴是任务通过率，红线代表同等成本下成功率最高的 Agent 与模型组合。Pi 在不少场景中表现优于 Claude Code 和 Codex，而最高点来自 Pi 加 Claude Opus 4.8 的组合。
下面按 11 个部分系统梳理 Pi 的使用方式：安装配置、模型接入、基础操作、指令追加、会话管理、插件扩展、Skills、Web UI、跨 Session 记忆、安全机制，以及源码与 SDK。
Pi 的安装配置
Pi 的安装门槛很低。Windows 上，打开 PowerShell，执行官网提供的一键安装命令：
powershell -c "irm https://pi.dev/install.ps1 | iex"如果系统缺少 Node.js，安装脚本会提示是否自动安装。Pi 在 Windows 上使用 Git Bash 作为命令行环境；如果机器没有安装 Git，也可以让 Pi 顺手装好。
安装完成后，关闭当前终端，重新打开一个终端并输入：
pi如果能看到 Pi 的对话界面，说明安装完成。
macOS 的安装同样简单，执行：
curl -fsSL https://pi.dev/install.sh | sh配置模型
启动 Pi 后，输入：
/loginPi 支持两类模型接入方式：API Key 和模型订阅。
如果选择 API Key，可以在供应商列表中搜索目标模型厂商。以 DeepSeek 为例，先在 Pi 中筛选 DeepSeek，再到 DeepSeek 开放平台创建 API Key，复制后填入 Pi。
配置完成后，可以通过：
/model切换默认模型。也可以使用 Shift + Tab 调整思考强度，或用 Control + L 快速打开模型选择器。
另一种方式是接入模型订阅。再次输入 /login，选择账号登录，例如 OpenAI Codex，然后通过浏览器完成授权。授权成功后，模型列表里就会出现对应订阅下可用的模型。
基础操作
Pi 的工作目录就是启动它时所在的项目目录。进入项目文件夹后启动 Pi，后续让它写代码、改文件、运行命令，默认都会发生在这个目录里。
如果提示词需要多行输入，不要直接按回车。Shift + Enter 可以换行；Control + G 可以打开一个记事本式编辑器，适合写更长的需求。
完成提示词后保存并回到 Pi，按回车即可执行。Pi 会根据当前项目生成或修改代码。
任务完成后，界面底部会显示一组运行信息：
• 输入 Token：整个 Session 的累计输入 • 输出 Token：模型本轮或累计输出 • Cache Read：命中的缓存 Token • CH：最近一次请求的缓存命中率 • 成本估算：本轮或当前会话的大致费用 • 上下文占用：当前会话占模型窗口的比例
Pi 支持在对话窗口里临时执行命令。输入一个英文叹号，再接命令即可：
!npm run dev这种方式下，命令输出会进入 Pi 的上下文，AI 能看到执行结果并继续判断下一步。如果不希望 AI 看到命令输出，可以使用两个叹号。
Pi 也支持截图反馈。比如页面布局不满意，可以截图后粘贴到对话窗口，让 Pi 根据图像调整代码。除了图片，还可以用 @ 引用项目文件或目录，让 AI 针对指定上下文修改。
指令追加：Steering 与 Follow-up
AI 执行任务时，需求经常会发生变化。Pi 提供两种追加指令的方式：Steering 和 Follow-up。
Steering 适合“立即纠偏”。例如 Pi 正准备使用 Express 做后端，但你希望它改用 Next.js 和 SQLite，可以直接在对话框里补一句需求并回车。Pi 会把这条消息当作实时引导，尽快调整当前执行方向。
Follow-up 更像“排队任务”。它不会打断当前执行，而是等 Pi 完成手头工作后再处理。Windows 上可能需要先取消 PowerShell 中 Alt + Enter 的全屏快捷键，否则会和 Pi 的 Follow-up 快捷键冲突。
配置好后，输入追加指令并按 Alt + Enter，Mac 上是 Option + Enter，这条消息会进入队列。排队期间也可以通过 Alt + ↑ 取回并修改。
这两种机制背后对应 Pi 的双层 Agent Loop：
• 内层循环负责调用模型、执行工具、读取结果、判断任务是否完成 • Steering 会在内层循环的后续轮次注入上下文，用于实时改变方向 • Follow-up 位于外层循环，等当前任务结束后再开启下一轮任务
Pi 还支持一次性非交互模式：
pi -p "查找今天的天气，并在桌面写入天气.txt"这种模式适合把 Pi 当成一次性的 CLI 命令使用。
会话管理与对话树
Pi 的会话单元叫 Session。一次连续对话就是一个 Session。输入 /new 可以创建新 Session，清空旧上下文，让 AI 专注处理新任务。
关闭窗口后，可以用：
pi -c从最近的 Session 继续，也可以用：
pi -r从历史 Session 中选择一个恢复。
Pi 的 Session 不是简单的线性记录，而是一棵对话树。输入 /tree 可以查看历史节点，并回退到某个节点继续生成分支。它很适合做不同方案的探索，比如同一个功能先走“蔬菜列表”分支，再从中间节点尝试“海鲜列表”分支。
需要注意的是，对话树只回退对话历史，不会自动回退代码。代码层面的回滚仍然要配合 Git 完成。例如：
git reset --hard <commit-id>回退对话历史时，Pi 还会提供几种处理方式：直接丢弃、总结被丢弃的分支，或者让用户自定义总结规则。总结只针对当前被回退的分支，不会跨分支合并。
常用会话命令还有三个：
• /clone：完整复制当前 Session• /fork：从某个历史节点创建新 Session• /compact：手动压缩上下文
对于复杂任务，压缩能减少上下文占用；但日常开发中，任务完成后新开 Session 往往更干净，AI 的注意力也更集中。
工具设计与插件扩展
Pi 默认只有四个工具：Read、Write、Edit、Bash。它没有内置 MCP、SubAgent、Plan Mode、Todo 或 btw。这不是能力不足，而是一种设计选择：核心越小，模型越不容易被冗余工具干扰。
这四个工具覆盖了大多数编程场景。尤其是 Bash，本身就能承担搜索、构建、测试、运行脚本等大量工作。Pi 的理念是“让工具适应你的工作流，而不是让你适应工具”。
Pi 的扩展主要来自两类能力：插件和 Skills。
插件安装很直接，在 Pi 官网的 package 列表中找到目标插件，复制安装命令执行即可。比较实用的插件包括：
• pi-web-access：增加联网搜索和网页读取能力，基于 Exa MCP，通常不需要额外 API Key• pi-subagents：支持并行启动多个子代理，适合多方案生成和并行审查• pi-mcp-adapter：为 Pi 补上 MCP 能力，可读取项目中的.mcp.json• btw：在 AI 工作时开启旁路对话，不打断主任务• plan-mode：先生成计划，再确认执行，适合高风险改造• pi-goal：围绕一个目标多轮迭代，直到达成结果• pi-dynamic-workflows：通过动态工作流调度多个 Agent 协作• 即时通信插件：让 Pi 与手机消息连接，接收并处理移动端指令
插件可以全局安装，也可以项目级安装。项目级安装通常放在项目目录下，只对当前工程生效。这样能减少无关插件带来的系统提示词负担。
Agent Skills 的配置与使用
除了插件，Pi 还支持标准 Agent Skills 协议。项目级 Skills 通常放在：
项目目录/.agents/skills/每个 Skill 目录下包含 SKILL.md，Pi 启动后会识别这些技能，并在合适的场景自动调用。
以 Playwright CLI Skill 为例，它能让 Pi 操作浏览器完成自动化任务。安装工具本体后，把对应 Skill 放到项目目录，Pi 就能识别它。后续只要需求涉及浏览器操作，比如搜索、打开网页、填写表单，Pi 会根据上下文选择调用。
如果某个 Skill 希望在所有项目中生效，可以放到用户目录：
~/.agents/skills/SkillHub 也是寻找技能的好地方。例如 Markdown Converter Skill 可以把 PDF、文档等格式转换为 Markdown。遇到缺少运行依赖时，也可以让 Pi 根据 Skill 说明自动补装。
Web UI 界面安装与使用
不习惯命令行的用户，可以给 Pi 配一个 Web UI。社区里已经有一些成熟方案，安装后会自动打开浏览器界面。
Web UI 通常包含几个核心区域：
• 项目切换：选择当前工作目录 • 文件浏览器：查看项目文件结构 • 模型管理：添加 provider、配置 API Key、切换模型 • 技能与插件管理：启用、关闭、安装项目级或全局能力 • 中央对话区：输入指令、粘贴截图、使用斜线命令、调整思考强度
它和命令行版的核心能力一致，只是把操作入口做成了图形界面。熟悉 TUI 后，上手 Web UI 基本没有额外成本。
跨 Session 记忆与全局提示词
每次新建 Session，AI 都会进入一个全新的上下文。对于复杂项目，如果每次都重新介绍背景，会非常低效。
通用做法是在项目根目录创建：
AGENTS.md这个文件会成为 AI 每次进入项目时必读的指南。可以写入项目背景、目录结构、技术栈、编码约定、测试方式，以及你希望 AI 遵守的沟通风格。
如果不想手写，也可以让 Pi 通读项目后自动生成 AGENTS.md。它会把从源码、配置和文档中学到的重要信息整理进去，方便后续 Session 快速接续。
项目级 AGENTS.md 只影响当前项目。若希望对所有项目生效，可以在 Pi 的全局配置目录里创建全局 AGENTS.md。例如加入安全规则：禁止批量删除文件或目录，只允许针对明确路径做单文件删除。
Pi 还支持 APPEND_SYSTEM.md，它会直接追加到系统提示词中，优先级更高。但日常使用中，AGENTS.md 已经足够。
安全机制
Pi 的内置安全机制非常基础：当它在包含陌生插件或 Skill 的目录中启动时，会询问是否信任并加载这些能力。
一旦开始运行，Pi 默认拥有当前用户权限。它可以编辑文件、执行命令，也不会像某些工具那样在每个敏感操作前反复确认。这符合 Pi 的极简哲学，但也意味着用户需要自己做好边界控制。
更稳妥的方案有两类：
• 使用 WSL、Docker、虚拟机等隔离环境运行 Pi • 安装权限类插件，例如在执行敏感命令前弹出审批
如果只是日常开发，建议至少用 Git 管理项目，并在重要修改前提交一次。这样即使 AI 改坏了，也能快速回滚。
自己动手 DIY 插件
Pi 的开放接口比较充分，模型、工具系统、会话管理、UI 都能扩展。更有意思的是，可以让 Pi 帮你为 Pi 自己写插件。
例如：
• 根据 IP 查询地理位置，再获取天气，并展示在对话窗口顶部 • 保护 .env文件，阻止 AI 读取或编辑敏感内容• 执行 rm等删除命令前弹窗确认
这类插件通常就是一个 TypeScript 文件。生成后放到项目目录的 .pi/extensions 下，执行 /reload 即可加载。测试稳定后，也可以复制到 Pi 的全局配置目录，让所有项目都生效。
用 Pi 定制 Pi，是它最有意思的能力之一。只要需求描述清楚，很多轻量插件都能一次生成并跑通。
源代码架构与 SDK 集成
Pi 的源码很适合学习 Agent 架构。核心包主要包括：
• ai：统一不同模型供应商的调用方式• agent：实现 Agent Loop• coding-agent：定义编程场景、四个基础工具、系统提示词、Skills 与插件机制• tui：实现命令行交互界面
如果你正在做 Agent 开发，Pi 的源码是一份很好的参考材料。它展示了一个极简 Agent 如何在少工具、低上下文负担的前提下完成复杂编程任务。
Pi 的部分能力也已经封装为 SDK。例如，项目中需要统一接入多家模型，可以使用 Pi AI SDK；需要一个开箱即用的编程 Agent，也可以集成 Pi Coding Agent SDK。
总体来看，Pi 的价值不只在“又一个 Coding Agent”，而在于它证明了一件事：Agent 不一定要堆很多工具和复杂提示词。把核心做小、把扩展留给用户，反而能获得更高的速度、更低的成本，以及更灵活的工作流。