我用 Pi Agent 一个多月了，这是完整的上手指南
Pi Agent 是我最近一个多月的主力编程工具。从安装到配完一整套工作流，中间踩了不少坑。今天把路径完整梳理一遍。
这篇文章不是官方文档——是实际用下来的经验。
装 Pi 只要一行：
npm install -g --ignore-scripts @earendil-works/pi-coding-agent或者用安装脚本：
curl -fsSL https://pi.dev/install.sh | sh装完敲 pi 启动。但你首先需要一个模型。
Pi 配模型的体验做得挺好。如果你有 Claude Pro/Max、ChatGPT Plus/Pro 或者 GitHub Copilot 的订阅，直接 /login 就能认证——不需要去后台拿 Key，不需要填环境变量。这是少数几个让我觉得"对了"的交互。
如果你是 API Key 用户，用环境变量：
export ANTHROPIC_API_KEY=sk-ant-...
pi或者直接在命令行指定：
pi --provider deepseek --model deepseek-v4-pro --api-key sk-xxxPi 支持的提供商够多——Anthropic、OpenAI、Google、DeepSeek、OpenRouter、还有国内的 Kimi、MiniMax、小米 MiMo。手里有什么 Key 都能接。
切换模型用 Ctrl+L，或者在对话里敲 /model。我现在的日常搭配是 DeepSeek V4 做主力，遇到硬问题才切更强的模型。
Pi 默认没有联网能力。这在 2026 年是个明显短板——你不知道 React 最新版本有什么变化，就只能靠训练数据猜。
解决方案是 @lokiyou/pi-web-search：
pi install npm:@lokiyou/pi-web-search
pi /reload装好之后，扩展会在 ~/.pi/agent/extensions/pi-web-search/config.json 生成配置。你需要至少填一个搜索服务的 API Key。我用的是 Tavily，免费额度够日常用，搜索质量也稳定。
去 tavily.com 注册，Dashboard 里拿 Key，填进去：
{
"provider": "auto",
"tavilyApiKey": "把你的Key填这里"
}不用管其他字段。provider: "auto" 的意思是优先尝试 Grok，但你只配了 Tavily 它就只用 Tavily。
配置完成之后不需要调用任何特殊命令。你正常提问题，Agent 会在需要的时候自己上网查。你会发现它开始说"让我搜索一下"——这就是生效了。
接下来是文档处理。写代码的人免不了要读 PDF、改 Word、做表格、出 PPT。Pi 对四类文档都有内置的 Skill，不需要额外安装。
PDF 是覆盖最全的：读文字、提取表格、合并拆分、加水印、OCR 扫描件。你拖一个 PDF 到项目里，跟 Agent 说"把这个表格导出来"就行。
Word、Excel 和 PowerPoint 各有各自的 Skill。其中 Excel 和 PowerPoint 的 Skill 写得特别细致。
Excel 的核心规则就一条：不要硬编码计算结果，写公式。这意味着你让 Agent 做一个财务报表，它不会给你一个只能看的数字表，而是一个改了输入会自动重算的活文件。
PowerPoint 的更特别——它不仅教 Agent 怎么生成 PPT，还教它怎么做不像 AI 做的 PPT。里面列了配色方案、排版规则，还有一条"永远不要在标题下面加装饰条"。这是个很细节的判断：AI 做 PPT 最爱干的事情就是在标题下加一条彩色横线，这个 Skill 明令禁止了。
四个 Skill 的安装路径都是 ~/.pi/agent/skills/ 下面的对应目录。Pi 默认就会扫描这里，你只需要确认文件存在就行。
到这里，你的 Pi 能做的事情：联网搜索、读论文、写报告、做表格、出 PPT。
但还有一个东西让整个体验进了一步——多模型协作。
Pi 内置了一个 escalation 机制。它的逻辑很简单：你日常用一个便宜的模型（比如 DeepSeek V4），Agent 在执行过程中如果发现某个任务自己搞不定——连续失败两次、或者遇到不熟悉的领域——会自行决定把任务交给更强的模型。
强模型处理完，自动把结果交回来。你继续在便宜模型上对话，不需要手动切换。整个过程你是无感知的，除非你去看日志。
这就形成了一个很自然的工作流：80% 的任务用便宜的模型，20% 的硬骨头自动升级到旗舰。不用全程开着贵的跑，也不用在任务中间手动切来切去。
这个机制默认启用。想看可用模型的话，/models-status。
用了一个多月，我整理了一份最短配置清单：
开始态：npm install -g @earendil-works/pi-coding-agent，然后 /login 或者配 API Key。
搜索：pi install npm:@lokiyou/pi-web-search，去 Tavily 拿个免费 Key 填进 config.json。
文档：确认 ~/.pi/agent/skills/ 下有 pdf、docx、xlsx、pptx 四个目录。没有就从 Pi 的 skills 目录拷过去。
多模型：默认就有，不用额外配置。
这份清单装完，Pi 基本上覆盖了我日常 90% 的场景。剩下的 10% 是每个人自己特有的工作流——但那正好是 Pi 设计里留给你自己去建的部分。
如果你也是 macOS 用户，建议把终端字体调到 14pt 以上。Pi 的 TUI 在 Retina 屏幕上小字体的时候会显得挤，调大之后舒服很多。