📋 目录

项目介绍

Hermes Workspace 是一个基于 React + TypeScript + Vite 构建的现代化 Web 界面，为 Hermes Agent 提供更加优雅、高效的交互体验。

什么是 Hermes Agent？

Hermes Agent 是由 Nous Research 构建的自进化 AI 代理，具备强大能力，核心特性如下：

  • 🔄 闭环学习系统 - 从经验中创建技能，在使用中不断优化迭代
  • 💬 多平台支持 - 适配 Telegram、Discord、Slack、WhatsApp、Signal、CLI 等主流平台
  • 🛠️ 40+ 内置工具 - 支持文件操作、浏览器调用、MCP 集成等功能
  • 📅 定时任务 - 内置 cron 定时调度器
  • 🤖 子代理并行 - 可创建隔离子代理，处理并行工作流
  • 🎯 模型无关 - 兼容 300+ 大模型，可自由切换

Hermes Workspace 的作用

作为 Hermes Agent 的专属前端界面，它补齐了原生交互短板，提供以下能力：

  • 🎨 精美的视觉设计 - 现代化 UI，搭配流畅动画效果
  • 💻 更好的聊天体验 - 支持 Markdown、代码高亮、消息实时流式输出
  • 🔧 可视化配置 - 图形化界面配置模型、工具、MCP 等参数
  • 📱 响应式设计 - 完美适配桌面端、移动端设备
  • 🧠 多代理协作 - 原生支持 agent swarm（代理群体）功能
  • 📁 文件管理 - 内置文件浏览器，便捷管理文件

与原生 Dashboard 的区别与亮点

功能对比表

表格

功能特性 原生 Dashboard Hermes Workspace
技术栈 React + Vite React 19 + TypeScript + Vite
聊天界面 基础聊天面板 Markdown 渲染、代码高亮、动态效果
Agent Swarm ❌ 不支持 ✅ 支持多代理协作、等距办公室视图
移动端适配 ⚠️ 基础兼容 ✅ 完整响应式设计
主题切换 ✅ 支持 ✅ 支持，新增多款主题
国际化 ✅ 多语言 ✅ 支持
内存编辑器 ❌ 无 ✅ 可视化内存管理面板
工具界面 基础配置页 交互更友好的可视化配置界面
动画效果 效果较少 Framer Motion 全场景流畅动画
代码块展示 基础展示 Shiki 语法高亮，支持一键复制
Electron 桌面版 ❌ 无 ✅ 支持，可独立桌面运行

核心亮点功能

1. Agent Swarm（代理群体）

采用可视化视图管理多代理协作，样式示意：

plaintext

┌─────────────────────────────────────┐
│  等距办公室视图 - 多代理协作        │
│  ┌─────┐ ┌─────┐ ┌─────┐          │
│  │代理A│ │代理B│ │代理C│          │
│  └─────┘ └─────┘ └─────┘          │
│  可视化代理状态和活动              │
└─────────────────────────────────────┘
  • 像素风格专属代理头像
  • 等距办公室视图直观展示所有代理
  • 实时刷新代理运行状态、活动日志
2. 升级聊天体验
  • 深度优化 Markdown 渲染，表格、列表、富文本完美展示
  • 消息过渡动画，交互体验更佳
  • 输入框智能补全、内容联想建议
3. 内存系统可视化
  • 独立可视化内存编辑器
  • 记忆文件分组管理、快速检索
  • 内存内容实时预览面板
4. 现代化 UI 设计
  • 基于 Tailwind CSS v4 搭建样式体系
  • 渐变配色 + 分层阴影，视觉层次清晰
  • 页面切换、弹窗等全场景过渡动画

快速启动指南

前置要求

  1. Node.js 18 及以上版本
  2. npm /pnpm（推荐使用 pnpm）
  3. 本地已正常安装 Hermes Agent

步骤 1：安装项目依赖

打开终端，进入项目根目录执行命令：

bash

运行

# 进入项目文件夹
cd hermes-workspace-main

# 推荐：pnpm 安装依赖
pnpm install

# 备选：npm 安装依赖
npm install

步骤 2：启动开发服务

bash

运行

# 方式1：一键启动（同时启动 Gateway + 前端服务）
pnpm start:all

# 方式2：仅启动前端开发服务器
pnpm dev

# 方式3：启动 Electron 桌面开发版
pnpm electron:dev

启动成功后，浏览器会自动访问地址：http://localhost:3000

步骤 3：生产环境打包构建

bash

运行

# 打包 Web 网页版本
pnpm build

# 打包 Windows 桌面端
pnpm electron:build:win

# 打包 macOS 桌面端
pnpm electron:build:mac

常见问题与解决方案

问题 1：React insertBefore DOM 报错

报错信息

plaintext

NotFoundError: Failed to execute 'insertBefore' on 'Node': 
The node before which the new node is to be inserted is not a child of this node.

