# hermes-ui

[Hermes Agent](https://github.com/NousResearch) 的自托管 Web 控制台 —— 聊天、会话历史、技能、
MCP 服务器、模型管理、IM 频道、文件管理、用量统计，都在一个浏览器界面里。

> 项目正在按阶段重建中，功能开发进度见 `docs/phases/README.md`。

## 前置条件

hermes-ui 以纯 Node.js 服务形式运行，**不捆绑任何运行时**。

- Node.js `>=23`
- 已安装 Python 与 `hermes-agent`

装好 `hermes-agent` 后，把 `hermes` 放进 `PATH`，或用 `HERMES_BIN` 指向可执行文件：

```bash
export HERMES_BIN=/path/to/hermes
```

找不到 CLI 时，界面会给出安装引导，而不是静默失败。

## 快速开始

```bash
npm ci --ignore-scripts
npm run build
npm start
```

然后打开 http://localhost:8648，用首次启动时打印的默认凭据登录。

开发模式（热重载）：

```bash
npm run dev
```

客户端跑在 http://localhost:8649，Koa 服务在 8647 端口。

## 目录结构

```
packages/client   Vue 3 客户端：视图、组件、Pinia store、i18n、API 封装
packages/server   Koa API、Socket.IO 聊天运行时、SQLite 存储、Hermes 对接
packages/skills   注入到 Hermes skills 目录的内置技能
tests             Vitest 单元/集成测试与 Playwright 浏览器测试
scripts           构建脚本与仓库 harness 脚本
docs              架构说明、harness 文档与分阶段施工计划
```

## Docker

```bash
docker compose up -d
```

镜像基于 `nousresearch/hermes-agent`，容器内已包含 Python 与 Hermes CLI。

## 配置项

| 变量 | 说明 |
| --- | --- |
| `HERMES_BIN` | `hermes` 可执行文件路径。默认回退到 `PATH` 中的 `hermes`。 |
| `HERMES_HOME` | Hermes profile 目录，用于隔离多身份。 |
| `HERMES_WEB_UI_HOME` | Web UI 状态目录，默认 `~/.hermes-web-ui`。 |
| `HERMES_WEBUI_STATE_DIR` | Web UI 状态目录的备用覆盖项。 |
| `PORT` | 服务端口。 |

`HERMES_WEB_UI_*` 前缀与 `~/.hermes-web-ui` 数据目录是从 0.6.x 刻意保留的，
这样已有部署脚本与数据目录不会失效。

## 命令

| 命令 | 说明 |
| --- | --- |
| `npm run dev` | 客户端与服务端热重载开发。 |
| `npm run build` | 类型检查并构建客户端与服务端产物。 |
| `npm start` | 以生产模式启动服务。 |
| `npm run test` | 运行 Vitest 测试。 |
| `npm run test:coverage` | 运行 Vitest 并产出覆盖率。 |
| `npm run test:e2e` | 运行 Playwright 浏览器测试。 |
| `npm run harness:check` | 校验仓库文档、workflow 与 package scripts。 |
| `npm run openapi:generate` | 重新生成 `docs/openapi.json`。 |

## 许可协议

BSL-1.1，见 `LICENSE`。