第一章 Pi 能帮你做什么

1.1 从一个小任务认识它

假设你有一个小项目，里面有个函数叫 add，但它错误地把两个数相减。你希望有人查看文件，找出问题，把减号改成加号，再检查结果。这个任务很短，却已经包含几种不同工作：理解要求、获取项目内容、决定怎样修改、真正写入文件、判断修改是否有效。

在 Pi 里，你可以用自然语言提出这件事。例如：“请看看 calculator.js 里的 add，修复加法，并告诉我改了什么。”这句话是任务的入口。Pi 接下来会把相关信息交给模型，让模型在可用工具的帮助下逐步处理。文件是否读取成功、修改是否匹配、检查是否通过，都可能影响下一步。

“工具”是软件实际能够调用的操作。读取文件是一种工具，执行命令是一种工具，修改文件也是一种工具。工具执行后有结果：可能是文本，也可能是错误。例如读取一个不存在的文件，应该得到文件错误；它不会因为模型希望文件存在，就自动变成成功。

“Agent”在本书中指一种工作方式：程序让模型作出下一步选择，执行被选择的工具，把结果交回模型，再决定是否继续。它通常要经过多轮交互。Pi 提供了实现这套流程的运行框架，并把常用编程工具、会话管理和终端界面组合成了可以直接使用的命令行产品。

你第一次使用时，可以把它想成一个需要看到材料、也需要收到检查反馈的编程协作者。任务说明越具体，它越容易判断应当查看哪里，以及怎样确认完成。

1.2 模型、工具和运行框架分别负责什么

模型接收消息，并生成后续内容。它可能直接回答，也可能生成结构化的工具调用请求。例如，它请求名为 read 的工具，并给出一个文件路径。这个请求本身只是数据；操作系统不会因为数据里出现了 read 就自行读文件。

Pi 中的运行框架负责接住这个请求。它需要找到工具，检查参数是否符合要求，真正执行工具，再把结果放回后续消息中。若用户取消任务，它还要传递取消信号。若界面要显示进度，它还要发布执行事件。这些工作共同决定“一个回答”怎样变成“一个能够持续推进的过程”。

工具负责具体操作。默认编程工具包括 read、bash、edit 和 write。read 读取内容；bash 运行命令；edit 根据匹配内容修改文件；write 写入文件内容。模型不会自动拥有你电脑上的所有功能，它只能使用宿主程序提供给它的能力。反过来，工具一旦执行了真实写入，工作目录里的文件也就真的改变了。

还有一种参与者叫“模型服务提供方”，即接受模型请求的服务。Pi 的统一接口支持多家提供方。你选择哪家服务、哪个模型，以及使用什么认证方式，会影响可用能力、响应速度、费用和限制。把模型换成另一家，并不意味着文件工具也要重写；这正是分层设计要解决的问题。

可以用下面这张责任表记忆它们：

1.3 一次修改为什么会有多轮

把加法任务拆开，就能看到一次常见的执行过程。下面是解释用的流程，不是已经运行过的日志：

用户：修复 calculator.js 中的 add
模型：请求 read，查看 calculator.js
工具：返回函数内容
模型：请求 edit，把错误的表达式改成加法
工具：返回修改结果
模型：根据项目情况请求相关检查
工具：返回检查结果
模型：说明修改和验证情况

如果第二步显示文件路径不正确，后面就不能原样继续。模型可能需要列目录或让用户补充信息。如果修改工具报告没有找到预期内容，也应该重新查看文件，而不是宣布修复完成。工具结果之所以必须回到模型消息中，是因为后续决定依赖现实状态。

你也可以给出更有限的任务：“只解释这个函数，先不要修改。”这时任务目标改变，读取和回答可能就足够。对于仓库中的程序，项目规则也会约束如何处理，例如只能运行特定测试，或不得擅自提交代码。这些约束会进入上下文，影响模型的选择；具体操作仍由实际工具和执行环境完成。

对新手来说，先观察这条链路比先学习所有命令更有效。看到一条工具记录时，问自己：它要获取什么证据？返回了什么？这份结果怎样改变下一步？这三个问题能够帮助你分辨“有一段看起来合理的文字”与“有可以检查的执行依据”。

1.4 命令行产品和可复用基础库

从使用者角度看，最明显的产品是 pi：你在终端里启动它，输入要求，看到流式回答和工具记录。从工程角度看，仓库还提供了一组基础库。开发者可以只调用模型，也可以把 Agent 放到自己的应用里，或者通过 RPC 让另一个程序控制 Pi。

“CLI”是 Command-Line Interface 的缩写，意思是命令行界面。“SDK”是 Software Development Kit 的缩写，意思是供其他程序使用的开发接口。“RPC”指进程或程序之间的一种远程调用方式；在 Pi 的 RPC 模式中，另一个程序可以发送结构化命令，并接收事件。你不需要在第一天就写 SDK 程序，但理解它们都是入口形式，有助于看懂目录为何分成多个包。

这个仓库还有独立的持久化运行时 durable，以及状态同步、远程执行、外部工具协议等模块。它们扩展了工程的应用范围。我们会在后面单独介绍，并清楚区分：哪些能力属于默认 CLI，哪些需要配置或扩展，哪些属于独立基础库。