多模型AI聊天客户端

AI Chatbot

React + Vite + Supabase Auth + Multi‑LLM Streaming (OpenAI, Anthropic, Google Gemini, DeepSeek)

Modern, secure, streaming AI chat interface with an animated glassmorphic login and pluggable assistant architecture.

1.概述

该项目是一个专注于前端的多提供商AI聊天客户端。它通过Supabase电子邮件/密码对用户进行身份验证，并逐令牌流式传输模型响应（服务器发送事件，SSE），以实现响应式用户体验。提供者被封装在轻量级的Assistant类后面(src/assistants/*)因此，您可以轻松地交换或扩展模型。

为什么是这个堆栈？

• React+Vite：快速开发服务器，现代构建，易于处理环境变量。
• Supabase Auth：插入托管的Postgres+Auth，具有JWT会话持久性。
• SSE流媒体：每令牌UI更新，以减少感知延迟。
• 模块化助理：每个供应商都是独立的；在不接触核心聊天UI的情况下添加新内容。

2.特点

• 电子邮件/密码验证（会话持久性和自动刷新）
• 带有基本验证的动画、可访问的登录表单
• 多LLM提供商支持：OpenAI、Anthropic Claude、Google Gemini、DeepSeek
• 增量响应流（异步生成器模式）
• 简单的提供者切换（实例化不同的Assistant类）
• 通过配置环境变量 import.meta.env
• 为敏感密钥提供安全的服务器/代理端点（推荐的生产模式）
• 内置项目代码工具(list_project_files, read_project_file, summarize_project)无需外部文件系统服务器即可读取和汇总源代码
• 聊天中每个工具的结果卡分开，以获得更清晰的输出（展开/折叠单个工具输出）
• 每回合工具执行分组：每个用户提示后面都紧接着该回合工具活动的面板（运行执行+完成结果），保留了按时间顺序排列的上下文

3.项目结构（要点）

src/
	App.jsx                # High-level composition & chat orchestration
	supabaseClient.js      # Supabase initialization using env vars
	context/AuthContext.jsx# Auth state provider
	components/            # UI modules (Login, Chat, Controls, Loader)
	assistants/            # Provider adapters (openai, anthropic, googleai, deepseekai, sseParser)
	MCP/                   # Worker / server integration (tool registration, streaming endpoints)

4.先决条件

5.环境变量

创建本地文件 ./.env.local （Vite自动加载）至少：

VITE_SUPABASE_URL=https://YOUR_PROJECT_ID.supabase.co
VITE_SUPABASE_ANON_KEY=YOUR_SUPABASE_ANON_PUBLIC_KEY

可选（仅限开发/测试–避免在生产捆绑包中公开）：

VITE_OPENAI_API_KEY=sk-...            # If you bypass proxy (not recommended)
VITE_ANTHROPIC_API_KEY=sk-ant-...     # Dev only, prefer server proxy
VITE_GOGGLE_AI_API_KEY=AIza...        # Google Generative AI key (typo kept for compatibility if present)
VITE_DEEPSEEK_AI_API_KEY=sk-...       # DeepSeek key if direct calling

生产最佳实践：将提供者密钥保存在服务器/CCloudflare Worker上（请参阅机密部分），并仅向浏览器公开您自己的代理端点。

6.安装和运行

git clone https://github.com/arasmodirpolimi/AI-CHATBOT.git
cd AI-CHATBOT
npm install
npm run dev

打开http://localhost:5173并使用Supabase测试用户登录。

在聊天中阅读项目代码

您可以要求助手使用内置的代码工具。示例提示：

• List project files. → 调用 list_project_files
• Read the file src/components/Chat/Chat.jsx → 调用 read_project_file
• Summarize the project codebase → 调用 summarize_project

现在，每个工具执行都直接在触发它的用户消息下呈现。当前回合的运行执行出现在实时活动面板中；完成的执行显示为具有关闭控件的独立可扩展/可折叠卡。前几轮将保留其完成的工具结果窗口，这样您就可以按时间顺序滚动工具使用情况，而不会丢失上下文。

7.Supabase权限设置

1. 在Supabase仪表板中：身份验证→ 提供商→ 启用电子邮件。
2. （可选）禁用电子邮件确认以加快本地迭代。
3. 在身份验证下手动创建用户→ 用户（或在实施后使用注册流程）。
4. 将项目URL和匿名密钥添加到 .env.local 如上所示。

验证流内部

• AuthContext 电话 supabase.auth.getSession() 在山上。
• 添加一个监听器，以在令牌刷新或注销时保持React状态的一致性。
• signInWithEmail 包裹 supabase.auth.signInWithPassword.
• signOut 电话 supabase.auth.signOut 并清除记住的电子邮件。
• “记住我”仅将电子邮件字符串存储在 localStorage （无代币）。

8.切换模型提供者

每个提供商导出 Assistant 具有一致的界面：

const assistant = new OpenAI.Assistant("gpt-4o-mini");
const response = await assistant.chat("Hello");
for await (const chunk of assistant.chatStream("Explain SSE")) {
	// append chunk to UI
}

要切换：

import { Assistant as AnthropicAssistant } from './assistants/anthropic';
const assistant = new AnthropicAssistant();

提供商备注

9.流媒体架构

1. 用户在聊天UI中提交提示。
2. assistant.chatStream(prompt) 返回异步生成器。
3. UI使用生成器并将令牌/块附加到活动消息中。
4. SSE解析(sseParser.js)转换原始 data: 行转换为JSON对象，直到 [DONE].

流媒体的好处

• 更快的感知响应时间。
• 实时取消或注入工具事件的可能性。
• 高级功能的基础（部分推理跟踪、工具调用进度）。

10.Anthropic与OpenAI（快速比较）

11.Cloudflare Worker/Secrets（可选）

如果通过Cloudflare Worker部署SSE代理：

wrangler secret put OPENAI_API_KEY
wrangler secret put ANTHROPIC_API_KEY

然后将Worker路线映射到 /openai/chat, /anthropic/chat 所以浏览器永远看不到原始密钥。

12.安全准则

• 切勿提交服务角色或管理员密钥。
• 对于提供者调用，首选服务器/工作代理；避免在客户端暴露密钥。
• 在存储用户聊天历史记录之前启用行级安全（RLS）。
• 考虑在代理端点上进行速率限制和日志记录。
• 在生产中使用HTTPS；注意流媒体中的混合内容。

13.与新供应商合作

1. 创建 src/assistants/myprovider.js.
2. 实施 chat(prompt, history?) 和 async *chatStream(...).
3. 将SSE或流式SDK输出解析为纯文本增量(yield string).
4. 通过实例化插入UI new Assistant() 在组件或上下文中。

最小模板：

import { parseSSEReadable } from './sseParser';
export class Assistant {
	constructor(model = 'my-model') { this.model = model; }
	async chat(content) { /* fetch -> return full text */ }
	async *chatStream(content) {
		const res = await fetch('/myprovider/chat', { /* ... */ });
		for await (const evt of parseSSEReadable(res.body)) {
			const delta = evt.delta || evt.text; if (delta) yield delta;
		}
	}
}

