YT 学习笔记

Pi Agent 入门精进：四件工具、四层扩展与 CMAX 多 agent 编排

30分钟阅读下载 MD

封面

David Ondrej · 47:02 · 发布 2026-06-12 · 4.9万次观看(截至抓取) · 观看原视频

主旨

David Ondrej 把 Pi Agent(由 Mario 打造的极简 AI 编码 harness)从安装、上下文配置、四件工具、四层扩展一路讲到 CMAX 多 agent 编排与反 MCP 的设计立场,主张把 Pi 当作个人可塑的底层平台、由主人自己注入上下文与扩展,而不是当一个产品级 IDE 来用。

核心论点

  1. Pi 是 harness 不是产品——Claude Code 与 Codex 是面向千万用户的”产品”,高 opinionated、慢、装满 safeguard;Pi 只带四个工具、1000 token 的系统提示,把它适配到你的工作流,而不是反过来。(→ 详解1)
  2. 上下文由三层 markdown 文件承载,且兼容 CLAUDE.md——system.md 完全覆盖、append system.md 追加在系统提示末尾、agents.md 可全局或按项目生效;Pi 甚至直接读 CLAUDE.md 存量配置。(→ 详解2)
  3. 四件工具 = 整台电脑——Read / Write / Edit / Bash 里 Bash 一项就足以驱动整台机器,因为绝大多数应用/服务最终都暴露了终端入口。(→ 详解3)
  4. 让 agent 自己改造 agent——不要人肉背命令,装好 Pi 后让它替你装扩展、改提示、配 skill。“你才是瓶颈”(You, the human, are the limiting block)。(→ 详解4)
  5. 四种增强方式由轻到重——agents.md 永远在线 → prompt templates 用 slash 触发 → skills 触发式自动加载 → extensions 真正可执行的 TypeScript 代码;越往后能力越大、改造成本越高。(→ 详解5)
  6. Pi 是 YOLO 模式 + 必须配最强模型——不弹权限询问、不给小模型留情;用户用 Opus 4 fast 之类的最贵最强模型来弥补安全感的缺口,新手可装 pi-permission-system 兜底。(→ 详解6)
  7. Pi + Codex 是最强多 agent 编排组合——Pi 当指挥(sleep + 读其他 agent 的输出),Codex CLI 当执行者;LLM 读输出比人快约 100 倍,这条人机分工是真正 OP 的地方。(→ 详解7)
  8. Pi 反 MCP,把 MCP 包成 CLI 命令——任何需要的能力都优先用 Bash 调原生 CLI 工具;实在要用 MCP 时,用 MCP border 或 PI MCP adapter 把它压扁成 CLI 调用,而不是堆一堆 MCP server。(→ 详解8)

知识点详解

1. Pi 是 harness 不是产品 00:07

David 开场就把 Pi 与 Claude Code、Codex 划到两个物种——前者是 harness(可塑底盘),后者是产品(封装好的 IDE)。Pi 的 system prompt 只占大约 1000 token,比同类 agent 少 10–15 倍,这部分 token 每次调用都要付费,所以”短小”也是经济账。

Pi 官网首页那句”You should adapt pi to your workflows, not the other way around”被 David 当作整堂课的主旨反复引用。Claude Code 与 Codex 是万亿估值的 OpenAI 与 Anthropic 为千万大众市场做的”安全产品”,自带一堆 guardrail、每次工具调用都要弹权限确认;Pi 则是为愿意自己造轮子的人留的最小内核。

这套判断延续了 Harness 在已有 vault 笔记里的口径——agent 输出的天花板 90% 由 harness 决定、只有 10% 由模型决定。Pi 走的就是把 harness 做得极薄、把控制权完全交给用户这条路。

2. 安装与多 provider 接入 00:49

安装只有一行 curl 一次性脚本,粘到任何终端、20 秒搞定。Pi 不绑定单一 provider,启动时输入 /login 选择供应商:可以用 Anthropic / OpenAI 的订阅,也可以用 OpenRouter 这类聚合 API 接 15 家以上的模型。David 演示的路径是 OpenRouter——充 5–10 美元、生成 API key、把 limit 设到 30 美元(防爆)、粘回 Pi 即可。

