# 第六阶段：Pods 与总结

> 对应源文件：`packages/pods/src/`

## 一、Pods -- 远程沙箱管理

`pods` 是一个独立的 CLI 工具，用于管理远程 Linux 开发环境（"pods"）。它让 pi agent 能够在隔离的容器中安全执行代码。

### 架构

```
packages/pods/src/
├── cli.ts             # CLI 入口 + 子命令分发
├── commands/          # 子命令实现
│   ├── create.ts      # 创建新 pod
│   ├── list.ts        # 列出所有 pods
│   ├── destroy.ts     # 销毁 pod
│   ├── ssh.ts         # SSH 连接到 pod
│   └── ...
├── config.ts          # 配置管理
├── model-configs.ts   # 预定义的 pod 规格
├── models.json        # pod 型号定义
├── ssh.ts             # SSH 连接工具
└── types.ts           # 类型定义
```

### 核心功能

| 命令 | 说明 |
|------|------|
| `pods create` | 创建一个新的远程 pod |
| `pods list` | 列出所有活跃的 pods |
| `pods ssh <name>` | SSH 连接到指定 pod |
| `pods destroy <name>` | 销毁指定 pod |
| `pods run <name> <command>` | 在 pod 中执行命令 |

### 与 coding-agent 的关系

`pods` 不直接依赖 coding-agent，但提供了 coding-agent 需要的**远程执行基础设施**：

```
coding-agent 的工具（read, bash, write, edit）
  │
  ├── 本地执行（默认）
  │   └── 直接调用 Node.js fs/child_process
  │
  └── 远程执行（pods）
      └── 通过 SSH 在 pod 中执行
```

这是通过前面学到的 `ReadOperations` 和 `BashOperations` 可插拔接口实现的。

---

## 二、项目架构总结

### 依赖关系

```
                          ┌──────────┐
                          │  pi-ai   │  统一 LLM 调用
                          └────┬─────┘
                               │
                    ┌──────────┴──────────┐
                    │   pi-agent-core     │  Agent 循环 + 工具执行
                    └──────────┬──────────┘
                               │
              ┌────────────────┼────────────────┐
              │                │                │
     ┌────────┴───────┐  ┌────┴────┐    ┌──────┴──────┐
     │ pi-coding-agent│  │ pi-tui  │    │  pi-web-ui  │
     │ CLI 编码助手    │  │ 终端 UI  │    │ 浏览器 UI   │
     └────────┬───────┘  └─────────┘    └─────────────┘
              │
     ┌────────┼────────┐
     │        │        │
  ┌──┴──┐ ┌──┴──┐ ┌───┴───┐
  │ mom │ │pods │ │ ...   │
  │Slack│ │远程 │ │ 其他  │
  │ bot │ │沙箱 │ │ 集成  │
  └─────┘ └─────┘ └───────┘
```

### 分层架构

| 层次 | 包 | 职责 | 关注点 |
|------|-----|------|--------|
| **基础设施层** | `ai` | LLM 调用、Provider 管理、模型注册 | 协议适配、流式传输 |
| **运行时层** | `agent` | 工具调用循环、状态管理、事件分发 | 循环控制、消息队列 |
| **产品层** | `coding-agent` | 内置工具、扩展系统、会话管理、压缩 | 功能完整性、可扩展性 |
| **界面层** | `tui` / `web-ui` | 用户交互、渲染、输入处理 | 用户体验、性能 |
| **集成层** | `mom` / `pods` | Slack bot、远程执行环境 | 部署、安全、协作 |

### 核心设计原则

**1. 可插拔接口**

几乎所有 I/O 操作都通过接口抽象：
- `ReadOperations` → 本地/SSH/内存文件系统
- `BashOperations` → 本地/Docker/SSH shell
- `streamFn` → 直接调用/代理调用/mock
- Provider Registry → 懒加载任意 LLM provider

**2. 事件驱动**

从 `ai` 包的 `AssistantMessageEvent` 到 `agent` 包的 `AgentEvent` 到 `coding-agent` 的扩展事件，整个系统通过事件流串联。每一层在消费上层事件的同时，发出自己层级的事件。

**3. 最小核心**

核心代码量极小：
- `ai` 包核心类型定义 < 500 行
- `agent` 包核心循环 < 700 行
- `agent` 包 Agent 类 < 550 行

大部分功能通过扩展系统添加。

**4. 树形会话**

不是简单的线性聊天记录，而是完整的树形结构，支持分支、导航、fork，配合增量压缩实现无限长对话。

---

## 三、学习路径回顾

```
阶段 1: ai 包
├── 统一类型系统（Message, Context, Tool, Model）
├── 流式传输协议（AssistantMessageEvent）
├── Provider 架构（Registry + 懒加载）
└── Provider 内部（消息转换 + SSE 解析）

阶段 2: agent 包
├── 扩展的类型（AgentMessage, AgentTool, AgentEvent）
├── 双层循环（tool-call loop + follow-up loop）
├── 消息转换（convertToLlm, transformContext）
└── Agent 类（状态管理 + 事件订阅 + 消息队列）

阶段 3: coding-agent 包
├── 内置工具（read, write, edit, bash, grep, find, ls）
├── 扩展系统（工具 + 命令 + 快捷键 + UI + 事件）
├── 会话管理（JSONL 树形结构 + 分支 + 导航）
└── 上下文压缩（token 估算 + 切割点 + LLM 摘要）

阶段 4: TUI
├── Component 接口（render → string[]）
├── 差异化渲染
├── Overlay 系统
└── 键盘输入处理

阶段 5: Web UI + MoM
├── Lit Web Components
├── Artifacts 沙箱预览
├── Slack bot 集成
└── 事件驱动自动化

阶段 6: Pods + 总结
├── 远程沙箱管理
└── 整体架构复盘
```

---

## 下一步建议

理论学习完成后，建议通过以下实践加深理解：

1. **写一个扩展**：在 `.pi/extensions/` 下创建一个简单的扩展，注册一个自定义工具
2. **跟踪一次完整请求**：在 `agent-loop.ts` 加 log，观察一次 `prompt()` 调用的完整事件序列
3. **阅读测试代码**：`packages/agent/test/` 和 `packages/coding-agent/test/` 有大量测试用例，展示了各种边界情况
4. **自定义 Provider**：参考 `packages/ai/src/providers/` 添加一个新的 LLM provider
5. **阅读 SDK 文档**：`packages/coding-agent/docs/sdk.md` 描述了如何把 pi 嵌入到你自己的应用中