Pi Coding Agent：一个可以被你改造的极简编程 Agent
这两年，编程 Agent 已经不稀奇了。
从 Claude Code、Codex CLI，到各种 IDE 插件，大多数工具的产品逻辑都差不多：给你一个已经包装好的智能体，你在它允许的范围里使用它。
但 Pi Coding Agent 的思路有点不一样。
它不是一个封闭的”AI 编程产品”，而是一个极简 Agent Harness。换句话说，它更像是一个可以运行在终端里的 Agent 操作系统：核心保持很小，把工作流、工具、技能、提示词、扩展、模型供应商都留给用户自己定制。
官方对它的定位很直接：
Change the harness, not your workflow. 改造 Agent 底座，而不是被 Agent 工作流反过来改造。
这正是 Pi 最有意思的地方。
一、Pi 是什么？
Pi Coding Agent 是一个运行在终端里的本地编程 Agent。
它默认提供最基础的能力：
读取文件
写入文件
编辑文件
执行 shell 命令
搜索文件
维护会话历史
切换模型
加载项目上下文
使用 Skills / Extensions / Prompt Templates 扩展能力
但它并不追求把所有功能都内置进去。
官方甚至明确说：Pi 默认不内置 sub-agent、plan mode、MCP、权限弹窗、后台 bash 等功能。
这听起来像缺点，但其实是 Pi 的设计哲学：
Pi 提供原语，而不是提供封死的功能。
如果你需要计划模式，可以自己做一个 plan-mode extension。如果你需要子代理，可以装 sub-agent extension。如果你需要权限控制，可以写 permission gate。如果你需要路径保护，可以加 protected-paths。
如果你需要 SSH 执行、沙箱、状态栏、交互式 UI，也都可以通过扩展完成。
它更像是**”给工程师用的 Agent 框架”**，不是”给普通用户用的 AI 编程盒子”。
二、安装 Pi
Pi 以 npm 包形式发布。
官方推荐安装方式：
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
其中 --ignore-scripts 是为了禁用 npm 依赖安装时的 lifecycle scripts。Pi 正常安装不依赖这些脚本，安全性更好。
Linux / macOS 也可以使用官方安装脚本：
curl -fsSL https://pi.dev/install.sh | sh
安装完成后，进入项目目录：
cd /path/to/project pi
第一次启动后，可以通过 /login 登录订阅类模型服务，也可以通过环境变量配置 API Key：
export ANTHROPIC_API_KEY=sk-ant-... pi
Pi 支持的模型供应商很多，包括 Anthropic、OpenAI、Google、Azure、Bedrock、Mistral、Groq、Cerebras、xAI、Hugging Face、Kimi For Coding、MiniMax、OpenRouter、Ollama、小米 MiMo 等。
三、Pi 的基本使用方法
启动 Pi 后，它会进入一个终端 TUI 界面。你可以直接输入任务：
Summarize this repository and tell me how to run its checks.
Pi 会读取项目文件，分析仓库结构，然后给出运行方式、检查命令、可能的改动建议。
引用文件
在输入框里输入 @，可以模糊搜索并引用项目文件。也可以在命令行中直接传入文件：
pi @README.md "Summarize this" pi @src/app.ts @src/app.test.ts "Review these together"
这对代码审查、重构、测试分析很方便。
执行 shell 命令
交互模式里可以用：
!npm run lint
命令输出会进入模型上下文，Agent 可以基于结果继续分析。
如果你想执行命令，但不想把输出喂给模型，可以用：
!!npm run lint
这适合一些输出很长、但只需要你自己看的命令。
切换模型
Pi 支持运行中切换模型：
/model
也可以用快捷键：
Ctrl + L：选择模型
Ctrl + P：在常用模型之间循环
Shift + Tab：切换 thinking level
这点对工程使用很实用：简单任务用便宜模型，复杂重构切高推理模型。
一次性命令模式
Pi 不一定要进入交互界面，也可以当作命令行工具用。
pi -p "Summarize this codebase"
管道输入：
cat README.md | pi -p "Summarize this text"
指定图片：
pi -p @screenshot.png "What's in this image?"
这意味着 Pi 可以被嵌入 shell 脚本、CI 流水线、代码审查流程中，不只是一个 TUI 聊天工具。
四、AGENTS.md：Pi 的工作说明书
Pi 会自动读取项目里的上下文文件，包括：
~/.pi/agent/AGENTS.md当前项目及父目录里的
AGENTS.md当前项目及父目录里的
CLAUDE.md
你可以在项目根目录写一个 AGENTS.md：
# Project Instructions - Run `npm run check` after code changes. - Do not run production migrations locally. - Keep responses concise. - Use TypeScript strict mode.
这样 Pi 每次进入项目都会自动知道项目约定。
这对长期项目非常重要。否则每次都要重新告诉 Agent 项目怎么启动、哪些目录不能动、测试命令是什么、数据库迁移能不能跑、代码风格是什么、交付前必须检查什么。
Pi 的思路是：把项目规则写进文件，而不是写进临时对话。
这点和 OpenClaw / Claude Code / Codex 的 AGENTS.md 体系是一致的。
五、会话是树，不是线
这是 Pi 最值得注意的能力。
很多 Agent 工具的会话是线性的。你问一句，它答一句。中间如果走错了，要么撤销，要么新开会话。
Pi 的会话是树结构。
它会把 session 保存到 ~/.pi/agent/sessions/，每个 session 是 JSONL 文件，并且内部是树状结构。
你可以用：
/tree
跳回任意一个历史节点，从那里继续走另一条分支。
这对编程任务特别有用。比如你让 Pi 重构一个模块：
分支 A：用最小改动方式修
分支 B：顺手重构架构
分支 C：先写测试再改代码
分支 D：完全换一种实现
传统 Agent 对话里，这些尝试很容易混在一起。Pi 的 /tree 可以把这些探索路径留在同一个 session 文件里，而且可以随时切换。
这五个能力——极简原语、模型切换、项目上下文、命令行模式、树状会话——构成了 Pi 的核心骨架。 它不试图做一个”万能编程助手”，而是做一个”你说了算的 Agent 底座”。
如果你是那种喜欢自己组装工具链的工程师，Pi 值得一试。