## 项目概述

Hermes WebUI 是 Hermes Agent 的自托管 Web 界面，目标是从浏览器或手机获得接近 Hermes CLI 的完整体验。它采用三栏布局：左侧为会话与导航，中间为聊天，右侧为工作区文件浏览；模型、Profile、工作区等控制集中在 composer footer，设置与会话工具集中在 Hermes Control Center。

项目使用 Python 标准库 HTTP 服务器加原生 JavaScript，没有构建步骤、没有前端框架、没有打包器。仓库元数据显示许可证为 MIT。最新 Release 为 v0.52.106（2026-07-29 发布）。

## 核心功能

### 聊天与 Agent 能力
- 通过 SSE 流式输出，令牌实时出现。
- 支持多 Provider 模型，动态模型下拉框来自已配置的密钥。
- 消息处理中可继续发送，自动排队。
- 可编辑任意历史用户消息并从该处重新生成，可一键重试最后一条回复。
- 工具调用卡片、子 Agent 委派卡片、Mermaid 图表、思考/推理展示、危险命令审批卡。
- SSE 断线自动重连，适合 SSH 隧道场景。
- 附件的上下文指示、令牌数、成本与填充条展示。

### 会话管理
- 创建、重命名、复制、删除、搜索会话；支持置顶、归档、项目分组、标签。
- 按今天/昨天/更早分组；可导出 Markdown 或 JSON、从 JSON 导入。
- 可生成公开只读分享链接。
- CLI 会话桥：可从 Hermes Agent 的 SQLite 存储中导入 CLI 会话。

### 工作区文件浏览器
- 目录树、面包屑、文本/Markdown/图片内联预览。
- 支持 `workspace://path/to/file` 链接。
- 文件新建、编辑、删除、重命名、二进制下载。
- Git 检测：显示分支名与脏文件数。

### 语音输入
- 使用 Web Speech API 录音、实时中间转写、静音自动停止。
- 浏览器不支持时自动隐藏。

### Profile 与设置
- Profile 创建、切换、删除；可从当前 Profile 克隆配置。
- 可指定本地端点 Base URL 与 API key 写入 Profile 的 `config.yaml`。
- 切 Profile 无需重启服务。

### 安全
- 可选密码认证，默认关闭；支持 Passkey/WebAuthn 与 OIDC。
- 签名 HMAC HTTP-only Cookie，24 小时 TTL。
- 安全响应头、20MB POST 上限、CDN 资源 SRI hash。

### 主题与移动端
- 主题轴为 system/dark/light，Skin 轴包含多个皮肤。
- 移动端有汉堡侧栏、滑出文件面板、44px 最小触控目标，桌面布局不变。

## 适用与不适用场景

### 适用场景
- 已经或打算使用 Hermes Agent 的用户。
- 自托管、重视数据与对话留在自己服务器上的场景。
- 需要通过浏览器或手机远程使用 Agent，且可接受 SSH 隧道或 Tailscale。
- 需要持久记忆、自托管 cron、跨会话技能、多消息平台接入的 Agent 工作流。
- 熟悉 Python 生态并希望 Web 界面与 CLI 功能对齐的用户。

### 不适用场景
- 没有安装 Hermes Agent 的环境：WebUI 只是浏览器界面，运行时、记忆、配置、cron 与凭据属于 Hermes Agent。
- 官方 bootstrap 不支持原生 Windows：建议使用 Linux、macOS 或 WSL2；社区有原生 Windows 方案但非官方。
- 双容器 Docker 部署中，从 WebUI 触发的工具运行在 WebUI 容器而非 Agent 容器，git/node 等工具可能缺失。
- 需要 WebUI 与 Hermes Agent 版本严格独立混用的场景：当前二者仍按 Release 配对测试，混用版本不受支持。

## 技术架构与依赖

- 后端：Python 标准库 HTTP 服务器，无 Web 框架。入口为 `server.py`，逻辑位于 `api/`（auth、config、models、routes、streaming、workspace、onboarding、profiles 等）。
- 前端：`static/` 下的原生 HTML/CSS/JS，无框架、无打包器。主要模块包括 `ui.js`、`workspace.js`、`sessions.js`、`messages.js`、`panels.js`、`commands.js`、`boot.js`。
- 状态目录：默认在 `~/.hermes/webui/`（POSIX），可通过 `HERMES_WEBUI_STATE_DIR` 覆盖。
- 运行时依赖：直接导入 Hermes Agent 的 Python 模块，并读取 `HERMES_HOME` 配置；默认在进程内运行 Agent，不连接外部 Agent API 服务。
- 测试：约 11,500 个测试，覆盖约 1,150 个测试文件，CI 在 Python 3.11/3.12/3.13 上运行。
- Docker：提供单容器、双容器、三容器 Compose 文件，镜像基于 `python:3.12-slim`。
- Nix：提供 flake package 与 NixOS module。
- 仓库资料未提供完整的主依赖锁定清单；除 README 与文档中提到的内容外，更多依赖细节未给出。

## 安装与快速开始

### 本地启动

```bash
git clone https://github.com/nesquena/hermes-webui.git hermes-webui
cd hermes-webui
python3 bootstrap.py
```

也可以使用：

```bash
./start.sh
```

`bootstrap.py` 会检测 Hermes Agent，缺少时尝试运行官方安装脚本；创建或复用 Python 虚拟环境；启动 Web 服务并等待 `/health`；默认打开浏览器。

### 后台守护方式

```bash
./ctl.sh start
./ctl.sh status
./ctl.sh logs --lines 100
./ctl.sh restart
./ctl.sh stop
```

### Docker 快速开始

```bash
git clone https://github.com/nesquena/hermes-webui
cd hermes-webui
cp .env.docker.example .env
# 如宿主 UID 不是 1000（例如 macOS），编辑 .env
docker compose up -d
# 打开 http://localhost:8787
```