启动后用 /model 切模型、Shift+Tab 在 Off → Minimal → Low → Medium → High → Extra High 之间循环切换思考强度。David 默认 Extra High + Opus 4 fast(Opus 4.8 的 fast 版本),理由后面详解 6 展开。

这段”30 秒装好 + 任意模型”的入场体验,和 self-hosting AI / Ollama 笔记里的”自托管 + 任意模型”思路是同一谱系——把对底层的控制权交还给用户。区别是 Pi 走的是云端 API 聚合(更轻),自托管笔记走的是本地权重(更重)。

3. 上下文三层与 CLAUDE.md 兼容 05:55

Pi 的 context engineering 完全建立在 markdown 文件上,有三层入口:

  • system.md:完全覆盖内置系统提示。David 警告”be careful with this one”,不要碰,因为它会替换掉 Mario 精心调过的默认行为。
  • append system.md:每次会话都追加到系统提示末尾。这是日常改”Pi 应该怎么回答”的入口,David 把”短、直接、英文、无 emoji、英国日期格式”这一类偏好都塞在这里;甚至还塞了”David can’t see tool/bash output. Always relay results in text”以解决 Claude Code 里”只说执行了但不给结果”的痛点。
  • agents.md:可全局放,也可放进任意项目文件夹,Pi 在该目录启动会话时自动加载。这是项目级偏好与上下文的落地点。

最关键的一点是”Pi even reads your existing cloth.m MD files”——如果用户已经有 Claude Code 项目里堆满的 CLAUDE.md,Pi 会原样兼容,无需迁移。这一条对从 Claude Code 切换过来的人几乎零摩擦。

这套”目录即配置、文件即 prompt”的做法,对应 静态上下文与动态上下文 笔记里”恒定加载 vs 按需加载”的权衡——三层文件本质上都是静态上下文(每次会话常驻),Pi 选择把动态上下文交给 skills 与 prompt templates(详解 5)。

4. 四件工具 + Bash 撑起整台电脑 06:38

Pi 出厂只带四件工具:Read / Write / Edit / Bash。Web search、文件搜索、PDF 解析这些都要用户自己装扩展加进来。David 反复强调”you don’t need dozens of MCPs, hundreds of pre-built skills”,四件工具够用。

关键论断是 Bash:“with bash tool, Pi can basically do anything on your computer”。理由是任何专业开发者能在终端里完成的事——装包、起进程、分析网络、改 Wi-Fi、开应用、关应用——Pi 都能做,因为 Bash 工具直接给它 terminal 权限。

这种”四件最小集 + 终端万能”的取舍和 Claude Code Skill 笔记里的范式是平行的:Claude Code 的内置工具集虽然更复杂,但本质上 Bash + 文件操作仍是主力;真正决定行为差异的是用户往上叠加的 skills 与 extensions,而非内置工具数量。

5. 让 agent 自己改造 agent:四种增强方式 10:42

David 把”如何让 Pi 越用越强”分成四种由轻到重的方法,每种都比上一种能力大、改造成本高:

  1. agents.md:永远是”always on context”。把任何想让 Pi 每次都记住的事写进去,30 秒搞定。
  2. Prompt templates:不是简单 prompt,而是 slash 命令。任何重复过一次的提示都该提成模板,用 /xxx 触发。David 的 /short(让回答更短更简单)每天用几十次,演示里从”review 整个 codebase”到”让回答更简洁”都是 prompt template。
  3. Skills:触发式自动加载。Pi 会根据当前对话主题判断该加载哪个 skill,然后把它完整内容读进上下文。David 演示的 research-prompt skill 就是为 ChatGPT 5.5 pro extended、Perplexity Deep Research 这类深度调研工具写”提示词生成器”,避免每次手写调研提示。
  4. Extensions:真正的 TypeScript 代码。可以做 hook、可以补工具,能力最大也最重。pi-web-access 这种”装上才有 web search”的就是 extension。

修改任何配置后必须 /reload 才生效——这是新手最容易踩的坑。

