极简 Agent 架构
创建时间： 2026-06-09
来源： [[sources/How Pi Works Agent Architecture, Tools, TUI, and Skills.md]]
相关： Harness-Engineering、Claude-Code-Extension-Layer、Managed-Agents、Agent-First-Repository-Design、Agent-Memory-Platform、Agent-Native-Infrastructure、Software-3.0、Agent-Paradigm-Shift、Vibe-Coding-to-Agentic-Engineering、OpenClaw、Prompt-Engineering、Agent-Readiness
概述
极简 Agent 架构是一种设计哲学：将编码智能体的核心保持得足够小，使其可被完整理解，同时通过清晰定义的扩展点让能力按需增长。Pi 是这一哲学的优秀实践案例——它是一个极简的终端编码 agent，但其架构包含了现代 agent 系统的全部关键组件。
这种架构的价值在于教育性与可维护性的统一。核心循环足够简单，可以被一次性理解；扩展机制足够清晰，不会让功能堆砌变成维护噩梦。对于想要设计自己的 agent 的人来说，这是最值得优先研究的参考架构。
两层分离
Pi 将系统分为两个不可混淆的层次：
| 层次 | 职责 | 设计意图 |
|---|---|---|
| Agent Core | 运行 agentic 循环：初始化上下文、调用模型、解析响应、执行工具、迭代直到完成 | 与 UI 解耦，可被程序化调用或 SDK 集成 |
| Pi Interactive | 终端 UI 和用户工作流：聊天输入、会话管理、压缩、技能、命令 | 专注用户体验，不侵入核心逻辑 |
这一分离对应 Managed-Agents 中”大脑与手解耦”的虚拟化思想——只是 Pi 在本地终端环境中做了轻量实现。核心层不感知 TUI 的存在，TUI 也不干预循环的执行逻辑。
核心 Agent 循环
所有交互遵循同一模式：
- 初始化上下文
- 将当前状态发送给模型
- 接收最终回答或工具调用请求
- 执行工具调用
- 将结果追加回对话
- 重复直到模型终止
这个循环本身 trivial。真正重要的设计问题是：什么被放入上下文，以及工具结果如何被反馈。Pi 的提示系统回答了前者，工具 schema 回答了后者。
这一循环是 Software-3.0 中”神经网络作为宿主进程”的具体实现：模型负责决策（宿主），工具负责执行（外设调用），结果返回驱动下一轮决策。
分层提示系统
Pi 的上下文不是单一系统提示，而是五层叠加：
- 基础代理行为 — 最小化的默认系统提示
- 全局用户/环境指令 — 跨项目的行为约定
- 项目特定指令 — 当前代码库的约定（如使用
uv、特定发布流程） - 技能/工作流指令 — 当前任务类型的可复用流程
- 当前用户请求 — 本次交互的具体目标
分层的设计让同一个 agent 核心能在不同项目中表现出合适的行为，而不需要修改全局实现。这与 Claude-Code-Extension-Layer 中 CLAUDE.md → Skills → Plugins 的层级扩展，以及 Prompt-Engineering 中”极致清晰 + 双向沟通”的方法论完全一致。
工具系统
工具是模型与环境的桥梁。模型本身只能生成文本，无法直接读文件、执行命令或编辑代码。Pi 将这些能力暴露为结构化工具：模型需要知道每个工具的用途、输入 schema 和预期输出。
典型工具包括：读文件、执行 shell 命令、编辑文件、写新文件、搜索仓库。
工具的设计要点不在于功能多，而在于schema 的精确性。模糊的 tool description 会导致模型误调用，清晰的 schema 则让模型能准确规划多步操作。这是 Harness-Engineering 中”将品味编码为可机械执行的规则”的基础层。
扩展与技能
Extensions
Extensions 让 Pi 在不动核心的前提下增加能力。它可以贡献：额外工具、自定义命令、修改后的提示、项目特定集成、额外工作流行为。
这是”保持核心小，通过扩展点实现可选/可定制功能”的模式。对比 OpenClaw 的丰富内置能力，Pi 选择了相反的极端：核心几乎为空，一切通过扩展注入。
Skills
Skills 是可复用的工作流指令。关键区别：skills 不是给人类阅读的文档，而是给 agent 执行的操作指令。
例如一个视频发布 skill 可以定义：产生基础剪辑 → 生成字幕 → 添加叠加层 → 渲染 → 上传 → 写博客 → 创建社交帖子。agent 每次遇到同类任务时，不需要重新发现这个流程，而是直接遵循 skill 中编码的步骤。
这与 Agent-Native-Infrastructure 中”文档应写给 Agent 而非人”的原则直接呼应，也是 Agent-Memory-Platform 中”procedural memory”（程序性记忆）的显式实现。
会话与压缩
Sessions
Session 存储对话历史、工具结果和继续任务所需的状态。没有 session，每一轮都会丢失关键信息；有了 session，agent 才能表现得像一个持续性协作者而非无状态的问答机器。
Coding 任务天然是多步的：读文件 → 理解结构 → 编辑 → 运行 → 检查错误 → 迭代修复。Session 让这种多步流程得以延续。
Compaction
长会话最终会遇到上下文限制。Compaction 不是丢弃历史，而是将旧的对话状态压缩为更紧凑的表示：保留用户目标、关键决策、变更过的文件、当前阻塞点、相关命令和结果；移除或压缩不再需要的噪声细节。
这是 Agent-Memory-Platform 中”记忆生命周期管理”（合并、衰减、冲突检测）的简化实现。没有 compaction，有用的会话会迅速膨胀到不可用。
与其他框架的对照
| 维度 | Pi（极简） | Claude Code（生产级） | OpenClaw（功能丰富） |
|---|---|---|---|
| 核心哲学 | 最小可理解核心 + 扩展 | Harness 工程，扩展层体系 | 分层记忆 + 多模型调度 + 群体智能 |
| 扩展机制 | Extensions | CLAUDE.md / Hooks / Skills / Plugins / MCP | 插件化架构 |
| 会话管理 | 本地 Session + Compaction | 多会话、持久化、跨项目 | 分层长期记忆 |
| 适用场景 | 学习、个人项目、快速原型 | 大规模代码库、团队协作 | 复杂多 agent 协作 |
Pi 的价值不在于功能 compete，而在于架构的透明性。如果你想理解 agent 系统是如何工作的，从 Pi 开始；如果你需要在生产中运行，向 Claude Code 和 OpenClaw 的方向演进。
为什么这种架构有效
Pi 的有效性来自一组小而清晰的抽象的组合：
- 核心循环 与模型对话
- 上下文构建器 组装指令和历史
- 工具系统 让模型能作用于世界
- 会话 保持状态连续性
- 扩展 添加可选能力而不膨胀核心
- TUI 包裹核心以提供可用界面
- 压缩与技能 支持长工作流
单独看，每个组件都不复杂。组合在一起，它们构成了一个既有能力又可被理解的编码 agent。这与 Vibe-Coding-to-Agentic-Engineering 中”Vibe Coding 拉高地板，Agentic Engineering 保持质量天花板”的演进路径一致：Pi 是理解 agentic engineering 的最低门槛入口。
参考资料
- 来源：
sources/How Pi Works Agent Architecture, Tools, TUI, and Skills.md - 原始教程：https://alejandro-ao.com/pi-architecture/