Upload README.md with huggingface_hub

README.md

@@ -1,387 +1,23 @@
-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)
+---
+title: Hermes Agent
+emoji: 🤖
+colorFrom: blue
+colorTo: purple
+sdk: docker
+pinned: false
+app_port: 7860
+---
+
+# Hermes Agent v0.10.0
+
+智能 AI 代理，支持多平台消息网关、持久化记忆和 Web 管理界面。
+
+## 功能
+- 🤖 AI 对话与工具调用
+- 🌐 Web Dashboard 管理
+- 💾 数据持久化（Hugging Face Dataset）
+- 🔔 多平台消息网关
+- ⚡ 自动唤醒
+
+## 使用
+访问 Space URL 即可使用 Web 管理界面。