这四层结构与 Claude Code 笔记里的 Skills / Slash Commands / CLAUDE.md / Plugins 几乎是同一张图:Claude Code 的 Skills 对应 Pi 的 Skills,Slash Commands 对应 prompt templates,CLAUDE.md / Memory 对应 agents.md 与 append system.md,Plugins / Hooks 对应 extensions。David 本人在视频里直接承认 Pi 兼容 CLAUDE.md,等于把两个生态的扩展层并轨了。

6. YOLO 模式与必须配最强模型 25:00

“PI agent is always in YOLO mode”——Pi 永远不会问你要权限,这点对新手危险,但 David 把它框成”skill 问题”:会写 agents.md、prompt templates 与 skills 的人几乎不会让 Pi 误删东西;不会的人才真需要安全网。

解决”不会用 + 不安全”矛盾的方法不是给 Pi 加 guardrail,而是给它装最贵最强的模型:“Do not use pi with small models. Please avoid models that are cheap like Haiku Gemini Flash”。小模型在 YOLO 模式下做灾难性错误(误删文件夹、装错包)的概率显著高于 Opus 4 fast / Claude Mythos / GPT 5.6 这类前沿模型;所以 David 用 Pi 就直接把最贵的模型堆上去,把安全感的缺口用模型能力来补,而不是用产品级的权限弹窗来补。

对不想冒这个险的人,pi-permission-system 是官方市场下载量最高的权限扩展(月均 17,000 次下载),装上即可在保留 YOLO 速度的同时接回 Claude Code 那样的逐调用确认。

这与 Harness 笔记里”Harness 优化的 90% 在工程基础而非工具栏”形成印证——David 没把”装权限系统”当成终极解,而是把模型选择当成更高优先级的变量,因为模型不够强的话,任何 guardrail 都只是延迟灾难而不是消除灾难。

7. CMAX:Pi 当指挥、Codex 当执行的多 agent 编排 28:08

David 自己 90% 的 AI 交互跑在 CMAX(为并行跑多个 AI agent 而生的终端多窗格管理器)里。Pi 没有 sub-agent 是 Mario 的设计选择,理由是 sub-agent 在 Claude Code 里”半时你都不知道它在干嘛、为什么这么干”,Pi 走的是更透明的路——直接 spawn 多个 Pi 实例各自跑。

更 OP 的组合是 Pi + Codex CLI:Pi 当 orchestrator(用 sleep N 间隔轮询、读 Codex 输出的少量 token),Codex 当 actor(写代码、调服务、跑测试,主力 token 消耗)。David 让 Pi 同时驱动 4 个 Codex 在 CMAX 的 2×2 grid 里各写一个不同的小应用,Pi 总开销几乎为零,因为它只读 Codex 输出,而 LLM 的读速比人快大约 100 倍。

这条分工也是 Agent Teams / Subagent 笔记里”主 session 兼 team lead”思路的镜像——区别是 Claude Code 的 sub-agent 在主 session 内部 spawn(隐藏上下文),Pi + Codex 是把两个独立进程摆在两个窗格里(可见、可手动介入)。后者对”我必须知道每个 agent 在干嘛”的工程师更友好。

调试 VPS 上的 Hermes Agent / 其他服务时,这套编排尤其好用:Pi 通过 SSH 跳进 VPS、开 Codex CLI 处理现场代码修改、自己盯着输出告诉用户结果——等于把”远程服务器 debug”从单人操作变成”LLM 同事替你盯日志”。

8. 会话是树不是线:39:18

Pi 的 session 不是 Claude Code / ChatGPT 那种线性历史,而是一棵树。任何”在历史某点改了用户输入”的瞬间都会分叉出新的对话分支,而原分支完整保留。David 演示:在原对话某点敲 Escape 两次回滚、修改上一条用户消息、回车后 Pi 从那一节点重答,老对话仍然挂在树上可继续走。

要把一个分支单独拎出来做独立 session,用 /fork;要导出 JSONL 给团队成员或者自己写工具分析,用 /share 生成 gist 或可分享链接;要跨机器跨 CMAX crash 之后找回对话,用 /resume 列出历史 session 列表回车跳入。Session 文件是便携 JSONL,所以可以 rsync / git 同步,可以 cat / grep 当数据源。

