Pi Agent · 可自我扩展的 AI 编码代理

安装 Pi（多平台）

一行克隆，安全安装，五分钟在本地跑起编码代理。点右侧按钮即可复制。

快速开始 git clone https://github.com/earendil-works/pi.git && cd pi

终端 · macOS

# 1. 获取源码
git clone https://github.com/earendil-works/pi.git
cd pi

# 2. 安全安装依赖（锁定版本，禁用生命周期脚本）
npm install --ignore-scripts

# 3. 构建全部包
npm run build

# 4. 启动交互式编码代理
./pi-test.sh

终端 · Linux

# 1. 获取源码
git clone https://github.com/earendil-works/pi.git
cd pi

# 2. 安全安装依赖（锁定版本，禁用生命周期脚本）
npm install --ignore-scripts

# 3. 构建全部包
npm run build

# 4. 启动交互式编码代理
./pi-test.sh

终端 · Windows (WSL2)

# 推荐在 WSL2 中运行，避免原生 PowerShell 路径问题
wsl
git clone https://github.com/earendil-works/pi.git
cd pi
npm install --ignore-scripts
npm run build
./pi-test.sh

若访问 GitHub 缓慢，可用国内镜像克隆，其余步骤与上方完全一致：

终端 · 国内镜像

# 用 ghproxy 镜像克隆
git clone https://ghproxy.com/https://github.com/earendil-works/pi.git
cd pi

# 之后步骤与上方一致
npm install --ignore-scripts
npm run build
./pi-test.sh

前置要求：Node.js 18+ 与 npm。要让代理真正调用模型，需在 pi-ai 中配置 API Key，详见模型供应商。

想看完整步骤与最小 Agent 循环示例？前往快速上手。

为什么是 Pi

不是又一个黑盒助手，而是一套你可以读懂、改写、扩展的 Agent 运行时。

🧩

稳定内核，可变外设

模型会变、工具会变、UI 会变，但 Agent Loop 的本质稳定：准备上下文 → 请求模型 → 处理工具 → 写回结果 → 继续或停止。

🔌

统一多供应商 LLM

pi-ai 屏蔽 OpenAI / Anthropic / Google / Bedrock / Vertex / Copilot 的差异，一份代码切换供应商。

🛠

工具 + 状态管理

pi-agent-core 内置工具调用与会话状态机，支持 JSONL 会话树、分支与断点续跑。

⌨️

交互式编码 CLI

pi-coding-agent 是终端里的结对程序员，读取仓库、改文件、跑命令、自我纠错。

🖥

差分渲染终端 UI

pi-tui 只重绘变化的部分，长会话也不卡顿，体验接近原生应用。

🔒

供应链加固

依赖精确锁定、lockfile 为真相源、发布前隔离测试，默认以启动用户权限运行。

四个核心包

npm workspaces 单仓，按需取用，也可整体安装。

🧠

@earendil-works/pi-ai

统一的多供应商大语言模型 API，流式、工具调用、供应商工厂一应俱全。

统一 LLM 接入

⚙️

@earendil-works/pi-agent-core

具备工具调用与状态管理的代理运行时，是 Pi 的心脏。

Agent 运行时

⌨️

@earendil-works/pi-coding-agent

面向开发者的交互式编码代理命令行工具。

编码 CLI

🖥

@earendil-works/pi-tui

带差分渲染能力的终端 UI 库，长输出也流畅。

终端 UI

一次请求怎么走

清晰的职责分层，让每一层都可独立替换与测试。

Layer 1 · 交互层

TUI / RPC / SDK

用户或外部系统通过终端界面、远程调用或直接 SDK 提交 prompt。

Layer 2 · 运行层

AgentSession → Agent

展开技能与模板、检查模型与认证，把消息交给 Agent Loop，并把事件回传 UI。

Layer 3 · 核心循环

Agent Loop → pi-ai → 工具 → 会话存储

稳定的循环：请求模型、执行工具、写回结果，直到给出最终答案或停止。

关键设计：把「不稳定的外部世界」和「稳定的核心循环」分开。供应商、工具、UI、扩展随时可换，核心循环保持不变。

五分钟跑起来

克隆、安装、启动——细节见快速上手。

开始使用 Pi →

常见问题

第一次了解 Pi Agent 时，先看这几个问题。

Pi Agent 适合什么人使用？

Pi Agent 适合希望自己控制模型、工具、会话和用户界面的开发者。它既可以直接作为交互式编码代理使用，也可以作为可扩展的 Agent 运行时集成到自己的应用中。

Pi Agent 支持哪些模型供应商？

Pi 通过 pi-ai 提供统一的多供应商接口，支持 OpenAI、Anthropic、Google、Bedrock、Vertex 和 Copilot 等接入方式，具体可用模型以模型供应商文档和上游仓库为准。

没有 API key 可以先学习 Pi 吗？

可以。Pi 提供 MockModel 和教学文档，可以在没有真实 API key 的情况下理解 Agent Loop、工具调用和会话状态。