GuaDa—智能 AI 对话平台

GuaDa——智能 AI 对话系统，支持 ReAct Agent、多模型适配、RAG 知识库检索、MCP 工具调用与 Skills 技能框架。目标是打造一个可用、易用、好用的个人智能助理。目前处于早期开发阶段，部分功能正在持续快速迭代中。

遇到问题、意见建议、技术交流请加QQ群：1047993501

系统概览

GuaDa 是一个功能完备的 AI 对话和工作辅助平台，集成了浏览器自动化、 RAG 知识库、MCP 协议 和 Skills 技能框架，支持多种模型提供商，可作为企业内部 AI 中台、聊天机器人后端或个人智能助理使用。

架构特点：

•双入口：REST + SSE API 和 Bot Gateway 是两个对等入口，分别服务 Web/桌面用户和即时通讯平台用户，最终汇聚到同一个 Agent 引擎

•Agent 中心化：所有能力（知识检索、工具执行、技能调用）经由 Agent 循环统一调度

•插拔式扩展：工具、技能、模型适配器均采用接口抽象，支持热插拔（目前skills支持热插拔，其余正在开发）

•长上下文管理：两级压缩，优先裁剪工具结果再进行语义压缩，压缩支持回退

•工具按需加载：参考SKILL渐进式披露，工具也支持折叠懒加载，AI按需激活工具集，获取工具详细说明，节约Tokens

•浏览器自动化：Electron 物尽其用，使用Electron内嵌 Chromium 浏览器引擎，Agent 可直接操控浏览器页面，实现页面交互、数据采集等操作，打破传统 API 的边界限制

•知识库多轮问答：Agent自主决定如何搜索知识库、搜索多少轮次，而不是系统预先排序，准确度更高

产品截图：

整体架构

架构层次介绍

层级	职责	核心组件
前端入口	用户交互层,提供三种访问方式:Web 应用、Electron 桌面应用、IM 平台客户端	Vue 3 Web 端、Electron 桌面应用、QQ/飞书/企业微信等 IM 平台
入口层	请求处理与路由分发,将不同来源的请求统一转换为内部协议	REST + SSE API(面向 Web/Electron)、Bot Gateway(面向 IM 平台)
核心服务层	业务逻辑中枢,由 Agent Engine 统一调度对话、知识检索、工具调用等能力	Agent Engine、上下文压缩、知识库 RAG、工具与 MCP、Skills 框架、LLM 适配器
数据层	持久化存储基础设施,管理关系型数据、向量索引和文件资源	SQLite(Prisma)、sqlite-vec + FTS5、文件系统存储

核心引擎

Agent 对话引擎

GuaDa 的核心是一个实现了 ReAct (Reasoning + Acting) 模式 的多轮自治循环引擎：

关键设计：

机制	说明
会话锁 (Session Lock)	基于内存 Map 的排他锁，同一会话同时仅处理一个请求，防止并发冲突
流式传输 (SSE)	异步生成器逐块产出事件，前端实时渲染文本、思维链、工具调用进度
ReAct 循环	LLM 推理 → 工具调用 → 结果注入 → 再度推理
中断处理	`AbortSignal` 传递至 LLM 请求层，客户端断开时自动中止，节省 Token 成本
再生模式	支持 `overwrite`（覆盖）和 `multi_version`（多版本并存）两种消息重生策略
思考追踪	记录推理开始/结束时间戳，计算思维链耗时，存储于消息元数据中

上下文管理与压缩

系统采用 两级压缩策略 管理长对话的上下文窗口，在 Token 限制与信息保真之间取得平衡。

架构层次

核心特性：

•Token 计数：使用 @huggingface/tokenizers 进行精准 Token 计数，避免字符预估的不准确性

•检查点 (Checkpoint)：每次压缩持久化游标到 SessionContextState 表，重启/中断后从检查点恢复

•保护机制：最近 5 条消息强制保留不受压缩影响，最新 3 条工具结果免于裁剪

•专用压缩模型：支持配置独立模型执行压缩，降低摘要生成成本

三种压缩模式：

系统定义了三种摘要生成策略：

模式	枚举值	行为
丢弃	`disabled`	直接丢弃超出目标的旧消息，仅保留最新的 N 条。最快、零 Token 成本，但不保留历史语义
快速压缩	`fast`	单次 LLM 调用生成摘要。将待压缩消息序列化为 JSON 格式输入模型，一次性产出总结
迭代压缩	`iterative`	Agent 自检优化循环（最多 3 轮）。模型通过 `write_summary` 提交草稿，自我审查后调用 `confirm_submit` 确认最终版本，质量最高但耗时较长

压缩模式可通过角色级 summaryMode 或全局 enableSummary 配置项切换，默认使用 iterative；若迭代未产出结果则自动回退到 fast。

工具调用系统

工具系统采用 命名空间隔离 + Provider 插件 架构，支持内置工具和外部动态工具的混合编排。

当前内置的 Provider