14.测试与调试

调试提示：

• 添加 console.log(payload) 里面 parseSSEReadable 以检查提供程序事件形状。
• 日志 session 在...之内 AuthContext 用于令牌刷新问题。
• 使用浏览器DevTools→ 网络观看 /openai/chat （流媒体播放时应保持待定状态）。

15.常见问题

16.路线图/未来的改进

• 注册和密码重置流程
• OAuth（谷歌/GitHub）通过 supabase.auth.signInWithOAuth
• 保留每个用户的聊天历史记录（Postgres表+RLS策略）
• 工具调用可视化（UI中的函数执行跟踪）
• 提示模板和系统消息编辑
• 限速和使用计量仪表板
• 主题切换和可访问性对比度改进
• 流媒体取消按钮
• 用于富文件操作的外部文件系统MCP服务器（通过npx生成）

文件系统MCP服务器支持

添加一个提供文件系统工具（读/写/列表/搜索等）的外部MCP服务器。通过POSTing创建 /api/mcp/servers 与类型 filesystem:

{
	"name": "fs",
	"type": "filesystem",
	"command": "npx",
	"args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
}

服务器以id进行响应；通过以下方式获取工具 /api/mcp/servers/<id>/tools.

工具发现现在通过MCP JSON-RPC完全动态(initialize + tools/list).没有捆绑静态回退列表。

安全注意事项：

• 不要在没有沙盒的情况下公开文件系统MCP服务器。
• 在受限的工作目录或容器中运行它。
• 在可能的情况下，首选只读或经过审核的工具；在上游添加允许/拒绝路径过滤器。

