Pi 项目介绍：把 Coding Agent 做成可改造的终端 Harness

这两年 AI Coding 工具越来越像完整产品：内置计划模式、权限弹窗、子代理、MCP、任务列表、后台任务、图形界面。

earendil-works/pi 走的是另一条路：核心保持轻，能力尽量开放给用户自己扩展。

项目地址：https://github.com/earendil-works/pi

官网文档：https://pi.dev/

一句话定位

Pi 是一个可自定义的终端 AI coding agent harness：它提供编码 Agent、工具调用 runtime、统一模型 API、TUI 组件和包机制，让你按自己的工作流改造 Agent，而不是被工具默认形态限制。

如果说很多 Coding Agent 是“开箱即用的产品”，Pi 更像是“可以自己搭积木的 Agent 底座”。

基础信息卡片

字段	内容
项目名	Pi
仓库	https://github.com/earendil-works/pi
官网	https://pi.dev/
License	MIT
技术栈	TypeScript 为主
核心包	`pi-coding-agent`、`pi-agent-core`、`pi-ai`、`pi-tui`
运行形态	交互式 TUI、print/JSON、RPC、SDK
核心场景	终端 Coding Agent、自定义 Agent 工作流、模型/工具/界面扩展

说明：Stars、Forks、版本号和语言占比会持续变化，发布后请以 GitHub 页面实时数据为准。

它解决什么问题

现在很多 Agent 工具的能力越来越强，但也带来一个问题：默认工作流越来越重。

有些人需要内置 plan mode、权限确认、MCP、子代理和图形界面；也有人只想要一个轻量、可脚本化、能嵌进自己终端工作流的 Agent。

Pi 的判断是：

不要把所有功能都塞进核心；
保留足够小的 Agent harness；
把扩展点开放出来，让用户按自己的工作流组合。

这也是它最值得看的地方。Pi 不是单纯再做一个 Claude Code 或 Codex 的替代品，而是在回答另一个问题：Agent 的“底座”应该长什么样，才能被个人和团队长期改造？

核心功能

1. 终端优先的 Coding Agent

Pi 的主要入口是终端 TUI。它支持常见的 AI coding agent 工作流：读取项目上下文、调用工具、修改文件、执行命令、在会话中继续迭代。

官网给出的定位很明确：Pi 是一个 minimal terminal coding harness。重点不是把每个功能都做成固定按钮，而是让你可以把它接进自己的终端习惯里。

2. 多模型、多 provider

Pi 通过 @earendil-works/pi-ai 提供统一的多 provider LLM API。

官网列出的 provider 覆盖 Anthropic、OpenAI、Google、Azure、Bedrock、Mistral、Groq、Cerebras、xAI、Hugging Face、OpenRouter、Ollama 等。实际可用情况取决于你的配置、账号和 API Key。

这对团队有用：你可以把“Agent 工作流”和“模型供应商”拆开，不必因为换模型就换整套工具。

3. 可扩展的 Agent runtime

@earendil-works/pi-agent-core 提供工具调用、状态管理等 Agent runtime 能力。

这意味着 Pi 不只是一个 CLI，也可以作为更底层的 Agent 组件被复用。你可以把它嵌到自己的 Node.js 应用里，或者通过 RPC / JSON event stream 让其它系统调用它。

4. Skills、Prompt Templates、Extensions 和 Packages

Pi 的扩展思路很接近“把上下文工程产品化”：

Skills：按需加载的能力说明和工具约束；
Prompt Templates：可复用的提示词模板；
Extensions：TypeScript 模块，可扩展工具、命令、快捷键、事件和 TUI；
Pi Packages：把 extensions、skills、prompts、themes 打包分享。

这套机制的价值在于：你不必每次都靠一段超长 prompt 控制 Agent，而是把稳定的规则、工具和工作流沉淀成可复用资产。

5. 会话树与可分享历史

Pi 的 session 是树结构，可以回到之前某个节点继续分支，也可以导出 HTML 或分享 session。