这套设计与 Git Worktree 笔记里”每个并行 Claude Code 会话各占一个 worktree、最后合并”是同一思想:不强制线性化、保留所有分支、把”我要回去看一眼老路径”做成第一公民操作。

9. 反 MCP:把 MCP 包成 CLI 命令 45:48

David 把 Pi 的 MCP 立场表述为”anti-MCP”,理由是 MCP 在 Pi 的世界里被当成不必要的中间层。Pi 的哲学是”anything you want to do with PI, it can do it as a CLI command line interface”——能直接 bash 调的命令(curl、git、psql、gh、ffmpeg)就别绕 MCP server。

实在要用 MCP 时有两个瘦身方案:MCP border 把 MCP server 的方法暴露为 CLI 命令,Pi 通过 Bash 调用;PI MCP adapter 是社区扩展,跳过 MCP 胖运行时、把 MCP server 的工具直接挂进 Pi 的工具列表。两者都是”接 MCP 但不让它把上下文与启动时间撑爆”的妥协方案。

这套立场与 MCP 笔记里”跨厂商通用工具协议”的定位并不冲突——MCP 在 Claude Code、Cursor、各类 IDE 上仍然是接入外部服务的事实标准;David 不反协议本身,反的是”用 Pi 就必须走 MCP server”这种默认假设。

可执行步骤

  • 复制 pi.dev 官网的 curl one-liner,粘到终端、20 秒装好 Pi。
  • 启动 Pi → /login → 选 OpenRouter → 充 $5–$10 → 设 $30 单 key 上限 → 粘回 API key。
  • 把”永远在线”的偏好(语言、格式、emoji 规则)写到 append system.md;给当前项目写 agents.md。
  • 装 pi-web-access 扩展,以后任何”搜一下”的活都在 Pi 里完成,不切窗口到 ChatGPT / Perplexity。
  • 每天重复 ≥1 次的 prompt(让回答更短、总结某文件、复盘今天的任务)提成 prompt template,用 /xxx 触发。
  • 写或抄 3–5 个 skills,优先覆盖”写深度调研提示词”、“复盘本仓库改动”、“格式化输出”三类高频场景。
  • 装 CMAX,按 command N / command D / command shift D 起多窗格;在 CMAX 里 spawn 2 个 Codex CLI + 1 个 Pi 当指挥,跑至少一次”Pi 派活给 Codex、Pi 轮询输出、Pi 把结果汇总回用户”的真实任务。
  • 在 Pi 里做一次 /fork,把当前 session 拆成两条平行分支,体验”对话是树不是线”;用 /share 生成 gist 链接发给队友,验证 session 分享确实能用。
  • 任何想用 MCP 的场景先问”我能不能 bash 调原生 CLI”,能就直接调;只有当 CLI 调不通或效率太低时,才装 MCP border / PI MCP adapter 把 MCP 包成 CLI。

关联

  • Harness —— 印证:David 同样把”harness 决定 90% 上限”当作核心立场,只是把 harness 做得更薄(1000 token 系统提示、四件工具)而不是更厚。
  • Claude Code Skill —— 互补:Claude Code 的 Skills / Slash Commands / CLAUDE.md 正好对应 Pi 的 skills / prompt templates / agents.md,两边机制几乎一一映射;本片独有 CMAX 多 agent 编排与反 MCP 立场。
  • MCP —— 互补:本片给出 MCP 的”瘦身接入”路径(MCP border / PI MCP adapter),作为MCP 笔记里”通用协议”之外的另一种现实用法。
  • 同频道互补:Matt Pocock 的 Agentic Engineering 工作流全拆解 同样围绕”把 harness 当主战场”展开,但视角不同——本片是 David 对 Pi 这个具体工具的深度使用,那篇是 Matt Pocock 个人方法论的一小时访谈,两片合看能看到”薄 harness 工具”与”重方法论”两种路线。

一手来源与延伸

