一天一个开源项目

开源项目第187期：Pi — 哲学驱动的极简 AI Coding Agent，86k Stars，30+ LLM 提供商，无限扩展

极简哲学驱动的 AI coding agent harness。5 个 npm 包：统一 LLM API（30+ 提供商）、agent 运行时、TUI 库、coding agent CLI、遥测合约。四种模式（交互/打印/JSON/RPC/SDK），会话分支树，TypeScript 扩展系统，Skills/Prompt Templates/Pi Packages 生态。刻意不内置 MCP、子 agent、权限弹窗、计划模式。TypeScript，MIT，86k Stars。

·约 11 分钟阅读·AI Tools
open-sourceAI-agentcoding-agentterminalTypeScriptLLMCLIextensibledeveloper-tools

引言

"Adapt pi to your workflows, not the other way around."

这是「每日一个开源项目」系列的第 187 篇。今天的项目是 Pi —— 一个极简哲学驱动的 AI coding agent harness，86,334 颗 Star，由游戏开发者 Mario Zechner（libGDX 作者）创建。

Pi 有一个不寻常的 README 章节叫「Philosophy」，里面逐条列出了它刻意不做的事：没有 MCP、没有子 agent、没有权限弹窗、没有计划模式、没有内置待办列表、没有后台 bash。每条后面跟着理由，以及「如果你真的需要，用扩展自己做」。

这不是功能缺失，而是一种设计立场：核心保持极简，所有定制通过扩展层完成，不强迫用户接受工具作者的工作流偏好。

86k Stars，2025 年 8 月创建，MIT 许可。

你会学到什么

  • Pi 的 5 个 npm 包和各自的职责
  • 四种运行模式：交互/打印/JSON/RPC/SDK
  • 会话分支树（Session Tree）的设计
  • 扩展生态：Extensions、Skills、Prompt Templates、Pi Packages
  • Pi 的哲学：刻意不内置什么，以及为什么
  • 30+ LLM 提供商列表和切换方式

前提知识

  • 基本的终端/命令行使用经验
  • 了解 AI coding agent 的基本概念（工具调用、系统提示）
  • TypeScript 基础知识对理解扩展开发有帮助

项目背景

概述

Pi 是一个 AI coding agent 的「harness」—— 这个词很准确：它是一个驾驭 LLM 的框架，而不是一个固定的产品。它把 LLM 接入、agent 循环、TUI 渲染、会话管理做成了独立的 npm 包，让用户可以根据需要选择和扩展。

项目信息

  • 作者: Mario Zechner（badlogic，libGDX 游戏框架作者）
  • 主语言: TypeScript
  • 许可证: MIT
  • 官网: pi.dev

项目数据

  • ⭐ GitHub Stars: 86,334+
  • 🍴 Forks: 10,721+
  • 📄 许可证: MIT
  • 📅 创建时间: 2025-08-09

五个 npm 包

Pi 是一个 monorepo，核心功能拆分成五个独立的 npm 包：

包名功能
@earendil-works/pi-ai统一多提供商 LLM API（OpenAI、Anthropic、Google 等）
@earendil-works/pi-agent-coreAgent 运行时：工具调用循环 + 状态管理
@earendil-works/pi-coding-agent交互式 coding agent CLI（面向用户的主入口）
@earendil-works/pi-tui差分渲染 TUI 库
@earendil-works/pi-telemetry厂商中立遥测合约、参考适配器、合规测试

这种拆分让用户可以只用 pi-ai 做 LLM API 统一层，或者只用 pi-agent-core 嵌入到自己的应用里，不必接受整个 coding agent CLI。

快速上手

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
# 或者
curl -fsSL https://pi.dev/install.sh | sh

设置 API Key 或直接登录订阅账号：

export ANTHROPIC_API_KEY=sk-ant-...
pi
pi
/login  # 选择提供商（支持订阅账号：Claude Pro/Max、ChatGPT Plus/Pro、GitHub Copilot）

默认开箱即用的工具：read、bash、edit、write、grep、find、ls。不需要任何配置，直接对话。

30+ LLM 提供商

Pi 内置的提供商列表是目前 coding agent 工具里最全的之一：

订阅账号（无需 API Key）：

  • Anthropic Claude Pro/Max
  • OpenAI ChatGPT Plus/Pro（Codex）
  • GitHub Copilot

