---
title: Hermes
emoji: 🐳
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false
---

# Hermes AI Application
20260504更新内容
### 2.1 Baoyu 技能系统（Baoyu Skills）
**什么是 Baoyu Skills？**
这是知名AI大神宝玉老师的一套开源的 AI 技能库，就像一本"AI 技能菜谱"，里面包含了各种预置的功能模块。
**使用的三个核心技能：**
#### 1. baoyu-imagine（AI 画画技能）
- **功能：** 根据文字描述生成图片
- **支持的后端：** Google Gemini、SiliconFlow、OpenAI 等
- **特点：** 可以设置图片尺寸、质量、比例等参数
#### 2. baoyu-cover-image（封面图生成）
- **功能：** 自动为文章生成封面图
- **特点：** 可以设置风格、配色、字体等
#### 3. baoyu-article-illustrator（文章配图生成）
- **功能：** 为长篇文章自动生成插图
- **特点：** 根据文章内容智能匹配图片，支持批量生成
- **适用场景：** 公众号长文、博客文章、年度报告等需要大量配图的场景
### 2.2 数字卡兹克（Digital Kazik）—— 长文写作助手
"数字生命卡兹克"（Khazix-writer）是 **独立的开源 AI 技能**。它是一个**公众号长文写作 skill**，由另一位大神卡兹克（Khazix）个人开发。
**核心功能：**
当用户需要撰写公众号文章、写稿子、续写文章、根据素材产出长文时使用。
**触发词包括但不限于：**
写文章、写稿子、帮我写、续写、扩写、公众号文章、长文、出稿、按我的风格写
### 2.3 数据同步系统（Data Sync）
**为什么要数据同步？**
因为 Hugging Face Spaces 的容器重启后会丢失所有数据，就像电脑重启后内存里的东西会消失一样。
**工作原理（用邮局比喻）：**
1. **备份：** 每次有新的聊天记录、图片、配置，就打包寄到"邮局"（Hugging Face Dataset）
2. **恢复：** 容器重启后，从邮局取回之前的包裹，恢复所有数据
3. 注意SKIP_CONFIG_RESTORE 的作用是：
这是一个 "不恢复配置" 的开关。默认行为（不设置此变量）：
- Space 重启时，会从 Dataset 恢复 所有 之前保存的文件
- 包括 config.yaml、.env、以及各种配置
- 这会把你调试配置阶段手动修改的设置覆盖掉
设置 SKIP_CONFIG_RESTORE=true 后：
- 跳过恢复某些配置文件，比如 config.yaml和baoyu_skills/等等
- 但其他数据正常恢复： 聊天记录、图片、记忆、skills、会话历史等
- 容器重启后entrypoint.sh 会重新生成受保护的配置文件，比如 config.yaml 等。
建议如果没有修改配置的需求时或者配置稳定后使用设置SKIP_CONFIG_RESTORE=false，这样每次重启会从dataset中恢复所有备份。
### 2.4 图片浏览和下载服务
核心组件
image-proxy.js —— 一个 Node.js 代理服务器，部署在 Space 的 :7860 端口（对外暴露的端口）。
工作原理
用户访问 https://usernamename-spacename.hf.space/images/
           ↓
    image-proxy.js (端口 7860)
           ↓
    读取 /data/.hermes/image_cache/ 目录
           ↓
    返回 HTML 图片列表页面
功能特性
1. 图片列表页面（/images/）
- 自动扫描 image_cache 目录下的所有图片
- 生成美观的 HTML 页面展示所有图片
- 支持缩略图预览、下载链接、原始大小查看
2. 单图片访问（/images/<filename>）
- 直接访问单张图片，可用于嵌入到聊天或其他页面
- 支持常见的图片格式：png, jpg, jpeg, gif, webp
3. 代理功能
- 除了 /images/ 路径，其他所有请求都转发给 BFF（:7861）
- 这意味着 :7860 是统一入口，既提供图片服务，又提供 Web UI
特点：
1. 图片持久化：生成的图片保存在 /data/.hermes/image_cache/
2. Web 可访问：通过 /images/ URL 可以直接在浏览器查看
3. 方便分享：用户可以把图片 URL 分享给其他人
4. 统一管理：所有 AI 生成的图片集中在一个地方


4.26更新内容；

