GitHub - nesquena/hermes-webui: Hermes WebUI：从网页或手机使用 Hermes Agent 的最佳方式！· GitHub

Hermes Web UI

Hermes Agent 是一款部署在你服务器上的复杂自主 Agent，可通过终端或即时通讯应用访问，能够记住所学内容，运行时间越长能力越强。

Hermes WebUI 是一款轻量级深色主题 Web 应用，在浏览器中为 Hermes Agent 提供交互界面。与 CLI 体验完全一致——凡是能在终端完成的操作，都可以在这个界面中完成。无需构建步骤，无需框架，无需打包工具。仅依赖 Python 和原生 JS。

布局为三栏式：左侧边栏用于会话导航，中间为聊天区，右侧为工作区文件浏览器。模型、配置文件及工作区控件位于编辑器底栏——在编辑消息时始终可见。圆形上下文环一目了然地显示 Token 用量。所有设置和会话工具均在 Hermes 控制中心（启动入口位于侧边栏底部）。

| 亮色模式，完整配置文件支持 | 自定义设置，配置访问密码 |

| 工作区文件浏览器与内联预览 | 会话项目、标签及工具调用卡片 |

这让你能够通过便捷的 Web UI 以近乎 1:1 的方式使用 Hermes CLI，并可通过 SSH 隧道从你的 Hermes 部署环境安全访问。一条命令启动服务，一条命令建立 SSH 隧道，即可在本机访问。Web UI 的每一个功能均使用你现有的 Hermes Agent 和已有模型，无需任何额外配置。

目录

• 为何选择 Hermes——它是什么，与同类产品的对比
• 快速上手——克隆 + bootstrap.py / start.sh / ctl.sh
• 功能——聊天、会话、工作区、语音、配置文件、安全、主题、面板、移动端
• 配置与访问——自动发现、覆盖配置、远程/Tailscale/手机访问、手动启动
• Docker——单容器与多容器部署
• 运行测试
• 架构——后端/前端布局、状态目录
• 文档——完整文档索引
• 贡献者

为何选择 Hermes

大多数 AI 工具每次会话都会重置。它们不知道你是谁、你做过什么，也不了解你项目的规范。你每次都要重新解释自己的情况。

Hermes 可以跨会话保留上下文，在你离线时运行定时任务，并随着运行时间的增长对你的环境越来越熟悉。它使用你现有的 Hermes Agent 配置和已有模型，无需任何额外配置即可启动。

它与其他 Agent 工具的不同之处：

• 持久记忆 — 包括用户画像、Agent 笔记，以及可保存可复用流程的技能系统；Hermes 会学习你的环境，无需反复重学
• 自托管调度 — 可在你离线时触发的 cron 任务，并将结果推送至 Telegram、Discord、Slack、Signal、邮件等平台
• 支持 10+ 即时通讯平台 — 与终端相同的 Agent，可从手机直接访问
• 自我进化的技能 — Hermes 能从经验中自动编写并保存技能；无需浏览市场，无需安装插件
• Provider 无关 — 支持 OpenAI、Anthropic、Google、DeepSeek、OpenRouter 等
• 可编排其他 Agent — 能够为繁重的编程任务调用 Claude Code 或 Codex，并将结果回写至自身记忆
• 完全自托管 — 你的对话，你的记忆，你的硬件

与同类产品对比（竞品格局仍在快速演变——完整分析见 docs/why-hermes.md）：

| | OpenClaw | Claude Code | Codex CLI | OpenCode | Hermes |

| 持久记忆（自动） | 是 | 部分支持† | 部分支持 | 部分支持 | 是 |

| 定时任务（自托管） | 是 | 否‡ | 否 | 否 | 是 |

| 即时通讯访问 | 是（15+ 平台） | 部分支持（Telegram/Discord 预览版） | 否 | 否 | 是（10+） |

| Web UI（自托管） | 仅 Dashboard | 否 | 否 | 是 | 是 |

| 自我进化技能 | 部分支持 | 否 | 否 | 否 | 是 |

| Python / ML 生态 | 否（Node.js） | 否 | 否 | 否 | 是 |

| Provider 无关 | 是 | 否（仅 Claude） | 是 | 是 | 是 |

| 开源 | 是（MIT） | 否 | 是 | 是 | 是 |

† Claude Code 提供 CLAUDE.md / MEMORY.md 项目上下文及滚动式自动记忆，但不支持完整的跨会话自动回溯 ‡ Claude Code 提供云端托管调度（Anthropic 基础设施）及会话级 /loop；不支持自托管 cron

最接近的竞品是 OpenClaw——两者均为常驻运行、自托管、开源的 Agent，都具备记忆、cron 和即时通讯能力。主要区别在于：Hermes 将自动编写并保存技能作为核心行为（OpenClaw 的技能系统以社区市场为核心）；Hermes 在版本更新中更为稳定（OpenClaw 有记录在案的版本回退问题，ClawHub 也曾发生涉及恶意技能的安全事件）；且 Hermes 原生运行于 Python 生态。完整对比详见 docs/why-hermes.md。