术语

  • Pi Agent / pi.dev — Mario 主导开发的极简 AI 编码 harness,系统提示仅 ~1000 token,出厂只带 Read/Write/Edit/Bash 四件工具。
  • Harness — 围绕 AI 编码助手的规则/context/skills/guardrails/workflow/可观测性集合;Pi 走”最薄 harness”路线。
  • Append system.md — Pi 全局配置入口,每次会话追加在系统提示末尾,改 Pi 行为的最安全起点。
  • agents.md — Pi 的项目级 / 全局上下文入口,Claude Code 中对应 CLAUDE.md。
  • Prompt template — Pi 的 slash 命令,把重复提示固化进 ~/.pi/prompts/ 后用 /xxx 触发。
  • Skill — Pi 的按需加载能力单元,触发时整段读进上下文,对应 Claude Code Skills。
  • Extension — Pi 用 TypeScript 写的可执行扩展,能加工具、能做 hook,能力最大也最重。
  • YOLO 模式 — Pi 默认无权限弹窗、agent 直接执行所有动作的运行模式;要求配最强模型 + 谨慎的 agents.md 来弥补安全感。
  • CMAX — 为并行运行多个 AI agent 而设计的终端多窗格管理器,内建浏览器、可一键开新窗格。
  • Steering — Pi 运行中按 Enter 立即改方向、按 Alt+Enter 在 Pi 完成后追发下一条消息的两种 mid-run 控制。
  • Session tree — Pi 的对话不是线性历史而是树:任何在历史某点改输入的瞬间都会分叉出新分支。
  • MCP border / PI MCP adapter — 把 MCP server 调用压扁成 CLI 命令或直接挂工具的两种 Pi 兼容方案。

金句

“PI Agent, also known as PI.dev, is a very simple and customizable AI agent” — 00:07 — 开场定义,直白点题:Pi 不是一个产品,是一个可塑的 agent 内核。

“you should adapt pi to your workflows, not the other way around” — 01:49 — Pi 官网首页那句被 David 当主旨反复引用的口号,是整套”harness not product”哲学的最短版。

“the system prompt is just 1,000 tokens, which is 10 to 15 times less than other agents” — 02:04 — Pi 极简的最具体度量,也是经济账:每次调用都少付 10–15 倍的 system prompt token 成本。

“You, the human, are the limiting block” — 11:13 — David 在强调”让 agent 自己改 agent”时的判断:限制产出的是人写的低水平 prompt,不是模型能力。

“PI agent is always in YOLO mode” — 25:04 — 把”Pi 永远不会弹权限确认”这件事从警告升级为设计哲学:YOLO + 最强模型 = 真正能放权的 agent 用法。

“an LLM can read maybe 100 times faster than humans” — 37:26 — Pi 当 orchestrator 读 Codex 输出的根本依据,也是”LLM 同事替你盯日志”分工的杠杆点。

立场与利益

  • 与利益同向(待印证):“Pi 比 Claude Code/Codex 更适合严肃玩家”、“应该立刻开始用 Pi 否则 2027 年会被甩开”——这两条是 David 卖 Pi Agent 课程与 New Society 社群的核心 hook,采信前应独立验证 Pi 是否真的在自己场景里优于 Claude Code。
  • 利益中性:四件工具、四层扩展、CMAX 多 agent 编排、会话树与 /fork//share//resume、反 MCP 的接入路径——这些是工具能力与设计哲学的事实陈述,与卖课无关,可独立验证。
  • 与利益反向(可信度最高):“Do not use pi with small models”与”YOLO 模式 + 必须配最强模型”——这两条客观上把 Pi 的使用门槛抬高(更贵的 API 费用、不能贪便宜用 Haiku / Gemini Flash),与”快速拉用户入门”的商业动机相反;David 愿意在卖课视频里同时强调”用 Pi 必须用最贵模型”,说明他对 Pi 的定位是给真懂的玩家而不是给凑热闹的小白。

利益证据(摘 description):David 的视频链接同时挂了 Supabase(赞助商,有专属 referral 域名 supabase.plug.dev/F2BkjFC)、他自己的 Pi Agent 课程、新社群 Skool 链接、招聘页 Scale Software、以及他的声纹工具 Glaido affiliate 链接。这些推广链接不影响他关于 Pi 工具能力的事实陈述,但解释了为何”立刻用 Pi”的紧迫感叙事在视频里反复出现。

