Pi 详细使用指南

Pi - AI 编程助手，支持读取文件、执行命令、编辑代码等多种功能

---

📋 目录

1. 基本介绍
2. 命令行用法
3. 子命令详解
4. 选项参数
5. 使用模式
6. 工具介绍
7. 模型配置
8. 环境变量
9. 实用示例

---

基本介绍

Pi 是一款强大的 AI 编程助手，通过命令行交互帮助开发者完成各种编程任务。它支持多种 AI 模型（Google Gemini、OpenAI GPT、Anthropic Claude 等），并提供文件读取、命令执行、代码编辑等核心工具。

核心特性

• 🤖 支持多种 AI 提供商和模型
• 📁 文件读取与编辑
• 💻 Bash 命令执行
• 🔄 会话管理（断点续传）
• 🧩 扩展系统
• 🎨 主题支持
• 🔧 技能系统

---

命令行用法

pi [选项] [@文件...] [消息...]

基本语法

# 交互式模式
pi

# 带初始提示的交互式模式
pi "列出 src/ 目录下所有的 .ts 文件"

# 非交互式模式（执行后退出）
pi -p "列出 src/ 目录下所有的 .ts 文件"

# 包含文件作为输入
pi @prompt.md @image.png "天空是什么颜色的？"

# 多条消息
pi "读取 package.json" "我们有哪些依赖？"

---

子命令详解

扩展管理命令

命令	说明	示例
pi install	安装扩展	pi install ./my-extension
pi remove	移除扩展	pi remove ./my-extension
pi uninstall	移除扩展的别名	pi uninstall ./my-extension
pi update [source]	更新扩展	pi update
pi list	列出已安装扩展	pi list
pi config	打开配置界面	pi config

选项说明：

• -l 或 --local：仅本地安装，不添加到全局设置

---

选项参数

模型配置选项

选项	说明	示例
--provider	设置 AI 提供商	--provider openai
--model	设置模型（支持 provider/id 格式）	--model gpt-4o-mini 或 --model openai/gpt-4o
--api-key	手动指定 API Key	--api-key sk-xxx
--thinking	设置思考级别	--thinking high

思考级别说明：

• off - 关闭思考
• minimal - 最小思考
• low - 低级别
• medium - 中级别
• high - 高级别
• xhigh - 极高级别

模型简写格式：

# 使用 provider/id 格式
pi --model openai/gpt-4o "帮我重构代码"

# 使用思考级别简写
pi --model sonnet:high "解决这个复杂问题"

会话管理选项

选项	说明	示例
--continue, -c	继续上一个会话	pi -c "我们刚才讨论了什么？"
--resume, -r	选择要恢复的会话	pi -r
--session	指定会话文件	pi --session ./my-session.jsonl
`–session-dir
`	指定会话存储目录	pi --session-dir ./sessions
--no-session	不保存会话（临时模式）	pi --no-session

系统提示选项

选项	说明	示例
--system-prompt	设置系统提示词	--system-prompt "你是一个Python专家"
--append-system-prompt	追加系统提示词内容	--append-system-prompt @custom.txt

工具控制选项

选项	说明	示例
--tools	启用指定工具	--tools read,bash,edit,write
--no-tools	禁用所有内置工具	pi --no-tools

可用工具列表：

• read - 读取文件内容
• bash - 执行 Bash 命令
• edit - 编辑文件（查找替换）
• write - 写入文件（创建/覆盖）
• grep - 搜索文件内容（只读，默认关闭）
• find - 通过 glob 模式查找文件（只读，默认关闭）
• ls - 列出目录内容（只读，默认关闭）

只读模式示例：

# 只读模式，无法修改文件
pi --tools read,grep,find,ls -p "审查 src/ 目录下的代码"

多模型切换选项

选项	说明	示例
--models	设置可循环切换的模型列表	--models claude-sonnet,claude-haiku,gpt-4o

支持：

