https://t.co/qn75Cm1VFX

meng shao on X: "https://t.co/qn75Cm1VFX" / X

meng shao

@shao__meng

$

深读 Pi School 15 节课：一门用 Pi 本身教你 Pi Agent 的免费课程，让 Pi 一边教你一边被你使用

6

18

80

122

Pi School 课程

Pi School 是一门免费、自定进度的开源课程（Apache 2.0，社区项目，非官方产品），教授的是 Pi（ https://pi.dev/ ）， 由 Earendil Works 运营的极简终端编程智能体。课程对其的定位很清楚：Pi 是"model-agnostic"（模型无关）的本地智能体，本体只做最小核心，读写文件、跑命令、连接模型，其余能力全部靠技能（Skills）、扩展（Extensions）、提示模板和 MCP 服务器自行拼装。

课程明确说了目标人群：不只是开发者，是“任何想用 AI 在电脑上做创造性东西的人”，只要求对命令行有基本适应，不要求会编程。但它的后半段（Code mode、Extensions）实际上也为资深开发者保留了深度。

教学设计：形式本身就在示范产品理念

这门课最值得注意的一点是它的 授课方式与产品哲学完全同构 ：

•第一课在浏览器完成，其余 14 课全部在 Pi 终端内交互进行。每课只提供一个可复制的提示词（prompt），你把它粘给 Pi， Pi 自己读取课程内容、教你这一课、并标记完成 ，进度实时同步回网页。

•也就是说，课程没有“教材→工具”的分离， 工具就是教材的讲解者 。你在学会 Pi 的过程中，每一步都在真实使用 Pi。

•注册无需账号，不收集个人数据，本地生成随机学生 ID，进度存在 Cloudflare KV。这种轻量、隐私优先的姿态与 Pi 本身“极简核心”的定位一脉相承。

这种“用 X 学 X”的设计还有一层隐性教学价值：它迫使学习者从一开始就把 AI Agent 当作 对话式的协作者 ，而不是一套需要背命令的软件。

十五课的内在脉络

课程表面是 15 个主题，实际可以清晰地分为四个递进阶段。

阶段 1：建立环境与“契约”（第 1–5 课）

Installation → Interview → Configuration → Trust → Instructions

这一阶段解决三件事：装好工具、连上模型、立好规矩。

• Installation 的态度非常务实。Pi 不内置免费模型，课程给出清晰的决策树：有 ChatGPT Plus/Pro 就用官方的 "Sign in with ChatGPT"（OpenAI 认可的第三方接入方式）；没有就注册免费的 OpenRouter 账号选 :free 模型，零成本。特别值得注意的是它的 诚实 ：明确警告 Claude Pro/Max 和 GitHub Copilot 虽然出现在 /login 选项里，但经第三方工具路由其凭据违反 Anthropic 和 GitHub 的服务条款，且有真实的封号执法史，不建议使用。这种“把条款风险讲透”的做法在同类教程中很少见。

• Interview 是个性化机制：Pi 先问你想要 fast track（快速通道、无测验）还是 thorough（完整讲解），所有问题皆可选。一个细节是"fast track 是默认值”，课程默认尊重你的时间。

• Configuration 引入两层配置体系：全局 ~/.pi/agent/settings.json 与项目级 .pi/settings.json（嵌套合并、项目优先），并教学设置默认模型。

• Trust 是整个阶段最重要的一课，后面单独展开。

• Instructions 教 AGENTS.md，这个文件已成为事实上的行业标准（Pi、Claude Code 等多工具通用），分全局（个人偏好，不进 Git）、父目录链、项目级（进 Git、团队共享）三层加载。课程给的示例非常接地气：不只是编码规范，还包括“永远不用 em dash”“PR 描述以 This PR 开头”这类沟通偏好。它还点出 Pi 的一个核心理念： Pi 没有 /init 这类专用命令，你直接用自然语言让 Pi 扫描项目生成 AGENTS.md ，"描述你想要什么，Pi 用已有工具想出怎么做"。

阶段 2：理解模型的边界（第 6–9 课）

Models → Context → Sessions → Branching

这一阶段从“装好了”转向“用得懂”，是课程中认知密度最高的部分。

• Models 的核心论断： 模型选择是决定 Pi 使用体验的第一因素 。旗舰模型（Claude、GPT、Gemini）写码更好、推理更强、犯错更少，但按请求计费；免费模型零成本但难任务明显更弱。用好 Pi 就是找到成本与能力的平衡点。这一课还覆盖了 Cloudflare AI Gateway / Workers AI 作为 provider，以及通过 llama.cpp 路由跑本地模型（免费、私密，但小模型在 agentic 任务上明显偏弱）。