web UI 主要功能上手指南
现在你的 AI 助手已经部署好、微信也接通了，来看看 Web UI 还能做什么。
### 7.1 聊天（Chat）
点击左侧的 **Chat** 按钮，进入聊天界面。
- **新建对话**：点左上角的 **+ New Chat** 按钮
- **切换模型**：在聊天框上方的下拉菜单中切换不同的 AI 模型
- **搜索历史**：按 `Ctrl+K` 可以搜索所有历史对话
- **上传文件**：点击聊天框旁边的附件按钮，可以上传图片或文件让 AI 分析
- **下载文件**：AI 生成的文件可以在对话中直接下载
### 7.2 模型管理（Models）
点击左侧的 **Models** 按钮。
- 这里列出了你所有可用的 AI 模型供应商
- 点击任意供应商可以看到该供应商下有哪些模型
- 你可以添加新的供应商（支持任何 OpenAI 兼容的接口）
- **Nous Portal** 和 **OpenAI Codex** 还支持 OAuth 登录，直接在网页上点击授权就行
### 7.3 用量统计（Usage）
点击左侧的 **Usage** 按钮。
- 你可以看到 token 使用量的每日趋势图
- 每个模型的使用占比
- 估算的费用（基于公开的模型定价）
- 缓存命中率（缓存命中越多，速度越快、费用越低）
### 7.4 定时任务（Jobs）
点击左侧的 **Jobs** 按钮。
- 你可以创建定时任务，让 AI 在指定时间自动做事
- 比如每天早上 8 点总结新闻、每周一整理待办事项
- 支持 Cron 表达式（高级用户），也有简单的预设可选
- 可以随时暂停、恢复或手动触发执行
### 7.5 技能和记忆（Skills & Memory）
点击左侧对应的按钮。
- **Skills**：查看 AI 自己学到的技能。AI 会在使用过程中自动创建技能，比如"如何调用某个 API"或"用户喜欢的代码风格"
- **Memory**：查看和编辑 AI 关于你的记忆。你可以修改这些记忆来让 AI 更了解你
### 7.6 设置（Settings）
点击右上角的齿轮图标。
- **Display**：调整显示偏好（流式输出、紧凑模式等）
- **Agent**：AI 的行为参数（最大迭代次数、超时时间等）
- **Memory**：记忆系统的开关和限制
- **Session**：会话超时和重置设置
- **Privacy**：隐私保护（自动去除个人信息）




4.20更新了哪些内容

### 1. 备份恢复不再覆盖模型配置

**改动文件**：`src/data_sync.py`

之前的工作流程是：Space 启动 → 从 Dataset 恢复旧配置（覆盖新配置）→ 启动 Hermes。这导致每次重启后模型配置都被旧数据覆盖。

现在的流程是：Space 启动 → 从 Dataset 恢复其他数据（聊天记录、人格设定等）→ **跳过 config.yaml** → 由启动脚本根据当前环境变量重新生成配置。

具体来说，`data_sync.py` 的 `restore_from_download()` 方法现在会：
- 默认跳过 `config.yaml` 的恢复（由环境变量 `SKIP_CONFIG_RESTORE=true` 控制）
- 仅在本地完全不存在 config.yaml 时，才从备份中恢复一份作为初始值
- 其他数据（聊天记录、人格、技能等）照常恢复，不受影响

### 2. 三层防覆盖机制保护模型配置

**改动文件**：`entrypoint.sh`

即使跳过了旧配置恢复，Hermes 内部仍然有一个"配置桥接"机制，会在启动时自动检测 API Key 并可能修改 config.yaml。为了防止这种情况，我们增加了三层保护：

**第一层：环境变量注入**
- 在 Hermes 启动前，将所有供应商的 Base URL 导出到进程环境变量中
- 导出 `HERMES_MODEL` 环境变量，确保定时任务等场景也使用正确的模型
- 环境变量列表包括：`NVIDIA_BASE_URL`、`SILICONFLOW_BASE_URL`、`GEMINI_BASE_URL`、`OPENROUTER_BASE_URL`、`LONGCAT_BASE_URL`

**第二层：启动前强制锁定**
- 在 Dashboard 启动前，通过 `hermes config set` 命令将模型配置写入 config.yaml
- 如果 `hermes config set` 不可用，回退到 `yq` 工具直接修改 YAML 文件
- 修改后立刻用 `yq` 读取验证，确认模型字段没有被意外修改

