1. 项目概述为 Hermes AI Agent 打造一个现代化的 Web 仪表盘如果你和我一样是 Hermes AI Agent 的深度用户那你肯定也经历过这样的场景在终端里敲着命令看着一行行日志输出试图理解 AI 助手正在“思考”什么、调用了哪些工具、消耗了多少 Token。这种交互方式虽然强大但不够直观尤其是在进行多轮复杂对话或需要回顾历史会话时体验会变得有些割裂。这就是我决定动手构建 Hermes Dashboard 的初衷——我需要一个能集中展示、管理和交互的“驾驶舱”让我能像使用 ChatGPT 网页版一样优雅地与我的本地 AI 助手对话。Hermes Dashboard 是一个开源的、现代化的 Web 仪表盘专门为 Hermes AI Agent 生态系统设计。它的核心目标是将 Hermes 强大的后端能力通过一个美观、响应迅速的前端界面呈现出来。这个项目不是官方出品而是我个人基于实际使用痛点驱动的产物。它的设计灵感很大程度上来源于 PinchChat一个为 OpenClaw 设计的优秀 UI但在实现上我们完全从零开始针对 Hermes 的 API 和数据格式进行了深度定制和优化。无论你是开发者想要一个更友好的调试界面还是普通用户希望获得更接近主流 AI 产品的使用体验这个仪表盘都能满足你。整个项目采用前后端分离的架构前端使用 React 18 TypeScript Vite 构建确保了极致的开发体验和运行时性能后端则是一个轻量级的 Python FastAPI 服务作为连接前端和 Hermes Gateway 的“桥梁”。这个桥梁服务器负责会话管理、实时通信转发以及 Hermes 配置文件的读取。最让我满意的是其实时聊天功能基于 WebSocket 实现你可以看到 AI 的“思考过程”Thinking Blocks和“工具调用”Tool Calls像流一样逐步呈现这种体验远比等待一个完整的响应要有趣和透明得多。2. 核心功能与设计哲学解析2.1 功能全景不止于聊天界面很多人第一眼看到 Hermes Dashboard可能会觉得它只是一个聊天窗口。确实聊天是核心但它的设计远不止于此。我把它定位为一个“会话管理中心”。下面我来拆解一下它的几个核心功能模块以及我为什么认为这些设计是必要的。实时聊天与流式响应这是仪表盘的灵魂。我们通过 WebSocket 连接将 Hermes Gateway 的流式响应实时推送到前端。这意味着你输入问题后答案会像真正的对话一样一个字一个字地“流”出来。更重要的是我们完整解析并可视化了 Hermes 响应中的关键结构thinking思考过程、tool_calls工具调用和content最终回复。每个thinking块都会显示其消耗的时间每个tool_calls都会展示工具名称、参数和状态成功/失败。这种透明化对于调试复杂的 Agent 工作流至关重要你能清楚地知道 AI 在哪一步“卡住”了或者调用了哪个工具却得到了意外结果。全局可视化控制在实际使用中尤其是进行多轮复杂对话后页面可能会被大量的思考过程和工具调用记录填满干扰你对核心对话内容的阅读。为此我在侧边栏顶部设计了三个全局开关“隐藏思考”、“隐藏工具”、“隐藏结果”。一键即可折叠或展开所有同类区块。这个功能看似简单却极大地提升了长会话的可读性和操作效率。这是我在早期使用原型时被满屏的 JSON 结构“轰炸”后第一时间加入的功能。会话管理与令牌消耗可视化所有与 Hermes 的交互都会以“会话”的形式保存。在左侧的会话列表中你可以清晰地看到每个会话的标题自动从首条消息生成、创建时间、使用的模型以及一个非常直观的令牌消耗进度条。这个进度条以不同颜色区分已用 Token 和上下文剩余容量让你对当前会话的“成本”和“剩余空间”一目了然。你还可以通过拖拽来重新排序会话将重要的对话置顶。多主题与深度定制考虑到长时间编码或阅读每个人的视觉偏好和场景都不同。仪表盘内置了Dark暗黑、Light明亮、OLED纯黑三种主题以及Cyan青色、Violet紫色、Emerald翡翠绿、Amber琥珀色、Rose玫瑰粉、Blue蓝色六种强调色。OLED 主题是为 AMOLED 屏幕设备准备的能实现真正的纯黑背景在夜间使用或节省电量时尤其友好。所有这些设置都通过一个统一的设置面板点击右上角的齿轮图标进行管理并且会即时保存到浏览器的本地存储中。2.2 架构设计为什么选择 FastAPI React 的组合在技术选型上我经过了深思熟虑。最终选择 FastAPI 作为后端桥梁React 作为前端框架是基于以下几个核心考量后端FastAPI的考量异步原生支持Hermes Gateway 的流式响应本质上是异步的。FastAPI 对async/await的原生支持使得处理 WebSocket 连接和转发 SSEServer-Sent Events流变得异常简单和高效。相比传统的 Flask需要额外扩展FastAPI 的异步路由写起来更直观。自动 API 文档FastAPI 自动生成的交互式 API 文档Swagger UI 和 ReDoc对于项目后续的维护和他人接入非常友好。调试接口时我基本不需要打开额外的 API 测试工具。与 Python 生态无缝集成Hermes 本身是 Python 项目其配置~/.hermes/config.yaml和会话文件~/.hermes/sessions/*.jsonl都是 Python 友好的格式。使用 FastAPI 可以方便地利用pyyaml、jsonlines等库进行解析无需在不同语言环境间进行复杂的数据转换。轻量与高性能这个桥梁服务器的逻辑相对简单主要是路由转发和文件读写。FastAPI 基于 Starlette非常轻量启动速度快资源占用低完美符合“桥梁”的定位。前端React TypeScript Vite的考量类型安全与开发体验TypeScript 是必须的。面对 Hermes API 返回的复杂嵌套的 JSON 数据结构如果没有类型定义开发过程将是一场灾难。我们为会话、消息、工具调用等核心数据结构定义了完整的 TypeScript 接口这极大地减少了运行时错误并提升了代码提示的体验。组件化与状态管理聊天界面天然适合组件化开发。我们将界面拆分为ChatContainer、MessageBubble、ThinkingBlock、ToolCallCard、SessionSidebar等独立组件。状态管理方面鉴于应用复杂度适中我们选择了 React 内置的 Context API 结合useReducer来管理全局的主题、会话列表和当前活动会话状态避免了引入 Redux 等重型库的复杂度。极速的开发与构建Vite 取代了传统的 Webpack。它的快速冷启动和热更新HMR能力让前端开发体验有了质的飞跃。修改一个组件几乎在保存的瞬间就能在浏览器中看到更新这对于需要频繁调整 UI 的仪表盘项目来说效率提升是巨大的。响应式设计我们使用 Tailwind CSS 来构建样式。其功能优先Utility-First的理念让我们能快速实现从桌面端到移动端的响应式布局。通过简单的断点类如md:flex,sm:hidden就能让侧边栏在移动设备上变为可滑出的抽屉聊天区域自适应屏幕宽度。通信流程详解 整个数据流可以概括为React前端 (10007端口) - WebSocket/HTTP - FastAPI桥梁 (8643端口) - HTTP/SSE - Hermes Gateway (8642端口) - 本地文件系统 (~/.hermes/)。 桥梁服务器在这里起到了关键的解耦作用。前端不需要知道 Hermes Gateway 的具体细节只需要与桥梁通信。桥梁负责认证、会话文件读写、以及将 Hermes 的流式响应转换为更前端友好的 WebSocket 消息格式。这种设计也使得未来替换后端 AI 服务只要协议兼容成为可能。3. 从零开始的部署与配置实操指南3.1 环境准备与一键启动假设你已经在本地运行着 Hermes AI Agent并且 Gateway 服务在默认的 8642 端口运行。接下来我们一步步把 Dashboard 跑起来。第一步克隆项目与依赖安装# 克隆项目代码 git clone https://github.com/monaleesa77/hermes-dashboard.git cd hermes-dashboard项目结构非常清晰。/frontend目录包含所有 React 代码/backend目录则是 Python 桥梁服务。后端依赖安装cd backend # 强烈建议使用虚拟环境 python3 -m venv venv # 激活虚拟环境 # macOS/Linux: source venv/bin/activate # Windows: # venv\Scripts\activate # 安装依赖 pip install -r requirements.txtrequirements.txt核心包含了fastapi,uvicorn[standard],websockets,pydantic,pyyaml,jsonlines等。使用虚拟环境可以避免污染你的全局 Python 环境也便于管理不同项目的依赖。前端依赖安装cd ../frontend npm install # 或者如果你喜欢用 yarn 或 pnpm # yarn install # pnpm install这个过程会下载 React、TypeScript、Vite 以及相关的 UI 库如lucide-react图标库等所有依赖。第二步配置桥梁服务器在启动前最关键的一步是配置后端。后端的所有配置都通过backend/.env文件管理。如果该文件不存在你需要从模板创建cd backend cp .env.example .env然后编辑.env文件以下是最关键的几个配置项# 桥梁服务器自身监听的地址和端口 BRIDGE_HOST0.0.0.0 # 设置为 0.0.0.0 允许同一网络下的其他设备访问 BRIDGE_PORT8643 # 默认端口如果冲突可以修改 # 你的 Hermes Gateway 地址 HERMES_API_URLhttp://localhost:8642 # 如果 Hermes Gateway 配置了 API 密钥请填写在这里。默认通常是 ‘any‘。 HERMES_API_KEYany # Hermes 配置和会话文件的根目录 # 默认是 ~/.hermes请根据你的实际路径修改 HERMES_HOME/Users/你的用户名/.hermes # CORS 跨域设置允许前端运行在10007端口访问后端 # 这里使用了通配符允许你整个局域网段访问方便移动端调试 CORS_ORIGINShttp://localhost:10007,https://localhost:10007,http://127.0.0.1:10007,https://127.0.0.1:10007,http://192.168.*:10007,http://10.*.*.*:10007注意HERMES_HOME的路径一定要配置正确否则桥梁服务器将无法读取你的历史会话。在 macOS/Linux 上~代表用户主目录。在 Windows 上你需要填写完整路径例如C:\Users\你的用户名\.hermes。第三步启动服务你可以选择手动分别启动前后端或者使用我提供的便捷脚本。方法一使用一键启动脚本推荐在项目根目录下我准备了一个start.sh脚本Windows 用户可以使用对应的start.bat或使用 Git Bash 来运行.sh文件。# 确保脚本有执行权限 chmod x start.sh # 运行脚本 ./start.sh这个脚本会依次执行以下操作检查 Hermes Gateway 是否在运行通过访问http://localhost:8642/health。激活 Python 虚拟环境并启动后端桥梁服务器在backend目录。启动前端开发服务器在frontend目录。自动在默认浏览器中打开http://localhost:10007。方法二手动启动如果你更喜欢分步控制或者需要调试# 终端1确保 Hermes Gateway 在运行 hermes gateway run # 或者如果已经在运行可以跳过 # 终端2启动后端桥梁 cd backend source venv/bin/activate python main.py # 看到 INFO: Uvicorn running on http://0.0.0.0:8643 表示成功 # 终端3启动前端 cd frontend npm run dev # 看到 VITE v4.x.x ready in xxx ms 以及 Local: http://localhost:10007 表示成功然后打开浏览器访问http://localhost:10007你应该就能看到 Hermes Dashboard 的主界面了。3.2 核心配置文件深度解析为了让仪表盘更贴合你的工作环境理解几个核心配置文件的用途至关重要。除了刚才提到的backend/.env前端也有一些配置值得关注。后端配置 (backend/.env) 进阶BRIDGE_HOST0.0.0.0这个设置让桥梁服务器监听所有网络接口。如果你想限制只能从本机访问可以改为127.0.0.1。设置为0.0.0.0是允许从同一局域网内其他设备比如手机、平板访问仪表盘的前提。CORS_ORIGINS这是解决跨域问题的关键。前端运行在10007端口后端在8643端口浏览器出于安全考虑会阻止这种跨端口请求。这个配置告诉后端哪些来源的请求是被允许的。我们配置了localhost、127.0.0.1以及192.168.*和10.*.*.*这两个常见的局域网 IP 段基本覆盖了家庭网络环境。HERMES_API_KEY如果你的 Hermes Gateway 在配置中启用了 API 密钥认证通常在~/.hermes/config.yaml中设置你必须将正确的密钥填在这里。默认的 Hermes 安装通常不使用密钥所以填any即可。前端配置 (frontend/vite.config.ts) Vite 的配置文件主要做了两件事开发服务器代理为了让前端在开发时能方便地调用后端 API我们配置了代理。所有以/api或/ws开头的请求都会被 Vite 的开发服务器转发到http://localhost:8643即我们的桥梁后端。这样在前端代码中你可以直接用相对路径如/api/sessions发起请求而不需要写完整的后端地址。server: { proxy: { /api: http://localhost:8643, /ws: { target: http://localhost:8643, ws: true, // 代理 WebSocket }, }, },构建优化配置了构建产物的输出目录、代码分割等这些对于生产环境部署很重要。Hermes 配置文件 (~/.hermes/config.yaml) 仪表盘本身不修改这个文件但会读取其中的信息例如可用的模型列表。当你点击界面上的模型选择器时下拉列表里的选项就是从这里动态获取的。确保你的 Hermes 配置正确仪表盘才能获取到完整的模型信息。3.3 移动端访问与 PWA 安装实战一个现代化的仪表盘不应该被束缚在电脑前。Hermes Dashboard 支持响应式设计并且可以作为一个渐进式 Web 应用PWA安装到手机主屏幕获得近乎原生应用的体验。让手机访问电脑上的仪表盘 原理很简单让你的手机和电脑处于同一个 WiFi 网络下然后通过电脑的局域网 IP 地址来访问。查找电脑的 IP 地址macOS/Linux在终端输入ifconfig | grep inet | grep -v 127.0.0.1找到类似inet 192.168.1.105的地址。Windows在命令提示符输入ipconfig找到“无线局域网适配器 WLAN”或“以太网适配器”下的IPv4 地址。确保服务正在运行且允许外部访问确认backend/.env中BRIDGE_HOST0.0.0.0并且电脑的防火墙没有阻止10007和8643端口。macOS系统设置 - 网络 - 防火墙 - 防火墙选项...确保相关端口未被阻止。Windows控制面板 - Windows Defender 防火墙 - 高级设置 - 入站规则确保有允许 Node.js 和 Python 的规则。在手机浏览器中访问打开手机浏览器输入http://[你的电脑IP]:10007例如http://192.168.1.105:10007。如果一切顺利你就能看到登录界面。重要安全提示当前简化版配置使用的是HTTP协议数据在局域网内以明文传输。请仅在可信的家庭或办公室网络中使用此功能切勿在咖啡馆、机场等公共 WiFi 下使用以防会话数据被窃听。如需 HTTPS需要生成自签名证书并修改配置过程较为复杂且手机会有安全警告一般开发调试无需启用。将仪表盘安装为手机 AppPWA PWA 技术可以让网页应用像原生 App 一样被安装到主屏幕并且具备离线缓存、独立窗口运行等特性。iOS (Safari)用 Safari 浏览器成功打开仪表盘页面。点击底部的分享按钮一个方框带向上箭头。在分享菜单中向下滑动找到并点击“添加到主屏幕”。可以自定义名称如“Hermes Dashboard”然后点击“添加”。Android (Chrome)用 Chrome 浏览器打开仪表盘页面。点击右上角三个点菜单。选择“安装应用”或“添加到主屏幕”。确认安装。安装后你的手机桌面上会出现一个 Hermes Dashboard 的图标点击它就会以独立应用窗口的形式打开没有浏览器地址栏体验更佳。这得益于我们在frontend项目中配置的manifest.json和 Service Worker。4. 开发与定制深入项目结构与二次开发4.1 前后端代码结构导览如果你想修复 Bug、添加新功能或者单纯想学习一下实现了解代码结构是第一步。后端 (/backend) 结构main.pyFastAPI 应用入口。定义了所有的 REST API 路由/api/*和 WebSocket 路由/ws/chat。这里是请求的“总调度中心”。hermes_client.py封装了与 Hermes Gateway 的 HTTP 和 SSE 通信。包含一个HermesClient类负责发送聊天请求、处理流式响应。这是桥梁与 Hermes 核心交互的地方。session_store.py负责读写~/.hermes/sessions/目录下的.jsonl会话文件。它解析每一行 JSON将其转换为前端需要的会话和消息结构。这里处理了会话的增删改查。models.py使用 Pydantic 定义了所有请求和响应的数据模型。例如ChatRequest、ChatResponse、Session、Message等。这确保了 API 接口数据的类型安全和自动验证。config_loader.py一个工具模块用于读取和解析~/.hermes/config.yaml文件提取出可用的模型列表等配置信息。前端 (/frontend/src) 结构App.tsx应用根组件。它定义了主要的布局结构Header、Sidebar、Main Chat Area并提供了全局的 Context如 ThemeContext, SessionContext。components/所有 React 组件都存放在这里并按功能分文件夹。Chat/最核心的聊天区域组件。ChatContainer管理消息列表和输入框MessageBubble渲染单条消息ThinkingBlock和ToolCallCard分别渲染思考块和工具调用卡片。Sidebar/左侧会话列表组件。SessionList展示所有会话SessionItem是单个会话项包含拖拽排序逻辑。Layout/布局组件如Header顶栏包含设置按钮和主题切换、SettingsPanel设置抽屉。services/封装了所有与后端 API 和 WebSocket 通信的逻辑。api.ts使用axios或fetch封装 REST API 调用获取会话列表、创建会话等。websocket.ts管理 WebSocket 连接的生命周期、消息发送和接收。这里处理了连接建立、重连、消息队列等细节。types/集中存放所有的 TypeScript 类型定义文件.d.ts或.ts确保前后端数据类型一致。hooks/自定义 React Hooks例如useWebSocket、useLocalStorage用于持久化主题设置等。4.2 如何添加一个新的主题或强调色定制 UI 是让项目更具个人色彩的乐趣所在。假设你想添加一个“深紫色”主题。第一步定义新的 CSS 变量前端样式主要基于 CSS 变量和 Tailwind CSS。所有主题和颜色都定义在frontend/src/index.css或一个专门的theme.css文件中。找到定义:root浅色主题和.dark、.oled类下 CSS 变量的地方。为你新主题的各个部分定义变量。通常包括--background背景色--foreground前景文字色--card卡片背景色--card-foreground卡片文字色--primary主要按钮/强调色--primary-foreground主要按钮上的文字色--secondary次要元素色--muted柔和/禁用状态色--accent点缀色可能和 primary 相同或不同--border边框色--ring焦点环颜色例如在.dark选择器下复制一份变量定义将类名改为.theme-deep-purple并修改颜色值。第二步在前端状态管理中注册新主题在定义主题状态的地方通常在App.tsx或一个专门的theme.ts文件中你会找到一个主题列表数组如export const themes [ { id: dark, name: Dark, icon: Moon }, { id: light, name: Light, icon: Sun }, { id: oled, name: OLED, icon: Smartphone }, // 添加你的新主题 { id: deep-purple, name: Deep Purple, icon: Palette }, ] as const;同时确保你的图标组件如Palette已从图标库中导入。第三步更新设置面板设置面板SettingsPanel组件中会有一个下拉选择器来切换主题。你需要将新的主题选项添加到对应的下拉菜单数据源中。第四步动态应用主题在根组件或一个主题提供者中会有根据当前选择的主题 ID 来动态更新html标签class的逻辑。例如当选择deep-purple时将html的类设置为theme-deep-purple。确保这个逻辑包含了你的新主题。添加强调色也是类似的过程在 CSS 中定义一组新的--primary、--accent等变量然后在颜色选择器的配置数组中添加新选项最后在应用颜色的逻辑处进行关联。4.3 核心通信流程从输入到响应的数据之旅理解数据如何流动是进行任何深度定制或故障排查的基础。让我们跟踪一次完整的用户提问过程。用户输入与前端处理 用户在输入框键入消息并按下发送。ChatInput组件捕获事件通过 Context 或 Props 调用一个sendMessage函数。该函数会做几件事将用户消息对象添加到本地消息列表并立即在 UI 上显示以优化响应速度。通过WebSocketService将消息对象包含session_id,content,model等信息序列化为 JSON并通过已建立的 WebSocket 连接发送到ws://localhost:8643/ws/chat。桥梁服务器路由与转发 后端的main.py中有一个 WebSocket 端点/ws/chat。当它收到前端发来的消息后首先进行基本的验证如会话是否存在。然后调用HermesClient的stream_chat方法。这个方法会向HERMES_API_URL即http://localhost:8642发起一个 HTTP POST 请求请求体是格式化的聊天请求并设置Accept: text/event-stream头部以接收 SSE 流。Hermes Gateway 开始处理请求并返回一个 SSE 流。流式响应处理与转发HermesClient.stream_chat方法会逐块读取 SSE 流。对于收到的每一块数据一个 JSON 对象进行初步解析和格式化。例如将 Hermes 返回的thinking、tool_calls等字段提取出来包装成前端约定好的消息格式。通过异步的 WebSocketsend_text方法将这一块格式化后的数据实时发送回前端。这个过程持续到 Hermes 返回[DONE]事件或流关闭。前端实时渲染 前端的WebSocketService在onmessage事件监听器中持续收到后端推送的流式数据块。根据消息类型如thinking、tool_call、content_chunk更新本地 React 组件的状态。ThinkingBlock组件会展示一个可折叠的区域显示 AI 的“内心独白”。ToolCallCard组件会展示一个工具调用卡片包含工具名、参数并根据返回结果更新状态运行中/成功/失败。MessageBubble组件会逐步追加content_chunk实现打字机效果。所有这些更新都是响应式的React 会自动高效地重渲染相关部分。会话持久化 当一次完整的响应结束后桥梁服务器会收到最终的完整消息。此时session_store.py中的逻辑会被触发将这条新的助理消息追加到对应会话的.jsonl文件末尾。这样下次刷新页面或重新打开仪表盘时历史会话得以完整恢复。5. 常见问题排查与性能优化心得5.1 启动与连接问题速查表在部署和使用过程中你可能会遇到一些问题。下面是我总结的常见问题及其解决方法。问题现象可能原因排查步骤与解决方案访问http://localhost:10007白屏或无法连接1. 前端开发服务器未启动。2. 端口被占用。1. 检查终端是否运行了npm run dev且无报错。2. 运行lsof -i :10007查看端口占用终止冲突进程或修改frontend/vite.config.ts中的server.port。前端控制台报错WebSocket connection failed或Failed to fetch /api/...1. 后端桥梁服务器未启动。2. CORS 配置错误。3. 代理配置错误。1. 检查后端终端是否运行python main.py且监听在8643端口 (http://localhost:8643/api/health应返回{status:ok})。2. 确认backend/.env中的CORS_ORIGINS包含了http://localhost:10007。3. 确认frontend/vite.config.ts中的proxy配置正确指向http://localhost:8643。会话列表为空或提示“无法读取会话”1.HERMES_HOME路径配置错误。2. 对会话文件没有读取权限。3. Hermes Gateway 未运行或路径不同。1. 检查backend/.env中的HERMES_HOME确保路径指向正确的.hermes目录。使用绝对路径更可靠。2. 检查~/.hermes/sessions/目录是否存在且包含.jsonl文件。3. 运行curl http://localhost:8642/health确认 Hermes Gateway 健康。发送消息后无响应或 WebSocket 连接立即关闭1. Hermes Gateway 服务异常。2. 请求模型不存在或配置有误。3. 桥梁服务器转发请求时出错。1. 查看后端终端日志通常会有详细的错误信息如连接被拒、模型未找到。2. 检查 Hermes Gateway 的日志 (hermes gateway run的终端)。3. 尝试用curl直接向 Hermes Gateway 发送一个简单请求测试其是否正常工作。移动设备无法访问1. 电脑和手机不在同一网络。2. 电脑防火墙阻止了端口。3. 使用了错误的 IP 地址。1. 确认两者连接的是同一个 WiFi。2. 暂时关闭电脑防火墙测试。3. 在电脑上用ifconfig或ipconfig获取正确的局域网 IP不要使用localhost或127.0.0.1。确保.env中BRIDGE_HOST0.0.0.0。实操心得日志是你的好朋友。遇到任何问题第一步永远是打开终端查看后端 (python main.py) 和前端的 (npm run dev) 的运行日志。90% 的问题都能从日志输出的错误信息中找到线索。特别是后端日志它会记录每一个 API 请求、WebSocket 连接和文件操作是诊断问题的第一现场。5.2 性能优化与使用技巧随着会话历史越来越长或者进行复杂的工具调用你可能会关心性能。这里有一些优化建议和使用技巧。前端性能优化虚拟化长列表如果单个会话的消息量巨大比如超过 1000 条渲染所有消息可能会导致页面卡顿。可以考虑引入react-window或react-virtualized这样的虚拟滚动库只渲染可视区域内的消息项。优化重渲染使用React.memo包裹MessageBubble、SessionItem等纯展示型组件防止因父组件状态无关更新导致的不必要重渲染。合理使用useCallback和useMemo来缓存函数和计算值。WebSocket 连接管理确保 WebSocket 连接是单例的并且在组件卸载时正确关闭。我们的WebSocketService类应该实现为可重用的避免重复创建连接。后端性能优化会话文件读取优化session_store.py在读取大型.jsonl文件时应避免一次性加载全部内容到内存。可以使用jsonlines库流式读取或者实现分页读取。目前我们是在获取会话列表时读取所有消息来计算 Token对于超长会话可以考虑惰性计算或缓存 Token 使用量。异步文件操作使用aiofiles库替代同步的open()和文件读写操作可以让 FastAPI 在等待文件 I/O 时不阻塞其他请求提升并发能力。连接池如果与 Hermes Gateway 的通信频繁可以考虑使用httpx.AsyncClient并配置连接池复用 HTTP 连接减少建立连接的开销。使用技巧快捷键考虑为常用操作添加键盘快捷键。例如Ctrl/Cmd K聚焦到输入框Ctrl/Cmd Enter发送消息Esc取消当前 AI 生成等。这能极大提升重度用户的使用效率。会话归档与清理长期使用后会话文件会占用磁盘空间。可以在设置面板中添加一个“清理旧会话”的功能自动删除超过一定天数或总 Token 超过限制的会话。导入/导出会话实现会话的导出为 JSON 或 Markdown和导入功能方便备份或与他人分享有趣的对话记录。多模型快速切换在输入框附近或设置中提供一个模型下拉选择器并记住每个会话最后使用的模型。这样在不同会话间切换时可以无缝使用不同的模型如 GPT-4 用于复杂推理Claude 用于创意写作。一个我踩过的坑WebSocket 重连与消息队列。在网络不稳定的环境下WebSocket 可能会断开。最初的实现没有处理重连一旦断开用户就需要手动刷新页面。后来我增加了自动重连机制并在前端实现了一个简单的消息队列。在连接断开期间用户发送的消息会被暂存在队列中当连接恢复时自动按顺序重新发送。这个小小的改进极大地提升了应用的健壮性。实现的关键是在websocket.ts中监听onclose事件启动一个指数退避的重连定时器并维护一个待发送消息的数组。