Pi：小到你能读完源码的编码 Agent

01

它是什么：一个「你能自己养」的编码 Agent

Pi 是 Mario Zechner（网名 badlogic，libGDX 框架作者）维护的开源编码 Agent，住在 pi-mono 这个 TypeScript 单仓库里。官网 pi.dev 的定位一句话：a minimal, extensible agent harness you can make your own——一个极简、可扩展、能改造成「你自己的」agent harness。它不在功能上堆料，而是把「能跑起来」的最小核心做扎实，其余一切交给扩展机制。

核心哲学浓缩成一句：默认只给模型四个工具——read、write、edit、bash。作者认为一个编码 agent 有这四样就够了，剩下的能力靠 skills、extensions 长出来。所以你在官方 README 里看不到 plan mode、看不到子智能体、看不到权限弹窗——不是做不了，是不替你做决定（这个取舍值多少分，第 07 节专门讨论）。

它适合三类人：想理解 agent 内部机理的人（源码小到能读完，扩展示例里甚至有「等待时玩 Doom」这种）；要把 agent 嵌进自己产品或脚本的人（SDK 与 RPC 模式是一等公民）；被全家桶工具「管太多」的人——想要自己的工作流，而不是工具替你规定的工作流。

「小」不是偷工减料，是有意的架构选择：核心小，系统提示词就短，模型行为就可预期；核心小，每个能力都能讲清楚来龙去脉，出问题就知道去哪查；核心小，改造点就清晰——你在自己的扩展里重写一个「子智能体」，成本是百来行 TypeScript，而不是去给一个大项目提 PR 等半年。仓库的 README 本身就是主文档，写得直白，读完它你就读完了产品。

作者

Mario Zechner（badlogic · libGDX 作者）

仓库

github.com/badlogic/pi-mono（TypeScript monorepo）

协议

MIT

安装包

@mariozechner/pi-coding-agent（命令名 pi）

内置工具

read · write · edit · bash（+ grep · find · ls）

运行模式

交互 TUI · print/JSON · RPC · SDK

平台

macOS · Linux · Windows · Android（Termux）

官网

pi.dev（域名由 exe.dev 捐赠）

02

安装与认证：npm 一条命令，认证两条路

Pi 是模型无关的——它自己不带模型，接哪家就用哪家。所以安装之后还差一步「认证」：给 API key，或者用你已有的订阅登录。

# 安装（需要 Node.js 环境）
npm install -g @mariozechner/pi-coding-agent

# 认证方式一：API key 环境变量
export ANTHROPIC_API_KEY=sk-ant-…

pi --version

pi

> /login      # 选择 provider，走 OAuth 授权
> /model      # 选具体模型（快捷键 Ctrl+L）

git clone https://github.com/badlogic/pi-mono.git
cd pi-mono
npm install
npm run build
./pi-test.sh      # 直接从源码跑 pi，任意目录可用

两条安装路径的取舍：npm 全局装最省心，跟着 npm 升级走；源码路径适合想读代码、改代码、贡献 PR 的人——整个仓库 npm install && npm run build 就绪，没有私有构建工具链，这也是「读完源码」承诺的一部分。另外记两个常规维护命令：

# 升级到最新版（pi 自己也有更新命令，见第 05 节）
npm install -g @mariozechner/pi-coding-agent

# 卸载
npm uninstall -g @mariozechner/pi-coding-agent

# 看当前版本与完整帮助
pi --version
pi --help

03

第一次对话：进仓库，开口就行

cd ~/your-project
pi

# 带初始消息启动，省一次输入
pi "List all .ts files in src/"

# 单次执行，不进交互界面
pi -p "Summarize this codebase"

# 管道输入也能接
cat README.md | pi -p "Summarize this text"

• 01

  选好模型

  Ctrl+L（或 /model）打开模型选择器；--models "claude-*,gpt-4o" 可以预设一组，之后 Ctrl+P / Shift+Ctrl+P 在组里前后轮换。

• 02

  把项目规矩写进 AGENTS.md

  启动时它会从 ~/.pi/agent/AGENTS.md（全局）、父目录、当前目录逐级加载 AGENTS.md（或 CLAUDE.md），全部拼接生效。项目约定、常用命令写在这里，等于每次开工前自动交底。

• 03

  让它干活

  读文件、改文件、跑命令，每一步都显示在界面上；Ctrl+O 折叠/展开工具输出，Escape 随时打断。任务要具体：「给 src/utils 加一个 toKebabCase 并补单测」远好过「优化一下代码」。

