React代理助手

Name: React代理助手
Author: jidechao

作者：jidechao2 星标更新：2025-11-22

安装使用来源：spider==github.com

项目介绍

ReACT 智能助手

基于 OpenAI Agents SDK 的智能助手系统，实现 ReACT 推理和行动模式，支持多轮工具调用、对话历史管理、流式响应、MCP 工具集成以及现代网页用户界面。

📋 目录

功能特性
技术栈
系统架构
快速开始
配置指南
用户指南
项目结构
开发指南
常见问题
许可

✨ 功能特性

核心功能

🧠 ReACT 推理模式
- 观察：仔细分析用户问题和当前可用信息
- 思考 (Think)：通过推理确定解决问题所需采取的行动
- 行动 (Act)：使用可用工具执行必要的操作
- 记忆：记住之前的对话和操作结果
🔧 多轮工具调用
- 支持多步骤工具调用以完成复杂任务
- 自动整合多个工具调用的结果
- 当需要继续调用工具时进行智能决策
💾 对话历史管理
- 使用 Redis 存储对话历史
- 自动保存和加载对话历史
- 在多次对话中保持上下文连续性
- 多会话管理：支持创建、切换和删除多个独立会话
⚡ 流式响应
- 实时输出生成的内容
- 打字机效果的互动体验
- 减少首字节响应时间
🔌 自定义模型提供者
- 灵活配置 OpenAI 或兼容服务的 API
- 支持自定义基础 URL
- 支持多种模型选择
🛠️ MCP 工具集成
- 支持 STDIO 协议（标准输入/输出）
- 支持 SSE 协议（服务器发送事件）
1. 支持可流式传输的 HTTP 协议
2. 支持 SSE 和可流式传输 HTTP 的超时配置
3. 动态加载和管理工具服务器
🌐 网页界面
- 现代网页用户界面（类似于 ChatGPT）
- 多会话管理（创建、切换、删除）
- 实时流式响应显示
- 工具调用和输出可视化
- WebSocket 实时通信
- Markdown 渲染：助手消息支持完整的 Markdown 格式渲染
  - 基本格式如标题、段落、列表等
  - 代码块语法高亮（支持多种编程语言）
  - 表格、引用、链接等高级格式
  - 支持 GitHub Flavored Markdown
  - 流式 Markdown 渲染（实时更新）

技术亮点

✅ 异步 IO 设计，高效处理并发操作
✅ 模块化架构，易于扩展和维护
✅ 改进的错误处理和资源清理机制
✅ 精美的命令行交互界面
✅ 现代网页用户界面（React+TypeScript+Tailwind CSS）
✅ 完整的单元测试覆盖率
✅ 类型注解和文档字符串

🛠️ 技术栈

后端

Python 3.8+
OpenAI Agents SDK - 代理框架和工具集成
FastAPI/WebSockets - WebSocket 服务器
Redis - 会话存储（必需）
Pydantic - 配置验证
python-dotenv - 环境变量管理

前端

React 18 - UI 框架
TypeScript - 类型安全
Tailwind CSS - 样式框架
Home - 构建工具
react-markdown - Markdown 渲染
remark-gfm - GitHub Flavored Markdown 支持
react-syntax-highlighter - 代码块语法高亮

🏗️ 系统架构

┌─────────────────────────────────────────────────────────────┐
│                     用户交互层                                │
│  ┌──────────────────┐      ┌──────────────────┐           │
│  │  命令行界面 CLI   │      │   Web 界面        │           │
│  │   (main.py)      │      │  (React + TS)    │           │
│  └──────────────────┘      └──────────────────┘           │
└────────────────────────┬───────────────────────────────────┘
                         │
         ┌───────────────┼───────────────┐
         │               │               │
         ▼               ▼               ▼
┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│  WebSocket  │  │  CLI 接口   │  │  Web API    │
│  服务器     │  │             │  │  (web_api)  │
└─────────────┘  └─────────────┘  └─────────────┘
         │               │               │
         └───────────────┼───────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                    Agent 核心层                               │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ ReACT 推理   │  │ 工具调用     │  │ 流式输出     │      │
│  │ 引擎         │  │ 管理器       │  │ 处理器       │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└────────────────────────┬────────────────────────────────────┘
                         │
         ┌───────────────┼───────────────┐
         ▼               ▼               ▼
┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│ 模型提供者  │  │ 会话管理    │  │ MCP 工具集成│
│ (Custom     │  │ (Redis)     │  │ (stdio/sse/ │
│  Provider)  │  │             │  │  http)      │
└─────────────┘  └─────────────┘  └─────────────┘
         │               │               │
         └───────────────┼───────────────┘
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                    配置管理层                                 │
│  ┌──────────────┐  ┌──────────────┐                         │
│  │ .env 配置    │  │ mcp_config   │                         │
│  │ 加载器       │  │ .json 加载器 │                         │
│  └──────────────┘  └──────────────┘                         │
└─────────────────────────────────────────────────────────────┘

🚀 快速开始

环境要求

Python 3.8+
Redis（用于会话存储）
Node.js 16+（仅限于网页界面）
npm 或 yarn（仅限于网页界面）

安装步骤

克隆项目

git clone <repository-url>
cd react-agent-assistant

安装并启动 Redis

# Windows（使用 Chocolatey）
choco install redis-64

# macOS（使用 Homebrew）
brew install redis
brew services start redis

# Linux（Ubuntu/Debian）
sudo apt-get install redis-server
sudo systemctl start redis-server

# 验证 Redis 是否运行
redis-cli ping
# 应该返回: PONG

安装后端依赖

# 创建虚拟环境（推荐）
python -m venv .venv

# 激活虚拟环境
# Windows:
.venv\Scripts\activate

# Linux/Mac:
source .venv/bin/activate

# 安装依赖
pip install -r requirements.txt

安装前端依赖（仅限于网页界面）

cd web
npm install
cd ..

配置环境变量

# 复制示例配置文件
cp .env.example .env

# 编辑 .env 文件，设置您的 API 密钥和配置

配置 MCP 工具（可选）

# 复制示例配置文件
cp mcp_config.example.json mcp_config.json

# 编辑 mcp_config.json，配置您的 MCP 服务器

运行程序

方法 1：命令行界面 (CLI)

python main.py

方法 2：网页界面

启动后端 WebSocket 服务器：

python web_main.py

服务器默认运行在 ws://localhost:8000

启动前端开发服务器（新终端窗口）：

cd web
npm run dev

前端默认运行在 http://localhost:5173（Vite 默认端口）

访问网页界面：

打开浏览器访问 http://localhost:5173

⚙️ 配置指南

1. 环境变量配置

创建 .env 文件（从 .env.example 复制）：

# OpenAI API 配置
OPENAI_API_KEY=your_api_key_here          # 必需：您的 API 密钥
OPENAI_BASE_URL=https://api.openai.com/v1 # 必需：API 基础 URL
OPENAI_MODEL=gpt-4                         # 必需：使用的模型名称

# Redis 配置（必需）
REDIS_URL=redis://localhost:6379/0        # 必需：Redis 连接 URL

# Web 服务配置（可选）
WEB_PORT=8000                              # WebSocket 服务器端口（默认 8000）
WEB_HOST=localhost                         # WebSocket 服务器主机（默认 localhost）

配置说明：

配置项	描述	示例
`OPENAI_API_KEY`	OpenAI API 密钥或兼容服务密钥	`sk-...`
`OPENAI_BASE_URL`	API 端点 URL	`https://api.openai.com/v1`
`OPENAI_MODEL`	模型名称	`gpt-4`, `gpt-4-turbo`, `gpt-3.5-turbo`
`REDIS_URL`	必需 Redis 连接 URL	`redis://localhost:6379/0`
`WEB_PORT`	（可选）WebSocket 服务器端口	`8000`
`WEB_HOST`	（可选）WebSocket 服务器主机	`localhost`

使用其他 API 服务：

如果您使用的是与 OpenAI 接口兼容的其他服务，只需修改 OPENAI_BASE_URL：

OPENAI_BASE_URL=https://your-api-service.com/v1

2. MCP 工具配置

创建 mcp_config.json 文件（从 mcp_config.example.json 复制）：

{
  "servers": [
    {
      "name": "filesystem",
      "protocol": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"]
    },
    {
      "name": "weather",
      "protocol": "sse",
      "url": "http://localhost:8000/sse",
      "timeout": 30
    },
    {
      "name": "calculator",
      "protocol": "streamablehttp",
      "url": "http://localhost:8000/mcp",
      "timeout": 30
    }
  ]
}

协议说明：

