前端应用

架构概述

该前端是使用TypeScript构建的现代化React应用，采用了分层架构，将API通信、状态管理和用户界面组件之间的关注点分离。

前端架构概览 前端采用组件化架构，UI组件、API通信和状态管理之间有清晰的分离。

来源：frontend/src/routes/conversation.tsx1-221 frontend/src/context/ws-client-provider.tsx1-382 frontend/src/api/open-hands.ts1-399

API客户端层

OpenHands类作为中心API客户端，为所有后端服务提供类型化的接口。它处理身份验证、请求头和会话范围内的操作。

OpenHands API客户端结构 API客户端为所有后端通信提供类型化的方法，并且具有会话范围内的操作，这些操作会自动包含适当的请求头和身份验证。

该类维护当前的会话上下文frontend/src/api/open-hands.ts21-39，并提供会话范围内的URL生成frontend/src/api/open-hands.ts44-51。主要方法包括：

方法类别	示例	目的
配置	`getModels()`、`getAgents()`、`getSecurityAnalyzers()`	检索可用选项
对话	`createConversation()`、`getConversation()`、`startConversation()`	管理对话生命周期
设置	`getSettings()`、`saveSettings()`	用户偏好和配置
开发工具	`getVSCodeUrl()`、`getWorkspaceZip()`	与开发环境集成
Git 操作	`getGitChanges()`、`getGitChangeDiff()`	版本控制集成

来源：frontend/src/api/open-hands.ts20-399 frontend/src/hooks/query/use-settings.ts10-34

实时通信

WsClientProvider 使用Socket.IO管理WebSocket连接，实现前端和后端之间的实时通信。它负责事件解析、错误恢复和维护连接状态。

WebSocket通信流程 WebSocket提供程序管理实时事件，并在发生文件操作时自动使相关缓存失效。

该提供程序实现了复杂的事件处理frontend/src/context/ws-client-provider.tsx169-261

事件分类：使用类型守卫来识别不同的事件类型frontend/src/context/ws-client-provider.tsx38-68
错误处理：处理错误事件并显示适当的用户反馈frontend/src/context/ws-client-provider.tsx174-193
缓存管理：自动使文件操作的React Query缓存失效frontend/src/context/ws-client-provider.tsx217-254
连接管理：处理带上次事件ID跟踪的重新连接frontend/src/context/ws-client-provider.tsx263-289

主要功能包括

带事件历史保留的自动重连
速率限制的消息处理，以防止UI阻塞
乐观的用户消息处理
与React Query集成以进行缓存无效化

来源：frontend/src/context/ws-client-provider.tsx1-382 frontend/src/hooks/query/use-active-conversation.ts1-23

国际化系统

该前端实现了一个全面的国际化系统，支持16种语言，拥有超过500个翻译键，按功能领域进行组织。

国际化系统结构 i18n系统使用集中的翻译文件，并为类型安全生成TypeScript声明。

该系统提供

功能	实现	示例
类型安全	生成的`I18nKey`枚举	`I18nKey.HOME$LAUNCH_FROM_SCRATCH`
命名空间	域名-前缀键	`SETTINGS$MCP_CONFIGURATION`
回退	默认为英语	内置于react-i18next
动态加载	每种语言的JSON	所有语言在单个文件中

翻译键领域包括

STATUS$：WebSocket连接和系统状态消息
SETTINGS$：配置UI，包括MCP服务器设置
CHAT_INTERFACE$：聊天消息、输入占位符和交互状态
SECURITY$：风险级别和安全分析器消息
ACTION$：用户操作提示和建议

来源：frontend/src/i18n/translation.json1-947 frontend/src/i18n/declaration.ts1-456

设置管理

设置系统提供分层配置管理，包含客户端默认值、服务器持久化和应用程序的实时更新。

设置管理流程 设置从默认值流经服务器存储，并带有客户端验证和缓存。

设置系统支持

配置类别:

LLM设置：模型选择、API密钥、基础URLfrontend/src/services/settings.ts6-13
代理配置：代理类型和能力frontend/src/services/settings.ts8
提供商集成：GitHub/GitLab令牌和主机frontend/src/services/settings.ts15
MCP配置：模型上下文协议服务器设置frontend/src/services/settings.ts22-25
UI 偏好设置：语言、通知、分析同意 frontend/src/services/settings.ts9-21

关键实现细节:

默认设置在服务器设置不可用时提供备用值 frontend/src/hooks/query/use-settings.ts65-78
设置在客户端和服务器端均进行验证
实时更新会使 React Query 缓存失效 frontend/src/hooks/mutation/use-save-settings.ts62-64
会话结束时的确认，用于活动对话 frontend/src/components/shared/modals/settings/settings-form.tsx53-66

来源： frontend/src/services/settings.ts1-32 frontend/src/hooks/query/use-settings.ts1-82 frontend/src/hooks/mutation/use-save-settings.ts1-69 frontend/src/components/shared/modals/settings/settings-form.tsx1-135

