个人知识库

主题

Pi 大道至简，超越Codex和Claude Code的极简Agent，保姆级全攻略， 一期视频精通 ​

B 站 · 技术爬爬虾 · 44:37 · 原视频 正文与截图来自 BiliNote 任务 4434d162-e3f9-4448-8df0-a35b093167d8，本页只做 vault 格式转换。

视频章节 ​

时间章节
00:001. Pi Agent 简介与核心优势
01:172. 安装指南：Windows 与 Mac
02:283. 模型配置：API Key 与订阅登录
03:364. 基础使用与界面信息解读
06:435. 指令追加机制：Steering 与 Follow-up
10:056. 核心 Agent Loop 双层循环架构
10:557. 一次性非交互模式与 Session 管理
12:138. 高级会话管理：对话树、克隆与分叉
16:289. 上下文压缩机制：Compact 与 New
17:2410. 极简设计哲学与基础工具
18:1911. 插件扩展系统：安装与实战
27:1012. Skills 技能系统：安装与全局配置
30:5913. Pi Web UI 网页端使用指南
34:1414. 记忆系统：AGENTS.md 与全局提示词
37:5115. 安全机制与沙箱运行建议
39:4916. DIY 插件：让 AI 自己写插件
43:0117. 源码架构与 SDK 开发
—AI 总结

1. Pi Agent 简介与核心优势 · 00:00 ​

Pi 是近期热度极高的 AI Agent，其核心特点可以用四个字形容：大道至简。它仅有四个基础工具，系统提示词也仅仅只有 1000 token 左右。

极简带来的极致效率：

  • Token 消耗极低：在 Pi 中说句“你好”仅占用 1100 上传 Token。相比之下，在 Codex 中仅打招呼就占用 18000 token（白白消耗了 7% 的上下文窗口）。
  • 速度极快：根据 Composer 上个月的基准测试，Pi Agent 完成编程任务的速度比起其他 Coding Agent 快了 1.5 到 2 倍。
  • 成本极低：任务成本比起主流框架（如 Codex、Claude Code）低了不少。
  • 质量极佳：数据服务大厂 Data Breaks 在自家百万行代码仓库上进行了基准测试。横轴是任务成本，纵轴是任务通过率（代码质量）。图表显示，整张图代码质量的最高点就是 Pi + Claude Opus 4.8 的组合，在大部分场景下表现优于 Claude Code 和 Codex。

2. 安装指南：Windows 与 Mac · 01:17 ​

Windows 操作系统安装 ​

  1. 在桌面右键，选择“在终端中打开”（Windows PowerShell）。
  2. 来到 Pi 官网，找到 PowerShell 的一键安装命令并复制。
  3. 粘贴到控制台回车。Pi 检测到没有 Node.js，输入 Y 回车先安装 Node.js。
  4. 继续输入 Y 回车安装 Pi 本体。
  5. Pi 使用 Git Bash 作为命令行运行环境。如果没有安装过 Git，它会询问，建议输入 W 让 Pi 帮你安装。
  6. 安装结束后，关闭当前的命令行窗口，重新打开一个终端，输入 pi 即可启动。

macOS 操作系统安装 ​

  1. 打开终端。
  2. 去 Pi 官网复制 Curl 命令，粘贴进终端执行即可完成安装。

3. 模型配置：API Key 与订阅登录 · 02:28 ​

启动 Pi 后，输入命令 /login 进行配置。有两种配置模型的方法：

方法一：API Key 配置 ​

  1. 选择 Sign in with an API Key。Pi 支持 40 多家模型供应商。
  2. 以 DeepSeek 为例，输入关键词筛选出 DeepSeek 并回车。
  3. 去 DeepSeek 官网的 API 开放平台，确保有额度，创建并复制 API Key。
  4. 将 Key 填写到 Pi 里面回车，发送消息测试即可。

方法二：模型订阅登录 ​

  1. 输入 /login，选择 Sign in with account。
  2. 选择对应的服务商（如 OpenAI Codex），选择 Browser login。
  3. 在浏览器完成登录后回到 Pi，敲快捷键 Ctrl + L 即可看到模型列表。

模型切换与思考强度：

  • 输入 /model 切换模型。
  • 使用快捷键 Shift + Tab 切换模型的思考强度（根据任务复杂程度选择）。
  • Ctrl + L 快速打开模型选择面板。

4. 基础使用与界面信息解读 · 03:36 ​

