Pi Agent 快速上手教程以及扩展推荐

2026-09-01笔记约 2667 字9 分钟1

1. Pi 是什么

Pi 是一个轻量、可扩展的终端编程代理。它默认提供文件读取、写入、编辑和 Shell 执行能力，并通过扩展、技能、提示模板和主题来适配不同的开发工作流。

Pi 类似 Claude Code / Codex / OpenCode 的 Coding Agent，但更精简更轻量。

Pi 的核心保持精简，不强制内置 SubAgent、Plan、MCP 等复杂能力，而是允许用户根据自己的需求安装对应的扩展或自行定制。这种设计使 Pi 更适合有一定开发基础、希望掌控工作流的用户。

2. 安装 Pi

环境要求

Node.js；
npm；

npm 安装

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

安装完成后验证：

pi --version
pi --help

启动 Pi：

pi

3. 配置模型与登录

3.1 使用订阅登录

启动 Pi 后执行：

/login

然后选择对应的服务商并完成登录。Pi 支持 Anthropic Claude、OpenAI Codex、GitHub Copilot 等订阅服务，具体可用 Provider 以当前版本为准。

模型选择：

/model

3.2 使用 `models.json`

models.json 用于添加或覆盖自定义 Provider 和模型配置，文件位置为：

~/.pi/agent/models.json

通用模板如下：

{
  "providers": {
    "my-provider": {
      "baseUrl": "https://api.example.com/v1",
      "api": "openai-responses",
      "apiKey": "YOUR_API_KEY",
      "models": [
        {
          "id": "model-id",
          "name": "My Model",
          "reasoning": true
        },
        {
          "id": "another-model-id",
          "name": "Another Model",
          "reasoning": false
        }
      ]
    }
  }
}

常见字段：

字段	说明
`baseUrl`	Provider 的 API 地址
`api`	使用的 API 类型，例如 `openai-completions` ,`openai-responses`,`anthropic-messages`
`apiKey`	API Key
`models[].id`	服务商实际使用的模型 ID
`models[].name`	Pi 中显示的模型名称
`reasoning`	是否支持推理/思考等级

如果使用多个 Provider，可以继续在 providers 下添加配置：

{
  "providers": {
    "provider-a": {
      "baseUrl": "https://a.example.com/v1",
      "api": "openai-responses",
      "apiKey": "YOUR_KEY_A",
      "models": [
        {
          "id": "model-a",
          "name": "Model A",
          "reasoning": true
        }
      ]
    },
    "provider-b": {
      "baseUrl": "https://b.example.com/v1",
      "api": "openai-completions",
      "apiKey": "YOUR_KEY_B",
      "models": [
        {
          "id": "model-b",
          "name": "Model B",
          "reasoning": false
        }
      ]
    }
  }
}

修改 models.json 后重新启动 Pi，或执行：

/reload

4. 使用 Pi

Pi 的基本使用方式是直接用自然语言描述任务：

pi

阅读当前项目，分析目录结构并总结主要模块。

检查最近修改的代码，找出潜在问题并运行测试。

实现这个功能，并在修改后执行相关测试。

常用启动方式：

pi "检查当前项目"
pi -p "总结当前项目"
pi -c                    # 继续最近会话
pi -r                    # 选择历史会话
pi --no-session          # 不保存会话

文件引用：

pi @README.md "总结这份文档"
pi @src/index.ts "检查这段代码"

常用交互命令：

/model       # 选择模型
/thinking    # 调整思考等级
/new         # 新建会话
/resume      # 恢复会话
/tree        # 查看会话树
/compact     # 压缩上下文
/session     # 查看会话信息
/export      # 导出会话
/reload      # 重新加载扩展和配置
/settings    # 打开设置

5. 配置文件

Pi 的全局配置目录：

~/.pi/agent

项目级配置目录：

当前项目/.pi

常见配置文件：

文件	作用
`settings.json`	全局设置、主题和已安装包
`models.json`	自定义 Provider 和模型
`auth.json`	登录凭据相关信息
`keybindings.json`	快捷键配置
`SYSTEM.md`	自定义系统提示词
`AGENTS.md`	全局协作规范和项目指令
`trust.json`	项目信任状态
`sessions/`	历史会话文件

全局配置对所有项目生效，项目级 .pi 配置可以覆盖全局配置。

6. Pi 包管理与扩展清单

6.1 包管理命令

安装 npm 包：

pi install npm:包名
pi install npm:包名@版本

安装 Git 包：

pi install git:github.com/用户/仓库

卸载包：

pi remove npm:包名
pi uninstall npm:包名

更新扩展：

pi update --extensions

更新 Pi 和扩展：

pi update --all

查看已安装包：

pi list

管理包内的扩展、技能、主题等资源：

pi config

安装或更新扩展后，通常需要重启 Pi，或者在当前会话执行：

/reload

