乐于分享
好东西不私藏

32k stars!终端里的 AI 编程助手:pi-mono 全面解析!

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
核心:终端编程 Agent CLI
@mariozechner/pi-ai
统一 LLM API,支持多家提供商
@mariozechner/pi-tui
终端 UI 库(差分渲染)
@mariozechner/pi-web-ui
Web 端 AI 对话 UI 组件
@mariozechner/pi-mom
Slack Bot,将消息委托给 pi agent
@mariozechner/pi-pods
管理 vLLM 在 GPU Pod 上部署的 CLI

核心功能详解

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
Claude Code
Cursor
开源
多 LLM 提供商
部分
部分
本地模型支持
有限
可扩展(无需 fork)
纯终端运行
会话分支管理
有限
Slack 集成
vLLM 部署管理

总结

pi-mono 是一个面向严肃开发者的 AI Agent 基础设施项目。它不追求「开箱即用、面向大众」的产品路线,而是把扩展性和可组合性放在第一位。

适合你,如果你:

  • • 不满足于「黑盒」的 AI 编程助手,希望深度定制行为
  • • 需要在多个 LLM 提供商之间灵活切换,或接入本地私有模型
  • • 想把 AI Agent 能力嵌入到自己的工具链、Slack 工作流中
  • • 是一个喜欢折腾、相信「工具应该服务于工作流」的工程师

可能不适合,如果你:

  • • 只是想要一个简单好用的 AI 编程助手,不想管底层细节
  • • 团队以非技术角色为主,难以维护 TypeScript 扩展

从提交频率和 CHANGELOG 的活跃程度来看,这个项目正处于高速迭代阶段,值得持续关注。

项目地址github.com/badlogic/pi-mono


如果你觉得这篇文章有帮助,欢迎点赞转发~