协议	描述	必填字段	可选字段	适用场景
`stdio`	通过标准输入/输出通信	`command`, `args`	`env`	本地命令行工具
`sse`	通过服务器发送事件通信	`url`	`timeout`, `env`	支持 SSE 的 HTTP 服务
`streamablehttp`	通过 HTTP 流式请求通信	`url`	`timeout`, `env`	标准 HTTP API 服务

超时配置：

timeout 超时（秒），仅对 SSE 和可流式传输 HTTP 协议有效
如果未配置，默认超时或无限等待（取决于协议实现）

注意： 如果不需要 MCP 工具，可以删除 mcp_config.json 文件或将 servers 数组设为空 []。

📖 用户指南

CLI 界面使用

启动后，您将看到欢迎界面：

============================================================
欢迎使用 ReACT 智能助手！
============================================================

这是一个基于 ReACT 推理模式的智能助手，能够：
  • 观察和理解您的问题
  • 思考解决方案
  • 使用工具执行操作
  • 记住对话历史

输入 'exit' 或 'quit' 退出程序
输入 Ctrl+C 也可以随时退出

============================================================

您:

网页界面使用

会话管理

创建新会话点击左侧的“新建会话”按钮
切换会话点击左侧对话列表中的任意会话
删除对话点击对话右侧的删除按钮（这将同时删除该对话的所有聊天记录）
默认会话首次访问时自动创建默认会话

发送消息

在底部输入框中输入您的问题
按下 Enter 键或点击“发送”按钮发送消息
AI 助手将提供实时流式响应，呈现打字机效果

消息显示

用户消息显示在右侧，背景为蓝色
助手消息显示在左侧，背景为白色
- 支持完整的 Markdown 格式渲染
- 代码块自动语法高亮
- 表格、列表、链接等格式友好显示
工具调用：显示为独立卡片
- 工具调用卡片：显示工具名称和调用参数（默认折叠）
- 工具输出卡片：显示工具执行结果（默认折叠）
- 状态指示：显示“正在进行...”或“已完成”

Markdown 渲染功能

助手消息支持以下 Markdown 格式：

标题：# H1, ## H2, ### H3
列表有序和无序列表
代码块：自动语法高亮（支持多种编程语言）
- 用三个反引号包裹代码块
- 指定语言类型：Python
内联代码用单个反引号包裹
链接自动识别并渲染可点击链接
表格：支持 GitHub Flavored Markdown 表格
引用：用 > 标记引用内容
加粗/斜体：**粗体**, *斜体*

📁 项目结构

react-agent-assistant/
├── src/                      # 后端源代码
│   ├── agent_core.py        # Agent 核心逻辑（ReACT 推理）
│   ├── cli.py               # CLI 交互界面
│   ├── config.py            # 配置管理
│   ├── mcp_manager.py      # MCP 工具管理器
│   ├── model_provider.py    # 模型提供者
│   ├── session_manager.py  # 会话管理器
│   └── web_api.py           # WebSocket API 服务
├── web/                     # 前端源代码
│   ├── src/
│   │   ├── components/      # React 组件
│   │   │   ├── ChatWindow.tsx      # 聊天窗口组件
│   │   │   ├── MessageInput.tsx    # 消息输入组件
│   │   │   └── SessionList.tsx     # 会话列表组件
│   │   ├── services/        # 服务层
│   │   │   └── websocket.ts # WebSocket 客户端
│   │   ├── types/           # TypeScript 类型定义
│   │   ├── App.tsx          # 主应用组件
│   │   └── main.tsx         # 入口文件
│   ├── package.json         # 前端依赖配置
│   └── vite.config.ts       # Vite 构建配置
├── tests/                   # 单元测试
├── openspec/                # OpenSpec 规范文档
├── main.py                  # CLI 入口
├── web_main.py              # Web 服务入口
├── requirements.txt          # Python 依赖
├── mcp_config.json          # MCP 工具配置
└── README.md                # 项目文档

🛠️ 开发指南

后端开发

运行测试：

pytest

代码格式：

项目使用 Python 标准代码风格，建议使用 black 或 autopep8 格式化代码。

前端开发

开发模式：

cd web
npm run dev

构建生产版本：

cd web
npm run build

预览生产构建：

cd web
npm run preview

代码检查：

cd web
npm run lint

添加新的 MCP 工具

在 mcp_config.json 中间添加服务器配置
根据