Hermes Agent 系统架构设计参考: 官方架构文档源码版本:b63229016一、设计理念原则实践进程隔离Gateway平台集成和 DashboardWeb UI完全独立进程各自独立启停重启协议兼容API Server 对外暴露 OpenAI 兼容接口任意 OpenAI 生态工具均可接入插件化平台Messaging PlatformTG/Discord/Teams 等以 adapter 形式接入 Gateway会话持久化SQLite WAL 模式保证 ResponseStore 和 SessionDB 重启不丢平台无关核心一个 AIAgent 类同时服务于 CLI、Gateway、ACP、Batch 和 API Server可观测执行每个 tool call 均通过回调对用户可见可中断API 调用和 tool 执行均可被用户输入或信号中途取消二、整体进程架构┌─────────────────────────────────────────────────────────────────────┐ │ 三大入口 │ │ │ │ hermes dashboard hermes gateway run hermes run │ │ (独立进程 :9119) (Gateway 进程内 :8642) (独立进程 TUI) │ │ FastAPI React SPA APIServerAdapter 共用 stdin/stdout │ │ Gateway 进程 │ └──────────────┬─────────────────┬─────────────────┬───────────────────┘ │ │ │ │ HTTP/REST │ OpenAI HTTP │ interactive │ Bearer token │ Bearer token │ TUI │ │ │ ┌──────────────▼────┐ ┌────────▼────────┐ ┌─────▼──────────────┐ │ Dashboard │ │ API Server │ │ TUI │ │ hermes │ │ (APIServer │ │ hermes run │ │ dashboard │ │ Adapter) │ │ │ │ :9119 │ │ :8642 │ │ hermes_cli/ │ │ FastAPI │ │ 共用 Gateway │ │ main.py │ │ web_server.py │ │ AIAgent 实例 │ │ │ └───────────────────┘ └───────┬────────┘ └────────────────────┘ │ ┌───────────▼───────────┐ │ Gateway 主进程 │ │ gateway/run.py │ │ │ │ PlatformRegistry │ │ AIAgent共享实例 │ │ SessionDB │ │ CronScheduler │ │ Platform Adapters: │ │ Telegram, Discord, │ │ API Server (:8642), │ │ Dashboard (:9119)... │ └───────────────────────┘关键设计: API Server 是 Gateway 主进程内的 adapterAPIServerAdapter与 Telegram/Discord adapter 并列运行共享同一个 AIAgent 实例。Dashboard 是完全独立进程不依赖 Gateway。三、核心组件3.1 AIAgentrun_agent.py核心对话引擎处理 provider 选择、prompt 构建、tool 执行、重试、回退、回调、压缩和持久化。AIAgent.run_conversation() ├── prompt_builder.build_system_prompt() │ └── 组装: personality memory skills context files tool guidance ├── runtime_provider.resolve_runtime_provider() ├── API callchat_completions / codex_responses / anthropic_messages ├── tool_calls? → model_tools.handle_function_call() → loop └── final response → display → save to SessionDB3.2 HermesCLIcli.py交互式终端 UI包含完整的 TUI 实现多行编辑、斜杠命令自动补全、对话历史、中断重定向、流式 tool 输出。3.3 Gatewaygateway/run.py消息平台集成中枢管理 20 个 platform adapters平台路径Telegram, Discord, Slack, WhatsApp, Signalgateway/platforms/Matrix, Mattermost, Email, SMSgateway/platforms/DingTalk, Feishu, WeCom, Weixin, QQBotgateway/platforms/HomeAssistant, Webhook, API Server, Yuanbaogateway/platforms/3.4 APIServerAdaptergateway/platforms/api_server.pyOpenAI 兼容 HTTP API通过 aiohttp 实现监听:8642。是 Gateway 进程内的协程与其他 platform adapter 并列。四、API Server 架构4.1 源码结构gateway/platforms/api_server.py 2,933 行 │ ├── APIServerAdapter 主类 │ ├── setup_routes() 路由注册第 2810-2831 行 │ ├── _check_auth() Bearer token 认证 │ └── start()/stop() aiohttp AppRunner 生命周期 │ ├── IdempotencyCache 10 分钟请求去重 │ ├── ResponseStore SQLite WAL 持久化 │ ├── get() / put() / delete() │ ├── get_conversation() 按 session name 反查 │ └── 上限 100 条LRU 淘汰 │ └── _RunManager Runs API 异步任务 ├── _run_statuses {run_id: status} ├── _run_events {run_id: asyncio.Queue} └── _run_threads {run_id: Thread}4.2 路由注册# gateway/platforms/api_server.py 第 2810-2831 行self._app.router.add_get(/health,self._handle_health)self._app.router.add_get(/health/detailed,self._handle_health_detailed)self._app.router.add_get(/v1/health,self._handle_health)self._app.router.add_get(/v1/models,self._handle_models)self._app.router.add_get(/v1/capabilities,self._handle_capabilities)self._app.router.add_post(/v1/chat/completions,self._handle_chat_completions)self._app.router.add_post(/v1/responses,self._handle_responses)self._app.router.add_get(/v1/responses/{response_id},self._handle_get_response)self._app.router.add_delete(/v1/responses/{response_id},self._handle_delete_response)self._app.router.add_get(/api/jobs,self._handle_list_jobs)self._app.router.add_post(/api/jobs,self._handle_create_job)self._app.router.add_get(/api/jobs/{job_id},self._handle_get_job)self._app.router.add_patch(/api/jobs/{job_id},self._handle_update_job)self._app.router.add_delete(/api/jobs/{job_id},self._handle_delete_job)self._app.router.add_post(/api/jobs/{job_id}/pause,self._handle_pause_job)self._app.router.add_post(/api/jobs/{job_id}/resume,self._handle_resume_job)self._app.router.add_post(/api/jobs/{job_id}/run,self._handle_run_job)self._app.router.add_post(/v1/runs,self._handle_runs)self._app.router.add_get(/v1/runs/{run_id},self._handle_get_run)self._app.router.add_get(/v1/runs/{run_id}/events,self._handle_run_events)self._app.router.add_post(/v1/runs/{run_id}/stop,self._handle_stop_run)4.3 三协议对比维度Chat CompletionsResponses APIRuns API协议OpenAI 兼容OpenAI 兼容OpenAI 兼容状态无状态有状态previous_response_id异步任务queued/running/completed/failed/cancelled持久化否SQLite ResponseStore否内存状态仅 SSE 可追踪流式SSE 可选否一次性返回SSE必须会话保持X-Hermes-Session-Idheaderprevious_response_id/conversationinput 中带 session适用场景简单请求/响应多轮对话保持上下文长时间运行客户端订阅事件4.4 Runs API 详细流程客户端 APIServerAdapter │ │ │──POST /v1/runs─────────────▶│ 分配 run_id状态queued→running │◀──202 {run_id:...}──────│ 立即返回不等 AI 完成 │ │ │──GET /v1/runs/{id}/events───▶│ 建立 SSE 连接 │◀─event: run.started ─────────│ │◀─event: tool.started ─────────│ │◀─event: message.delta ────────│ │◀─event: tool.completed ──────│ │◀─event: run.completed ───────│ 最终结果 │ │ │──POST /v1/runs/{id}/stop────▶│ 中断 run │◀─event: run.cancelled ───────│状态机:queued→running→completed/failed/cancelled4.5 认证机制def_check_auth(self,request):# 1. 未配置 key - 允许仅限本地开发ifnotself._api_key:returnNone# 2. Authorization: Bearer tokenauthrequest.headers.get(Authorization,)ifauth.startswith(Bearer ):tokenauth[7:].strip()ifhmac.compare_digest(token,self._api_key):returnNone# OK# 3. 返回 401returnweb.json_response({error:{...}},status401)/health系列端点无需认证其他所有端点强制认证已配置 key 时使用hmac.compare_digest防止时序攻击五、Dashboard 架构5.1 组件关系hermes dashboard独立进程 :9119 │ ├── hermes_cli/web_server.py FastAPI 后端4,062 行 │ ├── _SESSION_TOKEN 每进程随机secrets.token_urlsafe(32) │ ├── auth_middleware Bearer token 验证 │ ├── REST API 端点 /api/* │ └── WebSocket /api/ptyxterm.js PTY bridge │ └── hermes_cli/web_dist/ React SPAnpm build 产物 ├── index.html 内嵌 scriptwindow.__HERMES_TOKEN__ └── assets/ JS CSS bundles5.2 认证流程SPA 加载 ├── GET / → HTML 中内嵌 scriptwindow.__HERMES_TOKEN__xxx ├── JS 读取 token └── 后续所有 /api/* 请求 Header: Authorization: Bearer token │ ▼ auth_middleware() hmac.compare_digest(auth, fBearer {_SESSION_TOKEN}) ├── 匹配 ──► 处理请求 └── 不匹配 ─► 401 Unauthorized注意: Dashboard 的_SESSION_TOKEN是每进程随机与 API Server 的API_SERVER_KEY.env完全独立。5.3 PTY Bridge嵌入式 TUI浏览器xterm.js │ │ WebSocket /api/pty ▼ web_server.py: pty_bridge() │ ├──► Python PTYsubprocess │ └──► hermes runstdin/stdout │ └──► WebSocket 回传 PTY 输出到 xterm.js5.4 前端技术栈层级技术框架React 19 TypeScript构建Vite样式Tailwind CSS v4 shadcn/ui 风格组件状态React Context Hooks终端模拟xterm.js WebGL 渲染插件 SDKwindow.__HERMES_PLUGIN_SDK__不捆绑 React5.5 Dashboard 插件系统~/.hermes/plugins/name/ ├── plugin.yaml CLI/Gateway 插件清单 ├── __init__.py CLI/Gateway hooks └── dashboard/ Dashboard 扩展可选 ├── manifest.json 插件配置tab、slots、entry ├── dist/ │ ├── index.js 预编译 JS bundleIIFE无构建步骤 │ └── style.css 自定义 CSS可选 └── plugin_api.py 后端 FastAPI 路由可选插件通过window.__HERMES_PLUGINS__.register(name, Component)注册不捆绑 React通过 SDK 访问。5.6 Shell SlotsSlot位置header-left/header-right顶部栏左右侧sidebar驾驶舱侧边栏仅layoutVariant: cockpit时渲染sessions:top/sessions:bottomSessions 页面顶部/底部analytics:top/analytics:bottomAnalytics 页面顶部/底部cron:top/cron:bottomCron 页面顶部/底部config:top/config:bottomConfig 页面顶部/底部六、数据流设计6.1 配置读取层级hermes config set xxx │ ▼ ~/.hermes/config.yaml │ ├──► Dashboard (web_server.py) │ └── 直接读取 YAML │ └──► Gateway (gateway/run.py) └── 通过 HermesConfig 类读取 │ └──► AIAgent / PlatformAdapter6.2 会话持久化~/.hermes/state.db (SQLite WAL) │ ├──► SessionDB │ │ │ ├──► Gateway所有 platform adapter 共享 │ │ │ └──► API Server/v1/responses 等 │ └── ~/.hermes/response_store.db │ └──► ResponseStoreAPI Server 专属 │ └──► /v1/responses 持久化上限 100 条LRU七、安全模型7.1 认证矩阵服务端点认证方式无 key 行为API Server/health系列无允许API Server其他所有API_SERVER_KEY.env拒绝401Dashboard/api/*_SESSION_TOKEN每进程随机不适用key 必然存在Dashboard静态资源/无允许7.2 密钥存储原则~/.hermes/.env API Keys、Tokens敏感 ~/.hermes/config.yaml 平台开关、行为配置非敏感7.3 CORS 策略API Server: 默认不启用CORS。直接浏览器访问需设置API_SERVER_CORS_ORIGINSDashboard: 仅允许localhost/127.0.0.1来源八、目录结构hermes-agent/ ├── run_agent.py # AIAgent — 核心对话循环~13,700 行 ├── cli.py # HermesCLI — 交互终端 UI~11,500 行 ├── model_tools.py # Tool 发现、schema 收集、分发 ├── toolsets.py # Tool 分组和平台预设 ├── hermes_state.py # SQLite session/state 数据库 FTS5 ├── hermes_constants.py # HERMES_HOME、profile 路径 ├── batch_runner.py # 批量轨迹生成 │ ├── agent/ # Agent 内部模块 │ ├── prompt_builder.py # System prompt 组装 │ ├── context_engine.py # ContextEngine 抽象类可插拔 │ ├── context_compressor.py # 上下文压缩默认有损摘要 │ ├── prompt_caching.py # Anthropic prompt caching │ ├── auxiliary_client.py # 辅助 LLM视觉、摘要 │ └── model_metadata.py # 模型上下文长度、token 估算 │ ├── hermes_cli/ # CLI 子命令 │ ├── main.py # 入口 — 所有 hermes 子命令~10,400 行 │ ├── config.py # DEFAULT_CONFIG、OPTIONAL_ENV_VARS、迁移 │ ├── commands.py # COMMAND_REGISTRY — 斜杠命令定义 │ ├── auth.py # PROVIDER_REGISTRY、凭证解析 │ ├── setup.py # 交互式设置向导~3,500 行 │ ├── web_server.py # Dashboard FastAPI 后端4,062 行 │ └── web_dist/ # React SPA 构建产物 │ ├── gateway/ # 消息平台网关 │ ├── run.py # GatewayRunner — 消息分发~12,200 行 │ ├── session.py # SessionStore — 对话持久化 │ └── platforms/ # 20 个 adapter: telegram, discord, api_server 等 │ ├── tools/ # Tool 实现 │ ├── registry.py # 中心 tool 注册表61 个 tools │ ├── terminal_tool.py # 终端编排 │ ├── browser_tool.py # 浏览器自动化 │ ├── mcp_tool.py # MCP 客户端~3,100 行 │ └── environments/ # 终端后端local、docker、ssh、modal 等 7 种 │ ├── cron/ # 调度器 ├── acp_adapter/ # ACP 服务端VS Code / Zed / JetBrains ├── plugins/ # 插件memory、context_engine 等 ├── skills/ # 内置 skills └── website/docs/ # 官方文档站九、版本变化要点v0.12.0变化说明API Server 三协议Chat Completions / Responses API / Runs API 完整实现会话持久化SQLite WAL 模式ResponseStore SessionDB 重启不丢Runs API202 即返回 SSE 事件流 run_id轮询 并发控制10Dashboard 认证每进程随机_SESSION_TOKENBearer token 中间件验证插件化 Platform动态PlatformRegistryadapter 按需加载Dashboard 主题6 种内置主题 YAML 自定义主题 驾驶舱布局TTS Provider可插拔 TTS provider registry冷启动优化TUI 冷启动削减约 57%