站点图标 高效码农

Pi Coding Agent终极指南：如何在终端用这个简洁的编码工具提升开发效率？

高效码农

Pi Coding Agent: 如何在终端中使用这个简洁的编码工具

你好！如果你正在寻找一个在终端里运行的编码助手，能够帮助你处理代码、运行命令，还能根据你的需求灵活扩展，我觉得Pi Coding Agent值得一试。它是一个最小化的终端编码工具，设计思路是让你适应自己的工作流程，而不是反过来。接下来，我会一步步解释Pi是什么，怎么用它，以及它的一些核心功能。我们来聊聊你可能有的疑问，比如“Pi Coding Agent是什么？”或者“怎么安装和开始使用它？”

Pi是一个终端编码 harness，意思是它提供了一个框架，让你和语言模型互动来完成编码任务。它内置了一些基本工具，比如读取文件、编写文件、编辑代码和运行bash命令，但最酷的地方在于它的可扩展性。你可以用TypeScript编写扩展、技能、提示模板和主题，来定制它。Pi有四种运行模式：交互模式、打印或JSON输出、RPC用于进程集成，以及SDK用于嵌入到你的应用中。

假设你是个开发者，想知道Pi能帮你做什么。简单来说，它让模型能访问你的文件系统，执行命令，并根据你的指令生成响应。默认情况下，它给模型四个工具：read、write、edit和bash。模型会用这些工具来完成你的请求。如果你需要更多功能，可以通过技能或扩展添加。

如何快速启动Pi Coding Agent？

如果你想马上试试Pi，这里是安装和启动的步骤。整个过程很简单，只需要几分钟。

  1. 打开你的终端。
  2. 运行这个命令来全局安装Pi： 
    npm install -g @mariozechner/pi-coding-agent
  3. 设置API密钥，比如Anthropic的： 
    export ANTHROPIC_API_KEY=sk-ant-...

    然后运行：

    pi

    或者，如果你有订阅，可以用：

    pi
/login  # 然后选择提供商

安装后，你就可以直接和Pi聊天了。比如，你可以说“列出当前目录下的所有文件”，Pi会用工具来处理并回复你。平台注意事项：如果你用Windows、Termux（Android），或者需要设置终端或shell别名，可以参考相关文档，但这里我们聚焦核心。

为什么这个快速启动这么简单？因为Pi的设计就是最小化，不想让你在配置上浪费时间。安装后，它会加载默认工具，让你立刻开始工作。

Pi Logo

（这是Pi的logo，看起来简洁吧？它代表了工具的minimalist风格。）

Pi支持哪些提供商和模型？

你可能会问：“Pi能用哪些AI模型？”Pi支持多种提供商和模型，确保你能选择适合的。每个内置提供商都有工具能力的模型列表，每次发布都会更新。

通过订阅认证的提供商：

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

通过API密钥认证的提供商：

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

要切换模型，用/model命令，或者按Ctrl+L打开选择器。Pi会维护这些模型的列表，让你轻松挑选。

如果你想添加自定义提供商或模型，可以编辑~/.pi/agent/models.json，只要它们支持OpenAI、Anthropic或Google的API。对于自定义API或OAuth，用扩展来实现。这让Pi很灵活——你不用局限于内置的。

举个例子，如果你用OpenAI的GPT-4o，想知道怎么设置：先设置API密钥，然后运行pi --provider openai --model gpt-4o "帮我重构代码"。这样就直接用了指定模型。

Pi的交互模式是怎么工作的？

交互模式是Pi最常用的方式，让你在终端里和模型对话。界面从上到下包括启动头、消息区、编辑器和页脚。

  • 启动头：显示快捷键（用/hotkeys看全部）、加载的AGENTS.md文件、提示模板、技能和扩展。
  • 消息区：你的消息、助手响应、工具调用和结果、通知、错误，以及扩展的UI。
  • 编辑器：输入的地方，边框颜色表示思考水平。
  • 页脚：显示工作目录、会话名称、总令牌/缓存使用、成本、上下文使用和当前模型。
Interactive Mode