• Context 讲上下文窗口与压缩（compaction）。这是理解所有 AI 工具的通用知识：上下文以 token 计（约 ¾ 个词），包含你的消息、文件内容、工具输出和模型回复。窗口快满时 Pi 自动触发压缩，把旧的对话摘要化以腾出空间，也可手动 /compact。课程的实践建议很成熟：大模型日常不用操心；小模型要“一任务一会话”、注意漂移信号；主动 /compact 的最佳时机是任务边界处（摘要会损失信息，少压优于多压，且可以带指示词引导摘要重点，如 /compact focus on the API changes）。它还仔细解释了底部上下文计量器变红只是颜色阈值（约 98% 才真正触发），不是出错。

• Sessions 讲会话管理：自动保存为 JSONL 文件、/new、/name、/resume、pi -c 直续最近会话、/export（本地 HTML/JSONL）与 /share（上传生成查看链接）的区别，以及 /bug 生成私密错误报告。

• Branching 是 Pi 最有特色的功能之一： 会话不是线性的消息流，是一棵树 。每条记录有 id 和 parentId，你随时可以用 /tree 跳回任意历史节点，选中用户消息会把它放回编辑器供你修改重发（产生新分支），选中助手消息则直接从该点继续。这解决了两个高频痛点： 不丢掉第一次尝试就能对比另一种方案 、 搞砸了可以原地回退 而不必重开会话。课程还辨析了 /tree（同文件内探索）、/fork（从早期提示词开新会话）、/clone（复制当前分支）三者的分工。

阶段 3：扩展能力体系（第 10–15 课）

Skills → Tools → MCP → Code mode → Extensions → Images

这一阶段是课程的后半程，讲 Pi 如何从“极简核心”长成你需要的任何东西。它实际上是一套 四层的扩展模型 ，从浅到深：

1. Skills（知识包） ，遵循 Anthropic 发起、现由 agentskills.io 维护的开放标准，本质是一个带 SKILL.md 的文件夹。按“渐进披露”原则工作：启动时只加载名称和描述，用到时才载入全文。安装推荐用 npx skills CLI（一次装到所有 AI 工具）。课程让学员装四个：Cloudflare、Replicate、frontend-design、skill-creator，最后一个用来“把任何做成的流程固化为可复用技能”。

1. MCP（外部工具接入）， Model Context Protocol 开放标准。默认 4 个内置工具（read/bash/edit/write）覆盖文件与命令，其余一切（实时数据、内部文档、第三方服务）通过 MCP 服务器获得。配置格式与 Claude Code/Cursor 相同，可直接复制。

1. Code mode（批量执行）， 一个聪明的设计：模型不逐个调用工具，是写一段短 JavaScript 脚本去并行调用它们（如 Promise.all 同时读十个文件），只把脚本结果返回给模型。收益是三重的：往返更少、可并行、可在返回前过滤结果省上下文。脚本运行在无文件系统、无网络的沙箱中，只能做 Pi 工具能做的事。

1. Extensions（行为改造）， 最深的一层：TypeScript 模块，可以订阅 Pi 的生命周期事件、注册自定义工具与命令、甚至构建自己的终端 UI。课程在这里点名了 Pi 的哲学： Pi 没有 Plan mode、没有内置逐动作权限确认、没有内置网页搜索， 这些“别的工具有的功能”在 Pi 中都是“自己用扩展写”，官方甚至附带了 plan-mode.ts 和 permission-gate.ts 示例。这就是"minimal harness"的含义：核心只保证可扩展性，不预设行为。

其中 MCP 与 Code mode 的联动是点睛之笔：MCP 工具 默认不直接展示给模型 （避免几十个工具定义吃掉上下文），是通过 codemode 脚本按需搜索调用。每个服务器可配置 codemode / deferred / direct / hidden 四档曝光度。

最后一课 Images 收尾：粘贴、拖拽、@ 引用、CLI 参数四种方式给模型喂图，适用于复刻 UI 设计、调试视觉 bug、从截图提取文字。前提是模型本身支持视觉。

贯穿始终的 Trust 模型

Trust 值得单独说明，因为它是 Pi 与其他 agent 工具 最鲜明的理念分歧 ：

