出海数字营销宝典 Logo
出海数字营销宝典evaoo.com

Pi Agent 零基础实操指南:从终端配置到完成首个自动化任务

2026-11-06小墨同学 @xiaomovps约 20 分钟阅读

作者:小墨同学(@xiaomovps)•发布日期:2026-08-26 13:45•专栏:AI Agent 终端实操

Pi Agent 零基础实操教程Pi Agent 零基础实操教程

第一次接触终端 Agent,最先要掌握三件事:

划清文件读写边界、看懂实时工具调用,以及跑通一次可独立核验的任务。

网上有很多命令速查表,但新手打开终端看着闪烁的光标,往往不知道第一句该怎么写。更常见的隐患是轻信 Agent 回复的“已经完成”,既不检查输出文件的实际路径,也不核对原文件是否受损、关键字段是否漏掉。

这篇教程只演示一件完整的事:在独立练习目录里放入一份模拟会议记录,让 Pi 读取并生成行动清单。任务跑完后,我们不看 Pi 的口头总结,直接回到命令行核对原文件哈希值、输出文件、负责人和截止日期。

本文目录

  • 01|认识 Pi:区分本地 Agent 与本地模型,了解终端工具的读写流程。
  • 02|安装与登录:新建独立练习目录,完成全局安装、版本确认与账号认证。
  • 03|首个实操任务:用 @ 引用会议记录,在提示词里写明材料、动作、限制和验收方式。
  • 04|命令行验收:核对 SHA-256 哈希值、输出文件、三位负责人与截止日期。
  • 05|规则与会话管理:掌握 ! 与 !! 命令区别、AGENTS.md 规则加载及会话分支操作。

一、Pi 能做什么

Pi 是运行在终端里的编码与任务 Agent。你在指定目录启动它后,它可以读取文件、修改内容、写入新文件,也能执行本机 Shell 命令。交互方式接近对话,但改动会直接落到本地磁盘上。

  1. 本地 Agent 与本地模型的区别

Pi 客户端运行在你的电脑上,文件读写范围受当前系统账号权限控制;负责推理的大模型既可调用云端 API,也可接入本地模型服务。

  1. 直接读写本地文件

网页聊天工具只能输出文本供你手动复制粘贴;Pi 可以直接读取 input/项目会议记录.md,并将整理结果写入 output/行动清单.md。

Pi Agent 核心能力概览Pi Agent 核心能力概览

二、安装、确认版本与登录

1. 新建独立的练习目录

启动终端 Agent 前,不要直接在桌面、下载目录或正式代码仓库里操作。先建一个隔离的练习目录,把输入和输出分开:

BASH3 行
1mkdir -p ~/Downloads/Pi-Agent-零基础实操-demo/input
2mkdir -p ~/Downloads/Pi-Agent-零基础实操-demo/output
3cd ~/Downloads/Pi-Agent-零基础实操-demo

2. 全局安装 Pi

通过 npm 执行官方全局安装命令(附带 --ignore-scripts 参数):

BASH1 行
1npm install -g --ignore-scripts @earendil-works/pi-coding-agent

npm 安装 Pinpm 安装 Pi

版本号确认 0.80.10版本号确认 0.80.10

3. 两种登录认证方式

进入练习目录后运行 pi。你可以在输入框内输入 /login 授权已有的 Claude Pro/Max 或 ChatGPT Plus/Pro 订阅,也可以通过环境变量配置模型服务商的 API Key。

Pi 登录入口选择Pi 登录入口选择

三、认识终端界面的四个区域

Pi 终端四大区域Pi 终端四大区域

  1. 顶部启动区

显示当前版本号、快捷键提示,以及已加载的上下文文件(如 AGENTS.md)、主题、Skill 与扩展包。

  1. 中间消息区

实时展示工具调用记录(read、write 及 Shell 命令执行)。相比模型的文字回复,工具调用记录才能准确反映磁盘上的实际变动。

  1. 下方输入区

支持输入自然语言指令、@文件 路径补全与斜杠命令。任务偏离预期时,按 Escape 键可立即中断执行。

  1. 底部状态栏

显示当前工作目录、模型名称、推理深度(low/high)、Token 费用与上下文窗口占用比例。

状态栏详细指标状态栏详细指标

四、跑通第一个可验收的任务

在 input/项目会议记录.md 中写入包含 3 位负责人、3 个截止日期和 3 条风险提醒的测试记录。运行 Pi 之前,先计算原文件的 SHA-256 哈希值:

BASH2 行
1shasum -a 256 input/项目会议记录.md
2# e1d5fce2a192e31aa5bbc676c93621f58f12f52f4b76c4ba7580c6f4fe594eca

在 Pi 输入框键入 @input/项目会议记录.md 补全文件路径:

@文件 候选补全@文件 候选补全

任务提示词四要素结构(材料 + 动作 + 限制 + 验收)

TEXT1 行
1读取 input/项目会议记录.md,整理成 output/行动清单.md。必须保留每个事项、负责人、截止日期和风险提醒;不要修改 input 中的原文件,不要访问当前练习目录以外的内容。完成后列出新增和修改的文件,并说明我应该怎样验收。

提示词提交提示词提交

工具 write 事件发生工具 write 事件发生

回到命令行执行五项独立验收

五项验收对照表五项验收对照表

检查项命令行验证方式验收结论
1. 输入文件未改动shasum -a 256 执行前后哈希值一致PASS
2. 输出文件已生成test -f output/行动清单.md && echo PASSPASS
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 重新加载规则/reload 重新加载规则

六、会话树、分支与上下文压缩

Pi 内置了多会话与上下文管理命令:

  • 退出与恢复:运行 pi -c 继续上一次对话;运行 pi -r 从列表选择历史会话。
  • 会话树与分支:输入 /tree 查看对话节点树;输入 /fork 从任意历史节点切出新分支,尝试不同改法而不覆盖原记录。
  • 上下文压缩:长对话接近上下文上限时,输入 /compact 汇总早期对话记录,释放上下文空间。

会话树与 Fork 操作会话树与 Fork 操作

七、权限边界与练习顺序

注意:提示词约束不等于系统权限隔离

在提示词里写“不要修改其他目录”只是给模型的文字约定,无法替代操作系统的权限控制。运行来源不明的外部脚本或第三方 Extension 时,必须在受限账号或隔离环境中先做测试。

后续练习建议

  1. 第一步:练习单文件读取与格式整理,养成跑完任务后用命令行做五项验收的习惯。

  2. 第二步:在项目根目录编写 AGENTS.md 固定读写规则,配合 Git 分支管理核对每次改动。

  3. 第三步:把高频重复任务封装成独立 Skill 或 Extension,减少重复输入提示词。

下一步:创建你的本地 AGENTS.md

跑通上面的单次练习后,你可以直接在练习目录新建一份 AGENTS.md,写入目录只读约束与输出格式要求,再运行 /reload 验证规则加载效果。先在模拟文件上把“下发指令、观察工具事件、命令行独立核验”跑熟,再把 Pi 引入日常真实项目。

Pi Agent

觉得本文有启发?一键复制标准引用摘要

自带原文归因链接与核心摘要,可直接粘贴至团队飞书/Slack 知识库、技术周报或大模型上下文。