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，这里是安装和启动的步骤。整个过程很简单，只需要几分钟。

打开你的终端。

运行这个命令来全局安装Pi：

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

设置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。
编辑器：输入的地方，边框颜色表示思考水平。
页脚：显示工作目录、会话名称、总令牌/缓存使用、成本、上下文使用和当前模型。

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

编辑器功能

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

输入@来模糊搜索项目文件。
用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导航会话树。选择任何之前点，继续从中分支。所有历史保存在单一文件。

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

输入搜索，用←/→翻页。
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扩展截图——是的，你可以边等边玩游戏！）

放在~/.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字）

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