Pi Coding Agent 完全指南：极简主义 Coding Agent 的终极玩法

前言

按照作者的话来说，Pi Coding Agent 是一个有主见且极简的 Coding Agent。上手了一段时间后，我认为它是目前最好用的 AI Agent CLI 之一。

很多项目爆火后都会迎来各种低质量的 issues 和 AI 生成的 PR，而 pi 这个名字非常有意思——它会与数学常数产生关联，这正是作者有意为之，目的是降低知名度，保持社区质量。

设计理念

翻译自 官方文档

Pi 奉行近乎激进的可扩展性，因此无需、也不愿替你规定工作流。许多在别的工具中"内建"的能力，在这里都可通过 extensions、skills 或安装第三方 pi packages 来实现。核心保持精简，你按自己的工作方式塑造 Pi。

Pi 有意不包含以下功能，但你完全可以通过扩展或外部工具实现：

• 不做 MCP。 你可以构建带有 README 的 CLI 工具（见 Skills），也可以编写 extension 为 Pi 增加 MCP 支持。
• 不设 sub-agents。 可借助 tmux 启动多个 Pi 实例，或用 extensions 自行搭建。
• 不弹 permission popups。 可以在容器中运行，或通过 extensions 构建与自身安全要求匹配的确认流程。
• 不设 plan mode。 计划可直接写入文件，或借助 extensions 自行实现。
• 不内置 to-dos。 它们容易让模型困惑。请使用 TODO.md 或用 extensions 自定义。
• 不提供后台 bash。 请使用 tmux——全程可观测，交互更直接。

设计哲学的详细论述见作者博文，写得非常精彩。

快速上手

使用过程中有困难可以查阅 DeepWiki。

安装

方式一：curl（Linux / macOS）

curl -fsSL https://pi.dev/install.sh | sh

方式二：npm

npm install -g @earendil-works/pi-coding-agent

接着通过 pi 命令启动，或为你的终端配置快捷键。

Windows

Windows 用户还需要一个 bash shell。检查顺序：

1. ~/.pi/agent/settings.json 中的自定义路径
2. Git Bash（C:\Program Files\Git\bin\bash.exe）
3. PATH 中的 bash.exe（如 Cygwin, MSYS2, WSL）

对于大多数用户，Git for Windows 足够了。

自定义 Shell 路径（settings.json）：

{ "shellPath": "C:\\cygwin64\\bin\\bash.exe" }

Termux（Android）

详见官方文档。

模型配置

配置好后可以通过 /model（或 Ctrl+L）选择模型。

订阅

对于具有以下订阅之一的用户：

• Claude Pro/Max
• ChatGPT Plus/Pro（Codex）
• GitHub Copilot

可通过 /login 进行登入，使用 /logout 登出。认证 Token 会被储存在 ~/.pi/agent/auth.json。

API 密钥

可通过环境变量设置：

export ANTHROPIC_API_KEY=sk-ant-...
pi

或写入 ~/.pi/agent/auth.json：

{
  "anthropic": { "type": "api_key", "key": "sk-ant-..." },
  "openai": { "type": "api_key", "key": "sk-..." },
  "google": { "type": "api_key", "key": "..." },
  "opencode": { "type": "api_key", "key": "..." }
}

支持的 API 密钥提供商：

默认情况下 auth.json 以 0600 权限创建（仅用户可读写）。Auth 文件凭证优先于环境变量。

第三方提供商

通过 ~/.pi/agent/models.json 添加自定义提供商和模型（Ollama、vLLM、LM Studio、代理等）。

完整示例：

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        {
          "id": "llama3.1:8b",
          "name": "Llama 3.1 8B (Local)",
          "reasoning": false,
          "input": ["text"],
          "contextWindow": 128000,
          "maxTokens": 32000,
          "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
        }
      ]
    }
  }
}

支持的 API 类型：

• 在 providers 层级设置的 api，作为该 provider 下所有 models 的默认值。
• 在 models 层级中，单个模型可以通过自己的 api 字段覆盖默认值。
• 如遇 Error: 403 Your request was blocked，说明请求被 CF 阻断。自定义请求头加上 UA 即可：

"headers": {
  "User-Agent": "MyCustomClient/1.0"
}

