DOCUMENT 01 · 搭建 · 部署 · 使用

从安装到第一条对话

本文覆盖 pi 的用户视角：安装方式、Provider 接入、交互模式核心操作、会话与分支模型、Compaction、Settings、上下文文件、Pi Packages 包管理、完整 CLI 参考。读完这一篇，你可以把 pi 当成日常工具使用。

■ 安装

平台	注意点
macOS · Linux	原生支持，Node ≥18 即可
Windows	推荐 Windows Terminal；`Alt+Enter` 默认是全屏，需在终端设置里改键位（见 docs/terminal-setup.md）
Termux (Android)	可跑，见 docs/termux.md
tmux	OSC 序列与键位有专门适配，见 docs/tmux.md

■ Providers 与认证

pi 把"Provider 接入"和"模型选择"分两步：先 /login 或注入环境变量绑定凭证，再 /model 切模型。Provider 列表硬编码并随每个版本更新；自定义 Provider 走 extension。

三类接入方式

订阅 · Subscription

用 OAuth 复用你已有的会员账号。命令：/login 后选 provider。

Anthropic Claude Pro/Max

OpenAI ChatGPT Plus/Pro (Codex)

GitHub Copilot

API Key

导出环境变量或在 /login 里粘贴。20+ 内置 Provider：

Anthropic

OpenAI

Azure OpenAI

DeepSeek

Google Gemini · Vertex

Amazon Bedrock

Mistral

Groq · Cerebras

xAI · OpenRouter

Cloudflare AI Gateway

Vercel AI Gateway

ZAI · Hugging Face

Fireworks · Together AI

Kimi For Coding · MiniMax

Xiaomi MiMo (CN/AMS/SG)

自定义 Provider

在 ~/.pi/agent/models.json 添加（只要协议是 OpenAI / Anthropic / Google 兼容即可）；OAuth 或全新协议走 extension。详见 docs/models.md、docs/custom-provider.md。

■ 交互模式

默认模式。界面从上到下：启动头（加载的 AGENTS.md / 模板 / skills / extensions）→ 消息流 → 编辑器 → 状态栏（cwd / session / token / cost / context% / 当前模型）。

编辑器

功能	键位
文件引用（fuzzy 搜索）	输入 `@`
路径补全	Tab
多行	Shift+Enter（Windows: Ctrl+Enter）
粘贴图片	Ctrl+V（Windows: Alt+V），也可拖拽到终端
跑 bash 并发给模型	`!command`
跑 bash 不发给模型	`!!command`

斜杠命令（/）

命令	作用
`/login` · `/logout`	Provider OAuth 登录/登出
`/model`	切换模型（也可 Ctrl+L）
`/scoped-models`	设置 Ctrl+P 可循环切换的模型范围
`/settings`	thinking level / 主题 / 消息投递 / transport
`/resume` · `/new`	选历史会话恢复 / 新建会话
`/tree` · `/fork` · `/clone`	会话树跳点 / 从某轮分叉 / 复制当前 active branch
`/compact [指令]`	手动压缩上下文，可附加自定义指令
`/copy`	把最后一条 assistant 消息复制到剪贴板
`/export [file]`	把会话导出成可分享 HTML
`/share`	上传为私密 GitHub Gist，返回分享链接
`/reload`	重载 keybindings / extensions / skills / prompts / context
`/hotkeys`	看完整快捷键

关键快捷键

键位	作用
Ctrl+C	清空编辑器
Ctrl+C × 2	退出
Escape	取消当前请求
Escape × 2	打开 `/tree`
Ctrl+L	模型选择器
Ctrl+P / Shift+Ctrl+P	循环 scoped models
Shift+Tab	切换 thinking level
Ctrl+O / Ctrl+T	折叠/展开 tool 输出 / thinking 块

消息队列（边跑边输入）

Enter：steering（当前 turn 结束后投递）
Alt+Enter：follow-up（整轮全部完成后才投递）
Escape：取消并把队列恢复到编辑器
Alt+Up：把队列消息拿回编辑器修改

■ 会话 · 分支 · 压缩

pi 的会话本质是 JSONL 文件，每行带 id 与 parentId——是一棵树，不是一条线。分支不开新文件，全部 in-place。

存放位置

