干翻 Claude Code！这个终端 AI 编程神器把"极简"玩到了变态级别

当所有 AI 编程工具都在比拼功能谁更全的时候，Pi Agent 选择了一条不同的路——把核心做到最小，把扩展交给用户。

前言

我接触 AI 编程工具这一阵子，越用越有一种别扭：它们都在替我做主。功能越堆越满，可我想关掉某个用不上的东西时，往往连个开关都找不到。我渐渐明确自己想要的，不是一个"什么都会"的巨无霸，而是一个"核心很小、扩展我自己说了算"的底座。

如果你也关注过这一赛道，大概率听说过 Claude Code、GitHub Copilot CLI、OpenAI Codex CLI 这些名字。它们各有所长，但共同特点正是我上面说的——功能越来越重，内置越来越多。

Pi Agent（全称 Pi Coding Agent）反其道而行，正好踩中了我想要的那个点。它的官方理念是一句很有态度的话：

“There are many agent harnesses but this one is yours”（Agent 工具很多，但这个是你自己的）

这句话不是营销口号。Pi Agent 真的把大量高级功能从核心中移除，交给扩展系统按需安装，核心只保留最基础的能力：读文件、写文件、编辑文件、执行命令。

本文是我基于 Pi Agent 官方文档、结合自己上手体验梳理而成，聚焦它的核心设计理念、实用功能和差异化优势，帮你快速判断这个工具是否值得上手。

---

一、Pi Agent 是什么

Pi Agent 是一个运行在终端中的 AI 编程助手，由 earendil-works 团队开发。你在项目目录中启动它，用自然语言描述需求，它会读取代码、执行命令、修改文件，像一个协作开发者一样工作。

它的核心定位可以用三个关键词概括：

• 终端原生：没有 GUI，没有 Electron，纯 TUI 界面
• 极简核心：核心内置工具极少（最基础的 read / write / edit / bash，另含 grep / find / ls 等检索工具），其余全部可插拔
• 可组合：通过 Extensions、Skills、Prompt Templates、Themes、Packages 五种方式扩展

---

二、设计哲学：小核心，大生态

Pi Agent 最值得聊的不是某个功能，而是它的设计哲学。

大多数工具的演进路径是：功能越来越多 → 越来越臃肿 → 维护成本飙升 → 用户体验下降。Pi Agent 的创作者显然想避免这条路径，他们选择了一条 Unix 哲学式的路线：

核心保持最小化，工作流相关的功能通过扩展体系实现，而不是内置到核心中。

这意味着：

• 核心代码量小，维护和理解成本低
• 你可以只安装真正需要的功能
• 扩展开发门槛低——TypeScript 文件即可，无需编译
• 社区可以自由贡献和分享扩展包

这种设计带来的实际好处是什么？举个例子：如果你只需要一个能在终端里帮你改 bug 的 AI 助手，Pi Agent 开箱即用，零额外配置。如果你需要 MCP 协议支持、子代理编排、自动化 CI 集成，这些都可以通过安装对应的扩展包来实现。

与 Claude Code / Codex CLI 的对比：

对比维度	Pi Agent	Claude Code	Codex CLI
核心大小	极简，无内置 MCP/子代理等	功能较多（Hook、MCP、子代理等）	中等
扩展方式	TypeScript 扩展 + Skills + 包	Hook + MCP 服务器 + Skills	Skills + MCP
支持的 AI 提供商	30+（订阅 + API Key）	Anthropic API 为主	GitHub Copilot / OpenAI
会话管理	树状分支，支持 fork/clone	线性 + 分支恢复	基本会话管理
包生态系统	有（npm/git 分发包）	无内置包管理	Skills 仓库
本地模型支持	内置 llama.cpp 支持	不支持	不支持
MCP 支持	核心不内置，需通过扩展实现	原生内置 MCP	支持 MCP
权限管控	无原生命令级弹窗，需自行写扩展拦截	内置文件读写授权弹窗	有内置权限机制
生态成熟度	社区扩展较少，偏早期	官方生态完善	官方生态较完善

这个对比很有意思。Pi Agent 在"核心功能数量"上是最少的，但在"可扩展性"和"模型选择自由度"上反而是最强的。它不绑死任何一家 AI 提供商——你可以用 Claude Sonnet 做复杂推理，用 DeepSeek 做日常编码，甚至用本地 llama.cpp 模型做离线任务。

---

三、30+ AI 提供商：模型自由

这是 Pi Agent 最实用的差异化优势之一。

大多数 AI 编程工具绑定特定模型生态。Claude Code 绑定 Anthropic，Codex CLI 绑定 OpenAI。而 Pi Agent 支持 30+ AI 提供商，包括：