### Nix

```bash
nix shell github:nesquena/hermes-webui#default
```

### 手动启动

```bash
cd /path/to/hermes-agent
HERMES_WEBUI_PORT=8787 venv/bin/python /path/to/hermes-webui/server.py
```

健康检查：

```bash
curl http://127.0.0.1:8787/health
```

## 典型使用方法

1. 完成首次启动后，在浏览器打开 `http://127.0.0.1:8787`。
2. 首次运行会进入 onboarding 向导：选择 Provider、配置模型与工作区、可选设置密码。若向导提示去 CLI 完成，则运行 `hermes model` 后刷新 WebUI。
3. 在 composer 中开始对话；可使用 `/` 唤起斜杠命令，例如 `/help`、`/clear`、`/model`、`/workspace`、`/usage`、`/theme`。
4. 在右侧工作区浏览文件，通过 `workspace://` 链接在聊天中引用文件。
5. 使用 Hermes Control Center 管理会话、任务（cron）、技能、记忆、Profile 与设置。
6. 远程访问：默认只绑定 `127.0.0.1`，可用 `ssh -N -L 8787:127.0.0.1:8787 user@host` 建隧道；或配合 Tailscale 并将 `HERMES_WEBUI_HOST=0.0.0.0` 与 `HERMES_WEBUI_PASSWORD` 一起设置。
7. Docker 多容器部署时，如需 cron 定时执行，需要同时运行 Hermes Gateway 守护进程，否则任务不会自动 tick。

## 配置与部署要点

主要环境变量（来自 README）：

| 变量 | 默认值 | 说明 |
|---|---|---|
| `HERMES_WEBUI_AGENT_DIR` | 自动发现 | Hermes Agent 源码或已安装模块根路径 |
| `HERMES_WEBUI_PYTHON` | 自动发现 | Python 可执行文件 |
| `HERMES_WEBUI_HOST` | `127.0.0.1` | 绑定地址 |
| `HERMES_WEBUI_PORT` | `8787` | 服务端口 |
| `HERMES_WEBUI_STATE_DIR` | `$HERMES_HOME/webui` | 会话与状态存放位置 |
| `HERMES_WEBUI_DEFAULT_WORKSPACE` | `~/workspace` | 默认工作区 |
| `HERMES_WEBUI_PASSWORD` | 未设置 | 设置后启用密码认证 |
| `HERMES_HOME` | `~/.hermes` | Hermes 状态基础目录 |
| `HERMES_WEBUI_CSP_CONNECT_EXTRA` | 未设置 | 追加可信 connect-src 来源 |
| `HERMES_WEBUI_SSE_CHUNKED` | 未设置 | 反代缓冲场景下使用 chunked SSE |
| `HERMES_WEBUI_EXTENSION_DIR` 等 | 未设置 | 扩展注入相关配置 |

部署要点：

- WebUI 与 Hermes Agent 应视为 Release 配对，升级或固定版本时建议一起进行；版本错配不受支持。
- 远程暴露前必须启用密码认证；默认绑定 loopback。
- Docker 中 `localhost` 指向容器自身，访问宿主机服务应使用 `host.docker.internal`（Docker Desktop）或 `host.containers.internal`（Podman）等地址。
- Docker 需关注 UID/GID 匹配；推荐使用官方 Compose 中的命名卷以避免权限问题。
- 双容器/三容器部署中，Agent 源码通过 `hermes-agent-src` 卷共享；升级 Agent 镜像时需要删除该卷再重新创建。
- 默认聊天在 WebUI 进程内运行，`HERMES_API_URL` 只被 Tasks/cron 健康探测读取；如需外部端点的模型可作为自定义 OpenAI-compatible Provider 添加，或使用 Gateway 后端。
- 扩展机制会以完整 WebUI 会话权限执行脚本，只应启用可信来源的扩展。

## 限制、风险与许可证

- 许可证：仓库元数据显示为 MIT。仓库资料未提供除 MIT 之外的许可证或合规信息。
- 原生 Windows 未获官方 bootstrap 支持；社区方案存在已知限制，如 POSIX 风格路径、bash 假设工具可能不工作。
- WebUI 与 Hermes Agent 内部存在直接耦合（直接 import Agent 模块、读取状态布局），在稳定 API 边界工作完成前，升级不一致可能造成导入或行为漂移。
- 双容器 Docker 部署中，WebUI 触发工具运行在 WebUI 容器，不是 Agent 容器，这是架构性限制。
- 默认绑定 `127.0.0.1`，远程访问需要隧道或显式开放并配合认证。
- 扩展脚本具有完整会话权限，共享或多用户部署时应谨慎启用。
- 仓库资料未提供完整的已知漏洞清单、安全审计报告或供应链 SBOM 信息。

## 官方链接

- 仓库主页：https://github.com/nesquena/hermes-webui
- 最新 Release：https://github.com/nesquena/hermes-webui/releases/tag/v0.52.106
- Hermes Agent 官网：https://hermes-agent.nousresearch.com/
- 仓库内文档索引：README 中的 Docs 一节列有 `docs/why-hermes.md`、`docs/troubleshooting.md`、`docs/docker.md`、`docs/remote-access.md`、`docs/onboarding.md`、`ARCHITECTURE.md`、`CHANGELOG.md` 等。

## 信息来源和分析时间

本指南仅基于所提供仓库内容生成，包括仓库元数据（owner、name、description、language、license、topics、latestRelease）以及 README 和仓库内文档。分析所用数据快照中的最新 Release 为 v0.52.106，发布于 2026-07-29。分析时间：基于该数据快照，未进行实时网络验证；如仓库后续变更，请以官方仓库为准。