~/.pi/agent/sessions/<按 cwd 组织>/<session-id>.jsonl

命令行入口

命令	作用
`pi -c`	继续最近会话
`pi -r`	浏览选历史会话
`pi --no-session`	临时会话，不落盘
`pi --session <path\|id>`	指定会话文件或 ID 继续
`pi --fork <path\|id>`	从指定会话/ID 直接 fork 一份新会话

/tree · 在树上跳来跳去

在 /tree 视图里：搜索（直接打字）→ 折叠/跳分支（Ctrl+← / →）→ 翻页（← / →）→ 过滤模式循环（Ctrl+O：默认 → 无工具 → 仅用户 → 仅 labeled → 全部）→ Shift+L 给消息打书签 → Shift+T 切时间戳显示。

Compaction · 上下文压缩

长会话快撑爆上下文时，pi 自动总结老消息、保留近期。手动：/compact 或 /compact <自定义指令>。自动：默认开启，分为"溢出后恢复"和"接近上限提前压"两种触发器。

注意 · Compaction 是有损的——但原始 JSONL 完整保留，/tree 随时可以回去看真实历史。压缩算法可被 extension 完整替换（见 03 文档 Compaction 一节）。

■ Settings

位置	作用域
`~/.pi/agent/settings.json`	全局（所有项目）
`.pi/settings.json`	项目（覆盖全局）

用 /settings 改常用项，或直接编辑 JSON。完整字段见 docs/settings.md。

启动期网络行为（可关）

开关	说明
`PI_SKIP_VERSION_CHECK=1`	不检查新版本
`PI_TELEMETRY=0` 或 `enableInstallTelemetry: false`	关安装/更新匿名上报
`--offline` · `PI_OFFLINE=1`	关闭所有启动期网络（含上面两项）

■ Context Files & System Prompt

启动时 pi 会按以下顺序拼接 AGENTS.md（或 CLAUDE.md）：

~/.pi/agent/AGENTS.md          (全局)
<cwd 一路向上>/AGENTS.md       (各级父目录)
<cwd>/AGENTS.md                (当前目录)

用 --no-context-files / -nc 关闭。要替换默认 System Prompt，写 .pi/SYSTEM.md（项目）或 ~/.pi/agent/SYSTEM.md（全局）；追加用 APPEND_SYSTEM.md。

■ Pi Packages

把 Extensions / Skills / Prompts / Themes 打成包，从 npm 或 git 安装。

pi install npm:@foo/pi-tools
pi install npm:@foo/pi-tools@1.2.3        # 锁版本
pi install git:github.com/user/repo
pi install git:github.com/user/repo@v1    # 锁 tag/commit
pi install ssh://git@github.com/user/repo@v1
pi install https://github.com/user/repo@v1

pi install ... -l         # 项目级（.pi/git/ · .pi/npm/）
pi remove npm:@foo/pi-tools
pi list
pi update                 # 更新 pi 本体 + 所有未锁定包
pi update --extensions    # 只更新包
pi update --self          # 只更新 pi 本体
pi config                 # 启用/禁用某个 extension/skill/prompt/theme

⚠ 安全提醒 · pi 包以完整系统权限运行：extension 是任意代码，skill 可指挥模型执行任意操作。装第三方包前看一眼源码。

自己写一个包

{
  "name": "my-pi-package",
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./extensions"],
    "skills": ["./skills"],
    "prompts": ["./prompts"],
    "themes": ["./themes"]
  }
}

没有 pi 字段时，pi 会按约定目录自动发现（extensions/、skills/、prompts/、themes/）。

■ CLI 参考

pi [options] [@files...] [messages...]

常用参数	作用
`-p, --print`	print 模式，一次性输出
`--mode rpc`	RPC stdio 模式（JSONL 协议，见 03 文档）
`-c, --continue`	继续最近会话
`-r, --resume`	选历史会话
`--session <id>`	指定会话 ID 继续
`--fork <id>`	从指定会话 fork
`--no-session`	不落盘
`-nc, --no-context-files`	不加载 AGENTS.md
`--offline`	不做启动期网络请求

下一篇 → 02 · 架构 · 模块 · 文件结构：进入 src，理解 pi 的五层骨架与 Extension/Skill/Prompt/Theme 模型。