• Anthropic（Claude 系列）
• OpenAI（GPT 系列）
• Google Gemini
• DeepSeek
• Groq
• xAI
• Mistral
• llama.cpp 本地模型
• 以及更多兼容 OpenAI 接口的第三方提供商

在交互模式中，你可以用 Ctrl+L 打开模型选择列表，或用 Ctrl+P 在收藏模型间快速切换。这意味着你可以根据任务复杂度选择不同模型——简单任务用便宜的 DeepSeek Flash，复杂推理用 Claude Sonnet，离线场景用本地模型。

接入 DeepSeek 的实操

以 DeepSeek 为例，接入过程非常简洁。DeepSeek 提供 OpenAI 兼容接口，Pi Agent 直接复用现有的 OpenAI 适配层，无需额外开发适配器。核心工作只有两步：

1. 在 models.json 中声明供应商和模型参数
2. 通过环境变量提供 API Key

配置文件路径：

• Linux / macOS: ~/.pi/agent/models.json
• Windows: %USERPROFILE%\.pi\agent\models.json

配置内容示例：

{
  "providers": {
    "deepseek": {
      "baseUrl": "https://api.deepseek.com",
      "api": "openai-completions",
      "apiKey": "$DEEPSEEK_API_KEY",
      "models": [
        {
          "id": "deepseek-v4-pro",
          "name": "DeepSeek V4 Pro",
          "contextWindow": 1000000,
          "maxTokens": 384000,
          "reasoning": true,
          "cost": {
            "input": 0.435,
            "output": 0.87,
            "cacheRead": 0.003625,
            "cacheWrite": 0
          }
        },
        {
          "id": "deepseek-v4-flash",
          "name": "DeepSeek V4 Flash",
          "contextWindow": 1000000,
          "maxTokens": 384000,
          "reasoning": true,
          "cost": {
            "input": 0.14,
            "output": 0.28,
            "cacheRead": 0.0028,
            "cacheWrite": 0
          }
        }
      ]
    }
  }
}

注意 apiKey 字段使用 $DEEPSEEK_API_KEY 环境变量引用，而不是明文写入密钥。这是 Pi Agent 的安全设计——API Key 不落盘到配置文件，通过环境变量注入。

密钥安全补充：① Windows 下用 set 临时设的环境变量仅当前终端会话有效，重启即丢失，建议写入 ~/.pi/agent/auth.json 或系统/用户环境变量做持久化；② Pi 也允许在 auth.json / models.json 中明文写密钥（不推荐），文件一旦泄露即等于泄露密钥，建议用环境变量或 auth.json 并设 chmod 600 限制权限。另外，models.json 属于 provider/模型配置，改动后需重启 Pi 会话才能生效，/reload 不会重载它（见第六节）。

DeepSeek 的两个模型定位差异明显：V4 Pro 适合复杂推理任务（$0.435/M input），V4 Flash 更快更便宜（$0.14/M input），可以根据场景灵活选择。

---

四、树状会话：AI 对话的"版本控制"

这是 Pi Agent 最独特的特性，也是我个人认为最惊艳的设计。

传统的 AI 对话是线性的——你问它答，一路聊到底。如果你想回到之前的某个节点换个方向探索，要么重新开始，要么在已有对话中"硬拐弯"，之前的上下文就乱了。

Pi Agent 把会话做成了树状结构：

├─ user: "帮我实现一个登录功能..."
│  └─ assistant: "好的，我来实现..."
│     ├─ user: "用 JWT 方案..."
│     │  └─ assistant: "使用 JWT 实现..."
│     │     └─ user: "测试通过了"  ← 当前活跃分支
│     └─ user: "还是用 Session 方案..."
│        └─ assistant: "使用 Session 实现..."

你可以从同一个起点出发，分别探索 JWT 和 Session 两个方案，每个方案的完整对话都被保留。通过 /tree 命令打开会话树浏览器，可以在分支间自由跳转。

三个会话管理命令的区别：

命令	作用	典型场景
/tree	在同一会话文件中浏览和跳转分支	多条思路放在一起管理，方便对比
/fork	从选定的历史节点新建一个独立会话文件（原文件保持不变），从该断点重新探索	对早前的方案另起炉灶，不影响已有会话
/clone	把当前活动分支（或整棵会话树）复制成新会话文件作为副本	继续之前先留一份退路，随时可回到副本

简单记：/fork 是"从过去某个岔路口重新走一条新路"（原路保留），/clone 是"先把当下的整条路复印一份再继续"（留备份）。多分支复杂场景优先用 /fork 做平行实验，用 /clone 做安全快照。

