这篇教程写给完全没接触过 AI 编程工具的朋友。你不需要懂编程，只需要会复制粘贴。

  • 完全新手：按顺序读，先花 5 分钟看懂”Pi 强在哪”（第 1 章），再做安装配置（第 2-5 章），最后跟着做第一个作品（第 6 章）。
  • 用过 Claude Code / Codex 的朋友：直接跳到第 3 章装好、第 4 章配模型，重点看进阶篇（下篇）。
  • 报错怎么办：把报错文字完整截图，发给任何一个 AI 工具问”这个报错怎么解决”，比瞎猜快十倍。
  • 做到哪一步算入门：Pi 帮你写出网页、你在浏览器里看到效果的那一刻。

第 1 章 Pi 到底有多强：5 分钟看懂它凭什么火

先说结论：Pi 是 2026 年最火的极简 AI 编程 Agent，GitHub 9.3 万星、1.1 万 fork、npm 周下载 130 万次。 作者 Mario Zechner 是 libGDX 游戏框架的创始人，属于”真大佬下场”。

它官网首页只有一句话：

“There are many agent harnesses, but this one is yours.” （Agent 框架一大堆，但这个是你的。）
“有很多种手套可供选择，但这只属于你。” （代理框架有很多，但这个是你的。）

问题来了：市面上 Claude Code、Codex 已经够有名了，为什么 Pi 能杀出来？因为它干了件”反着来”的事，大家都在给 AI 加功能，它却在给 AI 做减法。

1.1 三个数字看懂它的哲学

对比：内置工具；Pi：4 个（读/写/改/执行命令，另有 3 个只读查询）；Claude Code / Codex：10 个以上，还在不断加

对比：系统提示词；Pi：约 1000 token；Claude Code / Codex：一万 token 起步

对比：打个招呼；Pi：1100 token，占 0.4% 上下文；Claude Code / Codex：Codex 要 1.8 万 token，占 7%，活没干先烧 7% 的”办公桌”

看不懂 token 没关系，记住一句话：AI 每轮对话都要把”系统提示词 + 工具清单”重新发一遍，这些是固定开销。 提示词一万 token、工具 20 个，一个 50 轮的任务，光固定开销就比 Pi 贵出一个数量级。Pi 砍的正是这笔”固定税”。

1.2 硬数据：它赢在哪儿，不是嘴说

  • 同价质量更高：全球知名大数据公司 Databricks 拿自家几百万行代码的仓库跑基准，发现”换一个 Agent 外壳，同样成本能差 2 倍以上”，而同等成本下 Pi 的代码质量超过 Claude Code 和 Codex，整张图质量最高点是 Pi 配 Claude 最强模型。
  • 速度更快：Composio 的测试显示，Pi 完成编程任务比同类工具快 1.5 到 2 倍。
  • 大佬亲身背书：Shopify CEO 用 Pi 给自己的开源模板引擎写了个自动优化插件，跑了几十轮自动实验，把性能提升 53%、内存占用减少 61%，全程 AI 自己动手。

1.3 Pi 的六大特点（记不住没关系，后面都会用到）

  1. 极简默认只有 4 个工具，AI 干了什么，每一步都摊开在你眼前，没有黑盒。
  2. 快同样任务，完成速度快 1.5-2 倍。
  3. 省上下文纪律好，同样的活，账单更薄。
  4. 模型自由15+ 家供应商随便切（DeepSeek、Claude、ChatGPT、Gemini、Kimi……），对话中途换模型不丢上下文。
  5. 生态开放要什么功能装什么（联网、子代理、Plan、goal 目标模式、MCP 连接外部服务），甚至可以用网页版界面。
  6. 能自我进化最离谱的一条，它可以自己给自己写插件。你缺什么功能，跟它说一声，它自己写、自己装、自己测。

一句话总结：别人给 AI 加装备，它给 AI 减负担。减到底，AI 反而发挥得更好。

第 2 章 三个概念先懂（2 分钟）

正式动手前，把三个词过一遍，后面全是顺水推舟：

