天工开物KAIWU AI
工具指南 › Pi › Pi 使用指南(完整全套)
核实于 2026-11-08
工具指南·其十五核实于 2026-11-08

Pi 使用指南(完整全套)

适用对象
想快速了解工具定位、核心功能和上手路径的中文用户
核对日期
2026-11-08
本页目录

本指南综合了 10 篇公众号实测与深度教程(2026-08-24 ~ 11-05)。文中的 [1]~[10] 对应文末「参考原文」,序号与 00_清单.md 一致。每张图下方注明出处与对应文章。素材之间说法不一致、同名混淆或容易踩坑的地方,均用 ⚠️ 明确标出。

公众号素材收录了「显林叔」系统的成体系开源实战系列(覆盖架构原理、会话控制与子 Agent 协作),以及硅基流动、PPIO派欧云等云厂商的模型实测接入指南。技术规范补充了 GitHub 官方开源协议与扩展接入标准,以 [官1]~[官6] 标注,查阅日期 2026-11-08。


一、定位:它是什么,适合谁

在各类 Agent 工具越做越臃肿、动辄加载数万 Token 系统提示词的当下,Pi(全称 Pi Coding Agent,命令行命令为 pi)走了一条完全相反的极简主义道路 [1][8][10]。

它在 GitHub 上收获了超 10 万 Star,被开发者社区誉为**「最省 Token、最轻量透明的硬核编码 Agent」** [8][10]。它摒弃了复杂的 Electron 桌面外壳,直接以极速 CLI 运行在本地终端内,其核心设计哲学只有一句话:用最精炼的工具集、最小的 Prompt 开销,完成最扎实的本地代码交付 [1][8][10]。

图 1 四个核心工具

图源:[1] 时妙Ai花园《Pi Agent终极教程:从0到1打造自己的AI工作台》

1. 核心极简哲学:四个核心工具

许多重型 Agent 往往向模型注入几十个工具定义,导致模型极易产生工具选择混乱和幻觉。Pi 严格遵循「Unix 极简哲学」,主智能体出厂仅内置 4 个核心基础工具 [1][10]:

  1. 读文件(read_file):支持行号区间切片读取,绝不大段倾倒无用内容。

  2. 写文件(write_file):全量创建或覆盖特定文件。

  3. 精准编辑(edit_file):通过精确的目标字串定位进行局部替换,保留全部上下文缩进。

  4. 终端执行(run_command):执行编译、测试、Git 操作及构建脚本。

所有更高级的能力(如联网查询、MCP 协议、多子 Agent 编排),全部作为按需动态加载的扩展资源层存在,绝不常驻污染基础上下文 [1][2]。

图 2 可改造资源层

图源:[1] 时妙Ai花园《Pi Agent终极教程:从0到1打造自己的AI工作台》

2. 和同类 AI 编码工具怎么比

维度Pi (Pi Coding Agent)Claude CodeOpenCodeAider
架构哲学极致极简、透明无黑盒 [1][10]商业大厂端到端方案大而全开源工作台专注 Git 差异提交的小工具
Token 消耗极度节省(比常规 Agent 省 40%~60%)[8]偏高(注入大量官方规则)中等(取决于配置)较低(偏向单次代码 Diff)
启动与运行速度毫秒级极速启动,内存占用极少 [8][10]启动较快(Node 环境)桌面版占用较高极快(Python 环境)
界面形态纯终端 CLI,无 GUI 客户端 [1]终端 CLI + 桌面版终端 CLI + 桌面端纯终端交互
生态扩展支持四类资源层、MCP 与子 Agent [1][7]支持官方 Skills / MCP支持自由插件池与 MCP支持命令行参数微调
图 3 Token对比测试

图源:[8] 硅基流动《10 万星,巨省 Token,极简 Agent Pi 上手指南》

