3.2 Pi 入门：安装、首次运行与核心操作

📌 基于 Pi（@earendil-works/pi-coding-agent）· 2026-09 更新。Pi 是开源的终端 AI 编程 Agent，迭代较快。命令和界面以 pi --version 对应的官方文档为准，本页只教不会变的那部分：心智模型和核心操作范式。

一、本节你会做出什么

你会在终端里请到一个真正能干活的 AI：你说一句话，它读你的文件、改你的代码，然后你用 git diff 验收它。

📷 效果位：Pi 运行中的终端界面，AI 正在读文件并提出修改

这一节走完，你就具备了本课后面所有项目的“生产力底座”。

二、开始前你需要

已完成 3.1 工具全景与选择建议，并且选定了终端 Agent 做主力
已完成 2.2：node -v 能打印版本号（Pi 需要 Node 18 以上）
已完成 2.3：这一节会让 AI 直接改你的文件，没有 Git 兜底不要开始
2.2 里建的 hello-node 项目（删了的话，回 2.2 第 5 步重建一个）

⚠️ 选了 AI IDE 的同学：操作部分可以跳过，但请读完「第 2 步：它到底在干什么」——那是所有终端 Agent 的共同心智模型，第 6 章排错要用。

三、跟着做

第 1 步：安装

推荐方式（Mac / Windows 通用），用你在 2.2 装好的 npm：

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

-g 是全局安装（2.2 讲过）。装完验证：

pi --version

打印出版本号就成功了。

Mac / Linux 另有一条官方的一键脚本：curl -fsSL https://pi.dev/install.sh | sh。

还记得 2.1 那条安全线吗——“从网上直接下载并执行的一长串，只接受官网文档里给出的那条”。这条正是官网文档给出的那条，所以它满足条件。 但如果你更想稳妥，就用上面的 npm 方式，效果一样。

Windows 用户：请用 Windows Terminal（系统自带或应用商店可装）而不是老式命令行窗口，Pi 的界面需要终端支持 True Color 才显示正常。

📷 截图位 1：pi --version 的输出

第 2 步：它到底在干什么（这段比安装重要）

在敲第一条命令之前，先建立心智模型。Pi 不是一个聊天框，它是一个循环。

你说一句话之后，它在反复做这四件事：

     ┌──────────────────────────────┐
     │  1. 读：打开你的文件看内容     │
     │  2. 想：决定下一步做什么       │
     │  3. 做：改文件 / 执行命令      │
     │  4. 看：看看结果对不对         │
     └──────────┬───────────────────┘
                │  不对就回到第 1 步，继续
                ▼
            做完，向你汇报

这个循环带来三个你必须知道的后果：

后果	对你意味着什么
它能看到你整个项目	你不用把代码贴给它，说文件名就行
它会真的动手改文件	没有 Git 存档 = 裸奔。这就是 2.3 排在前面的原因
一句话可能触发几十步操作	交代任务要交代清楚，否则它会朝错误方向跑很远

💡 一句话记住：在线工具是“点菜”，AI IDE 是“和师傅一起干”，终端 Agent 是“派活给施工队”——所以派活的质量决定一切，这正是 3.5 整节要讲的事。

第 3 步：首次运行与登录

关键动作：先 cd 到项目文件夹，再启动 Pi。

cd ~/Documents/ai-course/hello-node     # Mac，换成你的路径
cd D:\ai-course\hello-node              # Windows，换成你的路径
pi

🔴 这是新手第一大坑：Pi 只看得到你启动它时所在的那个文件夹。站错地方启动，它会对着一个空文件夹发呆，或者在你的用户主目录里乱建文件。启动前先 pwd 确认一次，养成习惯。

首次启动会让你完成认证。在 Pi 的输入框里打：

/login

按提示走完。Pi 支持接多种模型供应商——用 2.4 里注册的那个账号或 API Key 即可。两种常见方式：

方式	怎么做
订阅型账号	`/login` 走浏览器授权流程
API Key	启动 Pi 之前，在终端里设置对应供应商的环境变量（如 `ANTHROPIC_API_KEY`），或按文档写进配置

登录完成后，用 /model 看一眼当前用的是哪个模型。

📷 截图位 2：Pi 的欢迎界面与登录成功提示

配置文件存在哪：~/.pi/agent/。卸载 Pi 不会删掉它，重装后登录状态和设置都还在。

第 4 步：第一句话——先让它“只说不做”

新手最容易犯的错，是第一句话就让它大改。 正确的开场是让它先熟悉项目、也让你熟悉它。

在 Pi 的输入框里打：