概念：Agent；人话解释：能自己动手干活的人工智能，不只是聊天，还能读写文件、运行命令；类比：一个会写代码的员工

概念：模型（Model）；人话解释：Agent 的”大脑”，负责理解和思考；类比：员工的大脑

概念：Token；人话解释：AI 计费的”字数”，中文约 1 个字 ≈ 1-2 个 token；类比：电费，用得越多越贵

概念：上下文（Context）；人话解释：AI 一次能记住的内容总量；类比：员工的办公桌，越大能摊开的东西越多

Pi 本质：一个让你用一句话指挥”会写代码的员工”的终端工具。 它负责调度模型、读写文件、执行命令，把”说人话”翻译成”干活”。

第 3 章 安装 Pi：三选一，都很简单

Pi 本体是一个 npm 包，装好后全局可用。三种方式任选：

方式一：Windows 一键脚本（推荐）

  1. 桌面空白处点右键 、 “在终端中打开”。
  2. 粘贴这条命令，回车：

powershell -c “irm

https://pi.dev/install.ps1

| iex”

  1. 如果提示需要 Node.js 或 Git，输入 y 让它自动装（Pi 依赖 Node.js 运行）。
  2. 关掉当前窗口，重新打开一个终端（这步不能省，新装的命令才生效）。
  3. 输入 pi 回车，出现对话界面即成功。

方式二：Mac / Linux 一键脚本

打开”终端”，粘贴：

curl -fsSL

https://pi.dev/install.sh

| sh
执行以下命令：curl -fsSL https://pi.dev/install.sh | sh

装完重新开终端，输入 pi。

方式三：npm 全局安装（任何系统）

已经装了 Node.js（建议 LTS 版本）的话：

npm install -g –ignore-scripts

@earendil

-works/pi-coding-agent
使用 npm 安装全局模块，并忽略@earendil-works/pi-coding-agent 中的脚本文件：npm install -g –ignore-scripts @earendil-works/pi-coding-agent

然后 cd 到你的项目目录，输入 pi 启动。

验证：输入 pi –version 能看到版本号，就说明装好了。

第 4 章 配置模型：给 Pi 装上”大脑”

装好只是空壳，得先配一个模型。两种方式，二选一。

方式一：API Key（按量付费，灵活）

  1. 启动 Pi，输入 /login 回车。
  2. 选 API key 那一项。
  3. 国内直连推荐 DeepSeek（便宜、稳定）：打开 DeepSeek 开放平台 、 注册充值 、 “API keys”里创建一个 key，复制。
  4. 回到 Pi 把 key 粘贴进去，按提示完成。
  5. 打个招呼测试。Pi 回复了 = 配置成功。

也可以不用 /login：先 export DEEPSEEK_API_KEY=sk-xxx 再启动 Pi，等价。

方式二：订阅账号（包月党）

  1. /login选 Sign in with account。
    /login 时选择“使用账户登录”。
  2. 选你的订阅：Claude Pro/Max、ChatGPT Plus/Pro（Codex）、GitHub Copilot 都支持。
    选择你的订阅服务：Claude Pro/Max、ChatGPT Plus/Pro（Codex）、GitHub Copilot 都支持使用。
  3. 浏览器弹窗登录，登录完回 Pi。
  4. 按 Ctrl + L 打开模型选择器，看到你的订阅模型。

日常切模型的三个快捷键

操作：打开模型选择器；快捷键 / 命令：Ctrl + L 或 /model

操作：循环切换常用模型；快捷键 / 命令：Ctrl + P（后退 Shift + Ctrl + P）

操作：调整思考强度（省不省钱就看它）；快捷键 / 命令：Shift + Tab 循环：off 、 minimal 、 low 、 medium 、 high 、 xhigh 、 max

省钱口诀：简单任务用便宜模型 + 低思考强度；复杂任务再上贵模型。对话中途随时切，不丢上下文。

第 5 章 基础操作：学会”使唤”它

5.1 建项目文件夹（工作地点）

  1. 新建文件夹，比如 family-ledger（建议全英文名，省得以后踩坑）。
  2. 右键文件夹 、 “在终端中打开” 、 输入 pi 回车。
  3. 窗口顶部显示这个文件夹的路径，这就是 AI 的工作地点，代码都写在这里。