快速上手

运行仓库引导脚本：

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

或继续使用 Shell 启动器：

./start.sh

对于自托管虚拟机或家庭实验室安装，ctl.sh 封装了常用的守护进程生命周期命令，无需依赖 fuser 或 pkill：

./ctl.sh start # background daemon, PID at ~/.hermes/webui.pid ./ctl.sh status # PID, uptime, bound host/port, log path, /health ./ctl.sh logs --lines 100 # tail ~/.hermes/webui.log ./ctl.sh restart ./ctl.sh stop

ctl.sh start 会在守护进程封装下以前台/无浏览器模式运行引导脚本，将日志写入 ~/.hermes/webui.log，并遵守 .env 配置及行内覆盖参数（如 HERMES_WEBUI_HOST=0.0.0.0 ./ctl.sh start）。

进阶：动态回忆预填充与 Gateway 驱动的聊天

两项可选的自托管部署功能——为浏览器对话绑定动态会话回忆预填充（支持 Joplin/Obsidian/Notion/llm-wiki 路由），以及将浏览器聊天通过运行中的 Hermes Gateway 转发——已记录在 docs/advanced-chat-setup.md 中。大多数用户无需使用这两项功能。

引导脚本将执行以下操作：

• 检测 Hermes Agent；若未安装，则尝试运行官方安装程序（curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash）。
• 查找或创建包含 WebUI 依赖的 Python 环境。
• 启动 Web 服务器并等待 /health。
• 除非传入 --no-browser 参数，否则自动打开浏览器。
• 在 WebUI 内引导你进入首次运行向导。

此引导脚本暂不支持原生 Windows。请使用 Linux、macOS 或 WSL2。有关 Windows / WSL 登录自动启动的配置，请参阅 docs/wsl-autostart.md。

社区维护的原生 Windows 安装指南见 @markwang2658/hermes-windows-native-guide（配套安装仓库：@markwang2658/hermes-windows-native）。来自社区的反馈汇总于 #1952：

• 内存占用： 社区实测原生约 330 MB，WSL2+Docker 约 1080 MB（因配置而异）。
• 可用功能： 聊天、工作区浏览器、会话管理、所有主题。
• 已知限制： 工作区浏览器中部分 POSIX 风格文件路径会显示异常；依赖 bash 的 Agent 工具可能无法在原生环境下正常运行。
• 原生 Windows 安装： 安装 Python 3.11+，然后在 hermes-agent 根目录下于 PowerShell 中依次执行：python -m venv venv → pip install -r requirements.txt → pwsh .\start.ps1（会自动发现 venv\Scripts\python.exe）。
• 与 WSL2 的关系： WSL2 并非前提条件——WSL2 构建的 venv（venv/bin/python，ELF 格式）无法被原生 Windows Python 调用，请使用上述原生安装方式。若你希望拥有完整的 bootstrap.py + Linux 运行时，WSL2 可作为并行安装环境单独使用。

如果安装完成后 provider 配置仍不完整，首次运行向导会引导你使用 hermes model 完成配置，而不是尝试在浏览器内复现完整的 CLI 配置流程。有关向导的分步说明、provider 选择、本地模型服务器 Base URL 配置及安全重复运行，请参阅 docs/onboarding.md。如果有 AI 助手协助安装、重装、引导、provider 配置或首次运行支持，请让它在执行命令或检查日志前先阅读 docs/onboarding-agent-checklist.md。

功能

聊天与 Agent

• 通过 SSE 实现流式响应（Token 生成即时显示）
• 多 Provider 模型支持——支持所有 Hermes API Provider（OpenAI、Anthropic、Google、DeepSeek、Nous Portal、OpenRouter、MiniMax、小米 MiMo、Z.AI）；模型下拉列表根据已配置的密钥动态生成
• 支持在消息处理过程中发送新消息——自动进入队列
• 可内联编辑任意历史用户消息并从该位置重新生成
• 一键重试上一条 Assistant 回复
• 可直接在编辑器底栏取消正在运行的任务（Send 按钮旁的 Stop 按钮）
• 内联工具调用卡片——每张卡片显示工具名称、参数及结果摘要；多工具对话支持全部展开/折叠切换
• 子 Agent 委托卡片——子 Agent 活动以独特图标和缩进边框显示
• 内联 Mermaid 图表渲染（流程图、时序图、甘特图）
• 思考/推理展示——用于 Claude 扩展思考和 o3 推理块的可折叠金色主题卡片
• 危险 Shell 命令审批卡片（允许一次 / 本次会话 / 始终允许 / 拒绝）
• 网络中断后 SSE 自动重连（SSH 隧道断线恢复）
• 文件附件在页面刷新后保持，默认存储在活动工作区之外（~/.hermes/webui/attachments/ /，或配置后使用 HERMES_WEBUI_ATTACHMENT_DIR/ /）
• 消息时间戳（每条消息旁显示 HH:MM，悬停显示完整日期）
• 代码块复制按钮，带"Copied!"反馈提示
• 通过 Prism.js 实现语法高亮（支持 Python、JS、bash、JSON、SQL 等）
• AI 响应中的安全 HTML 渲染（粗体、斜体、代码转换为 markdown）
• rAF 节流的 token 流式输出，使长响应渲染更流畅
• 编辑器底部的上下文用量指示器——token 计数、费用及填充进度条（感知模型）

