《万字长文 | Pi Agent 零基础实操：从打开终端到完成第一个真实任务》
作者: 小墨同学 @xiaomovps
我最近一直在想，普通人第一次接触终端 Agent，最应该学会的到底是什么。
不是背诵复杂的底层参数或自动化脚本，而是分清材料边界、盯住工具调用，并完成一次能够独立核对的真实任务。
网上很容易找到一长串命令。很多人看完似乎懂了不少，真把终端打开，光标一闪，又不知道第一句话该写什么。更麻烦的情况是，Agent 回了一句“已经完成”，人也跟着放心了，文件究竟写到了哪里、原材料有没有被覆盖、里面漏了什么字段，全都没看。
所以这篇教程只做一件完整的事：在一个独立练习文件夹里放入一份虚构的会议记录，让 Pi 读取它并生成行动清单。任务结束后，我们不用 Pi 自己的总结作证明，直接回到命令行检查原文件校验值、输出文件、负责人和截止日期。
📖 本文导读纲要：
- 01｜认识 Pi：理清本地 Agent 与本地模型的区别，理解可执行工具的闭环。
- 02｜安装与界面：从独立练习目录开始，完成全局安装、版本确认与认证登录。
- 03｜第一个真实任务：用 @ 引用会议记录，把材料、动作、限制和验收写进提示词。
- 04｜独立验收：核对 SHA-256 校验值、输出文件、三位负责人与截止日期。
- 05｜扩展与安全：理解 !/!! 命令隔离、AGENTS.md 规则持久化与会话分支管理。
一、Pi 能帮普通人做什么
Pi 是一个运行在终端里的 Agent。你在某个文件夹里启动它，它可以围绕当前任务读取文件、写入文件、修改内容，也可以执行本机命令。它回复你的方式仍然像聊天，可它能继续动手，把结果真实落到电脑里。
1. 本地 Agent vs. 本地模型
Pi 程序运行在你的电脑上，能接触什么文件和命令与你的启动路径权限相关；而负责理解和生成的大模型既可以来自云端 API，也可以来自本地服务。两者是不同概念。
2. 具备真实操作闭环
普通聊天工具只能生成文本让你手动复制粘贴，而 Pi 可以直接读取 input/项目会议记录.md 并自动写入 output/行动清单.md。
二、安装、确认版本与登录
1. 先给第一次练习单独建个文件夹
终端 Agent 最容易被忽略的一步，发生在启动以前。别直接在桌面、下载目录或正式项目里跑。先建立一个专门的练习沙盒：
mkdir -p ~/Downloads/Pi-Agent-零基础实操-demo/output
cd ~/Downloads/Pi-Agent-零基础实操-demo
2. 从官方复制全局安装命令
使用 npm 完成官方全局包安装（带 --ignore-scripts 参数）：
3. 登录的两条路径
进入练习目录后运行 pi。认证方式支持在输入区输入 /login 通过 Claude Pro/Max、ChatGPT Plus/Pro 订阅授权，或者直接配置对应模型提供方的 API Key。
三、第一次打开 Pi，先看懂四个区域
1. 顶部启动区
显示版本、快捷键提示，以及当前加载的 Context（如 AGENTS.md）、主题、Skill 与扩展包。
2. 中间消息区
呈现真实工具调用流（read、write、Shell 执行）。文字总结可以很顺，但工具事件才能告诉你电脑上到底发生了什么。
3. 下方输入区
支持输入文字、@文件 补全以及斜杠命令。按 Escape 可随时中断当前失控或超范围的任务。
4. 底部状态栏
展示当前目录、模型名称、思考级别（low/high）、Token 成本与上下文占用率。
四、完成第一个可以验收的真实任务
在 input/项目会议记录.md 中存入包含 3 位负责人、3 个日期、3 条风险提醒的会议记录，并在执行前计算 SHA-256 校验指纹：
# e1d5fce2a192e31aa5bbc676c93621f58f12f52f4b76c4ba7580c6f4fe594eca
在 Pi 输入区键入 @input/项目会议记录.md 选定材料：
读取 input/项目会议记录.md，整理成 output/行动清单.md。必须保留每个事项、负责人、截止日期和风险提醒；不要修改 input 中的原文件，不要访问当前练习目录以外的内容。完成后列出新增和修改的文件，并说明我应该怎样验收。
脱离 Agent 总结：回到命令行执行五重物理验收
| 检查项 | 物理验证方式 | 验收结论 |
|---|---|---|
| 1. 输入文件未被篡改 | shasum -a 256 执行前后值 100% 恒定 | PASS |
| 2. 输出文件真实存在 | test -f output/行动清单.md && echo PASS | PASS |
| 3. 三位负责人无遗漏 | 小林、小周、小陈逐一核对 | PASS |
| 4. 三个截止日期无偏差 | 2026-08-28 / 08-30 / 09-01 准确映射 | PASS |
| 5. 风险提醒未被压缩 | 核对命令有效性、隐藏凭据等 3 条提醒完整保留 | PASS |
五、让 Pi 理解文件和项目规则
!命令 与 !!命令
单个 ! 执行命令并将输出送入模型；双感叹号 !! 执行命令仅在终端本地打印，绝不污染模型上下文。
AGENTS.md 规则持久化与 /reload
将“input 只读、输出到 output”等长期约束写入项目根目录的 AGENTS.md，输入 /reload 即可热更新生效。
六、会话树、分支与上下文压缩管理
Pi 具备强大的会话管理能力：
- 退出与恢复：
pi -c快速继续上次对话；pi -r选择历史会话。 - 会话决策树：输入
/tree可视化查看历史节点；使用/fork从任意历史点裂变新会话，安全尝试平行方案。 - 上下文瘦身：对话过长导致 Context 饱满时，执行
/compact自动压缩早期历史，腾出推理空间。
七、安全边界与新手三阶进阶法
⚠️ 警惕：提示词约束 ≠ 物理系统隔离
在提示词里写“不要修改其他目录”属于业务层软约束。面对不可信的外部脚本或第三方 Extension，务必使用系统权限隔离与独立练习文件夹，先测试再引入生产环境。
🚀 新手三阶升级路线：
1. 第一阶段：单文件读写与格式整理，掌握 5 重独立物理验收习惯。
2. 第二阶段：编写 AGENTS.md 固化项目规范，结合 Git 分支管理与自动化测试。
3. 第三阶段：将高频重复流程封装为专属 Skill 或 Extension，构建自动化工作流。
💡 结语与思考
玩终端 Agent 最好的起点，永远是从一份丢了也不心疼的虚构材料开始。当你亲手看着一个输入文件被工具精准读取，又通过命令行核对出完整的校验值与输出文件，你对终端 Agent 的掌控感就真正建立起来了！