API Key 接入：

  • Anthropic、OpenAI、Azure OpenAI、DeepSeek
  • Google Gemini、Google Vertex、Amazon Bedrock
  • Mistral、Groq、Cerebras、xAI
  • Cloudflare AI Gateway、Cloudflare Workers AI
  • OpenRouter、Vercel AI Gateway
  • Hugging Face、Fireworks、Together AI、Baseten
  • NVIDIA NIM、Kimi For Coding、MiniMax
  • 小米 MiMo（含中国区、阿姆斯特丹、新加坡节点）
  • ZAI Coding Plan（全球/中国）、OpenCode Zen/Go
  • Ant Ling

本地推理：

  • llama.cpp router server（/login llama.cpp + /llama 管理模型下载）

切换模型用 Ctrl+L 打开选择器，或命令行：

pi --model openai/gpt-4o "帮我重构这段代码"
pi --model sonnet:high "解决这个复杂问题"  # 带思考级别

四种运行模式

交互模式（默认）

带 TUI 的交互终端，从上到下：

  • 启动头部：快捷键提示、已加载的 AGENTS.md、模板、技能、扩展
  • 消息区：对话、工具调用结果、错误、扩展 UI
  • 编辑器：边框颜色标示思考级别
  • 底部状态栏：工作目录、会话名、token 用量（↑ 输入/↓ 输出/R 缓存读/W 缓存写/CH 缓存命中率）、成本、当前模型

打印模式（非交互）

pi -p "总结这个代码库"
cat README.md | pi -p "总结这段文字"   # 支持管道 stdin

JSON 模式

pi --mode json "帮我分析这个问题"
# 输出所有事件为 JSONL，适合脚本处理

RPC 模式

pi --mode rpc
# stdin/stdout JSONL 协议，适合非 Node.js 进程集成

SDK 模式（嵌入使用）

import { createAgentSession, ModelRuntime, SessionManager } from "@earendil-works/pi-coding-agent";
 
const modelRuntime = await ModelRuntime.create();
const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  modelRuntime,
});
 
await session.prompt("当前目录有哪些文件？");

会话系统

会话存储

会话以 JSONL 文件形式保存在 ~/.pi/agent/sessions/，按工作目录分组。每条记录有 id 和 parentId，天然支持分支结构，不需要创建多个文件。

pi -c              # 继续最近的会话
pi -r              # 浏览并选择历史会话
pi --no-session    # 临时模式，不保存
pi --name "任务名" # 命名会话

会话分支树（Session Tree）

这是 Pi 的一个独特设计：按 Escape 两次打开 /tree 视图，可以在整个会话历史树中导航，跳到任意历史节点继续工作。

/tree  快捷键：
  搜索：输入关键词
  折叠/展开分支：Ctrl+← / Ctrl+→
  翻页：← / →
  过滤模式：Ctrl+O（默认→无工具→仅用户→仅标签→全部）
  复制消息：Ctrl+X
  添加书签：Shift+L

/fork：从历史节点创建新会话文件（修改后重新发送）。 /clone：复制当前分支到新会话文件，从当前位置继续。

Context Compaction（上下文压缩）

长会话超出上下文窗口时，Pi 支持自动或手动压缩：

/compact           # 手动压缩
/compact 专注 API  # 带自定义指令的压缩

自动压缩默认开启，在接近上下文限制时触发，或上下文溢出时恢复重试。完整历史仍在 JSONL 文件中，通过 /tree 可回溯。

扩展生态

Extensions（TypeScript 扩展）

扩展是 Pi 最强大的机制：TypeScript 模块，可以添加自定义工具、命令、快捷键、事件处理、UI 组件。

export default function (pi: ExtensionAPI) {
  pi.registerTool({ name: "deploy", ... });
  pi.registerCommand("stats", { ... });
  pi.on("tool_call", async (event, ctx) => { ... });
}

扩展能做的事（README 列举的部分）：

  • 自定义工具（或完全替换内置工具）
  • 子 agent 和计划模式
  • 自定义上下文压缩和摘要
  • 权限门控和路径保护
  • 自定义编辑器和 UI 组件
  • 状态栏、头部、底部、覆盖层
  • Git 检查点和自动提交
  • SSH 和沙箱执行
  • MCP server 集成
  • 让 Pi 看起来像 Claude Code
  • 游戏（在等待期间玩 Doom —— 有人真的实现了）

扩展放在 ~/.pi/agent/extensions/（全局）或 .pi/extensions/（项目级）。

Skills（技能包）

遵循 Agent Skills 标准，按需加载的能力包，Markdown 格式：

<!-- ~/.pi/agent/skills/my-skill/SKILL.md -->
# My Skill
当用户询问 X 时使用此技能。
 