多行输入与执行 ​

  • 输入指令时，按回车直接发送。
  • 多行换行：使用 Shift + Enter，或按快捷键 Ctrl + G 打开一个记事本编辑器，编辑完成后保存关闭，提示词会自动同步。

底部信息栏解读 ​

当 Pi 完成任务后，底部会显示一行详细数据：

  • 上箭头 ↑：整个 Session 的输入 token。
  • 下箭头 ↓：输出 token。
  • 大写 R：整个 Session 里面有多少 token 命中了缓存（Read）。
  • CH：最近一次请求的缓存命中率（Cache Hit Rate），非整个 session 的。
  • 预估成本：括号里的 (sub) 代表 Subscription（订阅），即使用的是订阅账号，成本仅供参考。
  • 百分比与窗口：如 4.6%/272k 表示当前占用了模型 4.6% 的上下文窗口，GPT5.6 总上下文为 272K。
  • auto：自动压缩机制，达到阈值自动触发。
  • 提供商与模型：如 openai-codex gpt-5.6-sol。
  • 思考强度：最后面的 . high 表示当前模型的思考强度。

终端运行命令 ​

  • 在对话窗口敲一个英文叹号 !，输入命令（如 npm run dev），AI 可以看到命令运行的结果和过程。
  • 敲两个叹号 !!，输入命令，AI 看不到运行过程和结果。

图片与文件交互 ​

  • 截图沟通：直接截图，在 Windows 上按 Alt + V，Mac 上按 Ctrl + V 粘贴给 AI。
  • @ 文件：输入 @ 符号，选择某个代码文件进行针对性沟通。

5. 指令追加机制：Steering 与 Follow-up · 06:43 ​

当 AI 在执行过程中理解错了意思，Pi 提供了两种追加指令的方式：

Steering（引导 / 打方向盘） ​

  • 操作：在 AI 执行过程中，直接输入补充指令并按回车。
  • 效果：指令前会显示 Steering。AI 会立即改变执行方向。这是 Pi 的默认追加方式。

Follow-up（排队） ​

  • 操作：输入指令后，按 Alt + Enter（Mac 为 Option + Enter）。
  • 效果：指令前显示 Follow-up。不会影响 AI 当前这一轮的工作，而是等待 AI 完成全部工作后才会看到并执行。
  • 注意（Windows）：需先修改 PowerShell 设置，删除 Alt+Enter 全屏的快捷键（在设置 -> 操作中找到并删除）。
  • 修改排队指令：按 Alt + 上箭头 可以把排队中的指令拿回来重新编辑。

6. 核心 Agent Loop 双层循环架构 · 10:05 ​

Pi 实现上述两种指令追加的核心机制是双层循环：

  1. 内层循环：调用大模型 -> 提取工具调用 -> 执行工具 -> 将结果返回给模型 -> 判断是否完成（shouldStop）。如果未完成，进入下一轮循环。
    • 巧妙设计：进入下一轮循环时，Pi 会把 Steering 消息注入上下文，从而对用户的指令进行实时反应。
  2. 外层循环：检查是否有 Follow-up 消息。如果有，则开启外层循环继续工作。Follow-up 消息处于外层循环，需要等待内层循环处理完毕才能读取。

7. 一次性非交互模式与 Session 管理 · 10:55 ​

非交互模式 ​

输入 pi -p "指令内容"，Pi 会在后台静默执行，中间过程不可见，执行完毕后输出结果。适合把 Pi 当作一次性 CLI 命令使用。

Session 基础管理 ​

  • Session 是会话管理的单元。一个连续的对话记录就是一个 Session。
  • 输入 /new 创建一个新的 Session，清空上下文窗口。
  • 输入 pi -c：从最近的一次 Session 继续对话。
  • 输入 pi -r：挑选一个历史 Session 进行对话。

8. 高级会话管理：对话树、克隆与分叉 · 12:13 ​

Pi 的特色功能是对话树。Session 不是纯线性结构，而是树状结构。

对话树 (/tree) ​

  • 输入 /tree 进入树状视图。
  • 可以选择历史节点回退对话。注意：树回退只能回退对话历史，不能回退代码。代码回退需要配合 Git 使用（如 git reset --hard <commit-id>）。

回退选项 ​

