第 1 课：什么是 pi 与第一次会话

什么是 pi？

Pi 是一个极简终端编程代理（minimal terminal coding agent）。它是一个运行在终端里的程序，连接 AI 模型，帮你处理代码和文件。可以把它想象成一个真正能"动手"的 AI 助手：能读取文件、修改文件、运行命令——而不只是聊天。

它的理念是：让 pi 适应你的工作流，而不是反过来。 它自带可靠的默认配置，但刻意省略了一些功能（子代理、计划模式、权限弹窗、内置待办清单）。相反，你可以通过技能（skills）、提示词模板（prompt templates）、扩展（extensions）和包（packages）按需添加你想要的一切。这让核心保持小巧且可预测。

如何安装 pi

Pi 以全局 npm 包的形式安装：

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

也可以使用 curl -fsSL https://pi.dev/install.sh | sh 安装。卸载命令为 npm uninstall -g @earendil-works/pi-coding-agent——注意卸载后你的设置、凭据和会话会保留在 ~/.pi/agent/ 中。

启动 pi

基本命令很简单：

cd /path/to/project
pi

Pi 运行在你的当前工作目录中，并且可以修改该目录下的文件。所以你要从想处理的项目目录启动它。

身份认证

Pi 需要一个模型提供商。两种方式：

方式一——订阅登录： 在 pi 内运行 /login 并选择一个提供商（Claude Pro/Max、ChatGPT Plus/Pro、GitHub Copilot）。

方式二——API 密钥： 启动前设置环境变量：

export ANTHROPIC_API_KEY=sk-ant-...
pi

或者用 /login 把密钥存到 ~/.pi/agent/auth.json。Pi 支持很多提供商：Anthropic、OpenAI、Google Gemini、DeepSeek、Groq、OpenRouter、xAI 等 25 个以上。

第一次会话

pi 启动后，直接输入请求并按 Enter：

Summarize this repository and tell me how to run its checks.

默认情况下，pi 会给模型四个工具：

• read — 读取文件
• write — 创建或覆盖文件
• edit — 精确修改文件
• bash — 运行 shell 命令

另外三个只读工具（grep、find、ls）可通过 CLI 选项启用。模型会自己决定何时使用这些工具来完成任务——你可以实时观察它工作：读取文件、运行命令、展示结果。

安全提示： pi 可以修改文件并在你的工作目录中运行命令。为了便于回滚，请在 git 仓库中工作。

现在就来试试

1. 在任何项目里打开终端并运行 pi。
2. 在编辑器中输入 @——会出现模糊文件搜索，方便引用文件。
3. 试试 !git status——以 ! 开头的命令会在 shell 中运行并且把输出发送给模型。!!git status 运行但不发送输出。
4. 输入 /hotkeys 查看所有键盘快捷键。

一次性模式

你并不总是需要交互模式。快速提问时：

pi -p "Summarize this codebase"
cat README.md | pi -p "Summarize this text"
pi -p @screenshot.png "What's in this image?"

-p（打印模式）回答后即退出。以 @ 前缀的文件会被包含进消息中。

---

作业： 在一个真实项目中启动 pi，端到端完成一个小任务（例如："找到 X 的定义并解释给我听"）。观察模型如何使用它的工具。