适合谁:

  • Token 敏感型开发者与学生:每一分钱 API 额度都想花在刀刃上,不希望每次聊两句就被冗长系统提示词吃掉几千 Token 的人 [8]。

  • 崇尚纯终端全键盘操作的极客:日常在 Vim、Neovim、Tmux 或 SSH 远程服务器里生活,要求工具极速无延迟的人 [4][10]。

  • 希望深入理解 Agent 底层原理的人:想彻底看清一条 Prompt 如何穿过模型、工具并最终落盘的架构师(Pi 的架构极其透明,没有隐藏的商业中转逻辑)[10]。

不适合谁:

  • 离不开图形化编辑器、要求必须有漂亮桌面窗口、拖拽式卡片交互的初学者 [10]。

  • 需要一键生成 3D 动画、音视频全流程多媒体创作的内容创作者 [1]。


二、准备与安装

0. 先选路线:你属于哪种情况

你的情况推荐安装方式核心步骤
Windows 10/11 用户npm 全局安装看第 1、2 步
macOS / Linux / 远程云服务器npm 或 pnpm 全局安装看第 1、2 步
使用硅基流动 / PPIO / DeepSeek API配置对应平台的兼容 Base URL看第四节「2. 接入第三方模型与 API Key」

1. 账号与费用

  • 开源工具本身:Pi 为开源项目,核心软件完全免费,直接通过 npm 安装 [1][2]。

  • API 费用自理:由于 Pi 极度省 Token,它搭配单价极具性价比的国内模型(如 DeepSeek-V3、Qwen-2.5-Coder、GLM-4)使用成本极其廉价,即使高强度连续重构代码,一天往往也只消耗几毛钱 [8][9]。


2. 全平台安装与版本核对

Pi 基于 Node.js 生态构建,支持在全平台通过一行命令安装 [2][4]:

前置要求

  • Node.js >= 18.0.0。终端输入 node -v 核对版本。

安装命令

bash
# 全局安装 pi-agent
npm install -g pi-coding-agent

# 或者使用 pnpm
pnpm add -g pi-coding-agent

安装完成后,输入命令核对版本与安装源:

bash
pi --version
图 4 版本核对与安装源

图源:[2] 狒狒AI《Pi 保姆级教程:7000 字手把手从 0 到 1,把扩展生态一起打通》


3. 四种运行模式(核心机制)

Pi 提供了四种标志性的工作模式,帮助开发者在「自动化效率」与「代码绝对安全」之间自如平衡 [9]:

图 5 四种运行模式

图源:[9] PPIO派欧云《PPIO × Pi:极简编码 Agent,定制你的工作流》

运行模式启动命令 / 标识核心行为适用场景
Interactive(交互模式,默认)pi终端多轮对话,每执行一步向用户请示批准 [4][9]日常功能研发、增量编码
Print / Dry-Run(打印模式)pi --print 或 pi -p只生成修复报告与 Diff,不碰磁盘落盘 [2]最适合改祖传老代码,先看报告与复核,绝不污染代码库 [2]
Batch(非交互无头批处理)pi --batch "prompt"无需人工确认,全自动执行并退出代码 0/1 [9]CI/CD 自动化构建、深夜挂机批量巡检
Review(结果包审阅模式)pi --review运行子 Agent,生成包含证据链的可审阅结果包 [7]复杂多模块协作、重大架构重构前的多视角推演

三、上手流程:从零到第一个完整项目

下面演示如何从零启动 Pi,并使用其独具特色的「Print 打印模式」安全修复一个有 Bug 的数据分析脚本 [2]。

第一步:启动 Pi

在工作目录终端中键入:

bash
pi

终端会弹出紧凑的 ASCII Logo 与当前激活的模型与环境信息:

图 6 Pi启动界面

图源:[9] PPIO派欧云《PPIO × Pi:极简编码 Agent,定制你的工作流》

第二步:执行第一个只读探索任务

对于新接手的陌生仓库,不要立刻让它改代码,先让它熟悉环境:

"请通读当前目录下的 README.md 与核心入口文件,总结该工程的模块划分与关键数据流向。"

图 7 第一个只读任务

图源:[9] PPIO派欧云《PPIO × Pi:极简编码 Agent,定制你的工作流》

Pi 仅调用 read_file 切片读取文件,并在数秒内输出精准架构摘要,未修改任何磁盘数据。

