Pi Agent 使用指南：GitHub 9 万 Star 的极简开源编程智能体，一条命令让 AI 帮你写代码

行走的陀螺仪

600人浏览 · 2026-08-16 09:39:04

行走的陀螺仪 · 2026-08-16 09:39:04 发布

Pi Agent 使用指南：GitHub 9 万 Star 的极简开源编程智能体，一条命令让 AI 帮你写代码

厌倦了又贵又重、被单一厂商锁死的 AI 编程工具？本文带你 10 分钟上手 Pi Agent——一个"小而美"的开源终端编程智能体：不绑定任何模型厂商、核心极简、想加什么功能自己装。

一、背景：AI 编程工具很火，但为什么你还没用爽？

这两年 AI 编程工具爆发式增长：Cursor、Claude Code、GitHub Copilot、Windsurf……" vibe coding "（氛围编程）已经从概念变成了很多程序员的日常。你用自然语言描述需求，AI 直接帮你读代码、改代码、跑命令、修 Bug。

但真正用起来，很多开发者会遇到这几类问题：

痛点	具体表现
厂商锁定	用 Claude Code 只能方便地用 Anthropic 的模型，想换成 GPT、Gemini、DeepSeek 就很折腾
订阅/价格贵	一款工具一份订阅，模型 API 一份钱，钱包遭不住
黑盒、难定制	想改改工作流、加个自己的小工具？对不起，闭源产品你说了不算
越做越重	内置了一堆你可能永远用不上的功能（子智能体、计划模式、弹窗确认……），核心反而不够专注
隐私顾虑	代码要传到别人的云端处理，企业场景直接被劝退

于是社区一直在等一个"返璞归真"的工具：核心足够小、足够透明，但想扩展时随手就能扩展。

2025 年 8 月，libGDX 游戏框架作者、开源老兵 Mario Zechner（GitHub ID：badlogic）开源了他的答案——Pi。一年时间，它在 GitHub 上拿下了 超过 9 万 Star（截至 2026 年 8 月），成为最火的开源编程智能体之一。

🏠 官网：https://pi.dev
📦 代码仓库：https://github.com/badlogic/pi-mono
📄 协议：MIT（随便用，商用也行）

二、Pi Agent 是什么？它解决了什么问题？

2.1 一句话介绍

Pi 是一个运行在终端里的极简编程智能体（Coding Agent）：你用大白话提需求，它会自己读文件、写代码、改代码、执行命令，直到把活干完。它是开源的，不绑定任何 AI 模型厂商，并且设计哲学是"让 Pi 适应你的工作流，而不是让你适应它"。

名字 π（Pi）本身就体现了它的定位：像圆周率一样简单、纯粹、无限延展。

2.2 Pi 如何逐个击破上面那些痛点

你的痛点	Pi 的答案
厂商锁定	内置 30 多家模型接入方式：Claude、GPT、Gemini、DeepSeek、Kimi、MiniMax、xAI、OpenRouter……甚至支持本地 llama.cpp 跑开源模型，`/model` 一键切换
太贵	直接复用你已有的订阅！Claude Pro/Max、ChatGPT Plus/Pro、GitHub Copilot 订阅都能登录使用，不用额外付订阅费；也可以用各家 API Key 按量付费
黑盒难定制	完全开源（MIT）。用 TypeScript 写几行代码就能给它加自定义工具、命令、界面组件；不想写代码？社区有大量现成的 Pi 包，`pi install` 一条命令装上
功能堆砌	Pi 刻意不内置子智能体、计划模式、任务清单、弹窗审批这些"大而全"的功能——核心只保留最必要的部分，其他全部做成可选扩展
隐私顾虑	完全本地运行、开源自查代码，模型调用走你自己的 Key/订阅；还有离线模式（`--offline`）

2.3 它的工作原理（一分钟看懂）

Pi 本质上是一个"Agent 循环 + 终端界面"：