6.2 推荐扩展清单

扩展	版本	主要功能
`@juanibiapina/pi-extension-settings`	0.9.1	统一管理扩展配置
`@juanibiapina/pi-powerbar`	0.15.0	Powerline 状态栏
`@narumitw/pi-btw`	0.56.0	侧线程问答
`pi-agent-browser-native`	0.5.0	浏览器自动化
`@victor-software-house/pi-curated-themes`	0.2.1	终端主题集合
`@pi-unipi/notify`	2.14.2	多平台通知
`pi-mcp-adapter`	2.31.0	MCP 服务适配
`pi-rounded-tools`	0.1.3	工具输出圆角边框
`pi-open-tui`	0.3.0	TUI 界面和遥测增强
`@ff-labs/pi-fff`	0.10.6	FFF 模糊文件与内容搜索

7. 扩展功能介绍

7.1 `@juanibiapina/pi-extension-settings`

扩展设置基础设施，为其他扩展提供统一的设置界面和配置存储。

主要命令：

/extension-settings
/extension-settings-local

/extension-settings：管理全局扩展配置；
/extension-settings-local：管理当前项目配置；
支持选项切换、字符串配置和有序多选；
全局配置保存到 ~/.pi/agent/settings-extensions.json；
项目配置保存到 .pi/settings-extensions.json。

该扩展需要优先加载。当前配置中它位于扩展列表第一位，顺序正确。

7.2 `@juanibiapina/pi-powerbar`

提供类似 tmux 的持久化 Powerline 状态栏。

默认可以展示：

Git 分支；
输入/输出 Token 和缓存信息；
上下文使用率；
当前 Provider 和模型；
会话费用；
订阅用量。

通过 /extension-settings 配置左右两侧 Segment、显示顺序、分隔符、位置和进度条样式。

该扩展依赖 pi-extension-settings，应放在它之后加载。当前配置顺序满足要求。

7.3 `@narumitw/pi-btw`

提供与主会话隔离的侧线程，适合临时提问、代码解释和方案讨论。

/btw
/btw 解释一下这个 TypeScript 错误
/btw 总结当前实现，但不要修改主线程

主要特性：

侧线程不会自动进入主对话；
可以从主会话树选择上下文；
支持侧线程内继续追问；
使用 Ctrl+R 将答案、指定范围或完整线程带回主编辑器；
可以配置独立模型和思考等级；
支持搜索侧线程记录。

配置文件：

~/.pi/agent/pi-btw.json

示例：

{
  "model": "anthropic/claude-sonnet-4-5",
  "thinkingLevel": "low",
  "rememberThinkingLevelChanges": true,
  "fullscreenCopyOnSelect": true
}

7.4 `pi-agent-browser-native`

将上游 agent-browser 集成为 Pi 原生工具 agent_browser，用于真实浏览器操作。

适用场景：

打开网页、文档和后台系统；
获取页面快照和截图；
点击、填写表单和选择下拉框；
使用登录态和持久化 Profile；
网页 QA、资料调研和下载文件；
Electron 桌面应用发现与管理。

该扩展需要额外安装上游 agent-browser，并确保命令在 PATH 中：

npm install -g [email protected]
agent-browser --version

录制视频等功能还需要 ffmpeg。

排查环境：

pi-agent-browser-doctor

在 Pi 中直接描述浏览器任务即可，例如：

使用 agent_browser 打开 https://example.com，并获取交互式页面快照。

7.5 `@victor-software-house/pi-curated-themes`

提供 65 个深色终端主题，主题来源于 iTerm2-Color-Schemes，并适配 Pi 的语义化主题模型。

选择主题：

/theme

也可以在 settings.json 中指定：

{
  "theme": "catppuccin-mocha"
}

可用主题包括：

catppuccin-mocha；
dracula-plus；
gruvbox-dark；
kanagawa-wave；
lovelace；
mellow；
vague；
front-end-delight。

当前本机主题为：

front-end-delight

7.6 `@pi-unipi/notify`

为 Pi 的生命周期事件提供通知能力，支持：

Windows 原生通知；
Gotify；
Telegram；
ntfy。

主要命令：

/unipi:notify-settings
/unipi:notify-test
/unipi:notify-set-gotify
/unipi:notify-set-tg
/unipi:notify-set-ntfy
/unipi:notify-event <event> <on|off>

可监听的事件包括：

workflow_end；
ralph_loop_end；
mcp_server_error；
agent_end；
agent_settled；
memory_consolidated；
session_shutdown；
ask_user_prompt。

配置文件：

~/.unipi/config/notify/config.json

Windows 原生通知无需额外配置即可使用；Telegram、Gotify 和 ntfy 需要先配置服务信息。

7.7 `pi-mcp-adapter`

为 Pi 提供 MCP 支持，并通过按需搜索和调用减少 MCP 工具定义对上下文的占用。