先不要改任何文件。请读一下这个项目，用三句话告诉我：
这是个什么项目、用了什么技术、首页文件在哪。

你会看到它开始调用工具读文件，然后给你一段总结。

观察三件事：

它列出了读过哪些文件 —— 这说明它真的在看你的项目，不是在瞎编
它没有改任何东西 —— 说明“先不要改”这句话是有效的
它答得对不对 —— 答错了说明你站错了文件夹，退出重来

✅ 把这条当成习惯：进一个新项目，第一句话永远是“先别改，告诉我这是什么”。第 4.11 节会把这招扩展成一套完整方法。

第 5 步：第一次真实改动（带验收）

现在让它干活。动手之前，先存档——这是 2.3 的规矩一：

先退出 Pi（Ctrl+C 或输入 /exit），执行：

git add -A
git commit -m "Pi 首次改动之前的存档点"

重新 pi 进去，交代任务：

请把首页的主标题改成「我的第一个本地项目」，
副标题改成「由 Pi 帮我改的」。
只改这两处文字，不要动布局和样式。改完告诉我你改了哪个文件。

它会读文件、改文件，然后汇报。注意看它有没有请求你确认——多数情况下写文件前会让你批准一次，看清楚再放行。

验收（关键，别省）：

退出 Pi，在终端执行 2.3 学的两条：

git diff --stat      # 它一共动了几个文件、几行
git diff             # 具体改了什么，红减绿加

你要问自己一个问题：改动范围和我的要求匹配吗？

只改了 1 个文件、几行 → ✅ 正常
动了 6 个文件、300 行 → 🚨 危险信号，回 2.3 用 git restore . 撤掉，重新把需求说清楚

然后 pnpm dev 跑起来，浏览器打开 localhost:3000 看效果。满意就存档：

git add -A && git commit -m "改掉首页标题文案"

📷 截图位 3：git diff 显示的改动 + 浏览器里的新标题

恭喜——你刚刚完成了本课最核心的一个循环：

交代任务 → AI 动手 → git diff 验收 → 满意就 commit，不满意就 restore

后面 9 章，你做的事情都是这个循环的重复，只是任务越来越大。

第 6 步：核心操作速查

不用背，用到时回来查。

输入框里的三个符号

符号	作用	什么时候用
`@`	引用文件，模糊搜索文件名	让它改指定文件：`@app/page.tsx 把这里的按钮改成圆角`
`!`	执行 shell 命令，并把输出给 AI	让它看报错：`!pnpm build`
`!!`	执行命令但不把输出给 AI	你自己想看一眼，不占用 AI 的上下文

@ 是最该练的一个——明确指到文件，AI 跑偏的概率立刻下降一大截。

常用斜杠命令

命令	作用
`/login` `/logout`	登录 / 退出账号
`/model`	换模型
`/settings`	调整思考强度等偏好
`/new`	开一个全新会话（上下文清空）
`/resume`	继续之前的某次对话
`/tree`	浏览会话历史树
`/fork`	从之前某条消息分叉出新对话
`/reload`	重新加载规则文件和扩展
`/export`	把会话导出成 HTML
`/share`	上传成 Gist 分享

键盘快捷键

快捷键	作用
`Shift`+`Tab`	切换思考强度（难任务调高，简单任务调低省钱）
`Ctrl`+`L`	打开模型选择器
`Ctrl`+`V`	粘贴图片（把设计稿或报错截图直接贴给它，非常好用）
`Shift`+`Enter`	换行（不发送）
`Ctrl`+`C`	中止当前操作（2.1 学的那个刹车，这里同样管用）

🚨 最该记住的是 Ctrl+C：发现它朝错误方向跑了，立刻打断，别等它跑完。打断越早，git restore 要清理的东西越少。

第 7 步：`/new` 是什么时候用的（上下文管理入门）

你会遇到这个现象：聊得越久，AI 越糊涂——开始忘记前面说过的事，或者反复改同一个地方改不对。

原因是它的“记忆”（上下文）有容量上限，而一次会话里读过的所有文件、跑过的所有命令输出都堆在里面。

处理办法就一条规矩：

换一件事做的时候，就 /new 开个新会话。

场景	该不该 `/new`
刚做完“改标题”，现在要“加一个表单”	✅ 该
同一个功能改了三轮还没对	✅ 该（换个说法重新讲，往往比继续纠缠更快）
就在刚才那个改动上再微调一下	❌ 不用

完整的上下文管理方法在 3.5，那里会讲清“为什么长会话会变笨”和更多手段。更细的技巧在 [附录 H Pi 进阶技巧]。

第 8 步：规则文件 `AGENTS.md`（先知道有这回事）

