如果你也在找一个「不绑架供应商、能深度定制、还能嵌进自己程序」的终端 AI 编码 Agent,那 Pi 值得一试。它和 Claude Code、OpenAI Codex CLI 是同一类东西,但设计哲学很不一样:最小内核 + 极强可扩展性——核心极小,几乎一切「功能」都靠扩展、技能、自定义 Provider 补上。

这篇文章是我边读 Pi 官方文档、边对照本地源码仓库(v0.80.7)整理出来的使用向指南。从「它是什么」一路讲到「怎么配模型、怎么用、怎么扩展」。如果你只想先跑起来,直接跳到第 4 节;想理解它的设计,第 1、2 节别跳过。


1. Pi 是什么(定位与理念)

一句话:运行在终端里的 AI 编码 Agent,类似 Claude Code、OpenAI Codex CLI。

Pi 的官方理念是 “There are many agent harnesses but this one is yours”——Agent 工具很多,但这个是你自己的。「你的」意味着完全自主可控,体现在五个层面:

  1. 模型自主:不捆绑任何模型供应商,15+ 家任选,Key 归你管、账单归你控,想换就换。
  2. 权限自主:工具启用/禁用由你决定(--tools / --exclude-tools),文件读写、命令执行都在你的用户权限下跑,没有隐藏的后台进程或云端代理。
  3. 行为自主:扩展(Extensions)和技能(Skills)架构让你可以拦截、修改、替换 Agent 的任何行为——从工具调用到上下文注入,从快捷键到 UI 面板,全部可编程。
  4. 数据自主:会话历史、配置、凭证全部落本地(~/.pi/agent/),不上传任何遥测或使用数据(除非你主动 /share),源码开源可审计。
  5. 集成自主:四种运行模式(交互 / Print / RPC / SDK)覆盖从日常编码到脚本自动化再到程序嵌入的全部场景,你决定 Agent 以什么形态融入你的工作流,而不是反过来。

工作方式:给一句话,它在项目目录里读文件、写文件、跑命令,循环调用大模型直到完成任务。

核心哲学:最小内核 + 极强可扩展性(Primitives, Not Features / 「原语而非功能」)。这句话不是口号,后面第 2 节我会用真实的代码量把它坐实。

金句:Adapt Pi to your workflows, not the other way around.(让 Pi 适应你的工作流,而不是反过来。)

设计取舍:Pi 故意不内置很多「看起来应该有」的功能,而是用扩展或 CLI 替代。理解这一点,你就不会总问「为什么 Pi 没有 XXX」:

不内置的功能 Pi 的替代方案
MCP 协议集成 把工具写成带 README 的 CLI,或装 MCP 扩展
子 Agent tmux 开多会话,或自己写扩展
权限确认弹窗 放进容器跑,或自己写确认流程扩展
计划模式 把计划写文件,或写扩展
内置待办事项 用 TODO.md,或装扩展
后台 bash tmux 获得完整可观测性

适合谁:偏好终端工作流者、想深度定制甚至让 Agent 改写自己的进阶用户、需同时接多家模型者、想把 Agent 嵌进自己程序的开发者(SDK/RPC)。

安全前提:默认以用户权限运行,无内置沙箱;不受信任的仓库使用前先读第 16 节安全须知。


2. 代码规模与架构哲学(最小内核 + 极强可扩展性)

「最小内核」常常被人当营销话术,但 Pi 是真的。下面是我基于本地仓库(v0.80.7 tag)实测的数字:

  • 全仓 5 个包、382 个文件、约 113,242 行
  • 各包规模:
文件数 行数 角色
ai 152 38,156 模型 / provider 适配层
coding-agent 164 52,710 编码 Agent 主体(含 CLI)
tui 28 12,145 终端 UI
agent 25 8,244 内核抽象(agent loop)
orchestrator 13 1,987 编排
总计 382 113,242 5 个包全量(不含测试)