你输入一句自然语言，比如"帮我修复登录页面的这个 Bug"；
Pi 把请求发给 AI 模型，模型默认只有 4 个工具可用：
- read：读文件
- write：写文件
- edit：改文件
- bash：执行终端命令（跑测试、装依赖、git 提交……）
模型自主决定"读哪个文件 → 怎么改 → 跑什么命令验证"，循环往复直到任务完成；
全程你都能在终端里看到它每一步干了什么，随时可以打断、补充指令。

就这么简单。大道至简，四个工具足以完成绝大多数编程任务，这也是它能保持轻量的关键。

三、快速上手：10 分钟跑起来

3.1 环境要求

Node.js（建议使用较新的 LTS 版本）
Windows 用户需要额外装一个 Git for Windows（Pi 在 Windows 上需要 bash 环境，装完 Git 自带，无需别的操作）

⚠️ Windows 小贴士：Pi 会按顺序寻找 bash：① ~/.pi/agent/settings.json 里配置的 shellPath ② Git Bash（C:\Program Files\Git\bin\bash.exe）③ PATH 里的 bash。绝大多数人装个 Git for Windows 就够了。

3.2 安装（二选一）

方式一：npm 全局安装（推荐）

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

--ignore-scripts 会跳过依赖的安装脚本，普通安装完全不需要这些脚本，更安全。

方式二：官方一键脚本

curl -fsSL https://pi.dev/install.sh | sh

装完验证一下：

pi -v

3.3 配置模型：两种方式任选

方式 A：用你已有的订阅（零额外费用）

pi

启动后输入 /login，选择服务商登录即可。目前支持：

Anthropic Claude Pro / Max
OpenAI ChatGPT Plus / Pro（Codex）
GitHub Copilot

方式 B：API Key（按量付费）

# 以 Anthropic 为例
export ANTHROPIC_API_KEY=sk-ant-xxxxxx

# 国内用户常用的 DeepSeek
export DEEPSEEK_API_KEY=sk-xxxxxx

pi

也可以启动后在终端里 /login，从 30 多个服务商列表里选（DeepSeek、Kimi、MiniMax、小米 MiMo、xAI、Groq、OpenRouter、Together……应有尽有，甚至还有 llama.cpp 本地模型）。

3.4 第一次对话

进入项目目录，敲：

cd 你的项目
pi

然后直接说人话就行：

> 帮我看看这个项目是干嘛的，先总结一下目录结构

Pi 会自己去找文件、读代码，然后给你一份总结。再来一个实际的：

> src/utils/date.ts 里有个格式化函数有 Bug，2 月份会算错，
> 修一下，并且补一个单元测试，跑通给我看

你会看到它：read 读源码 → edit 修 Bug → write 写测试 → bash 跑测试 → 全绿后告诉你结果。

恭喜，你已经会用 Pi 了！ 下面这些内容，是用熟之后的进阶技巧。

四、日常使用核心技巧

4.1 输入框里的三个魔法符号

符号	作用	示例
`@`	模糊搜索并引用项目文件	输入 `@App.tsx` 把文件带给 AI
`!`	直接执行 shell 命令，输出发给 AI	`!npm test`
`/`	打开命令面板	`/model`、`/resume`……

还有两个高频操作：

粘贴图片：Ctrl+V（Windows 终端是 Alt+V），可以把报错截图、设计稿直接丢给 AI 看；
换行：Shift+Enter；按 Ctrl+G 可以把输入框切换到外部编辑器（如记事本）写长需求。

4.2 常用命令速查表

命令	作用
`/model`	切换模型（快捷键 Ctrl+L）
`/login` `/logout`	登录/退出服务商
`/resume`	从历史会话中恢复
`/new`	开一个新会话
`/tree`	会话树：回到任意历史节点重开分支（后悔药）
`/compact`	手动压缩上下文，长会话省钱省 token
`/settings`	图形化设置（思考等级、主题等）
`/export`	把会话导出成 HTML/JSONL
`/share`	上传成私密 GitHub Gist，生成可分享链接
`/hotkeys`	查看全部快捷键

