Pi Coding Agent 完整使用指南

Pi 是一个极简、可扩展的终端 AI 编程代理。它的核心理念是“内核尽量小，功能靠扩展”，默认只给模型最基础的读写与执行能力，其余一切（子代理、MCP、权限控制、UI 增强）都由社区扩展或你自己编写的 TypeScript 模块补足。

一、安装 Pi

Pi 需要 Node.js 22.19 或更高版本。根据你的系统选择一种方式：

方式一：官方安装脚本（macOS / Linux，推荐）

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

安装脚本会固定依赖版本，后续用 pi update 更新。

方式二：npm 全局安装（跨平台）

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

注意：npm 安装不会固定传递依赖的版本。

Windows 用户（PowerShell）：

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

验证安装：

bash
pi --version

二、快速上手

2.1 启动 Pi

bash
cd /path/to/your/project
pi

Pi 会以当前目录为工作区，自动发现相关文件和配置，并按目录分组保存会话。

2.2 连接模型（首次使用）

在 Pi 的交互界面中输入：


/login

根据提示选择提供商，粘贴 API Key 或完成订阅授权。完成后用 /model 可以切换模型。

2.3 给 Pi 一个任务

直接输入自然语言即可，例如：


总结 @meeting-notes.md，把行动项保存到 action-items.md
解释这个仓库的结构，以及如何运行检查

输入 @ 会弹出文件搜索，不用手打完整路径。Pi 会展示每一次文件读取、搜索、命令执行和编辑，但不会在每次工具调用前询问你（默认行为）。

2.4 继续之前的会话

bash
pi --continue

或进入 Pi 后用 /resume 选择其他历史会话。

2.5 退出

输入 /exit 或按 Ctrl+C。

三、安装扩展与技能

Pi 的扩展体系分三层：Skill（技能） 是给模型的按需指令包；Extension（扩展） 是用 TypeScript 写的可执行模块，可以注册新工具、命令、事件钩子；Pi Package 是把多个扩展/技能/主题打包分发的 npm 或 git 包。

3.1 安装 Pi Package（最简单）

bash
# 从 npm 安装
pi install npm:@foo/pi-tools

# 从 git 安装
pi install git:github.com/user/repo

安装后执行 /reload 或重启 Pi 生效。

⚠️ 安全提醒：Pi Package 以完整系统权限运行，扩展可以执行任意代码。安装第三方包前请先审查源码。

3.2 手动放置扩展或技能

将文件放到对应目录，Pi 启动时会自动发现：

类型	全局目录	项目目录
扩展	`~/.pi/agent/extensions/`	`.pi/extensions/`
技能	`~/.pi/agent/skills/`	`.pi/skills/`
提示模板	`~/.pi/agent/prompts/`	`.pi/prompts/`

技能的标准格式是 SKILL.md 文件，调用方式为 /skill:技能名，也可以让模型自动加载。

四、推荐的扩展与 Package

以下推荐基于 Pi 官方包目录中已有描述、功能明确的社区包。安装前请自行审查源码。

4.1 dnopi

包含 6 个实用技能和 2 个扩展，适合日常开发辅助。

组件	说明
`tmux` 技能	在 tmux 会话中运行长时间进程
`web-search` 技能	通过真实浏览器进行多引擎网页搜索和内容提取
`slack-latest` 技能	读取 Slack 最近消息、线程并回复
`linear` 技能	通过 linearis CLI 管理 Linear issue
`improve-agent` 技能	分析 Pi 会话记录，找出重复问题并改进工作流
`notify.ts` 扩展	代理需要关注时弹出桌面通知

安装：

bash
pi install npm:dnopi

4.2 @vaayne/agent-kit

精选的技能+扩展合集，兼容 Pi 和 Claude Code。包含 MCP 客户端集成、子代理、JetBrains IDE 控制等能力。

核心扩展：