第三步:使用 Print 模式生成修复报表

针对代码中的统计错误,在终端使用 Print 模式让它提出修复方案 [2]:

bash
pi -p "修复 report.py 中计算同比增幅时除以零引发崩溃的缺陷"

Pi 会在终端打印出结构化的分析报告与逐行 Diff 变更对比:

图 8 print模式修复报表

图源:[2] 狒狒AI《Pi 保姆级教程:7000 字手把手从 0 到 1,把扩展生态一起打通》

第四步:人工复核并落盘

开发者亲自复核每一处变动的逻辑正确性 [2]:

图 9 修复后亲自复核

图源:[2] 狒狒AI《Pi 保姆级教程:7000 字手把手从 0 到 1,把扩展生态一起打通》

确认无误后,敲回车或切换回正常模式执行落盘,代码安全落地,零风险消除 Bug [2]!


四、核心功能与进阶

1. 四类可定制资源层体系

Pi 虽小,但其架构设计了高度分层的定制资源体系 [1][9]:

图 10 四类定制资源

图源:[9] PPIO派欧云《PPIO × Pi:极简编码 Agent,定制你的工作流》

  1. 项目规范指令(AGENTS.md):定义项目级技术约定与行为禁忌 [1][6]。

  2. 技能包(Skills):封装常用操作(如部署、迁移、数据库备份)为可复用指令 [6]。

  3. 扩展机制(Extensions):通过 JavaScript 插件拓展新工具(如接入网络搜索、数据库直连)[2]。

  4. MCP 协议支持(Model Context Protocol):标准化接入外部工具库 [2]。

全局与项目级 AGENTS.md

在用户根目录下可配置全局 ~/.pi/agents.md,在项目目录下可配置本地 AGENTS.md [1][8]:

图 11 全局AGENTS.md示例

图源:[8] 硅基流动《10 万星,巨省 Token,极简 Agent Pi 上手指南》

通过显式规定"严禁未经测试提交代码"、"所有注释一律使用英文",Pi 会严格以其为行为准绳 [6][8]。


2. 重点:接入第三方模型与 API Key 配置

Pi 本身没有任何厂商倾向性,原生全面支持 OpenAI 兼容标准接口。国内各大模型中转商(如硅基流动、PPIO 等)是 Pi 的绝佳搭档 [8][9]。

(1)在模型服务商处创建 API Key

以硅基流动(SiliconFlow)为例,注册后进入控制台创建 API 密钥 [8]:

图 12 硅基流动新建API密钥

图源:[8] 硅基流动《10 万星,巨省 Token,极简 Agent Pi 上手指南》

若使用 PPIO 派欧云等云厂商,获取其接口基础地址与模型具体 ID [9]:

图 13 PPIO模型详情与接口地址

图源:[9] PPIO派欧云《PPIO × Pi:极简编码 Agent,定制你的工作流》

(2)配置模型提供商字典

Pi 的核心配置文件位于用户根目录下的 ~/.pi/config.json:

json
{
  "default_model": "siliconflow/deepseek-ai/DeepSeek-V3",
  "providers": {
    "siliconflow": {
      "base_url": "https://api.siliconflow.cn/v1",
      "api_key": "env:SILICONFLOW_API_KEY",
      "models": [
        "deepseek-ai/DeepSeek-V3",
        "deepseek-ai/DeepSeek-R1"
      ]
    },
    "ppio": {
      "base_url": "https://api.ppinfra.com/v3/openai",
      "api_key": "env:PPIO_API_KEY",
      "models": [
        "deepseek/deepseek-v3/community",
        "deepseek/deepseek-r1/community"
      ]
    },
    "deepseek_official": {
      "base_url": "https://api.deepseek.com/v1",
      "api_key": "env:DEEPSEEK_API_KEY",
      "models": [
        "deepseek-chat",
        "deepseek-reasoner"
      ]
    },
    "ollama_local": {
      "base_url": "http://localhost:11434/v1",
      "api_key": "ollama",
      "models": [
        "qwen2.5-coder:7b"
      ]
    }
  }
}

(3)验证模型接入