命名空间	Provider	功能
`knowledge_base`	KnowledgeBaseToolProvider	知识库语义搜索、文件列表、分块查看
`memory`	MemoryToolProvider	会话记忆读写
`time`	TimeToolProvider	时间日期查询
`shell`	ShellToolProvider	系统命令执行
`image_recognition`	ImageRecognitionToolProvider	图片内容识别
`mcp`	MCPToolProvider	MCP 服务器远程工具
`skill`	SkillToolBridgeService	Skills 技能调用与管理

知识库 (RAG)

知识库模块实现了完整的 检索增强生成 (RAG) 流程，支持 Agent 自助多轮搜索与文档写入。

核心亮点

Agent 自助知识库管理 — 这是本系统区别于常规 RAG 的关键能力：

•自助多轮搜索：Agent 可在一次回答中多次搜索知识库，从"先搜再查分块"到"按文件名过滤"，组合多种策略逼近目标信息，自主决定是否需要再次搜索、搜索哪些文件、搜索哪些分块。

•自助写入：Agent 读取本地文件后调用 add_document 将其解析、分块、向量化并存入知识库，全程无需用户手动操作

文档处理管线

文件上传后依次经过格式解析（PDF/DOCX/TXT 等 40+ 格式，多编码自动检测）、基于 Token 的智能分块（句子边界切割 + 可配置重叠）、向量嵌入（兼容 OpenAI Embeddings API 的任意模型），最终双写至 sqlite-vec 向量库与 FTS5 全文索引。后台异步处理全程追踪百分比进度，启动时自动恢复中断任务并清理孤儿数据。

混合检索

系统融合 语义搜索 和 关键词搜索，加权计算最终得分：

最终得分 = semanticWeight × 语义分数 + keywordWeight × 关键词分数

•语义搜索基于向量余弦相似度 (sqlite-vec)

•关键词搜索基于 FTS5 全文检索 + jieba 中文分词 + BM25 重排序

•权重可配置，支持按文件/文档 ID 过滤

•支持分区存储，每个知识库一个独立向量表

文件树

知识库支持层级目录结构，支持创建文件夹、批量上传、移动、重命名。

Skills 技能框架

Skills 模块基于 Anthropic Skills 协议 设计，以文件系统为存储，支持热插拔和渐进式加载。

核心能力

组件	功能
SkillDiscoveryService	扫描 skills 目录，发现并注册技能
SkillLoaderService	解析 YAML frontmatter，加载 L1/L2 内容
SkillRegistry	内存中的技能注册表
SkillOrchestrator	技能调度、关键词匹配、元数据注入
SkillToolBridgeService	将技能注册为 `skill__` 命名空间工具
SkillVersionManager	语义化版本 + SHA256 哈希变更检测

与 Agent 的集成

1启动时扫描技能目录 → 注入 L1 元数据到 System Prompt

2Agent 根据用户请求判断是否需要激活某技能

3当需要时，调用 skill__call({skillName: "xxx"}) 获取 L2 指令

4技能内的脚本可通过执行引擎运行，结果返回 Agent 继续处理

Bot 网关

Bot 网关将 AI 对话能力扩展到即时通讯平台，通过统一的适配接口实现多平台无缝接入。

•统一适配接口 (IBotPlatform)：策略模式设计，新平台接入只需实现接口

•自动重连：WebSocket 断连后指数退避重试

•消息合并：1.5 秒窗口内多条消息合并为一条处理

•会话映射：通过 (platform, type, nativeId) 三元组建立外部用户到内部 Session 的映射

•生命周期管理：支持动态启动、停止、重启机器人实例

快速开始

环境要求

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

•npm ≥ 9.x

启动后端

cd backend-tsnpm install              # 自动执行 prisma generatenpm run db:seed:force    # 初始化种子数据（默认账户 guada / guada）npm run start:dev        # 开发模式启动 → http://localhost:3000

启动前端

cd frontendnpm installnpm run dev              # 开发模式启动 → http://localhost:5173

生产环境部署

Web 版本

详细的生产环境部署指南请查看：

https://gitee.com/zhendongdong/guada_ai/blob/master/docs/PRODUCTION_DEPLOYMENT.md

主要步骤包括：1. 配置环境变量（复制 .env.example 为 .env）2. 构建生产版本（npm run build）3. 使用 PM2 进程守护4. 配置 Nginx 反向代理5. 设置 HTTPS 证书

Electron 版本

详细的 Electron 部署指南请查看：

https://gitee.com/zhendongdong/guada_ai/blob/master/docs/ELECTRON_DEPLOYMENT.md

主要内容包括：1. 开发环境搭建2. 生产构建与打包3. 数据持久化与备份4. 故障排查与日志查看5. 更新与升级

常见问题

遇到问题请查看：

https://gitee.com/zhendongdong/guada_ai/blob/master/docs/TROUBLESHOOTING.md

常见问题包括：- 数据库表不存在- Prisma Client 未生成- 端口冲突- 环境变量配置错误- 权限问题

项目结构

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

许可证

本项目基于 MIT License 开源。

参考链接

[1]: https://nestjs.com

[2]: https://vuejs.org

[3]: https://www.typescriptlang.org

[4]: https://www.prisma.io