快速上手

最后更新：2026-10-10

本章带你在本地把 Pi 跑起来：安装依赖、构建、启动编码代理，并理解一次最小运行的调用链路。

前置检查：需要 Node.js 18+、npm 和 Git。动手前先确认：

node -v  # 应 ≥ v18
npm -v
git --version

1. 获取源码

git clone https://github.com/earendil-works/pi.git
cd pi

2. 安全安装依赖

Pi 采用 npm workspaces 单仓管理。为避免依赖的生命周期脚本执行不可信代码，官方推荐始终加上 --ignore-scripts：

# 开发安装
npm install --ignore-scripts

# CI 安装
npm ci --ignore-scripts

供应链加固：依赖精确锁定，package-lock.json 为真相源；本地安装、文档安装、pi update --self 都尽可能使用 --ignore-scripts。

3. 构建与检查

npm run build   # 构建所有包
npm run check   # lint + 格式化 + 类型检查

构建成功后各包会生成 dist/ 目录。npm run check 若报错，先看运行与调试的排错部分，不要硬跳过去。

4. 启动编码代理 CLI

pi-coding-agent 是交互式编码代理，进入仓库后即可像结对程序员一样让它读代码、改文件、跑命令：

# 从源码运行（可从任意目录调用）
./pi-test.sh

# 运行测试（无 API key 时自动跳过依赖 LLM 的用例）
./test.sh

要用真实模型？先去模型供应商配置 API Key（以 OpenAI 为例）：

export OPENAI_API_KEY="sk-..."

没有 Key 也不影响：用 MockModel 照样能跑通下面的最小循环，先理解机制再接真模型。

验证一下：在代理会话里输入"用一句话介绍当前目录是做什么的"。如果返回了合理结果，说明模型已接通 ✅。不想花真实 token 的话，把模型切到 MockModel，它会在本地模拟回复，照样跑通工具与循环逻辑。

5. 最小 Agent 循环

Pi 的核心是一个稳定的循环：准备上下文 → 请求模型 → 处理工具 → 写回结果 → 继续或停止。下面是一段示意调用链：

UI→ API→ Session→ AgentLoop→ Model→ Tool

UI      → POST /api/runs
API     → 返回 runId，建立 SSE 事件流
Session → 写入用户消息、构建上下文
Loop    → model.complete(messages, tools)
Model   → 返回 toolCall: read_file
Tool    → 执行并返回结果
Loop    → 再次请求模型，直至最终答案
API     → SSE 推送 AgentEvent + 完整会话

下一步

想看整体设计，去总体架构。
想了解各包职责，去核心包。
想本地调试，去运行与调试。

常见问题

安装 Pi Agent 前需要什么环境？

建议准备 Node.js 18 或更高版本、npm 和 Git。安装依赖时建议使用 npm install --ignore-scripts，以减少不必要的生命周期脚本执行。

Pi Agent 如何启动？

获取源码后执行 npm install --ignore-scripts、npm run build，再使用项目提供的 pi-test.sh 启动交互式编码代理。真实模型调用还需要配置对应供应商的 API key。

没有 API key 能否跑通安装后的示例？

可以。没有 API key 时可以先使用 MockModel 理解最小 Agent 循环；需要调用真实模型时，再按照模型供应商文档配置密钥。