pi-mono 框架完全指南 2026：极简主义 AI 编码助手实战

在 AI 编码助手日益复杂的今天，pi-mono 以其极简主义设计哲学脱颖而出。作为一个模块化的 monorepo 项目，pi-mono 提供了一套统一的 LLM API、轻量级的编码代理 CLI 和灵活的终端 UI 组件，让开发者能够以最小的开销获得强大的 AI 辅助编程能力。

本文将深入介绍 pi-mono 的核心组件、使用方法和最佳实践，帮助你快速掌握这个新兴的 AI 开发工具。

一、什么是 pi-mono？

pi-mono 简介

pi-mono 是一个用 TypeScript 编写的模块化 monorepo 项目，由开发者 Mario Zehner 创建。它包含多个相互关联的包，核心目标是提供：

统一的 LLM API：支持多个提供商的无缝切换
极简编码助手：专注于核心功能，拒绝臃肿
完全可观测性：所有交互都可检查和追踪
灵活的部署方案：支持云端和本地 LLM 部署

GitHub: https://github.com/badlogic/pi-mono

NPM: https://www.npmjs.com/org/mariozechner

设计哲学

pi-mono 遵循以下核心设计原则：

原则	描述
极简主义	只构建需要的功能，拒绝功能膨胀
完全可观测	所有交互都可检查、可追踪
上下文工程优先	精确控制进入模型上下文的内容
YOLO 模式	默认无限制访问文件系统（无安全检查）
文件即状态	使用 TODO.md、PLAN.md 等文件而非内置功能

有意不支持的功能

pi-mono 有意不包含以下流行功能，以保持简洁：

功能	替代方案
❌ 内置待办列表	使用 `TODO.md` 文件
❌ 计划模式	使用 `PLAN.md` 文件 + 只读工具
❌ MCP 支持	使用 CLI 工具替代
❌ 后台 bash	使用 `tmux`
❌ 子代理	通过 bash 自启动子代理

二、项目结构

Monorepo 架构

pi-mono/
├── packages/                # 核心包目录
│   ├── ai/                  # 统一 LLM API
│   ├── agent-core/          # 代理运行时
│   ├── coding-agent/        # 编码代理 CLI
│   ├── tui/                 # 终端 UI 库
│   ├── web-ui/              # Web 聊天组件
│   ├── mom/                 # Slack 机器人
│   └── pods/                # vLLM 部署管理
├── scripts/                 # 脚本工具
├── .pi/                     # pi 配置
├── biome.json               # 代码风格配置
├── tsconfig.base.json       # TypeScript 基础配置
└── package.json             # 根配置

核心包说明

包名	描述	用途
`@mariozechner/pi-ai`	统一 LLM API	多提供商模型访问
`@mariozechner/pi-agent-core`	代理运行时	状态管理、事件订阅
`@mariozechner/pi-coding-agent`	编码代理 CLI	交互式代码开发
`@mariozechner/pi-tui`	终端 UI	差异渲染、进度条
`@mariozechner/pi-web-ui`	Web 组件	AI 聊天界面
`@mariozechner/pi-mom`	Slack 机器人	消息委托
`@mariozechner/pi-pods`	GPU 部署	vLLM 管理

三、快速开始

3.1 环境要求

Node.js: 18.0 或更高版本
npm: 9.0 或更高版本
操作系统: Windows / Linux / macOS

3.2 安装 pi-coding-agent

# 全局安装编码代理
npm install -g @mariozechner/pi-coding-agent

# 验证安装
pi --version

3.3 配置 API 密钥

创建 ~/.pi/config.json 配置文件：

{
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-your-anthropic-key"
    },
    "openai": {
      "apiKey": "sk-your-openai-key"
    },
    "google": {
      "apiKey": "your-google-key"
    }
  },
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-5"
}

或者使用环境变量：

export ANTHROPIC_API_KEY="sk-ant-your-key"
export OPENAI_API_KEY="sk-your-key"

3.4 第一个命令

# 基本使用
pi "帮我创建一个 Python Flask 应用"

