快速上手

相关源文件

本页面内容基于以下源文件生成：

• README.md
• CONTRIBUTING.md
• package.json
• packages/coding-agent/README.md
• test.sh
• pi-test.sh
• packages/ai/src/providers/google-gemini-cli.ts
• packages/ai/src/providers/google.ts
• packages/ai/src/providers/mistral.ts
• packages/ai/src/providers/anthropic.ts

Pi 是一个极简的终端编码工具集，支持通过 TypeScript 扩展、技能、提示模板和主题进行高度定制。该项目采用 monorepo 架构，包含多个核心包：统一的多提供商 LLM API、Agent 运行时、交互式编码代理 CLI 等。

环境要求

Pi 项目对运行环境有以下要求：

操作系统支持方面，项目提供了多个平台说明文档：Windows、Termux (Android)、tmux 以及终端设置指南 (packages/coding-agent/README.md:81)。

安装与认证

全局安装

最简单的安装方式是通过 npm 全局安装 pi coding agent：

bash
1npm install -g @mariozechner/pi-coding-agent

安装完成后，需要进行身份认证。Pi 支持两种认证方式：API Key 和 OAuth 订阅登录 (packages/coding-agent/README.md:59-80)。

API Key 认证

使用 API Key 认证时，需要设置相应的环境变量：

bash
1export ANTHROPIC_API_KEY=sk-ant-...
2pi

OAuth 订阅登录

如果已有订阅账户，可以使用 OAuth 登录方式：

bash
1pi
2/login  # 然后选择提供商

支持的提供商

Pi 支持多种订阅服务和 API Key 提供商 (packages/coding-agent/README.md:85-116)：

订阅服务：

• Anthropic Claude Pro/Max
• OpenAI ChatGPT Plus/Pro (Codex)
• GitHub Copilot
• Google Gemini CLI
• Google Antigravity

API Key 提供商：

• Anthropic
• OpenAI
• Azure OpenAI
• Google Gemini
• Google Vertex
• Amazon Bedrock
• Mistral
• Groq
• Cerebras
• xAI
• OpenRouter
• Vercel AI Gateway
• ZAI
• OpenCode Zen
• OpenCode Go
• Hugging Face
• Kimi For Coding
• MiniMax

基本使用

交互模式界面

启动 pi 后进入交互模式，界面从上到下包含以下组成部分 (packages/coding-agent/README.md:122-134)：

• 启动头部：显示快捷键、已加载的 AGENTS.md 文件、提示模板、技能和扩展
• 消息区域：用户消息、助手响应、工具调用和结果、通知、错误和扩展 UI
• 编辑器：输入区域，边框颜色表示思考级别
• 页脚：工作目录、会话名称、总 token/缓存使用量、成本、上下文使用率、当前模型

默认工具集

默认情况下，pi 为模型提供四个工具：read、write、edit 和 bash。模型使用这些工具来执行用户的请求 (packages/coding-agent/README.md:79)。

编辑器功能

编辑器支持多种便捷功能 (packages/coding-agent/README.md:135-146)：

常用命令

在编辑器中输入 / 可触发命令 (packages/coding-agent/README.md:147-171)：

会话管理

会话存储结构

会话以 JSONL 文件形式存储，具有树形结构。每个条目包含 id 和 parentId，支持就地分支而无需创建新文件 (packages/coding-agent/README.md:205-208)。

会话自动保存到 ~/.pi/agent/sessions/ 目录，按工作目录组织 (packages/coding-agent/README.md:210-211)。

会话管理命令

bash
1pi -c                  # 继续最近的会话
2pi -r                  # 浏览并选择过去的会话
3pi --no-session        # 临时模式（不保存）
4pi --session <path>    # 使用指定的会话文件或 ID

开发环境配置

从源码构建

对于开发者或需要从源码运行 pi 的场景，需要先克隆仓库并安装依赖 (README.md:48-56)：

bash
1npm install          # 安装所有依赖
2npm run build        # 构建所有包
3npm run check        # 代码检查、格式化和类型检查
4./test.sh            # 运行测试（无 API Key 时跳过 LLM 相关测试）
5./pi-test.sh         # 从源码运行 pi（必须从仓库根目录运行）

重要提示：npm run check 需要先运行 npm run build。web-ui 包使用 tsc，需要依赖项编译后的 .d.ts 文件 (README.md:58)。

测试脚本说明

测试脚本 test.sh 会在运行前备份现有的认证文件，并取消设置所有 API Key 环境变量，以确保测试环境的隔离性 (test.sh:4-38)：

bash
1# 脚本会处理的环境变量
2unset ANTHROPIC_API_KEY
3unset ANTHROPIC_OAUTH_TOKEN
4unset OPENAI_API_KEY
5unset GEMINI_API_KEY
6unset GROQ_API_KEY
7unset CEREBRAS_API_KEY
8unset XAI_API_KEY
9unset OPENROUTER_API_KEY
10unset ZAI_API_KEY
11unset MISTRAL_API_KEY
12# ... 更多 API Key

常见问题与排错

问题 1：Node.js 版本不兼容

症状：安装或运行时报错，提示 Node.js 版本不满足要求。

解决方案：确保 Node.js 版本 >= 20.0.0。可以使用 nvm 或 fnm 等版本管理器切换 Node.js 版本：

bash
1# 使用 nvm
2nvm install 20
3nvm use 20
4
5# 使用 fnm
6fnm install 20
7fnm use 20

问题 2：npm run check 失败

症状：运行 npm run check 时出现类型错误或找不到 .d.ts 文件。

解决方案：根据项目说明，npm run check 需要先运行 npm run build (README.md:58)：

bash
1npm run build
2npm run check

问题 3：从源码运行 pi 失败

症状：执行 ./pi-test.sh 时报错或无法启动。

解决方案：确保从仓库根目录运行该脚本 (README.md:55)。如果当前不在根目录：

bash
1cd /path/to/pi-mono
2./pi-test.sh

问题 4：API Key 未生效

症状：设置了环境变量但仍然无法认证。

解决方案：检查环境变量名称是否正确。测试脚本中列出了所有支持的环境变量名称 (test.sh:25-38)。确保使用正确的变量名，例如 ANTHROPIC_API_KEY 而非 ANTHROPIC_KEY。

问题 5：提交 PR 前检查未通过

症状：贡献代码时 CI 检查失败。

解决方案：在提交 PR 前确保本地检查通过 (CONTRIBUTING.md:27-30)：

bash
1npm run check  # 必须无错误通过
2./test.sh      # 必须通过

下一步建议

完成快速上手后，可以进一步探索以下内容：

1. 提供商详细配置：参阅 docs/providers.md 了解各提供商的详细设置说明（需要确认）

2. 自定义模型配置：通过 ~/.pi/agent/models.json 添加自定义提供商，或使用扩展支持自定义 API 和 OAuth（需要确认）

3. 扩展与技能开发：了解如何通过 TypeScript 扩展、技能、提示模板和主题来定制 pi 的工作流程

4. 会话高级功能：探索会话分支、压缩等功能，优化长时间对话的上下文管理

5. 键盘快捷键定制：通过 ~/.pi/agent/keybindings.json 自定义键盘快捷键（需要确认）