**第三层：启动后二次验证**
- Dashboard 改为后台启动，等待 5 秒初始化
- 再次读取 config.yaml，检查模型配置是否被 Dashboard 启动流程覆盖
- 如果发现被修改或被清空，立即用 `yq` 修正回正确值
- 没有 `yq` 时回退到 `sed` 做局部修改（不会破坏其他配置项）

### 3. 修复压缩阈值错误

**改动文件**：`entrypoint.sh`、`config/config.yaml`

Hermes 的 `compression.threshold` 是一个**比率值**（0 到 1 之间的小数），不是绝对 token 数。例如 0.50 表示"当对话上下文使用到模型上下文窗口的 50% 时触发压缩"。

之前的配置写了 `threshold: 4000`，Hermes 把它当作"400000%"来计算，得出的压缩阈值为 8.19 亿 tokens，远超压缩模型 100 万 tokens 的处理能力，导致压缩功能完全失效。

现在改为 `threshold: 0.50`，含义清晰：对话上下文达到模型上限的 50% 时触发压缩，压缩模型 `gemini-3-flash-preview`（1M 上下文）完全能够处理。

### 4. Dockerfile 支持自动更新和 YAML 处理

**改动文件**：`Dockerfile`

- 移除了 `--branch v2026.4.13` 固定版本参数，改为始终拉取最新代码。这样在 Hugging Face Space 的 Settings 页面点击 **Factory Rebuild**，就会自动获取 Hermes Agent 的最新版本
- 新增安装 `yq`（YAML 处理工具），用于运行时精确修改 config.yaml 中的特定字段，而不是覆盖整个文件

### 5. 更新默认模型

**改动文件**：`entrypoint.sh`、`config/config.yaml`

NVIDIA 供应商的默认模型从 `minimaxai/minimax-m2.7`（该模型在实际使用中无响应）更换为 `moonshotai/kimi-k2-thinking`。




# Hermes Agent v0.9.0 on Hugging Face Spaces

智能AI代理，支持16个消息平台，持久化记忆，和Web管理界面。

## 功能

- 🤖 AI 对话与工具调用
- 🌐 Web Dashboard 管理
- 💾 数据持久化到 Hugging Face Dataset
- 🔔 支持消息网关（Telegram/Discord/Slack等）
- ⚡ 自动唤醒保持在线

## 技术栈

- Hermes Agent v0.9.0
- FastAPI Web Dashboard
- Hugging Face Datasets 持久化
- Docker Spaces

## 数据目录映射

| Hermes 目录 | Dataset 路径 | 说明 |
|------------|-------------|------|
| `~/.hermes/config.yaml` | `/config/config.yaml` | 核心配置 |
| `~/.hermes/.env` | `/config/.env` | 环境变量 |
| `~/.hermes/auth.json` | `/config/auth.json` | OAuth认证 |
| `~/.hermes/SOUL.md` | `/personality/SOUL.md` | 代理人格 |
| `~/.hermes/memories/` | `/memories/` | 持久记忆 |
| `~/.hermes/skills/` | `/skills/` | 自定义技能 |
| `~/.hermes/sessions/` | `/sessions/` | 会话历史 |
| `~/.hermes/state.db` | `/state/state.db` | SQLite数据库 |
| `~/.hermes/logs/` | `/logs/` | 日志文件 |
| `~/.hermes/cron/` | `/cron/` | 定时任务 |

## 环境变量

```bash
# 必需
HF_DATASET_REPO=your-username/hermes-data

# 可选
HERMES_HOME=/data/.hermes
SYNC_INTERVAL=300  # 同步间隔（秒）
HF_TOKEN=your-huggingface-token  # 用于访问私有 dataset
```

## 快速开始

### 1. 创建 Hugging Face Dataset

```bash
# 创建一个新的 dataset 用于存储数据
huggingface-cli repo create hermes-data --type dataset
```

### 2. 设置环境变量

在 Hugging Face Spaces 的 Settings 中设置：
- `HF_DATASET_REPO`: 你的 dataset 名称 (例如: username/hermes-data)
- `HF_TOKEN`: Hugging Face access token

### 3. 配置唤醒服务

使用 UptimeRobot 或 Cron-job.org 定期访问 Space URL 以保持在线。

## 部署步骤

### 部署到 Hugging Face Spaces

#### 方式一：通过 Web 界面部署

1. **创建 Space**: 访问 https://huggingface.co/new-space
   - 选择 "Docker" SDK
   - 设置 Space 名称
   - 选择硬件配置（免费版即可开始）

