第四章 第一次使用 Pi

4.1 先分清工具、模型与服务商

第一次接触 Pi，最容易混在一起的是三个名字。Pi 是运行在你电脑上的助手程序，负责接收任务、整理上下文、调用工具、保存会话。模型是生成回答并决定下一步操作的系统。服务商则提供访问模型的账号、接口或本地服务。安装 Pi，只完成了第一件事；还需要选择可用的模型访问方式。

可以把一次任务理解为这样的配合：你要求“读一下项目说明，告诉我如何启动”，Pi 把请求和工具说明交给模型；模型提出读取文件；Pi 真正打开文件，再把内容送回模型。文件访问发生在 Pi 运行的环境中，回答生成则取决于所选模型。远程模型通常需要网络，本地模型需要另行准备相应服务。

本书以仓库提交 16f5f0af4d85ca583d045ceb5ed6d646fcaf7761 为基准。这个版本的 npm 包名是 @earendil-works/pi-coding-agent，命令名是 pi。网上旧文章可能使用旧包名或旧快捷键，遇到差异时应先核对版本，不要把不同年代的安装方法拼在一起。

4.2 安装已经发布的程序

普通使用者可以从 npm 安装。npm 是 Node.js 的软件包管理工具；Node.js 是运行 Pi 的程序环境。本版本要求 Node.js 至少为 22.19，安装前可在终端检查环境：

node --version
npm --version

满足要求后，官方文档给出的 npm 安装命令是：

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

-g 表示把命令装到当前 npm 的全局位置，让你能在不同目录运行 pi。–ignore-scripts 表示安装时不执行软件包的生命周期脚本；官方明确说明，正常 npm 安装不需要这些脚本。如果终端找不到 pi，需要检查 npm 全局命令目录是否进入 PATH。PATH 是终端寻找命令时检查的一组目录。

macOS 和 Linux 还可以使用官网安装器。它固定安装依赖，并通过 pi update 更新；直接 npm 安装不会固定全部间接依赖。Windows 有对应的安装说明。本章不要求初学者同时尝试所有方法：选择一种，记录来源，以后按该方法更新即可。这些命令是操作示例，本书没有替你执行安装。

从源码开发是另一条路线。那时你需要克隆整个仓库，在仓库根目录用 npm install –ignore-scripts 安装工作区依赖，再通过 ./pi-test.sh 运行源码。这里的脚本名称虽然包含 test，却是文档提供的源码启动入口。普通使用者不需要为了运行已发布的 Pi 而先构建整个工程，也不需要学习每个内部包。

4.3 在一个明确的文件夹里开始

选择一个熟悉的小项目，在终端进入它，再启动 Pi：

cd /path/to/project
pi

这里的路径需要替换成真实目录。当前工作目录会影响默认文件路径、配置发现和会话分组。第一次练习可以使用有备份的小项目，这样每次读取和修改都有具体对象，也容易检查结果。启动界面会显示会话、输入区以及模型、上下文和用量等信息。

进入 Pi 后输入 /login，选择服务商，按提示连接订阅账号或保存 API 密钥。API 密钥可以理解为允许程序调用服务的凭证，不能写进公开项目。之后用 /model 选择当前可用模型。能看到某个模型名称，不等于已经拥有调用权限；账号、密钥、服务端点以及模型支持范围仍需匹配。

第一条任务可以写成：“请阅读 README.md，介绍这个目录的用途，并列出你还需要核实的内容。暂时不要修改文件。”输入框中的 @ 可以帮助你搜索并附加文件，但这不是唯一读取方式；模型也可能主动调用 read。按 Enter 提交后，观察界面中的文件读取和工具结果，最后把回答与原文对照。

Pi 默认启用四个基础工具。read 读取文件内容；bash 执行终端命令；edit 按指定内容修改已有文件；write 写入文件。它还提供可选工具，但初学时先记住这四个，就能解释大部分工作过程。例如“读说明”通常需要 read，“查看 Git 状态”可能需要 bash，“调整一段代码”可能需要 edit。

任务进行中也能补充说明。交互模式下，Enter 提交的补充通常用于调整当前工作；Alt+Enter 提交的后续任务等待当前工作结束。Escape 可以中止正在进行的任务。不同终端可能占用快捷键，准确按键应以 /hotkeys 和当前终端说明为准。中止也不能自动撤销已经完成的文件写入。

4.4 理解费用与实际权限

Pi 的费用与模型访问方式有关。远程 API 往往按输入、输出和缓存等用量计费；订阅账号按服务商条款处理；本地模型则消耗你自己的计算资源。token 是模型处理文字等内容时使用的计量单位，并不等于一个汉字。长文件、反复工具调用和上下文压缩都可能增加模型请求。

界面底部和 /session 可以帮助查看用量与费用，但显示结果依赖模型价格等描述信息，以及服务商返回的用量，不能代替服务商账单。初次使用时选择较小任务，观察请求次数和用量，再逐步扩大范围，比先让助手扫描整个磁盘更容易判断成本。不要把安装了开源程序误解成所有模型调用都免费。

权限同样需要具体理解。Pi 默认不会在每次工具调用前都请求确认。工具使用启动 Pi 的操作系统账号权限；当前目录是工作起点，并不是隔离墙。bash 可以运行该账号能够运行的命令，扩展也在 Pi 进程内执行。项目中一句“请只读”是工作约定，不会改变操作系统权限。

项目信任控制项目配置、扩展、技能等资源是否加载，并不限制启动后工具能访问哪些路径。AGENTS.md 等上下文文件还有独立的加载规则。需要强隔离时，应采用容器、虚拟机或其他操作系统边界，并只暴露任务所需文件和凭证。日常工作中则保留版本记录、检查差异、确认结果再发布。