17.贡献

1. 分叉与分支： git checkout -b feat/your-feature.
2. 保持变化最小化和集中；如果行为发生变化，请更新文档。
3. 跑 npm run build （可选）以确保没有生产错误。
4. 提交描述动机的公关+截图（如果UI发生变化）。

18.许可证

麻省理工学院（见 LICENSE 如果添加）。替换或增强专有部署。

19.快速入门片段

// Inside a React component after auth:
import { Assistant as OpenAIAssistant } from './assistants/openai';
const assistant = new OpenAIAssistant();
async function ask(q) {
	let text = '';
	for await (const delta of assistant.chatStream(q)) {
		text += delta;
		// setState(text) to update UI progressively
	}
	return text;
}

20.致谢

使用Vite React模板构建；适用于多提供商AI实验。感谢流式API的开放模型提供商。

享受在这个AI+身份验证启动器之上构建。欢迎投稿！

21.部署指南

GitHub页面（仅前端）

在静态主机上附加环境变量

GitHub Pages（和其他静态主机）在构建时烘焙环境变量。您必须提供：

VITE_SUPABASE_URL=https://YOUR_PROJECT_ID.supabase.co
VITE_SUPABASE_ANON_KEY=YOUR_PUBLIC_ANON_KEY

这些是公开的（非密钥），但仍然通过RLS策略保护数据。如果它们缺失，构建工作流现在会注入占位符，应用程序应显示警告（登录操作将失败）。在“设置”>“秘密”>“操作”下设置真实秘密以启用身份验证。

GitHub Pages仅提供静态文件。您可以部署内置的Vite应用程序，但不能部署Express/MCP服务器。提供的工作流程 .github/workflows/deploy-pages.yml 自动：

1. 安装依赖项
2. 跑 npm run build
3. 发布 dist/ 文件夹到页面

首次成功运行后，检查操作日志或设置>页面中的URL。如果资产404位于子路径下，请设置 base 在 vite.config.js:

import { defineConfig } from 'vite';
export default defineConfig({ base: '/REPO_NAME/' });

后端托管（MCP和代理需要）

选择任何免费的节点/边缘平台运行 src/MCP/server.js:

设置机密（OPENAI_API_KEY、ANTHROPIC_API_KEY、ALLOWED_ORIGIN）。切勿将提供者密钥暴露给浏览器。

已添加环境变量

PORT 和 ALLOWED_ORIGIN 现在支持 server.js.在部署时调整原点以防止CORS问题。

将前端链接到后端

使用环境变量（例如。 VITE_API_BASE)将fetch调用指向已部署的后端源：

const API_BASE = import.meta.env.VITE_API_BASE || 'http://localhost:3100';
fetch(`${API_BASE}/openai/chat`, { /* ... */ });

添加 VITE_API_BASE 如果需要，在GitHub Pages构建环境中（Pages build只注入静态值，没有秘密）。

代码空间

在云开发环境的GitHub Codespace中运行所有内容：

export OPENAI_MOCK=1
export ANTHROPIC_MOCK=1
npm ci
npm run dev

转发端口（3100个后端，5173个前端）和测试流端点。

部署故障排除

Cloudflare Worker集成（后端代理）

部署Cloudflare Worker可以让您在边缘托管最小的代理端点。步骤：

1. 添加机密（从不提交提供程序密钥）：
   复制

   wrangler secret put OPENAI_API_KEY
   wrangler secret put ANTHROPIC_API_KEY
   wrangler secret put ALLOWED_ORIGIN # e.g. https://<user>.github.io/AI-CHATBOT
   

2. 部署： wrangler deploy
3. 设置页面构建环境 VITE_API_BASE 到您的Worker URL，例如：
   复制

   VITE_API_BASE=https://ai-chatbot-mcp-alt.<your-subdomain>.workers.dev  # Use latest Worker hostname (avoid old Access-protected domain)
   

确保每个端点返回CORS标头：

Access-Control-Allow-Origin: <frontend origin>
Access-Control-Allow-Headers: Content-Type
Access-Control-Allow-Methods: GET, POST, OPTIONS

缺少飞行前或来源不匹配通常会产生通用浏览器 TypeError: Failed to fetch.

按键旋转和泄漏响应

人为错误处理改进

服务器现在对常见的Anthropic上游故障执行有限的自动恢复：

