这篇写什么

目标是建立一个稳定的全局理解框架：pi-mono 最核心的四层分别负责什么，以及一条“用户发一句话”会如何穿过这些层。

先记住四层

用最短的图记住：

第 4 层：pi-tui
第 3 层：pi-coding-agent
第 2 层：pi-agent-core
第 1 层：pi-ai

换个方向理解：

模型能力
-> agent 运行时
-> coding 产品
-> terminal 界面

一句话总结

pi-mono 的核心，是把大模型能力一步步落成一个能在终端里工作的编程代理：

统一模型调用
-> 让模型调用工具并循环工作
-> 做成面向编程场景的产品
-> 提供终端交互体验

第 1 层：packages/ai（pi-ai）

这一层的职责可以概括为：把不同 provider 的大模型统一成一套可调用接口。

它主要收敛这些差异：

• 请求格式差异
• 消息格式差异
• tool calling 差异
• 流式输出差异
• token 与 cost 统计差异

你可以把它理解成：模型适配层 / LLM 抽象层。

第 2 层：packages/agent（pi-agent-core）

这一层解决的是：让“调用模型一次”变成“让模型持续工作”。

只有 pi-ai 时，系统更像：

用户提问
-> 调一次模型
-> 返回结果

但 agent 的主流程是：

用户提任务
-> 模型回答或调用工具
-> 系统执行工具
-> 把工具结果塞回上下文
-> 再调用模型
-> 重复直到任务结束

你可以把它理解成：Agent 运行时 / Agent 引擎。

它负责：

• 管理 agent 状态与消息历史
• 驱动多轮调用（loop）
• 执行工具并回灌结果
• 把过程暴露成 agent 级事件流

第 3 层：packages/coding-agent

这是用户真正接触到的“产品层”。

它把前两层装配成一个面向代码仓库工作的 agent，并提供默认工具集，例如：

• read
• write
• edit
• bash

你可以把它理解成：面向编程场景的 agent 产品层。

第 4 层：packages/tui

这是终端 UI 框架，负责交互体验（输入、渲染、选择器、弹层等）。

它不决定 agent 如何思考和执行，但决定用户体验是否顺畅。

四层之间的依赖关系

pi-coding-agent 使用 pi-agent-core
pi-agent-core 使用 pi-ai
pi-coding-agent 的界面由 pi-tui 支撑

一条完整执行链路（最重要的主线）

假设用户输入：

帮我检查这个项目的 README 并总结

系统内部大致会这样运行：

1. pi-coding-agent 组织当前 session、上下文和可用工具。
2. pi-agent-core 启动一轮执行，决定调用模型。
3. pi-ai 将统一上下文转换为目标 provider 请求并发起调用。
4. 模型返回结果，若需要外部信息，会发起 read 等工具调用。
5. pi-agent-core 执行工具，拿到结果。
6. pi-agent-core 把工具结果作为 toolResult 回灌到上下文。
7. pi-ai 再次调用模型，让模型基于结果继续生成。
8. pi-coding-agent 把过程与最终结果组织给用户。
9. pi-tui 把消息/状态渲染到终端。

建议阅读顺序

如果你接下来要继续看源码，推荐按层推进：

1. packages/ai
2. packages/agent
3. packages/coding-agent
4. packages/tui