Nexus Hub (Deptz)

Nexus Hub

基于Python的编排器，用于跨多个渠道（WhatsApp、Web、Slack、电子邮件、Telegram）进行多租户AI对话，支持OpenAI、Gemini、内部RAG和MCP工具。

前端管理仪表板

Nexus Hub管理员 -用于管理Nexus Hub的Vue.js管理仪表板可在 .管理仪表板提供了一个用户友好的界面，用于管理租户、API密钥、消息等。

快速开始

项目新手？ 看 docs/guides/KICKSTART_GUIDE.md 获取5分钟内入门的分步指南！

特性

• 多渠道支持 -WhatsApp、网络、Slack、电子邮件、电报
• 多LLM支持 -OpenAI、Gemini，具有统一接口
• 知识库 -内部RAG（pgvector）、OpenAI文件搜索、Gemini文件搜索
• MCP集成 -模型上下文协议服务器支持
• 租户隔离 -严格的行级安全（RLS）执行
• 分层提示 -核心护栏、全局系统提示、租户自定义提示
• 工具抽象 -统一工具执行引擎
• 事件日志记录 -全面的可观察性和报告
• 代理规划 -主动规划和任务管理

先决条件

• Python 3.11+（建议用于最新的软件包版本）
• PostgreSQL 15+ pgvector 扩展
• （可选）用于OpenAI集成的OpenAI API密钥
• （可选）Gemini集成的Gemini API密钥
• （可选）Redis用于速率限制和消息队列

安装

1.克隆和设置

# Create virtual environment
python3.11 -m venv venv
source venv/bin/activate  # On macOS/Linux
# or
venv\Scripts\activate  # On Windows

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

2.数据库设置

# Create database
createdb nexus_hub

# Enable pgvector extension
psql -d nexus_hub -c "CREATE EXTENSION IF NOT EXISTS vector;"

# Run migrations
psql -d nexus_hub -f migrations/001_initial_schema.sql
psql -d nexus_hub -f migrations/002_enable_rls.sql

3.环境配置

# Copy example environment file
cp .env.example .env

# Edit .env with your configuration values
# Minimum required: DATABASE_URL

4.启动服务器

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

API将于 http://localhost:8000

用法

健康检查

curl http://localhost:8000/health

发送信息

curl -X POST http://localhost:8000/messages/inbound \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "your-tenant-uuid",
    "channel": "web",
    "direction": "inbound",
    "from": {"type": "user", "external_id": "user-123"},
    "to": {"type": "bot", "external_id": "bot-1"},
    "content": {"type": "text", "text": "Hello, how can you help me?"},
    "metadata": {},
    "timestamp": "2025-01-16T10:00:00Z"
  }'

文档

• 入门指南 -完整的设置和测试指南
• 系统架构 -系统设计和架构
• 代理消息流 -代理规划是如何运作的
• 及时管理 -快速架构和验证
• API关键实现 -安全的API密钥管理
• MCP服务器安全 -MCP服务器的安全要求
• 电报设置 -电报适配器配置
• 贡献 -贡献指南
• 完整文档索引 -完整的文档索引

API文档

服务器运行后：

• Swagger用户界面: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

项目结构

nexus-hub/
├── app/
│   ├── models/          # Domain models
│   ├── services/        # Business logic
│   ├── adapters/        # Vendor adapters (OpenAI, Gemini, RAG, MCP)
│   ├── api/             # FastAPI routes
│   ├── infra/           # Infrastructure (database, config, auth)
│   └── main.py          # FastAPI application
├── migrations/          # SQL migration files
├── docs/                # Documentation
│   ├── guides/         # User guides
│   ├── technical/      # Technical documentation
│   └── development/    # Development docs
├── tests/              # Test suite
└── scripts/            # Utility scripts

主要特点

租户隔离

• 所有数据库查询的作用域都是 tenant_id
• RLS策略在数据库级别强制隔离
• TenantContext 对所有操作都是强制性的

快速架构

分层提示堆栈：

1. 核心护栏 （不可变，平台控制）
2. 全局系统提示 （默认行为）
3. 租户自定义提示 （已验证，租户特定）
4. 对话历史 （令牌截断）
5. 当前用户消息

工具执行

支持统一工具抽象：

• internal_rag -内部RAG（pgvector）语义搜索
• openai_file -通过矢量存储进行OpenAI文件搜索
• gemini_file -通过文件搜索商店进行Gemini文件搜索
• mcp -MCP服务器工具

测试

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=app --cov-report=html

# See tests/README.md for detailed test documentation

贡献

我们欢迎捐款！请看 贡献.md 作为指导方针。

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。