安装、首次会话与第一个任务
把 Pi 跑起来,并交给它一件真正的事:安装、工作文件夹、身份验证、第一个任务,以及当结果不是你想要的样子时该怎么办。
在为智能体写代码之前,你得先运行一个。本章会把你从零带到一次含有真实工 作的会话,然后把大部分篇幅花在真正困难的那部分上:给智能体一个它能完成的 任务。
安装
在 macOS 或 Linux 上,Pi 有一个安装程序:
curl -fsSL https://pi.dev/install.sh | sh
或者从 npm 安装,这要求 Node.js 22.19 或更高版本:
# The book's path: the release every claim here was checked against.
npm install -g --ignore-scripts @earendil-works/pi-coding-agent@1.0.4
# The managed path: whatever is current when you run it.
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
Pi 在一次普通的 npm 安装中不需要依赖项的生命周期脚本,这就是
--ignore-scripts 出现在那里的原因。
如果你想严格照本书的论断来做,就用锁定版本的那种形式,并且在看到差异时说出
来。这里的一切都是针对 1.0.4 写的:受管理的安装程序会跟随当前发布版,而
在两者不一致的地方,本书描述的是较旧的那个。在相信任何一条关于行为的论断之
前,先用 pi --version 确认。
要说清楚这个锁定做了什么、没做什么。@1.0.4 固定的是 pi-coding-agent 本身
的版本。它不锁定它所依赖的东西,npm 会把那些传递依赖解析到满足条件的版本
——这正是 quickstart.md 在这个安装程序与那个"锁定所有依赖"的安装程序之间划
出的区分。如果你需要一棵完全可复现的依赖树,那是安装程序或锁定文件该管的事,
不是一个版本范围该管的事。
自 1.0.1 起,在 macOS 和 Linux 上还有第三条路径,三者之间的差别不是表面 上的:
nix profile add github:earendil-works/pi/stable
第一条路径那个安装程序会"锁定所有依赖,并用 pi update 更新
Pi"。npm 路径,按 quickstart.md 现在的说法,“不锁定传递依赖”。Nix 从源码构
建 Pi,用 nix profile upgrade pi 更新,并且完全不能由 pi update 更新——包与
模型目录的更新依然有效,但二进制的移动是包管理器说了算。
对一个跟着读的读者来说,这个选择很少有意思。对一个要把 Pi 部署到团队或 CI 镜像里的读者来说,这就是全部决策:一棵锁定的依赖树可复现,一棵未锁定的不可 复现,而 Pi 现在正是出于这个理由建议把全局的 npm 安装迁移到受管理的安装程 序。第 22 章会回到这对你发布的包里那些依赖意味着什么。
验证一下:
pi --version
原生 Windows 有一条单独的准备路径,Termux 下的 Android 也有一条。如果你用的 是其中任何一种,先读对应的文档再继续——差别在 shell 的选择与存储上,不在智能 体循环上。
工作文件夹不是细节
这是人们会跳过的一步,而它带来的改变比你预期的多。
cd /path/to/folder
pi
工作文件夹做三件事。它帮助 Pi 发现相关文件、指令与配置。它是 Pi 查找适用于
你手头工作的上下文文件的地方。而它是 Pi 对已保存会话分组的方式,这正是
pi --continue 能恢复正确那段对话的原因。
在正确的目录里启动 Pi。一个在你主目录里启动的会话,和一个在你正在处理的仓库 里启动的会话,不是同一个会话,它们也看不到同样的指令。
身份验证
在 Pi 内部:
/login
选择一个 provider 并按提示操作——使用订阅,或存储一个 API 密钥。然后:
/model
会搜索可用模型,并显示那些其 provider 拥有可用身份验证的模型。在某个模型上按
Ctrl+S 可将其保存为新会话的默认模型。
如果你根本不想让 Pi 写入凭据,那就改为设置该 provider 的环境变量。这是 CI 中 的正确选择,但它同时也是优先级最低的来源:当配置了多个凭据来源时,你刚刚导出 的那个常常被一个已存储的来源盖住。第 3 章给出确切的顺序。
交给它一个任务
Pi 会显示它执行的每一次文件读取、每一次搜索、每一条命令和每一次编辑。它不会 在每次工具调用前都询问。这一点值得直说,因为它对任何在真实机器上运行智能体的 人来说,是唯一最重要的操作事实。
一些效果不错的任务:
Summarize @meeting-notes.md and save the action items to action-items.md.
Explain how this repository is structured and how to run its checks.
Compare @previous.csv with @current.csv and summarize the important changes.
在编辑器里输入 @ 可以搜索文件,而不必输入它的路径。
然后,当 Pi 完成时,审阅它的响应以及任何被改动的文件。对重要的工作使用版 本控制或备份。对不可信的或无人值守的工作,使用容器或另一个沙箱。
这一段不是文档里的套话。它是操作契约,而第 42 章就是解释其中真正利害所在的那 一章。
一个你能继续构建的首次会话
完整的路径,按顺序排列。每一步都是出问题时可以停下来的地方。
flowchart TD
I["安装 pi<br/>受管理的安装程序、npm 或 nix"] --> V["pi --version<br/>本书预期 1.0.4"]
V --> F["选择一个项目文件夹<br/>可以随手扔掉的东西"]
F --> A["身份验证<br/>用 pi,或 --api-key / 环境变量"]
A --> T["项目信任提示<br/>授予一次"]
T --> C["pi config<br/>检查发现了什么"]
C --> P["第一个真实任务"]
版本检查刻意排在第二位,而它正是大多数人跳过的那一步。本书是针对 1.0.4
写的;如果 pi --version 报告的是别的东西,那么接下来那些关于行为的论断描述
的是另一个程序。要说出来,并去读漂移说明,而不是在阅读过程中悄悄地把差异抹
平。
接下来的章节会构建扩展、技能和包,而第二部分是这一切真正开始的地方。你会想要
一个项目来做这些东西——某种一次性的、里面只有一件小东西的东西。最小的有用示例
是一个带 .pi/ 的目录:
my-agent/
├── AGENTS.md 上下文文件:指令,适用于本目录及其以下
└── .pi/ 项目配置
├── APPEND_SYSTEM.md 追加到系统提示词
├── settings.json 项目设置:工具与资源
└── prompts/
└── review.md 一条可复用的提示词,可作为 /review 使用
.pi/ 是会绊住人们的那部分,所以直说:项目配置住在 .pi/ 下面。
settings.json、APPEND_SYSTEM.md、SYSTEM.md、mcp.json 以及资源目录都在
那里。一个直接放在 my-agent/ 里的 APPEND_SYSTEM.md 是仓库里的一个文件,
Pi 不会把它当配置读,而且它会在无声中失败。
例外情况,以及产生它的那条规则:一个上下文文件是按位置找到的,而其他一切
都按约定在 .pi/ 下找到。
| 你想要什么 | 放在哪里 | 如何被发现 | 需要项目信任吗? |
|---|---|---|---|
| 适用于本文件夹及其以下的指令 | 位于文件夹根部的 AGENTS.md |
从工作目录向上回溯 | 否 |
| 替换基础系统提示词的指令 | .pi/SYSTEM.md |
.pi/ 下的约定 |
是 |
| 追加到系统提示词的指令 | .pi/APPEND_SYSTEM.md |
.pi/ 下的约定 |
是 |
| 工具、资源与模式默认值 | .pi/settings.json |
.pi/ 下的约定 |
是 |
可复用的提示词,以 /name 形式 |
.pi/prompts/*.md |
.pi/ 下的约定 |
是 |
| MCP 服务器 | .pi/mcp.json |
.pi/ 下的约定 |
是 |
| 技能 | .pi/skills/<name>/SKILL.md |
递归搜索 SKILL.md |
否 |
最后一列是现在就该记住、而不是等到第 8 章才记住的那一列:一个陌生人的仓库可以
用一个 AGENTS.md 引导你的模型,不论你有没有授予信任,但少了它就不能运行代码
或更改你的系统提示词。第 28 章详细给出发现规则,而第 8 章讲的正是那个信任决策
给你带来什么、不带来什么。
Pi 第一次会要求项目信任。授予它,Pi 就会发现 .pi/extensions、.pi/skills
和 .pi/prompts。第 8 章讲那个信任决策实际做什么,而在你再次授予它之前,那值
得先弄明白。注意 SYSTEM.md 和 APPEND_SYSTEM.md 在那道信任门之内,而上下文
文件不在——一个陌生人的仓库可以用一个 AGENTS.md 更改你的指令,却不能更改你
的系统提示词。
当你在那里的时候,把这个命令跑一次:
pi config
它会显示被发现的资源,以及 pi 的内置扩展,并让你启用或禁用它们。当某样东西没 有出现时,这是要跑的第一个命令——其频繁程度远超本应去读源码的必要程度。
稍后继续
会话会自动保存。要恢复同一个工作文件夹最近的那次会话:
pi --continue
用 /resume 来选择另一个已保存的会话。
为什么第一个任务如此重要
再看一遍那三个例子。它们没有一个说明该怎么做这件事。每一个都说明了完成品是什 么样子、点出了材料是什么、并指出了输出去哪里。
拿它跟最常见的第一个提示词比一比:
Fix the bug.
那条提示词没什么问题。它只是一个不同的请求:它把任务的定义和执行一起委托了出 去,而且它这么做的那个语境里,智能体才刚刚启动,对这个仓库、这个代码库的约 定、或者"修好了"在这儿意味着什么,一无所知。
三个现在就该养成的习惯:
**点出材料。**一个 @file、一个目录、一套测试。智能体能找到东西,但你知道哪些
东西相关。
**说明输出应该是什么。**一个文件、一个 diff、一张表格、编辑器里的一个数字。 “总结"让格式保持开放;“把行动项保存到 action-items.md"则不然。
**先让它看。**在要求改动之前先要求对仓库的解释,这很便宜,而且它把智能体的理解 摆在你面前,趁它还错着、还容易纠正的时候。
第 10 章会详细展开这个论证,因为它是全书里杠杆最高的技能,也是反馈循环最短的 那个。你今天就可以练它,在写下一行扩展代码之前。
刚刚发生了什么
四个命令,你就启动了一个进程、对它做了身份验证、给了它一个可以工作的文件 夹、跑了一个任务,并在之后恢复了它。本书余下部分描述的一切——扩展运行时、技 能路由器、设置优先级链、会话文件——都在那个进程内、那段对话上、那个文件夹里 运作。
下一章
你有了一个能跑的循环,还有跑在它里面的东西。你还不知道的是这个循环跑在什么之 上。模型、provider、凭据、思考级别和缓存状态坐在本书每一个机制的下面,会产生 看起来跟上一层里的 bug 一模一样的症状,所以它们是接下来要弄对的东西。
第 3 章:模型、provider 与思考级别。