回退对话历史时，Pi 提供三个选项：

  1. No summary：彻底回退，抛弃后面的历史。
  2. Summarize：对丢弃的分支进行总结，完成后 AI 会对这段工作有大概印象。
  3. Summarize with custom prompt：自定义总结提示词。

克隆与分叉 ​

  • /clone：把当前 Session 完整复制一份成为新的 Session。
  • /fork：不是克隆整棵树，而是选择一个对话节点，基于该节点复制出一个新的 Session。新 Session 只携带之前的对话历史。

9. 上下文压缩机制：Compact 与 New · 16:28 ​

  • /compact：手动触发上下文压缩。Pi 会把之前的对话历史进行总结和精简，从而释放上下文空间，降低后续 token 消耗。
  • 通用经验：清空好于压缩。过多的历史会话会干扰 AI 的注意力。执行完一轮任务后，最好直接输入 /new 新开一个 Session，将注意力集中到新任务上。

10. 极简设计哲学与基础工具 · 17:24 ​

Pi 默认只有四个基础工具：Read (读文件)、Write (写文件)、Edit (改文件)、Bash (运行命令)。

  • 设计理念：用最小的一组工具覆盖绝大多数编程任务。特别是 Bash 工具，可以调用 fd 搜索文件、grep 检索代码等。
  • 没有的功能：没有 MCP、没有 Sub Agent、没有 Plan mode、没有 Todo、没有 BTW。
  • 哲学：核心越小越干净，模型能更好发挥。用户拥有最大自由度去组装其他能力。

11. 插件扩展系统：安装与实战 · 18:19 ​

Pi 提供了丰富的扩展能力，主要体现在插件（Extensions）和技能（Skills）两个方面。

插件安装基础 ​

  • 安装命令：pi install npm:<package-name>。
  • 默认安装到全局目录。
  • 项目级安装：在命令后加 -l（local），插件只对当前项目生效，并存储在项目目录的 .pi 文件夹下。

核心插件推荐与实战 ​

  1. pi-web-access：让 Pi 具备联网搜索能力，零配置模式，无需 API Key。
    • 卸载：将 install 改为 uninstall。
  2. pi-subagents：让 Pi 拥有并行运行多个子代理的能力。
    • 用法：/pi-subagents，可以让多个 worker 并行开发。
  3. pi-mcp-adapter：让 Pi 具备 MCP 功能。
    • 配置：自动读取项目目录下的 .mcp.json 文件。可配置高德地图 MCP 等。
  4. pi-btw：旁路对话功能。
    • 用法：/btw。可以在 AI 工作的同时开启旁路对话提问，不会打断主工作。
  5. pi-plan-mode：计划模式。
    • 用法：/plan-mode。AI 不会直接干活，而是先输出一份计划（如 plan.md），确认后关闭模式并让 AI 执行。
  6. pi-goal：目标模式。
    • 用法：/goal。让 AI 在多个轮次中朝固定目标执行，直至完成。适合大型项目迭代。
  7. pi-dynamic-workflows：动态工作流。
    • 类似 Claude Code 的特色功能，可编写 JS 脚本在后台自动调度几十个或上百个子代理同时协同工作。
    • 用法：/workflows，可通过 /workflows 命令查看后台子代理工作状态。
  8. pi-wechat-assistant：微信连接。
    • 用法：/wechat login 扫码登录，/wechat start 启动。可以在手机微信上给 Bot 发消息，电脑端 Pi 会同步执行并回复。

12. Skills 技能系统：安装与全局配置 · 27:10 ​

Skills 是近一年的热点，Pi 遵循标准的 Skills 协议。

  • 项目级技能路径：项目目录/.agents/skills/skill-name/SKILL.md。
  • 全局级技能路径：用户目录/.agents/skills/skill-name/SKILL.md。

Playwright CLI 技能实战 ​

  1. 先安装工具本体：npm install -g @playwright/cli@latest。
  2. 从 GitHub 下载源码，找到 skills 文件夹，复制到指定目录。
  3. 启动 Pi，看到 [Skills] 里有了 playwright-cli，即可让 AI 操作浏览器。

Skill Hub 检索与安装 ​

  • 网站：skillhub.cn。
  • 可通过下载 zip 或直接将提示词发给 AI 让 AI 安装（如安装 markdown-converter 技能）。
  • 若缺少依赖（如 uv），可以直接让 Pi 帮你安装。

13. Pi Web UI 网页端使用指南 · 30:59 ​