• 04

  学会排队说话

  它在干活时你也可以继续输入：Enter 是「指挥」——这轮工具跑完就插话；Alt+Enter 是「补充」——等它全部干完再送达。误发了按 Escape 收回编辑器。

输入框里能做的事

pi 的编辑器看似朴素，官方面板里实际支持这些操作（全列在 /hotkeys）：

@ 引用文件

输入 @ 模糊搜索项目文件，选中即作为附件进入上下文。

Tab 补全路径

输入路径时按 Tab 补全。

Shift+Enter 换行

多行输入（Windows Terminal 用 Ctrl+Enter）。

Ctrl+V 粘图片

粘贴截图到上下文（Windows 用 Alt+V），也可以直接拖进终端。

!command

自己跑一条 shell 命令，输出送给模型看。

!!command

只跑不喂——输出不进上下文，适合噪音大的命令。

# @ 前缀把文件带进消息
pi @prompt.md "Answer this"
pi @code.ts @test.ts "Review these files"

# 图片直接当参数
pi -p @screenshot.png "What's in this image?"

04

核心概念：四个工具、四种模式、四件套

4.1 极简核心：默认只给四个工具

read、write、edit、bash 是默认四件套；内置工具全集还有 grep、find、ls。为什么少即是多：工具越少，系统提示词越短，模型行为越可预期，你越容易判断「它为什么这么做」。工具集还是可调的——一条命令就能进入只读模式：

# 只放行 read/grep/find/ls —— 审阅别人的代码时用
pi --tools read,grep,find,ls -p "Review the code"

# 其他控制粒度
--no-builtin-tools   # 关内置工具，保留扩展工具
--no-tools           # 全关（纯对话）

4.2 四种运行模式：它是个「组件」，不只是个「程序」

默认是交互 TUI；-p 是 print 模式（出答案就退出）；--mode json 把全部事件以 JSON lines 输出，适合脚本消费；--mode rpc 在 stdin/stdout 上跑 LF 分隔的 JSONL 协议，给非 Node.js 的进程集成用；最彻底的是 SDK——直接 import 进你的应用。官方 README 里给的 SDK 起步代码：

import { AuthStorage, createAgentSession, ModelRegistry, SessionManager } from "@mariozechner/pi-coding-agent";

const authStorage = AuthStorage.create();
const modelRegistry = ModelRegistry.create(authStorage);
const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  authStorage,
  modelRegistry,
});

await session.prompt("What files are in the current directory?");

真实世界的 SDK 集成案例，README 指了 openclaw/openclaw 这个项目；RPC 协议细节在 docs/rpc.md——注意它严格要求按 \n 分帧，别用会拆 Unicode 分隔符的通用行读取器。

README 的 Examples 一节给了一组可直接抄的启动姿势，覆盖日常九成场景：

# 交互 + 初始消息
pi "List all .ts files in src/"

# 非交互；管道输入会并进首条提示
pi -p "Summarize this codebase"
cat README.md | pi -p "Summarize this text"

# 指定模型：provider 前缀、思考档位、模型组
pi --provider openai --model gpt-4o "Help me refactor"
pi --model openai/gpt-4o "Help me refactor"
pi --model sonnet:high "Solve this complex problem"
pi --models "claude-*,gpt-4o"

# 只读审阅 / 高强度思考
pi --tools read,grep,find,ls -p "Review the code"
pi --thinking high "Solve this complex problem"

4.3 定制四件套与 pi packages

Extensions（TypeScript 模块：注册工具、命令、快捷键、事件处理器甚至 UI）、Skills（Agent Skills 标准的能力包，SKILL.md 文件，/skill:name 调用或让模型自动加载）、Prompt templates（Markdown 模板，输入 /名字 展开，支持 {{变量}} 占位）、Themes（dark/light 内置，主题文件支持热重载）。这四样都可以打进 pi packages，用 npm 或 git 分享给别人：

pi install npm:@foo/pi-tools              # 装 npm 包
pi install git:github.com/user/repo@v1    # 装 git 包，钉在 tag 上
pi install npm:@foo/pi-tools -l           # 项目本地安装（.pi/ 下）
pi list                                   # 看装了什么
pi config                                 # 启用/停用包里的扩展、技能、模板、主题

四件套加包，落盘后长这样——记住这张目录地图，后面排障全靠它：