在项目根目录建一个 AGENTS.md 文件，Pi 每次启动都会自动读它。写进去的要求，不用每次重复说。

一个最小可用的版本：

# 项目约定

- 本项目使用 Next.js + TypeScript + Tailwind CSS
- 所有回复用中文
- 改动前先说明你打算改哪些文件，等我确认后再动手
- 不要自作主张新增依赖包，需要装什么先问我

这只是尝个味道。规则文件怎么写才真正有效，是 3.5 的重点内容之一。 改完 AGENTS.md 记得 /reload 或重启 Pi 让它生效。

四、完成的标志是

五、卡住了看这里

Q：pi 提示 command not found。 和 2.2 的 Node 一样的老问题：① 关掉终端重开；② npm install -g 是否真的成功（往上翻有没有红色报错）；③ Mac 上如果报 EACCES 权限错误，参考 2.2 第五部分的解法。

Q：界面显示乱码、颜色怪异、框线断裂。 终端不支持 True Color。Windows 换 Windows Terminal；Mac 自带终端一般没问题，也可以换用 iTerm2。可以先跑 echo $COLORTERM 看看是不是输出 truecolor。

Q：/login 打不开浏览器，或者授权后没反应。 ① 手动复制它给的链接到浏览器打开；② 国内网络访问海外服务不稳时，改用「API Key + 环境变量」的方式，接 2.4 里注册的国内模型平台；③ 确认系统时间是准的（时间偏差会导致授权校验失败）。

Q：它说“我找不到这个文件”，但文件明明在。 99% 是你启动 pi 时站错了文件夹。/exit 退出，pwd 确认位置，cd 到项目根目录再 pi。

Q：它改了一堆我没让它改的东西。 这是终端 Agent 最典型的翻车方式，处理流程固定三步：① Ctrl+C 打断；② git restore . 全部撤销；③ 把需求写得更具体再来一次（“只改 X，不要动 Y”）。这不是事故，这是日常——所以每次动手前存档才那么重要。

Q：它一直在转圈/跑了很久也没结束。 可能陷进了“改了又错、错了又改”的循环。Ctrl+C 打断，git restore .，然后 /new 换个说法重新描述。硬等下去通常只会烧更多钱。第 6.3 节有完整的破局手段。

Q：怎么知道我花了多少钱？ 按量计费的话，去 2.4 里那个模型平台的账单页看用量。记得当时设的消费上限。日常省钱的办法：简单任务用 Shift+Tab 调低思考强度，以及做完一件事就 /new（会话越长，每轮重复发送的上下文越多）。

Q：它要执行一条命令，让我批准，我该不该点同意？ 看命令。读文件、ls、pnpm dev 这类放心同意。出现 rm -rf、sudo、或者往你项目外面写东西的，先停下来问它为什么——2.1 那条安全线在这里同样适用。

六、本节提示词

① 进入陌生项目的第一句话（存起来，你会用几百次）：

先不要修改任何文件。
请读一下当前项目，告诉我：
1. 这是一个什么项目，用了什么技术栈；
2. 主要的目录和文件分别负责什么；
3. 怎么把它跑起来（给我确切的命令）；
4. 有没有什么地方是现在就坏的、或者明显有问题的。

用中文回答，说人话，我是零基础。

② 让它先出方案再动手（避免大改跑偏，3.5 会展开讲）：

我想实现这个功能：【具体描述】

**先不要写代码。** 请先给我一个方案：
1. 你打算改哪些文件、新建哪些文件；
2. 每个文件大概改什么；
3. 有没有需要我先决定的地方；
4. 这次改动有什么风险。

我确认之后你再动手。

③ 让它自己汇报改了什么（配合 git diff 双重验收）：

你刚才的改动，请用中文列个清单告诉我：
1. 改了哪些文件，每个文件改了什么、为什么；
2. 有没有改到我没要求的地方？如果有，说明原因；
3. 有没有新增依赖包或者改动配置文件？
4. 我现在应该怎么验证效果，给我具体步骤。

④ 让它写第一版 AGENTS.md：

请为当前项目生成一份 AGENTS.md 规则文件，内容包括：
1. 项目的技术栈和目录约定（你从项目里读出来的真实情况，不要编）；
2. 和我协作的方式：用中文、大改动前先出方案等我确认、不擅自加依赖；
3. 代码风格上需要遵守的约定。

写完直接创建到项目根目录，然后把内容念给我听一遍。

上一节 ← 3.1 工具全景与选择建议 下一节 → 3.3 AI IDE：Cursor、Trae 的界面、Chat 与 Agent 模式