earendil-works/pi · 上手攻略
- 仓库：earendil-works/pi
- 链接：https://github.com/earendil-works/pi
- 分类：ai-tooling
- 作者：Tom
- 更新：2026-08-17
是什么
pi 是由 earendil-works 开发的轻量级终端 AI Agent 工具包，包含四个核心 npm 包：
| 包 | 说明 |
|---|---|
@earendil-works/pi-coding-agent |
交互式编码 Agent CLI |
@earendil-works/pi-agent-core |
Agent 运行时（工具调用 + 状态管理） |
@earendil-works/pi-ai |
统一多提供商 LLM API（OpenAI/Anthropic/Google 等） |
@earendil-works/pi-telemetry |
供应商中立的遥测合约与参考适配器 |
官方文档：https://pi.dev | Discord：https://discord.com/invite/3cU7Bz4UPx
Stars 82,886，属于高影响力开源 Agent 工具类项目。
解决什么问题
- Coding Agent 门槛高：Claude Code / Cursor 等工具功能强大但绑定特定生态 → pi 提供与工具无关的轻量 harness
- 多 LLM 提供商切换繁琐：项目用 Anthropic，部署想换 Google，测试要换本地模型 → 统一 API 层解决
- Agent 运行时重复造轮子：每个团队都要自己写工具调用循环、状态管理、会话管理 → pi-agent-core 提供可复用运行时
- 本地模型集成难：想跑 llama.cpp 但没有顺手工具 → 内置
/llama命令管理本地 router
快速安装
方式一：npm 全局安装（推荐）
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
# 启动
cd /path/to/your/project
pi
--ignore-scripts 跳过生命周期脚本（pi 本身不需要安装脚本）。
方式二：curl 安装脚本（Linux/macOS）
curl -fsSL https://pi.dev/install.sh | sh
卸载
# npm 安装的用 npm 卸载
npm uninstall -g @earendil-works/pi-coding-agent
# pnpm
pnpm remove -g @earendil-works/pi-coding-agent
# yarn
yarn global remove @earendil-works/pi-coding-agent
# bun
bun uninstall -g @earendil-works/pi-coding-agent
⚠️ 卸载后 ~/.pi/agent/ 下的 settings、credentials、sessions 和已安装的 pi packages 不会自动清除，需手动删除。
核心用法
首次启动与认证
pi
# 交互式登录（订阅制 Provider）
/login
# 或直接设置 API Key 环境变量
export ANTHROPIC_API_KEY=sk-ant-...
pi
基础交互
# 在项目目录启动后，直接输入请求
Summarize this repository and tell me how to run its checks.
# 默认提供 4 个工具：read / write / edit / bash
文件引用（@ 语法）
# 模糊搜索文件并引用
pi @README.md "Summarize this"
# 多文件引用
pi @src/app.ts @src/app.test.ts "Review these together"
粘贴图片或文本
交互模式下按 Ctrl+V（macOS Alt+V）粘贴图片或文本，支持拖拽图片到终端。
快捷键参考
| 操作 | 快捷键 |
|---|---|
| 切换模型 | /model 或 Ctrl+L |
| 切换思维级别 | Shift+Tab |
| 循环 scoped 模型 | Ctrl+P / Shift+Ctrl+P |
| 运行 shell 命令（输出发给模型） | !<command> |
| 运行命令（不追加到上下文） | !!<command> |
会话管理
pi -c # 继续最近一次会话
pi -r # 浏览历史会话
pi --name "my task" # 启动时命名会话
pi --session <path|id> # 打开指定会话
# 交互式会话内命令
/resume # 恢复
/new # 新建
/tree # 查看会话树
/fork # 分叉
/clone # 克隆
/reload # 重新加载上下文文件
非交互模式（单次请求）
# 单次提示
pi -p "Summarize this codebase"
# 管道输入
cat README.md | pi -p "Summarize this text"
# 图片理解
pi -p @screenshot.png "What's in this image?"
# JSON 事件流输出
pi -p "Summarize this" --mode json
# RPC 模式（进程集成）
pi -p "Summarize this" --mode rpc
llama.cpp 本地模型
# 在 pi 交互式会话内
/llama
pi 支持通过 /llama 命令管理本地 llama.cpp router 和模型。
支持的 LLM 提供商
pi 的 @earendil-works/pi-ai 包支持极为广泛的 Provider 列表，分为订阅制和API Key两类：
订阅制 OAuth（通过 /login）：
- ChatGPT Plus/Pro（Codex）— OpenAI 官方推荐
- Claude Pro/Max — Anthropic 官方
- GitHub Copilot — VS Code 内置方式
- xAI（Grok/X）
- OpenRouter（OAuth）
- Radius
API Key / 环境变量（部分列表）：
| Provider | 环境变量 |
|---|---|
| Anthropic | ANTHROPIC_API_KEY |
| OpenAI | OPENAI_API_KEY |
| Google Gemini | GEMINI_API_KEY |
| DeepSeek | DEEPSEEK_API_KEY |
| NVIDIA NIM | NVIDIA_API_KEY |
| Amazon Bedrock | AWS_BEARER_TOKEN_BEDROCK |
| Groq | GROQ_API_KEY |
| Cerebras | CEREBRAS_API_KEY |
| Cloudflare AI | CLOUDFLARE_API_KEY |
| Hugging Face | HF_TOKEN |
| Fireworks | FIREWORKS_API_KEY |
| Together AI | TOGETHER_API_KEY |
| MiniMax | MINIMAX_API_KEY |
| Kimi For Coding | KIMI_API_KEY |
| 小米 MiMo | XIAOMI_API_KEY |
| Qwen Token Plan | QWEN_TOKEN_PLAN_API_KEY |
| OpenCode | OPENCODE_API_KEY |
完整列表以官方文档 https://pi.dev/docs/latest/providers 为准。
扩展与自定义
Agent Skills
# pi 交互式内安装 skills
# 具体命令需参考官方文档 /skills 页面
扩展开发（TypeScript）
pi 支持 TypeScript 扩展： - Tools（工具） - Commands（命令） - Events（事件） - Custom UI（TUI 组件）
文档：https://pi.dev/docs/latest/extensions
Pi Packages
打包并分享扩展、skills、prompts、themes 的方式： 文档：https://pi.dev/docs/latest/packages
Prompt Templates
可从 slash 命令展开的复用提示词模板： 文档：https://pi.dev/docs/latest/prompt-templates
安全注意
⚠️ pi 默认无内置权限系统：它以启动它的用户和进程权限运行，可以读写文件系统、执行命令、访问网络凭证。不要对不可信输入直接运行 pi。
建议隔离方案（文档推荐三种模式）：
- Gondolin 扩展：将 pi 和 Provider 认证保留在宿主机，工具和
!命令路由进本地 Linux 微 VM（适合需要认证但又要隔离工具的场景） - Plain Docker：整个 pi 进程跑在本地容器（简单隔离）
- OpenShell：整个 pi 进程跑在策略控制的沙箱中（最高隔离级别）
文档：https://pi.dev/docs/latest/containerization
典型适用场景
| 场景 | 适合度 |
|---|---|
| 在已有项目中使用 Claude Code/Windsurf 等之外的轻量 Agent | ⭐⭐⭐⭐⭐ |
| 统一管理多个 LLM 提供商 API | ⭐⭐⭐⭐⭐ |
| 自定义 Agent 运行时（不想自己写工具调用循环） | ⭐⭐⭐⭐ |
| 本地 llama.cpp 模型与云端模型混合使用 | ⭐⭐⭐⭐ |
| 团队需要标准化 Agent 开发框架 | ⭐⭐⭐ |
| 简单代码补全（建议用 IDE 插件） | ⭐⭐ |
坑与注意
⚠️ 无内置持久化权限控制：需要自己做好进程隔离，对于有安全要求的场景必须配合 Docker 或 Gondolin。
⚠️ 不是 IDE 插件：pi 是终端工具，不提供 IDE 内联补全；如果你想要 IDE 内补全，用 Cursor/Windsurf/VSCode Copilot。
⚠️ API Key 需要自己管理：订阅制 Provider 可 OAuth 登录，但 API Key 方式需要自己配置 .env 或 ~/.pi/agent/auth.json。
⚠️ Bun 作为构建工具：pi 的构建系统使用 Bun（monorepo 根目录 bun.lockb），开发时需要安装 Bun。
⚠️ LLM 相关测试需要 API Key：./test.sh 会跳过不需要 API Key 的测试，但完整测试覆盖需要配置 key。
⚠️ session 数据默认保存在 ~/.pi/agent/sessions/，每次 pi -c 读取最新会话，session 文件是 JSONL 格式。
⚠️ 非中文项目：pi.dev 文档和项目 README 为英文，中文资料较少。
与同类对比
| 工具 | 类型 | Stars | 特点 |
|---|---|---|---|
| pi | Agent CLI + Runtime | 82K | 最广 Provider 覆盖、最轻量核心 |
| Claude Code | Agent CLI | 官方 | 绑定 Anthropic、工具链完整 |
| OpenAI Codex | Agent CLI | 官方 | 绑定 OpenAI |
| Aider | Agent CLI | ~9K | 纯 Python、轻量、专注编辑 |
| ** Goose** | Agent CLI | 活跃 | 国产、多 Provider 支持 |
pi 的核心优势：最广 LLM Provider 覆盖 + 最小的核心运行时。如果你想用 Gemini 跑 coding agent 测试，同时想兼容 Anthropic 作为备选，pi 是目前门槛最低的方案。
一句话推荐结论
pi 是追求Provider 无关和工具链轻量化的开发者的最佳选择——对已有 Claude Code/Cursor 生态的用户来说迁移成本有限，但对需要跨多个 LLM 服务或自建 Agent 框架的团队来说，pi-agent-core 是目前最值得研究的开源运行时实现之一。