扩展	作用
`mcp`	MCP 客户端集成，带工具编排
`subagent`	将任务委派给专门的子代理（librarian、oracle、ui-engineer、worker）
`notify`	长时间任务完成时系统通知
`powerline-status`	带 git、时间、上下文信息的丰富状态栏

值得关注的技能：mcp-jetbrains-ide（通过 MCP 控制 JetBrains IDE）、mcp-context7-docs（查询最新库文档）、frontend-design（高质量 UI 生成）。

安装：

bash
pi install npm:@vaayne/agent-kit

4.3 @keywaytech/pi-provider-manager

如果你需要频繁切换或管理多个模型供应商，这个扩展提供本地 Web 图形界面来编辑 models.json 和 settings.json，免去手改 JSON 的麻烦。功能包括：增删改供应商/模型、一键设置默认项、API Key 打码显示、自动备份（保留最近 10 份）、连接测试。

安装：

bash
pi install git:github.com/KeywayTech-org/pi-provider-manager

安装后执行 /reload，然后输入 /providers 即可打开管理页面。

五、接入模型

Pi 支持多种模型接入方式，按你的场景选择。

5.1 使用内置提供商（最简单）

启动 Pi 后执行 /login，选择提供商（如 Anthropic、OpenAI 等），按提示完成订阅授权或粘贴 API Key。之后用 /model 切换可用模型。

也可以通过环境变量传入 Key，例如：

bash
export ANTHROPIC_API_KEY=sk-ant-...
pi

5.2 使用 MiniMax 等第三方提供商

以 MiniMax 为例，设置环境变量后指定 provider 和 model 启动：

bash
export MINIMAX_CN_API_KEY=sk-cp-...
pi --provider minimax-cn --model MiniMax-M3

MiniMax 也提供了一键配置向导：

bash
npx -y mmx-cli@latest agent setup

在工具列表中选择 Pi 即可。

5.3 使用本地模型（llama.cpp）

Pi 支持 llama.cpp 的 router 模式，可以加载多个 GGUF 模型并按需切换。

安装 llama.cpp：

bash
curl -LsSf https://llama.app/install.sh | sh

启动 router（不带 --model 参数，以 router 模式运行）：

bash
llama serve \
  --no-models-autoload \
  --host 127.0.0.1 \
  --port 8080 \
  -ngl all \
  -c 32768 \
  --jinja

关键参数：--jinja 启用兼容的聊天模板和工具调用；--no-models-autoload 让模型加载保持手动控制。

配置 Pi：


/login llama.cpp

输入 router URL（默认 http://127.0.0.1:8080）。然后用 /llama 加载模型，用 /model 选择当前会话使用的模型。

5.4 自定义 API 端点（OpenAI 兼容等）

Pi 的模型配置保存在 ~/.pi/agent/models.json。你可以手动编辑该文件，添加自定义的 baseUrl、api、apiKey 和 models 列表；也可以使用上面推荐的 pi-provider-manager 扩展通过图形界面管理。

配置后，在 Pi 中用 /model 选择自定义模型即可。

六、常用命令速查

命令	作用
`/login`	连接模型提供商
`/model`	切换模型
`/reload`	重新加载扩展/技能/配置
`/compact`	压缩长会话的上下文
`/resume`	选择并恢复历史会话
`/settings`	修改常用设置
`/skill:名称`	手动调用某个技能
`/exit`	退出 Pi

配置文件位置：全局 ~/.pi/agent/settings.json，项目级 .pi/settings.json（覆盖全局）。项目指令写在 AGENTS.md 中（Pi 启动时从当前目录和上级目录逐层加载），也可以放在 ~/.pi/agent/AGENTS.md 作为全局指令。

七、注意事项

默认无权限确认：Pi 不会在每次工具调用前询问你。处理不可信代码或无人值守任务时，建议使用容器或沙箱隔离。
第三方包有完整系统权限：pi install 的包可以执行任意代码、修改你的文件。只安装你审查过源码的包。
会话自动保存：Pi 按工作目录分组保存会话，换目录后 pi --continue 恢复的是对应目录的最近会话。