Hermes Workspace：现代化的 Hermes Agent Web 界面完整指南

📋 目录

• 项目介绍
• 与原生 Dashboard 的区别与亮点
• 快速启动指南
• 常见问题与解决方案
• Hermes Agent 连接配置
• 一键启动服务方案
• 未来展望：一键安装包计划

项目介绍

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 的区别与亮点

功能对比表

表格

核心亮点功能

1. Agent Swarm（代理群体）

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

plaintext

┌─────────────────────────────────────┐
│ 等距办公室视图 – 多代理协作 │
│ ┌─────┐ ┌─────┐ ┌─────┐ │
│ │代理A│ │代理B│ │代理C│ │
│ └─────┘ └─────┘ └─────┘ │
│ 可视化代理状态和活动 │
└─────────────────────────────────────┘

• 像素风格专属代理头像
• 等距办公室视图直观展示所有代理
• 实时刷新代理运行状态、活动日志

2. 升级聊天体验

• 深度优化 Markdown 渲染，表格、列表、富文本完美展示
• 消息过渡动画，交互体验更佳
• 输入框智能补全、内容联想建议

3. 内存系统可视化

• 独立可视化内存编辑器
• 记忆文件分组管理、快速检索
• 内存内容实时预览面板

4. 现代化 UI 设计

• 基于 Tailwind CSS v4 搭建样式体系
• 渐变配色 + 分层阴影，视觉层次清晰
• 页面切换、弹窗等全场景过渡动画

快速启动指南

前置要求

步骤 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 不同步。

修复方案

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>

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 连接失败

按以下清单逐一排查：

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：内置脚本（推荐）

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

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 设计、交互体验、功能丰富度上全面升级，尤其擅长多代理协作、可视化管理等场景。后面陆续会把实用的功能记录发出来。

核心使用流程回顾

项目官方资源

• Hermes Agent GitHub：https://github.com/NousResearch/hermes-agent
• 官方文档：https://hermes-agent.nousresearch.com/docs/
• 社区交流：https://discord.gg/NousResearch