Sessions

• 创建、重命名、复制、删除，按标题和消息内容搜索
• 每个 session 通过 ⋯ 下拉菜单执行操作——置顶、移入项目、归档、复制、删除
• 将 session 固定/加星标至侧边栏顶部（金色标识）
• 归档 session（隐藏而不删除，可切换显示）
• Session 项目——带颜色的命名分组，用于整理 session
• Session 标签——在标题中添加 #tag，生成带颜色的标签芯片，点击可筛选
• 在侧边栏按今天 / 昨天 / 更早分组（日期分组可折叠）
• 支持下载为 Markdown 记录、完整 JSON 导出或从 JSON 导入
• Session 在页面刷新和 SSH 隧道重连后持久保留
• 浏览器标签页标题反映当前活动 session 名称
• CLI session 桥接——来自 hermes-agent 的 SQLite 存储中的 CLI session 会显示在侧边栏，带有金色"cli"徽章；点击即可导入完整历史记录并正常回复
• Token/费用显示——每个对话显示输入 token 数、输出 token 数和预估费用（可在设置中或通过 /usage 命令切换）

Workspace 文件浏览器

• 目录树，支持展开/折叠（单击切换，双击导航）
• 面包屑导航，路径片段可点击
• 内联预览文本、代码、Markdown（渲染后）及图片
• 使用 workspace://path/to/file 的聊天链接可在右侧预览面板中打开文件
• 编辑、创建、删除和重命名文件；创建文件夹
• 二进制文件下载（服务端自动检测）
• 目录导航时文件预览自动关闭（带未保存编辑守卫）
• Git 检测——workspace 标题栏显示分支名称和脏文件计数徽章
• 右侧面板支持拖拽调整宽度
• 代码预览带语法高亮（Prism.js）

语音输入

• 编辑器中的麦克风按钮（Web Speech API）
• 点击开始录音，再次点击或发送以停止
• 实时中间转录结果显示在文本框中
• 静音约 2 秒后自动停止
• 追加到现有文本框内容（不会替换）
• 浏览器不支持 Web Speech API 时隐藏（Chrome、Edge、Safari 支持）

Profiles

• 编辑器底部的 Profile 芯片——下拉菜单显示所有 profile，含 gateway 状态和模型信息
• Gateway 状态点（绿色 = 运行中）、模型信息、每个 profile 的 skill 数量
• Profiles 管理面板——从侧边栏创建、切换和删除 profile
• 创建时从当前活动 profile 克隆配置
• 创建时可填写可选的自定义端点字段——Base URL 和 API key 在创建时写入 profile 的 config.yaml，无需手动编辑文件即可配置 Ollama、LMStudio 及其他本地端点
• 无缝切换——无需重启服务器；重新加载配置、skill、memory、cron、模型
• 每个 session 记录 profile（记录创建时活动的 profile）

认证与安全

• 可选密码认证——默认关闭，localhost 使用零摩擦
• 通过 HERMES_WEBUI_PASSWORD 环境变量或设置面板启用
• 可选 passkeys/WebAuthn——用密码登录后在设置 -> 系统中注册；至少注册一个 passkey 后，登录页面才会显示 passkey 登录选项
• 注册至少一个 passkey 后，设置 -> 系统可移除密码并保持仅 passkey 登录。密码认证在你选择去密码化之前始终作为引导/恢复路径；passkey 为同源存储，保存在 WebUI 状态目录的本地
• 已签名的 HMAC HTTP-only cookie，TTL 24 小时
• 极简暗色主题登录页，位于 /login
• 所有响应均附带安全头（X-Content-Type-Options、X-Frame-Options、Referrer-Policy）
• POST 请求体大小限制 20MB
• CDN 资源使用 SRI 完整性哈希固定版本

主题

• 外观分为两个维度：Theme（system、dark、light）和 Skin（default、ares、mono、slate、poseidon、sisyphus、charizard、sienna、catppuccin、nous、geist-contrast / Geist Contrast）
• 通过设置 -> 外观切换（即时实时预览）或使用 /theme
• 跨页面刷新持久保留（服务端存储于 settings.json + localStorage 实现无闪烁加载）
• Skin 使用 data-skin 加 CSS 变量；暗色模式通过 .dark class 解析，而非 data-theme 自定义主题轴——详见 THEMES.md