4.3 会话管理：像 Git 一样"分支开发"

Pi 的会话保存为 JSONL 文件（按项目目录归档在 ~/.pi/agent/sessions/），而且是树形结构：

聊到一半发现方向不对？按两次 Esc 打开 /tree，回到任意一条历史消息，从那里重新开始——所有历史都保留，一个文件搞定；
pi -c 继续最近一次会话；pi -r 浏览挑选历史会话；
/fork 从某条消息分叉出一个全新会话文件，放心大胆做实验。

4.4 让 Pi 记住你的项目规矩：AGENTS.md

在项目根目录建一个 AGENTS.md（也兼容 CLAUDE.md），写上你的约定，Pi 每次启动都会自动加载：

# 项目约定
- 本项目使用 pnpm，不要用 npm
- 组件写在 src/components，每个组件一个文件夹
- 提交信息用中文，遵循 Angular 规范

家里/公司全局约定也可以写在 ~/.pi/agent/AGENTS.md。

4.5 脚本化使用（非交互模式）

Pi 不只是聊天工具，也能塞进脚本和流水线：

# 一次性提问，输出结果就退出（-p = print 模式）
pi -p "总结一下这个代码库的架构"

# 管道：把 README 喂给它总结
cat README.md | pi -p "把这段文档翻译成英文"

# 只读模式：只许看不许改，安全审查代码
pi --tools read,grep,find,ls -p "审查这个项目的安全问题"

# 直接指定模型和思考强度
pi --model sonnet:high "解决这个复杂的并发问题"

五、进阶：把 Pi 调教成你自己的专属 Agent

这是 Pi 最有魅力的部分。它提供四层定制能力，按需取用，不碰代码也能玩：

5.1 提示词模板（Prompt Templates）——懒人必备

把常用的提示词存成文件，以后 /名字 一键展开。

<!-- ~/.pi/agent/prompts/review.md -->
帮我审查代码，重点关注：{{focus}}

在 Pi 里输入 /review，会自动展开并把光标停在 focus 处让你补充。

5.2 技能（Skills）——给 AI 的"操作手册"

一个技能就是一个 Markdown 文件夹（遵循开放的 Agent Skills 标准），描述"遇到某类任务该怎么做"。模型按需自动加载，也可以 /skill:名字 手动调用。比如写一个"发布流程"技能，把公司发版的十几个步骤写清楚，以后说一句"发个版"，AI 就照着手册执行。

5.3 扩展（Extensions）——程序员的主场

用 TypeScript 写几行代码，就能给 Pi 增加自定义工具、命令、快捷键，甚至替换整个编辑器界面：

export default function (pi) {
  pi.registerTool({ name: "deploy", /* ... */ });
  pi.registerCommand("stats", { /* ... */ });
  pi.on("tool_call", async (event, ctx) => { /* ... */ });
}

社区已经用它实现了：MCP 支持、子智能体、计划模式、Git 自动提交、SSH/沙箱执行、权限审批弹窗……甚至有人跑了个 Doom（毁灭战士）在等待 AI 时玩游戏 😄。

5.4 Pi 包（Pi Packages）——一条命令装别人造好的轮子

# 从 npm 安装社区扩展包
pi install npm:@foo/pi-tools

# 从 GitHub 装
pi install git:github.com/user/repo

# 管理
pi list          # 看装了什么
pi update --all  # 全部更新
pi remove npm:@foo/pi-tools

在 npm 上搜索 pi-package 关键词就能找到大量现成的扩展包。

⚠️ 安全提醒：Pi 包拥有完整系统权限（可以执行任意代码），安装第三方包前请先审查源码，只装信得过的。

5.5 四种运行模式

模式	用法	场景
交互模式	`pi`	日常开发
Print 模式	`pi -p "..."`	脚本/CI 里一次性调用
JSON 模式	`pi --mode json`	事件流输出，方便程序解析
RPC 模式	`pi --mode rpc`	跨语言进程集成（stdin/stdout 上的 JSONL 协议）