32k stars!终端里的 AI 编程助手:pi-mono 全面解析!
终端里的 AI 编程助手:pi-mono 全面解析
一个工具包,搞定 AI Agent 开发的所有基础设施
背景:现有工具哪里不够用?
过去两年,AI 编程助手如雨后春笋:GitHub Copilot、Cursor、Claude Code……但开发者在实际使用中常常碰到三堵墙:
第一堵墙:绑定死了。 工具和特定 LLM 提供商强绑定,换个模型就要换整套工具链。
第二堵墙:不能改。 想自定义行为?要么 fork 源码,要么对着文档苦等官方更新。
第三堵墙:散装的。 想在终端用、又想接 Slack、还想跑自己的模型服务,需要东拼西凑好几套工具。
pi-mono 就是为了解决这三个痛点而生的。
pi-mono 是什么?
pi-mono 是一个开源的 AI Agent 工具包,项目的核心定位是:
“AI agent toolkit: coding agent CLI, unified LLM API, TUI & web UI libraries, Slack bot, vLLM pods”
换成大白话就是:一个 monorepo,包含了从「和 AI 对话写代码」到「部署自己的模型服务」全流程所需的所有基础设施。
项目由 Mario Zechner(libGDX 作者,游戏开发界知名开发者)主导开发,目前活跃度极高,几乎每天都有更新。