## Steps
1. 做这个
2. 然后那个

通过 /skill:名称 手动调用，或由 agent 根据 SKILL.md 描述自动选择。

Prompt Templates（提示词模板）

<!-- ~/.pi/agent/prompts/review.md -->
检查这段代码中的 Bug、安全问题和性能问题。
重点关注：{{focus}}

编辑器里输入 /review 自动展开。

Pi Packages

将扩展、技能、模板、主题打包通过 npm 或 git 分享：

pi install npm:@foo/pi-tools
pi install git:github.com/user/repo
pi install git:github.com/user/repo@v1   # 固定版本
pi list
pi update --all
pi config    # 启用/禁用扩展、技能、模板

⚠️ 安全警告：Pi Packages 以完整系统权限运行。安装第三方包前请审查源代码。

Pi 的哲学：刻意不做什么

Pi 的 Philosophy 章节逐条列出了它不内置的功能，以及背后的原因：

刻意不做为什么如何满足需求
MCP见这篇博文，CLI 工具 + README 更直接用扩展自己实现 MCP 支持
子 agent实现方式各异，不应由工具强制用 tmux 启动多个 pi 实例，或扩展实现
权限弹窗应与执行环境和安全需求契合，不该是通用弹窗在容器里运行，或扩展实现符合场景的确认流
计划模式各有偏好把计划写进文件，或扩展实现
内置待办会让模型困惑用 TODO.md，或扩展实现
后台 bashtmux 有完整可见性和直接交互用 tmux

这种「刻意极简」的设计哲学意味着 Pi 的核心不会随着功能膨胀而变得难以理解，也不会强迫用户接受一套固定的工作流。代价是：新用户的开箱体验不如功能全面的工具，需要花时间配置才能达到理想状态。

供应链安全

Pi 对依赖安全的处理值得单独提：

  • 精确版本锁定：所有直接外部依赖固定到精确版本（save-exact=true），内部 workspace 包使用范围版本
  • 最小发布年龄：.npmrc 设置 min-release-age=2，避免安装当天刚发布的依赖
  • package-lock.json 作为唯一真相：pre-commit hook 阻止意外的 lockfile 修改（需要 PI_ALLOW_LOCKFILE_CHANGE=1 显式解除）
  • shrinkwrap：发布的 CLI 包含 npm-shrinkwrap.json，对 npm 用户锁定传递依赖
  • CI 审计：定期运行 npm audit --omit=dev + npm audit signatures --omit=dev
  • Lifecycle script 许可名单：有明确允许列表，新的 lifecycle script 依赖会导致检查失败直到被审查

消息队列（在 Agent 工作时发送）

一个细节设计：在 agent 正在执行工具调用时，可以提前排队消息：

  • Enter — 排队一条「引导」消息，在当前工具调用完成后立即发送
  • Alt+Enter — 排队一条「后续」消息，在 agent 完成所有工作后发送
  • Escape — 中止并把排队消息恢复到编辑器

这解决了「agent 跑偏了但我又不想粗暴中断」的常见场景。

参考资源

官方链接

总结

Pi 是一个有清晰设计立场的工具：宁可核心极简、需要用户自己配置，也不要一个充满内置功能但难以修改的黑盒。86k Star 说明这个立场找到了对应的用户群。

几个工程决策值得记录：

Philosophy 章节：主动声明不做什么并给出理由，这在开源工具里比较少见。它让用户在安装前就能判断这个工具是否适合自己，而不是安装后发现缺少某个「标准功能」。

5 个独立 npm 包：TUI、LLM API、agent 运行时各自独立，意味着你可以只用 pi-ai 做多提供商统一层，或者用 pi-agent-core 把 agent 循环嵌入自己的应用。不需要接受整个 CLI。

会话分支树：JSONL + parentId 的树形结构让分支不需要多文件，所有历史都在一个文件里，通过 /tree 视图随时导航。在其他 coding agent 工具里这种设计不常见。

供应链安全的投入：依赖精确锁定、lockfile pre-commit 保护、CI 定期审计、shrinkwrap 锁定传递依赖 —— 这个重视程度超过了大多数开发工具。

如果你对 Claude Code、Codex 这类工具的工作流有自己的想法，并且愿意花一点时间配置而不是开箱即用，Pi 的扩展系统给了你足够的空间把它改造成你想要的样子。

探索 PrimeSkills —— 精选 AI agent 和技能工具，每一个都经过真实工作流验证。没有炒作，只有真正好用的工具。

访问我的个人主页，获取更多见解和有趣的产品。

← 返回博客列表