（这是交互模式的截图，你可以看到消息如何显示，编辑器在底部。）

编辑器功能

编辑器是核心输入区。怎么用？

  • 输入@来模糊搜索项目文件。
  • 用Tab完成路径。
  • Shift+Enter（或Windows Terminal的Ctrl+Enter）输入多行。
  • Ctrl+V粘贴图像，或拖拽到终端。
  • !command运行bash命令并发送输出给LLM，!!command只运行不发送。

标准编辑键如删除词、撤销等都支持。

命令列表

输入/触发命令。扩展可以添加自定义命令，技能用/skill:name，提示模板用/templatename扩展。

这里是常用命令表格：

命令 描述
/login, /logout OAuth认证
/model 切换模型
/scoped-models 启用/禁用Ctrl+P循环的模型
/settings 调整思考水平、主题、消息传递、传输
/resume 从之前会话选择
/new 开始新会话
/name <name> 设置会话显示名
/session 显示会话信息（路径、令牌、成本）
/tree 跳转到会话任何点并继续
/fork 从当前分支创建新会话
/compact [prompt] 手动压缩上下文，可选自定义指令
/copy 复制最后助手消息到剪贴板
/export [file] 导出会话到HTML文件
/share 上传为私有GitHub gist，带可分享HTML链接
/reload 重载扩展、技能、提示、上下文文件（主题自动热重载）
/hotkeys 显示所有键盘快捷键
/changelog 显示版本历史
/quit, /exit 退出Pi

这些命令让交互更高效。比如，如果你想分享会话，用/share就能生成链接。

键盘快捷键

常用快捷键表格：

键 动作
Ctrl+C 清空编辑器
Ctrl+C 两次 退出
Escape 取消/中止
Escape 两次 打开/tree
Ctrl+L 打开模型选择器
Ctrl+P / Shift+Ctrl+P 循环范围模型向前/向后
Shift+Tab 循环思考水平
Ctrl+O 折叠/展开工具输出
Ctrl+T 折叠/展开思考块

你可以自定义这些在~/.pi/agent/keybindings.json。

消息队列

当代理在工作时，你可以提交消息：

  • Enter：队列转向消息，在当前工具执行后传递（中断剩余工具）。
  • Alt+Enter：队列跟进消息，只在代理完成所有工作后传递。
  • Escape：中止并恢复队列消息到编辑器。
  • Alt+Up：取回队列消息到编辑器。

在设置中配置传递：steeringMode和followUpMode可以是"one-at-a-time"（默认，逐个响应）或"all"（一次性传递所有）。transport选择"sse"、"websocket"或"auto"。

交互模式感觉像在和一个聪明的助手聊天，你输入，它思考，然后用工具行动。

Pi的会话系统如何管理历史？

会话是Pi保持上下文的方式。它们存储为JSONL文件，带树结构，每个条目有id和parentId，允许原地分支而不创建新文件。

管理会话

会话自动保存到~/.pi/agent/sessions/，按工作目录组织。

命令：

  • pi -c：继续最近会话。
  • pi -r：浏览并选择过去会话。
  • pi --no-session：临时模式（不保存）。
  • pi --session <path>：用特定会话文件或ID。

分支

用/tree导航会话树。选择任何之前点，继续从中分支。所有历史保存在单一文件。

Tree View

（树视图截图，帮助你可视化分支。）

  • 输入搜索，用←/→翻页。
  • Ctrl+O切换过滤模式：默认 → 无工具 → 只用户 → 只标签 → 所有。
  • 按l标签条目作为书签。

用/fork从当前分支创建新会话文件。打开选择器，复制历史到选中点，把消息放到编辑器修改。

压缩

长会话可能耗尽上下文窗口。压缩总结旧消息，保持最近的。

  • 手动：/compact或/compact <自定义指令>。
  • 自动：默认启用。在上下文溢出时触发（恢复并重试）或接近限额时（主动）。通过/settings或settings.json配置。

压缩是有损的，但完整历史在JSONL文件。用/tree重访。用扩展自定义压缩行为。