价值定位

  • 适合谁:已经在用 Claude Code 或 Codex CLI、觉得 IDE 级封装限制了自己、想自己掌控上下文与扩展的工程师与高级用户;以及正在搭建多 agent 编排(CMAX、Codex CLI)并需要”指挥者 agent”角色的实践者。
  • 解决什么:把 AI agent 从”产品级 IDE”里解放出来——用户可以自己写 agents.md 注入偏好、自己写 prompt templates 把重复提示固化、自己写 skills 让 agent 触发式获取上下文、自己写 extensions 加工具;同时给出 Pi + Codex 的多 agent 编排实操范式。
  • 认知 vs 实操:以实操为主——视频给出从安装、/login、装 web-access、写 agents.md、装 CMAX 到 spawn 多 Codex 的完整链路;认知层面的贡献是把”harness not product”与”反 MCP”这两个判断点说清楚。
  • 与已有笔记重叠时:与 Harness / Claude Code Skill 的判断同源,但本片独有 (1) Pi 作为最薄 harness 的具体配置路径(append system.md / agents.md / prompt templates 三件套)、(2) CMAX 多 agent 编排(指挥者 Pi + 执行者 Codex 的分工)、(3) 会话树与 /fork 的非线性历史设计、(4) 反 MCP 用 CLI 替代 server 的明确立场。

自检问题

  1. Pi 与 Claude Code、Codex 在设计哲学上的最核心分野是什么?为什么 David 把 Pi 称作 harness 而不是产品? 答案:详解 1。核心分野是”是否把控制权交给用户”。Claude Code/Codex 是面向千万大众的产品,自带 safeguard 与权限弹窗;Pi 是最薄 harness,只带四件工具、1000 token 系统提示,把适配权完全交给用户。印证句:01:49 “you should adapt pi to your workflows, not the other way around”。

  2. Pi 的四层扩展方式(agents.md / prompt templates / skills / extensions)由轻到重的能力与改造成本如何对应?日常该优先用哪一层? 答案:详解 5。agents.md(永远在线、改造成本 30 秒)→ prompt templates(slash 触发、30 秒)→ skills(触发式自动加载、1–2 分钟)→ extensions(真 TypeScript、最重);日常应先用 agents.md 与 prompt templates 覆盖重复提示,skills 覆盖主题性场景,extensions 只在 markdown 不够时再写。印证句:14:02 “any prompt that you find yourself repeating often, turn it into a prom template”。

  3. 为什么 David 强调 Pi 必须配最强模型,不能贪便宜用 Haiku / Gemini Flash?YOLO 模式下安全感的缺口靠什么补? 答案:详解 6。Pi 默认 YOLO 模式、永不弹权限确认,小模型在这种模式下更容易做出灾难性错误(误删文件夹、装错包);David 的解法是把模型选择当成第一变量,而不是装一堆 guardrail,安全感靠模型能力补。新手可装 pi-permission-system 兜底。印证句:25:23 “Do not use pi with small models. Please avoid models that are cheap like Haiku Gemini Flash”。

  4. Pi + Codex 在 CMAX 里”Pi 当指挥、Codex 当执行”的分工为什么 OP?LLM 在哪个环节比人快得多? 答案:详解 7。LLM 读输出的速度比人快约 100 倍,所以 Pi 做 orchestrator 的成本极低——它只需要 sleep + 读 Codex 的输出、给用户汇总;真正耗 token 的写代码、调服务交给 Codex CLI,主力消耗走用户的 Codex / ChatGPT 订阅,不烧 OpenRouter 的额度。印证句:37:26 “an LLM can read maybe 100 times faster than humans”。

  5. Pi 为什么”反 MCP”?David 给出哪两种”实在要用 MCP 时的瘦身接入方案”? 答案:详解 9。Pi 主张”能直接 bash 调的命令就别绕 MCP server”,MCP 在 Pi 视角里是多余的中间层;实在要用 MCP 时,有 MCP border(把 MCP server 暴露成 CLI 命令,Pi 通过 Bash 调)与 PI MCP adapter(跳过 MCP 胖运行时,直接把 MCP server 的工具挂进 Pi 工具列表)两种方案。印证句:46:01 “Instead of connecting MCBs directly, it serves them as CLI tools”。

关系图谱

反向链接