当你从一个分支跳到另一个分支时，Pi Agent 还可以为被放弃的分支生成摘要，让你在新分支中知道之前探索了什么。这个设计把"AI 对话的版本控制"变成了现实。

---

五、Skills 系统：渐进式披露的智慧

Skills（技能）是 Pi Agent 的另一大亮点，它实现了一个叫做"渐进式披露（Progressive Disclosure）"的设计模式。

什么是 Skill

一个 Skill 就是一个包含 SKILL.md 文件的目录。SKILL.md 中包含技能的名称、描述和详细的使用指令，AI 会在需要时自动读取并执行。

你可以把 Skill 理解为 AI 的"专业培训手册"——平时不占上下文空间，需要时才加载。

工作原理

1. Pi Agent 启动时扫描所有 Skill 位置，只提取名称和描述
2. 所有可用 Skill 的描述以 XML 格式嵌入系统提示词中（占用极少的 token）
3. 当用户的任务匹配某个 Skill 的描述时，AI 自动用 read 工具加载完整的 SKILL.md
4. AI 按照指令工作，使用相对路径引用技能目录中的脚本和资源

这种设计的巧妙之处在于：100 个 Skill 的元信息开销 ≈ 一段系统提示词的长度，但完整的指令只在需要时才加载。

Skill 的目录结构

my-skill/
├── SKILL.md              # 必需：Frontmatter + 指令
├── scripts/              # 辅助脚本
│   └── process.sh
├── references/           # 详细参考文档（按需加载）
│   └── api-reference.md
└── assets/
    └── template.json

SKILL.md 使用 YAML Frontmatter 定义元信息：

---
name: brave-search
description: 通过 Brave Search API 进行网页搜索和内容提取。适用于搜索文档、事实查询或任何网页内容检索。
---

其中 description 是 AI 决定是否加载该 Skill 的关键依据。一个模糊的 description 会导致在不合适的场景被触发，或者在需要的场景被忽略。

兼容性

Pi Agent 实现了 Agent Skills 标准，并且可以直接加载 Claude Code 或 OpenAI Codex 的 Skills：

{
  "skills": [
    "~/.claude/skills",
    "~/.codex/skills"
  ]
}

这意味着如果你之前已经在用 Claude Code 积累了 Skills，迁移到 Pi Agent 时无需重写。

补充两点：① 除了自动匹配，你也可以用 /skill:技能名 手动触发某个 Skill；② 兼容 Claude Code / Codex 的 Skills 时，路径解析与资源引用规则可能不同（Pi 用相对于技能目录的路径引用脚本和资源），迁移后建议实际跑一遍验证，避免相对路径失效。

---

六、TypeScript 扩展：无限可能

如果说 Skills 是"Markdown 写的工作流指令"，那么 Extensions 就是"TypeScript 写的代码级扩展"。

Extension 可以做到：

• 注册自定义工具——AI 可以调用的新功能
• 注册自定义命令——用户通过 /命令名 调用
• 监听生命周期事件——在 AI 工作的各个阶段插入逻辑
• 注册键盘快捷键
• 展示自定义 UI

示例依赖两个包，首次使用请先安装：npm i typebox @earendil-works/pi-coding-agent（或放进项目依赖）。

一个 Hello World 级别的 Extension 长这样：

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

export default function (pi: ExtensionAPI) {
  // 会话启动时触发
  pi.on("session_start", async (_event, ctx) => {
    ctx.ui.notify("我的扩展已加载！", "info");
  });

  // 拦截危险命令
  pi.on("tool_call", async (event, ctx) => {
    if (event.toolName === "bash"
      && event.input.command?.includes("rm -rf")) {
      const ok = await ctx.ui.confirm("危险操作！", "确认执行 rm -rf？");
      if (!ok) return { block: true, reason: "用户阻止" };
    }
  });

  // 注册自定义工具
  pi.registerTool({
    name: "greet",
    label: "打招呼",
    description: "向指定的人打招呼",
    parameters: Type.Object({
      name: Type.String({ description: "要打招呼的人名" }),
    }),
    async execute(toolCallId, params) {
      return {
        content: [{ type: "text", text: `你好，${params.name}！` }],
        details: {},
      };
    },
  });
}

这个示例展示了三个核心能力：事件监听（session_start、tool_call）、自定义工具注册（registerTool）和 UI 交互（notify、confirm）。

扩展通过 jiti 加载，TypeScript 代码无需编译即可直接运行。放在 ~/.pi/agent/extensions/（或项目 .pi/extensions/）目录中的扩展支持 /reload 热重载。

