# Hermes WebUI

> 仓库地址：https://github.com/sanchomuzax/hermes-webui
> 作者/组织：sanchomuzax
> 成熟度：beta
> 分析日期：2026-04-15

## 一句话总结
一个只读的 Hermes Agent 监控和配置查看 dashboard，通过 polling bridge 读取 agent 的 SQLite 数据库和 YAML 配置，不侵入核心代码。

## 项目定位与架构
Hermes WebUI 定位为 Hermes Agent 的伴侣工具（companion tool），核心哲学是"只读"——所有操作不修改 agent 核心代码和数据，最大限度保证安全性。

三层架构：React SPA 前端 ↔ FastAPI 后端（polling bridge）↔ Hermes Agent（数据源）。后端每 3 秒轮询 agent 的 `state.db`（只读模式），通过 REST 和 WebSocket 向前端推送数据。

技术栈后端为 Python 3.11+ / FastAPI / Uvicorn / Pydantic / PyYAML / SQLite；前端为 React 19 + TypeScript + Vite + TailwindCSS 4 + TanStack Query + WebSocket client。

## 关键技术特性
- **Dashboard**：实时活动指标——session 计数、消息量、成本追踪、gateway 健康状态、model 使用分布
- **Sessions 浏览器**：全文搜索对话历史，消息级别检查
- **配置查看器**：只读展示 `config.yaml` 和环境变量（敏感数据掩码）
- **Cron 管理**：调度任务列表、执行状态、prompts 展示
- **Skills 浏览器**：内置和自定义 skills 源码查看
- **WebSocket 实时同步**：无需修改 agent 代码即可获得实时更新
- **systemd 集成**：提供完整的 service file 模板

## 设计亮点与创新
"只读哲学"是关键设计决策——在 agent 运维中，防止意外修改配置比提供更多操作能力更重要。通过 polling bridge 间接读取数据源，完全解耦于 Hermes Agent 核心，这意味着任何 Hermes 版本升级都不会影响 WebUI。敏感数据自动掩码也体现了安全意识。

## 局限性与风险
依赖已安装的 Hermes Agent（`~/.hermes/`）。前端需要手动构建（非预编译分发）。WAL 文件锁可能在 agent 活跃写入时造成短暂显示延迟。无写入能力意味着不能通过 UI 修改配置——这既是安全特性也是功能限制。

## 与生态系统的关联
与 Mission Control（全功能编排 dashboard）形成轻/重量级互补——WebUI 适合单 agent 监控，Mission Control 适合多 agent 舰队管理。与 hermes-neurovision（艺术化可视化）在监控维度上互补。可搭配 hermes-autonomous-server（无头部署）使用。