1. 过载（HTTP 529/ overloaded_error)

   • 在放弃之前，最多可尝试3次增量回退（1s、2s、3s）。
   • 返回JSON错误负载 classification: "overloaded" 对于基本流端点，或者在工具感知模式下发出重试事件。
   • 建议：等待几秒钟，然后重试；过载是暂时的。

2. 未找到模型（HTTP 404/ not_found_error)

   • 在候选人列表中自动回退(claude-3-5-sonnet(-latest), haiku, opus).
   • 如果所有回退都失败，则返回错误 classification: "not_found".
   • 措施：验证 ANTHROPIC_MODEL env或更新到当前可用的模型。

3. 一般性错误

   • 其他非OK状态显示为 classification: "error".
   • 上游响应体的前400个字符用于上下文。

工具感知流媒体(/anthropic/ai/chat-stream)现在发射结构化 error 消息字符串中包含分类标记的事件。客户端将这些标记映射到更友好的系统消息。

如果您在重试后仍看到重复的过载错误，请考虑降低并发性，使用较轻的模型（俳句），或添加一个断路器，在故障爆发后将新请求延迟约15秒。 如果提供者密钥被暴露：

1. 立即生成新密钥（提供者仪表板）。
2. 更新Worker/server机密并重新部署。
3. 使旧密钥无效（删除/撤销）。
4. 如果密钥已提交，则清除存储库历史记录（使用 git filter-repo).
5. 添加轻量级速率限制+日志记录，以检测滥用尖峰。

为了便于本地开发，您仍然可以使用 VITE_OPENAI_API_KEY 或 VITE_ANTHROPIC_API_KEY；把它们放在里面 .env.local （已经被忽视了）。生产构建应该省略这些，只依赖于由服务器端机密保护的代理端点。

安全检查列表

• 将所有提供程序API密钥排除在公共构建之外。
• 如果公开，则添加基本利率限制。
• 日志工具使用情况(/logs/tools)并轮换原木。
• 考虑将会话状态移动到Redis/持久对象以进行水平扩展。

22.MCP服务器部署（当前方法）

该项目现在以使用JSON-RPC的Worker或外部MCP服务器为目标。之前的Express特定部署说明和静态工具回退已被删除。使用下面的Worker部署指南，或通过UI插入外部MCP服务器。

23.Cloudflare工作后端和动态外部MCP服务器（当前实施）

该项目已迁移，因此后端现在在Cloudflare Worker上运行(src/MCP/worker.ts)而不是Express服务器。工人提供：

为什么会有这种变化？

最初的要求是：“用户必须能够连接MCP服务器”。用户界面现在允许任何用户添加任意外部MCP服务器（这些服务器在 <baseUrl>/mcp).Worker充当了一个轻量级的代理/握手协助器，因此浏览器不需要直接管理多个会话头（如果远程服务器缺乏许可源，则可以避免CORS问题）。

添加服务器（UI流）

1. 打开应用程序（本地或已部署）-左侧边栏显示MCP服务器管理器。
2. 输入外部MCP服务器的名称（标签）和基本URL（例如。 https://example-tools.workers.dev).不包括 /mcp （Worker会自动附加它）。
3. Worker存储服务器（如果配置了KV；否则在内存中回退）并尝试MCP initialize 握手以缓存a sessionId.
4. 工具调用器面板自动获取 tools/list 并为每个工具渲染按钮。

调用工具

1. 单击工具名称——将从工具的输入模式或参数对象生成动态表单。
2. 填写参数并单击“调用工具”。
3. 工人呼唤 tools/call 在外部服务器上，如果会话过期，则自动重新初始化会话，并返回结果。
4. 结果作为附件附加到主聊天中 tool 消息。

持久性

如果KV命名空间绑定 MCP_SERVERS 配置在 wrangler.toml，服务器定义在部署中保持不变。没有KV，服务器仅存储在内存中（在Worker冷重启时丢失）。添加到 wrangler.toml:

kv_namespaces = [
	{ binding = "MCP_SERVERS", id = "<production_namespace_id>", preview_id = "<preview_namespace_id>" }
]

创建方式：

wrangler kv namespace create MCP_SERVERS
wrangler kv namespace create MCP_SERVERS --preview

然后将返回的ID复制到配置中。

安全和CORS

集 ALLOWED_ORIGIN 前端来源的秘密（逗号分隔的倍数列表）。强化CORS现在用403拒绝不允许的起源，而不是倒退：

wrangler secret put ALLOWED_ORIGIN