# 指定模型
pi --provider anthropic --model claude-sonnet-4-5 "解释一下什么是闭包"

# 只读模式（仅查看，不修改文件）
pi --tools read,grep,find,ls "分析这个项目的结构"

# 打印模式（不执行，只显示计划）
pi --print "重构这个函数的代码结构"

四、pi-ai：统一 LLM API

4.1 安装

npm install @mariozechner/pi-ai

4.2 支持的模型提供商

提供商	API 类型	代表模型
Anthropic	Messages API	Claude 3/4 系列
OpenAI	Completions/Responses	GPT-4o, o3-mini
Google	Generative AI	Gemini 2.0
xAI	OpenAI-compatible	Grok-2
Groq	OpenAI-compatible	Llama 3.1
Cerebras	OpenAI-compatible	Llama 3.1
OpenRouter	OpenAI-compatible	多模型聚合

4.3 基本用法

import { 
  Type, 
  getModel, 
  stream, 
  complete, 
  Context,
  Tool,
  StringEnum 
} from '@mariozechner/pi-ai';

// 获取模型（完全类型支持）
const model = getModel('anthropic', 'claude-sonnet-4-5');

// 创建上下文
const context: Context = {
  messages: [
    { role: 'user', content: '你好，请介绍一下自己' }
  ]
};

// 完整响应
const response = await complete(model, context);
console.log(response.content);

// 流式响应
const s = stream(model, context);
for await (const chunk of s) {
  process.stdout.write(chunk);
}

4.4 多提供商切换

import { getModel, complete, Context } from '@mariozechner/pi-ai';

// 创建共享上下文
const context: Context = {
  messages: [
    { role: 'user', content: '解释量子计算' }
  ]
};

// 使用 Claude
const claude = getModel('anthropic', 'claude-sonnet-4-5');
const claudeResponse = await complete(claude, context);

// 无缝切换到 GPT-4（保留上下文）
const gpt4 = getModel('openai', 'gpt-4o');
const gptResponse = await complete(gpt4, context);

// 切换到 Gemini
const gemini = getModel('google', 'gemini-2.0-flash');
const geminiResponse = await complete(gemini, context);

4.5 工具调用

import { Tool, Type } from '@mariozechner/pi-ai';

// 定义工具
const weatherTool: Tool<typeof weatherSchema> = {
  name: 'get_weather',
  description: '获取城市天气信息',
  parameters: Type.Object({
    city: Type.String({ 
      description: '城市名称',
      minLength: 1 
    }),
  }),
  execute: async (toolCallId, args) => {
    // 实际调用天气 API
    const temp = await fetchWeather(args.city);
    
    return {
      output: `${args.city}的温度：${temp}°C`, // 给 LLM
      details: { temperature: temp }          // 给 UI
    };
  }
};

// 使用工具
const response = await complete(model, {
  messages: [{ role: 'user', content: '北京天气如何？' }],
  tools: [weatherTool]
});

4.6 推理/思考模式

import { complete, Context } from '@mariozechner/pi-ai';

const model = getModel('anthropic', 'claude-sonnet-4-5');

// 检查模型是否支持推理
if (model.supportsReasoning) {
  console.log('模型支持推理/思考功能');
}

// 启用思考模式
const response = await complete(model, {
  messages: [{ 
    role: 'user', 
    content: '解决这个复杂的数学问题...' 
  }],
  thinking: {
    enabled: true,
    budget: 10000  // 思考 token 预算
  }
});

// 访问思考过程
console.log('思考过程:', response.thinking);
console.log('最终答案:', response.content);

4.7 Token 和成本追踪

import { complete, createCostTracker } from '@mariozechner/pi-ai';

// 创建成本追踪器
const costTracker = createCostTracker();

const response = await complete(model, {
  messages: [{ role: 'user', content: '...' }],
  costTracker
});

// 查看使用情况
const usage = costTracker.getUsage();
console.log(`输入 Token: ${usage.inputTokens}`);
console.log(`输出 Token: ${usage.outputTokens}`);
console.log(`总成本：$${usage.totalCost.toFixed(4)}`);