对于不习惯命令行的用户，可以使用社区开发的 Web UI（如 pi-web，GitHub 4200+ star）。

  • 安装运行：npx @agegr/pi-web@latest，会自动打开浏览器界面。
  • 界面功能：
    • 左上角切换项目，或选择自定义路径。
    • 左下角文件浏览器查看项目文件。
    • 左下角模型按钮：可添加 Provider 并配置 API Key。
    • 模型选择器：选择具体的模型。
    • 管理技能和插件：可以开关项目级或全局的技能/插件（关闭可节省 token）。
    • 添加技能：可在面板搜索并安装（如免费的 TTS 技能）。
    • 对话面板：支持斜杠命令、@ 文件、截图粘贴、调整思考强度等。

14. 记忆系统：AGENTS.md 与全局提示词 · 34:14 ​

跨 Session 的记忆通过 AGENTS.md 文件实现。每次新对话，AI 都会读取该文件作为上下文。

项目级记忆 ​

  • 在项目根目录创建 AGENTS.md。
  • 可让 Pi 通读项目源码后，自动生成该文件，记录项目架构、技术栈等信息。

全局记忆与安全提示 ​

  • 全局 AGENTS.md 路径：C:\Users\你的用户名\.pi\agent\AGENTS.md（Mac 为 ~/.pi/agent/AGENTS.md）。
  • 可在此处编写全局提示词，如要求禁止批量删除文件，只能通过明确路径单个删除。

追加系统提示词 ​

  • 在全局配置目录新增 APPEND_SYSTEM.md 文件，内容会直接追加到系统提示词中，优先级更高。

15. 安全机制与沙箱运行建议 · 37:51 ​

Pi 只有一个基础安全机制：在包含插件/技能的陌生目录启动时，询问是否信任。一旦开始运行，它处于最高权限，没有杀伤机制，自动执行命令不询问。

安全运行方案 ​

  1. 使用沙箱：官方推荐在容器、虚拟机中运行 Pi。如 WSL（Windows Linux 子系统）、Hyper-V、Docker 容器等。即使环境被搞坏，删掉重建即可，不影响宿主机。
  2. 安全插件：安装 pi-permission-system 插件，在执行敏感操作时会弹出审批窗口（类似 Claude Code）。

16. DIY 插件：让 AI 自己写插件 · 39:49 ​

Pi 开放了大量接口（如生命周期 Hook、工具系统、UI 渲染等），并且内置了插件开发知识，可以自己给自己写插件。

实战案例：

  1. 定制 UI 插件：让 Pi 编写一个根据 IP 查询地理坐标和天气，并展示到对话框的插件。编写好后放在 .pi/extensions/ 目录下，输入 /reload 重新加载即可生效。
  2. 安全防护插件：让 Pi 写一个禁止读取 .env 文件的插件，或者在执行 rm 命令时弹窗询问。

17. 源码架构与 SDK 开发 · 43:01 ​

Pi 的源码在 GitHub 上开源，是一个 Agent 设计规范的教科书。

  • 核心包：
    • ai：负责模型调用，统一市面上几十个模型厂商的接口。
    • agent：实现 Agent Loop（双层循环机制）。
    • coding-agent：编程功能具体实现，包含 4 个基础工具、系统提示词、skills 机制等。
    • tui：命令行界面实现。
  • SDK：开发者已将核心包封装成 SDK。可以在项目中安装 @earendil-works/pi-ai 和 pi-coding-agent，直接引用 createModel 方法接入所有大模型，或快速拥有一个开箱即用的 Coding Agent。

AI 总结 ​

本视频全面解析了极简 AI Agent Pi 的设计理念、安装配置与进阶玩法。Pi 以“大道至简”为核心，仅用 4 个基础工具和 1K 系统提示词，实现了超越 Codex 和 Claude Code 的极快速度与极低成本，同时在代码质量基准测试中表现出色。

教程覆盖了从基础安装、模型接入（API/订阅）、Steering 与 Follow-up 指令机制、双层 Agent Loop 原理，到 Session 管理、对话树高级操作等核心功能。更深入讲解了如何通过插件（如联网、子代理、MCP、微信接入）和 Skills（如 Playwright 浏览器自动化）扩展能力，以及通过 Web UI 和 AGENTS.md 记忆系统提升使用体验。最后强调了其安全哲学（沙箱运行）与强大的 DIY 插件能力（让 AI 自己写插件），展现了 Pi 极高的自由度与扩展潜力。