I've Been Using Pi Agent for Over a Month — Here's the Complete Guide

Pi Agent 是我最近一个多月的主力编程工具。从安装到配完一整套工作流，中间踩了不少坑。今天把路径完整梳理一遍。

Pi Agent has been my primary coding tool for over a month now. From installation to full workflow setup, I hit quite a few bumps along the way. Today I'll walk through the complete path.

这篇文章不是官方文档——是实际用下来的经验。

This isn't official documentation — it's hands-on experience.

装 Pi 只要一行：

Install Pi with one line:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

或者用安装脚本：

Or use the install script:

curl -fsSL https://pi.dev/install.sh | sh

curl -fsSL https://pi.dev/install.sh | sh

装完敲 pi 启动。但你首先需要一个模型。

After installation, type pi to start. But first, you need a model.

Pi 配模型的体验做得挺好。如果你有 Claude Pro/Max、ChatGPT Plus/Pro 或者 GitHub Copilot 的订阅，直接 /login 就能认证——不需要去后台拿 Key，不需要填环境变量。这是少数几个让我觉得"对了"的交互。

Pi's model configuration experience is well done. If you have Claude Pro/Max, ChatGPT Plus/Pro, or GitHub Copilot, just use /login to authenticate — no digging for API keys, no environment variables to set. One of those rare interactions that just feels right.

如果你是 API Key 用户，用环境变量：

If you're an API key user, use environment variables:

export ANTHROPIC_API_KEY=sk-ant-...
pi

export ANTHROPIC_API_KEY=sk-ant-...
pi

或者直接在命令行指定：

Or specify directly on the command line:

pi --provider deepseek --model deepseek-v4-pro --api-key sk-xxx

pi --provider deepseek --model deepseek-v4-pro --api-key sk-xxx

Pi 支持的提供商够多——Anthropic、OpenAI、Google、DeepSeek、OpenRouter、还有国内的 Kimi、MiniMax、小米 MiMo。手里有什么 Key 都能接。

Pi supports plenty of providers — Anthropic, OpenAI, Google, DeepSeek, OpenRouter, plus domestic options like Kimi, MiniMax, and Xiaomi MiMo. Whatever key you've got, it'll work.

切换模型用 Ctrl+L，或者在对话里敲 /model。我现在的日常搭配是 DeepSeek V4 做主力，遇到硬问题才切更强的模型。

Switch models with Ctrl+L, or type /model in conversation. My daily setup: DeepSeek V4 as the workhorse, only switching to stronger models for tough problems.

Pi 默认没有联网能力。这在 2026 年是个明显短板——你不知道 React 最新版本有什么变化，就只能靠训练数据猜。

Pi has no web access by default. In 2026, this is a glaring gap — if you don't know the latest React changes, you're stuck guessing from training data.

解决方案是 @lokiyou/pi-web-search：

The solution is @lokiyou/pi-web-search:

pi install npm:@lokiyou/pi-web-search
pi /reload

pi install npm:@lokiyou/pi-web-search
pi /reload

装好之后，扩展会在 ~/.pi/agent/extensions/pi-web-search/config.json 生成配置。你需要至少填一个搜索服务的 API Key。我用的是 Tavily，免费额度够日常用，搜索质量也稳定。

After installation, the extension generates config at ~/.pi/agent/extensions/pi-web-search/config.json. Fill in at least one search service API key. I use Tavily — the free tier covers daily needs, search quality is consistent.

去 tavily.com 注册，Dashboard 里拿 Key，填进去：

Sign up at tavily.com, grab the key from Dashboard, fill it in:

{
  "provider": "auto",
  "tavilyApiKey": "把你的Key填这里"
}

{
  "provider": "auto",
  "tavilyApiKey": "put your key here"
}

不用管其他字段。provider: "auto" 的意思是优先尝试 Grok，但你只配了 Tavily 它就只用 Tavily。

Don't worry about other fields. provider: "auto" means it prefers Grok but will use only Tavily if that's all you've configured.

配置完成之后不需要调用任何特殊命令。你正常提问题，Agent 会在需要的时候自己上网查。你会发现它开始说"让我搜索一下"——这就是生效了。

No special commands needed after config. Ask questions normally, and the Agent will search the web when needed. You'll notice it starts saying "let me search for that" — that's when you know it's working.

接下来是文档处理。写代码的人免不了要读 PDF、改 Word、做表格、出 PPT。Pi 对四类文档都有内置的 Skill，不需要额外安装。

Next: document processing. Coders inevitably need to read PDFs, edit Word docs, work with spreadsheets, and make slides. Pi has built-in Skills for all four — no extra installation needed.

PDF 是覆盖最全的：读文字、提取表格、合并拆分、加水印、OCR 扫描件。你拖一个 PDF 到项目里，跟 Agent 说"把这个表格导出来"就行。

PDF has the broadest coverage: read text, extract tables, merge/split, watermark, OCR scanned documents. Drop a PDF into the project, tell the Agent "export this table," and it's done.