会话系统让Pi适合长期项目，你可以分支实验而不丢失历史。

如何调整Pi的设置？

设置控制Pi的行为。用/settings修改常见选项，或直接编辑JSON文件。

位置表格：

位置 范围
~/.pi/agent/settings.json 全局（所有项目）
.pi/settings.json 项目（覆盖全局）

选项包括思考水平、主题、消息传递等。这让你微调Pi以匹配你的偏好。

上下文文件在Pi中起什么作用？

Pi在启动时加载AGENTS.md（或CLAUDE.md）从：

  • ~/.pi/agent/AGENTS.md（全局）
  • 父目录（从cwd向上走）
  • 当前目录

这些用于项目指令、约定、常见命令。所有匹配文件连接起来。

系统提示

用.pi/SYSTEM.md（项目）或~/.pi/agent/SYSTEM.md（全局）替换默认系统提示。用APPEND_SYSTEM.md追加而不替换。

上下文文件确保模型了解你的项目背景，提高响应准确性。

如何自定义Pi？

自定义是Pi的核心。你可以添加提示模板、技能、扩展和主题，甚至打包分享。

提示模板

这些是可复用Markdown文件提示。输入/name扩展。

例子：

<!-- ~/.pi/agent/prompts/review.md -->
Review this code for bugs, security issues, and performance problems.
Focus on: {{focus}}

放在~/.pi/agent/prompts/、.pi/prompts/或Pi包中。

技能

按需能力包，跟Agent Skills标准。用/skill:name调用，或让代理自动加载。

例子：

<!-- ~/.pi/agent/skills/my-skill/SKILL.md -->
# My Skill
Use this skill when the user asks about X.

## Steps
1. Do this
2. Then that

放在~/.pi/agent/skills/、~/.agents/skills/、.pi/skills/、.agents/skills/或Pi包中。

扩展

TypeScript模块扩展Pi，添加自定义工具、命令、快捷键、事件处理器和UI组件。

例子：

export default function (pi: ExtensionAPI) {
  pi.registerTool({ name: "deploy", ... });
  pi.registerCommand("stats", { ... });
  pi.on("tool_call", async (event, ctx) => { ... });
}

能做什么：自定义工具、子代理、计划模式、自定义压缩、权限门、自定义编辑器、Git检查点、SSH、MCP集成、游戏（如Doom）等。

Doom Extension

（Doom扩展截图——是的，你可以边等边玩游戏！）

放在~/.pi/agent/extensions/、.pi/extensions/或Pi包中。

主题

内置：dark、light。主题热重载：修改活跃主题文件，Pi立即应用。

放在~/.pi/agent/themes/、.pi/themes/或Pi包中。

Pi包

捆绑并分享扩展、技能、提示和主题，通过npm或git。找包在npmjs.com或Discord。

安全注意：Pi包有完整系统访问。审查源代码前安装第三方包。

安装命令：

pi install npm:@foo/pi-tools
pi install git:github.com/user/repo
pi remove npm:@foo/pi-tools
pi list
pi update
pi config  # 启用/禁用

用-l项目本地安装。创建包：在package.json加pi键，或用常规目录。

自定义让Pi适应你，而不是反过来。你可以构建子代理、计划模式等，而不叉Pi核心。

Pi的程序化使用方式？

除了交互，Pi有SDK和RPC模式。

SDK

用TypeScript嵌入：

import { AuthStorage, createAgentSession, ModelRegistry, SessionManager } from "@mariozechner/pi-coding-agent";

const { session } = await createAgentSession({
  sessionManager: SessionManager.inMemory(),
  authStorage: new AuthStorage(),
  modelRegistry: new ModelRegistry(authStorage),
});

await session.prompt("What files are in the current directory?");

RPC模式

用于非Node.js集成，用stdin/stdout：

pi --mode rpc

程序化使用让Pi集成到你的app或脚本中。

Pi的设计哲学是什么？

Pi强调可扩展性，不 dictation你的工作流。像子代理、计划模式这样的功能可以用扩展或包构建，而不是内置。这保持核心最小，让你塑造Pi。