~/.pi/agent/                  # 全局配置根（可用 PI_CODING_AGENT_DIR 改址）
├── settings.json             # 全局设置；项目级放 .pi/settings.json
├── keybindings.json          # 自定义快捷键
├── models.json               # 自定义 provider / 模型
├── AGENTS.md                 # 全局上下文文件
├── SYSTEM.md                 # 全局系统提示词替换；APPEND_SYSTEM.md 追加
├── sessions/                 # 会话 JSONL（按工作目录归档）
├── prompts/ · skills/        # 全局模板与技能
├── extensions/ · themes/     # 全局扩展与主题
└── git/                      # git 来源的 pi 包安装位置

4.4 模型无关：统一 LLM API

各家 provider 的差异被 @mariozechner/pi-ai 这一层统一 API 抹平——上面速查表里那串 provider 名单（从 Anthropic 到 DeepSeek、ZAI 到 Xiaomi MiMo）都走同一套接口。订阅类 provider 走 /login OAuth；API key 类用环境变量；公司网关或 OpenAI 兼容端点，在 ~/.pi/agent/models.json 里加自定义 provider；更怪的需求（自定义 OAuth 流程等）用扩展的 registerProvider() 解决。会话里 Shift+Tab 循环思考档位（off → minimal → low → medium → high → xhigh），也可以 --model sonnet:high 这样直接带档位启动。

最后记一组环境变量——迁移机器、写 CI、关遥测都用得上（完整列表见 README）：

PI_CODING_AGENT_DIR

改全局配置目录（默认 ~/.pi/agent）。

PI_CODING_AGENT_SESSION_DIR

改会话存储目录（--session-dir 可覆盖）。

PI_PACKAGE_DIR

改包目录（Nix/Guix 等场景用）。

PI_OFFLINE=1

关闭全部启动联网：版本检查、包更新检查、遥测。

PI_SKIP_VERSION_CHECK=1

只关版本检查，不动遥测开关。

PI_TELEMETRY=0

只关安装/更新遥测，不动版本检查。

PI_CACHE_RETENTION=long

延长 prompt 缓存（Anthropic 1h / OpenAI 24h）。

VISUAL / EDITOR

Ctrl+G 调外部编辑器写长输入时使用。

05

速查表：包、模式、扩展机制与命令

下面这块表格能搜，内容整理自 coding-agent 包的 README 与 CLI Reference。记不住命令名就搜 会话、压缩、模型 之类的词。

06

实战：四步把 pi 改造成你的专属工具

pi 的正确打开方式不是「用它的功能」，而是「给它长功能」。下面四步全部来自官方 README 的机制说明，做完你就有了三件自己的定制件。

步骤一：写一个提示词模板

Review this code for bugs, security issues, and performance problems.
Focus on: {{focus}}

保存后回到会话敲 /reload（或直接重开 pi），之后在输入框里输入 /review 即展开。模板支持 {{focus}} 这样的占位变量；放在 .pi/prompts/ 里就是项目级，放进 pi package 就能分享给同事。

步骤二：写一个技能

# Commit Skill
当用户请你提交代码时使用这个技能。

## 步骤
1. 先跑 git status 与 git diff 审查全部改动
2. 按约定式提交（Conventional Commits）格式写提交信息
3. 提交前把测试跑一遍，失败则先修复

会话里 /skill:commit 手动调用，或让模型判断场景自动加载。技能的威力在「把团队的隐性流程写成显性指令」——新人 clone 仓库就能继承老手的工作方式。

步骤三：写一个 TypeScript 扩展

扩展是 pi 定制能力的上限：注册工具、命令、事件处理器、UI 组件，官方示例里从 git 自动提交到「等待时玩 Doom」都有。README 给的骨架长这样：

export default function (pi) {
  pi.registerTool({ name: "deploy", /* 参数与执行逻辑，见 docs/extensions.md */ });

  pi.registerCommand("stats", { /* … */ });

  pi.on("tool_call", async (event, ctx) => { /* 审计日志 / 权限门 */ });
}

默认导出也可以是 async——工厂函数完成前 pi 会等它，适合启动前先拉一次远端模型列表之类的初始化。存好文件，/reload 生效。

步骤四：装别人的包，或把四件套打包

pi install npm:@foo/pi-tools        # 装第三方的
pi list                             # 看装了什么

# 把自己的扩展+技能+模板+主题打成一个包
# package.json 里加：
{
  "name": "my-pi-package",
  "keywords": ["pi-package"],
  "pi": { "extensions": ["./extensions"], "skills": ["./skills"] }
}

没有 pi 清单的包，pi 会按约定目录（extensions/、skills/、prompts/、themes/）自动发现。发布到 npm 或 git 仓库，团队里 pi install 一条命令共享。

验证：确认改造都生效了

pi
> /reload        # 重载模板、技能、扩展与上下文文件
> /review        # 模板应立即展开
> /skill:commit  # 技能应可调用（启动头也会列出已加载项）

