# scorpio **Repository Path**: MarsBighead/scorpio ## Basic Information - **Project Name**: scorpio - **Description**: MCP Client with web console to integrate different providers, models and multiple MCP servers. - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: https://gitee.com/MarsBighead/scorpio - **GVP Project**: No ## Statistics - **Stars**: 2 - **Forks**: 0 - **Created**: 2025-05-21 - **Last Updated**: 2026-05-01 ## Categories & Tags **Categories**: Uncategorized **Tags**: AI, MCP ## README # Scorpio

Scorpio

基于 Multi-Agent 架构的 AI Agent 应用框架

Gateway 中心化调度 · 多 Agent 协同 · 流式响应

English Version | GitHub | 文档
--- ## 目录 - [项目概述](#项目概述) - [核心功能](#核心功能) - [系统架构](#系统架构) - [技术栈](#技术栈) - [快速开始](#快速开始) - [开发指南](#开发指南) - [部署说明](#部署说明) - [演进历程](#演进历程) - [贡献指南](#贡献指南) - [许可证](#许可证) --- ## 项目概述 **Scorpio** 是一个围绕 **Multi-Agent 架构**构建的 AI Agent 应用框架。采用 **Gateway 中心化**调度架构，实现多 Agent 的注册、管理与任务分发，为构建复杂的 AI 应用系统提供基础设施。 ### 核心设计理念 - **Agent 优先**：以 Agent 为核心单元，通过 AgentGateway 统一调度 - **协议标准化**：基于 MCP（Model Context Protocol）实现工具调用标准化 - **流式优先**：从底层支持 SSE 流式输出，提供实时交互体验 - **分层清晰**：API → Service → Core 三层架构，职责分明 ### 适用场景 - 多 Agent 协同任务的研究与实现 - RAG（检索增强生成）应用开发 - 需要工具调用的 AI 应用（数据库查询、天气查询等） - 流式对话系统的快速原型验证 --- ## 核心功能 | 功能 | 说明 | |------|------| | **Multi-Agent 调度** | AgentGateway 统一管理多个 Agent，支持别名映射与动态路由 | | **AgentLoop 引擎** | 实现 ReAct 模式，支持多轮 LLM 调用与工具执行 | | **流式响应聚合** | 支持 LLM 与工具调用的流式输出聚合 | | **MCP 集成** | 基于 fastmcp 的 SSE 协议实现，支持外部工具扩展 | | **会话管理** | 基于 PostgreSQL + pgvector 的会话与向量存储 | | **Web 控制台** | React + Ant Design X 实现的交互式聊天界面 | --- ## 系统架构 ### 架构图 ```mermaid flowchart TD A["客户端请求"] --> B["AgentGateway"] B --> C["Agent 注册与管理"] subgraph AgentPool [Agent 池] D["DefaultAgent"] E["RAGAgent"] F["SecureAgent"] G["DummyAgent"] end C --> D & E & F & G B --> H["任务分发"] H --> I["执行 Agent"] I --> J["AgentLoop"] J --> K["LLM & 工具执行"] K --> L["流式响应"] L --> M["API 路由"] ``` ### 架构说明 **三层架构**： 1. **API 层**（FastAPI） - REST 端点：`/api/v1/*` - WebSocket：`/api/v1/chat/ws` - OpenAPI 文档：`/docs` 2. **Service 层** - 业务逻辑编排 - Agent 调度与协调 - 会话与消息管理 3. **Core 层** - **AgentGateway**：Agent 注册、管理与任务分发 - **AgentLoop**：多轮推理与工具调用循环 - **Adaptors**：MCP、Local 工具适配器 - **Memory**：会话记忆（Local/Redis） - **Providers**：LLM、Database 抽象 **外部依赖**： | 组件 | 角色 | 端口 | |------|------|------| | PostgreSQL + pgvector | 会话、消息、向量存储 | 5432 | | MCP Servers | 工具调用能力（SSE） | 8100/8080 | | LLM Provider | 推理、Embedding | 11434（Ollama） | --- ## 技术栈 ### 后端 | 技术 | 用途 | |------|------| | Python 3.12+ | 主要编程语言 | | FastAPI | API 服务框架 | | Uvicorn | ASGI 服务器 | | uv | 包管理器和虚拟环境 | | fastmcp | MCP 协议实现 | | Pydantic | 数据验证与设置管理 | | PostgreSQL + pgvector | 持久化存储 | ### 前端 | 技术 | 用途 | |------|------| | React 19 | UI 库 | | TypeScript | 类型系统 | | Vite | 构建工具与开发服务器 | | Ant Design / Ant Design X | UI 组件库 | | React Router | 客户端路由 | | Axios | HTTP 客户端 | ### 部署 | 技术 | 用途 | |------|------| | Docker | 容器化 | | Docker Compose | 多容器编排 | --- ## 快速开始 ### 前置条件 - Python 3.12+ 与 uv - Node.js 18+ 与 npm - Docker & Docker Compose（推荐） ### 一键启动（Docker Compose） ```bash # 1. 构建 Docker 镜像 make build-docker # 2. 启动所有核心服务 make install-docker # 3. 验证服务 curl http://localhost:8000/api/v1/auth/initialized ``` 访问： - **API 文档**： - **前端界面**： ### 手动启动（开发模式） **后端**： ```bash cd py uv venv --prompt scorpio source .venv/bin/activate uv pip sync pyproject.toml uvicorn scorpio.cli.main:app --reload --port 8010 ``` **前端**： ```bash cd frontend npm install cp .env.development .env # 首次运行前创建配置 npm run dev ``` 详细开发流程请参考 **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)**。 --- ## 开发指南 详细的开发环境配置、代码质量检查、测试验证流程，请参阅： **📘 [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)** 该文档涵盖： - 系统架构详解（含 mermaid 架构图） - Docker Compose 统一开发环境 - 代码质量检查（lint + pre-commit） - 测试与验证流程 - API 完整测试用例 - 常见问题排查 --- ## 部署说明 ### 后端构建 ```bash # 构建 Docker 镜像 make build-docker # 查看镜像 docker images | grep scorpio ``` ### 前端构建 ```bash cd frontend npm run build ``` 构建产物位于 `frontend/dist/scorpio-frontend/` ### Docker Compose 部署 ```bash # 启动开发环境（API + DB + MCP） docker-compose -f resource/dev/docker-compose.yaml up -d ``` 详细部署说明（含生产环境配置、镜像优化、数据备份等）请参考 **[docs/DEVELOPMENT.md#3-开发环境](docs/DEVELOPMENT.md#3-开发环境)**。 --- ## 架构演进 Scorpio 的架构演进分为两个阶段，核心在于用户与 Agent 交互方式的根本性转变。 ### 阶段一：MCP 中心化基础 项目从研究 MCP（Model Context Protocol）协议实现出发，通过分析 MCP Client 的行为模式，抽象出 AgentLoop 引擎 —— 一个 ReAct 风格的推理与执行循环，并基于 PocketFlow 框架构建了首个 RAG Agent 原型。 这一阶段用户需要直接配置 `provider`、`model`、`top_k`、`temperature` 等参数，Scorpio 作为 MCP 原生框架，将 LLM 和 MCP Server 的完整控制权交到用户手中。同时构建了基础 CLI 客户端，为终端交互测试提供支持。 **关键提交**：`7026a87` — Add agentic RAG with PocketFlow --- ### 阶段二：Multi-Agent 网关架构 受 OpenClaw 2026 讨论引发的 Multi-Agent 范式转变驱动，Scorpio 对 API 进行了根本性重构。 请求负载从一个详细的参数集合 —— 例如 `{"provider": "ollama", "model": "...", "top_k": 5, "temperature": 0.7, "messages": [...]}` —— 坍缩为一个仅表达意图的简单对象 `{"agent_name": "rag", "question": "..."}`。 在这层简化背后，是中央 AgentGateway 将请求路由到一组预配置的 Agents（default、rag、secure、dummy）。每个 Agent 内部自主管理其完整的执行环境，包括 LLM 供应商选择、MCP 工具集、RAG 管道配置以及所有相关超参数。 迁移还带来了清晰的三层架构（API → Service → Repository）、基于 Cookie 的 JWT 认证与刷新令牌机制，以及 PostgreSQL + pgvector 统一持久化层。前端提供了基于 React + Ant Design X 的流式聊天界面，新增了 `scorpio-cli` 客户端用于服务于 API 开发与 Agent-native CLI 模式研究。 **关键提交**： - `f13ff0f` — 服务层重构与 JWT 认证 - `7ac7a80` — Multi-Agent Gateway 架构与前端集成 --- 如今的 Scorpio 是一个生产级 Multi-Agent 框架：内置 4 种 Agent、支持可扩展的 MCP 工具集成、端到端流式响应、架构分层清晰 —— 所有能力都通过一个简单的 `agent_name` 参数暴露。 ## 路线图 ### 近期重点 1. **用户问题意图识别与查询扩展** — 提升对用户问题的理解能力，通过内容扩展处理简短提问 2. **完善Multi-Agent架构实现** — 优化RAG Agent对数据摄入(Data Ingestion)流程的支持，实现从文档切片、嵌入生成到向量入库的端到端特性；前端增加多Agent支持操作 3. **对话内容持久化** — 后端数据库入库 + 前端 IndexedDB 缓存 4. **Agent 记忆（memory）增强** — 长短期记忆管理 5. **scorpio-cli** - 持续提示命令行客户端（client）的功能特性，追踪Agent cli发展趋势 --- ## 贡献指南 欢迎为 Scorpio 做出贡献！请遵循以下步骤： 1. Fork 仓库 2. 创建特性分支 3. 提交更改 4. 推送到分支 5. 创建 Pull Request --- ## 许可证 本项目采用宽松的 MIT 许可证开源，详情请参阅 [LICENSE](LICENSE) 文件。