---
title: "这个开源 Agent 框架的核心设计，可能是目前最「聪明」的取舍"
source: "https://mp.weixin.qq.com/s/5F5kzLNBSzai9E2wl_CWVg"
tags: [pi-agent, event-bus, framework-design]
created: 2026-05-20
sha256: 712357a8d808ffbc6bbe10d21f12096cb238931ccddb41a9d930739834138241
---
---
# 这个开源 Agent 框架的核心设计，可能是目前最「聪明」的取舍
> 原文：[这个开源 Agent 框架的核心设计，可能是目前最「聪明」的取舍](https://mp.weixin.qq.com/s/5F5kzLNBSzai9E2wl_CWVg)  
> 作者：Felix  
> 来源：Felix的上下文  
> 日期：2026-05-02  
## 核心洞察
**Pi Agent（badlogic/pi-mono）** 的设计哲学：**核心代码保持极简，把所有"可定制性"的维度全部交给扩展系统。**
> 不是简单的"我们支持插件"的声明。扩展系统不是事后打补丁式的钩子集合，而是从架构第一天起就作为一等公民存在的能力注入层。
## 一个极度克制的核心
**核心只有三个抽象**：
| 抽象 | 职责 |
|------|------|
| **Agent** | 负责与大模型对话推理的引擎 |
| **Tools** | Agent 可调用的工具（读文件、执行命令、搜索代码等） |
| **Extensions** | 扩展系统，对外部完全开放 |
**没有**：工作流编排器、状态机图引擎、记忆检索层。
核心只做一件事：**让 Agent 跑起来**。
支撑整个扩展机制的源码只有**五个文件，约两千行代码**。相比之下，仓库里官方提供的扩展示例**超过 70 个**。
## 扩展的两种「能力形态」
### 第一类：监听并介入
扩展可以在 Agent 运行的任意关键节点插入自己的逻辑——
- LLM 收到消息之前**修改**它
- 工具即将执行时**拦截**它
- 工具返回结果之后**改写**它
- 每一轮对话结束时**更新**状态
这些节点覆盖了 Agent 从启动到结束的**完整流程**。框架在 Agent 的"必经之路"上预留了一串检查点，扩展可以选择在任意一个点上参与。
### 第二类：向核心注册新能力
这是 Pi Agent 与大多数"插件机制"最根本的区别。扩展不只是被动地"看"和"拦"，它可以**向核心注入全新的功能**：
- 注册一个自定义工具（LLM 可在推理过程中调用）
- 注册一个终端命令（用户可直接键入执行）
- 注册一组键盘快捷键
- 注册一个新的模型 Provider
- 替换整个输入编辑器、终端 Footer 或 Header
## 具体场景
### 场景一：安全门禁
扩展在工具调用前拦截 `rm -rf` 等危险命令，弹出确认框。在后台无人值守模式下，直接阻止。
**代码量**：极简——只需要做两件事：声明监听工具调用事件 + 判断命令是否危险并返回阻止或放行。没有配置文件，没有项目结构约定，没有对核心代码的任何修改。
### 场景二：计划模式 + 确认后执行
在修改代码之前，让 Agent 进入"只读模式"——只能查看文件、搜索代码、回答问题，但不能做修改。只读模式下完成分析后，生成步骤清单。用户审阅确认后，Agent 才切换到可修改模式，按步骤逐一执行。
涉及的状态切换和阶段管理相当复杂，但**核心逻辑完全包裹在扩展文件中**，不需要改动框架底层一行代码。
### 场景三：待办事项工具
注册一个 `todo` 自定义工具，让 LLM 通过工具调用来添加、勾选或清除任务。
**关键设计**：工具的状态存在对话历史里。如果用户在某个节点"分叉"出新的会话分支，待办事项的状态会自动跟过去，不需要额外处理。**框架的底层机制替扩展作者解决了状态迁移和分支合并问题。**
## 和别的框架对比
| 类型 | 特点 | 局限性 |
|------|------|--------|
| **配置文件驱动** | 上手简单，预设几个位置留参数入口 | 灵活性天花板低 |
| **继承体系驱动** | 类型安全、IDE 友好 | 要求深入理解框架内部结构和继承链 |
| **Pi Agent：事件总线 + 能力注册** | 不要求继承任何类，不需要理解继承关系；扩展只是普通 TypeScript 函数 | — |
**关键差异**：Pi Agent 的扩展既是**观察者**也是**提供者**。大多数框架的"插件"只能在既有流程上增加行为；Pi Agent 的扩展可以**改变流程本身**。
## 适合谁 / 可能不适合谁
**特别适合**：
- 需要大量原型验证、频繁调整 Agent 行为的开发团队
- 希望从干净、不臃肿的代码库开始学习 Agent 原理的技术爱好者
- 需要在标准 Agent 行为之上构建高度定制化工作流的场景
- 评估"既能快速上手、又能深度改造"的 Agent 技术底座
**可能不适合**：
- 完全不具备 TypeScript/JavaScript 基础
- 追求开箱即用、零配置的即用型产品体验
- 需要企业级多租户、权限管理和审计日志的场景
---
## 来源
- Felix，"这个开源 Agent 框架的核心设计，可能是目前最「聪明」的取舍"，Felix的上下文，2026-05-02
- badlogic/pi-mono GitHub 仓库：https://github.com/badlogic/pi-mono