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

发布日期：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的选型边界。

安装与认证

安装

Pi通过npm分发：

# 推荐：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替换为对应包管理器即可。安装后在项目目录启动：

cd /path/to/project
pi

认证：订阅登录 vs API Key

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

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

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

# 启动前设置环境变量
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界面：

pi

进入后，常用快捷键：

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

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

# 单次打印输出
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应用：

pi --mode rpc

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

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

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文件），支持从任意历史节点继续、分叉出新路径，而不是线性记录。

会话基本操作

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

会话内命令

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

树形导航场景

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

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

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

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

AGENTS.md：项目级别指令

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

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

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

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

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

Skills：按需加载的能力包

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

加载位置：

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

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

与Claude Code/Codex Skills互用：

// ~/.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        # 按需加载的参考文档

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

## 使用方式

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

Prompt Templates：可复用提示词

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

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

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

Compaction：自动上下文压缩

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

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

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

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

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

加载位置：

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

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

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

// ~/.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。

注册自定义工具

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工具。

注册自定义命令

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包

# 从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进程运行在本地容器里，适合简单隔离场景：

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大模型广场支持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规范，格式基本一致。

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年版）。

延伸阅读