# Hermes Desktop

[Hermes Agent](https://github.com/NousResearch) 的 Electron 桌面应用，提供聊天、会话历史、
技能、MCP、模型管理、IM 频道、文件管理和用量统计。

## 快速开始

源码开发需要 Node.js `>=23`，并自行安装 Python 与 Hermes Agent。
桌面安装包内置 Electron/Node.js；Hermes 仍使用本机安装，通过 `HERMES_BIN` 或 PATH 查找。

```bash
npm ci --ignore-scripts
npm run electron:setup
npm run dev
```

生产运行与打包：

```bash
npm run build
npm start
npm run dist
```

安装包输出到 `release/`。请在目标系统打包：macOS 为 DMG/ZIP，Windows 为 NSIS EXE，
Linux 为 AppImage/DEB。开发模式提供 Vite 界面热更新，后端或主进程修改后需重新运行。
详细数据目录、迁移旧数据、原生模块和验证方式见 [Electron 说明](docs/electron.md)。

## 目录结构

```
electron          Electron 主进程、元数据 preload、本地服务入口
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` | 服务数据目录覆盖值。桌面默认 Electron `userData/state`，Web 模式默认 `~/.hermes-web-ui`。 |
| `HERMES_WEBUI_STATE_DIR` | Web UI 状态目录的备用覆盖项。 |
| `PORT` | 服务端口。 |

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

## 命令

| 命令 | 说明 |
| --- | --- |
| `npm run dev` | 启动 Electron 与 Vite 界面热更新。 |
| `npm run dev:web` | 独立 Web 开发模式。 |
| `npm run electron:setup` | 下载 Electron 并重建原生模块。 |
| `npm run pack` / `npm run dist` | 应用目录 / 安装包。 |
| `npm run test:electron` | 真实 Electron 启动退出验证。 |
| `npm run build` | 类型检查并构建界面、服务端和 Electron 入口产物。 |
| `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`。