Chat API 内部实现与前后端交互
本文面向修改或调试 LobeHub 源码的开发者,说明应用内部聊天链路、事件序列及核心组件。
本文不是公开 REST API 或 SDK 接入指南。/webapi/chat/[provider]、内部 tRPC 路由、
Store actions 和 ChatService 是应用实现细节,不构成外部集成的稳定契约。
不要从以下时序图推断公开接口的认证、请求格式或兼容性保证。
需要 CLI、公开 API 或 TypeScript SDK 时,先阅读开发路径选择。以下代码片段用于解释内部控制流,不是可独立运行的客户端示例;阅读时应对照所用版本的源码。
本页范围
下方时序图主要展开客户端 Agent 循环。服务端执行另见客户端 vs 服务端执行。不同 transport 和执行场景不应被当作完全相同的链路。
本文中的「预设任务」指应用内部直接调用模型的辅助功能,不是用户在任务面板创建的 Task 或 Scheduled 自动化任务。用户任务说明见任务。
交互时序图
主要步骤说明
1. 客户端发起请求
用户发送消息后,sendMessage()
(src/store/chat/slices/agentRun/actions/entries/conversationLifecycle.ts)
创建用户消息和助手消息占位,然后调用 executeClientAgent()。
2. Agent Runtime 驱动循环
本节描述的客户端 Agent 聊天链路通过 AgentRuntime.step() 循环驱动。下文的预设任务直接调用模型,不经过该循环。
初始化
(src/store/chat/slices/agentRun/actions/transports/client/streamingExecutor.ts):
- 解析 agent 配置(模型、provider、插件列表等)
- 通过
createAgentToolsEngine()创建工具注册表 - 创建
GeneralChatAgent("大脑",决定下一步做什么) 和AgentRuntime("引擎",执行指令) - 通过
createClientRuntimeExecutors()将 package 共享执行器绑定到客户端 transport
执行循环:
每一步中,GeneralChatAgent 根据当前状态返回一条
AgentInstruction,AgentRuntime 通过对应的 executor 执行:
call_llm:调用 LLM(见下方步骤 3-5)call_tool:执行工具调用(见下方步骤 6)finish:结束循环compress_context:上下文压缩request_human_approve/request_human_prompt/request_human_select:请求用户介入
3. 前端处理 LLM 请求
当 Agent 发出 call_llm 指令时,executor 调用 ChatService:
src/services/chat/index.ts对消息、工具和参数进行预处理src/services/chat/mecha/下的模块完成上下文工程 (context engineering),包括 agent 配置解析、 模型参数解析、MCP 上下文注入等- 调用
getChatCompletion准备请求参数 - 使用
@lobechat/fetch-sse包中的fetchSSE发送请求到后端 API
4. 后端处理请求
src/app/(backend)/webapi/chat/[provider]/route.ts接收请求- 调用
initModelRuntimeFromDB从数据库读取用户的 provider 配置,初始化 ModelRuntime - 同时存在 tRPC 路由
apps/server/src/routers/lambda/aiChat.ts, 用于服务端消息发送和结构化输出等场景
5. 模型调用与响应处理
ModelRuntime(packages/model-runtime/src/core/ModelRuntime.ts) 调用相应模型提供商的 API,返回流式响应- 前端通过
fetchSSE和 fetchEventSource 处理流式响应 - 对不同类型的事件(文本、工具调用、推理等)进行处理
- 通过回调函数将结果传递回客户端
6. 工具调用场景
当 AI 模型在响应中返回 tool_calls 字段时,Agent 会发出
call_tool 指令。LobeHub 支持三种工具类型:
Builtin 工具:内置在应用中的工具,通过本地执行器直接运行。
- 前端通过
invokeBuiltinTool方法在客户端直接执行 - 包括搜索、DALL-E 图像生成等内置功能
MCP 工具:通过 Model Context Protocol 连接的外部工具。
- 前端通过
invokeMCPTypePlugin方法调用MCPService(src/services/mcp.ts) - 支持 stdio、HTTP(streamable-http/SSE) 和云端(Composio)三种连接方式
- MCP 工具的注册和发现通过 MCP 服务器配置管理
Plugin 工具:传统插件体系,通过 API 网关调用。 该体系预期将逐步废弃,由 MCP 工具体系替代。
- 前端通过
invokeBuiltinTool方法调用 - 获取插件设置和清单、创建认证请求头、 发送请求到插件网关
工具执行完成后,结果写入消息并返回给 Agent 循环,
Agent 会再次调用 LLM 基于工具结果生成最终响应。
工具分发逻辑位于
src/store/chat/slices/plugin/actions/pluginTypes.ts。
7. 预设任务处理
预设任务是系统预定义的特定功能任务,
通常在用户执行特定操作时触发
(不经过 Agent Runtime 循环,直接调用 LLM)。
这些任务使用 fetchPresetTaskResult 方法执行,
该方法与正常聊天流程类似,
但会使用专门设计的提示词(prompt chain)。
执行时机:
- 角色信息自动生成:当用户创建或编辑角色时触发
- 角色头像生成(通过
autoPickEmoji方法) - 角色描述生成(通过
autocompleteAgentDescription方法) - 角色标签生成(通过
autocompleteAgentTags方法) - 角色标题生成(通过
autocompleteAgentTitle方法)
- 角色头像生成(通过
- 消息翻译:用户手动点击翻译按钮时触发
(通过
translateMessage方法) - 网页搜索:当启用搜索但模型不支持工具调用时,
通过
fetchPresetTaskResult实现搜索功能
实际代码示例:
角色头像自动生成实现:
翻译功能实现:
8. 完成
当 Agent 发出 finish 指令时,循环结束,
调用 onFinish 回调,提供完整的响应结果。
客户端 vs 服务端执行
Agent Runtime 循环的执行位置取决于场景:
- 客户端循环(浏览器):常规 1:1 对话、继续生成、
群组编排决策。循环在浏览器中运行,
入口为
executeClientAgent()(src/store/chat/slices/agentRun/actions/transports/client/streamingExecutor.ts) - 服务端循环(队列 / 本地):群聊 supervisor agent、
子 agent 任务、API/Cron 触发。循环在服务端运行,
通过 SSE 流式推送事件到客户端,
入口为
AgentRuntimeService.executeStep()(apps/server/src/services/agentRuntime/AgentRuntimeService/executeStep/index.ts), tRPC 路由为apps/server/src/routers/lambda/aiAgent.ts
Model Runtime
Model Runtime(packages/model-runtime/)是 LobeHub 中
与 LLM 模型提供商交互的核心抽象层,
负责将不同提供商的 API 适配为统一接口。
核心职责:
- 统一抽象层:通过
LobeRuntimeAI接口 (packages/model-runtime/src/core/BaseAI.ts) 隐藏不同 AI 提供商 API 的差异 - 模型初始化:通过 provider 映射表
(
packages/model-runtime/src/runtimeMap.ts) 初始化对应的运行时实例 - 能力封装:
chat(聊天流式请求)、models(模型列表)、embeddings(文本嵌入)、createImage(图像生成)、textToSpeech(语音合成)、generateObject(结构化输出)
核心接口:
适配器架构:通过 createOpenAICompatibleRuntime 和
createAnthropicCompatibleRuntime 两种工厂函数,
大多数提供商只需少量配置即可接入。
目前支持超过 40 个模型提供商
(OpenAI、Anthropic、Google、Azure、Bedrock、Ollama 等),
各实现位于 packages/model-runtime/src/providers/。
Agent Runtime
Agent Runtime(packages/agent-runtime/)是
LobeHub 的 Agent 编排引擎。
如上文所述,它是驱动整个 chat 流程的核心执行引擎。
核心组件:
AgentRuntime(packages/agent-runtime/src/core/runtime.ts): "引擎",执行 Agent 指令循环, 支持call_llm、call_tool、finish、compress_context、request_human_*等指令类型GeneralChatAgent(packages/agent-runtime/src/agents/GeneralChatAgent.ts): "大脑",根据当前状态决定下一步执行什么指令GroupOrchestrationRuntime(packages/agent-runtime/src/groupOrchestration/): 多 Agent 编排,支持 speak /broadcast/ delegate /executeTask 等协作模式UsageCounter:token 使用和费用追踪InterventionChecker: 安全黑名单管理 Agent 行为边界