配置完成后,运行内置诊断命令核对自定义模型列表:

bash
pi list-models
图 14 list-models验证自定义模型

图源:[2] 狒狒AI《Pi 保姆级教程:7000 字手把手从 0 到 1,把扩展生态一起打通》

终端会绿色输出当前所有已被识别并测试连通的模型,表示多模型接入彻底跑通 [2]。


3. 生态打通:扩展与 MCP 管理

虽然核心工具只有 4 个,但你可以随时在终端查看并激活扩展插件生态 [2]:

查看已安装的本地扩展

bash
pi list
图 15 pi-list查看扩展

图源:[2] 狒狒AI《Pi 保姆级教程:7000 字手把手从 0 到 1,把扩展生态一起打通》

查看 MCP 服务器状态

bash
pi mcp-list
图 16 pi-mcp-list

图源:[2] 狒狒AI《Pi 保姆级教程:7000 字手把手从 0 到 1,把扩展生态一起打通》

动态联网能力示例

通过挂载轻量联网扩展,Pi 可以自主调用搜索引擎获取最新的软件包发布版本信息 [2]:

图 17 联网扩展查版本

图源:[2] 狒狒AI《Pi 保姆级教程:7000 字手把手从 0 到 1,把扩展生态一起打通》


五、避坑与注意(⚠️ 关键避坑)

1. ⚠️ 同名混淆风险(重名陷阱)

  • 现象:在网上搜索或安装时,极易混淆「Inflection AI 的 Pi 情感陪伴机器人」、「π 语言(Pi Lang)」或区块链代币「Pi Network」[清单说明]。

  • 指正:本指南所指的 Pi 严格指代 GitHub 上的开源项目 pi-coding-agent(终端命令为 pi),定位为本地自主编程智能体,切勿下载无关客户端或涉嫌灰色代币的恶意软件!

2. ⚠️ 拒绝盲目全自动:善用 Print 模式

  • 建议:Pi 能够直接操纵本机终端命令。面对核心业务代码库时,强烈建议初学者先使用 -p(Print 打印模式)预览修改方案(如图 09 所示)[2]。先复核 Diff 逻辑,再执行真机写入,这是极简 Agent 的最佳实践姿态。

3. ⚠️ 扩展不宜贪多:避免违背极简初衷

  • 建议:Pi 的最大优势是 Token 极其节省、上下文极其干净。切忌一次性挂载几十个不常用的 MCP 服务或大型扩展,这会导致其丧失核心的低成本与极速响应优势 [1][8]。


六、参考原文与出处

1. 本文参考微信公众号素材清单

#文章标题与链接来源公众号发布日期配图数为什么入选与核心引用点
1[Pi Agent终极教程:从0到1打造自己的AI工作台]时妙Ai花园2026-08-243架构入门精选,系统提出四大核心工具与可改造资源层概念(引用图 01、02)
2[Pi 保姆级教程:7000 字手把手从 0 到 1,把扩展生态一起打通]狒狒AI2026-10-29107000 字实操长文,手把手演示版本核对、模型验证、print 打印模式复核、扩展列表与联网查询(引用图 03、05、09、10、13、14、17)
3[系统学习 Pi Agent——从零基础到实战开发的完整指南]AI开挂日记2026-09-1701.5 万字系统进阶教材,全面拆解工程环境搭建与项目工程化规范
4[Pi Agent实战:01认识Pi,完成安装与模型连接]显林叔2026-10-261显林叔权威实战系列第 1 篇,从设计哲学讲起,梳理终端安装与连接链路
5[Pi Agent实战:03理解 Agent 运行、上下文与会话控制]显林叔2026-10-280显林叔实战系列第 3 篇,深度分析会话上下文维护机制与长任务内存管理
6[Pi Agent实战:05项目指令与可复用步骤]显林叔2026-10-290显林叔实战系列第 5 篇,阐述项目级 AGENTS.md 规则约束与可复用步骤(Skill)封装
7[Pi Agent实战:11子Agent协作与可审阅的结果包]显林叔2026-11-050显林叔实战系列第 11 篇,讲解多子 Agent 协同运行架构与交付物审查机制
8[10 万星,巨省 Token,极简 Agent Pi 上手指南]硅基流动2026-09-2813模型服务商官方实测,提供精准 Token 消耗对比数据、硅基流动 Key 申请与全局配置(引用图 04、11、16)
9[PPIO × Pi:极简编码 Agent,定制你的工作流]PPIO派欧云2026-10-3016云算力平台官方实测,覆盖 PPIO 模型配置、启动主界面、只读任务、四类资源层与四种运行模式(引用图 06、07、08、12、15)
10[把 Pi Agent 拆开:一条 Prompt 怎样穿过模型、工具和 Session]Jason的算法日志2026-10-252算法视角深度技术解构,剖析 Pi 工具调度底层执行链路与设计哲学