2. **克隆 Space 仓库**:
```bash
git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
cd YOUR_SPACE_NAME
```

3. **复制项目文件**:
```bash
# 复制所有项目文件到 Space 目录
cp -r /path/to/hermes-spaces/* .
```

4. **配置环境变量**:
   - 在 Space Settings → Variables 中设置:
     - `HF_DATASET_REPO`: `your-username/hermes-data`
     - `HF_TOKEN`: `your-huggingface-token`

5. **提交并推送**:
```bash
git add .
git commit -m "Initial deployment"
git push
```

6. **等待部署完成**:
   - 访问 `https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME`
   - 查看 Build 日志，等待部署完成

#### 方式二：通过 GitHub Actions 自动部署

1. **Fork 本仓库** 到你的 GitHub 账号

2. **在 Hugging Face 创建 Space**:
   - 访问 https://huggingface.co/new-space
   - 选择 Docker SDK
   - 记下 Space 名称

3. **配置 GitHub Secrets**:
   - 进入 GitHub 仓库 → Settings → Secrets and variables → Actions
   - 添加以下 secrets:
     - `HF_TOKEN`: 你的 Hugging Face access token
     - `HF_SPACE_REPO`: `YOUR_USERNAME/YOUR_SPACE_NAME`

4. **推送代码到 main 分支**:
```bash
git push origin main
```

5. **GitHub Actions 会自动部署**:
   - 查看 Actions 标签页查看部署进度
   - 部署完成后访问 Space URL

## 配置唤醒服务

由于 Hugging Face Spaces 免费版会在 48 小时无活动后休眠，建议配置外部唤醒服务：

### 使用 UptimeRobot（推荐）

1. 访问 https://uptimerobot.com 并注册账号
2. 点击 "Add New Monitor"
3. 配置如下：
   - **Monitor Type**: HTTP(s)
   - **Friendly Name**: Hermes Agent
   - **URL**: `https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/health`
   - **Monitoring Interval**: 5 minutes
4. 点击 "Create Monitor"

### 使用 Cron-job.org（备选）

1. 访问 https://cron-job.org
2. 创建新的 cron job
3. 配置 URL: `https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/health`
4. 设置每 5 分钟执行一次

## 首次使用

1. 访问 Space URL: `https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space`
2. 首次启动会创建默认配置，从 Dataset 恢复数据（如果存在）
3. 在 Web Dashboard 中配置：
   - API Keys（OpenAI, OpenRouter, etc.）
   - 消息网关（Telegram, Discord, etc.）
   - 代理人格（SOUL.md）

## 故障排除

### Space 无法启动

1. **检查构建日志**:
   - 访问 Space 页面 → Files → "Build logs"
   - 查看错误信息

2. **常见问题**:
   - **内存不足**: 升级到付费硬件（CPU Upgrade）
   - **依赖安装失败**: 检查 requirements.txt 格式
   - **权限错误**: 确保 Dockerfile 中设置了 USER appuser

### 数据未持久化

1. **检查环境变量**:
   - 确认 `HF_DATASET_REPO` 已正确设置
   - 确认 `HF_TOKEN` 有写入 Dataset 的权限

2. **检查 Dataset 权限**:
   - 确保 Dataset 是私有的（推荐）
   - 确保 Token 有 `write` 权限

3. **查看同步日志**:
   - 在 Space 的 Logs 中查看 data-sync 相关日志

### 消息网关断开

1. **这是正常现象**: Spaces 休眠后所有连接会断开
2. **解决方案**:
   - 升级到付费版保持持续运行
   - 或配置网关自动重连（在 Hermes 配置中设置）

## 文件说明

- `Dockerfile` - Docker 镜像定义
- `entrypoint.sh` - 容器启动脚本
- `requirements.txt` - Python 依赖
- `src/data_sync.py` - 数据同步服务
- `.github/workflows/deploy.yml` - GitHub Actions 自动部署

## 许可证

MIT License - 详见 LICENSE 文件

## 贡献

欢迎提交 Issue 和 Pull Request！

## 相关链接

- [Hermes Agent 官方仓库](https://github.com/NousResearch/hermes-agent)
- [Hugging Face Spaces 文档](https://huggingface.co/docs/hub/spaces-overview)
- [Hermes Agent 文档](https://hermes-agent.com)