安装 pi 与分支会话管理技巧
上一节介绍了 pi 的定位（20-03）：极简 harness、按需装扩展、省 token。这节实操：三种安装方式、第三方模型端点配置、给全局 skills 瘦身，以及 pi 最有特色的能力——会话树（/tree）分支管理，最后用 git 自动提交扩展把"会话回退"升级成"会话+代码一起回退"。
一、安装：三种方式按平台选
pi 适合极客、独立开发者和对预算敏感的用户（20-03 已述）。安装方式与 Claude Code / Codex 一样走 npm，也提供官方安装脚本：
# macOS / Linux：官方安装脚本（锁定依赖版本，支持 pi update 升级）
curl -fsSL https://pi.dev/install.sh | sh
# 或 npm 安装（不锁定传递依赖，要求 Node.js 22.19+）
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
# Nix（macOS/Linux，从源码构建）
nix profile add github:earendil-works/pi/stable
bash
Windows 用户使用官方 PowerShell 安装脚本（见 pi.dev 文档的 Windows Setup 页），或直接走 npm 方式。安装完验证：pi --version。
踩坑：npm 方式必须加 --ignore-scripts——pi 正常安装不依赖生命周期脚本，官方命令原文如此，照抄即可。
二、配置模型：/login 或 models.json
走官方 provider：/login
pi 内置 30+ provider（含国内厂商），三种凭证方式：
# 方式一：交互登录（OAuth 或存 API key，写入 ~/.pi/agent/auth.json）
/login
# 方式二：环境变量（CI 或不想落盘时用）
export DEEPSEEK_API_KEY=sk-...
pi
# 方式三：自定义端点走 models.json（见下）
bash
国内厂商的环境变量（2026-10 官方 provider 表实核）：
| 厂商 | 环境变量 |
|---|---|
| 智谱 ZAI Coding Plan（中国站） | ZAI_CODING_CN_API_KEY |
| DeepSeek | DEEPSEEK_API_KEY |
| Moonshot/Kimi For Coding | MOONSHOT_API_KEY / KIMI_API_KEY |
| MiniMax（中国站） | MINIMAX_CN_API_KEY |
| 通义 Qwen Token Plan（中国站） | QWEN_TOKEN_PLAN_CN_API_KEY |
| 小米 MiMo Token Plan（中国站） | XIAOMI_TOKEN_PLAN_CN_API_KEY |
（各家 Coding Plan 价格见 19-01 的国内端点矩阵与 2-01 模型价格表，不重复展开。）
走第三方 OpenAI 兼容端点：编辑 models.json
如果你用的是第三方中转或自建网关（如 19-02 自建三件套），需要编辑 ~/.pi/agent/models.json。注意：首次配置时 ~/.pi/agent/ 目录可能还不存在，先创建：
mkdir -p ~/.pi/agent
bash
然后用任意编辑器创建 models.json，把示例里的 YOUR_KEY 替换成自己的 key：
{
"providers": {
"自定义名称": {
"baseUrl": "https://你的第三方端点/v1",
"apiKey": "YOUR_KEY",
"models": [
{ "id": "glm-5.3-flash", "api": "openai-completions" }
]
}
}
}
json
上面示例里 "api": "openai-completions" 对应 OpenAI Chat Completions 协议（该值为官方文档原文）；Anthropic 协议、Responses 协议同理配置。保存后启动 pi，/model 菜单里就能看到你接入的模型。
三、首次使用与 skills 瘦身
进入任意工作目录运行 pi，它会初始化环境（自动读取全局配置与项目文件），随后就能用：
/：斜线命令菜单!前缀：直接执行原生 shell 命令@前缀：搜索并引用文件
演示环境里首次会话的上下文占用明显偏高——因为 pi 初始化时把全局 Claude Code 配置里常用的 skills 全部加载了过来，工作目录下的 AGENTS.md 也会被读入。这时直接对 pi 说：
这里有很多 skills 我不常用，请按重要程度归档精简，不常用的移出自动加载。
text
pi 会读取全局配置并按它的极简哲学归档不需要的条目。完成后执行 reload（pi 支持 /reload 热重载配置），再开一条新会话发送同样内容的消息——footer 里能看到新会话的上下文占用从原来的数 K 到数十 K 量级降到约 2K。会话越多，这笔节省越可观。
pi 的 footer 会实时显示本轮发送/接收的 token 数与花费金额，每一轮对话花了多少钱清清楚楚——这一点比大多数重型工具透明得多。
四、会话树：分支管理是 pi 的招牌能力
运行 /tree 打开会话树：历史会话按树形结构呈现，回到任意历史节点按回车，pi 会询问是否对之前的会话做总结（summarize）——不需要总结就直接从该节点继续。这样可以在同一个任务的多个"如果当初"之间自由切换：从节点 A 继续探索方案一，从节点 B 继续探索方案二，互不覆盖。
关键认知：会话回退 ≠ 代码回退
pi 的回退只是让会话从所选节点继续，代码并不会跟着回退。想让代码也随会话树走，思路是给 pi 装一个 git 自动提交扩展：
- 每次 pi 改动文件后自动 commit
- 使用 /tree 回退到某个会话节点时，扩展自动
git checkout对应提交
这个扩展不用自己写——直接让 pi 自己写（这种"自己给自己写扩展"正是 pi 的玩法）。演示里对 pi 的要求是：
请为 pi 创建一个自动 git 提交的扩展：在 git 仓库内每次改动自动提交；
非 git 仓库直接跳过；提交失败时在 UI 中提示；全局生效。
text
pi 会创建一个 extension（TypeScript 文件），安装后全局生效。效果实测：
# 干净目录里初始化一个演示仓库
mkdir demo && cd demo && git init
bash
让 pi 做一轮改动 → 自动 commit；再问"Vue 3 最新特性有哪些"（本地配了 Context7 的话它会去查 Context7 而不是纯模型回答）→ 又一轮改动与提交。此时打开 /tree：
回退到"改动任务"节点，git 仓库自动 checkout 回对应位置的代码；再回退到更早节点，文件自动切换回最新状态（对应那次提交的状态）。省去了手动 git reset 找节点、对提交的麻烦——所有操作只要是提交过的都自动记录在案。
五、输入与日常操作技巧
- 多行输入：Shift+Enter 换行（主讲习惯用这个）
- 临时记事本：Ctrl+G 打开一个临时多行编辑器（适合贴长文本），Ctrl+X 退出并把内容填充回命令行
- 粘贴图片：Ctrl+V
- 继续上次会话：退出后
pi --continue恢复最近会话，或/resume选择历史会话 - 不想用 TUI：社区有若干 pi GUI（如 pi GUI），界面类似 ChatGPT / Claude 客户端，支持明暗主题，不习惯终端操作的可选装
本节小结
- 安装三选一：官方脚本（macOS/Linux）、npm（全平台，Node 22.19+，必须
--ignore-scripts）、Nix；Windows 用官方 PowerShell 脚本或 npm - 模型配置：官方 provider 用
/login或环境变量（智谱/DeepSeek/Moonshot/MiniMax/Qwen/小米均有中国站变量）；第三方 OpenAI 兼容端点写~/.pi/agent/models.json（首次需mkdir -p ~/.pi/agent） - 首次会话上下文偏大是因为全局 skills 全量加载——让 pi 自己归档精简 + reload，新会话头部可降到约 2K
/tree会话树支持回到任意节点续聊（可选 summarize），但会话回退不回退代码- 装 git 自动提交扩展（可以让 pi 自己写）后，/tree 回退自动 checkout 对应提交，会话与代码同步回退
- 操作速记：Shift+Enter 多行、Ctrl+G 记事本、Ctrl+V 贴图、
pi --continue//resume续会话
↑