blog.dopana

Back

8 min
zh
ai/
cli/
developer tools/
typescript

探索 Pi Agent Harness：可扩展的终端 AI Agent 框架

深入了解 earendil-works 开源的 Pi Agent Harness：模块化架构、多 LLM 提供商支持、树状 Session 管理与 TS 插件扩展体系。

在当今的 AI 编程助手领域，大多数工具都是作为单体“黑盒”（Monolithic Black Box）构建的。开发者被迫适应固定的工作流、预设的 UI 界面和 Plan 模式。如果你想添加自定义工具、修改 Prompt 处理逻辑或对接特定的 Sandbox，通常只能等待厂商更新或编写复杂的封装脚本。

Pi (@earendil-works/pi) 带着明确的理念应运而生：让 AI Agent 适应你的工作流，而不是让你去适应 Agent。

[!NOTE] Pi 是由 earendil-works（由 Mario Zechner / badlogic 主导）开发的开源 AI Agent Harness 项目。Pi 拒绝臃肿的预设功能，而是提供轻量、模块化的底层原语，供开发者自由组合扩展。

1. 通俗易懂的解释（ELI5）#

设想你买了一辆引擎盖被焊死的跑车：你无法更换发动机，无法自定义仪表盘，也无法添加额外的传感器。

Pi Agent Harness 就像是一个模块化赛车底盘：

  • 发动机自由更换：在 Anthropic Claude、OpenAI GPT-4o、Google Gemini、DeepSeek 以及基于 llama.cpp 的本地大模型之间无缝切换。
  • 自定义仪表盘：使用 TypeScript Extensions 编写互动式终端 UI、Q&A 表单或状态栏。
  • 扩展新技能：通过 Skills 和 Prompt Templates 赋予 Agent 特定项目的操作指南。
  • 时光倒流与分支：所有交互记录均保存为树状 Session 文件。如果某种解题思路走不通，你可以随时回到历史中的任意节点开启新分支，而不会丢失之前的对话记录。

2. 4 层模块化架构#

Pi 被拆分为 4 个独立的 npm 包，既可以直接作为终端 CLI 使用，也可以作为 SDK 嵌入到自定义应用中：

┌─────────────────────────────────────────────────────────┐
│        @earendil-works/pi-coding-agent (CLI)             │
├─────────────────────────────────────────────────────────┤
│        @earendil-works/pi-tui (Terminal UI)             │
├─────────────────────────────────────────────────────────┤
│        @earendil-works/pi-agent-core (Agent Engine)     │
├─────────────────────────────────────────────────────────┤
│        @earendil-works/pi-ai (Unified Provider API)    │
└─────────────────────────────────────────────────────────┘
text
软件包作用与功能
@earendil-works/pi-ai统一的多提供商 LLM API 层，封装了 30+ 提供商（Anthropic、OpenAI、Gemini、DeepSeek、Bedrock、llama.cpp 等）。
@earendil-works/pi-agent-core核心 Agent 运行时，管理 Tool 调用（read, write, edit, bash）、消息历史、Agent Loop 及上下文压缩（Compaction）。
@earendil-works/pi-tui高性能终端 UI 库，支持增量/微细渲染（Differential Rendering）。
@earendil-works/pi-coding-agent开箱即用的终端交互式 AI 编程 Agent CLI Harness。

3. Pi 的核心特性与优势#

基于 TypeScript 的自扩展体系#

开箱即用状态下，Pi 为模型提供 4 个基础工具：read、write、edit 和 bash。开发者无需修改 Pi 内部代码即可完成自定义：

  • Skills (/skill:name)：使用 Markdown 或 TypeScript 定义的模块化工作流。
  • Extensions：使用 TypeScript 编写扩展，添加自定义 Tool、修改 TUI 布局或对接外部进程。
  • Prompt Templates：通过 /template-name 快捷展开的 Prompt 模板。
  • Pi Packages：将扩展、Skill 和主题打包，通过 npm 或 git 共享给团队。

树状 Session 管理 (/tree)#

不同于传统的线性 Chat 记录，Pi 的 Session 以 JSONL 树状结构存储（每个节点包含 id 与 parentId）。

在交互模式下输入 /tree，即可直观查看会话分支树，随时跳转到历史节点继续对话，或从过去的问题开启新分支。

[!TIP] 在 /tree 视图中按 Ctrl+O 可以切换过滤模式：显示完整历史、隐藏 Tool 输出、仅显示用户消息或仅显示书签节点。

广泛的 LLM 支持与本地模型#

Pi 同时支持 API Key 与 Subscription 登录：

  • 云端 API：Anthropic Claude, OpenAI, Google Gemini, DeepSeek, Groq, OpenRouter 等。
  • 本地模型：通过 /llama 命令连接 llama.cpp 服务，直接在本地下载并运行 GGUF 模型。

灵活的沙箱隔离 (Containerization)#

Pi 默认使用启动用户的权限运行。针对需要自动化运行或执行不可信代码的场景，Pi 提供了 3 种隔离方案：

  1. Gondolin Micro-VM：主进程留在宿主机，将 bash 工具的执行路由到轻量 Linux 微型虚拟机中。
  2. Plain Docker：在 Docker 容器中整体运行 pi 进程。
  3. OpenShell：通过细粒度安全策略限制权限。

4. 快速上手#

安装#

通过 npm 全局安装：

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

或使用官方一键安装脚本：

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

启动与配置#

配置 API Key 并启动：

Terminal
export ANTHROPIC_API_KEY=sk-ant-...
pi
bash

常用交互命令：

  • /model：选择活跃的模型（或快捷键 Ctrl+L）。
  • /login：配置提供商认证凭据。
  • /tree：打开树状 Session 导航视图。
  • /compact：手动执行上下文压缩。
  • /reload：热重载按键绑定、扩展、Skills 与 Prompt 模板。

5. Pi 与 OpenCode、Claude Code 及 Codex 对比#

特性Pi Agent (@earendil-works/pi)Claude CodeOpenAI CodexOpenCode
设计理念Unopinionated Harness（极简自扩展底层框架）Opinionated Assistant（深度绑定 Claude）Dedicated Assistant（深度绑定 OpenAI）模块化开源 Agent 框架
LLM 提供商30+ 提供商（Anthropic, OpenAI, Gemini, DeepSeek, llama.cpp）仅限 Anthropic 生态仅限 OpenAI 生态多提供商（API Key/OpenRouter）
Session 管理Tree Sessions (/tree)：树状历史，支持原地分支与回退线性对话历史 (Linear history)线性对话历史 (Linear history)标准会话 / 单次会话
可扩展性TypeScript Extensions, Skills, Prompt Templates, Pi Packages有限的 Hooks / Sub-agent基础 Custom Instructions / Tools插件架构与任务调度器
终端 UI高性能微细渲染 TUI (pi-tui)官方终端 UI基础 CLI终端 CLI
集成与 SDK4 种模式：交互式 CLI、Print/JSON、RPC、嵌入式 SDK独立 CLICLI / APICLI / Framework
沙箱隔离Gondolin Micro-VM, Docker, OpenShell宿主机 / Docker 容器宿主机Docker / Local

6. 助力开源 AI 社区#

Pi 鼓励开源开发者通过 badlogic/pi-share-hf 将真实编程 Session 日志分享到 Hugging Face。来自真实真实开发场景的数据将有效推动开源 LLM、Prompt 评估与 Agent 工具链的发展。

参考资料#

Khám phá Pi Agent Harness: AI Coding Agent Mở Rộng

Pi Agent Rust - High Performance AI Coding Assistant