nonebot-plugin-hermes 0.1.0__py3-none-any.whl

nonebot_plugin_hermes/__init__.py

@@ -0,0 +1,42 @@
+"""
+NoneBot Plugin Hermes
+
+通过 Hermes Agent API Server 实现多平台 AI 聊天机器人。
+支持所有 NoneBot adapter（OneBot v11/v12、QQ Official、Kook 等）。
+"""
+
+from nonebot import require, logger
+from nonebot.plugin import PluginMetadata, inherit_supported_adapters
+
+# 确保依赖的插件已加载
+require("nonebot_plugin_alconna")
+
+from .config import Config, plugin_config  # noqa: E402
+
+__version__ = "0.1.0"
+
+__plugin_meta__ = PluginMetadata(
+    name="Hermes Agent",
+    description="通过 Hermes Agent API Server 实现多平台 AI 聊天机器人",
+    homepage="https://github.com/NousResearch/hermes-agent",
+    usage=(
+        "在群聊中 @机器人 发送消息即可与 Hermes Agent 对话。\n"
+        "私聊直接发送消息即可。\n\n"
+        "命令：\n"
+        "/clear - 重置对话\n"
+        "/ping - 检查连接状态\n"
+        "/help - 显示帮助"
+    ),
+    type="application",
+    config=Config,
+    supported_adapters=inherit_supported_adapters("nonebot_plugin_alconna"),
+    extra={
+        "author": "gsskk",
+        "version": __version__,
+    },
+)
+
+logger.info(f"Hermes Plugin loaded — API: {plugin_config.hermes_api_url}")
+
+# 导入 handlers 以注册事件处理器
+from . import handlers  # noqa: F401, E402

nonebot_plugin_hermes/config.py

@@ -0,0 +1,55 @@
+"""
+配置模型
+
+所有配置项通过 NoneBot 的 .env 文件读取，前缀为 HERMES_。
+"""
+
+from typing import Set
+
+from nonebot import get_plugin_config
+from pydantic import BaseModel
+
+
+class Config(BaseModel):
+    # --- Hermes API Server ---
+    hermes_api_url: str = "http://127.0.0.1:8642"
+    """Hermes API Server 地址"""
+
+    hermes_api_key: str = ""
+    """Hermes API Server 密钥（对应 api_server.extra.key）"""
+
+    hermes_api_timeout: int = 300
+    """API 请求超时时间（秒），Agent 执行可能较慢"""
+
+    # --- 触发模式 ---
+    hermes_group_trigger: str = "at"
+    """群聊触发方式: at / all / keyword"""
+
+    hermes_keywords: Set[str] = {"/ai"}
+    """keyword 模式下的触发关键词"""
+
+    hermes_private_trigger: str = "all"
+    """私聊触发方式: all / allowlist"""
+
+    hermes_allow_users: Set[str] = set()
+    """允许私聊的用户 ID（allowlist 模式）"""
+
+    hermes_allow_groups: Set[str] = set()
+    """允许响应的群组 ID（空 = 全部允许）"""
+
+    # --- 会话 ---
+    hermes_session_expire: int = 3600
+    """会话过期时间（秒），过期后自动开始新会话"""
+
+    hermes_session_share_group: bool = False
+    """群内是否共享同一个 session（False = 每人独立）"""
+
+    # --- 消息 ---
+    hermes_max_length: int = 4000
+    """单条回复最大长度（超出截断，QQ 限制约 4500 字符）"""
+
+    hermes_ignore_prefix: Set[str] = {"."}
+    """以这些字符开头的消息不触发回复"""
+
+
+plugin_config = get_plugin_config(Config)