用户界面组件

前端提供了一套全面的 UI 组件，围绕对话管理、开发工具和用户设置进行组织。主界面采用了可调整面板的布局，并集成了聊天和工作区工具。

用户界面组件结构 UI 围绕一个中心化的对话界面进行组织，其中集成了开发工具和全面的设置管理。

核心界面组件:

对话路由：处理对话生命周期的主应用程序容器 frontend/src/routes/conversation.tsx41-215
聊天界面：实时消息，带有代理状态显示和操作建议
可调整面板：响应式布局，允许用户调整界面比例 frontend/src/routes/conversation.tsx110-192
选项卡式工作区：集成的开发工具，包括 VSCode、终端、Jupyter 和浏览器 frontend/src/routes/conversation.tsx118-182

开发工具集成:

VSCode 集成，支持外部链接 frontend/src/routes/conversation.tsx127-161
终端和 Jupyter Notebook 界面
用于 Web 应用程序测试的浏览器面板 frontend/src/components/features/browser/browser.tsx1-44
具有 diff 支持的 Git 更改查看器
已提供应用程序管理

交互功能:

Git 操作的操作建议 frontend/src/components/features/chat/action-suggestions.tsx1-83
代理状态监控，带 WebSocket 连接状态 frontend/src/components/features/controls/agent-status-bar.tsx1-117
实时错误处理和用户通知
移动端响应式设计，具有自适应布局 frontend/src/routes/conversation.tsx102-108

来源： frontend/src/routes/conversation.tsx1-221 frontend/src/components/features/chat/action-suggestions.tsx1-83 frontend/src/components/features/controls/agent-status-bar.tsx1-117 frontend/src/components/features/browser/browser.tsx1-44

状态管理和数据流

前端采用了混合状态管理方法，结合了用于 UI 状态的 Redux 和用于服务器状态的 React Query，提供了优化的缓存和实时更新。

状态管理架构 应用程序使用 Redux 管理 UI 状态，使用 React Query 管理服务器状态，并通过 WebSocket 集成提供实时更新。

状态管理类别:

存储类型	目的	示例
Redux	UI 状态和实时事件	代理状态、浏览器快照、终端状态
React Query	服务器数据和缓存	设置、对话、文件更改
上下文	横切关注点	WebSocket 连接、认证
本地状态	组件特定	表单输入、模态框可见性

关键查询钩子:

useSettings()：管理用户配置，提供 404 默认值回退 frontend/src/hooks/query/use-settings.ts36-82
useActiveConversation()：跟踪当前对话，并自动重新获取 frontend/src/hooks/query/use-active-conversation.ts8-22
useGetGitChanges()：管理文件更改跟踪，具有乐观排序 frontend/src/hooks/query/use-get-git-changes.ts8-67
useVSCodeUrl()：处理 VSCode 集成 URL 生成 frontend/src/hooks/query/use-vscode-url.ts15-40

数据流模式:

WebSocket 事件触发 Redux 更新和 React Query 缓存失效
设置更改会立即使相关查询失效
对话更改会重置本地组件状态
错误处理通过上下文提供程序传播

来源： frontend/src/hooks/query/use-settings.ts1-82 frontend/src/hooks/query/use-active-conversation.ts1-23 frontend/src/hooks/query/use-get-git-changes.ts1-67 frontend/src/context/ws-client-provider.tsx134-382

开发与测试

前端包含全面的测试工具、模拟服务和开发工具，以支持高效的开发工作流程和质量保证。

开发和测试架构 前端使用现代化的测试工具和全面的模拟，以实现可靠的开发和测试工作流程。

测试框架特性:

Mock Service Worker: 全面的 API 模拟，提供真实数据 frontend/src/mocks/handlers.ts1-342
Component Testing: 使用 React Testing Library 验证组件行为
Hook Testing: 自定义 hook 与正确的 context provider 一起隔离测试 frontend/__tests__/context/ws-client-provider.test.tsx1-98
Integration Testing: 通过模拟的后端服务进行完整的用户工作流测试

Mock 数据管理:

默认用户设置，以确保测试环境的一致性 frontend/src/mocks/handlers.ts15-33
对话生命周期模拟 frontend/src/mocks/handlers.ts50-93
Git 仓库和用户数据模拟 frontend/src/mocks/handlers.ts137-154
状态管理下的设置持久性模拟 frontend/src/mocks/handlers.ts189-221

开发工具:

TypeScript 保证类型安全和开发体验
ESLint 强制执行代码质量
Vite 提供快速开发构建和热模块替换
React DevTools 集成，用于调试状态和组件层级

来源：frontend/src/mocks/handlers.ts1-342 frontend/__tests__/context/ws-client-provider.test.tsx1-98 frontend/__tests__/routes/settings.test.tsx1-163 frontend/__tests__/components/chat/action-suggestions.test.tsx1-132