• 逗号分隔的模型列表
• Glob 模式（如 anthropic/*, *sonnet*）
• 模糊匹配
• 固定思考级别（如 sonnet:high）

# 限制在特定提供商
pi --models "github-copilot/*"

# 指定多个模型并固定思考级别
pi --models sonnet:high,haiku:low

扩展与技能选项

选项	说明	示例
--extension, -e	加载扩展文件（可多次使用）	-e ./ext.js -e ./another.js
--no-extensions, -ne	禁用扩展发现	pi -ne
--skill	加载技能文件或目录	--skill ./my-skill
--no-skills, -ns	禁用技能发现和加载	pi -ns
--prompt-template	加载提示模板	--prompt-template ./templates
--no-prompt-templates, -np	禁用提示模板发现	pi -np
--theme	加载主题文件	--theme ./my-theme
--no-themes	禁用主题发现	pi --no-themes

输出与导出选项

选项	说明	示例
--mode	输出模式：text/json/rpc	--mode json
--print, -p	非交互模式（执行后退出）	pi -p "分析代码"
--export	导出会话到 HTML	--export session.jsonl

其他选项

选项	说明	示例
--list-models [search]	列出可用模型（可搜索）	--list-models gpt
--verbose	强制详细启动输出	--verbose
--offline	禁用启动网络操作	--offline
--help, -h	显示帮助	--help
--version, -v	显示版本	--version

---

使用模式

1. 交互式模式（默认）

# 进入交互式对话
pi

# 带初始问题进入
pi "帮我分析这段代码"

# 包含多个文件
pi @file1.js @file2.js "比较这两个文件"

2. 非交互式模式

使用 -p 或 --print 参数，执行后自动退出：

pi -p "列出所有 .ts 文件"

# 结合其他选项
pi -p --model gpt-4o-mini "快速分析问题"

3. 会话恢复模式

# 继续上次会话
pi --continue

# 继续并添加新问题
pi -c "我们刚才说到哪了？"

# 选择要恢复的会话
pi --resume

---

工具介绍

read - 读取文件

读取文件内容，支持文本文件和图片（jpg, png, gif, webp）。

参数：

• path - 文件路径
• offset - 起始行号（1-based）
• limit - 最大读取行数

使用场景：

• 读取代码文件分析
• 读取配置文件
• 查看图片内容

bash - 执行命令

执行 Bash 命令，支持设置超时。

参数：

• command - 要执行的命令
• timeout - 超时时间（秒）

使用场景：

• 列出文件目录
• 运行测试命令
• 检查系统状态
• Git 操作

edit - 编辑文件

通过查找替换精确编辑文件。

参数：

• path - 文件路径
• oldText - 要查找的文本（必须完全匹配）
• newText - 替换的新文本

特点：

• 精确匹配（包括空格）
• 适合小范围精确修改

write - 写入文件

创建新文件或覆盖现有文件。

参数：

• path - 文件路径
• content - 文件内容

特点：

• 自动创建父目录
• 完全覆盖模式

---

模型配置

支持的提供商

提供商	环境变量	说明
Google (默认)	GEMINI_API_KEY	Gemini 系列模型
OpenAI	OPENAI_API_KEY	GPT 系列模型
Anthropic	ANTHROPIC_API_KEY / ANTHROPIC_OAUTH_TOKEN	Claude 系列模型
Azure OpenAI	AZURE_OPENAI_API_KEY	Azure 托管的 OpenAI
Groq	GROQ_API_KEY	高速推理
Cerebras	CEREBRAS_API_KEY	专用硬件推理
xAI	XAI_API_KEY	Grok 模型
OpenRouter	OPENROUTER_API_KEY	多模型聚合
Mistral	MISTRAL_API_KEY	Mistral 模型
MiniMax	MINIMAX_API_KEY	MiniMax 模型
Amazon Bedrock	AWS_*	AWS 托管模型
其他	详见环境变量	…

常用模型示例

# Google Gemini
pi --provider google --model gemini-2.0-flash

# OpenAI GPT-4o
pi --provider openai --model gpt-4o

# Anthropic Claude
pi --provider anthropic --model claude-3-5-sonnet

# 使用 provider/id 格式
pi --model openai/gpt-4o-mini
pi --model anthropic/claude-3-haiku

# 使用思考级别
pi --model sonnet:high "复杂问题"
pi --model haiku:low "简单问题"

---

环境变量

API Key 配置

# OpenAI
export OPENAI_API_KEY="sk-..."

# Google Gemini
export GEMINI_API_KEY="..."

# Anthropic Claude
export ANTHROPIC_API_KEY="sk-ant-..."
# 或 OAuth Token
export ANTHROPIC_OAUTH_TOKEN="..."

# Azure OpenAI
export AZURE_OPENAI_API_KEY="..."
export AZURE_OPENAI_BASE_URL="https://{resource}.openai.azure.com/openai/v1"
export AZURE_OPENAI_RESOURCE_NAME="..."
export AZURE_OPENAI_API_VERSION="v1"
export AZURE_OPENAI_DEPLOYMENT_NAME_MAP="gpt-4o=my-deployment"

# 其他提供商...
export GROQ_API_KEY="..."
export CEREBRAS_API_KEY="..."
export XAI_API_KEY="..."
export OPENROUTER_API_KEY="..."
export MISTRAL_API_KEY="..."
export MINIMAX_API_KEY="..."

AWS Bedrock 配置

export AWS_PROFILE="my-profile"
export AWS_ACCESS_KEY_ID="..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_BEARER_TOKEN_BEDROCK="..."
export AWS_REGION="us-east-1"

Pi 专用配置

# 会话存储目录（默认：~/.pi/agent）
export PI_CODING_AGENT_DIR="/custom/path"

# 覆盖包目录（用于 Nix/Guix）
export PI_PACKAGE_DIR="/nix/store/..."

# 禁用启动网络操作
export PI_OFFLINE=1

# 分享链接基础 URL
export PI_SHARE_VIEWER_URL="https://pi.dev/session/"

# 覆盖 Antigravity User-Agent 版本
export PI_AI_ANTIGRAVITY_VERSION="1.23.0"

---

实用示例

基础用法

# 启动交互式会话
pi

# 分析特定文件
pi "读取 src/main.js 并解释它的功能"

# 非交互式分析
pi -p "检查 package.json 的依赖版本"

文件操作

# 读取多个文件并比较
pi @file1.js @file2.js "找出这两个文件的差异"

# 批量分析
pi @src/*.ts "总结这些文件的主要功能"

代码审查

# 只读模式安全审查
pi --tools read,grep,find,ls -p "审查 src/ 目录的代码质量"

# 带模型的审查
pi --model claude-sonnet -p "检查这段代码的潜在问题" @code.js

使用不同模型

# 使用轻量级模型处理简单任务
pi --model gpt-4o-mini -p "格式化这段 JSON"

# 使用高级模型处理复杂任务
pi --thinking high "设计一个系统架构"

# 快速切换模型
pi --models sonnet,haiku,gpt-4o
# 然后按 Ctrl+P 在模型间切换

会话管理

# 开始一个长期项目会话
pi --session-dir ./project-sessions "开始分析项目"

# 第二天继续
pi --resume
# 或
pi -c "继续昨天的工作"

# 临时会话（不保存）
pi --no-session "临时查询"

扩展和主题

# 加载自定义扩展
pi -e ./my-extension.js -e ./another-ext.js

# 禁用所有扩展
pi -ne

# 加载自定义主题
pi --theme ./dark-theme.yaml

# 加载技能
pi --skill ./my-skill

导出会话

# 导出为 HTML
pi --export ~/.pi/agent/sessions/xxx/session.jsonl

# 指定输出文件
pi --export session.jsonl output.html

---

💡 最佳实践

1. 会话管理：对于长期项目，使用 --session-dir 组织会话文件
2. 模型选择：简单任务用轻量级模型，复杂任务用高级模型
3. 只读模式：审查代码时使用 --tools read,grep,find,ls 防止意外修改
4. 环境变量：将 API Key 存储在环境变量或 .env 文件中
5. 非交互模式：脚本化任务使用 -p 参数
6. 扩展系统：善用扩展和技能系统增强功能

---

🆘 获取帮助

# 查看完整帮助
pi --help

# 查看特定命令帮助
pi install --help
pi remove --help

# 列出可用模型
pi --list-models

# 搜索特定模型
pi --list-models gpt

---