# qbot

**Repository Path**: carllee34/qbot

## Basic Information

- **Project Name**: qbot
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-30
- **Last Updated**: 2026-06-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# QBot - 基于 LangChain 和 Next.js 的多智能体问答系统

## 项目概述

QBot 是一个简洁高效的多智能体协作问答系统，基于 Next.js 框架构建，集成 LangChain 实现 AI 模型调用。系统通过 YAML 配置文件灵活定义和管理智能体，支持多种大语言模型。

## 核心特性

### 1. 多智能体管理
- 支持多个智能体并行运行
- YAML 配置驱动，无需代码修改
- 动态加载和配置验证

### 2. 大模型支持
- OpenAI (GPT-4, GPT-4-Turbo, DeepSeek 等)
- Anthropic (Claude 系列)
- 自定义 API 端点支持

### 3. 简洁架构
- 直接使用 LangChain，无过度封装
- SQLite 持久化存储
- 简单的记忆系统（JSON 字符串存储向量，JS 余弦相似度语义检索）

### 4. 用户界面
- 新粗野主义/编辑式视觉风格（coral / teal 配色）
- Space Grotesk / DM Sans 字体
- 实时聊天界面、智能体选择器与会话管理

## 快速开始

### 1. 安装依赖

```bash
npm install
# 或
pnpm install
```

### 2. 配置环境变量

```bash
cp .env.example .env
```

编辑 `.env` 文件：

```env
# OpenAI API（必需，至少配置一个）
OPENAI_API_KEY=your_openai_api_key_here

# Anthropic API（可选）
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# 自定义 API（可选）
CUSTOM_API_KEY=your_custom_api_key_here

# SQLite 数据库路径（可选，默认使用项目目录下的 dev.db）
DATABASE_URL="file:./dev.db"
```

### 3. 启动开发服务器

```bash
npm run dev
```

访问 http://localhost:3000

### 4. 代码检查

```bash
npm run lint
```

### 5. 生产构建

```bash
npm run build
npm start
```

## 项目结构

```
qbot/
├── app/                          # Next.js App Router
│   ├── agents/page.tsx           # 智能体管理页面
│   ├── api/                      # API 路由
│   │   ├── agents/              # 智能体 CRUD
│   │   ├── chat/                # 聊天 API
│   │   ├── health/              # 健康检查
│   │   ├── sessions/            # 会话管理
│   │   └── settings/            # 系统设置
│   ├── page.tsx                 # 首页（聊天）
│   └── settings/page.tsx        # 设置页面
├── components/                   # React 组件
│   ├── agents/                  # 智能体管理组件
│   ├── chat/                    # 聊天组件
│   ├── layout/                  # 布局组件
│   ├── orchestration/           # 编排视图
│   └── ui/                      # 基础 UI 组件
├── lib/                          # 核心库
│   ├── agents/                  # 智能体与编排逻辑
│   │   ├── deep-agent.ts       # DeepAgent 封装
│   │   ├── orchestrator.ts     # 编排器
│   │   ├── router.ts           # 路由/委派逻辑
│   │   ├── tools.ts            # 工具注册
│   │   ├── types.ts            # 类型定义
│   │   └── ...
│   ├── api/                     # API 通用工具
│   ├── db/                      # Prisma 数据访问
│   ├── hooks/                   # React Hooks
│   └── settings/                # 系统设置服务
├── config/                       # YAML 配置
│   └── agents.yaml              # 智能体配置
└── prisma/
    ├── dev.db                   # SQLite 数据库文件（开发默认）
    └── schema.prisma            # 数据库 Schema
```

## YAML 配置

```yaml
version: "1.0.0"

agents:
  - id: my-agent
    name: 我的助手
    description: 一个简单的 AI 助手
    model:
      provider: openai
      model: gpt-4
      temperature: 0.7
    system_prompt: |
      你是一个有帮助的 AI 助手。
    memory_enabled: false
```

## API 接口

### 聊天

```bash
POST /api/chat
Content-Type: application/json

{
  "agent_id": "my-agent",
  "message": "你好",
  "session_id": "optional-session-id"
}
```

### 智能体管理

```bash
GET    /api/agents           # 获取所有智能体
POST   /api/agents           # 创建智能体
GET    /api/agents/:id       # 获取单个智能体
PUT    /api/agents/:id       # 更新智能体
DELETE /api/agents/:id       # 删除智能体
```

### 会话管理

```bash
GET /api/sessions                    # 获取所有会话
GET /api/sessions/:id                # 获取会话详情
```

## 技术栈

- **Next.js 16** - 全栈框架
- **React 19** - UI
- **TypeScript** - 类型安全
- **Tailwind CSS 4** - 样式
- **LangChain / LangGraph** - LLM 调用与编排
- **Prisma** - ORM
- **SQLite** - 持久化数据库

## 设计原则

1. **简洁务实** - 不过度工程化
2. **配置驱动** - YAML 灵活配置
3. **类型安全** - TypeScript 全覆盖
4. **直接调用** - LangChain 直接使用，无中间层

## 环境变量

| 变量 | 必需 | 说明 |
|------|------|------|
| `OPENAI_API_KEY` | 是* | OpenAI API 密钥 |
| `ANTHROPIC_API_KEY` | 否 | Anthropic API 密钥 |
| `CUSTOM_API_KEY` | 否 | 自定义 API 密钥 |
| `DATABASE_URL` | 否 | SQLite 文件路径，如 `file:./dev.db` |
| `ENCRYPTION_KEY` | 生产环境 | 长度 ≥32 字符，用于 AES-256-GCM 加密 API 密钥等敏感数据 |
| `AUTH_API_KEYS` | 否 | 逗号分隔的 API 密钥，用于中间件鉴权 |
| `CORS_ORIGIN` | 否 | 跨域来源，默认 `*` |

## 数据库

项目使用 SQLite 作为默认持久化数据库，无需额外安装 PostgreSQL 服务。

使用默认的 `DATABASE_URL="file:./dev.db"` 时，Prisma 会相对于 `prisma/schema.prisma` 创建 `prisma/dev.db`。

```bash
# 生成 Prisma Client
npm run db:generate

# 同步数据库（会根据 schema.prisma 自动创建/更新 SQLite 文件）
npm run db:push

# 启动 Prisma Studio
npm run db:studio
```

> 说明：`AgentMemory.embedding` 以 JSON 字符串形式存储，语义搜索在 JS 层通过余弦相似度实现。

## 升级后注意事项

- **Middleware 约定已废弃**：Next.js 16 构建时会提示 `middleware.ts` 约定已废弃，建议使用 `proxy`。当前实现仍兼容并自动转为 Proxy，不影响功能。
- **Lint 规则更严格**：`eslint-config-next@16` 启用了实验性 `react-hooks/set-state-in-effect` 规则，对 `useEffect` 内直接调用 `setState` 会发出 warning。这些警告来自标准的数据获取模式，不影响构建。
- **语义搜索实现**：SQLite 没有原生向量类型，`AgentMemory.embedding` 以 JSON 字符串存储，语义搜索在 JS 层通过余弦相似度实现。

## 部署

### Vercel（推荐）

1. 推送到 GitHub
2. Vercel 导入项目
3. 配置环境变量
4. 自动部署

### Docker

```bash
docker build -t qbot .
docker run -p 3000:3000 qbot
```

## 许可证

MIT