agent harness 最小内核 可扩展 终端原生
把智能体，
改造成你的样子
Pi 是一个最小、可扩展的智能体外壳。它跑在你的终端里：读文件、跑命令、改代码、把多步骤任务做完—— 而它该怎么工作，由你决定。
Pi 的自我描述：A minimal, extensible agent harness
that you can make your own.
最小、可扩展、可以变成你自己的智能体外壳。
- 形态
- 终端 TUI 为主，另有 4 种调用界面
- 内置工具
read · bash · edit · writegrep · find · ls · powershell- 会话
- JSONL 树状，可分支 / 压缩 / 导出
- 扩展
- 扩展 · 技能 · 提示模板 · 主题 → 包
- 模型
- 订阅 / 密钥 / 本地 / 兼容端点 / MCP
- 许可
- MIT · Node.js ≥ 22.19
›把 @meeting-notes.md 里的待办拆出来，存成 action-items.md
↑ 一次完整的 turn（示意）：读文件 → 搜索 → 写入 → 汇报。每一步都看得见，也记进会话。工具不做沙箱，用进程权限跑——这是 Pi 的边界，它不会瞒着你。
01 / 04
Pi 是谁？
一句话：Pi 是一个跑在终端里的 AI 智能体。你给它一个目标和一个工作目录，它会去看文件、执行命令、修改内容，把一个多步骤任务做完。
它的官方定义写得很克制：A minimal, extensible agent harness that you can make your own. —— 最小、可扩展、可以变成你自己的智能体外壳。harness这个词是关键： Pi 不是引擎本身，而是那个把引擎、工具、上下文和记忆装在一起、好让你驾驶的架构件。
它不是模型。Pi 不生产智能，它负责编排：组装上下文、和模型对话、执行工具调用、把每一步记进会话。 模型是外接的——你可以用订阅、API Key、本地跑着的 GGUF 模型，或者任何 OpenAI / Anthropic / Google 兼容的端点， 也可以自己写一个 Provider 扩展。
能用来干什么？凡是“在一个文件夹里干活”的事几乎都算：写代码、读代码、写文档、查资料、整理数据文件、批量改名、 做一些自己用的小工具。它默认打开的是终端界面，但它同时也是一个可以塞进脚本、塞进别的程序里的命令行工具。
出身也很清楚：earendil-works 维护的开源项目，MIT 许可，npm 包名
@earendil-works/pi-coding-agent，命令行就叫 pi，官网 pi.dev。
本文对应 1.2.0。
▌长什么样
默认全屏终端界面：上面是对话与工具调用记录，中间是输入区，底部状态栏显示当前目录、会话、模型、上下文用量和花费。
▌怎么记事
每个会话是一个 JSONL 文件，事件之间以“树”相连。可以退回去、开分支、压掉旧历史、导出成 HTML 或分享链接。
▌怎么长大
从写一份 AGENTS.md，到装一个社区包；中间有提示模板、技能、扩展、主题、Provider 每一档。需要哪一档用哪一档。
02 / 04
为什么会有 Pi？
因为“聪明的智能体”越来越多，“听话的智能体”越来越少。
过去两年，编码智能体普遍在长大：上下文管理、计划模式、子代理、长期记忆、审批流、沙箱、内置浏览器、 内部知识库……这些功能单看都不坏。问题在于，它们往往连着一整套关于“你该怎么工作”的假设一起打包送来： 先规划再动手、先派子代理再汇总、每一步都要审批。你要么接受这套工作方式，要么想办法绕开它。
Pi 的答案是反过来的：把内核做小，把决定权还给你。用官方 README 的第一句话概括——
Adapt Pi to your workflows,
not the other way around. —— Pi README，第一句
具体做法可以拆成三条底线：
- 内核只做一件事：一个循环。组装上下文 → 请求模型 → 执行工具 → 记录结果 → 需要的话再来一轮。 没有隐藏的阶段，没有魔法状态机。你能看见它每一步在干什么。
- 默认很能干，但不硬编。Pi 明确说它默认不带子代理（sub-agents）和计划模式（plan mode）。 需要什么，就直接让 Pi 自己写出来，或者装一个按你喜欢的方式实现的包。
-
扩展是一等公民，而且能像依赖一样分发。一个 Pi package 就是普通的 npm 包或 git 仓库，
扩展、技能、提示模板、主题可以一起装走，声明写在
settings.json里，一条命令安装。
所以 Pi 想做的不是“最强的智能体”，而是最少替你拿主意的智能体：它把“怎么做”留成接口， 而不是写成规则。这个取向的代价也很直白——开箱时它没有那么多现成花活，需要你（或者让 Pi）花一点时间把工作流接上去。
03 / 04
和其他智能体相比，Pi 有什么不同？
不谈高下，只谈取向。下面每一条，都是“同一件事，Pi 选了另一条路”。
| 维度 | Pi 的选择 | 更常见的做法 |
|---|---|---|
| 功能边界 | 核心刻意克制：子代理、计划模式这类能力默认不做，留给扩展或社区包 | 尽可能内建，开箱即用，但很难拆掉不想要的部分 |
| 定制深度 | 可以写 TypeScript 扩展：注册工具、/ 命令、快捷键、Provider、事件钩子、终端渲染 |
以配置项和提示词为主，遇到缺口只能等上游 |
| 工作流分发 | Pi package 走 npm / git / 本地路径安装，声明进 settings.json |
复制配置文件、手动搬目录、文档里贴一大段提示词 |
| 会话形态 | 一棵树：可退回旧节点开新分支，放弃的分支不删；/fork、/clone、/compact |
线性历史，想换个思路通常只能重开一个对话，前文全丢 |
| 调用方式 | 五种界面共用一个内核：交互式 TUI、print、JSON 事件流、RPC、TypeScript SDK | 以交互式 CLI 为主，自动化要另找一条不太一样的路子 |
| 非 LLM 模型 | codemode 里能直接跑分类器与图像模型，和工具调用放在同一处脚本里 |
少见，通常只接聊天模型 |
| 模型接入 | 订阅、API Key、本地 GGUF（llama.cpp router）、兼容端点、自定义 Provider，都在同一处切 | 取决于产品形态，本地模型往往要另开一条路 |
| 终端皮肤 | 主题跟随终端的前景/背景与 16 色，并按最小对比度重排色调；导出 HTML 用同一套颜色 | 固定配色，不跟随终端，也不保证对比度 |
| 安全模型 | project trust：先问你信不信这个目录，再加载项目资源；工具不做沙箱，用进程权限跑——这条写在文档里 | 有的默认沙箱但限制多，有的默认全权却不提示，边界常常含糊 |
上面是轮廓，下面这几处是 Pi 真正花心思的地方，也是最容易让人“用上就回不去”的部分。
会话是一棵树
/compact 插入一条摘要，后续请求用摘要代替老消息——
原始条目一个都不删。做完用 /export 导出成自包含 HTML，或者用 /share 生成查看链接
（配置了 Radius 认证时是组织内可见的 artifact，否则走私有 GitHub gist）。
五种界面，同一个内核
很多人把“终端里的智能体”和“能被程序调用的智能体”当成两个东西，在 Pi 这里它们是同一个东西的五个入口。 底下跑的是同一套 agent 与 session 机制，所以你在终端里攒下的一切——工具、技能、包、会话——在自动化里同样成立。
git diff | pi -p "review this"。prompt() 返回即跑完。同一套 agent 与 session 机制 · 同一份配置 · 同一批工具
扩展有阶梯，别一上来就写代码
Pi 的定制能力是分层的，而且官方建议：从能满足需求的最小机制开始。多数“我得写个扩展”的冲动，
一份 AGENTS.md 或者一个技能就够了；真需要可执行行为时，再往下一档走。
$ pi install npm:@your/pi-tools@1.0.0 · $ pi install git:github.com/you/pi-tools@v1 · $ pi list
codemode：让模型写脚本，而不是一条条点工具
codemode 是 Pi 里最有意思的一件工具：模型不再一条一条地调用工具，而是写一段 JavaScript，
在 QuickJS 沙箱里调用别的工具，还可以顺带跑分类器和图像模型。
只有脚本的输出会进入模型上下文——所以“读 200 个文件、只汇报 3 处不同”这种事，第一次变得便宜。
store() / load() 在多次调用之间记住小状态。默认没开，
在 settings.json 里加 "defaultTools": ["+codemode"]，或临时 pi --tools +codemode。
▌模型和凭证都归你
/login 接订阅或存 API Key，/model 选模型，/thinking 调推理强度。
模型目录可以从 pi.dev 在线覆盖，缓存下来的离网也能用。
本地 GGUF 走内置的 llama.cpp router；OpenAI / Anthropic / Google 兼容端点写进
models.json；协议特殊就直接写一个 Provider 扩展。甚至能按思考级别配置不同的采样参数。
▌MCP 与终端主题
MCP 服务器支持 stdio 和 streamable HTTP，pi mcp add 一条命令接入，用户级放
~/.pi/agent/mcp.json，项目级放 .pi/mcp.json。工具不一定要全部声明给模型，
可以让它按需搜索加载，别把上下文塞满工具清单。
主题内置 system / dark / light。system 会真的去问终端要前景色、
背景色和 16 个 ANSI 色，再按最小对比度重新摆放色调——正文字对背景至少 4.5:1；你把终端切成浅色，它会重建。
▌安全边界，写在前面
Pi 的工具和扩展以 Pi 进程的操作系统权限运行。project trust 只决定加不加载项目资源，它不是沙箱。 处理来路不明的文件、仓库、扩展，或者要无人值守地跑，请放进容器或其他沙箱里。 文档把这条单列成一节，而不是塞在免责声明里——这种坦白本身也是它设计取向的一部分。
04 / 04
怎么用 Pi：五步，到第一个任务
不需要读完文档。装好、接上模型、给它一件事，剩下的它会自己告诉你还缺什么。
第一步 · 装
$ curl -fsSL https://pi.dev/install.sh | sh
PS> powershell -c "irm https://pi.dev/install.ps1 | iex"
# npm（不锁定传递依赖，需要 Node.js ≥ 22.19） $ npm install -g --ignore-scripts @earendil-works/pi-coding-agent # Nix（从源码构建） $ nix profile add github:earendil-works/pi/stable # 验证与更新 $ pi --version $ pi update
安装脚本会把依赖版本钉死；npm 的安装方式不会。卸载不会动 ~/.pi/agent/ 里的配置、凭证、会话和已装包。
第二步 · 在工作目录里启动
$ cd ~/projects/notes $ pi
工作目录不是可选项，它是 Pi 的坐标系：它决定 Pi 能看到哪些文件、读哪些项目配置、把会话归到哪一组。 如果这个目录里有它不认识的配置，它会先问你要不要信任——这是加载项目资源前的唯一一道门。
第三步 · 接上模型
/login # 选一个服务商：订阅或 API Key /model # 选模型（也可以按 Ctrl+L） /thinking # 调推理强度（也可以按 Shift+Tab 循环）
第四步 · 派活
三条真实可用的开场白，替换成就地取材的版本：
› 总结 @meeting-notes.md，把待办写进 action-items.md。 › 讲清楚这个仓库的结构，以及怎么跑它的检查。 › 对比 @previous.csv 和 @current.csv，总结重要变化。
@引用文件
输入 @ 搜索并把文件（或图片）挂进提示词，不用敲完整路径。Tab 补全路径，拖进去或粘贴图片也行。
!顺手跑命令
!git status 跑一条终端命令并把输出带进对话；!! 则跑但不把输出给模型。
⌥边跑边说
Enter 发消息，会在当前响应和工具调用结束后引导下一步；Alt+Enter 追加后续任务；Esc 中止。
第五步 · 收工、续命、分支
$ pi --continue # 回到这个目录最近一个会话 $ pi --resume # 打开会话选择器 /tree /fork /clone # 会话内换分支、分家、复制现状 /compact # 压缩历史：插一条摘要，原条目保留 /export # 导出 HTML 或 JSONL /share # 生成查看链接（公开前先自查内容）
顺手记住这几个键
在 Pi 里运行 /hotkeys 看当前版本实际生效的按键；Windows Terminal 会占用部分 Alt 快捷键，另有替代键。
命令速查
# 跑一次就退出（脚本 / CI） $ pi --print "总结这个仓库" $ git diff | pi --print "review 这段改动" # 给程序消费 $ pi --mode json "检查这个仓库" > events.jsonl $ pi --mode rpc # 模型与工具 $ pi --model sonnet:high $ pi --tools read,grep,find,ls --print "评审这个项目" $ pi --tools +codemode $ pi --list-models # 资源与包 $ pi --extension ./review.ts $ pi install npm:@example/pi-tools@1.0.0 $ pi list $ pi remove npm:@example/pi-tools # 会话与 MCP $ pi --export session.jsonl out.html $ pi mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem .
第一件该改的事
用顺手之后，花十分钟把工作流接上去——这才是 Pi 和别的东西真正拉开距离的地方。 照着“最小的那一档”挑就行：
| 你想要的 | 就用这个 | 放哪 |
|---|---|---|
| 这个文件夹里永远遵守的规矩 | AGENTS.md | 项目根目录 或 ~/.pi/agent/ |
| 天天重复打的提示词 | prompt template | ~/.pi/agent/prompts/*.md |
| 某类任务的专门知识和脚本 | skill（SKILL.md） | ~/.pi/agent/skills/ · .pi/skills/ |
| 新工具、新命令、事件钩子 | extension（TypeScript） | ~/.pi/agent/extensions/ · .pi/extensions/ |
| 换个终端长相 | theme | ~/.pi/agent/themes/ |
| 团队一起装 | pi package | pi install npm:… / git:… |
改完在 Pi 里跑 /reload 让改动生效；启动时的头部会列出这次加载了哪些指令和资源。
Pi 不替你做决定。
它只保证一件事：那个决定是你的。内核够小，所以你能看懂；接口够多，所以你能改造； 会话是一棵树，所以你随时能回头。剩下的，就是你打算让它在你的文件夹里，替你做点什么。