来自其他来源的请求将被拒绝，除非 * 明确包括在内。

员工开发和部署

已添加脚本：

npm run worker:dev     # local dev (wrangler dev)
npm run worker:deploy  # deploy to Cloudflare

部署前添加机密：

wrangler secret put ANTHROPIC_API_KEY
wrangler secret put ALLOWED_ORIGIN

外部MCP服务器要求

您的外部服务器必须在以下位置实现Streamable HTTP传输 /mcp 支持JSON-RPC方法：

• initialize
• tools/list
• tools/call

Worker会自动发送：

{
	"jsonrpc": "2.0",
	"id": "init-<timestamp>",
	"method": "initialize",
	"params": {
		"clientInfo": { "name": "dynamic-client", "version": "1.0.0" },
		"capabilities": { "tools": {} }
	}
}

它缓存了 mcp-session-id 头球一旦失败，它就会重新运行 initialize.

局限性和未来工作

从Express迁移

以前的Express服务器已被Worker取代。您可以删除任何部署引用 src/MCP/server.js 一旦对工人的行为感到满意：

npm run worker:deploy
# Update any VITE_API_BASE to Worker URL

故障排除

这种动态MCP架构使用户能够插入任何兼容的工具服务器（类似于Claude Desktop自定义MCP服务器），而无需修改应用程序代码。仍受Cloudflare Access保护的旧Worker主机名必须替换为新的 ai-chatbot-mcp-alt 主机名（GitHub Pages工作流已更新）。

24.仅限工作人员模式（Express已弃用）

你要求运行这个项目 不使用Node.js/Express——仅使用Cloudflare Worker存储库现在与这一目标保持一致：

当前状态

• src/MCP/worker.ts 实现所有必需的后端功能。
• 添加了OpenAI流媒体代理端点： POST /openai/chat 上海证券交易所
• 已存在人为终点： /anthropic/chat, /anthropic/ai/chat, /anthropic/ai/chat-stream
• 动态MCP服务器CRUD+工具调用： /api/mcp/servers, /api/mcp/servers/:id/tools, /api/mcp/servers/:id/tool-call，加上启用/分配端点。
• 全球工具注册： /admin/tools （发布/获取/删除）
• CORS通过以下方式硬化 ALLOWED_ORIGIN 秘密。
• npm start 现在运行Worker(wrangler dev).旧的Express脚本已弃用。

所需机密（部署前设置）

wrangler secret put ALLOWED_ORIGIN            # e.g. https://<your-gh-username>.github.io/AI-CHATBOT
wrangler secret put ANTHROPIC_API_KEY         # if you need Anthropic
wrangler secret put OPENAI_API_KEY            # if you use OpenAI assistant

可选：

wrangler secret put ALLOWED_FETCH_DOMAINS     # comma list for http_get (e.g. en.wikipedia.org,api.example.com)
wrangler secret put MAX_FETCH_BYTES           # e.g. 30000

地方发展（仅限工人）

npm install
npm run worker:dev
# In another terminal
npm run dev   # Vite frontend, ensure VITE_API_BASE points to worker (see below)

添加到 .env.local （或Pages构建环境）：

VITE_API_BASE=http://127.0.0.1:8787

部署时，设置 VITE_API_BASE 到 *.workers.dev URL。

能力矩阵（工人）

删除Express（可选清理）

您可以删除 src/MCP/server.js 以及任何未使用的依赖项（express、cors、dotenv）——它们已经没有列出在 package.json。如果您之前部署了Node后端，则可以将其关闭；只要确保 VITE_API_BASE 指向工人。

前端更新检查表

1. 集 VITE_API_BASE=<worker_url>.
2. 确保浏览器请求转到 https://<worker>.workers.dev/....
3. 确认网络面板显示200+SSE /anthropic/ai/chat-stream 和 /openai/chat.
4. 对于URL摘要，请确保 ALLOWED_FETCH_DOMAINS 包括目标域（例如。 en.wikipedia.org).

验证仅限工作人员模式

普通工人的陷阱

下一步硬化步骤

• 通过耐用对象或KV计数器添加速率限制（每个IP）。
• 添加日志样本计数（避免完全提示保留）以实现可观察性。
• 为长时间运行的远程MCP工具调用实现流式传递。
• 引入取消（在客户端中止时关闭SSE流）。

您现在已与Node完全解耦；Worker是单个后端表面。