/reload 的边界：它主要重载扩展、Skills、提示词模板、主题和上下文文件（AGENTS.md 等）；但 models.json 这类 provider/模型配置改动不会被 /reload 生效，需要重启 Pi 会话。改完模型配置执行 /reload 发现不生效时，先重启再排查。

---

七、llama.cpp 本地模型：离线也能用

这是 Pi Agent 独有的能力——内置 llama.cpp 支持，可以直接在本地运行开源大模型，无需云端 API。

使用 /llama 命令管理本地模型：

/llama download    # 下载模型
/llama load        # 加载模型到内存
/llama unload      # 卸载模型
/llama list        # 查看已加载的模型

推荐的开源编码模型：

模型	参数量	量化建议	GPU 显存占用	CPU 纯推理内存	适用场景
Qwen 2.5 Coder	7B / 14B / 32B	Q4_K_M	8G / 16G / 32G	更高（建议 ≈2× 参数量）	通用编码、多语言
DeepSeek Coder V2	16B / 236B	Q4_K_M	16G / 很大	很大	复杂编程任务
CodeLlama	7B / 13B / 34B	Q4_K_M	8G / 16G / 32G	更高	代码补全、通用编码
Mistral	7B	Q4_K_M	8G	更高	轻量级编码助手

用量说明：表中"显存占用"指 GGUF 量化模型（如 Q4_K_M）走 GPU 推理的显存；若走 CPU 纯推理则占用内存（RAM），且常需参数量约 2 倍的内存、速度也更慢。显存不足会直接崩溃而非降级，选型前务必核对硬件。速度上，本地模型（尤其量化 / 小参数）的 tok/s 远低于云端前沿模型，复杂任务仍以云端为主。

当然，本地模型的编码能力通常弱于云端顶级模型。但在网络受限、数据敏感或需要频繁调用的场景下，这是一个非常有价值的备选方案。

推荐的混合策略：需要深度推理时用云端模型（如 Claude Sonnet），日常简单任务或网络受限时切换到本地模型，用 Ctrl+P 快速切换。

---

八、安全模型：不装沙盒，但讲清楚边界

Pi Agent 的安全设计很坦诚。它不在系统层面提供沙盒隔离，也不内置命令级的权限弹窗——明确告诉你：它以你当前用户的权限运行，能访问你账户能访问的所有文件，能执行的命令范围与你手动在终端操作完全一致。

但"无沙盒"不等于"无任何防护"：你可以用扩展监听 tool_call 事件做自定义拦截（如本文第六节那个 rm -rf 确认示例），这是应用层的阻断，不是系统级隔离。

这是有意为之的。Pi Agent 的设计哲学是：不提供"看似安全实则容易误解"的半成品沙盒。真正的隔离来自操作系统或虚拟化/容器边界。

项目信任机制（defaultProjectTrust）要分清两件事：它只决定启动时是否加载项目内的扩展 / Skills / 配置，并不限制 bash / read / write 等工具的权限。把"信任了项目配置"误当成"文件/命令被隔离"是新手最常见的误解。当检测到项目中有 .pi/settings.json、.pi/extensions 等项目资源时，会触发信任检查：

defaultProjectTrust 值	交互模式行为	非交互模式行为
"ask"（默认）	弹出信任确认提示	不加载项目资源
"always"	自动信任	自动信任
"never"	自动拒绝	自动拒绝

对于不受信任的仓库，官方建议在 Docker 容器或 VM 中运行，使用只读挂载和最小权限临时凭证。

---

九、快速上手

安装

# npm 全局安装
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# 或 curl 一键安装（Linux/macOS）
curl -fsSL https://pi.dev/install.sh | sh

验证安装：

pi --version

安装注意：① curl … | sh 会直接把远程脚本交给 shell 执行，存在供应链风险，正式环境建议先 curl … -o install.sh && cat install.sh 审查再执行，或直接用 npm 方式；② --ignore-scripts 是官方推荐写法（Pi 正常安装不依赖安装脚本，加上它反而规避供应链攻击，且不影响本地模型——本地模型靠独立的 llama.cpp / llama-server，并非 npm 安装时下载的二进制）；③ Windows 用户需先安装 Git for Windows（提供 bash shell），否则 Pi 无法运行。

启动

cd /path/to/your-project
pi

核心快捷键速查

操作	快捷键
提交输入	Enter
模型选择	Ctrl+L
切换模型	Ctrl+P / Shift+Ctrl+P
推理等级	Shift+Tab
展开/折叠工具输出	Ctrl+O
展开/折叠推理过程	Ctrl+T
中断操作	Escape
退出	Ctrl+D 或 /quit

