#前置知识与学习路径

本系列文档面向会写一点代码、但不一定了解 Agent 的读者。你不需要先学会所有终端术语，也不需要把整个仓库读完。先理解一个小 Agent，再在遇到问题时补 TypeScript、异步和终端知识，会更容易坚持下去。

最重要的前置知识只有三个：

1. 能读懂基本的 TypeScript/JavaScript；
2. 知道 async/await 大概在做什么；
3. 愿意在本地运行代码，并观察一次输入是怎样流动的。

其余概念会在文章中边用边解释。

#前置技能矩阵

不需要的前置：React/Vue/Web 框架、数据库、Docker。本项目是纯 Node.js 终端应用。

#读源码时只需要先记住的几个词

当前 Pi 的 LLM 层由两层组成。先理解 pi-ai 的通用能力，再理解 coding-agent 如何用 ModelRuntime 把它们组合起来：

#仓库规模（v0.80.10）

好消息：你不需要读完所有代码。先沿着运行时边界阅读，核心逻辑会自然收敛到几组文件：

• packages/agent/src/agent-loop.ts ~750 行
• packages/coding-agent/src/core/agent-session.ts 约 1500+ 行
• packages/ai/src/models.ts 是 Models 运行时的核心
• packages/tui/src/tui.ts 是 TUI 差分渲染的核心

其余大量文件是：

• 按 Provider 生成的模型目录（packages/ai/src/providers/*.models.ts）
• 各 Provider 的 API 实现（packages/ai/src/api/*.ts）
• 工具实现与渲染辅助
• 测试与示例扩展

#阅读顺序（推荐）

#第一周：建立全景图

Day 1-2  → 本文档（前置知识 + 学习路径）
Day 3-4  → 环境搭建与调试（实际运行代码，打断点）
Day 5-7  → 从终端到 TUI（理解 CLI 到界面的完整流程）

目标：能回答 "我在终端输入 pi hello，发生了什么？"

#第二周：深入 Agent Loop

Day 8-10 → 从输入到 LLM 循环（核心业务逻辑）
Day 11-12 → pi-ai Models、Provider 与 coding-agent ModelRuntime
Day 13-14 → 项目信任与认证体系

目标：能回答 "LLM 如何调用工具、循环处理、最终给出答案？认证和模型解析怎么发生？"

#第三周及以后：架构与设计

持续学习 → 核心架构与设计哲学
           → 上下文压缩与会话分支
           → TUI 实现细节（按需）
           → 扩展系统（按需）

目标：能独立编写 Extension、自定义 Tool、自定义 Provider、修改 TUI 行为。

#不同背景的读者

#如果你是前端开发者

你最需要补的课：

1. Node.js Stream API — TUI 和 LLM 通信都基于流
2. 终端概念 — raw mode、ANSI 转义、pty
3. Agent 模式 — 思考 "LLM + 工具 + 循环" 而非 "请求 → 响应"

你的优势：理解组件化思维（TUI 的 Component 接口与 React 组件概念类似）。

#如果你是后端开发者

你最需要补的课：

1. LLM API — streaming、tool calling、reasoning 的概念
2. 终端 UI — 不同于 Web UI 的渲染模型
3. TypeScript 类型系统 — 项目重度使用泛型和条件类型

你的优势：理解事件循环、异步编程、API 抽象。

#如果你是 Python/非 TS 开发者

建议先花 1-2 天学习 TypeScript 基础：

• 类型注解、接口、泛型
• async/await 语法
• ES Module 导入导出

Pi 的代码风格是显式类型、尽量避免 any、纯 async/await，对 Python 开发者来说相当易读。

#调试工具准备

不要在浏览器中读代码。这个项目需要本地调试才能理解数据流。GitHub 的代码浏览无法追踪运行时行为。

#预期学习时间

#下一步

→ 环境搭建与调试