「核心」有三层口径,对应第 1 节「最小内核」理念:

  1. 极简内核agent 包里定义 agent 能力的核心只有 3 个文件、约 1,370 行——
    • agent-loop.ts(792 行):主循环(收消息 → 调模型 → 跑工具 → 回灌)
    • agent.ts(575 行):agent 定义 / 工具调用
    • node.ts(2 行):节点原语
  2. 实现内核coding-agent/src/core/(目录名即 core)——44 个文件、约 26,824 行,落地会话管理、模型解析、扩展加载、工具、权限、资源加载。
  3. 全仓:382 文件 / 约 11.3 万行。

为什么「功能」几乎不在内核:11.3 万行里有大量是 TUI、模型解析、扩展加载这些可扩展层;真正定义「agent 能做什么」的抽象极薄,其余全靠扩展(Extensions)、技能(Skills)、自定义 Provider 补上——这正是第 1 节「原语而非功能 / Primitives, Not Features」的工程量佐证。

读码起点:想验证上面说法,直接看 agent/src/agent-loop.ts(3 个文件就能读懂内核),再进 coding-agent/src/core/ 看落地。


3. 四种运行模式

Pi 不是只能「开个终端对话」,它有四种形态,对应不同的使用场景:

模式 说明 典型入口
Interactive 完整终端 UI(TUI),日常编码 直接 pi
Print / JSON 一次性输出 / 事件流,脚本自动化 pi -p "..." / --mode json
RPC stdin/stdout JSON 协议,非 Node 程序集成 --mode rpc
SDK 作为库嵌入 Node 应用 import { ... } from "@earendil-works/pi-coding-agent"

日常用 Interactive 就够了;想把 Pi 接进 CI、脚本或自己的程序,后三种模式是关键。第 12 节会展开。


4. 安装 Pi

两种方式,新手推荐一键脚本。

方式一:一键脚本(推荐新手)

# macOS / Linux
curl -fsSL https://pi.dev/install.sh | sh
# Windows(PowerShell)
powershell -c "irm https://pi.dev/install.ps1 | iex"

方式二:npm 全局安装(加 --ignore-scripts 更安全)

npm install -g --ignore-scripts @earendil-works/pi-coding-agent
# 等价:pnpm add -g --ignore-scripts ... / bun add -g --ignore-scripts ...

--ignore-scripts 关闭依赖的生命周期脚本;Pi 正常使用不依赖安装脚本。这是一个供应链安全约定——依赖的安装脚本能执行任意代码,关掉它更稳妥。

验证pi --version(例:0.80.7 区间)。

卸载npm uninstall -g @earendil-works/pi-coding-agent(或对应 pnpm/bun 全局移除命令)。

卸载不删配置,配置仍在 ~/.pi/agent/;需手动清理。


5. 配置模型 Provider(Pi 不含模型,需自备凭证)

Pi 本身不带模型,你得自己提供 API 凭证。录入凭证主要有 多种方式,常见的是以下四种:

1、订阅登录(省心,自动管 Key)
2、API Key(灵活,自管 Key)
3、自定义模型供应商
4、云平台

现在介绍前三种。

5.1 方式一:订阅登录账号

最省心的方式——用你已有的订阅账号授权,Pi 自动管 Key。

  • 适用供应商:Claude Pro/Max、ChatGPT Plus/Pro(Codex)、GitHub Copilot。
  • 怎么用:进 Pi 后输入 /login,按提示授权;退出用 /logout
  • 凭证落点:自动写入 ~/.pi/agent/auth.json,过期自动刷新,无需手动维护 Key

/login 进入后:

Pi使用指南(大纲)-1784616864329.webp

选择使用账号登陆:

Pi使用指南(大纲)-1784616670577.webp

选择订阅账号供应商:

Pi使用指南(大纲)-1784616580409.webp

5.2 方式二:API Key(自管 Key,15+ 家供应商)

适用 Anthropic / OpenAI / Google / DeepSeek 等 几十 家,有三种方法录入 Key:

A 方法:/login 选择 API key 登录

Pi使用指南(大纲)-1784616762871.webp

截图里列出了 35 个供应商可直接填 Key:

Pi使用指南(大纲)-1784616784032.webp

B 方法:环境变量(当前 shell 生效,临时)

export ANTHROPIC_API_KEY=sk-ant-...      # Anthropic
export OPENAI_API_KEY=sk-...             # OpenAI
export GEMINI_API_KEY=...                # Google
export DEEPSEEK_API_KEY=...              # DeepSeek
# 15+ 家,变量名见官方 Providers 文档:https://pi.dev/docs/latest/providers#api-keys

