# Pi 用户手册

> pi 终端编码智能体的完整中文手册：安装、提供商配置、扩展与技能、SDK 与各平台设置。

---

LLMS 索引： [llms.txt](/llms.txt)

---

Pi 是一个极简的终端编码智能体框架。它的核心保持小巧，通过 TypeScript 扩展、技能、提示词模板、主题和 pi 包来扩展能力。

本手册翻译自 [pi 官方文档](https://github.com/earendil-works/pi/tree/main/packages/coding-agent/docs)。

## 快速开始 {#quick-start}

使用 npm 安装 Pi：

```bash
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
```

`--ignore-scripts` 会在安装过程中禁用依赖的生命周期脚本。pi 在常规 npm 安装下不需要执行安装脚本。

在 Linux 或 macOS 上，也可以使用安装脚本：

```bash
curl -fsSL https://pi.dev/install.sh | sh
```

卸载 pi 本体时（无论当初用 curl 还是 npm 安装），使用 npm：

```bash
npm uninstall -g @earendil-works/pi-coding-agent
```

如果使用 pnpm、Yarn 或 Bun 安装，请使用对应的全局卸载命令：`pnpm remove -g @earendil-works/pi-coding-agent`、`yarn global remove @earendil-works/pi-coding-agent` 或 `bun uninstall -g @earendil-works/pi-coding-agent`。

然后在项目目录中运行：

```bash
pi
```

订阅制提供商通过 `/login` 完成认证，或在启动 pi 前设置 API 密钥（例如 `ANTHROPIC_API_KEY`）。

完整的首次运行流程参见[快速开始](/book/pi/quickstart/)。

## 目录 {#contents}

- [1 快速开始](/book/pi/quickstart/)
- [2 使用 Pi](/book/pi/usage/)
- [3 提供商](/book/pi/providers/)
- [4 llama.cpp](/book/pi/llama-cpp/)
- [5 安全](/book/pi/security/)
- [6 容器化](/book/pi/containerization/)
- [7 设置](/book/pi/settings/)
- [8 快捷键](/book/pi/keybindings/)
- [9 会话](/book/pi/sessions/)
- [10 上下文压缩与分支摘要](/book/pi/compaction/)
- [11 扩展](/book/pi/extensions/)
- [12 技能](/book/pi/skills/)
- [13 提示词模板](/book/pi/prompt-templates/)
- [14 主题](/book/pi/themes/)
- [15 Pi 包](/book/pi/packages/)
- [16 自定义模型](/book/pi/models/)
- [17 自定义提供商](/book/pi/custom-provider/)
- [18 环境变量](/book/pi/environment-variables/)
- [19 会话文件格式](/book/pi/session-format/)
- [20 SDK](/book/pi/sdk/)
- [21 RPC 模式](/book/pi/rpc/)
- [22 JSON 事件流模式](/book/pi/json/)
- [23 TUI 组件](/book/pi/tui/)
- [24 Windows 配置](/book/pi/windows/)
- [25 Termux（Android）配置](/book/pi/termux/)
- [26 tmux 配置](/book/pi/tmux/)
- [27 终端配置](/book/pi/terminal-setup/)
- [28 Shell 别名](/book/pi/shell-aliases/)
- [29 开发](/book/pi/development/)

---

本节页面：

- [快速开始](/book/pi/quickstart/): 从安装、登录认证到完成第一个 pi 会话的完整入门流程。
- [使用 Pi](/book/pi/usage/): pi 的日常使用细节：交互模式、斜杠命令、会话管理、CLI 参考与设计原则。
- [提供商](/book/pi/providers/): 配置 pi 的模型提供商：订阅认证、API 密钥、云端与自定义提供商。
- [llama.cpp](/book/pi/llama-cpp/): 让 pi 通过 llama.cpp 路由服务器加载和切换多个本地 GGUF 模型。
- [安全](/book/pi/security/): pi 的本地信任模型、项目信任机制、沙箱边界与安全问题报告方式。
- [容器化](/book/pi/containerization/): 介绍以容器、微虚拟机或沙箱隔离运行 pi 的四种模式与配置要点。
- [设置](/book/pi/settings/): pi 的 JSON 设置文件：全局与项目设置、模型、界面、压缩、重试等全部选项说明。
- [快捷键](/book/pi/keybindings/): 自定义 pi 的全部键盘快捷键：按键格式、动作清单与 Emacs/Vim 配置示例。
- [会话](/book/pi/sessions/): 会话的自动保存、恢复、命名、树状分支结构与常用管理命令。
- [上下文压缩与分支摘要](/book/pi/compaction/): pi 如何在上下文超限时自动压缩并总结被放弃的分支，以及通过扩展自定义摘要。
- [扩展](/book/pi/extensions/): 讲解 pi 扩展的开发：事件订阅、自定义工具与命令、UI 交互和会话控制。
- [技能](/book/pi/skills/): 技能的加载位置、工作原理、SKILL.md 结构、frontmatter 字段与校验规则。
- [提示词模板](/book/pi/prompt-templates/): 用 Markdown 片段定义可通过 /name 调用的提示词模板，支持参数与默认值。
- [主题](/book/pi/themes/): 用 JSON 文件定义 pi TUI 的配色：主题格式、颜色令牌、取值方式与创建技巧。
- [Pi 包](/book/pi/packages/): pi 包的安装管理、三种来源、创建方法、目录结构、依赖与过滤配置。
- [自定义模型](/book/pi/models/): 通过 ~/.pi/agent/models.json 添加自定义提供商与模型，配置兼容性与逐模型覆盖。
- [自定义提供商](/book/pi/custom-provider/): 用扩展的 pi.registerProvider() 注册自定义提供商、OAuth 登录与自定义流式 API。
- [环境变量](/book/pi/environment-variables/): pi 读取的配置变量、进程标记，以及注入 shell 工具的会话环境变量。
- [会话文件格式](/book/pi/session-format/): 会话 JSONL 文件的存储结构：条目类型、消息类型、树形结构与解析示例。
- [SDK](/book/pi/sdk/): 通过 SDK 以编程方式调用 pi 的智能体能力，将 pi 嵌入应用、构建自定义界面与自动化集成。
- [RPC 模式](/book/pi/rpc/): 介绍如何通过 stdin/stdout 上的 JSON 协议以无头方式驱动 pi 编码智能体。
- [JSON 事件流模式](/book/pi/json/): 以 JSON Lines 输出 pi 会话事件，便于将 pi 集成到其他工具或自定义界面。
- [TUI 组件](/book/pi/tui/): 介绍 pi 的 TUI 组件系统：组件接口、IME 支持、覆盖层、内置组件及键盘鼠标输入。
- [Windows 配置](/book/pi/windows/): pi 在 Windows 上默认使用 Git Bash，也可改用 PowerShell 工具运行命令。
- [Termux（Android）配置](/book/pi/termux/): 在 Android 的 Termux 环境中安装并运行 pi，含剪贴板与存储权限说明。
- [tmux 配置](/book/pi/tmux/): 在 tmux 中正确传递 Shift+Enter、Ctrl+Enter 等修饰键的推荐配置。
- [终端配置](/book/pi/terminal-setup/): 各终端模拟器对 Kitty 键盘协议的支持情况与按键配置方法。
- [Shell 别名](/book/pi/shell-aliases/): 让 pi 在非交互式 bash 中启用你的 shell 别名的配置方法。
- [开发](/book/pi/development/): 从源码构建与测试 pi，涵盖 fork 品牌重塑、路径解析与项目结构。

---

反链：

- [Pi 的运行机制与原理](/blog/post/pi-internals/)
- [书籍](/book/)