设置与配置

• Hermes 控制中心（侧边栏启动按钮）——对话标签（导出/导入/清除）、偏好设置标签（模型、发送键、主题、语言、所有开关）、系统标签（版本、密码）
• 发送键：Enter（默认）或 Ctrl/Cmd+Enter
• 显示/隐藏 CLI session 开关（默认启用）
• Token 用量显示开关（默认关闭，也可通过 /usage 命令切换）
• 控制中心始终在对话标签打开；关闭时重置
• 未保存更改守卫——关闭时有未持久化更改则弹出放弃/保存提示
• Cron 完成提醒——Toast 通知及任务标签上的未读徽章
• 后台 Agent 错误提醒——非活动 session 遇到错误时显示横幅

斜杠命令

• 在编辑器中输入 / 即可弹出自动补全下拉菜单
• 内置命令：/help、/clear、/compress [focus topic]、/compact（别名）、/model 、/workspace 、/new、/usage、/theme
• 方向键导航，Tab/Enter 选择，Escape 关闭
• 未识别的命令直接传递给 Agent

面板

• Chat——session 列表、搜索、置顶、归档、项目、新建对话
• Tasks——查看、创建、编辑、运行、暂停/恢复、删除 cron 任务；运行历史；完成提醒
• Skills——按分类列出所有 skill，搜索、预览、创建/编辑/删除；关联文件查看器
• Memory——内联查看和编辑 MEMORY.md 与 USER.md
• Profiles——创建、切换、删除 Agent profile；克隆配置
• Todos——当前 session 的实时任务列表
• Spaces——添加、重命名、移除 workspace；从顶部栏快速切换

移动端响应式

• 汉堡菜单侧边栏——移动端（<640px）滑入覆盖层
• 侧边栏顶部标签在移动端保持可用；无固定底部导航占用聊天高度
• 文件侧滑面板从右侧边缘弹出
• 所有交互元素触控目标最小 44px
• 手机上全高聊天/编辑器，无底部导航间距
• 桌面布局完全不变

配置与访问

start.sh 几乎可以自动检测所有配置；以下子节介绍在无法自动检测时的调节选项，以及如何远程访问 UI。

start.sh 自动发现的内容

| 内容 | 发现方式 |

| Hermes agent 目录 | HERMES_WEBUI_AGENT_DIR 环境变量，其次 HERMES_HOME/webui（Windows 默认 %LOCALAPPDATA%\hermes\webui，POSIX 默认 ~/.hermes/webui） |

| 默认 workspace | HERMES_WEBUI_DEFAULT_WORKSPACE 环境变量，其次 ~/workspace，再次状态目录 |

| 端口 | HERMES_WEBUI_PORT 环境变量或第一个参数，默认 8787 |

若自动发现找到所有内容，则无需任何额外配置。

覆盖配置（仅在自动检测失败时需要）

export HERMES_WEBUI_AGENT_DIR=/path/to/hermes-agent export HERMES_WEBUI_PYTHON=/path/to/python export HERMES_WEBUI_PORT=9000 export HERMES_WEBUI_AUTO_INSTALL=1 # enable auto-install of agent deps (disabled by default) ./start.sh

或内联方式：

HERMES_WEBUI_AGENT_DIR=/custom/path ./start.sh 9000

环境变量完整列表：

| 变量 | 默认值 | 描述 |

| HERMES_WEBUI_AGENT_DIR | 自动发现 | hermes-agent 检出路径 |

| HERMES_WEBUI_PYTHON | 自动发现 | Python 可执行文件 |

| HERMES_WEBUI_HOST | 127.0.0.1 | 绑定地址（0.0.0.0 表示所有 IPv4，:: 表示所有 IPv6，::1 表示 IPv6 回环） |

| HERMES_WEBUI_PORT | 8787 | 端口 |

| HERMES_WEBUI_STATE_DIR | HERMES_HOME/config.yaml | Hermes 配置文件路径 |

远程访问（SSH 隧道、Tailscale、手机）

服务器默认绑定至 127.0.0.1。要从其他机器访问，可使用 SSH 隧道（ssh -N -L 8787:127.0.0.1:8787 user@host，start.sh 会在 SSH 连接时自动为你打印该命令），或将服务器和手机加入 Tailscale 网络，配置 HERMES_WEBUI_HOST=0.0.0.0 + HERMES_WEBUI_PASSWORD 后访问 http:// :8787。完整教程（含社区 ARM64-Android 实测报告）：docs/remote-access.md。

手动启动（不使用 start.sh）

如需直接启动服务器：

cd /path/to/hermes-agent # or wherever sys.path can find Hermes modules HERMES_WEBUI_PORT=8787 venv/bin/python /path/to/hermes-webui/server.py