2. 官方技术文档与生态规范列表

编号来源与页面名称查阅日期补充与核实用到的核心内容
[官1]Pi Coding Agent GitHub 官方仓库 (pi-coding-agent)2026-11-08官方技术白皮书、极简架构规范、CLI 全局参数与安装依赖标准
[官2]Pi 运行模式与交互规范 (Execution Modes RFC)2026-11-08Print 模式(Dry-Run)、Batch 模式与审阅结果包(Review Bundle)技术实现
[官3]Pi Extension & MCP Bridge Documentation2026-11-08外部轻量 JavaScript 扩展与标准 MCP 服务的动态加载协议

3. 本文使用图片清单核对表

图片文件名图片内容说明引用章节对应素材来源
01-四个核心工具.png官方四大基础核心工具示意图第一节 定位[1] 时妙Ai花园
02-可改造资源层.png核心层之上的四类动态可扩展资源层架构第一节 定位[1] 时妙Ai花园
03-版本核对与安装源.jpg全局安装后通过 --version 核对版本与源第二节 2. 全平台安装[2] 狒狒AI
04-硅基流动新建API密钥.png在硅基流动控制台创建 API Key 界面第四节 2. 接入第三方模型[8] 硅基流动
05-list-models验证自定义模型.jpg运行 pi list-models 验证模型连通性第四节 2. 接入第三方模型[2] 狒狒AI
06-PPIO模型详情与接口地址.pngPPIO 派欧云模型详情页与 OpenAI 接口格式第四节 2. 接入第三方模型[9] PPIO派欧云
07-Pi启动界面.png终端启动 Pi 后的极简信息面板与状态看板第三节 上手流程[9] PPIO派欧云
08-第一个只读任务.png执行首次不碰磁盘的代码仓库架构分析任务第三节 上手流程[9] PPIO派欧云
09-print模式修复报表.jpg使用 -p 打印模式生成的修复报告与 Diff第三节 上手流程[2] 狒狒AI
10-修复后亲自复核.jpg开发者亲自复核 Print 模式输出的正确性第三节 上手流程[2] 狒狒AI
11-全局AGENTS.md示例.png用户主目录下的全局行为约束规则配置第四节 1. 四类定制资源层[8] 硅基流动
12-四类定制资源.jpg指令、技能包、扩展与 MCP 四类生态体系第四节 1. 四类定制资源层[9] PPIO派欧云
13-pi-list查看扩展.jpg运行 pi list 查看当前已挂载的本地扩展第四节 3. 生态打通与扩展[2] 狒狒AI
14-pi-mcp-list.jpg运行 pi mcp-list 查看当前激活的 MCP 服务第四节 3. 生态打通与扩展[2] 狒狒AI
15-四种运行模式.jpg交互、打印、批处理与审阅四种运行模式对比第二节 3. 四种运行模式[9] PPIO派欧云
16-Token对比测试.pngPi 与常规重型 Agent 的 Token 消耗实测对比第一节 定位[8] 硅基流动
17-联网扩展查版本.jpg挂载联网扩展后通过搜索引擎查阅最新包版本第四节 3. 生态打通与扩展[2] 狒狒AI
更新于 2026-11-08来源:用户提供《工具指南_完整全套_含所有MD与图片.zip》;正文保留原文参考来源