五、pi-coding-agent：编码代理 CLI

5.1 核心工具

pi-coding-agent 提供 4 个核心工具：

工具	描述	参数
read	读取文件内容	`path`, `offset`, `limit`
write	写入/创建文件	`path`, `content`
edit	精确编辑文件	`path`, `oldText`, `newText`
bash	执行 bash 命令	`command`, `timeout`

5.2 只读工具（可选）

# 启用只读工具
pi --tools read,grep,find,ls "分析项目结构"

工具	描述
grep	文本搜索
find	文件查找
ls	目录列表

5.3 会话管理

# 继续当前会话
pi continue "继续之前的任务"

# 恢复之前的会话
pi resume "session-2026-03-18"

# 创建会话分支
pi branch "experimental" "尝试新的实现方法"

# 列出所有会话
pi sessions

# 删除会话
pi session delete "session-id"

5.4 项目上下文（AGENTS.md）

在项目根目录创建 AGENTS.md 文件，定义项目特定规则：

# 项目规则

## 代码风格
- 使用 TypeScript
- 遵循 ESLint 配置
- 函数最大长度 50 行

## 测试要求
- 所有新功能必须包含单元测试
- 使用 Jest 测试框架
- 覆盖率不低于 80%

## 提交规范
- 使用 Conventional Commits
- 必须包含 issue 链接

## 技术栈
- Node.js 18+
- React 18
- PostgreSQL 15

pi 会自动加载这些规则到上下文中。

5.5 自定义 Slash 命令

创建 .pi/commands/review.md：

---
description: 运行代码审查子代理
---
作为代码审查专家，请审查当前目录的代码：

1. 检查代码风格和最佳实践
2. 识别潜在的性能问题
3. 查找安全漏洞
4. 提供改进建议

使用以下命令执行审查：
$@

使用：

pi /review "审查 src/ 目录的代码"

5.6 主题定制

创建自定义主题 ~/.pi/themes/dark.json：

{
  "name": "Dark Theme",
  "colors": {
    "primary": "#00ff00",
    "secondary": "#0088ff",
    "error": "#ff4444",
    "success": "#44ff44",
    "warning": "#ffaa00"
  },
  "symbols": {
    "user": "👤",
    "assistant": "🤖",
    "tool": "🔧",
    "error": "❌"
  }
}

使用：

pi --theme dark "帮我写个函数"

六、实战示例

6.1 创建 Flask 应用

pi "创建一个简单的 Flask REST API 应用，包含以下功能：
1. GET /users - 获取用户列表
2. POST /users - 创建用户
3. GET /users/:id - 获取单个用户
4. DELETE /users/:id - 删除用户

使用 SQLite 数据库，包含完整的错误处理。"

6.2 代码重构

pi --tools read,edit,bash "重构 src/services/userService.ts 文件：
1. 提取重复逻辑为独立函数
2. 添加 TypeScript 类型定义
3. 添加单元测试
4. 运行测试确保功能正常"

6.3 Bug 修复

pi "分析并修复以下问题：
应用启动时报错 'Cannot find module xxx'。
请检查 package.json 和导入语句，修复依赖问题。"

6.4 功能开发

pi "为项目添加用户认证功能：
1. 安装必要的依赖（jsonwebtoken, bcrypt）
2. 创建认证中间件
3. 实现登录和注册接口
4. 更新 API 文档"

七、pi-agent-core：代理运行时

7.1 安装

npm install @mariozechner/pi-agent-core

7.2 创建 Agent

import { Agent, createModel } from '@mariozechner/pi-agent-core';
import { getModel } from '@mariozechner/pi-ai';

// 创建 Agent
const agent = new Agent({
  model: getModel('anthropic', 'claude-sonnet-4-5'),
  name: '编码助手',
  instructions: '你是一个专业的 TypeScript 开发助手'
});

// 订阅事件
agent.on('message', (msg) => {
  console.log('收到消息:', msg);
});

agent.on('tool-call', (call) => {
  console.log('工具调用:', call.name, call.args);
});

