Pi 文档使用说明
Pi 文档使用说明
📋 目录
- 快速开始
- 提供商 & 模型
- 交互式模式
- 编辑器
- 常用命令
- 键盘快捷键
- 消息队列
- 会话管理
- 分支 & 树视图
- Fork & Clone
- 自动/手动压缩
- 设置 & 环境变量
- 上下文文件
- 自定义
- Prompt Templates
- Skills
- Extensions
- 主题
- Pi Packages
- 编程式使用 (SDK / RPC)
- 常用 CLI 示例
- 常见问题 & 注意事项
- 贡献 & 开发
快速开始
npm install -g @mariozechner/pi-coding-agent
export ANTHROPIC_API_KEY=sk-ant-... # 或其他提供商的 API key
pi # 直接进入交互式终端
若已有订阅，可使用
pi /login登录并在登录后选择模型。
提供商 & 模型
- 内置提供商：Anthropic, OpenAI, Google, Azure, Claude, Mistral, Groq, 等等。
- 认证方式：
- 订阅登录：
pi /login→ 选择提供商 → 完成 OAuth。 - API Key：在环境变量或
/settings中设置对应*_API_KEY。 - 模型切换：
/model或Ctrl+L，也可使用--model参数直接指定（如--model claude-3-5-sonnet:high）。
交互式模式
编辑器
| 操作 | 快捷键 |
|---|---|
| 插入文件 (模糊搜索) | @ + 输入路径 |
| 完成路径 | Tab |
| 多行输入 | Shift+Enter (Windows Terminal: Ctrl+Enter) |
| 粘贴图片 | Ctrl+V (Windows: Alt+V) |
| 运行 Bash 命令并发送输出 | !your_cmd |
| 运行 Bash 命令但不发送输出 | !!your_cmd |
| 清空编辑框 | Ctrl+C |
退出 Pi（两次 Ctrl+C） |
Ctrl+C 两次 |
常用命令 (/ 开头)
| 命令 | 功能 |
|---|---|
/login, /logout |
登录/登出 |
/model |
切换模型 |
/settings |
调整思考层级、主题等 |
/new |
创建新会话 |
/fork |
从历史节点创建新会话 |
/clone |
复制当前分支为新会话 |
/compact |
手动压缩（摘要）上下文 |
/tree |
交互式树视图，随时跳转分支 |
/share |
生成 GitHub Gist + HTML 链接 |
/export <file> |
导出为 HTML |
/hotkeys |
查看所有快捷键 |
/quit |
退出 |
键盘快捷键
| 键 | 功能 |
|---|---|
Ctrl+L |
模型选择 |
Ctrl+P / Shift+Ctrl+P |
前后循环模型（scoped models） |
Shift+Tab |
调整思考层级 |
Ctrl+O |
折叠/展开工具输出 |
Ctrl+T |
折叠/展开思考块 |
Escape |
取消/退出当前操作 |
Escape x2 |
打开 /tree |
Alt+Enter |
发送 “后续” 消息（等待当前完成） |
Enter |
发送 “引导” 消息（当前完成后立即发送） |
Alt+Up |
将已排队的消息拉回编辑框 |
完整列表请在交互式窗口执行
/hotkeys。
消息队列
- Enter → “Steering” 消息：在当前回复完成后立即发送。
- Alt+Enter → “Follow‑up” 消息：等到模型完整结束后才发送。
- Escape → 中止并恢复排队消息。
- Alt+Up → 把排队消息拉回编辑框。
会话管理
- 保存位置：
~/.pi/agent/sessions/<working‑dir>/（按项目目录划分）。 - 启动已有会话
bash pi -c # 继续最近会话 pi -r # 浏览并选择历史会话 pi --session <path|id> # 指定会话文件或部分 UUID - 分支 (Tree View)：
/tree中可搜索、折叠、标记（Shift+L）节点，随时跳转继续。 - Fork / Clone：
- Fork：从历史用户消息生成新会话文件。
- Clone：复制当前分支到新会话文件。
- 压缩 (Compaction)：
- 自动触发（上下文溢出或接近上限）。
- 手动
/compact（可附加自定义指令）。 - 完整历史仍保存在 JSONL 文件，可通过
/tree回溯。
设置 & 环境变量
- 全局：
~/.pi/agent/settings.json - 项目局部：
./.pi/settings.json（覆盖全局） - 常用选项（可在
/settings中修改） thinkingLevel:"off" | "minimal" | "low" | "medium" | "high" | "xhigh"theme:"dark" | "light" | "customTheme"transport:"sse" | "websocket" | "auto"steeringMode/followUpMode:"one-at-a-time" | "all"
环境变量（可覆盖）
| 变量 | 用途 |
|------|------|
| PI_CODING_AGENT_DIR | 自定义配置根目录（默认 ~/.pi/agent） |
| ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY | 对应提供商的密钥 |
| PI_TELEMETRY | 0/false 禁用安装/更新匿名遥测 |
| VISUAL, EDITOR | Ctrl+G 启动的外部编辑器 |
上下文文件
- AGENTS.md / CLAUDE.md 自动在以下路径向上搜寻并拼接：
~/.pi/agent/, 父目录 (逐层向根), 当前目录。 - SYSTEM.md（全局或项目）覆盖默认系统提示。
- APPEND_SYSTEM.md 追加到系统提示。
- 如不需要上下文文件，可使用
--no-context-files或-nc。
自定义
Prompt Templates（提示模板）
- 保存为
*.md（如review.md）放在
~/.pi/agent/prompts/,.pi/prompts/或 pi 包中。 - 在聊天时输入
/review自动展开模板。 - 支持 Mustache/Handlebars 风格变量（
{{var}}）。
Skills（技能）
- 目录结构
skills/<skill‑name>/SKILL.md。 - 通过
/skill:name手动调用，或让模型自行决定。 - 适合一次性过程（如 “生成单元测试”）。
Extensions（扩展）
- TypeScript 模块（默认导出函数），可注册工具、命令、UI、事件监听等。
- 常用 API：
pi.registerTool(),pi.registerCommand(),pi.on(event, handler)。 - 加载方式：
pi -e ./my‑ext.ts或通过 pi 包。 - 安全提示：扩展拥有完整系统权限，务必审查代码来源。
Themes（主题）
dark、light为内置，放在~/.pi/agent/themes/,.pi/themes/或包中可自定义。- 修改后自动热重载。
Pi Packages（包装）
- npm、git、URL 均可。例：
pi install npm:@foo/pi-tools。 - 包结构在
package.json中通过"pi"字段声明资源路径，或遵循约定目录 (extensions/,skills/,prompts/,themes/) 自动发现。 - 全局安装到
~/.pi/agent/git/，本地（-l）安装到项目.pi/git/。 - 安全警告：Pi 包在运行时拥有完整系统访问权限。请在安装前审查源码，或只使用可信来源的包。
编程式使用 (SDK / RPC)
SDK 示例（Node/TS）
import { AuthStorage, createAgentSession, ModelRegistry, SessionManager } from "@mariozechner/pi-coding-agent";
const auth = AuthStorage.create();
const models = ModelRegistry.create(auth);
const { session } = await createAgentSession({
sessionManager: SessionManager.inMemory(),
authStorage: auth,
modelRegistry: models,
});
await session.prompt("列出当前项目的所有 TypeScript 文件");
RPC 模式（外部进程集成）
pi --mode rpc
- 使用 LF 分隔的 JSONL 帧协议，与任何语言的标准输入/输出交互。
- 详细协议见
docs/rpc.md。
常用 CLI 示例
# 交互式会话并打开默认模型
pi
# 指定模型、思考层级
pi --model claude-3-5-sonnet:high "帮我设计订单系统"
# 非交互式快速答案
pi -p "解释一下什么是事件驱动架构"
# 非交互式与 piped stdin
cat README.md | pi -p "为这段文本写两句摘要"
# 不同模型（无需 --provider）
pi --model openai/gpt-4o "帮我重构代码"
# 限制模型循环
pi --models "claude-*,gpt-4o"
# 只读模式（禁用所有工具）
pi --tools read,grep,find,ls -p "审查代码"
# 高思考层级
pi --thinking high "解决这个复杂问题"
环境变量
| 变量 | 描述 |
|---|---|
PI_CODING_AGENT_DIR |
覆盖配置根目录 |
PI_PACKAGE_DIR |
覆盖包目录（Nix/Guix） |
PI_SKIP_VERSION_CHECK |
跳过启动时的版本检查 |
PI_TELEMETRY |
1/true 启用或 0/false 禁用安装遥测 |
PI_CACHE_RETENTION |
long 延长提示缓存（Anthropic: 1h, OpenAI: 24h） |
VISUAL, EDITOR |
Ctrl+G 启动的外部编辑器 |
贡献 & 开发
- Fork 项目 →
npm install→npm run dev（实时热加载） - 提交 PR 前请运行
npm test，并遵守CONTRIBUTING.md中的代码风格。 - 如需添加新模型或提供商，参照
docs/models.md与docs/custom-provider.md。
许可证
MIT