Pi Agent 零基础实操指南:从终端配置到完成首个自动化任务
作者:小墨同学(@xiaomovps)•发布日期:2026-08-26 13:45•专栏:AI Agent 终端实操
Pi Agent 零基础实操教程
第一次接触终端 Agent,最先要掌握三件事:
划清文件读写边界、看懂实时工具调用,以及跑通一次可独立核验的任务。
网上有很多命令速查表,但新手打开终端看着闪烁的光标,往往不知道第一句该怎么写。更常见的隐患是轻信 Agent 回复的“已经完成”,既不检查输出文件的实际路径,也不核对原文件是否受损、关键字段是否漏掉。
这篇教程只演示一件完整的事:在独立练习目录里放入一份模拟会议记录,让 Pi 读取并生成行动清单。任务跑完后,我们不看 Pi 的口头总结,直接回到命令行核对原文件哈希值、输出文件、负责人和截止日期。
本文目录
- 01|认识 Pi:区分本地 Agent 与本地模型,了解终端工具的读写流程。
- 02|安装与登录:新建独立练习目录,完成全局安装、版本确认与账号认证。
- 03|首个实操任务:用 @ 引用会议记录,在提示词里写明材料、动作、限制和验收方式。
- 04|命令行验收:核对 SHA-256 哈希值、输出文件、三位负责人与截止日期。
- 05|规则与会话管理:掌握 ! 与 !! 命令区别、AGENTS.md 规则加载及会话分支操作。
一、Pi 能做什么
Pi 是运行在终端里的编码与任务 Agent。你在指定目录启动它后,它可以读取文件、修改内容、写入新文件,也能执行本机 Shell 命令。交互方式接近对话,但改动会直接落到本地磁盘上。
- 本地 Agent 与本地模型的区别
Pi 客户端运行在你的电脑上,文件读写范围受当前系统账号权限控制;负责推理的大模型既可调用云端 API,也可接入本地模型服务。
- 直接读写本地文件
网页聊天工具只能输出文本供你手动复制粘贴;Pi 可以直接读取 input/项目会议记录.md,并将整理结果写入 output/行动清单.md。
Pi Agent 核心能力概览
二、安装、确认版本与登录
1. 新建独立的练习目录
启动终端 Agent 前,不要直接在桌面、下载目录或正式代码仓库里操作。先建一个隔离的练习目录,把输入和输出分开:
| 1 | mkdir -p ~/Downloads/Pi-Agent-零基础实操-demo/input |
| 2 | mkdir -p ~/Downloads/Pi-Agent-零基础实操-demo/output |
| 3 | cd ~/Downloads/Pi-Agent-零基础实操-demo |
2. 全局安装 Pi
通过 npm 执行官方全局安装命令(附带 --ignore-scripts 参数):
| 1 | npm install -g --ignore-scripts @earendil-works/pi-coding-agent |
npm 安装 Pi
版本号确认 0.80.10
3. 两种登录认证方式
进入练习目录后运行 pi。你可以在输入框内输入 /login 授权已有的 Claude Pro/Max 或 ChatGPT Plus/Pro 订阅,也可以通过环境变量配置模型服务商的 API Key。
Pi 登录入口选择
三、认识终端界面的四个区域
Pi 终端四大区域
- 顶部启动区
显示当前版本号、快捷键提示,以及已加载的上下文文件(如 AGENTS.md)、主题、Skill 与扩展包。
- 中间消息区
实时展示工具调用记录(read、write 及 Shell 命令执行)。相比模型的文字回复,工具调用记录才能准确反映磁盘上的实际变动。
- 下方输入区
支持输入自然语言指令、@文件 路径补全与斜杠命令。任务偏离预期时,按 Escape 键可立即中断执行。
- 底部状态栏
显示当前工作目录、模型名称、推理深度(low/high)、Token 费用与上下文窗口占用比例。
状态栏详细指标
四、跑通第一个可验收的任务
在 input/项目会议记录.md 中写入包含 3 位负责人、3 个截止日期和 3 条风险提醒的测试记录。运行 Pi 之前,先计算原文件的 SHA-256 哈希值:
| 1 | shasum -a 256 input/项目会议记录.md |
| 2 | # e1d5fce2a192e31aa5bbc676c93621f58f12f52f4b76c4ba7580c6f4fe594eca |
在 Pi 输入框键入 @input/项目会议记录.md 补全文件路径:
@文件 候选补全
任务提示词四要素结构(材料 + 动作 + 限制 + 验收)
| 1 | 读取 input/项目会议记录.md,整理成 output/行动清单.md。必须保留每个事项、负责人、截止日期和风险提醒;不要修改 input 中的原文件,不要访问当前练习目录以外的内容。完成后列出新增和修改的文件,并说明我应该怎样验收。 |
提示词提交
工具 write 事件发生
回到命令行执行五项独立验收
五项验收对照表
| 检查项 | 命令行验证方式 | 验收结论 |
|---|---|---|
| 1. 输入文件未改动 | shasum -a 256 执行前后哈希值一致 | PASS |
| 2. 输出文件已生成 | test -f output/行动清单.md && echo PASS | PASS |
| 3. 三位负责人齐全 | 核对小林、小周、小陈均在清单中 | PASS |
| 4. 三个截止日期准确 | 核对 2026-08-28、08-30、09-01 对应无误 | PASS |
| 5. 风险提醒完整保留 | 核对命令有效性、隐藏凭据等 3 条提醒未丢失 | PASS |
五、用 AGENTS.md 管理项目规则与本地命令
!命令 与 !!命令
单个感叹号 ! 执行命令后会将输出发给大模型;双感叹号 !! 只在本地终端回显结果,不占用模型上下文。
AGENTS.md 与 /reload
把“input 目录只读、结果写入 output 目录”等固定规则写进项目根目录的 AGENTS.md,在会话中输入 /reload 即可重新加载生效。
感叹号执行命令
/reload 重新加载规则
六、会话树、分支与上下文压缩
Pi 内置了多会话与上下文管理命令:
- 退出与恢复:运行
pi -c继续上一次对话;运行pi -r从列表选择历史会话。 - 会话树与分支:输入
/tree查看对话节点树;输入/fork从任意历史节点切出新分支,尝试不同改法而不覆盖原记录。 - 上下文压缩:长对话接近上下文上限时,输入
/compact汇总早期对话记录,释放上下文空间。
会话树与 Fork 操作
七、权限边界与练习顺序
注意:提示词约束不等于系统权限隔离
在提示词里写“不要修改其他目录”只是给模型的文字约定,无法替代操作系统的权限控制。运行来源不明的外部脚本或第三方 Extension 时,必须在受限账号或隔离环境中先做测试。
后续练习建议
-
第一步:练习单文件读取与格式整理,养成跑完任务后用命令行做五项验收的习惯。
-
第二步:在项目根目录编写 AGENTS.md 固定读写规则,配合 Git 分支管理核对每次改动。
-
第三步:把高频重复任务封装成独立 Skill 或 Extension,减少重复输入提示词。
下一步:创建你的本地 AGENTS.md
跑通上面的单次练习后,你可以直接在练习目录新建一份 AGENTS.md,写入目录只读约束与输出格式要求,再运行 /reload 验证规则加载效果。先在模拟文件上把“下发指令、观察工具事件、命令行独立核验”跑熟,再把 Pi 引入日常真实项目。
觉得本文有启发?一键复制标准引用摘要
自带原文归因链接与核心摘要,可直接粘贴至团队飞书/Slack 知识库、技术周报或大模型上下文。