C 方法:持久化到 auth.json(长期生效)

auth.json 里写 Key 的三种写法:

  • "!命令":运行时执行该命令,取 stdout 作为 Key(如从密钥管理器取)。
  • "$变量名":读取同名环境变量作为 Key。
  • 字面量:直接把 Key 字符串写进 auth.json。

5.3 进阶:自定义模型与供应商(models.json)

如果你想接 Ollama、vLLM、LM Studio、代理,或 DeepSeek 这类「非内置供应商」,靠 models.json 实现。

  • 入口文件~/.pi/agent/models.json(Windows:%USERPROFILE%\.pi\agent\models.json)。每次打开 /model 自动重载,编辑后无需重启;无 auth 时模型会加载但不可用。

  • 用途:把 Ollama / vLLM / LM Studio / 代理 / DeepSeek 等「非内置供应商」接进来,或覆盖内置供应商的 endpoint。

  • 顶层结构providers 对象,每个 provider 含连接信息 + models 数组:

    {
      "providers": {
        "provider-name": {
          "baseUrl": "https://...",
          "api": "openai-completions",
          "apiKey": "$ENV_VAR",
          "models": [ ... ]
        }
      }
    }
    
  • Provider 字段baseUrl(API 地址) / api(API 类型) / apiKey(可选,也可走 /login、auth.json、--api-key) / oauth(动态 OAuth,如 "radius",需 gateway baseUrl) / headers / authHeader(设 true 自动加 Authorization: Bearer <apiKey>) / modelOverrides(逐模型覆盖内置/已注册模型)。

  • 支持的 API 类型(apiopenai-completions(最兼容) / openai-responses / anthropic-messages / google-generative-ai。可在 provider 级设默认,model 级覆盖。

  • apiKey / headers 的三种写法(与 5.2 的 auth.json 一致):"!命令"(执行命令取 stdout) / "$ENV_VAR""${ENV_VAR}"(环境变量) / 字面量;"$$" 字面 $"$!" 字面 !

  • 模型字段(models 数组每项)

字段 必填 说明
id 传给 API 的模型标识
name 人类可读标签,用于 /model 显示与匹配
api 覆盖 provider 的 api
reasoning 是否支持扩展思考
thinkingLevelMap pi 思考级别 → provider 值映射(见下)
input ["text"]["text","image"]
contextWindow 上下文窗口(tokens),默认 128000
maxTokens 最大输出(tokens),默认 16384
cost 每百万 token 费率 input/output/cacheRead/cacheWrite
compat provider 兼容项(合并 provider 级)
  • thinkingLevelMap(控制思考强度):pi 级别 off / minimal / low / medium / high / xhigh / max。值为 string=发送该值;null=不支持(隐藏/跳过);省略=用 provider 默认(xhigh/max 不支持)。

  • 示例 A:DeepSeek(OpenAI 兼容,来自 DeepSeek 官方接入指南)

    {
      "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,
              "input": ["text"],
              "reasoning": true,
              "cost": { "input": 1.74, "output": 3.48, "cacheRead": 0.145, "cacheWrite": 0 }
            },
            {
              "id": "deepseek-v4-flash",
              "name": "DeepSeek V4 Flash",
              "contextWindow": 1000000,
              "maxTokens": 384000,
              "input": ["text"],
              "reasoning": true,
              "cost": { "input": 0.14, "output": 0.28, "cacheRead": 0.028, "cacheWrite": 0 }
            }
          ]
        }
      }
    }
    
    • 配好后 export DEEPSEEK_API_KEY=...(Windows:$env:DEEPSEEK_API_KEY=...);进项目 pi/model → 选 deepseek → 选 Pro / Flash。
    • ⚠️ 字段差异提醒:DeepSeek 官方示例里用 compat.reasoningEffortMap 控思考强度,但 Pi 官方文档已将其标记为旧字段,应改用 model 级 thinkingLevelMap(见上表);写新配置请以官方为准。
  • 示例 B:本地 Ollama(最简,仅 id 必填)

    {
      "providers": {
        "ollama": {
          "baseUrl": "http://localhost:11434/v1",
          "api": "openai-completions",
          "apiKey": "ollama",
          "models": [ { "id": "llama3.1:8b" }, { "id": "qwen2.5-coder:7b" } ]
        }
      }
    }
    
  • 示例 C:覆盖内置供应商(走代理)——只设 baseUrl 即可把请求路由到代理:

    { "providers": { "anthropic": { "baseUrl": "https://my-proxy.example.com/v1" } } }
    
  • 自定义供应商(非 OpenAI/Anthropic 协议):实现自定义 API 与 OAuth 流,详见官方 Custom providers 文档。

