夜雨聆风
新手上路
这篇教程写给完全没接触过 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 游戏框架的创始人，属于"真大佬下场"。
它官网首页只有一句话：
问题来了：市面上 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 的六大特点（记不住没关系，后面都会用到）
- 极简
默认只有 4 个工具，AI 干了什么，每一步都摊开在你眼前，没有黑盒。 - 快
同样任务，完成速度快 1.5-2 倍。 - 省
上下文纪律好，同样的活，账单更薄。 - 模型自由
15+ 家供应商随便切（DeepSeek、Claude、ChatGPT、Gemini、Kimi……），对话中途换模型不丢上下文。 - 生态开放
要什么功能装什么（联网、子代理、Plan、goal 目标模式、MCP 连接外部服务），甚至可以用网页版界面。 - 能自我进化
最离谱的一条，它可以自己给自己写插件。你缺什么功能，跟它说一声，它自己写、自己装、自己测。
一句话总结：别人给 AI 加装备，它给 AI 减负担。减到底，AI 反而发挥得更好。
第 2 章 三个概念先懂（2 分钟）
正式动手前，把三个词过一遍，后面全是顺水推舟：
概念：Agent；人话解释：能自己动手干活的人工智能，不只是聊天，还能读写文件、运行命令；类比：一个会写代码的员工
概念：模型（Model）；人话解释：Agent 的"大脑"，负责理解和思考；类比：员工的大脑
概念：Token；人话解释：AI 计费的"字数"，中文约 1 个字 ≈ 1-2 个 token；类比：电费，用得越多越贵
概念：上下文（Context）；人话解释：AI 一次能记住的内容总量；类比：员工的办公桌，越大能摊开的东西越多
Pi 本质：一个让你用一句话指挥"会写代码的员工"的终端工具。 它负责调度模型、读写文件、执行命令，把"说人话"翻译成"干活"。
第 3 章 安装 Pi：三选一，都很简单
Pi 本体是一个 npm 包，装好后全局可用。三种方式任选：
方式一：Windows 一键脚本（推荐）
桌面空白处点右键 、 "在终端中打开"。 粘贴这条命令，回车：
powershell -c "irm https://pi.dev/install.ps1 | iex"如果提示需要 Node.js 或 Git，输入 y让它自动装（Pi 依赖 Node.js 运行）。- 关掉当前窗口，重新打开一个终端
（这步不能省，新装的命令才生效）。 输入 pi回车，出现对话界面即成功。
方式二：Mac / Linux 一键脚本
打开"终端"，粘贴：
curl -fsSL https://pi.dev/install.sh | sh装完重新开终端，输入 pi。
方式三：npm 全局安装（任何系统）
已经装了 Node.js（建议 LTS 版本）的话：
npm install -g --ignore-scripts @earendil-works/pi-coding-agent然后 cd 到你的项目目录，输入 pi 启动。
pi --version 能看到版本号，就说明装好了。
第 4 章 配置模型：给 Pi 装上"大脑"
装好只是空壳，得先配一个模型。两种方式，二选一。
方式一：API Key（按量付费，灵活）
启动 Pi，输入 /login回车。选 API key 那一项。 国内直连推荐 DeepSeek（便宜、稳定）：打开 DeepSeek 开放平台 、 注册充值 、 "API keys"里创建一个 key，复制。 回到 Pi 把 key 粘贴进去，按提示完成。 打个招呼测试。Pi 回复了 = 配置成功。
/login：先 export DEEPSEEK_API_KEY=sk-xxx 再启动 Pi，等价。方式二：订阅账号（包月党）
/login选 Sign in with account。 选你的订阅：Claude Pro/Max、ChatGPT Plus/Pro（Codex）、GitHub Copilot 都支持。 浏览器弹窗登录，登录完回 Pi。 按 Ctrl + L打开模型选择器，看到你的订阅模型。
日常切模型的三个快捷键
操作：打开模型选择器；快捷键 / 命令：Ctrl + L 或 /model
操作：循环切换常用模型；快捷键 / 命令：Ctrl + P（后退 Shift + Ctrl + P）
操作：调整思考强度（省不省钱就看它）；快捷键 / 命令：Shift + Tab 循环：off 、 minimal 、 low 、 medium 、 high 、 xhigh 、 max
省钱口诀：简单任务用便宜模型 + 低思考强度；复杂任务再上贵模型。对话中途随时切，不丢上下文。
第 5 章 基础操作：学会"使唤"它
5.1 建项目文件夹（工作地点）
新建文件夹，比如 family-ledger（建议全英文名，省得以后踩坑）。右键文件夹 、 "在终端中打开" 、 输入 pi回车。窗口顶部显示这个文件夹的路径，这就是 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 用截图提需求（不用打一个字）
觉得界面丑？比如想让"结余"数字更醒目：
浏览器里截图。 回到 Pi，Windows 按 Alt + V、Mac 按Ctrl + V粘贴图片。输入"结余数字要大、用绿色显示"。 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。先上路，再谈车技。
---