注意：请使用 Agent venv 的 Python（或任何已安装 Hermes agent 依赖的 Python 环境）。系统 Python 将缺少 openai、httpx 及其他必需包。

健康检查：

curl http://127.0.0.1:8787/health

Docker

预构建镜像（amd64 + arm64）在每次发布时推送至 GHCR。

涵盖全部 3 个 compose 文件、常见故障模式及绑定挂载迁移的完整配置指南，请参阅 docs/docker.md。README 仅涵盖 5 分钟快速上手路径。

5 分钟快速上手（单容器）

最简配置：一个在进程内运行 Agent 的 WebUI 容器。

git clone https://github.com/nesquena/hermes-webui cd hermes-webui cp .env.docker.example .env # Edit .env if your host UID isn't 1000 (e.g. macOS where UIDs start at 501) docker compose up -d # Open http://localhost:8787

请以拥有 Hermes home 目录的用户身份运行 Compose。sudo docker compose up -d 可能导致 ( id -u ) -e WANTED_GID= ( id -u ) -e WANTED_GID= (id -u)

更深入的逐项说明，请参阅 docs/docker.md。

注意： 默认情况下，Docker Compose 绑定到 127.0.0.1（仅限本地访问）。如需在网络上对外暴露，请在 docker-compose.yml 中将端口改为 "8787:8787"，并设置 HERMES_WEBUI_PASSWORD 以启用身份验证。

运行测试

测试会动态发现代码仓库和 Hermes Agent，无需硬编码路径。

cd hermes-webui pytest tests/ -v --timeout=60

或者显式使用 Agent venv：

/path/to/hermes-agent/venv/bin/python -m pytest tests/ -v

测试在使用独立状态目录的隔离服务器上运行，不会触碰生产数据和真实的 cron 任务。当前快照：跨 ~700 个测试文件共收集约 7,150 个测试，在 CI 中以 Python 3.11、3.12 和 3.13 运行（各 3 个并行分片）。

架构

无构建步骤，无框架，无打包工具——基于 Python 标准库 HTTP 服务器和原生 JS。后端位于 api/，前端位于 static/。

后端（api/）

server.py HTTP routing shell + auth middleware api/ auth.py Optional password authentication, signed cookies, passkeys config.py Discovery, globals, model detection, reloadable config helpers.py HTTP helpers, security headers models.py Session model + CRUD + CLI/state.db bridge onboarding.py First-run onboarding wizard, OAuth provider support profiles.py Profile state management, hermes_cli wrapper routes.py All GET + POST route handlers (if/elif dispatch, no decorators) state_sync.py /insights sync — message_count to state.db streaming.py SSE engine, run_agent, cancellation, compression updates.py Self-update check and release notes upload.py Multipart parser, file upload handler workspace.py File ops, workspace helpers, git detection

前端（static/）

index.html HTML template style.css All CSS incl. mobile responsive, themes + skins ui.js DOM helpers, renderMd, tool cards, context indicator workspace.js File preview, file ops, git badge, central api() fetch wrapper sessions.js Session CRUD, collapsible groups, search, reload recovery messages.js send(), SSE handlers, live streaming, session recovery panels.js Cron, skills, memory, profiles, settings (Control Center) commands.js Slash command autocomplete boot.js Mobile nav, voice input, theme/skin boot, bfcache handler

测试与打包

tests/ Pytest suite (~7,150 tests; isolated server/state fixtures) pyproject.toml Tooling config (ruff lint gate) — not a packaged distribution Dockerfile python:3.12-slim container image docker-compose.yml Compose with named volume and optional auth .github/workflows/ CI: ruff + sharded pytest, browser smoke, Docker smoke, multi-arch Docker build + GitHub Release on tag

状态默认存储在仓库之外的 ~/.hermes/webui/（包含会话、工作区、设置、项目、last_workspace）。可通过 HERMES_WEBUI_STATE_DIR 覆盖。完整的设计说明和端点目录详见 ARCHITECTURE.md。

文档

从这里开始

• docs/why-hermes.md — Hermes 的设计理念、思维模型，以及与 Claude Code / Codex / OpenCode / Cursor 的详细对比
• docs/onboarding.md — 首次运行向导、provider 配置、本地模型服务器 Base URL，以及安全重复运行说明
• docs/troubleshooting.md — 常见故障（如"AIAgent 不可用"）的诊断流程

使用与定制

• THEMES.md — 主题与皮肤系统、自定义主题指南
• docs/workspace-git.md — 工作区 Git 控件
• docs/EXTENSIONS.md — 管理员控制的 WebUI 扩展注入

部署与运维