5.2 常用输入技巧

你想做什么：发一条指令；怎么操作：打字，回车

你想做什么：输入多行指令；怎么操作：Shift + Enter 换行，写完再回车

你想做什么：打开系统编辑器写长文；怎么操作：Ctrl + G（Windows 打开记事本），保存关掉自动同步

你想做什么：给 AI 看截图；怎么操作：粘贴：Windows 按 Alt + V，Mac 按 Ctrl + V（Windows 是 Alt+V，最容易记反）

你想做什么：让 AI 只读某个文件；怎么操作：输入 @ 弹出文件搜索，选中即可；命令行也能 pi

@README

.md “概括一下”

你想做什么：运行命令并把结果给 AI；怎么操作：!命令，例如 !npm run dev

你想做什么：运行命令但 AI 看不见；怎么操作：!!命令，例如 !!git commit -m “wip”

5.3 看懂底部状态栏

界面最下面一行是”仪表盘”：

  • 输入 Token / 输出 Token本会话累计的输入、输出量。
  • Cache Read / 缓存命中率命中缓存越多越省钱。
  • 预估成本花了多少（订阅模式仅供参考）。
  • xx% / 总窗口当前上下文占用比例、模型总窗口大小。
  • **auto（压缩）**上下文快满时自动压缩历史。
  • 末尾：模型供应商 + 模型名 + 思考强度。

5.4 会话：随时走，随时回

  • /new：开新会话（AI 忘掉之前一切）。
  • 下次回来：pi -c 继续最近一次；pi -r 从列表里挑一个。
  • 也可以 pi –name “记账本任务” 给会话起名，方便以后找。

第 6 章 第一个作品：做”家庭记账本”网页

理论够了，动手。这一章你会在 10 分钟内让 Pi 从零做出一个家庭记账本网页，记收入、记支出、看汇总。这是咱们自己的例子，你也可以换成任何你想要的（菜谱管理、读书清单、健身打卡……），套路完全一样。

6.1 下达任务

在 Pi 对话框输入：

用 React 做一个家庭记账本网页，功能包括： 1. 记录每笔收支（金额、类别、备注、日期） 2. 显示总收入、总支出、结余 3. 最近的记录列表

回车。Pi 会开始”读文件、写文件、跑命令”，耐心等它跑完。

看到什么算成功：对话里出现大量文件操作记录，最后提示你可以启动项目。

6.2 启动看效果

!npm run dev

等它启动，会给你一个本地地址（一般是 http://localhost:5173 或 3000）。浏览器打开，记账本的页面就在眼前。 恭喜，第一个作品完成！

6.3 用截图提需求（不用打一个字）

觉得界面丑？比如想让”结余”数字更醒目：

  1. 浏览器里截图。
  2. 回到 Pi，Windows 按 Alt + V、Mac 按 Ctrl + V 粘贴图片。
  3. 输入”结余数字要大、用绿色显示”。
  4. Pi 看图改代码，刷新浏览器看效果。

6.4 让它把代码拆干净

趁热打铁，让代码别堆在一个文件里：

@src/main

.tsx 把代码拆成组件，收支表单一个组件、汇总一个组件、列表一个组件

Pi 会重构代码结构。以后加功能、改样式都更清晰。

6.5 记住这几个命令，闭环就通了

命令：!npm run dev；作用：启动项目

命令：!npm install；作用：装依赖

命令：/new；作用：干完一轮，开新会话继续

命令：pi -c；作用：明天回来接着干

到这里你已经入门了。 接下来想更上一层楼，AI 干活时怎么”插话”、会话怎么开分支、怎么装 goal 模式让 AI 自己跑完一个目标、甚至让 AI 自己给自己写插件，请看下篇。

写在最后（上篇）

别贪多。今天就把 Pi 装上，让它写出你的记账本，做完这一件事，你就超过 90% 的人了。

命令有拿不准的，回看第 5 章的表格；报错了截图问 AI。先上路，再谈车技。