没有MCP：用带README的CLI工具，或建扩展添加MCP支持。

没有子代理：用tmux生成Pi实例，或建自己的。

没有权限弹窗：用容器，或建确认流。

没有计划模式：写计划到文件，或建它。

没有内置to-dos：用TODO.md，或建自己的。

没有背景bash：用tmux。全可观察性，直接交互。

这种哲学让Pi灵活，聚焦于让你构建所需。

Pi的CLI参考

命令：

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

包命令

pi install <source> [-l]
pi remove <source> [-l]
pi update [source]
pi list
pi config

模式

  • 默认：交互
  • -p, --print：打印响应并退出
  • --mode json：输出所有事件为JSON行
  • --mode rpc：RPC模式
  • --export <in> [out]：导出会话到HTML

模型选项

选项 描述
--provider <name> 提供商
--model <pattern> 模型模式或ID（支持provider/id和可选:<thinking>）
--api-key <key> API密钥
--thinking <level> off, minimal, low, medium, high, xhigh
--models <patterns> 逗号分隔模式用于Ctrl+P循环
--list-models [search] 列出可用模型

会话选项

选项 描述
-c, --continue 继续最近会话
-r, --resume 浏览并选择会话
--session <path> 用特定会话
--session-dir <dir> 自定义会话目录
--no-session 临时模式

工具选项

选项 描述
--tools <list> 启用特定内置工具（默认：read,bash,edit,write）
--no-tools 禁用所有内置工具

内置工具：read, bash, edit, write, grep, find, ls

资源选项

选项 描述
-e, --extension <source> 加载扩展（可重复）
--no-extensions 禁用扩展发现
--skill <path> 加载技能（可重复）
--no-skills 禁用技能发现
--prompt-template <path> 加载提示模板（可重复）
--no-prompt-templates 禁用提示模板发现
--theme <path> 加载主题（可重复）
--no-themes 禁用主题发现

其他选项

选项 描述
--system-prompt <text> 替换默认提示
--append-system-prompt <text> 追加到系统提示
--verbose 强制详细启动
-h, --help 显示帮助
-v, --version 显示版本

文件参数：用@前缀包含文件，如pi @prompt.md "Answer this"。

例子：

  • pi "List all .ts files in src/"
  • pi -p "Summarize this codebase"
  • pi --model openai/gpt-4o "Help me refactor"
  • pi --models "claude-*,gpt-4o"
  • pi --tools read,grep,find,ls -p "Review the code"
  • pi --thinking high "Solve this complex problem"

环境变量：

变量 描述
PI_CODING_AGENT_DIR 覆盖配置目录（默认：~/.pi/agent）
PI_PACKAGE_DIR 覆盖包目录
PI_SKIP_VERSION_CHECK 跳过启动版本检查
PI_CACHE_RETENTION 设置为long延长提示缓存
VISUAL, EDITOR Ctrl+G的外部编辑器

FAQ

Pi Coding Agent适合初学者吗？

是的，如果你有专科背景，会编程，它通俗易懂。默认设置就很强大，扩展适合高级用户。

怎么处理长会话？

用压缩：手动或自动。树视图让分支容易。

Pi免费吗？

Pi本身是MIT许可的免费工具，但模型需要订阅或API密钥，可能有成本。

能用Pi构建自定义工具吗？

绝对可以，用扩展注册工具。例子包括部署工具或统计命令。

Pi支持图像吗？

是的，在编辑器Ctrl+V粘贴，或用工具处理。

怎么分享Pi包？

用npm发布，添加pi键到package.json，或用git。

Pi的哲学为什么这么强调扩展？

因为它想让你控制工作流，而不是内置一切。像没有内置子代理——你可以用扩展建自己的。

希望这篇文章帮你了解Pi。如果你有具体问题，比如“怎么用扩展玩Doom？”，它其实是个有趣的例子，展示扩展的潜力：注册一个工具来运行游戏，而代理思考时玩。Pi让编码更有趣，不是吗？如果试用，告诉我你的体验！（字数统计：约4500字）

退出移动版