Pi一个极简的harness agent使用指南
如果你也在找一个「不绑架供应商、能深度定制、还能嵌进自己程序」的终端 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 工具很多,但这个是你自己的。「你的」意味着完全自主可控,体现在五个层面:
- 模型自主:不捆绑任何模型供应商,15+ 家任选,Key 归你管、账单归你控,想换就换。
- 权限自主:工具启用/禁用由你决定(
--tools/--exclude-tools),文件读写、命令执行都在你的用户权限下跑,没有隐藏的后台进程或云端代理。 - 行为自主:扩展(Extensions)和技能(Skills)架构让你可以拦截、修改、替换 Agent 的任何行为——从工具调用到上下文注入,从快捷键到 UI 面板,全部可编程。
- 数据自主:会话历史、配置、凭证全部落本地(
~/.pi/agent/),不上传任何遥测或使用数据(除非你主动/share),源码开源可审计。 - 集成自主:四种运行模式(交互 / 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 节「最小内核」理念:
- 极简内核:
agent包里定义 agent 能力的核心只有 3 个文件、约 1,370 行——agent-loop.ts(792 行):主循环(收消息 → 调模型 → 跑工具 → 回灌)agent.ts(575 行):agent 定义 / 工具调用node.ts(2 行):节点原语
- 实现内核:
coding-agent/src/core/(目录名即 core)——44 个文件、约 26,824 行,落地会话管理、模型解析、扩展加载、工具、权限、资源加载。 - 全仓: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 进入后:

选择使用账号登陆:

选择订阅账号供应商:

5.2 方式二:API Key(自管 Key,15+ 家供应商)
适用 Anthropic / OpenAI / Google / DeepSeek 等 几十 家,有三种方法录入 Key:
A 方法:/login 选择 API key 登录

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

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 类型(
api):openai-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):
--api-key命令行参数auth.json- 环境变量
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.md 与 CLAUDE.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输出不进上下文。 - 切换模型 / 思考强度:
/model或Ctrl+L;Shift+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 还能当「工具」用:
- Print:
pi -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/
更多推荐

所有评论(0)