# 9.3万星开源神器Pi Agent完整指南：极简终端编程助手，从安装到Extension开发

- 原文：[https://news.qiniu.com/archives/1787103478559](https://news.qiniu.com/archives/1787103478559)
- 发布时间：2026-08-19
- 分类：教程与实践
- 标签：AI Agent、AI 编程、Agent Skills

> 发布日期：2026年8月19日 | 话题：AI编程工具 · Pi Agent · 开发者工具 · 终端Agent

Pi（pi.dev）是由 Earendil Inc. 开发的开源终端AI编程Agent，MIT协议，GitHub仓库（earendil-works/pi）已累计9.3万星（数据来源：GitHub，2026年8月19日）。它的设计哲学与Claude Code、OpenAI Codex方向相反——后者追求功能完备，Pi追求"Primitives, not features"：默认只有4个核心工具（read/write/edit/bash），刻意不内置子Agent、权限弹窗、Plan模式、待办列表、后台命令，把所有"可选功能"留给Extension机制和社区包来实现。核心理念是"There are many agent harnesses, but this one is yours"——Pi适应你的工作流，不是反过来。本文覆盖安装认证、四种运行模式、会话树管理、Skills与Extension开发、上下文压缩，以及Pi与Claude Code/Codex的选型边界。

* * *

![](https://news-static.qiniu.com/legacy/images/c8/c818de57ddfc8f88ff66f70ce46077777e43bf797684cd7a8606e606963ef398.jpg)

## 安装与认证

### 安装

Pi通过npm分发：

```bash
# 推荐：curl一键安装
curl -fsSL https://pi.dev/install.sh | sh

# 或npm全局安装（--ignore-scripts关闭依赖生命周期脚本）
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
```

支持pnpm、yarn、bun，命令相同，将`npm install -g`替换为对应包管理器即可。安装后在项目目录启动：

```bash
cd /path/to/project
pi
```

### 认证：订阅登录 vs API Key

**方式一：订阅登录（内置支持Claude Pro/Max、ChatGPT Plus/Pro、GitHub Copilot）**

```text
# 在Pi内运行
/login
# 选择提供商，完成OAuth流程
```

**方式二：API Key（任意兼容提供商）**

```bash
# 启动前设置环境变量
export ANTHROPIC_API_KEY=sk-ant-...
pi

# 或Google
export GOOGLE_GENERATIVE_AI_API_KEY=...
pi
```

Key也可以通过`/login`写入`~/.pi/agent/auth.json`永久保存，不需要每次设置环境变量。

Pi支持15+家模型提供商：Anthropic、OpenAI、Google、Azure、Bedrock、Mistral、Groq、Cerebras、xAI、Ollama（本地）等，会话中途可用`/model`或`Ctrl+L`切换，无需重启。

* * *

## 四种运行模式

### 模式一：Interactive（交互TUI）

默认模式，完整终端UI界面：

```bash
pi
```

进入后，常用快捷键：

- `Ctrl+L` — 切换模型
- `Shift+Tab` — 循环调整thinking级别
- `Enter` — 发送当前引导消息（工具执行完当前步骤后中断）
- `Alt+Enter` — 等Agent完成后再发送跟进消息
- `@文件名` — 模糊搜索并引用文件
- `Ctrl+V` — 粘贴图片或文本（支持拖拽图片）

### 模式二：Print/JSON（非交互单次运行）

```bash
# 单次打印输出
pi -p "总结这个仓库的主要结构"

# 管道输入
cat README.md | pi -p "总结这段文字"

# 引用特定文件
pi -p @README.md "总结这个文件"
pi -p @src/app.ts @src/app.test.ts "一起审查这两个文件"

# JSON事件流输出（用于脚本处理）
pi -p "分析这个代码库" --mode json
```

### 模式三：RPC（进程间通信）

通过stdin/stdout的JSON协议与Pi集成，适合非Node.js应用：

```bash
pi --mode rpc
```

接收结构化JSON命令，返回事件流，适合IDE插件、自动化脚本、CI管道中调用Pi而不依赖Node.js。

### 模式四：SDK（嵌入到自有应用）

```typescript
import { createAgent } from "@earendil-works/pi-agent-core";

const agent = await createAgent({
  model: "claude-opus-4",
  cwd: "/path/to/workspace",
});

const result = await agent.run("审查代码库并修复测试失败");
console.log(result.finalResponse);
```

`pi-agent-core`包提供完整的工具调用和状态管理，可嵌入到任意Node.js应用。

* * *

## 四个内建工具（默认工具集）

Pi默认只给模型4个工具：

| 工具 | 功能 |
|---|---|
| `read` | 读取文件内容 |
| `write` | 创建或覆盖文件 |
| `edit` | 对文件打patch（精确替换） |
| `bash` | 执行Shell命令 |

额外内建只读工具（`grep`/`find`/`ls`）通过工具选项启用，不默认加载，避免工具噪音。

这个极简设计是Pi的核心选择：4个工具覆盖了95%的编码任务，额外能力通过Extension按需注册，不强制占用系统提示词空间。

* * *

## 会话管理：树形结构与分支导航

Pi将会话存储为树形结构（JSONL文件），支持从任意历史节点继续、分叉出新路径，而不是线性记录。

### 会话基本操作

```bash
pi -c              # 继续最近一次会话
pi -r              # 浏览历史会话选择器
pi --name "重构认证模块"    # 启动时命名会话
pi --session <id>  # 打开指定会话
pi --fork <id>     # 从指定会话分叉出新会话
```

### 会话内命令

```text
/tree       # 打开会话树视图，导航到任意历史节点
/fork       # 从当前位置分叉出新分支
/clone      # 复制当前活跃分支到新会话
/resume     # 浏览本项目历史会话
/export     # 导出为HTML
/share      # 上传为私有GitHub Gist，获得可分享链接
/compact    # 手动触发上下文压缩
/session    # 显示当前会话信息（消息数、token用量、成本）
```

### 树形导航场景

会话树最典型的用法是探索多个解决方案：

```text
├─ 用户："重构这个认证模块"
│  └─ 助手：生成方案A
│     ├─ 用户："继续方案A"    ← 当前活跃
│     └─ 用户："试试方案B"    ← /tree可导航到这里继续
```

`/tree`里按`↑/↓`导航，`Enter`跳到选中节点继续，`Shift+L`给节点打标签方便后续查找。

* * *

## 上下文管理：AGENTS.md、Skills、Prompt Templates、Compaction

### AGENTS.md：项目级别指令

Pi按以下顺序加载指令文件：

1. `~/.pi/agent/AGENTS.md` — 全局指令（适用所有项目）
2. 从当前目录到根目录沿途的 `AGENTS.md`（也支持`CLAUDE.md`兼容格式）
3. 项目级 `AGENTS.override.md`（存在时替代同目录的`AGENTS.md`）

```markdown
<!-- AGENTS.md 示例 -->
# 项目指令

- 每次代码变更后运行 `npm run check`
- 不要在本地执行生产迁移脚本
- 保持回复简洁
- 使用中文回复
```

更改后运行`/reload`热重载，不需要重启Pi。

### Skills：按需加载的能力包

Skills遵循[Agent Skills规范](https://agentskills.io/specification)，是携带指令+工具+脚本的能力包，启动时只把名称和描述加入系统提示词，模型按需读取全文，实现"渐进式披露"。

**加载位置**：

- 全局：`~/.pi/agent/skills/` 或 `~/.agents/skills/`
- 项目级：`.pi/skills/` 或 `.agents/skills/`（项目信任后才加载）

**直接调用**：`/skill:brave-search` 或 `/skill:pdf-tools extract`

**与Claude Code/Codex Skills互用**：

```json
// ~/.pi/agent/settings.json
{
  "skills": [
    "~/.claude/skills",
    "~/.codex/skills"
  ]
}
```

Pi支持直接复用Claude Code和Codex的Skills目录，无需迁移。

**自定义Skill结构**：

```
my-skill/
├── SKILL.md          # 必填：frontmatter + 使用说明
├── scripts/
│   └── run.sh        # 辅助脚本
└── references/
    └── api.md        # 按需加载的参考文档
```

````markdown
---
name: my-skill
description: 处理X类型任务时使用，提供Y和Z工具。具体描述。
---

## 使用方式

```bash
./scripts/run.sh <input>
````

```

```

### Prompt Templates：可复用提示词

Markdown文件格式，存放在`~/.pi/agent/prompt-templates/`或`.pi/prompt-templates/`，输入`/名称`展开：

```markdown
<!-- ~/.pi/agent/prompt-templates/review.md -->
---
name: review
---
审查以下代码，重点检查：安全漏洞、性能问题、可读性问题。每个问题说明严重级别。
```

在Pi里输入`/review`，模板内容展开为当前输入。

### Compaction：自动上下文压缩

当上下文接近窗口上限（默认保留16384 token余量），Pi自动触发压缩：取最近20k token的消息保留，将更早的消息摘要为结构化Summary，追加到会话日志。模型下次请求看到的是：系统提示词 + Summary + 保留的最近消息。

```bash
# 手动压缩，可指定压缩侧重点
/compact 重点保留架构决策和已修改的文件列表
```

**Extension可定制压缩逻辑**：通过订阅`compaction`事件，可以实现：代码感知摘要（保留函数签名）、按主题分类摘要（架构决策/已修改文件/待办事项分开摘要）、或完全自定义压缩策略。

* * *

## Extension开发：给Pi增加任意能力

Extension是TypeScript模块，通过`pi.registerTool()`、`pi.registerCommand()`、事件订阅扩展Pi的能力。

**加载位置**：

- 全局：`~/.pi/agent/extensions/`
- 项目：`.pi/extensions/`

支持`/reload`热重载，不需要重启。

### 最小Extension示例：拦截危险命令

```typescript
// ~/.pi/agent/extensions/safety-guard.ts
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.on("tool_call", async (event, ctx) => {
    if (
      event.toolName === "bash" &&
      event.input.command?.match(/rm\s+-rf|drop\s+table|git\s+push\s+--force/i)
    ) {
      const ok = await ctx.ui.confirm(
        "危险操作",
        `确认执行？\n\n${event.input.command}`
      );
      if (!ok) return { block: true, reason: "用户取消" };
    }
  });
}
```

放入`~/.pi/agent/extensions/`，运行`/reload`即生效，无需重启Pi。

### 注册自定义工具

```typescript
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";

export default function (pi: ExtensionAPI) {
  pi.registerTool({
    name: "search_jira",
    label: "搜索Jira",
    description: "在Jira中搜索指定关键词的Issue",
    parameters: Type.Object({
      query: Type.String({ description: "搜索关键词" }),
      project: Type.Optional(Type.String({ description: "项目Key" })),
    }),
    async execute(toolCallId, params, signal, onUpdate, ctx) {
      const results = await fetchJiraIssues(params.query, params.project);
      return {
        content: [{ type: "text", text: JSON.stringify(results) }],
        details: { count: results.length },
      };
    },
  });
}
```

注册后，模型可以在后续对话中调用`search_jira`工具。

### 注册自定义命令

```typescript
pi.registerCommand("checkpoint", {
  description: "保存当前工作状态到git stash",
  handler: async (args, ctx) => {
    const msg = args || `pi-checkpoint-${Date.now()}`;
    await ctx.exec(`git stash push -m "${msg}"`);
    ctx.ui.notify(`已保存检查点: ${msg}`, "success");
  },
});
```

之后在Pi里输入`/checkpoint 修复认证前的状态`即可执行。

### 安装社区Extension包

```bash
# 从npm安装
pi install npm:@foo/pi-tools

# 从git安装
pi install git:github.com/badlogic/pi-doom
```

GitHub Topics `pi-extension`下可以发现社区Extension：权限门控、Git检查点、SSH执行、沙箱、MCP集成、子Agent编排等。

* * *

## 容器化与沙箱

Pi本身没有内置权限系统，默认以启动用户的权限运行。官方提供三种隔离模式：

**Gondolin Extension**（推荐）：保留Pi进程和Provider认证在宿主机，将内建工具和`!`命令路由进本地Linux micro-VM执行，安全性高且对用户透明。

**Plain Docker**：整个Pi进程运行在本地容器里，适合简单隔离场景：

```bash
docker run -it --rm -v $(pwd):/workspace -w /workspace \
  node:22 npx @earendil-works/pi-coding-agent
```

**OpenShell**：在策略控制的沙箱里运行Pi进程，适合企业安全合规场景。

* * *

## Pi vs Claude Code vs OpenAI Codex：选哪个

| 维度 | Pi | Claude Code | OpenAI Codex |
|---|---|---|---|
| 模型绑定 | 任意15+提供商 | Anthropic（支持BYOK） | OpenAI（支持BYOK） |
| 开源协议 | MIT开源 | 闭源 | 闭源 |
| Extension机制 | TypeScript模块，完整API | hooks.json（有限） | 有限 |
| 内置子Agent | 无（可用Extension实现） | 有 | 有 |
| 内置权限弹窗 | 无（可用Extension实现） | 有 | 有 |
| 会话树分支 | 支持树形 + /tree导航 | 线性 | 线性 |
| Skills来源 | 兼容Claude Code/Codex Skills目录 | 独立 | 独立 |
| 容器化支持 | 三种内置方案 | 需自行配置 | 需自行配置 |

**选Pi的信号**：

- 需要接入非Anthropic/OpenAI模型（Mistral、Ollama本地模型、Google等）
- 需要深度定制工具集和Agent行为（Extension开发）
- 需要会话树分支探索多个方案
- 希望在Codex/Claude Code之外有不依赖厂商配额的备用选择

**选Claude Code或Codex的信号**：

- 开箱即用、不需要任何配置
- 需要成熟的子Agent和并发任务支持
- 已深度集成Anthropic/OpenAI生态

[**七牛云AI大模型广场**](https://www.qiniu.com/ai/models)支持OpenAI兼容接口，Pi通过自定义Provider可以直接接入DeepSeek、Kimi、GLM、MiniMax等25个国产模型，设置方式与其他OpenAI兼容端点一致（在`~/.pi/agent/settings.json`中配置provider）。

* * *

## FAQ

**Pi可以使用Claude订阅而不消耗API配额吗？**

可以。`/login`选择Claude Pro/Max，Pi通过OAuth接入Claude的订阅额度，不消耗API key配额。ChatGPT Plus/Pro（即Codex）和GitHub Copilot同理。这是Pi相对于直接调API的成本优势之一。

**Pi的Extension和Claude Code的hooks有什么本质区别？**

Claude Code的hooks是在settings中配置的shell命令钩子，只能在特定事件点触发外部命令，能力有限。Pi的Extension是完整的TypeScript模块，可以访问完整的TUI API、注册工具、修改工具调用输入输出、自定义压缩逻辑、注册键盘快捷键——等同于一个完整的插件系统。

**Pi的Skills和Claude Code的Skills格式兼容吗？**

Pi直接兼容Claude Code和Codex的Skills目录——在`settings.json`里添加`~/.claude/skills`路径即可，无需迁移或格式转换。两者都遵循[Agent Skills规范](https://agentskills.io/specification)，格式基本一致。

**9.3万星的Pi和15万星的DeepSeek Harness该选哪个？**

定位不同。Pi是面向个人开发者的终端编程助手，偏重日常编码任务、会话管理、Extension定制，有完整的TUI交互体验；DeepSeek Harness偏重批量自动化、Agent编排框架、Python SDK集成、可作为其他工具的上层编排层。如果你主要场景是个人编码和项目维护，选Pi；如果需要批量处理、多Agent编排或把AI能力嵌入到自有系统，选dsh。

* * *

## 总结

Pi Agent以"Primitives, not features"的设计哲学，提供4个核心工具+完整的Extension框架，把功能选择权交给开发者。9.3万GitHub星（2026年8月19日）来自开发者对"不被厂商工具链锁定"需求的认可：Pi同时支持订阅认证（Claude/ChatGPT/Copilot）和API Key认证（15+提供商），Skills目录兼容Claude Code和Codex，Extension系统支持TypeScript全量开发，会话树结构支持分支探索和历史回溯，压缩机制支持Extension定制。当前版本功能完整，MIT开源，无锁定风险，是Claude Code和Codex之外最值得了解的开源终端编程Agent选项。

本文数据来源：Pi官网（pi.dev，2026年8月）、GitHub仓库（earendil-works/pi，93,149 stars，2026年8月19日）、官方文档（packages/coding-agent/docs/，2026年8月版）、Agent Skills规范（agentskills.io，2026年版）。

* * *

**延伸阅读**

- Pi官网（含Demo和完整文档）：[https://pi.dev/](https://pi.dev/)
- GitHub仓库（MIT开源）：[https://github.com/earendil-works/pi](https://github.com/earendil-works/pi)
- Pi Extension文档：[https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/extensions.md](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/extensions.md)
- Pi Skills文档：[https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/skills.md](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/skills.md)
- 七牛云AI大模型广场（OpenAI兼容接口，适合Pi自定义Provider接入国产模型）：[https://www.qiniu.com/ai/models](https://www.qiniu.com/ai/models)