# 退出后在终端确认包就位
pi list

启动时的 startup header 会列出已加载的 AGENTS.md、模板、技能与扩展——改造有没有生效，看头几行就知道。

07

避坑：极简派的四个取舍

坑一：别拿极简 Agent 当全家桶用

pi 的官方哲学清单值得背下来——每一项「没有」，官方都给了替代路径：

没有 MCP

作者的答案是「写带 README 的 CLI 工具」（即 Skills），或用扩展接 MCP。理由见 README 的 Philosophy 一节。

没有子智能体

做法不止一种：tmux 里开多个 pi 实例、扩展自己写、装现成的包。

没有权限弹窗

跑在容器里，或用扩展做贴合你安全要求的确认流。

没有 plan mode

把计划写进文件（模型读文件本身就是执行的一部分）。

没有内置 TODO

用 TODO.md 文件——作者认为内置待办列表会干扰模型。

没有后台 bash

用 tmux：完全可观测、可直接交互。

这些不是缺陷清单，是设计立场——但如果你现在就需要这些功能且不想自己动手，pi 会让你觉得「缺胳膊少腿」。装包前记得先看它用哪些机制补的，质量参差。

坑二：扩展 API 与文档在动

pi 迭代很快，扩展 API、会话格式、settings 字段都可能调整。三个「文档可能过时了」的信号：命令报未知参数、启动头不再列出你装的扩展、行为和 docs 描述对不上——出现任何一个，回仓库看当前 README。对策：升级 pi 后先 /reload 或重启验证扩展；写扩展时对照仓库 docs/extensions.md 与 examples/extensions/ 的当前版本——这两个目录就是官方文档，别抄半年前的博客代码。另注意这个仓库对社区贡献的规则（新贡献者的 issue/PR 默认自动关闭，维护者每日复核），提 PR 前先读 CONTRIBUTING.md。

坑三：provider 配置踩空

三类坑各有对策：环境变量名各家不同（ANTHROPIC_API_KEY 只是其中之一，别拿 OpenAI 的 key 配给 Anthropic 的变量名）；订阅走 /login OAuth 而不是环境变量；公司自建网关用 ~/.pi/agent/models.json 注册自定义 provider（要求对方说 OpenAI/Anthropic/Google 三种 API 之一）。全列出可用模型用 --list-models，能省很多猜。内网环境记得 PI_OFFLINE=1——pi 启动会联网做版本检查与遥测。

pi --list-models            # 当前能用的模型都有哪些
pi --model openai/gpt-4o "Help me refactor"   # provider 前缀直接选
pi --model sonnet:high "Solve this"           # 模型+思考档位连写

坑四：和 Claude Code / OpenCode 怎么选

三问定取舍。一问工作流：团队已经用惯 Claude Code / OpenCode 的权限审批、plan mode、子 agent，那就别换——迁移成本大于收益。二问控制权：要把 agent 行为拧到自己手里（最小上下文、自定义工具、嵌入产品），pi 的扩展模型上限更高。三问中间态：其实没有中间态——但 pi 官方 README 留了一扇门：「Make pi look like Claude Code」被明确列在扩展能做到的事情里。也就是说，全家桶的「形」在 pi 上是可重建的，而 pi 的「骨」在全家桶上是不可拆的。想清楚哪边不可妥协，选择就自动成立了。

08

进阶方向与资源

• 官方仓库：github.com/badlogic/pi-mono —— coding-agent 的 README 就是主文档，docs/ 分册覆盖 providers、extensions、skills、packages、sdk、rpc 等主题。
• 官网：pi.dev —— 极简哲学的官方陈述，以及它对「上下文工程」的态度。
• 扩展示例：仓库 packages/coding-agent/examples/extensions/ —— 从注册工具到自定义 UI，拿一个改改就是你的第一个扩展。
• SDK 集成案例：openclaw/openclaw —— README 点名的真实 SDK 集成项目。
• 会话数据共享：badlogic/pi-share-hf —— 把 OSS 工作会话发布到 Hugging Face，用真实任务数据帮模型与工具进化。
• Discord 社区：README 徽章入口，第三方 pi 包的集散地之一。
• 分册文档：docs/providers.md（各家 provider 配置）、docs/extensions.md（扩展 API）、docs/packages.md（打包发布）、docs/session-format.md（会话 JSONL 格式）——按需深入。
• 会话树原理：docs/compaction.md 讲压缩内部机制——想搞懂「上下文管理」这个课题，这是难得的公开实现。

09

收尾：照着勾一遍

0 / 5