文档核验 2026-08-12 · 待自动实测

Pi（earendil-works/pi）

一句话定位：开源（MIT）的极简终端编码 Agent Harness，TypeScript 实现、provider 无关、BYOK（自带 Key）。一个 CLI 可对接 15+ 大模型厂商（Anthropic / OpenAI / Google / DeepSeek / Ollama / OpenRouter 等），靠扩展（extensions）、技能（skills）、提示词模板、主题自定工作流。 适用场景：想要"不被单一厂商绑定"的终端编码 Agent；需要多模型随时切换（/model）；想自己写扩展定制工具/命令/UI；跑本地模型（Ollama）或国产模型（DeepSeek）规避网络限制。

一、前置依赖

系统：macOS / Linux / Windows（原生 PowerShell 或 WSL2 均可）
Node.js 22 及以上（官方文档要求 22.19+；具体以 https://pi.dev/docs/latest 为准），建议先 node --version 确认
稳定网络（用于 npm 拉包；模型调用见"国内环境坑"）
模型凭据：二选一——① 订阅登录（pi /login，支持 Claude Pro/Max、ChatGPT Plus/Pro、GitHub Copilot）；② API Key（如 ANTHROPIC_API_KEY、OPENAI_API_KEY、DEEPSEEK_API_KEY 等环境变量）

二、安装步骤

macOS / Linux / WSL

方式 A（官方推荐，npm 全局，禁用依赖生命周期脚本）：

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

--ignore-scripts 是官方文档明确要求的，禁用安装期依赖脚本；Pi 正常安装不需要这些脚本。

方式 B（官方安装脚本）：

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

Windows（原生 PowerShell）

官方提供 PowerShell 安装器：

powershell -c "irm https://pi.dev/install.ps1 | iex"

WSL2 用户走上方 macOS/Linux 的 npm / curl 方式即可。

其他包管理器（任选）

pnpm add -g @earendil-works/pi-coding-agent
yarn global add @earendil-works/pi-coding-agent
bun add -g @earendil-works/pi-coding-agent

卸载：

npm uninstall -g @earendil-works/pi-coding-agent

三、最小可用配置

进入任意项目目录启动：

cd your-project
pi

首次启动会进入交互式 TUI。认证二选一：

pi /login          # 交互式选择订阅厂商（Claude Pro/Max、ChatGPT Plus/Pro、GitHub Copilot）

或启动前导出一个 API Key：

export ANTHROPIC_API_KEY=sk-ant-...     # 也可 OPENAI_API_KEY / DEEPSEEK_API_KEY / GOOGLE_API_KEY ...
pi

会话内随时切换模型：/model 或 Ctrl+L；循环收藏模型 Ctrl+P。

验证安装（能进入交互界面即成功）：

pi --version     # 查看版本；或直接输入 pi 进入 TUI

四、国内环境坑

海外模型 Key 受限：Anthropic / OpenAI / Google 等官方 API 在国内常需代理或海外环境。Pi 是 provider 无关设计，优先接国产 / 本地模型更稳——已内置支持 DeepSeek、Ollama（本地）、OpenRouter、Kimi For Coding、MiniMax、NVIDIA 等；用对应的 Key 或本地 Ollama 即可，不必直连海外厂商。
Node 版本：低于 22 会安装/运行异常，先用 nvm 升到 22：

nvm install 22 && nvm use 22

npm 拉包慢：可临时切换国内镜像（不影响 Pi 本身，仅加速 npm）：

npm install -g --ignore-scripts @earendil-works/pi-coding-agent --registry=https://registry.npmmirror.com

Windows 原生：用上面的 PowerShell 安装器；若用 npm 全局安装，确保 PowerShell 执行策略允许（Set-ExecutionPolicy -Scope CurrentUser RemoteSigned）。

五、常见报错 → 解决

现象	解决
`pi: command not found`	重载 shell（`source ~/.zshrc` / 重开终端）；确认 npm 全局 bin 在 PATH：`npm bin -g` 并把该路径加入 PATH
Node 版本过低 / 报错	`nvm install 22 && nvm use 22`，重开终端
npm 全局权限问题（EACCES）	`mkdir ~/.npm-global && npm config set prefix '~/.npm-global'`，并把 `~/.npm-global/bin` 加入 PATH
模型调用失败 / 401	核对对应 Provider 的 API Key、Base URL、模型名；国内直连海外厂商需代理，或换 DeepSeek / Ollama / OpenRouter
想限制工具权限	用容器 / 沙箱运行（官方文档有 Gondolin / Docker / OpenShell 方案），不要在高权限宿主机直接跑不受信任任务

六、实测状态

🟡 文档核验（2026-08-12）：安装命令与步骤取自 Pi 官方文档（pi.dev）与仓库 README，尚未在本机沙箱实跑验证。后续由站点 CI 定时实跑并更新徽章。

七、官方链接

官网 / 文档：https://pi.dev · https://pi.dev/docs/latest
快速开始：https://pi.dev/docs/latest/quickstart
Provider / 认证（订阅与 Key）：https://pi.dev/docs/latest/providers
Windows 专项：https://pi.dev/docs/latest/windows
源码仓库（MIT）：https://github.com/earendil-works/pi

踩坑交流 / 1v1 配置，加微信 hhummingg