不想了解,直接粘贴DeepSeek 官方《接入Pi》给出的完整配置内容,注意变量$DEEPSEEK_API_KEY的替换:

{
  "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,
          "input": ["text"],
          "reasoning": true,
          "cost": {
            "input": 1.74,
            "output": 3.48,
            "cacheRead": 0.145,
            "cacheWrite": 0
          },
          "compat": {
            "requiresReasoningContentOnAssistantMessages": true,
            "thinkingFormat": "deepseek",
            "reasoningEffortMap": {
              "minimal": "high",
              "low": "high",
              "medium": "high",
              "high": "high",
              "xhigh": "max"
            }
          }
        },
        {
          "id": "deepseek-v4-flash",
          "name": "DeepSeek V4 Flash",
          "contextWindow": 1000000,
          "maxTokens": 384000,
          "input": ["text"],
          "reasoning": true,
          "cost": {
            "input": 0.14,
            "output": 0.28,
            "cacheRead": 0.028,
            "cacheWrite": 0
          },
          "compat": {
            "requiresReasoningContentOnAssistantMessages": true,
            "thinkingFormat": "deepseek",
            "reasoningEffortMap": {
              "minimal": "high",
              "low": "high",
              "medium": "high",
              "high": "high",
              "xhigh": "max"
            }
          }
        }
      ]
    }
  }
}

5.4 配置优先级

凭证解析顺序(这不是一种录入方式,而是所有方式都遵循的通用规则——Pi 按以下优先级从高到低取 Key):

  1. --api-key 命令行参数
  2. auth.json
  3. 环境变量
  4. models.json 里的自定义 Key

6. 第一次运行

  • 进入项目目录,运行 pi,输入一句话(如「总结这个仓库」)即可。
  • 项目信任提示:检测到 .pi 等资源时,交互式启动会询问是否信任;选择存入 trust.json
    • 非交互模式按 defaultProjectTrust 处理。
  • Agent 工作循环:用户消息 → turn 循环(模型调工具 → 执行 → 结果塞回上下文 → 继续)→ 直到给出最终回复。

7. 四个内置工具

Pi 开箱带四个核心工具,外加三个默认关闭的只读工具:

工具 作用 默认启用
read 读文件
write 创建 / 覆盖文件
edit 局部补丁修改
bash 运行 shell
grep / find / ls 搜索 / 查找 / 列目录 否(需开启)
  • 控制参数--tools--exclude-tools--no-builtin-tools--no-tools
  • 提醒:工具能改文件,建议全程配合 git 使用。

8. AGENTS.md 项目指令

类似 Claude 的 CLAUDE.md,Pi 同时支持 AGENTS.mdCLAUDE.md 两个文件名。

  • 这个文件怎么来的(重点):Pi 不会自动生成 AGENTS.md,也没有 /init 这类初始化命令;它是你(或让 Pi 用 write 工具)手动创建的文件,Pi 只在启动时去发现并加载。
    • 创建方式:① 直接手写(项目根目录或 ~/.pi/agent/AGENTS.md);② 让 Pi 自己写——对它说「给这个项目写个 AGENTS.md」,它用 write 工具生成。
    • 发现机制:启动时 loadProjectContextFiles()全局 ~/.pi/agent/ + 从 cwd 逐级向上 找 AGENTS.md/CLAUDE.md(大小写不敏感),全部内容拼接进系统提示;可用 --no-context-files-nc)关闭。
  • 加载顺序(由大到小,当前目录优先最高)
    全局 ~/.pi/agent/AGENTS.md → 父目录 → 当前目录。
  • 修改系统提示
    • .pi/SYSTEM.md:整段替换系统提示。
    • .pi/APPEND_SYSTEM.md:追加到系统提示。
    • 改后需 /reload 或重启 Pi 生效。