•Pi 以你的权限本地运行，直接读写文件。它唯一的安全门是： 加载任何项目级配置（.pi/settings.json、项目 MCP、扩展、技能等）之前，先要你的一次性明确许可 。

•它 不是 逐动作的权限系统。一旦信任了项目，Pi 不会像某些工具那样在每条 bash 命令、每次文件编辑前暂停确认。课程对此毫无含糊：如果你想要那种逐条确认，"it's not a built-in setting — it's an extension"。

•信任决策可用 /trust 持久化到 ~/.pi/agent/trust.json，可用 defaultProjectTrust: ask/always/never 设全局默认，非交互模式（-p、--mode json/rpc）永不弹窗，单次运行可用 --approve/-a 覆盖。

•判断标准也很朴素：自己的项目说 yes，刚 clone 下来没审查过的说 no。

这本质上是把安全责任交还给用户的设计取向：用一个高杠杆的闸门（配置加载）防住“克隆恶意仓库即执行恶意配置”这类真正危险的攻击面，而把日常操作摩擦降到最低。

练习项目：从课程到真实产出

11 个练习不是课后习题，是 用 Pi 完成真实任务 的引导项目，覆盖面刻意地超越了“写代码”：

•开发向：Hono + Cloudflare Workers 建个人主页；Cloudflare AI Gateway 统一计费路由；macos-app-skills 做读取自己 Pi 使用统计的原生菜单栏应用。

•媒体向：Replicate 生成图像视频、FFMPEG + yt-dlp 剪视频、Whisper 本地转录。

•自动化向：Chrome DevTools 技能驱动真实浏览器、Gmail 分拣收件箱、Typefully 起草社媒帖文。

•元学习向：Matt Pocock 的 teach 技能给自己定制任意领域的课程。

•工程基础向：Git/GitHub 入门并完成第一次开源贡献。

这个选题组合印证了课程的野心：Pi 不是“编程工具”，是 通用计算机智能体 。

Tips 页面里的方法论

几条朴素但真正有用的建议，反映了作者对“人机协作”的理解：

• 描述目标而非手段 （talk about the what, not the how），给 agent 留出想出更优方案的空间。

• 知道何时放弃重来， 掉进兔子洞时（agent 犯错→你纠正→更糟），果断 /new 或用 /tree 回到出事之前，而不是继续纠缠。这可能是新手最缺的技能。

• 目录即权限边界， Pi 从哪级目录启动就只能看哪级以内；想跨项目操作就从更上层启动，但因为没有沙箱，只应在信任的目录这么做。

• 课程本身是弹性的， 可以要求跳过冗长解释、用西班牙语上课、随时回顾进度。"Be silly. Be bossy."

总体感受

优点是实打实的：

1. 课程结构有清晰的认知阶梯 ：环境 → 模型边界 → 扩展体系，每一课都建立在前一课的概念上（如 Code mode 课回扣 MCP 课的天气查询，说明你早已用过 codemode）。

1. 诚实度高 ：明说免费模型更弱、明说哪些订阅路径违反条款有封号风险、明说“自动压缩不会提示你，判断权在你”，不回避工具的局限和取舍。

1. 押注开放标准而非私有生态 ：AGENTS.md、agentskills.io、MCP、兼容 Claude/Cursor 的 mcpServers 格式，学到的概念大多可迁移到其他工具。

1. 教的是心智模型而非命令清单 ：比如压缩的“少压优于多压”、分支树的“选用户消息是改提问，选助手消息是续写”、信任模型的“一个闸门而非一网格规则”，这些都是可迁移的判断力。Cheatsheet 和 Glossary 则把速查需求单独抽出来，各司其职。

局限也应当指出：

1.深度上，它是 优秀的入门课而非进阶课， Extensions 一课只给出 API 形状和 60+ 示例的指引，真正的扩展开发要靠官方文档；对资深工程师，最有营养的可能只是 Trust/Branching/codemode 这几个 Pi 特有机制。

2.生态绑定不轻：11 个练习中 4 个直接用 Cloudflare 产品（课程自身也跑在 Cloudflare 上），Replicate、Typefully 等也都是特定商业服务，学到的流程可迁移，具体工具未必。

3.课程高度依赖“把提示词粘给 Pi 让它教自己”的模式，对不适应纯终端交互的人仍有门槛；且课程内容随 Pi 版本演进（文中已见“旧版课程曾装 pi-mcp-adapter”的痕迹），时效性维护是持续挑战。

/$

2:32 AM · Oct 8, 2026

·

7,055

Views