agent.on('error', (err) => {
  console.error('错误:', err);
});

// 发送消息
await agent.send('帮我创建一个快速排序函数');

7.3 状态管理

import { Agent } from '@mariozechner/pi-agent-core';

const agent = new Agent({
  model: getModel('anthropic', 'claude-sonnet-4-5'),
  state: {
    project: 'my-app',
    language: 'typescript',
    framework: 'react'
  }
});

// 更新状态
agent.setState({ language: 'typescript' });

// 获取状态
const currentState = agent.getState();
console.log(currentState);

7.4 消息队列

import { Agent, QueueMode } from '@mariozechner/pi-agent-core';

// 逐个处理模式（默认）
const agent1 = new Agent({
  model: getModel('anthropic', 'claude-sonnet-4-5'),
  queueMode: QueueMode.OneAtATime
});

// 全部处理模式
const agent2 = new Agent({
  model: getModel('anthropic', 'claude-sonnet-4-5'),
  queueMode: QueueMode.AllAtOnce
});

// 添加消息
await agent1.send('消息 1');
await agent1.send('消息 2');
await agent1.send('消息 3');

7.5 附件处理

import { Agent } from '@mariozechner/pi-agent-core';

const agent = new Agent({
  model: getModel('anthropic', 'claude-sonnet-4-5')
});

// 发送带图片的消息
await agent.send({
  content: '分析这张截图的 UI 设计',
  attachments: [
    {
      type: 'image',
      path: './screenshot.png',
      mimeType: 'image/png'
    }
  ]
});

// 发送带文档的消息
await agent.send({
  content: '总结这份文档的内容',
  attachments: [
    {
      type: 'document',
      path: './spec.pdf',
      mimeType: 'application/pdf'
    }
  ]
});

八、pi-pods：LLM 部署管理

8.1 安装

npm install -g @mariozechner/pi-pods

8.2 配置 GPU Pod

# 配置 SSH 连接
pi pods setup gpt-pod "ssh root@1.2.3.4" \
  --models-path /workspace \
  --vllm gpt-oss

# 配置 RunPod
pi pods setup runpod "ssh root@pod.runpod.io" \
  --models-path /runpod-volume

8.3 启动模型

# 启动预配置模型
pi start some/model --name mymodel --vllm

# 启动自定义模型
pi start model --name custom --vllm \
  --model-path /models/llama-3.1-70b \
  --gpu-memory-utilization 0.9

# 查看可用模型
pi start

8.4 多 GPU 管理

# 自动分配 GPU
pi start model1 --name m1  # GPU 0
pi start model2 --name m2  # GPU 1
pi start model3 --name m3  # GPU 2

# 指定 GPU
pi start model --name m1 --gpu 0
pi start model --name m2 --gpu 1

# 查看 GPU 使用情况
pi pods status

8.5 与编码代理集成

# 使用本地模型运行编码代理
pi-agent \
  --api responses \
  --model openai/gpt-oss-20b \
  "帮我优化这个函数"

九、高级用法

9.1 构建自定义 UI

import { Agent } from '@mariozechner/pi-agent-core';
import { createTUI } from '@mariozechner/pi-tui';

// 创建终端 UI
const tui = createTUI({
  theme: 'dark',
  showToolCalls: true
});

// 创建 Agent
const agent = new Agent({
  model: getModel('anthropic', 'claude-sonnet-4-5')
});

// 连接 UI
agent.on('message', (msg) => tui.showMessage(msg));
agent.on('tool-call', (call) => tui.showToolCall(call));
agent.on('error', (err) => tui.showError(err));

// 启动交互
tui.start(async (input) => {
  await agent.send(input);
});

9.2 Web 集成

import { createWebUI } from '@mariozechner/pi-web-ui';
import { Agent } from '@mariozechner/pi-agent-core';

const agent = new Agent({
  model: getModel('anthropic', 'claude-sonnet-4-5')
});

// 创建 Web UI
const webUI = createWebUI({
  agent,
  port: 3000,
  title: 'AI 编码助手'
});

// 启动服务
webUI.start();

