Pi Coding Agent 的常见使用方式是在代码项目目录中启动终端程序，用自然语言提出任务，再观察它读取文件、调用工具和反馈结果。它连接模型与本地开发环境；理解需求和生成下一步动作的是模型，实际文件操作由工具完成。产品入口是 Pi 官网。
本文涉及命令和功能的说明按 2026 年 9 月 17 日官方文档核实。
第一次启动
通过 npm 安装需要先准备可用的 Node.js 与 npm，具体运行环境要求应以所安装版本为准。官方安装命令为：
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
进入准备处理的项目目录后执行 pi。安装 CLI 与获得模型访问权限是两个步骤：还需要通过 /login 或对应提供商的 API Key 配置认证，再用 /model 选择可用模型。具体过程见官方快速入门。
界面里能看到什么
Pi 使用终端交互界面。中间的消息区域展示用户输入、模型回答、工具调用和执行结果；输入区用于继续描述任务；底部显示工作目录、模型及上下文等状态。它的工作过程因此不只是最后一段回答，也包括中途查了哪些文件、执行了哪些动作。
常用交互包括输入 @ 查找文件、用 /settings 调整设置，以及用 /session 查看当前会话。完整命令和快捷键见使用说明。
一次任务可能怎样进行
下面是说明性场景，不是一次实际运行记录。假设项目已有一个数组分页函数和对应测试，用户提出：
检查分页函数为什么在空数组时出错，修复后运行相关测试，并说明改动。
Agent 可能先读取函数与测试，确认输入约定；再修改实现或补充测试；随后执行测试命令。如果出现失败，它会把错误输出作为下一次判断的依据，继续查找原因。
用户可以据此检查三个不同的结果：代码是否真的改变、测试是否真的执行、回答中的结论是否与工具输出一致。例如“建议运行测试”与已经出现测试执行结果，代表不同的完成程度。
从只读任务开始
了解陌生仓库时，可以先限制模型可调用的工具：
pi --tools read,grep,find,ls -p "说明项目入口、主要模块及测试位置"
这里 -p 表示输出回答后退出，工具白名单只包含读取和查找能力。这便于观察 Agent 如何收集证据。需要注意，工具白名单约束的是模型可调用的工具；已经加载的扩展仍是可执行程序，不能把这个参数视为整个进程的沙箱。
项目约定与执行权限
项目中的 AGENTS.md 可以描述编码约定、测试命令和任务限制，帮助 Pi 理解工作环境。应把这些说明写成具体要求，例如“相关测试命令是什么”，而不是笼统要求“保证一切正确”。
Pi 的项目信任机制控制是否加载项目本地配置和扩展；它与文件、进程和网络隔离是不同层次。Pi 继承启动它的系统用户权限，真正需要隔离的执行环境应由容器或其他沙箱提供。边界见官方安全说明。
输入文件、图片与直接运行命令
在交互输入中键入 @ 可以查找项目文件并把所选文件作为本次消息的输入；也可以在支持的终端中粘贴或拖入图片。能否理解图片仍取决于当前模型是否支持图片输入。
以 ! 开头的命令会在当前环境执行，并把输出发给模型；以 !! 开头则执行命令但不把输出加入模型上下文。后一种方式适合只想自己查看结果的情况。两者都会真正执行命令，区别在于输出是否交给模型，而不是是否产生外部影响。
交互、单次输出与结构化模式
Pi 不只提供交互终端：
| 模式 | 行为 | 常见用途 |
|---|---|---|
| 默认交互模式 | 保持终端界面，可连续输入和观察工具调用 | 需要逐步参与的编码任务 |
-p / --print |
处理提示、输出结果后退出 | Shell 脚本或一次性查询 |
--mode json |
以 JSONL 输出运行事件 | 日志采集和程序处理 |
--mode rpc |
通过标准输入输出接收命令和推送事件 | 由其他程序持续控制 |
例如，pi -p "概括这个代码库的入口" 是一次性任务；它没有交互界面，不等于关闭工具或会话保存。各模式的参数与输出契约见官方使用说明。
运行中补充要求
Agent 工作时仍可发送消息。普通 Enter 提交的是 steering 消息：它会在当前 assistant turn 的工具调用结束后、下一次模型调用前送达。Alt+Enter 提交 follow-up：等当前 Agent 工作结束后再开始处理。
假设 Agent 正在修改分页函数：
- 输入“先不要改接口签名”属于改变当前处理方向，适合 steering。
- 输入“完成后再解释测试覆盖范围”属于后续任务，适合 follow-up。
- 按 Escape 会中止当前运行，并把尚未处理的排队消息还给编辑器。
消息已经排队，不代表模型已经看到；工具正在执行时，steering 也不会撤销已经发生的文件或命令操作。详细时序见消息队列文档。
怎样判断一次任务完成
界面中的自然语言结论、工具执行完成和需求真正满足是三个层次。检查结果时可以依次确认：
- 模型是否明确说明修改了什么；
- 工具记录是否显示目标文件确实发生变化；
- 测试或检查命令是否真正运行，以及退出状态和输出是什么；
- 当前工作区是否还存在与任务有关的未处理问题。
中止运行只会停止后续处理，不会自动回滚已经完成的写入。需要恢复代码时，应使用项目自己的版本管理或备份机制。