nonebot_plugin_hermes-0.1.0.dist-info/METADATA

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: nonebot-plugin-hermes
+Version: 0.1.0
+Summary: NoneBot plugin for Hermes Agent — multi-platform AI chatbot via Hermes API Server
+License: MIT
+Project-URL: Homepage, https://github.com/gsskk/nonebot-plugin-hermes
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: nonebot2>=2.3.0
+Requires-Dist: nonebot-plugin-alconna>=0.50.2
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: cachetools>=6.2.0
+
+# nonebot-plugin-hermes
+
+中文文档 | [English](README_EN.md)
+
+[Hermes Agent](https://github.com/NousResearch/hermes-agent) 的 NoneBot2 插件，通过 Hermes API Server 实现多平台 AI 聊天机器人。
+
+## 支持的平台
+
+通过 NoneBot adapter 机制，本插件自动支持：
+
+- ✅ OneBot v11（NapCatQQ、LLOneBot、go-cqhttp 等）
+- ✅ OneBot v12
+- ✅ QQ Official Bot
+- ✅ Kook（开黑啦）
+- ✅ Discord
+- ✅ Telegram
+- ✅ 飞书
+- ✅ 其他 `nonebot-plugin-alconna` 支持的平台
+
+## 工作原理
+
+```
+用户消息 → NoneBot Adapter → nonebot-plugin-hermes
+  → POST /v1/chat/completions (Hermes API Server)
+  → 解析回复 → UniMessage.send() → NoneBot Adapter → 用户
+```
+
+## 功能
+
+- ✅ 私聊 / 群聊对话
+- ✅ 多轮上下文记忆（基于 Hermes Session）
+- ✅ 群聊 @触发 / 关键词触发 / 全部触发
+- ✅ 图片接收（通过 vision 发给 AI）
+- ✅ 图片发送（解析 AI 回复中的 markdown 图片）
+- ✅ 会话超时自动重置
+- ✅ 白名单（群/用户级别）
+- ✅ 内置命令（`/clear` `/ping` `/help`）
+
+## 快速开始
+
+### 1. 前置条件
+
+- 已安装并运行 Hermes Agent，且 API Server 已启用
+- 已安装 NoneBot2 和对应平台的 adapter
+
+### 2. 启用 Hermes API Server
+
+在 `~/.hermes/config.yaml` 中：
+
+```yaml
+platforms:
+  api_server:
+    enabled: true
+    extra:
+      port: 8642
+```
+
+设置 API Key（**必须**，用于会话保持）：
+
+```bash
+# 生成密钥
+python -c "import secrets; print(secrets.token_hex(32))"
+# 或 openssl rand -hex 32
+
+# 写入 Hermes 环境配置
+echo 'API_SERVER_KEY=your-generated-key' >> ~/.hermes/.env
+```
+
+> **Note**: 不设置 `API_SERVER_KEY` 会导致 Session 续接被拒绝，每次对话无法保持上下文。
+
+启动 Hermes Gateway：
+
+```bash
+hermes gateway
+```
+
+### 3. 安装插件
+
+**方式 A：已有 NoneBot 项目**
+
+```bash
+pip install -e /path/to/nonebot-plugin-hermes
+# 或 uv add /path/to/nonebot-plugin-hermes
+```
+
+在 `pyproject.toml` 中添加插件：
+
+```toml
+[tool.nonebot]
+plugins = ["nonebot_plugin_hermes"]
+```
+
+**方式 B：新建 NoneBot 项目**
+
+```bash
+pip install nb-cli
+nb create          # 创建项目，选择 fastapi 驱动器
+nb plugin install nonebot-adapter-onebot  # 安装 OneBot 适配器
+pip install -e /path/to/nonebot-plugin-hermes
+```
+
+### 4. 配置
+
+复制示例配置：
+
+```bash
+cp .env.example .env
+```
+
+编辑 `.env`，主要配置：
+
+```env
+# OneBot 正向 WebSocket
+ONEBOT_WS_URLS=["ws://127.0.0.1:3001"]
+
+# Hermes API
+HERMES_API_URL=http://127.0.0.1:8642
+HERMES_API_KEY=
+
+# 群聊触发
+HERMES_GROUP_TRIGGER=at
+```
+
+### 5. 运行
+
+```bash
+nb run
+```
+
+## 可用的 AI 工具
+
+本插件通过 Hermes 的 `api_server` 平台通信，默认使用 `hermes-api-server` 工具集：
+
+| 工具类别 | 包含的工具 |
+|---------|-----------|
+| Web 搜索与提取 | `web_search`, `web_extract` |
+| 终端与进程 | `terminal`, `process` |
+| 文件操作 | `read_file`, `write_file`, `patch`, `search_files` |
+| 视觉与图片生成 | `vision_analyze`, `image_generate` |
+| 浏览器自动化 | `browser_navigate`, `browser_snapshot` 等 |
+| 规划与记忆 | `todo`, `memory`, `session_search` |
+| 代码执行与委托 | `execute_code`, `delegate_task` |
+| 定时任务 | `cronjob` |
+| 智能家居 | `ha_list_entities`, `ha_get_state` 等 |
+
+### 🔒 安全最佳实践：限制 API Server 工具集
+
+默认的 `hermes-api-server` 工具集包含 `terminal`、`execute_code` 等可执行服务器命令的工具。**对于面向外部用户的部署，强烈建议限制工具集**。
+
+在 `~/.hermes/config.yaml` 中配置 `platform_toolsets`：
+
+```yaml
+platform_toolsets:
+  # 其他平台保持默认
+  cli: [hermes-cli]
+  telegram: [hermes-telegram]
+
+  # API Server 使用受限工具集（按需选择）
+  api_server: [web, file, vision, image_gen, skills, todo, memory, session_search]
+```
+
+可选的安全级别：
+
+| 级别 | 配置 | 说明 |
+|------|------|------|
+| 🔴 最小权限 | `[safe]` | 仅 web + vision + image_gen，无文件/终端 |
+| 🟡 推荐 | `[web, file, vision, image_gen, skills, todo, memory, session_search]` | 有文件读写但无命令执行 |
+| 🟢 完全信任 | `[hermes-api-server]`（默认） | 包含终端、代码执行等全部工具 |
+
+> **Tip**: 运行 `hermes chat --list-toolsets` 查看所有可用工具集。
+
+
+
+## 命令
+
+| 命令 | 说明 |
+|------|------|
+| `/clear` | 重置对话，开始新会话 |
+| `/ping` | 检查 Hermes Agent 连接状态 |
+| `/help` | 显示帮助信息 |
+
+## 配置项
+
+所有配置项通过 `.env` 文件设置，参见 [.env.example](.env.example) 中的详细注释。
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `HERMES_API_URL` | `http://127.0.0.1:8642` | Hermes API Server 地址 |
+| `HERMES_API_KEY` | (空) | API 密钥 |
+| `HERMES_GROUP_TRIGGER` | `at` | 群聊触发: at / all / keyword |
+| `HERMES_PRIVATE_TRIGGER` | `all` | 私聊触发: all / allowlist |
+| `HERMES_SESSION_EXPIRE` | `3600` | 会话超时（秒） |
+| `HERMES_SESSION_SHARE_GROUP` | `false` | 群内共享 session |
+
+## 限制
+
+由于通过 HTTP API 与 Hermes 通信（而非原生 Gateway Adapter），以下功能不可用：
+
+- ❌ 追问用户（`clarify` 工具）
+- ❌ 跨平台发消息（`send_message` 工具）
+- ❌ 语音合成发送（`text_to_speech` 工具）
+- ❌ 危险命令审批按钮
+- ❌ Cron 定时主动推送
+- ❌ 中断正在运行的 Agent
+
+## License
+
+MIT

nonebot_plugin_hermes-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+nonebot_plugin_hermes/__init__.py,sha256=2rEkiPFjVfSTFqjPwharCJ7o1mu2F-mAKNLxGPJzeGE,1277
+nonebot_plugin_hermes/config.py,sha256=iM6_MM56vrY628TV6fSnBbhj7e6t9kTYuEWjp-mnnxo,1555
+nonebot_plugin_hermes-0.1.0.dist-info/METADATA,sha256=7JYn7bLCeKa_ZEsqg3e2ulnFpkfbdI78OdpLGg_V_dY,5927
+nonebot_plugin_hermes-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+nonebot_plugin_hermes-0.1.0.dist-info/top_level.txt,sha256=8opDU9spxCmiU2okVK23VCfzF4fy5YkXkKjAXVDxJ1Q,22
+nonebot_plugin_hermes-0.1.0.dist-info/RECORD,,

nonebot_plugin_hermes-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

nonebot_plugin_hermes-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+nonebot_plugin_hermes