9.3 Slack 集成

import { createSlackBot } from '@mariozechner/pi-mom';
import { Agent } from '@mariozechner/pi-agent-core';

const agent = new Agent({
  model: getModel('anthropic', 'claude-sonnet-4-5')
});

// 创建 Slack 机器人
const bot = createSlackBot({
  token: process.env.SLACK_BOT_TOKEN,
  agent,
  channelFilter: ['coding-help', 'tech-support']
});

// 启动机器人
bot.start();

9.4 SDK 集成

import { createSDK } from '@mariozechner/pi-coding-agent/sdk';

// 创建 SDK 实例
const sdk = createSDK({
  apiKey: 'your-api-key',
  endpoint: 'http://localhost:8080'
});

// 构建自定义应用
const response = await sdk.send({
  message: '分析这个项目',
  tools: ['read', 'grep', 'find']
});

// 流式响应
const stream = await sdk.stream({
  message: '生成测试用例'
});

for await (const chunk of stream) {
  console.log(chunk);
}

十、最佳实践

10.1 上下文管理

# ✅ 推荐：使用 AGENTS.md 定义项目规则
# ✅ 推荐：使用 TODO.md 跟踪任务
# ✅ 推荐：使用 PLAN.md 记录计划

# ❌ 避免：让模型记住太多细节
# ❌ 避免：过长的对话历史（定期清理）

10.2 成本控制

# 使用较小的模型处理简单任务
pi --model claude-haiku-4 "格式化这个文件"

# 使用只读模式预览更改
pi --tools read,grep "分析这段代码的问题"

# 使用打印模式确认计划
pi --print "重构整个模块"

10.3 安全建议

# ⚠️ 注意：pi 默认无安全检查（YOLO 模式）

# 建议在重要项目上使用只读工具
pi --tools read,grep,find,ls "分析代码"

# 审查更改后再执行
pi --print "删除临时文件"

# 使用 Git 跟踪更改
git add -A && git commit -m "Before AI changes"
pi "重构代码"
git diff  # 审查更改

10.4 性能优化

// ✅ 推荐：使用流式响应
const stream = stream(model, context);
for await (const chunk of stream) {
  process.stdout.write(chunk);
}

// ✅ 推荐：批量处理消息
await agent.batch([
  '任务 1',
  '任务 2',
  '任务 3'
]);

// ✅ 推荐：使用本地模型减少延迟
pi start llama-3.1-8b --name local
pi-agent --model openai/llama-3.1-8b "快速响应"

十一、故障排查

常见问题

1. API 密钥错误

# 检查配置
cat ~/.pi/config.json

# 检查环境变量
echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY

2. 模型不可用

# 查看可用模型
pi start

# 切换提供商
pi --provider openai --model gpt-4o "任务"

3. 工具执行失败

# 检查工具权限
ls -la /path/to/project

# 使用超时
pi --timeout 60 "长时间运行的任务"

4. 内存不足

# 减少上下文大小
# 编辑 ~/.pi/config.json
{
  "maxContextTokens": 50000
}

# 使用较小的模型
pi --model claude-haiku-4 "任务"

十二、总结

pi-mono 以其极简主义设计哲学，为 AI 编码助手领域带来了一股清流。它不提供花哨的功能，而是专注于核心体验：快速、可观测、灵活。

核心优势：

✅ 极简设计：只包含必要的功能
✅ 完全可观测：所有交互都可检查
✅ 多模型支持：23+ 提供商无缝切换
✅ 灵活部署：云端 + 本地 LLM 支持
✅ 模块化架构：可按需使用各组件
✅ TypeScript 优先：完整的类型支持

适用场景：

快速原型开发
代码重构和优化
自动化测试生成
文档编写和维护
本地 LLM 部署和管理

参考资源：

GitHub: https://github.com/badlogic/pi-mono
NPM: https://www.npmjs.com/org/mariozechner
作者博客：https://mariozechner.at/
自定义工具：https://github.com/badlogic/agent-tools

开始使用 pi-mono，体验极简主义 AI 编码助手的魅力！🚀