第 0 课：项目全景图

仓库：Pi —— 一个跑在终端里的 AI 编程助手（开源，MIT 协议）。 核心代码分层干净、体量不大，适合学习"AI Agent 到底怎么运作"。

1. Pi 是什么

在终端里输入 pi，用自然语言对话，例如"帮我把这个 bug 修了"。Pi 的行为：

你: "修复 login.ts 里的空指针 bug"
        │
        ▼
┌──────────────────────────────────────────────┐
│  Pi 把你的话 + 相关文件内容打包，发给大模型      │
│  大模型回复："我要先读一下 login.ts"            │
│  → Pi 替模型执行「读文件」这个动作              │
│  → 把结果再发回给大模型                        │
│  大模型回复："我要把第 42 行改成 xxx"           │
│  → Pi 替模型执行「改文件」                     │
│  → ... 如此循环 ...                           │
│  大模型最终回复："修好了，改动如下…"             │
└──────────────────────────────────────────────┘

关键认知：大模型本身只会"生成文字"，它没有手。 所谓 Agent（智能体），就是一个循环程序：

循环 {
   1. 把对话历史发给大模型
   2. 模型回话
   3. 如果模型说"我要用某个工具"(如读文件/跑命令)
        → 由 Pi 真正去执行，把结果塞回对话历史 → 回到 1
   4. 如果模型直接给出了最终回答 → 结束循环
}

这个循环是整个项目的灵魂，仓库里几乎所有代码都为它服务： 怎么把消息发给模型、界面怎么画、工具怎么定义。

2. 仓库结构：7 个房间

Monorepo（一个仓库装多个独立发布的 npm 包）。核心 4 个包按"底层 → 顶层"排列。

依赖方向：下面的包不认识上面的包（底层不知道谁在用它）。

┌─────────────────────────────────────────────────────┐
│  packages/coding-agent      ← 产品本身（你敲的 pi）    │
│  CLI 入口、配置系统、内置工具(read/bash/edit)、扩展系统 │
└───────┬──────────────────┬──────────────────────────┘
        │                  │
        ▼                  ▼
┌──────────────────┐   ┌──────────────────────────────┐
│ packages/agent   │   │ packages/tui                 │
│ 代理主循环         │   │ 终端界面库：编辑器、滚动、        │
│ (agent-loop.ts,  │   │ 差分渲染(只重画变化的部分)       │
│  只有 5 个文件!)   │   └──────────────────────────────┘
└───────┬──────────┘
        ▼
┌──────────────────┐      外部世界
│ packages/ai      │ ──HTTPS──▶  OpenAI / Anthropic(Claude)
│ 统一多家模型的 API │            / Google(Gemini) ...
└──────────────────┘

配角包：

已核对 package.json 的依赖关系：

• agent 只依赖 ai
• coding-agent 依赖 agent + ai + tui + mcp + codemode
• tui 和 ai 谁都不依赖（纯底层）

3. 一次完整交互的旅程

在 pi 里敲一句话后，消息的旅行路线：

 你敲键盘                终端界面            代理循环              模型 API
    │                  (packages/tui)   (packages/agent)   (packages/ai)
    │  按键事件              │                 │                  │
    ├──────────────────────▶│                 │                  │
    │                 编辑器收到文字            │                  │
    │                 回车→提交 ───────────────▶                  │
    │                                       组装消息列表           │
    │                                       (你说的+历史)          │
    │                                       ├──────────────────▶│ 打包成
    │                                       │                   │ HTTP 请求
    │                                       │                   │ 发给 Claude
    │                                       │                   │ /GPT ...
    │                                       │◀── 流式返回文字 ─────┤ (一个字一个字)
    │                                       │                   │ 或"工具调用"
    │                            ┌── 是文字？→ 交给 TUI 画到屏幕上      │
    │                            │                                   │
    │                            └── 是工具调用？(如 bash "npm test")   │
    │                                  → coding-agent 执行真实命令     │
    │                                  → 结果塞回消息列表 ────────────▶│ 再问模型
    │                                  (循环继续，直到模型给出最终回答)    │

三大主角各司其职：

• packages/tui：只管"怎么画"，不管业务。
• packages/agent：只管"循环和状态"（消息历史存在哪、何时停），不关心具体工具。
• packages/ai：只管"跟几十家模型厂商说同一种普通话"——写一份代码，翻译成 OpenAI/Anthropic/Google 各自的 HTTP 格式。

4. 学习路线