这点对调试 Agent 很重要。真实工作流里，Agent 往往会经历尝试、失败、修正、回退。树状历史比线性聊天更适合保留这些决策路径。

一个重要取舍：核心不追求全内置

Pi 官网专门列了“What we didn’t build”：没有内置 MCP、没有内置 sub-agents、没有内置 permission popups、没有内置 plan mode、没有内置 todos、没有内置 background bash。

这不是简单的“缺功能”，而是产品哲学：

核心提供 primitives，复杂功能通过扩展、技能、脚本、tmux 或包来实现。

这个取舍会筛选用户。

如果你想要完整、保守、开箱即用的 Agent 产品，Pi 可能会显得太自由；如果你想控制 Agent 的系统提示词、上下文、命令、UI 和运行方式，Pi 反而更有吸引力。

适合谁 / 不适合谁

适合谁

经常在终端里工作的开发者；
想研究 AI coding agent 底层机制的人；
想把 Agent 接入自己工具链、脚本或产品的人；
对 skills、prompt templates、extensions 有长期沉淀需求的团队；
需要多模型、多 provider 切换，但不想绑定单一平台的人。

不适合谁

只想要零配置、图形化、开箱即用的普通用户；
不愿意理解终端、配置文件和扩展机制的人；
需要企业级权限审计、集中管控、稳定 SLA 的团队；
只追求“马上替我写完代码”，不关心 Agent 工作流可塑性的人。

快速上手

官方文档给出的 npm 安装方式：

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

macOS / Linux 也可以使用安装脚本：

curl -fsSL https://pi.dev/install.sh | sh

然后在项目目录运行：

pi

认证方式可以用 /login，也可以设置模型供应商的 API Key，例如 ANTHROPIC_API_KEY。具体 provider 配置建议以官方文档为准。

我会怎么试用

如果只是“看一眼”，不要一上来就研究所有扩展机制。

更好的试用路径是：

找一个非核心仓库；
用 pi 让它读项目并做一个小改动；
试一次 pi -p "..." 的 print 模式，看它是否适合脚本化；
看 session tree、skills、prompt templates 是否能沉淀你的固定工作流；
再决定要不要研究 extensions 和 packages。

重点不是它第一次生成得多惊艳，而是你能不能把自己的规则放进去，并且长期复用。

优缺点（客观）

优点

核心轻，适合终端重度用户；
扩展点明确，适合做上下文工程和自定义工作流；
多 provider 支持较完整，降低模型绑定；
会话树、导出和分享能力适合复盘 Agent 行为；
MIT License，对二次开发和商业探索友好。

可能的限制

自由度高意味着学习成本也高；
很多高级能力需要通过扩展或外部工具组合实现；
对非终端用户不够友好；
团队级权限、安全、审计能力需要自己补齐；
生态是否成熟，要看后续 packages、extensions 和社区贡献的质量。

可变现方向（若你想做产品化）

团队 Agent Harness 定制：基于 Pi 给研发团队做统一的 coding agent 工作流。
行业 Skills / Packages：为前端、数据分析、DevOps、安全审计等场景做可安装包。
企业私有化 Agent 底座：把模型路由、审计、权限和内部工具接进 Pi runtime。
Agent 工作流咨询：帮团队把 prompt、AGENTS.md、skills、templates 和 CI 验证流程沉淀下来。

结论

Pi 最有价值的地方，不是“它也能写代码”，而是它把 Coding Agent 拆成了更可改造的几层：CLI、runtime、模型 API、TUI、skills、extensions 和 packages。

如果你需要的是一个成熟的一体化产品，Codex、Claude Code、Cursor 这类工具可能更直接。

但如果你在意的是：我的 Agent 能不能按我的工作流长出来，Pi 就很值得研究。

它代表了一种很有意思的方向：Agent 不只是工具本身，也可以是一个可持续演化的开发者工作台底座。