Word、Excel 和 PowerPoint 各有各自的 Skill。其中 Excel 和 PowerPoint 的 Skill 写得特别细致。

Word, Excel, and PowerPoint each have their own Skills. Excel and PowerPoint Skills are particularly well-crafted.

Excel 的核心规则就一条：不要硬编码计算结果，写公式。这意味着你让 Agent 做一个财务报表，它不会给你一个只能看的数字表，而是一个改了输入会自动重算的活文件。

Excel's core rule is simple: don't hardcode results — write formulas. This means when you ask the Agent to build a financial statement, you don't get a static table of numbers. You get a living file where changing an input auto-recalculates everything.

PowerPoint 的更特别——它不仅教 Agent 怎么生成 PPT，还教它怎么做不像 AI 做的 PPT。里面列了配色方案、排版规则，还有一条"永远不要在标题下面加装饰条"。这是个很细节的判断：AI 做 PPT 最爱干的事情就是在标题下加一条彩色横线，这个 Skill 明令禁止了。

PowerPoint's is even more special — it doesn't just teach the Agent how to make slides, it teaches how to make slides that don't look AI-generated. It includes color schemes, layout rules, and one line: "never add decorative bars under titles." This is a remarkably detailed judgment: AI's favorite PPT move is adding a colored line under every title, and this Skill explicitly forbids it.

四个 Skill 的安装路径都是 ~/.pi/agent/skills/ 下面的对应目录。Pi 默认就会扫描这里，你只需要确认文件存在就行。

All four Skills live under ~/.pi/agent/skills/. Pi scans here by default — just verify the files exist.

到这里，你的 Pi 能做的事情：联网搜索、读论文、写报告、做表格、出 PPT。

At this point, your Pi can: search the web, read papers, write reports, build spreadsheets, generate slides.

但还有一个东西让整个体验进了一步——多模型协作。

But there's one more thing that elevates the entire experience — multi-model collaboration.

Pi 内置了一个 escalation 机制。它的逻辑很简单：你日常用一个便宜的模型（比如 DeepSeek V4），Agent 在执行过程中如果发现某个任务自己搞不定——连续失败两次、或者遇到不熟悉的领域——会自行决定把任务交给更强的模型。

Pi has a built-in escalation mechanism. The logic is simple: you use a cheap model daily (e.g., DeepSeek V4). When the Agent encounters a task it can't handle — two consecutive failures, or an unfamiliar domain — it autonomously escalates to a stronger model.

强模型处理完，自动把结果交回来。你继续在便宜模型上对话，不需要手动切换。整个过程你是无感知的，除非你去看日志。

The stronger model handles it and returns the result automatically. You keep chatting on the cheap model, no manual switching needed. The entire process is invisible unless you check the logs.

这就形成了一个很自然的工作流：80% 的任务用便宜的模型，20% 的硬骨头自动升级到旗舰。不用全程开着贵的跑，也不用在任务中间手动切来切去。

This creates a natural workflow: 80% of tasks run on the cheap model, the 20% hard problems auto-escalate to flagship. No need to run expensive models the whole time, no need to manually switch mid-task.

这个机制默认启用。想看可用模型的话，/models-status。

This mechanism is enabled by default. Check available models with /models-status.

用了一个多月，我整理了一份最短配置清单：

After over a month, I've distilled a minimal setup checklist:

开始态：npm install -g @earendil-works/pi-coding-agent，然后 /login 或者配 API Key。

Getting started: npm install -g @earendil-works/pi-coding-agent, then /login or configure API key.

搜索：pi install npm:@lokiyou/pi-web-search，去 Tavily 拿个免费 Key 填进 config.json。

Search: pi install npm:@lokiyou/pi-web-search, grab a free Tavily key and fill config.json.

文档：确认 ~/.pi/agent/skills/ 下有 pdf、docx、xlsx、pptx 四个目录。没有就从 Pi 的 skills 目录拷过去。

Documents: verify pdf, docx, xlsx, pptx directories exist under ~/.pi/agent/skills/. If not, copy them from Pi's skills directory.

多模型：默认就有，不用额外配置。

Multi-model: built-in by default, no extra config needed.

这份清单装完，Pi 基本上覆盖了我日常 90% 的场景。剩下的 10% 是每个人自己特有的工作流——但那正好是 Pi 设计里留给你自己去建的部分。

With this checklist, Pi covers roughly 90% of my daily scenarios. The remaining 10% is everyone's unique workflow — which is exactly what Pi's design leaves room for you to build yourself.

如果你也是 macOS 用户，建议把终端字体调到 14pt 以上。Pi 的 TUI 在 Retina 屏幕上小字体的时候会显得挤，调大之后舒服很多。

If you're also on macOS, I recommend setting terminal font to 14pt or above. Pi's TUI looks cramped at small sizes on Retina screens — much more comfortable after sizing up.

我用 Pi Agent 一个多月了，这是完整的上手指南