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

2026-09-01笔记约 1397 字5 分钟9

1. Pi 是什么

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

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

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

2. 安装 Pi

npm 安装

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

启动 Pi：

pi

3. 配置模型与登录

3.1 使用订阅登录

启动 Pi 后执行：

/login

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

3.2 使用 `models.json`

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

~/.pi/agent/models.json

通用模板如下：

{
  "providers": {
    "my-provider": {
      "baseUrl": "https://api.example.com/v1",
      "api": "openai-responses",
      "apiKey": "$MY_API_KEY",
      "headers": {
        "X-Custom-Header": "value"
      },
      "authHeader": true,
      "models": [
        {
          "id": "model-id",
          "name": "My Model",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 128000,
          "maxTokens": 16384,
          "cost": {
            "input": 0,
            "output": 0,
            "cacheRead": 0,
            "cacheWrite": 0
          }
        }
      ]
    }
  }
}

常见字段：

字段	说明
`baseUrl`	Provider 的 API 地址
`api`	使用的 API 类型，例如 `openai-completions` ,`openai-responses`,`anthropic-messages`,`google-generative-ai`
`apiKey`	API Key
`headers`	发送请求时附加的自定义请求头
`authHeader`	是否自动添加 `Authorization: Bearer <apiKey>`
`models[].id`	服务商实际使用的模型 ID
`models[].name`	Pi 中显示的模型名称
`models[].reasoning`	是否支持推理/思考等级
`models[].input`	支持的输入类型，可填写 `["text"]` 或 `["text", "image"]`
`models[].contextWindow`	上下文窗口大小，单位为 Token
`models[].maxTokens`	单次响应允许生成的最大 Token 数
`models[].cost`	Token 费用信息，单位为每百万 Token

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

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

/reload

4. 使用 Pi

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

常用交互命令：

/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`	统一管理扩展配置	`pi install npm:@juanibiapina/pi-extension-settings`
`@narumitw/pi-btw`	侧线程问答	`pi install npm:@narumitw/pi-btw`
`pi-agent-browser-native`	浏览器自动化	`pi install npm:pi-agent-browser-native`
`@pi-unipi/notify`	任务状态通知	`pi install npm:@pi-unipi/notify`
`pi-mcp-adapter`	MCP 服务适配	`pi install npm:pi-mcp-adapter`
`@ff-labs/pi-fff`	文件和内容搜索	`pi install npm:@ff-labs/pi-fff`

TUI 扩展

扩展	主要功能	安装命令
`@juanibiapina/pi-powerbar`	Powerline 状态栏	`pi install npm:@juanibiapina/pi-powerbar`
`pi-open-tui`	完整 TUI 界面增强	`pi install npm:pi-open-tui`

美化扩展

扩展	主要功能	安装命令
`pi-rounded-tools`	为工具输出增加圆角边框	`pi install npm:pi-rounded-tools`

主题扩展

主题扩展	主要功能	安装命令
`pi-sakura-cyberdeck`	Sakura Cyberdeck 主题	`pi install git:github.com/beautifulrem/pi-sakura-cyberdeck`

7. 扩展功能介绍

7.1 功能扩展

`@juanibiapina/pi-extension-settings`

统一管理其他扩展的配置。pi-powerbar 依赖此扩展。

`@narumitw/pi-btw`

提供独立的侧线程，适合临时提问、代码解释和方案讨论。

/btw

`pi-agent-browser-native`

提供浏览器自动化能力，可用于打开网页、获取页面信息和操作表单。

使用前需要额外安装：

npm install -g agent-browser

`@pi-unipi/notify`

提供任务完成、错误和会话状态通知。

打开设置：

/unipi:notify-settings

建议在设置中开启 agent_settled 事件，便于及时获知任务已经处理完成。

`pi-mcp-adapter`

为 Pi 提供 MCP 支持，可按需搜索和调用 MCP 工具。

/mcp

`@ff-labs/pi-fff`

增强文件名和文件内容搜索，支持模糊匹配和索引搜索。

7.2 TUI 扩展

`@juanibiapina/pi-powerbar`

提供 Powerline 状态栏，可显示模型、上下文、Token、费用和 Git 信息。

该扩展依赖 @juanibiapina/pi-extension-settings。如果已经使用 pi-open-tui 或 pi-sakura-cyberdeck 主题，使用此扩展可能会产生冲突。

`pi-open-tui`

增强 Pi 的终端界面，提供顶栏、底栏、边框编辑器和运行信息展示。

/open-tui

7.3 美化扩展

`pi-rounded-tools`

为内置工具输出增加 Unicode 圆角边框，只改变显示效果，不改变工具功能。

7.4 主题扩展

`pi-sakura-cyberdeck`

提供 Sakura Cyberdeck 终端主题，建议pi-open-tui与此主题二选一即可；

安装后使用以下命令选择：

/theme

文章许可

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

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

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

笔记

9 0

还没有公开评论。

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

1. Pi 是什么

2. 安装 Pi

npm 安装

3. 配置模型与登录

3.1 使用订阅登录

3.2 使用 `models.json`

4. 使用 Pi

5. 配置文件

6. Pi 包管理与扩展清单

6.1 包管理命令

6.2 推荐扩展清单

功能扩展

TUI 扩展

美化扩展

主题扩展

7. 扩展功能介绍

7.1 功能扩展

`@juanibiapina/pi-extension-settings`

`@narumitw/pi-btw`

`pi-agent-browser-native`

`@pi-unipi/notify`

`pi-mcp-adapter`

`@ff-labs/pi-fff`

7.2 TUI 扩展

`@juanibiapina/pi-powerbar`

`pi-open-tui`

7.3 美化扩展

`pi-rounded-tools`

7.4 主题扩展

`pi-sakura-cyberdeck`

文章许可

评论0

发表评论