GuaDa AI：功能完备的AI Agent系统，支持MCP、Skills、多平台机器人

开源地址: https://gitee.com/zhendongdong/guada_ai
开源协议: MIT
发布平台: 程序员茄子（chenxutan.com）
标签: AI Agent, ReAct, MCP, Skills, RAG, 多模型, NestJS, Vue 3

引言

GuaDa — 智能 AI 对话平台。

围绕 ReAct Agent 设计，将 LLM 推理与工具调用深度结合，形成多轮自治循环。

集成 RAG 知识库、MCP 协议、Skills 技能框架，支持多种模型提供商。

可作为：

• 企业内部 AI 中台
• 聊天机器人后端
• 个人智能助理

一、项目概览

核心定位

打造一个可用、易用、好用的个人智能助理。

主要功能

二、架构特点

1. 双入口设计

┌─────────────────────────────────────────────┐
│                  用户入口                     │
├─────────────────────────────────────────────┤
│                                             │
│   REST + SSE API          Bot Gateway       │
│   (Web/桌面用户)           (IM平台用户)       │
│                                             │
└─────────────┬─────────────┬─────────────────┘
              │             │
              └──────┬──────┘
                     │
                     ▼
              ┌─────────────┐
              │ Agent Engine │
              └─────────────┘

两个对等入口，最终汇聚到同一个 Agent 引擎。

2. Agent 中心化

所有能力经由 Agent 循环统一调度。

• 知识检索 ✅
• 工具执行 ✅
• 技能调用 ✅

3. 插拔式扩展

Skills 目前支持热插拔，其余正在开发中。

4. 长上下文管理

两级压缩策略：

优先裁剪工具结果 → 语义压缩 → 压缩支持回退

三、技术选型

后端技术栈

前端技术栈

四、架构层次

四层架构

五、项目结构

ai_chat/
├── backend-ts/                    # NestJS 后端
│   ├── prisma/
│   │   └── schema.prisma          # 数据库 Schema
│   ├── src/
│   │   ├── common/                # 基础设施
│   │   │   ├── database/          # Prisma + Repository 层
│   │   │   ├── vector-db/         # 向量数据库抽象 + sqlite-vec 实现
│   │   │   ├── mcp/               # MCP 客户端
│   │   │   └── utils/             # Tokenizer 等工具
│   │   ├── modules/
│   │   │   ├── chat/              # 核心对话模块
│   │   │   │   ├── agent.service.ts         # Agent 循环引擎
│   │   │   │   ├── compression-engine.ts    # 两级压缩引擎
│   │   │   │   ├── conversation-context.ts  # 上下文管理器
│   │   │   │   └── message-store.service.ts # 消息持久化
│   │   │   ├── tools/             # 工具调用系统
│   │   │   │   └── providers/     # 各工具 Provider 实现
│   │   │   ├── skills/            # Skills 技能框架
│   │   │   │   ├── core/          # 核心服务 (发现/加载/注册/调度)
│   │   │   │   ├── integration/   # Skill-Tool 桥接
│   │   │   │   └── execution/     # 脚本执行引擎
│   │   │   ├── knowledge-base/    # 知识库模块 (RAG)
│   │   │   ├── llm-core/          # LLM 适配层
│   │   │   │   └── adapters/      # OpenAI / Gemini 适配器
│   │   │   ├── bot-gateway/       # 多平台机器人网关
│   │   │   ├── auth/              # JWT 认证
│   │   │   ├── models/            # 模型管理
│   │   │   ├── settings/          # 系统设置
│   │   │   └── users/             # 用户管理
│   │   └── main.ts                # 应用入口
│   └── skills/                    # Skills 技能目录
├── frontend/                      # Vue 3 前端
│   ├── src/
│   │   ├── components/
│   │   │   ├── chat/              # 对话界面
│   │   │   ├── knowledge-base/    # 知识库管理
│   │   │   ├── plugins/           # 工具/MCP/Skills 管理
│   │   │   ├── bot/               # 机器人管理
│   │   │   └── setting/           # 系统设置
│   │   ├── composables/           # 组合式函数
│   │   ├── stores/                # Pinia 状态管理
│   │   └── services/              # API 服务层
│   └── package.json
└── LICENSE

六、核心模块详解

1. Agent Engine

agent.service.ts - Agent 循环引擎

用户输入 → LLM 推理 → 工具调用 → 结果反馈 → LLM 推理 → ... → 最终回复

ReAct 循环：

• Reasoning：LLM 推理下一步行动
• Acting：执行工具/技能调用
• Observation：获取执行结果
• 循环：直到任务完成

2. 两级压缩引擎

compression-engine.ts

第一级：裁剪工具结果（优先）
    ↓
第二级：语义压缩
    ↓
支持回退

3. Skills 技能框架

热插拔支持：无需重启服务即可添加新技能。

4. 知识库 RAG

knowledge-base/ 模块

• 向量检索：sqlite-vec
• 全文搜索：FTS5
• 中文分词：jieba

5. 多平台机器人网关

bot-gateway/ 模块

支持平台：

• QQ ✅
• 飞书 ✅
• 企业微信 ✅
• 更多平台扩展中

七、快速开始

环境要求

• Node.js ≥ 18.x（推荐 20.x LTS）
• npm ≥ 9.x

启动后端

cd backend-ts
npm install
npx prisma migrate dev    # 初始化数据库
npm run db:seed:force     # 初始化种子数据
                          # 默认账户: guada / guada
npm run start:dev         # 开发模式启动
                          # → http://localhost:3000

启动前端

cd frontend
npm install
npm run dev               # 开发模式启动
                          # → http://localhost:5173

八、LLM 适配器

已支持

扩展中

更多模型适配器正在开发中。

九、MCP 协议支持

使用官方 SDK：

import { @modelcontextprotocol/sdk } from '...'

支持：

• 工具调用
• 资源访问
• 提示词模板

十、适用场景

十一、技术亮点

1. 全栈 TypeScript

前后端均使用 TypeScript，类型安全贯穿始终。

2. 现代化前端

Vue 3 Composition API + Vite + Pinia，开发体验一流。

3. 轻量级数据库

SQLite + sqlite-vec，无需额外部署数据库服务。

4. 中文优化

jieba 分词 + FTS5，中文检索效果好。

5. 长上下文支持

两级压缩策略，支持超长对话。

十二、与同类项目对比

十三、后续规划

根据项目结构，正在开发：

• 工具热插拔
• 模型适配器热插拔
• 更多 IM 平台支持

十四、总结

核心价值

推荐理由

如果你需要一个功能完备、架构清晰、易于扩展的 AI Agent 系统，GuaDa 是一个很好的起点。

本文首发于「程序员茄子」博客，原文链接：https://chenxutan.com