← Pi Agents

安装、首次会话与第一个任务

把 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 与思考级别。