常用入口：

/mcp

MCP 服务默认采用 lazy 生命周期，不会在启动时连接所有服务，而是在实际调用时连接。

常用配置文件：

.mcp.json
~/.config/mcp/mcp.json
~/.pi/agent/mcp.json
.pi/mcp.json

示例：

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "[email protected]"]
    }
  }
}

在 Pi 中可以按需搜索 MCP 工具：

使用 mcp 搜索 screenshot 相关工具

修改 MCP 配置或启用状态后执行：

/reload

7.8 `pi-rounded-tools`

为 Pi 内置的 read、write、edit、bash、grep、find 和 ls 工具增加 Unicode 圆角边框。

它不会改变工具原有的预览、语法高亮或 diff 内容，主要用于改善工具调用结果的视觉层次。

需要注意：该扩展会重新注册内置工具。如果其他扩展也覆盖这些工具，可能发生渲染冲突。

7.9 `pi-open-tui`

提供更完整的终端界面增强：

顶栏显示模型、思考等级和当前目录；
底栏显示 Git、运行环境、上下文、Token、费用和扩展状态；
带边框的编辑器；
单轮 TPS、TTFT、耗时、停顿和 Token 遥测；
可调整图标模式和滚轮行为；
支持中英文设置界面。

打开设置：

/open-tui

配置文件：

~/.pi/agent/open-tui.json

图标模式支持：

nerd：使用 Nerd Font 图标；
ascii：使用纯文本图标；
auto：自动检测，检测失败时回退到 ASCII。

7.10 `@ff-labs/pi-fff`

使用 FFF 替换或增强 Pi 的文件和内容搜索能力。FFF 是 Rust 原生、支持 SIMD 的搜索实现，并提供索引和访问频率排序。

提供的工具：

fffind：模糊文件名搜索；
ffgrep：文件内容搜索；
fff-multi-grep：多模式 OR 搜索；
@ 文件补全：使用 FFF 索引和模糊匹配。

主要优势：

文件在会话启动时后台建立索引；
不需要每次搜索都启动 fd 或 rg 子进程；
根据访问频率进行 Frecency 排序；
Git 修改、暂存和未跟踪文件会获得更高优先级；
支持模糊匹配、智能大小写和分页搜索；
全部搜索在本地执行，不上传项目文件。

常用命令：

/fff-health       # 查看索引和数据库状态
/fff-rescan       # 重新扫描文件
/fff-mode <mode>  # 切换工作模式

默认模式为 tools-and-ui。如果希望替换 Pi 内置的 find 和 grep，可以使用 override 模式：

/fff-mode override
/reload

配置文件：

~/.pi/agent/pi-fff.json

示例：

{
  "mode": "override",
  "enableFsRootScanning": false,
  "enableHomeDirScanning": true,
  "warnOnHomeDirScan": true,
  "followSymlinks": true
}

如果从用户主目录启动 Pi，FFF 可能会扫描整个主目录。项目较大时，可以根据需要关闭主目录扫描或调整扫描范围。

8. 推荐工作流

1. 进入项目目录并启动 Pi
2. 先让 Pi 阅读项目结构和 AGENTS.md
3. 使用 /context 检查上下文使用情况
4. 使用 /btw 处理不会影响主任务的临时问题
5. 分阶段修改代码，每阶段运行测试
6. 使用 /tree、/compact 管理长会话
7. 长时间任务启用 notify
8. 完成后使用 /session 或 /export 留存结果

示例：

cd path/to/project
pi

阅读项目结构、AGENTS.md 和 package.json，先给出实现计划，不要修改文件。

按计划实现第一步。完成后运行相关测试，并总结修改内容。

文章许可

Pi Agent 快速上手教程以及扩展推荐

https://0v0.day/posts/pi-agent

作者: Aki
发布于: 2026-09-01
更新于: 2026-09-01
许可: CC BY-NC-SA 4.0

笔记

1 0

还没有公开评论。

Pi Agent 快速上手教程以及扩展推荐

1. Pi 是什么

2. 安装 Pi

环境要求

npm 安装

3. 配置模型与登录

3.1 使用订阅登录

3.2 使用 `models.json`

4. 使用 Pi

5. 配置文件

6. Pi 包管理与扩展清单

6.1 包管理命令

6.2 推荐扩展清单

7. 扩展功能介绍

7.1 `@juanibiapina/pi-extension-settings`

7.2 `@juanibiapina/pi-powerbar`

7.3 `@narumitw/pi-btw`

7.4 `pi-agent-browser-native`

7.5 `@victor-software-house/pi-curated-themes`

7.6 `@pi-unipi/notify`

7.7 `pi-mcp-adapter`

7.8 `pi-rounded-tools`

7.9 `pi-open-tui`

7.10 `@ff-labs/pi-fff`

8. 推荐工作流

文章许可

评论0

发表评论