pi 架构总览
源码版本v0.73.1
badlogic/pi-mono 是一个 TypeScript monorepo,用五个 npm 包搭出一整条「统一 LLM API → 通用 Agent → 编码助手 → 终端/网页 UI」的栈。本页给一张全景图,后续每页拆一层。
五个包
| 包 | npm 名 | 角色 |
|---|---|---|
ai | @mariozechner/pi-ai | 统一 LLM API,9 个内置 provider,自动模型发现 |
agent | @mariozechner/pi-agent-core | 通用 Agent,双层 while 循环 + 工具执行 |
coding-agent | @mariozechner/pi-coding-agent | 编码助手 CLI,read/bash/edit/write 工具 + 会话管理 |
tui | @mariozechner/pi-tui | 终端 UI 库,差分渲染 + 同步输出 |
web-ui | @mariozechner/pi-web-ui | 网页聊天组件,Lit Web Components |
源码目录:packages/
分层
每层一句话
- pi-ai:把 9 家 LLM(Anthropic、OpenAI、Google、Bedrock...)统一成
stream/streamSimple两个函数,通过注册表按model.api分发。详见 流式门面 stream。 - pi-agent-core:
Agent类持状态,runLoop外层处理插话/排队、内层处理工具调用,流式 + 工具循环。详见 双层 while 主循环。 - pi-coding-agent:在
Agent外套AgentSession,加工具、系统提示、会话持久化、三种运行模式。详见 AgentSession 编排层。 - pi-tui:差分渲染 + DECSET 2026 同步输出,避免终端闪烁。详见 差分渲染 TUI 类。
- pi-web-ui:Lit 组件拥有自己的
Agent实例,通过createStreamFn包一层 CORS 代理调streamSimple。详见 AgentInterface 会话宿主。
分层动机
为什么不做成一个大包?因为各层消费者不同:网页组件不能依赖 Node 的 fs,终端 UI 不该背网页的 IndexedDB,通用 Agent 不该知道「编码」这件事。分层后,网页可以直接拿 pi-agent-core + pi-ai 自己跑 agent,跳过编码助手的工具集;编码助手 CLI 可以换 UI(tui 或 rpc 模式)而不动编排逻辑。pi-ai 单独成包,是为了让任何项目都能直接用统一 LLM API,不被 agent 概念绑住。
常见误读
- 「pi 是一个 coding agent」:不准确。
pi-coding-agent是上层应用,底层pi-ai和pi-agent-core是通用基础设施,可独立使用。 - 「UI 层只是渲染」:网页和终端 UI 都会参与流式——网页替换
Agent.streamFn注入 CORS 代理,终端订阅事件决定何时重绘。
推荐阅读顺序
先 流式门面 stream 懂 LLM 怎么调,再 双层 while 主循环 看工具循环,接着 AgentSession 编排层 看编码助手怎么装配,最后按兴趣挑 pi-tui 或 pi-web-ui。