• docs/remote-access.md — SSH 隧道、Tailscale 及手机访问（含社区 ARM64-Android 实测报告）
• docs/advanced-chat-setup.md — 可选的动态召回预填充，以及面向自托管部署的 Gateway 浏览器聊天
• docs/docker.md — Docker compose 配置、常见故障及绑定挂载迁移
• docs/supervisor.md — launchd、systemd、supervisord、runit 和 s6 进程管理器配置
• docs/wsl-autostart.md — WSL2 在 Windows 登录时自动启动
• docs/onboarding-agent-checklist.md — 助手引导安装/重装支持的安全规则与通过/失败检查项

贡献与设计

• CONTRIBUTING.md — 贡献风格、PR 规范及本地验证
• ARCHITECTURE.md — 系统设计、所有 API 端点、实现说明
• TESTING.md — 手动浏览器测试计划与自动化覆盖参考
• DESIGN.md — 设计令牌（design tokens）与平静控制台（calm-console）方向
• docs/UIUX-GUIDE.md — 源自设计文档和视觉清单的 UI/UX 原则
• docs/CONTRACTS.md — 面向贡献者和 Agent 的项目合同/RFC/设计索引
• docs/rfcs/README.md — 针对较大架构和耐久性提案的 RFC 索引

发布历史与计划

• CHANGELOG.md — 各版本发布说明
• ROADMAP.md — 功能路线图与迭代历史
• SPRINTS.md — 前瞻性迭代计划，含 CLI + Claude 功能对齐目标
• CONTRIBUTORS.md — 完整的社区贡献荣誉榜

贡献者

Hermes WebUI 的建设离不开开源社区的帮助。每一个 PR——无论是直接合并、纳入批量发布，还是从较大提案中提炼而来——都塑造了这个项目，我们对所有抽出时间做出贡献的人深表感谢。

超过 190 位贡献者的代码已随版本标签正式发布。完整且持续更新的荣誉榜——包括每位提交过一两个 PR 的贡献者，以及设计与架构工作的特别致谢名单——收录于 CONTRIBUTORS.md。以下为贡献最多的贡献者快照：

顶级贡献者（按 PR 数量排名，含已吸收/批量发布的工作）

完整的全部 194 位贡献者排名列表，包括每位提交过一两个 PR 的贡献者以及设计与架构贡献的特别致谢名单，请参阅 CONTRIBUTORS.md。

突出贡献

@franksong2702 — 最多产的外部贡献者（148 个 PR，v0.49.3 → v0.51.153）任期为所有外部贡献者中最长：会话标题保护（#301）、面包屑工作区导航（#302）、嵌入式工作区终端（#1099）、基于 worktree 的会话创建（#2053）、入门文档（#2052）、composer 底部栏容器查询、流式会话侧边栏豁免（#1327）、会话 sidecar 修复、cron 输出保留（#1295）、配置文件默认工作区持久化、手动 /compress 异步启动/状态端点（#2128）、worktree 状态展示（#2109）+ 生命周期保护移除（#2156，属于 #2057 生命周期总体工作）、会话后渲染去重（#2166）、原生 WebUI 快速路径（#2170）、尾部窗口响应裁剪（#2171）、陈旧流守护扩展（#2158）、CSP 上报收集器（#2160），以及移动端/响应式布局、会话侧边栏和工作区状态机等方面大量细节打磨。

@Michaelyklam — 近期版本中贡献最多的贡献者（117 个 PR，v0.50.240 → v0.51.139）生产环境 Docker 加固（#1921，移除了具有 sudo 能力的暂存用户）、配置文件作用域 skills 端点（#1903）、配置文件作用域 HERMES_HOME 下的 Gateway PID 解析（#1901）、配置文件感知的 AIAgent 缓存（#1898/#1904）、反斜杠 LaTeX 分隔符（#1848）、Codex 配额错误展示（#1770）、shell 路由 HTML 503（#1836）、陈旧 Kanban 客户端恢复（#1828）、上下文自动压缩 toast 展示时长（#1988）、/goal 命令（#1866）、Kanban 详情视图滚动（#1916）、CLI 会话工具元数据保留（#1778）、繁体中文 Kanban 本地化补全（#1979）、v0.51.51 移动端 Insights 分桶/布局（#2120/#2121）、Hermes 运行适配器 RFC（#2105，对应 #1925）、fork-from-here 绝对索引（#2198，对应 #2184）、opencode-go 自定义 provider 重叠路由（#2204，对应 #1894）。

@bergeouss — Provider 管理 UI + Docker 加固（70 个 PR，v0.48.0 → v0.51.46）在设置页面中添加/编辑自定义 provider 的 Provider 管理 UI、OAuth provider 状态检测（#1552）、双容器 Docker 配置、配置文件隔离加固（每个配置文件独立的 .env 密钥）、用户在设置 → Providers 中所见内容的大部分实现、在 Finder 中显示上下文菜单（#1551）、Gateway 状态卡片（#1552）、自动将会话分配到活跃项目过滤器（#1550）、更新横幅中的"最新动态？"链接（#1549）、OpenRouter 免费层实时获取（#1548）、凭证池 401 自愈（#1553）、模型选择器中的内联 provider 芯片 + 分组模型计数（#1644）。

