第六阶段：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 + 总结
├── 远程沙箱管理
└── 整体架构复盘

下一步建议

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

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