Pi Coding Agent 入门指南:轻量级开源 AI 编码代理的安装与使用
Pi Coding Agent 入门指南:轻量级开源 AI 编码代理的安装与使用
背景
2025-2026 年,AI 编码代理(Coding Agent)领域爆发式增长,Claude Code、Codex CLI、Cursor 等工具层出不穷。但这些产品化的工具都有一个共同问题:它们帮你做了太多决策——超大系统提示词、隐藏的上下文注入、无法自己控制的上下文策略。
Mario Zechner(libGDX 作者,知名游戏框架开发者)受够了 Claude Code 日益臃肿的设计,于 2026 年初发布了 Pi——一个极简的终端 AI 编码代理框架。它的设计理念非常直白:
“有很多代理框架,但这个是你自己的。”
Pi 的核心哲学:系统提示词 + 工具定义控制在 1000 tokens 以内,剩下的上下文预算全部交给你的项目。它不做决策,它只是提供你掌控一切的脚手架。
到今天,Pi 已经发展成一个完整的生态——40k+ GitHub stars,驱动着 250k+ stars 的 OpenClaw(史上增长最快的 GitHub 项目之一)。
核心概念与架构
Pi 是一个 TypeScript 单体仓库(monorepo),按依赖关系严格分层:
| 包名 | 作用 | 依赖 |
|---|---|---|
pi-ai |
统一多提供商 LLM API 层(15+ 提供商) | 无 |
pi-agent-core |
ReAct 循环核心(~200 行) | pi-ai |
pi-coding-agent |
终端编码代理 CLI | pi-agent-core + pi-tui |
pi-tui |
终端 UI 组件库 | 无 |
这种分层的意义在于:每一层都可以单独使用。你可以在自己的应用中使用 pi-ai 做批量 LLM 调用,用 pi-agent-core 嵌入 ReAct 循环,用 pi-coding-agent 作为日常编码助手。
设计哲学
- 4 个核心工具:
read、write、edit、bash。没有search_codebase、没有list_directory——用 bash 通用工具(grep -r、find .、git log)替代 - 系统提示词 ~100 tokens:
"You are an AI coding assistant. You help users with software engineering tasks. Use the provided tools to accomplish tasks." - 完全透明的上下文:所有注入上下文的内容都可在 TUI 中查看
- 可扩展而非内置功能:想加功能?写扩展,不要等核心更新
安装
通过 npm 安装(推荐)
|
|
验证安装:
|
|
通过 Ollama 安装(本地模型路径)
|
|
这会自动安装 Pi、配置 Ollama 作为提供商、添加网络搜索工具,并启动交互式会话。
macOS / Linux 安装脚本
|
|
快速上手
第一步:进入项目目录并启动
|
|
这会在你的项目目录中启动 Pi 的交互模式。
第二步:登录或配置 API Key
Pi 支持两种认证方式:
方式一:交互式登录(推荐)
在 Pi 中输入:
|
|
然后选择你需要的提供商——支持 Claude Pro/Max、ChatGPT Plus/Pro、GitHub Copilot 等订阅登录。
方式二:API Key 环境变量
|
|
Pi 支持 15+ 提供商:Anthropic、OpenAI、Google Gemini、DeepSeek、Mistral、Groq、xAI、Together AI、Hugging Face、AWS Bedrock、Azure、Ollama 等。
第三步:第一次交互
启动后输入你的第一个请求:
|
|
或者从命令行直接传递任务:
|
|
核心用法详解
1. 文件引用
使用 @ 在交互模式中引用文件,也可以从命令行传递:
|
|
2. 运行命令
Pi 支持两种命令执行方式:
|
|
! 适合让模型基于命令输出做决策,!! 适合只想在本机运行但不消耗上下文预算的场景。
3. 切换模型
在会话中切换模型:
|
|
启动时指定模型:
|
|
Pi 还支持思考级别(thinking level):
|
|
思考级别包括 off、minimal、low、medium、high、xhigh。简单任务用低级别,复杂推理用高级别。
4. 会话管理
Pi 将会话保存为 JSONL 树形结构,支持分支:
|
|
内部会话命令:
|
|
5. 上下文压缩(Compaction)
长时间会话会填满上下文窗口。Pi 的压缩机制会自动将旧消息替换为摘要,使用廉价模型(如 Haiku)完成:
|
|
压缩阈值可在设置中配置。
项目配置实战
创建 AGENTS.md
在项目根目录创建 AGENTS.md,设置 Pi 的行为规则:
|
|
Pi 会自动加载 AGENTS.md、CLAUDE.md 或项目根目录下的 SYSTEM.md。修改后执行 /reload 重新加载。
配置 settings.json
项目级设置 .pi/settings.json:
|
|
四运行模式
Pi 不止是终端 TUI,它有四种运行模式:
| 模式 | 命令/API | 使用场景 |
|---|---|---|
| 交互式 | pi |
日常编码 |
| Print/JSON | pi -p "query"、--mode json |
脚本、CI 钩子、事件流 |
| RPC | 基于 stdin/stdout 的 JSONL | 编辑器、仪表盘、非 Node 集成 |
| SDK | 在 Node 中直接导入 | 嵌入应用(如 OpenClaw) |
SDK 模式示例:嵌入到自己的应用
|
|
OpenClaw 就是用这个模式嵌入 Pi,构建了多平台(WhatsApp、Telegram、Slack、Discord 等)的个人 AI 助手。
扩展系统(Extensions)
扩展是 TypeScript 文件,通过 jiti 运行时加载(无需构建步骤)。编辑后输入 /reload 即可热重载。
基础扩展示例
|
|
自扩展能力
Pi 最强大的特性:Agent 可以自己写扩展并热重载。工作流:
- 描述需求:“我需要一个
/deploy命令来运行部署流水线” - Pi 编写扩展
.ts文件 - 输入
/reload - 测试新命令
- 如果出错,Pi 读取错误、修复代码、重载、重试
知名 Python 开发者 Armin Ronacher(Flask 和 Jinja2 作者)评价:“像黏土一样可塑的软件。” 他所有的 Pi 扩展(
/answer、/todos、/review、/files)都是 Pi 自己写的。
Skills 技能系统
Pi 实现了 agentskills.io 开放标准,技能包在 Pi、Claude Code、Codex CLI 之间可移植。
创建技能
|
|
安装社区技能包
|
|
使用 -l 标志安装为项目本地包。
实战案例 1:日常开发工作流
以下是一个完整的日常开发会话示例:
|
|
会话流程:
|
|
实战案例 2:代码审查
|
|
使用 --tools read,grep,find,ls 限制为只读工具,确保审查过程中 Agent 不会修改代码。
实战案例 3:多模型协作
Pi 支持在同一会话中切换提供商:
|
|
在交互式会话中,可以直接使用 /model 切换:
|
|
实战案例 4:建立完整的项目配置文件
下面是一个生产级项目的完整 Pi 配置:
|
|
提示词模板示例 (.pi/prompts/pr-description.md):
|
|
在 Pi 中可以直接通过 /pr-description 触发此模板。
与 Claude Code 对比
| 特性 | Pi | Claude Code |
|---|---|---|
| 开源 | 是 (MIT) | 否 |
| 系统提示词 | ~100 tokens | ~10,000 tokens |
| 提供商支持 | 15+ | Anthropic 为主 |
| 核心工具数 | 4 | 20+ |
| 扩展机制 | TypeScript 扩展 | 有限 |
| 会话树 | 支持(分支) | 线性 |
| 运行模式 | 4 种 | 交互式为主 |
| SDK 嵌入 | 支持 | 不支持 |
| 技能系统 | 开放标准 | 私有 |
常见问题
Pi 和 OpenClaw 是什么关系?
OpenClaw 是构建在 Pi SDK 之上的多平台 AI 助手(支持 WhatsApp、Telegram、Slack 等),由 Peter Steinberger 开发。它是 Pi SDK 模式的旗舰案例,也是 GitHub 上增长最快的项目之一。
是否支持本地模型?
支持。通过 Ollama 集成可以一键启动:ollama launch pi。或者在 models.json 中配置 Ollama 或其他 OpenAI 兼容的本地推理端点(如 vLLM)。
Pi 的性能表现如何?
Pi 在 Terminal-Bench 2.0 上与 Claude Code、Codex、Cursor 等产品抗衡,但只用了 <100 tokens 的系统提示词和 4 个工具。其创始人认为,前沿模型已经在训练数据中充分了解了编码代理的运作模式,不需要框架教它们怎么做。
能否在 CI/CD 中使用?
可以。使用 Print/JSON 模式 (pi -p "task" --mode json) 或 RPC 模式可以嵌入脚本流水线。同时可以用 --tools 限制只读操作,适合安全审查。
如何在不同提供商之间切换?
使用 /model 或在启动时指定 --provider 和 --model。Pi 的上下文接力(Context Handoff)功能能在不同提供商之间序列化会话状态——包括思维链、工具调用结果等——在切换模型时完整保持上下文。
总结
Pi 代表了一种与主流 AI 编码代理不同的设计思路:极简核心 + 最大扩展性。
- 如果你只需要一个"开箱即用"的编码助手,Pi 的默认体验已经很流畅
- 如果你希望完全掌控上下文策略和工作流,Pi 的扩展、技能、设置系统给了你所有必要的工具
- 如果你想在自己的应用里嵌入 AI Agent 能力,Pi 的 SDK 模式是最轻量的选择
Pi 的核心理念值得记住:框架的责任是让路,而不是指路。