@ai-ag2026 — 会话恢复 + 审计基础设施（67 个 PR，v0.50.279 → v0.51.190）自主 AI 贡献者（Hermes Agent 驱动），专注于耐久性：基于 state.db 的 sidecar 协调（#2041）、启动时孤立 .json.bak 恢复（#2035）、只读会话恢复审计端点（#2036、#2040）、/health 中的活跃运行生命周期（#2039）、docs/rfcs/turn-journal.md 处的崩溃安全 turn-journal RFC（#2042）、追加式 turn-journal 辅助器（#2059）、生命周期事件层（#2062）、Content-Security-Policy-Report-Only 请求头（#2084）、每个 cron 的 toast 开关（#2100）、fork 会话压缩血缘隔离（#2014）。

@dso2ng — 会话血缘 + 诊断（25 个 PR，v0.50.227 → v0.51.153）用于有界会话图诊断的 /api/session/lineage-report/ 端点（#2012）、陈旧 Mermaid 渲染错误清理（#1337）、session_source="fork" 续接链隔离（#2063）、侧边栏徽章展开时懒加载血缘报告（#2130），以及会话加载方面大量前端稳定性修复。

@jasonjcwu — Composer + 对话记录优化（16 个 PR，v0.50.227 → v0.51.132）通过点击活动轨道折叠侧边栏（#2054，融合 #1884 + #1924）、composer chip 灯箱（#1758）、工具密集型首轮对话的标题修复、会话切换时静默压缩状态（#2185）、并发发送丢失修复（#2186）、对话记录内引导消息徽章（#2187），以及一系列前端视觉优化修复。

@Jordan-SkyLF — 实时流式传输 + 用户体验优化（12 个 PR，v0.50.18 → v0.51.66）最初冲刺完成工作区回退解析、实时推理卡片（#366、#367、#394–#397），近期又密集提交：Provider 配额卡上的手动"刷新用量"按钮（#2150）、已取消轮次的状态分类（#2151）、Firefox 侧边栏滚动稳定性修复（#2200）、提前生成临时会话标题（#2202）、目标感知的"新功能"更新横幅链接（#2207），以及设置页面中 MCP 工具溢出修复（#2210）。

@aronprins — v0.50.0 UI 全面重构（PR #242，加上 9 个后续 PR）这是项目中迄今最大的单笔贡献：完整的 UI 重新设计——将模型/Profile/工作区控件移入 composer 底栏，用 Hermes Control Center（选项卡式弹窗）取代了齿轮图标设置面板，去掉活动栏改为内联 composer 状态显示，重新设计了带 ⋯ 操作下拉菜单的会话列表，并新增了工作区面板状态机。此外还包括聊天记录重新设计（#587）、侧边栏精简（#584）、三栏布局重构（#899）、浅色/深色主题 + 强调色皮肤（#627），以及从 #242 中提取的共享 confirm()/prompt() 对话框替换（PR #251）。

@iRonin — 安全加固冲刺（PR #196–#204）六个连续、专注的安全 PR：会话内存泄漏修复（过期 token 清理）、CSP + Permissions-Policy 响应头、30 秒慢客户端连接超时、通过环境变量支持可选 HTTPS/TLS、自更新的上游分支跟踪修复，以及文件浏览器 API 中的 CLI 会话支持。这种专注、高质量的安全工作，正是让自托管工具值得信赖的基石。

@lucasrc — 认证加固三部曲（PR #2191、#2192、#2193）三个协同配合的安全 PR，全部随 v0.51.57 发布：带 PBKDF2 密钥分离的线程安全登录频率限制器、设置保存时的密码哈希缓存失效处理，以及完整的 64 字符 HMAC-SHA256 会话签名（附带向后兼容的迁移桥接）。这种将安全工作拆分为三个独立可审查模块的方式，堪称范本。

@LumenYoung — 流式传输热路径正确性修复（8 个 PR，v0.51.47 → v0.51.99）原始的过期流回写保护（#2136——后续两个版本所扩展的 bug 类别）、gateway 状态 alive-null 分类（#2075）、压缩横幅锚点对齐（#2182），以及压缩完成时上下文进度环自动刷新（#2188）。每个 PR 都在代码库中最脆弱的子系统之一上进行了精准的外科手术式修复。

@dobby-d-elf — 前端可靠性 + 动效优化（15 个 PR，v0.51.38 → v0.51.161）已删除目录时的工作区回退（#2138）、iPhone PWA 底部滚动修复（#2143）、新增"Activity: X tools" composer 底栏闪光动画（#2203），以及后续的动画调优（#2212）。