原因：Markdown 分块渲染 + Framer Motion 动画，造成虚拟 DOM 与真实 DOM 不同步。

修复方案

  1. 修改 src/components/prompt-kit/markdown.tsx，简化渲染逻辑

typescript

运行

// 错误写法：分块渲染，使用索引作为 key
{blocks.map((block, index) => (
  <MemoizedMarkdownBlock
    key={`${blockId}-block-${index}`}
    content={block}
    components={components}
  />
))}

// 正确写法：直接渲染完整内容
<ReactMarkdown
  remarkPlugins={[remarkGfm, remarkBreaks]}
  rehypePlugins={[rehypeRaw, [rehypeSanitize, HTML_SANITIZE_SCHEMA]]}
  components={components}
>
  {content}
</ReactMarkdown>
  1. 修改 src/components/agent-chat/AgentChatMessages.tsx，移除冲突属性

typescript

运行

// 错误写法：包含 layout 属性
<motion.div
  key={message.id}
  layout="position"
  ...
/>

// 正确写法：删除 layout 属性
<motion.div
  key={message.id}
  ...
/>

问题 2：端口被占用

报错：Port 3000 is already in use

解决命令（Windows）

bash

运行

# 查看 3000 端口占用进程
netstat -ano | findstr :3000

# 结束占用进程（替换为查询到的 PID）
taskkill /PID <进程ID> /F

也可以修改 vite.config.ts 配置，更换运行端口。

问题 3：依赖安装失败

bash

运行

# 清理缓存、删除旧依赖，重新安装
pnpm store prune
rm -rf node_modules
pnpm install

# npm 兼容方案
npm install --legacy-peer-deps

问题 4：Gateway 连接失败

按以下清单逐一排查：

  1. 确认 Hermes Agent 已完整安装
  2. 执行 hermes gateway start，保证 Gateway 正常运行
  3. 核对项目内 Gateway API 地址配置
  4. 打开浏览器控制台，查看网络请求报错详情

Hermes Agent 连接配置

第一步：安装 Hermes Agent

powershell

