AI-Agent

14.1 项目完整回顾

从零开始的旅程

本项目展示了如何从零开始，逐步构建一个功能完整的 AI Agent。通过 11 个渐进式步骤（Step 0-10），我们学习了 AI Agent 的核心概念和实现细节。

演进历程

Phase 1: 基础能力 (Step 0-3)

1
2
3
4
5
6
7
Step 0: 基础 LLM 交互
   ↓
Step 1: 对话历史
   ↓
Step 2: 工具系统
   ↓
Step 3: 流式输出

核心成果：

  • ✅ LLM API 集成
  • ✅ 多轮对话支持
  • ✅ Function Calling 能力
  • ✅ 实时响应输出

关键学习点：

  • OpenAI SDK 的使用
  • 消息历史管理
  • 工具调用循环
  • SSE 流式响应

Phase 2: 配置与持久化 (Step 4-5)

1
2
3
Step 4: 配置文件
   ↓
Step 5: 会话持久化

核心成果：

  • ✅ 灵活的配置系统
  • ✅ 会话保存和加载
  • ✅ 多会话管理

关键学习点：

  • 配置优先级管理
  • JSON 文件存储
  • UUID 唯一标识
  • 索引优化

Phase 3: 扩展能力 (Step 6-8)

1
2
3
4
5
Step 6: 技能系统
   ↓
Step 7: 服务化架构
   ↓
Step 8: Web 客户端

核心成果：

  • ✅ 动态技能加载
  • ✅ WebSocket 服务器
  • ✅ 浏览器 UI

关键学习点：

  • YAML Frontmatter 解析
  • WebSocket 通信协议
  • 客户端-服务器分离
  • HTTP 静态文件服务

Phase 4: 高级特性 (Step 9-10)

1
2
3
Step 9: 多模态支持
   ↓
Step 10: 联网搜索

核心成果：

  • ✅ 图像识别能力
  • ✅ 实时搜索功能

关键学习点：

  • 视觉模型集成
  • Base64 图像传输
  • Tavily API 集成
  • 结果缓存机制

功能演进图

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
┌─────────────────────────────────┐
│        Step 10: 完整 Agent       │
│  ┌─────────────────────────────┐ │
│  │ Web Search 🔍            │ │
│  │ Multimodal 🖼️             │ │
│  │ Web UI 🌐                 │ │
│  │ Service 🖥️               │ │
│  │ Skills 📚                 │ │
│  │ Session 💾                │ │
│  │ Config ⚙️                 │ │
│  │ Tools 🛠️                 │ │
│  │ Streaming 🌊              │ │
│  │ Memory 📝                 │ │
│  └─────────────────────────────┘ │
└─────────────────────────────────┘

技术栈总览

核心技术

类别 技术 用途
语言 TypeScript 5.3+ 类型安全开发
运行时 Node.js 20+ JavaScript 执行环境
LLM OpenAI SDK / DeepSeek API 大语言模型调用
通信 WebSocket (ws) 实时双向通信
搜索 @tavily/core 互联网搜索
协议 MCP SDK 外部服务集成

开发工具

工具 用途
tsx 开发模式执行
tsc 生产构建
dotenv 环境变量管理
yaml YAML 解析
uuid 唯一标识生成
ws WebSocket 支持

架构演进对比

Step 架构模式 通信方式 客户端 并发
Step 0-6 单体应用 函数调用 CLI ❌
Step 7 客户端-服务器 WebSocket CLI ✅
Step 8 客户端-服务器 WebSocket + HTTP CLI + Web ✅
Step 9-10 客户端-服务器 WebSocket + HTTP CLI + Web ✅

代码组织

模块化设计

每个步骤都是独立的，可以单独运行和开发：

1
2
3
4
5
6
7
8
9
10
steps/
├── step0/
│   ├── src/
│   ├── package.json
│   └── tsconfig.json
├── step1/
│   ├── src/
│   ├── package.json
│   └── tsconfig.json
...

优势：

  • 清晰的学习路径
  • 每步可独立测试
  • 代码简洁易懂

代码复用策略

虽然各步骤独立，但代码模式被复制和改进：

1
2
3
4
5
6
7
Step N → Step N+1
   ↓
复制代码
   ↓
添加新功能
   ↓
改进架构

学习要点总结

1. LLM 集成

  • OpenAI SDK 使用：理解 chat completions API
  • 流式响应：处理实时输出
  • Function Calling：工具调用机制
  • 视觉模型：多模态内容处理

2. 工具系统

  • 工具定义：清晰的接口设计
  • 工具注册：集中式管理
  • 插件架构：可扩展设计
  • 参数验证：类型安全

3. 会话管理

  • 存储方案：JSON 文件存储
  • 序列化：数据持久化
  • 生命周期：创建、加载、删除
  • 索引优化：快速查找

4. 技能系统

  • 动态加载：运行时发现
  • Frontmatter：YAML 元数据
  • Prompt 构建：系统提示词生成
  • 分类组织：技能分类

5. 服务化架构

  • WebSocket：实时通信
  • 协议设计：消息格式定义
  • 并发管理：多连接支持
  • 状态隔离：独立会话

6. 多模态支持

  • 类型系统：多模态消息定义
  • Base64 传输：图像编码
  • 视觉模型：自动切换
  • UI 集成：上传和预览

7. 联网搜索

  • API 集成：Tavily SDK
  • 结果缓存：性能优化
  • 参数调优：搜索深度、时间范围
  • 错误处理：优雅降级

8. MCP 集成

  • 协议理解：MCP 标准化
  • 服务器连接：Stdio 传输
  • 工具适配：接口转换
  • 命名空间：避免冲突

项目特色

1. 教育价值

  • 渐进式学习：每步建立在前一步基础上
  • 完整代码：可运行的实现
  • 详细文档：配套教程

2. 工程实践

  • 类型安全：全面使用 TypeScript
  • 错误处理：完善的异常处理
  • 配置管理：灵活的配置系统
  • 测试支持：可测试的架构

3. 扩展性

  • 插件系统：易于添加工具
  • 技能系统：动态扩展知识
  • MCP 协议：标准化集成
  • API 友好：清晰的接口

代码质量

遵循的最佳实践

  1. 单一职责：每个模块职责明确
  2. 依赖注入：松耦合设计
  3. 错误处理：完善的异常处理
  4. 类型安全：全面的类型定义
  5. 配置驱动：行为可配置

代码统计

指标 值
总步骤数 11 (0-10)
代码文件数 ~200+
代码行数 ~10,000+
文档章节数 50+
支持的工具数 5+

小结

本项目通过 11 个渐进式步骤，完整展示了 AI Agent 的构建过程：

  • 从简单的 LLM 对话开始
  • 逐步添加工具、技能、服务、UI
  • 最终实现一个功能完整的 AI Agent

每个步骤都是可独立运行的，代码清晰易懂，文档详细完整。这个项目不仅是学习材料，也是实际可用的 AI Agent 框架。

导航

上一篇： 13.4 常用 MCP 服务器

下一篇： 14.2 所有功能特性汇总