Pi Coding Agent：把 AI 编程助手带回终端
现在的 AI 编程工具越来越多：有的深度集成编辑器，有的提供完整的图形界面，还有的直接替你设计好一整套工作流。Pi Coding Agent 选择了另一条路——保持核心足够小，把决定权交还给使用者。
官方将 Pi 定义为一个 minimal terminal coding harness，也就是“极简的终端编程代理框架”。它不是只会聊天的命令行工具，而是能读取文件、修改代码、执行命令，并围绕真实项目持续工作的 AI 编程助手。
更重要的是，Pi 并不试图规定你应该怎样使用 AI。它提供可靠的基础能力，再通过 Prompt Templates、Skills、Extensions 和 Pi Packages 让你搭建自己的工作流。
为什么 Pi 值得关注？
第一次接触 Pi 时，它给人的感觉可能是“功能不多”。但使用一段时间后会发现，这种克制正是它最有特点的地方。
1. 终端优先，工作路径足够直接
进入项目目录后运行：
pi接下来就可以直接描述任务，例如：
分析这个项目的目录结构，告诉我如何运行测试。默认情况下，Pi 会给模型提供四个工具：
read：读取文件write：创建或覆盖文件edit：精确修改文件bash：执行 Shell 命令
也就是说，模型不只是给出建议，还能真正检查仓库、修改代码并运行验证命令。整个过程都发生在当前终端中，不需要在多个窗口之间来回切换。
2. 不绑定单一模型
Pi 支持多个模型提供商，可以通过 /login 使用已有订阅，也可以通过环境变量配置 API Key。
例如使用 Anthropic API Key：
export ANTHROPIC_API_KEY=sk-ant-...pi进入 Pi 后，可以使用 /model 或 Ctrl+L 切换模型，也可以调整模型的 thinking level。对于 Ollama、LM Studio、vLLM 等本地或 OpenAI 兼容服务，还可以通过 ~/.pi/agent/models.json 添加自定义模型。
这种设计很适合希望根据任务切换模型的人：简单检索可以使用更快、更便宜的模型，复杂重构则可以切换到推理能力更强的模型。
3. 会话不是一条直线，而是一棵树
Pi 会自动保存会话。除了继续上次工作，它还支持从历史节点分支：
/resume：恢复以前的会话/tree：在当前会话树中跳转/fork：从过去的用户消息创建新会话/clone：复制当前分支到新会话/compact：压缩较早的上下文
/tree 是我认为非常实用的功能。假设你先让 AI 使用方案 A，后来发现方向不对，就可以回到之前的节点尝试方案 B，而不必丢掉原来的讨论。不同尝试会保留在同一个会话树中，既方便比较，也减少了重复说明背景的成本。
Pi 的核心哲学：少内置，多扩展
很多 AI 编程工具会直接内置计划模式、子代理、待办列表、权限弹窗和 MCP。Pi 的核心版本却有意不提供这些功能。
这并不代表 Pi 做不到，而是它认为这些能力没有唯一正确的实现方式：
- 想要计划模式，可以把计划写进文件，也可以用 Extension 实现；
- 想要子代理，可以启动多个 Pi 实例，或安装相应的第三方扩展；
- 想要命令确认，可以用 Extension 拦截危险操作；
- 想接入外部工具，可以写 CLI、Skill，或者自行添加 MCP 支持。
这种思路可以概括为：核心只提供通用机制，具体工作流由用户选择。
它的优点是透明、灵活，不容易被某套固定流程限制；代价则是，想获得高度定制的体验，需要愿意花一点时间配置。
四层定制方式
Pi 的扩展体系不是只有“写插件”这一条路，而是从简单到复杂提供了几个层次。
第一层：AGENTS.md
最简单的定制方式，是在项目中添加 AGENTS.md：
# Project Instructions
- 修改代码后运行 `pnpm check`。- 不要在本地执行生产环境迁移。- 保持回答简洁。Pi 启动时会从全局、父目录和当前目录加载 AGENTS.md 或 CLAUDE.md。这很适合记录项目规范、常用命令和禁止事项，让每次会话都自动获得一致的上下文。
第二层：Prompt Templates
如果某段提示词会反复使用，可以把它保存为 Markdown 模板。
例如创建 ~/.pi/agent/prompts/review.md：
---description: 审查当前代码变更---
请审查当前 Git 变更，重点检查：
- 逻辑错误- 安全问题- 异常处理- 缺失的测试之后在 Pi 中输入 /review，模板就会展开成完整提示词。它适合固定格式的代码审查、提交总结、测试修复等任务。
第三层：Skills
Skill 是一个带有说明、脚本和参考资料的能力包。Pi 启动时只加载 Skill 的名称与描述，任务匹配后再读取完整的 SKILL.md，这是一种“渐进式披露”机制，可以避免把所有说明一次性塞进上下文。
Skill 适合封装比较完整的专业流程，例如：
- 安全审计
- 浏览器自动化
- PDF 或表格处理
- 项目发布流程
- 团队内部的代码审查规范
项目级 Skill 可以放在 .pi/skills/，全局 Skill 可以放在 ~/.pi/agent/skills/。
第四层：Extensions
如果 Prompt 和 Skill 还不够，就可以使用 TypeScript 编写 Extension。Extension 能够：
- 注册新的模型工具和斜杠命令；
- 监听会话、模型和工具调用事件；
- 拦截或修改危险命令；
- 自定义终端 UI、状态栏和快捷键；
- 接入外部服务；
- 实现计划模式、沙箱、子代理等更复杂的工作流。
例如，一个 Extension 可以在执行 rm -rf 前弹出确认，也可以阻止模型修改 .env 等敏感文件。相比把所有能力写死在核心中，这种事件和工具 API 给了用户更大的组合空间。
最后，还可以把 Extensions、Skills、Prompt Templates 和 Themes 打包成 Pi Package，通过 npm 或 Git 分发给其他人。
安装与第一次使用
Pi 可以通过 npm 全局安装：
npm install -g --ignore-scripts @earendil-works/pi-coding-agent然后进入项目目录并启动：
cd /path/to/projectpi第一次使用可以运行：
/login选择可用的订阅或 API Key 提供商。完成认证后，可以从一个范围明确的任务开始：
先阅读 README 和 package.json，总结项目结构，不要修改文件。确认它对项目的理解正确后，再继续：
修复当前测试失败的问题，完成后运行相关测试，并总结修改内容。我更推荐这种“先理解，再修改，最后验证”的节奏，而不是一开始就让 AI 大范围重构。
不只是一款终端应用
除了交互式 TUI，Pi 还支持其他运行方式：
# 一次性执行pi -p "总结这个代码库"
# 输出 JSON 事件流pi --mode json
# 通过 JSONL 协议进行进程集成pi --mode rpc对于 Node.js / TypeScript 项目，还可以直接使用 SDK 创建 AgentSession，把 Pi 嵌入自定义应用、自动化流水线或自己的界面中。
因此，Pi 更像是一个可以直接使用的编程助手，同时也是一个构建其他 Agent 工具的基础设施。
使用时要注意什么？
Pi 的模型可以执行 Shell 命令并修改当前目录中的文件，因此使用时仍然需要基本的安全意识：
- 在 Git 仓库中工作，修改前确认工作区状态，方便比较和回滚；
- 先给范围明确的任务，避免让模型在目标不清楚时大改代码；
- 认真审查第三方 Pi Package，Extension 拥有当前用户权限，Skill 也可能引导模型执行脚本；
- 谨慎信任项目级配置，Pi 会在加载
.pi资源前进行项目信任检查； - 重要操作仍由人确认，尤其是删除、部署、迁移和密钥相关操作。
Pi 核心不提供统一的权限弹窗，所以更适合在 Git、容器、虚拟机或其他可回滚环境中使用。如果团队有固定的安全要求，也可以通过 Extension 实现自己的确认与拦截规则。
总结
Pi Coding Agent 最吸引人的地方，不是“开箱即用的功能最多”，而是它把最重要的基础能力做成了一个清晰、可观察、可扩展的终端框架。
如果你希望 AI 编程助手直接替你决定工作方式，Pi 可能需要一些配置；但如果你喜欢终端、在意模型选择，希望掌控上下文、工具和自动化流程，那么 Pi 很值得尝试。
它的设计可以用一句话概括：
不强迫你适应工具，而是让工具适应你的工作流。