#教程介绍

pi 是 Mario Zechner(badlogicgames,libGDX 作者)开源的一个极简终端 coding agent harness。它的自我描述是:

Pi is a minimal terminal coding harness. Adapt pi to your workflows, not the other way around.

在 Claude Code、Codex、opencode 等工具不断叠加功能的时代,pi 反其道而行:核心只给模型 4 个工具(read/write/edit/bash)、一段不到 1000 token 的系统提示词,没有 MCP、没有 sub-agent、没有 plan mode、没有内置 todo、没有后台 bash——但却在 Terminal-Bench 2.0 上打出了与主流 harness 相当的成绩。

这种"少即是多"的设计不是偷懒,而是一套完整的、可以被论证和复现的工程哲学。而理解这套哲学最好的方式,就是自己动手把它的核心造一遍。这正是本教程要做的事。

#pi 由什么组成

pi 是一个 monorepo,拆成四个职责清晰的包:

本教程的主角是最顶层的 pi-coding-agent,但要理解它,必须沿着它的依赖一路向下拆。

#为什么值得拆解 pi

• 代码可读性极高。没有历史包袱,没有为了兼容性堆出来的抽象,每个设计决策作者都在长文里写明了理由。
• 每个决策都有证据。极简提示词、四个工具够用、不做 sub-agent——这些"暴论"都有 benchmark 数据和日常使用的验证,而不是拍脑袋。
• 学完能直接用。pi 的三个底层包都是独立的 npm 库,理解它们之后,你可以用同样的积木拼出自己的 agent——实战篇最后正是这么做的。

#教程地图

• 导读(你在这里):pi 是什么、整体架构。
• 设计思想篇:逐条拆解 pi 的设计决策——极简核心、LLM 抽象层、agent loop、harness 层,以及那份著名的"不做"清单。
• 实战教程:十章递进式实战。先用纯 TypeScript + fetch 裸写一个 agent loop(约 100 行),逐章加入四大工具、流式输出、会话树、上下文压缩;最后用 pi 官方的 pi-ai + pi-agent-core 重构,得到一个架构上与 pi 同构的 mini-pi。
• 源码导读:给你一张 packages/coding-agent 的源码地图,以及工具实现、会话运行时的精读笔记。

建议的阅读顺序:

• 时间紧、只想快点做出自己的 agent:直接进实战教程,卡壳时回查对应的思想篇/源码导读章节。
• 想真正理解"为什么":按顺序读完设计思想篇,再进实战——你会发现每一行代码都对应一个论证过的决策。

#前置要求

• Node.js ≥ 20.19(或 22.12+),会基本的 TypeScript。
• 一个 OpenAI 兼容 API 的 key(OpenAI、DeepSeek、Kimi、OpenRouter 等任一均可,实战篇通过环境变量配置)。
• 可选:npm i -g @earendil-works/pi-coding-agent 安装 pi 本体,边用边对照,体验会好很多。

#版本与版权说明

本教程基于 pi 仓库 main 分支、commit 3da591ab 的源码写成。pi 迭代很快,细节请以最新源码为准;文中引用 pi 源码处均标注了文件路径,代码遵循其 MIT 许可。