9. 交互模式常用操作

  • 引用文件:输入 @ 触发模糊搜索;命令行也可以写成 pi @README.md "..."
  • 运行命令!cmd 输出进上下文;!!cmd 输出不进上下文。
  • 切换模型 / 思考强度/modelCtrl+LShift+Tab 循环思考强度;Ctrl+P 循环收藏模型。
  • 启动即指定--provider --model、厂商/模型、名称:思考强度--models(多模型循环)。
  • 输入技巧Shift+Enter 多行;Tab 路径补全;Ctrl+V 粘图;Ctrl+G 用外部编辑器。
  • 边跑边插话Enter 转向;Alt+Enter 追加后续;Escape 中止当前执行。

10. 斜杠命令速查

命令 说明
/login /logout 订阅登录 / 退出
/model /scoped-models 选模型 / 作用域模型
/settings 打开设置
/resume /new /name /session 会话:恢复 / 新建 / 命名 / 管理
/tree /fork /clone 会话树:跳转 / 分叉 / 复制分支
/compact 压缩上下文
/copy /export /import /share 复制 / 导出 HTML / 导入 / 私有 Gist 分享
/reload /trust /hotkeys /changelog /quit 重载 / 信任 / 快捷键 / 更新日志 / 退出

11. 会话管理(树形历史)

Pi 的会话是树形的,可以任意分叉而不丢分支——这是它比很多同类工具好用的地方。

  • 会话存 ~/.pi/agent/sessions/,按工作目录归类;任意分叉不丢分支
  • 恢复pi -c(最近一次)、pi -r(浏览历史)、--name--session--no-session
  • 导航/tree 跳节点;/fork 从历史分叉;/clone 复制分支。
  • 压缩/compact [提示] 手动或自动压缩上下文(详见官方 Compaction 文档)。
  • 导出 / 分享/export 导出 HTML;/share 发布为私有 Gist。

12. 非交互与程序化集成

除了交互模式,Pi 还能当「工具」用:

  • Printpi -p "...",支持管道输入、带图,跑完即退。
  • JSON 事件流--mode json,结构化事件,适合脚本消费。
  • RPC--mode rpc,stdin/stdout JSONL 协议,给非 Node 程序驱动。
  • SDK:Node 应用内嵌(@earendil-works/pi-coding-agent 作为库),比 RPC 更紧密。
  • 导出pi --export session.jsonl output.html
  • 三种程序化入口的权威细节见官方:SDK / RPC / JSON event stream 三篇文档。

13. 扩展 Extensions(核心可定制能力)

