Pi Agent完整教程：安装、配置、插件与社区热门扩展推荐

核心定义：Pi Agent 是 earendil-works 推出的终端编码代理，围绕 read、write、edit、bash 四个默认工具工作，并通过扩展、技能、提示模板和 Pi Packages 扩展能力。

关键事实：

@earendil-works/pi-coding-agent 的 npm 最新版为 0.85.1，发布时间为 2026-09-05。
官方快速安装支持 npm install -g --ignore-scripts @earendil-works/pi-coding-agent，也支持 curl -fsSL https://pi.dev/install.sh | sh。
Pi 的设置分为全局 ~/.pi/agent/settings.json 和项目 .pi/settings.json。
扩展文件可放在 ~/.pi/agent/extensions/ 或 .pi/extensions/，支持热重载。
Pi Packages 支持 npm、git 和本地路径安装。

适用场景：终端代码辅助、仓库改造、模型切换、团队共享扩展、长任务协作

不适合场景：只想要图形化 IDE 插件市场、只想用纯聊天机器人、不愿意管理本地配置

相关实体：Pi、earendil-works、npm、GitHub、Anthropic、OpenAI、Ollama、vLLM、LM Studio

Pi Agent 是什么

Pi Agent 是一个极简的终端编码代理。它的定位不是“全家桶式 IDE”，而是让你在当前目录里直接和模型协作，必要时再通过扩展、技能和包来加能力。

它默认只给模型四个工具：read、write、edit、bash。这意味着它更适合做真实代码工作，而不是看起来很热闹的演示。

怎么安装

最稳的安装方式是 npm：

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

也可以直接用官方安装脚本：

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

安装后进入项目目录，再启动：

cd /path/to/project
pi

卸载时按你的安装方式反向处理即可，npm 安装用 npm uninstall -g @earendil-works/pi-coding-agent。

怎么配置

Pi 的配置核心有三块：登录、模型、项目设置。

1. 登录和模型

如果你用订阅，直接在 Pi 里执行：

/login

官方支持的订阅入口包括 Claude Pro/Max、ChatGPT Plus/Pro（Codex）和 GitHub Copilot；API Key 方式也支持 Anthropic、OpenAI、DeepSeek、Gemini、OpenRouter 等多家提供方。

如果你想保存启动默认模型，可以在 /model 里选中后按 Ctrl+S。启动默认思考层级同理。

2. 全局和项目设置

Pi 的设置文件是 JSON，优先级是项目覆盖全局：

~/.pi/agent/settings.json
.pi/settings.json

一个最小配置长这样：

{
  "defaultProvider": "anthropic",
  "defaultModel": "<model-id>",
  "defaultThinkingLevel": "medium",
  "defaultProjectTrust": "ask"
}

3. 自定义模型

如果你接的是本地模型或 OpenAI 兼容服务，可以用 ~/.pi/agent/models.json：

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "compat": {
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false
      },
      "models": [
        { "id": "qwen2.5-coder:7b" }
      ]
    }
  }
}

插件怎么装

Pi 这里更准确的叫法是扩展、技能和 Pi Packages，不是传统意义上的“插件商店”。

安装包的常见方式有三种：

pi install npm:@foo/bar@1.0.0
pi install git:github.com/user/repo@v1
pi install /absolute/path/to/package

如果只是临时试用，可用：

pi -e npm:@foo/bar

扩展默认运行在完整系统权限下，装第三方包前要先看源码。

社区分享里更值得看的插件

如果按“社区里有人分享、有人安装、包页数据更活跃”来选，Pi 官方包目录的下载量比 GitHub 星标更有参考价值。按 pi.dev 包页截至 2026-09-07 的数据，可以优先看下面几类：

插件 / 包	月下载量	周下载量	适合场景	安装命令
`pi-subagents`	362.5K	122.4K	子代理、并行任务、审查、探索、后台作业	`pi install npm:pi-subagents`
`pi-memory`	37.1K	11.1K	持久记忆、决策记录、长期上下文检索	`pi install npm:pi-memory`
`@gotgenes/pi-subagents`	10K	2,670	Claude Code 风格子代理、后台代理、可视化 agent 面板	`pi install npm:@gotgenes/pi-subagents`
`pi-code`	4,004	334	把 Claude Code 的 `.claude/` 配置、skills、hooks、MCP、agents 迁到 Pi	`pi install npm:pi-code`
`@tian.zuo/pi-antigravity`	3,150	1,500	在 Pi 里使用 Antigravity / agy 模型	`pi install npm:@tian.zuo/pi-antigravity`
`@samfp/pi-memory`	1,220	317	轻量记忆、用户偏好和会话模式学习	`pi install npm:@samfp/pi-memory`
`@spikat/pi-review`	411	155	已提交分支和暂存区代码审查	`pi install npm:@spikat/pi-review`

这组清单更接近社区真实使用热度：子代理和记忆是最热的两条线，其次是把 Claude Code 工作流迁移到 Pi、接入特定模型提供方，以及代码审查类扩展。

实战流程

一个更像生产环境的流程是：

先用 pi 打开当前仓库。
用 /login 绑定模型提供方。
在 /model 里保存启动默认模型。
把项目级规则写进 .pi/settings.json 或 AGENTS.md。
需要额外能力时再装扩展包。
长任务场景用 pi -c、/resume、/fork 管理会话。

如果你是团队场景，建议再加一层项目信任控制。Pi 会区分全局信任和项目信任，没信任的目录不会自动加载本地资源和扩展。

常见坑

只设了 API Key，但没选对 provider，模型不会出现在 /model 里。
装了项目级包，却忘了信任该项目。
把扩展当成普通脚本，没意识到它拥有完整系统权限。
想用本地模型，却没处理 OpenAI 兼容服务的 developer / reasoning_effort 差异。

常见问题

Q：Pi 和传统 CLI 工具有什么区别？ Pi 更强调可扩展的代理工作流，默认工具很少，但能通过扩展、包和模型配置继续长出来。

Q：Pi 支持本地模型吗？ 支持。官方文档给了 Ollama、vLLM、LM Studio 一类 OpenAI 兼容服务的配置方式。

Q：插件和包是一回事吗？ 在 Pi 里，社区常把能扩展能力的内容统称插件，但官方更常用的词是 extensions、skills、prompt templates 和 Pi Packages。

Q：新手最该先装什么？ 先把官方 CLI 跑起来，再装一个和你模型提供方一致的 provider 包，最后再考虑记忆、协作或多机扩展。

结尾

如果你只是想快速上手，先把安装、登录和默认模型这三步跑通就够了。
如果你想把 Pi 用成长期工作台，再往下加扩展、项目设置和会话管理。

本文内容基于 2026-09-07 的官方文档、npm 版本、pi.dev 包页下载量和社区仓库信息，后续请按实际版本更新。

参考来源

官方仓库：github.com/earendil-works/pi
七牛云 AI 大模型广场：https://www.qiniu.com/ai/models