@JKJameson — Composer + 会话优化（10 个 PR）每个会话的持久化 composer 草稿（#1956），以及 composer 和会话侧边栏的大量后续细节打磨。

@gabogabucho — 西班牙语本地化 + 新手引导向导覆盖所有 UI 字符串的完整西班牙语（es）本地化，以及首次启动时引导新用户完成 provider 设置的一键式启动引导向导。

@deboste — 反向代理认证 + 移动端响应式布局（PR #3、#4、#5）最早的三个社区 PR：修复 EventSource/fetch 以使用 URL origin 适配反向代理部署、修正 config 中模型 provider 的路由，并添加了带 dvh 视口修复的移动端响应式布局。早期的基础性工作。

@indigokarasu — 视觉重设计提案（PR #213）一次纯 CSS 的完整 UI 重设计——规范的设计 token、以图标轨道侧边栏取代 emoji 标签条、统一的表单卡片、面包屑导航，以及 7 套以自定义属性形式内置的主题。该 PR 未原样合并，但深刻影响了 v0.50.0 中正式落地的设计语言与主题架构。

@zenc-cp — ReAct 循环的反幻觉防护（PR #133）一种三层防护方案（临时反幻觉提示词、实时 token 过滤、会话历史清理），流式传输管道至今仍在使用。

@Hinotoi-agent — Profile + 会话安全（PR #351、#2048）Profile .env 密钥隔离修复（PR #351），防止 API key 在 Profile 之间泄露；以及会话导入工作区验证（PR #2048），阻止通过精心构造的 JSON 文件对 / 发起文件读取攻击。

@Sanjays2402 — 无限滚动 + Start-jump 竞争修复（PR #1949）通过生成 token + 互斥锁的组合，修复了 v0.51.30 中无限滚动预取与 Start-jump 的 _ensureAllMessagesLoaded 之间的竞态条件。朴素的同标志检查方案（在 #1942 和 #1962 中提出）对 await 之后的竞态是无效的——Sanjays2402 的修复才是正确的解法。

@fxd-jason — 通过 SSE 实现实时审批 + 澄清（PR #1350、#1355）将 1.5 秒的 HTTP 轮询替换为 SSE 长连接，同时用于审批和澄清流程，将延迟从最高 1.5 秒降至近乎即时。所有正确性细节均处理到位（原子订阅 + 快照、锁内通知、队首载荷、尾部事件重新发送）。

@happy5318 — 自定义 provider 模型去重（PR #1947）修复了来自不同自定义 provider 的同名模型在选择器中被静默去重的问题，其中 Opus 还发现了原始测试中的一个需要补充的竞态条件。

@NocGeek — 流式滚动 + 手动 cron 输出持久化（7 个 PR）工具/队列卡片插入时的流式滚动视口稳定性（#1360）、手动 cron 运行输出及元数据持久化（#1372，从搁置的 #1352 中拆分）。

@DavidSchuchert — 德语翻译（PR #190）覆盖所有 UI 字符串、设置标签、命令和系统消息的完整德语（de）本地化——并对 i18n 系统进行了压力测试，发现了若干尚未支持翻译的元素，并在同一 PR 中一并修复。

@Bobby9228 — 移动端 Profiles 按钮（PR #265）在移动端导航流中加入了 Profiles 入口，使手机用户也能切换 Profile。

@kevin-ho — OLED 主题（PR #168）第 7 套内置主题：纯黑背景配以暖色强调，专为降低烧屏风险而调校。

@andrewy-wizard — 中文本地化（PR #177）初始简体中文（zh）本地化，是最早加入的非英语语言之一。

@DelightRun — WebUI 会话的 session_search 修复（PR #356）追查到流式传输路径中缺失的 SessionDB 注入问题，该问题曾静默地导致每个 WebUI 会话的相关功能异常。

@lawrencel1ng — Bandit 安全修复（PR #354）系统性的 bandit 扫描修复：urlopen 前的 URL scheme 验证、MD5 usedforsecurity=False，以及 40 余处裸 except: pass 块替换为规范的日志记录。

@shaoxianbilly — Unicode 文件名下载（PR #378）规范的 Content-Disposition 配合 RFC 5987 filename*=UTF-8''... 编码，确保非 ASCII 文件名下载时不会崩溃。

@lx3133584 — 反向代理的 CSRF 修复（PR #360）修复了一个在非 80/443 端口通过 Nginx Proxy Manager 等工具托管时的真实阻断性问题。

@betamod — 安全审计（PR #171）一次覆盖 CSRF / SSRF / XSS / 环境变量竞态条件的全面审计，随 v0.39.0 发布。

@TaraTheStar — 机器人名称 + 思维块 + 登录页重构（PR #132、#176、#181）可配置的助手显示名称、思维/推理块展示，以及登录页面重构。

Repo

git@github.com:nesquena/hermes-webui.git