Pi 的「功能」主要靠扩展实现。

  • 形态:TypeScript 模块,用 jiti 直接加载,无需编译
  • 位置:全局 ~/.pi/agent/extensions/*.ts;项目 .pi/extensions/*.ts
  • 能做什么(能力表):
    registerTool(注册工具)/ registerCommand(命令)/ registerShortcut(快捷键)/ tool_call 拦截 / context 修改 / sendMessage / registerProvider(自定义供应商)/ ctx.ui(自定义 UI)。
  • 最小示例:监听事件、拦截危险命令、注册工具或命令。
  • 本地测试pi -e ./my-extension.ts
  • 生态:官方提供 50+ 示例扩展。

14. 技能 Skills

  • 实现 Agent Skills 标准,兼容 Claude Code / Codex 技能。
  • 渐进式披露:仅名字 + 描述进提示;匹配到时才 read 加载正文。
  • 位置:全局 ~/.pi/agent/skills/~/.agents/skills/;项目 .pi/skills/(需信任)。
  • 结构:目录含 SKILL.md(必填 frontmatter:name / description)+ 任意附带文件。
  • 手动调用/skill:名称 [参数]

15. Pi 包管理 + 其他定制

  • Pi 包管理(打包分享扩展/技能/提示/主题):

    pi install npm:@foo/pi-tools     # 从 npm 装
    pi install git:github.com/...    # 从 git 装
    pi install -l <本地路径>          # 本地装
    pi remove <source>               # 卸载
    pi update                         # 更新 pi 自身
    pi update --all                  # 连同扩展一起更新
    pi list                           # 列出已装
    pi config                         # TUI 管理扩展/资源开关
    
  • 自定义模型~/.pi/agent/models.json 添加受支持供应商的模型条目(对应官方 Custom models)。

  • 自定义供应商:实现自定义 API 与 OAuth 流(官方 Custom providers)。

  • 提示模板 Prompt templates:可复用提示,从斜杠命令展开(官方 Prompt templates)。

  • 主题 Themes:内置 + 自定义终端主题(官方 Themes)。


16. 安全须知(务必读)

  • 无内置沙箱:以用户身份运行;真实隔离靠 OS / 容器。
  • 项目信任ask(默认)/ always-a)/ never-na);存 trust.json
    • 信任机制只是输入加载守卫(防静默改设置),不防提示注入
  • 不可信任务处理:放容器 / VM;仅挂必要工作区;不挂 ~/.pi/agent;最少 Key;限制网络;审查 diff。
  • 官方容器化文档:Gondolin / Docker / OpenShell 三种沙箱方案。

17. 参考资源

官方核心资源

  • 官网:https://pi.dev
  • 官方文档(Latest):https://pi.dev/docs/latest
  • 源码仓库:https://github.com/earendil-works/pi
  • npm 包:@earendil-works/pi-coding-agent(https://www.npmjs.com/package/@earendil-works/pi-coding-agent)
  • 一键安装脚本:https://pi.dev/install.sh,https://pi.dev/install.ps1

官方文档分章节(按本文涉及主题)

  • 快速开始 Quickstart:https://pi.dev/docs/latest/quickstart
  • 使用 Pi Using Pi(交互 / 斜杠命令 / 上下文文件 / CLI 参考):https://pi.dev/docs/latest/usage
  • Providers(内置供应商的订阅与 API Key 配置):https://pi.dev/docs/latest/providers
  • 安全 Security(项目信任 / 沙箱边界 / 漏洞上报):https://pi.dev/docs/latest/security
  • 容器化 Containerization(Gondolin / Docker / OpenShell 三种沙箱):https://pi.dev/docs/latest/containerization
  • 扩展 Extensions(TypeScript 模块:工具 / 命令 / 事件 / UI):https://pi.dev/docs/latest/extensions
  • 技能 Skills(Agent Skills 标准):https://pi.dev/docs/latest/skills
  • 提示模板 Prompt templates:https://pi.dev/docs/latest/prompt-templates
  • 主题 Themes:https://pi.dev/docs/latest/themes
  • Pi 包管理 Pi packages(打包分享扩展 / 技能 / 提示 / 主题):https://pi.dev/docs/latest/packages
  • 自定义模型 Custom models:https://pi.dev/docs/latest/models
  • 自定义供应商 Custom providers(自定义 API 与 OAuth 流):https://pi.dev/docs/latest/custom-provider
  • 程序化嵌入 SDK:https://pi.dev/docs/latest/sdk
  • RPC 模式(stdin/stdout JSONL 集成):https://pi.dev/docs/latest/rpc
  • JSON 事件流模式(Print 结构化事件):https://pi.dev/docs/latest/json
  • 会话管理 Sessions(分支 / 树形导航):https://pi.dev/docs/latest/sessions
  • 开发 Development(本地构建 / 项目结构 / 调试):https://pi.dev/docs/latest/development
  • 平台设置 Platform setup:Windows https://pi.dev/docs/latest/windows · Termux https://pi.dev/docs/latest/termux · tmux https://pi.dev/docs/latest/tmux · 终端设置 https://pi.dev/docs/latest/terminal-setup

第三方 / 中文资料

  • 菜鸟教程《Pi Coding Agent 入门教程》:https://www.runoob.com/ai-agent/pi-coding-agent.html
  • DeepSeek 官方《接入Pi》:https://api-docs.deepseek.com/zh-cn/quick_start/agent_integrations/pi_mono/
Logo

汇聚全球AI编程工具,助力开发者即刻编程。

更多推荐