Shift+Tab 在 off / minimal / low / medium / high / xhigh / max 多档推理强度间循环，档位越高思考越深、耗时与 token 消耗越多。

非交互模式

# 一次性问答
pi -p "总结一下这个代码库"

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

# 只读模式（仅开放读文件与检索类内置工具，禁用 write/edit/bash，避免误改）
pi --tools read,grep,find,ls -p "审查代码不修改"

--tools 是内置工具白名单：只放行列出的工具，其余（如 write、edit、bash）全部禁用。做代码审查优先用 read,grep,find,ls 而非 bash——因为 bash 能执行任意命令，并不真正"只读"。

Print 模式（-p）非常适合集成到脚本和 CI 流程中。

上下文文件

创建 AGENTS.md 让 AI 了解你的项目规范：

# 项目指令
- 代码修改后运行 `npm run check` 验证
- 提交前运行 `npm test` 确保测试通过
- 回复保持简洁，不要过度解释显而易见的代码
- 使用 TypeScript 严格模式

Pi Agent 会在启动时自动加载这个文件。修改后用 /reload 热重载，无需重启。

如果你之前使用 Claude Code，已有的 CLAUDE.md 文件可以直接被 Pi Agent 识别使用，无需重命名。

---

十、四种运行模式

Pi Agent 不只有交互模式，它支持四种模式适应不同场景：

模式	命令	适用场景
交互模式	pi	日常开发、交互式编程
Print 模式	pi -p "提示词"	脚本集成、快速查询
JSON 模式	pi --mode json	工具链集成、数据分析
RPC 模式	pi --mode rpc	进程间通信、编辑器插件

交互模式是你日常使用的。Print 模式适合一次性任务和 CI 集成。JSON 和 RPC 模式则面向更高级的工具链集成场景——比如你想把 Pi Agent 嵌入到自己的编辑器或工具中，RPC 模式通过 stdin/stdout 的 JSONL 协议让这一切成为可能。

使用约束：① RPC 模式不渲染 TUI，纯 stdin/stdout JSONL 协议，无法用键盘交互；② JSON / RPC 模式下没有终端界面，依赖 ctx.ui.confirm / ctx.ui.notify 弹窗的扩展会失效，相关扩展需改为非交互逻辑；③ 切换模型会保留并重发完整对话历史给新模型（/model 或 Ctrl+L），长对话切换会按新模型重新计费，产生额外 token 消耗，频繁切换注意成本。

---

十一、局限与注意事项（客观提醒）

前面写的都是优势，这里把短板说清楚，避免你踩坑：

• TUI 对终端有要求：界面依赖 24 位真彩色与 Kitty 键盘协议，老旧终端 / Windows 原生 cmd 会显示错乱或快捷键失灵。推荐 iTerm2、Kitty、WezTerm；Windows 用 Windows Terminal（需手动转发 Shift+Enter / Alt+Enter）或配合 WSL2。
• 纯社区驱动，迭代偏慢：相比 Claude Code 等大厂产品，Pi 的更新节奏与官方生态成熟度都更低，遇到 bug 可能要等社区或自己修。
• 高级能力都要自己搭：MCP、子代理、Plan 模式、CI 集成、后台任务等，核心一律不内置，要么装社区扩展包，要么自己写 TypeScript。开箱即用的"全家桶"体验它故意不给。
• 本地模型能力有阉割：本地（尤其小参数 / 量化）模型在复杂多工具链式调用、严格遵循 Skill 指令上明显弱于云端前沿模型；离线可用，但别指望它干重活。
• 无原生沙盒：再次强调，隔离靠你自己（Docker / VM），不要在未隔离环境跑不受信任的项目。

---

总结：Pi Agent 适合谁

结合上面的梳理，我的判断是：

适合你，如果：

• 你习惯在终端中工作，不喜欢 Electron 重型应用
• 你需要同时使用多个 AI 模型，不想被绑定到某一家
• 你有数据敏感场景，需要本地模型支持
• 你喜欢可组合的工具链，而非大而全的单体应用
• 你会写 TypeScript，想要深度定制自己的 AI 工具
• 你需要会话分支来探索不同实现方案

可能不适合，如果：

• 你完全不熟悉命令行操作
• 你需要开箱即用的 MCP、子代理等高级功能，不想手动安装扩展
• 你希望工具有内置的沙盒隔离机制

回到开头我说的——我要的不是一个"什么都会"的工具，而是一个"我说了算"的底座，Pi Agent 给的正是这个。它的价值不在于做了多少功能，而在于选择不做什么。在 AI 工具越来越重的趋势下，这种"少即是多"的设计哲学本身就是一个值得关注的方向。

---