核心子包一览
|
|
|
|---|---|
@mariozechner/pi-coding-agent |
|
@mariozechner/pi-ai |
|
@mariozechner/pi-tui |
|
@mariozechner/pi-web-ui |
|
@mariozechner/pi-mom |
|
@mariozechner/pi-pods |
|
核心功能详解
1. pi 编程 Agent —— 终端里的”轻量 Claude Code”
pi 是整个项目的门面。它是一个跑在终端里的 AI 编程助手,但和市面上大多数工具不同,它的设计哲学是:
“Adapt pi to your workflows, not the other way around.”
让工具适应你的工作流,而不是反过来。
默认工具集极简:开箱即用只给模型四个工具 —— read(读文件)、write(写文件)、edit(编辑文件)、bash(执行命令),刻意不加子 Agent 和 Plan Mode,保持轻量。
四种运行模式:
-
• Interactive:交互式 TUI 界面 -
• Print / JSON:打印输出,适合脚本调用 -
• RPC:进程间集成 -
• SDK:嵌入到自己的应用中
会话管理:会话自动保存到 ~/.pi/agent/sessions/,支持分支浏览、时间线回溯(/tree 命令),类似 Git 分支的概念管理对话历史。
2. 统一 LLM API —— 一套代码打天下
pi-ai 包提供了统一的多模型接口,一套 API 调用 OpenAI、Anthropic、Google 等多家提供商:
import { getModel, stream, Context } from '@mariozechner/pi-ai';
// 支持自动补全的强类型调用
const model = getModel('openai', 'gpt-4o-mini');
const context: Context = {
systemPrompt: 'You are a helpful assistant.',
messages: [{ role: 'user', content: '帮我写一个快排算法' }],
};
// 流式输出
const s = stream(model, context);
for await (const event of s) {
if (event.type === 'text_delta') process.stdout.write(event.text);
}
本地模型同样支持,只需在 ~/.pi/agent/models.json 添加配置:
{
"providers": {
"ollama": {
"baseUrl": "http://localhost:11434/v1",
"api": "openai-completions",
"models": [{ "id": "qwen2.5-coder:7b" }]
}
}
}
Ollama、vLLM、LM Studio 等 OpenAI 兼容服务均可接入。
3. 扩展系统 —— 不 fork 源码,照样深度定制
这是 pi-mono 最有特色的部分。用户可以通过 TypeScript Extension 来扩展 pi 的行为,无需修改核心源码:
import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
import { Type } from "@sinclair/typebox";
export default function (pi: ExtensionAPI) {
// 监听生命周期事件,拦截危险命令
pi.on("tool_call", async (event, ctx) => {
if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
const ok = await ctx.ui.confirm("危险操作!", "确认执行 rm -rf 吗?");
if (!ok) return { block: true, reason: "用户已拒绝" };
}
});
// 注册自定义工具(LLM 可以调用)
pi.registerTool({
name: "greet",
description: "向用户打招呼",
parameters: Type.Object({ name: Type.String() }),
async execute(toolCallId, params) {
return { content: [{ type: "text", text: `你好,${params.name}!` }] };
},
});
// 注册自定义命令(用户输入 /hello 触发)
pi.registerCommand("hello", {
description: "打声招呼",
handler: async (args, ctx) => ctx.ui.notify("Hello!"),
});
}
扩展支持打包成 Pi Package 通过 npm 或 git 分发,团队间共享配置非常方便。
4. Skills 和 Prompt Templates —— 给 AI 注入领域知识
Skills 是放在项目 .pi/skills/ 目录下的 Markdown 文件,pi 启动时会自动加载,相当于给模型配置项目专属的背景知识和操作规范。例如:你可以写一个 deploy.md 的 Skill,描述你们团队的部署流程,之后直接告诉 pi「帮我部署」,它就知道走哪套流程。
Prompt Templates 则是可复用的提示词模板,适合团队统一 AI 使用规范。
5. 多模型支持,随时切换
pi 内置支持主流模型提供商,通过 /login 订阅或配置 API Key 即可切换。在交互模式中,Ctrl+L 或 /model 命令可以随时在不同模型间切换,无需重启。
支持的提供商包括:OpenAI、Anthropic、Google(含 Gemini)、AWS Bedrock、Google Vertex AI,以及任何 OpenAI 兼容的本地服务。
怎么用?
安装
# 通过 npm 全局安装 pi 编程助手
npm install -g @mariozechner/pi-coding-agent
# 进入任意项目目录,启动
pi
基本使用
pi # 进入交互模式
pi "帮我重构这个函数" # 非交互模式,直接执行任务
pi -c # 继续上次会话
pi -r # 浏览历史会话列表
pi --no-session # 临时模式,不保存会话
pi --fork <session-id> # 从某个历史节点 fork 出新会话
常用交互命令
/model 切换模型(或 Ctrl+L)
/tree 浏览会话分支树
/fork 从当前节点创建新分支
/hotkeys 查看所有快捷键
Ctrl+O 切换消息过滤模式
安装扩展包
pi install npm:@foo/bar # 从 npm 安装
pi install git:github.com/user/repo # 从 git 安装
pi install ./my-local-extension # 本地路径安装
pi list # 查看已安装包
pi update # 更新所有包
从源码构建(开发者)
git clone https://github.com/badlogic/pi-mono
cd pi-mono
npm install # 安装所有依赖
npm run build # 构建所有包
npm run check # Lint + 格式检查 + 类型检查
./test.sh # 运行测试
./pi-test.sh # 从源码运行 pi(可在任意目录执行)
与同类工具的对比
|
|
|
|
|
|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
总结
pi-mono 是一个面向严肃开发者的 AI Agent 基础设施项目。它不追求「开箱即用、面向大众」的产品路线,而是把扩展性和可组合性放在第一位。
适合你,如果你:
-
• 不满足于「黑盒」的 AI 编程助手,希望深度定制行为 -
• 需要在多个 LLM 提供商之间灵活切换,或接入本地私有模型 -
• 想把 AI Agent 能力嵌入到自己的工具链、Slack 工作流中 -
• 是一个喜欢折腾、相信「工具应该服务于工作流」的工程师
可能不适合,如果你:
-
• 只是想要一个简单好用的 AI 编程助手,不想管底层细节 -
• 团队以非技术角色为主,难以维护 TypeScript 扩展
从提交频率和 CHANGELOG 的活跃程度来看,这个项目正处于高速迭代阶段,值得持续关注。
项目地址:github.com/badlogic/pi-mono
如果你觉得这篇文章有帮助,欢迎点赞转发~
夜雨聆风