每次在 Pi 中键入 /model 时，文件都会重新加载，因此编辑 models.json 无需重启。

指南

详见官方文档

感受一下 TUI 界面。你可以编写主题和扩展进行自定义，甚至让 Pi 看起来完全不同。

编辑器

删除单词、撤销等使用标准编辑快捷键。详见 Keybindings。

命令

在编辑器里输入 / 可触发命令。扩展可注册自定义命令，技能可用 /skill:name 调用，提示词模板可通过 /templatename 展开。

消息队列

智能体工作时，你也可以继续发消息：

• Enter：排入一条引导消息，在当前助手回合完成工具调用执行后立即送达
• Alt+Enter：排入一条跟进消息，在代理完成全部工作后送达
• Escape：中止当前过程，并把已排队消息恢复到编辑器
• Alt+Up：把队列中的消息取回到编辑器

可在 Settings 配置投递方式：steeringMode 和 followUpMode 可设为 "one-at-a-time"（默认，收到回复后再发下一条）或 "all"（一次性发送队列全部消息）。transport 用于选择支持多传输的提供方通道偏好（"sse"、"websocket" 或 "auto"）。

会话

会话以 JSONL 树结构保存。每条记录都有 id 和 parentId，所以可以在同一个文件里直接分支，不必新建文件。

管理

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

pi -c                  # 继续最近一次会话
pi -r                  # 浏览并选择历史会话
pi --no-session        # 临时模式（不保存会话）
pi --session <path|id> # 使用指定会话文件或会话 ID
pi --fork <path|id>    # 将会话分支到新会话文件

分支

• /tree：在当前会话文件内浏览会话树。选中任意历史节点，从那继续，所有分支都保留在同一会话文件中。输入关键词可搜索，←/→ 翻页。过滤模式（Ctrl+O）：default → no-tools → user-only → labeled-only → all。按 l 可给条目标记书签。
• /fork：从之前的用户消息创建一个新会话文件。系统会打开选择器，复制到所选节点为止的历史，并把该节点消息放入编辑器。
• /clone：将当前活动分支复制到新会话文件。

设置

使用 /settings 修改常用选项，或直接编辑 JSON 文件：

详见官方文档。

项目上下文

Pi 在启动时会从以下位置加载 AGENTS.md（或 CLAUDE.md）：

1. ~/.pi/agent/AGENTS.md（全局）
2. 父目录（从当前工作目录向上查找）
3. 当前目录

用于项目说明、约束和常用命令封装。所有匹配的 md 文件将被拼接在一起。

系统提示

• 用 .pi/SYSTEM.md（项目）或 ~/.pi/agent/SYSTEM.md（全局）替换系统提示词
• 用 APPEND_SYSTEM.md 在系统提示词末尾追加内容，而不替换

自定义

这部分的内容都可以封装为 pi package。公开的 Pi 包见 Packages - pi.dev。

提示词模板

将提示词封装为 Markdown 文件，输入 /文件名 展开。

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

放置在 ~/.pi/agent/prompts/（全局）、.pi/prompts/（项目）或封装为 pi package 分享。

技能

按需加载的技能包，遵循 Agent Skills 标准。可通过输入 /skill:name 调用，也可让 Agent 自动加载。

<!-- ~/.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 package。详见官方文档。

扩展

用 TypeScript 编写扩展，为 Pi 添加工具、命令、事件和自定义 UI。

放入 ~/.pi/agent/extensions/（全局）、.pi/extensions/（项目）或封装为 pi package。

参见文档和示例。

主题

内置暗色与明亮，修改主题配置后可热重载。

放入 ~/.pi/agent/themes/（全局）、.pi/themes/（项目）或封装为 pi package。

详见官方文档。

Pi Packages

将扩展、技能、提示词和主题打包为 npm/git 包，一键安装和分享：

pi install <source>     # 全局安装
pi install <source> -l  # 项目本地安装
pi list                  # 列出已安装的包
pi config                # 启用/禁用包资源

通过扩展与主题系统可以极大增强使用体验。直接对模型说出需求即可——Pi 的系统提示词中包含了文档路径，模型能够理解并使用这些自定义能力。