# Windows PowerShell 执行（推荐）
iex (irm https://hermes-agent.nousresearch.com/install.ps1)

bash

运行

# Linux / macOS / WSL2 执行
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

第二步：初始化配置

bash

运行

# 启动基础设置向导
hermes setup

# 推荐：使用 Nous Portal 一站式配置
hermes setup --portal

第三步：启动 Gateway 服务

bash

运行

# 首次使用：初始化 Gateway 配置
hermes gateway setup

# 启动 Gateway
hermes gateway start

# 查看 Gateway 运行状态
hermes gateway status

第四步：Workspace 连接配置

  1. 进入 Hermes Workspace 页面，打开设置面板
  2. 填写 Gateway API 地址，默认：http://localhost:8787
  3. 补充对应认证信息
  4. 点击测试连接，显示成功即可正常使用

一键启动服务方案

方案 1：内置脚本（推荐）

项目已集成并行启动脚本，一行命令启动所有服务：

bash

运行

pnpm start:all

该命令会同时启动 Hermes Gateway 和 Vite 前端服务。

方案 2：Windows 批处理脚本（启动.bat）

新建文本文件，粘贴代码后重命名为 启动.bat，双击运行即可：

batch

@echo off
echo ========================================
echo   Hermes Workspace 一键启动脚本
echo ========================================
echo [1/3] 检查 Hermes Agent...
hermes --version >nul 2>&1
if errorlevel 1 (
    echo ❌ Hermes Agent 未安装，请先运行安装脚本
    pause
    exit /b 1
)
echo [2/3] 启动 Hermes Gateway...
start "Hermes Gateway" cmd /k "hermes gateway start"
echo 等待 Gateway 启动...
timeout /t 3 /nobreak >nul
echo [3/3] 启动 Workspace...
cd /d "%~dp0"
pnpm dev
pause

方案 3：PowerShell 脚本（启动.ps1）

新建 启动.ps1 文件，内容如下：

powershell

Write-Host "========================================" -ForegroundColor Cyan
Write-Host "  Hermes Workspace 一键启动脚本" -ForegroundColor Cyan
Write-Host "========================================" -ForegroundColor Yellow
# 检查 Hermes Agent
try {
    Write-Host "[1/3] 检查 Hermes Agent..."
    hermes --version | Out-Null
    Write-Host "✅ Hermes Agent 已安装" -ForegroundColor Green
} catch {
    Write-Host "❌ Hermes Agent 未安装，请先运行安装脚本" -ForegroundColor Red
    Read-Host "按回车键退出"
    exit 1
}
# 启动 Gateway
Write-Host "[2/3] 启动 Hermes Gateway..."
$gatewayJob = Start-Job -ScriptBlock { hermes gateway start }
Start-Sleep -Seconds 3
# 启动 Workspace
Write-Host "[3/3] 启动 Workspace..."
Set-Location $PSScriptRoot
pnpm dev
# 清理后台任务
Receive-Job $gatewayJob
Remove-Job $gatewayJob -Force

方案 4：Docker Compose（服务器部署）

新建 docker-compose.yml 文件，适合服务端常驻部署：

yaml

version: '3.8'
services:
  hermes-gateway:
    image: hermes-agent:latest
    command: hermes gateway start
    ports:
      - "8787:8787"
    volumes:
      - ~/.hermes:/root/.hermes
    restart: unless-stopped
  hermes-workspace:
    build: .
    ports:
      - "3000:3000"
    depends_on:
      - hermes-gateway
    restart: unless-stopped
    environment:
      - VITE_GATEWAY_URL=http://hermes-gateway:8787

启动命令：

bash

运行

docker-compose up -d

未来展望：一键安装包计划

当前架构

目前使用需要分开部署两个组件：

plaintext

用户需要分别安装：
├─ Hermes Agent (Python)
│  └─ CLI, Gateway
└─ Hermes Workspace (Node.js)
   └─ Web UI / Electron

目标：统一一键安装体验

Phase 1：组合安装脚本

制作跨平台统一安装脚本，单命令完成全部安装：

bash

运行

# Linux / macOS 一键安装
curl -fsSL https://example.com/install-all.sh | bash

powershell

# Windows 一键安装
iex (irm https://example.com/install-all.ps1)

安装包含：Hermes Agent、Hermes Workspace、桌面快捷方式、开机向导等。

Phase 2：Electron 捆绑应用

将运行环境与程序深度打包，最终形成独立客户端：

plaintext

Hermes Workspace.app / Hermes Workspace.exe
├─ Electron 运行时
├─ React 前端资源
├─ 内置 Python 解释器
├─ 内置 Hermes Agent
└─ 自动启动 Gateway

优势：用户无需手动安装 Python、Node.js，单安装包开箱即用，版本兼容性更强。

Phase 3：应用商店发布

后续计划上架主流应用商店：

  • Windows：Microsoft Store
  • macOS：Mac App Store
  • Linux：各发行版官方软件仓库
Phase 4：SaaS 云端版本（可选）

推出云端托管服务，免除本地部署：支持多设备同步、团队协作、企业级扩展功能。

技术实现方案

方案 A：Electron Forge 配置

json

{
  "name": "hermes-workspace",
  "config": {
    "forge": {
      "packagerConfig": {
        "extraResource": "./hermes-agent-bundle"
      },
      "makers": [
        { "name": "@electron-forge/maker-squirrel" },
        { "name": "@electron-forge/maker-dmg" },
        { "name": "@electron-forge/maker-deb" }
      ]
    }
  }
}
方案 B：NSIS（Windows 安装包脚本）

nsis

; Hermes Workspace 安装脚本
Section "Main Section" SecMain
  ; 安装文件
  SetOutPath "$INSTDIR"
  File "hermes-workspace.exe"
  File "hermes-agent-embedded.zip"
  
  ; 解压嵌入式 Python
  nsisunz::Unzip "$INSTDIR\hermes-agent-embedded.zip" "$INSTDIR\agent"
  
  ; 创建桌面快捷方式
  CreateShortCut "$DESKTOP\Hermes Workspace.lnk" "$INSTDIR\hermes-workspace.exe"
  
  ; 写入注册表
  WriteRegStr HKLM "Software\Hermes Workspace" "InstallPath" "$INSTDIR"
SectionEnd
方案 C：pkg（macOS 打包配置）

javascript

运行

// pkg.config.json
{
  "scripts": "postinstall.js",
  "assets": [
    "dist/**/*",
    "hermes-agent/**/*"
  ],
  "installLocation": "/Applications/Hermes Workspace.app"
}

总结

Hermes Workspace 是 Hermes Agent 的现代化增强前端，对比原生 Dashboard，在 UI 设计、交互体验、功能丰富度上全面升级，尤其擅长多代理协作、可视化管理等场景。后面陆续会把实用的功能记录发出来。

核心使用流程回顾

  1. 执行 pnpm install 安装项目依赖
  2. 使用 pnpm dev 或 pnpm start:all 启动服务
  3. 保证 Hermes Gateway 正常运行，完成界面连接配置
  4. 遇到报错可查阅本文「常见问题」板块排查解决

项目官方资源

Logo
MCP技术社区

欢迎加入 MCP 技术社区！与志同道合者携手前行，一同解锁 MCP 技术的无限可能！

更多推荐

cover

信创数据库AI新方案！金仓KES MCP Server开源，IDE内一站式完成SQL调优

avatar MCP技术社区
cover

DBA会被AI取代吗？我花了一个下午实测了KES MCP Server，得出了这个结论

avatar MCP技术社区
cover

告别IDE和DBA工具之间反复横跳：用自然语言调优KES数据库，这套MCP方案做到了

avatar MCP技术社区