企业官网建设流程全解析

Hermes Agent 系统架构设计

参考: 官方架构文档
源码版本:b63229016

一、设计理念

二、整体进程架构

┌─────────────────────────────────────────────────────────────────────┐ │ 三大入口 │ │ │ │ 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 主进程内的 adapter（APIServerAdapter），与 Telegram/Discord adapter 并列运行，共享同一个 AIAgent 实例。Dashboard 是完全独立进程，不依赖 Gateway。

三、核心组件

3.1 AIAgent（run_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 call（chat_completions / codex_responses / anthropic_messages） ├── tool_calls? → model_tools.handle_function_call() → loop └── final response → display → save to SessionDB

3.2 HermesCLI（cli.py）

交互式终端 UI，包含完整的 TUI 实现（多行编辑、斜杠命令自动补全、对话历史、中断重定向、流式 tool 输出）。

3.3 Gateway（gateway/run.py）

消息平台集成中枢，管理 20 个 platform adapters：

3.4 APIServerAdapter（gateway/platforms/api_server.py）

OpenAI 兼容 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 三协议对比

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/cancelled

4.5 认证机制

def_check_auth(self,request):# 1. 未配置 key -> 允许（仅限本地开发）ifnotself._api_key:returnNone# 2. Authorization: Bearer <token>auth=request.headers.get("Authorization","")ifauth.startswith("Bearer "):token=auth[7:].strip()ifhmac.compare_digest(token,self._api_key):returnNone# OK# 3. 返回 401returnweb.json_response({"error":{...}},status=401)

• /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/pty（xterm.js PTY bridge） │ └── hermes_cli/web_dist/ React SPA（npm build 产物） ├── index.html 内嵌 <script>window.__HERMES_TOKEN__ └── assets/ JS + CSS bundles

5.2 认证流程

SPA 加载 ├── GET / → HTML 中内嵌 <script>window.__HERMES_TOKEN__="xxx" ├── JS 读取 token └── 后续所有 /api/* 请求 Header: Authorization: Bearer <token> │ ▼ auth_middleware() hmac.compare_digest(auth, f"Bearer {_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 PTY（subprocess） │ └──► hermes run（stdin/stdout） │ └──► WebSocket 回传 PTY 输出到 xterm.js

5.4 前端技术栈

5.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 bundle（IIFE，无构建步骤） │ └── style.css 自定义 CSS（可选） └── plugin_api.py 后端 FastAPI 路由（可选）

插件通过window.__HERMES_PLUGINS__.register(name, Component)注册，不捆绑 React，通过 SDK 访问。

5.6 Shell Slots

六、数据流设计

6.1 配置读取层级

hermes config set xxx │ ▼ ~/.hermes/config.yaml │ ├──► Dashboard (web_server.py) │ └── 直接读取 YAML │ └──► Gateway (gateway/run.py) └── 通过 HermesConfig 类读取 │ └──► AIAgent / PlatformAdapter

6.2 会话持久化

~/.hermes/state.db (SQLite WAL) │ ├──► SessionDB │ │ │ ├──► Gateway（所有 platform adapter 共享） │ │ │ └──► API Server（/v1/responses 等） │ └── ~/.hermes/response_store.db │ └──► ResponseStore（API Server 专属） │ └──► /v1/responses 持久化（上限 100 条，LRU）

七、安全模型

7.1 认证矩阵

7.2 密钥存储原则

~/.hermes/.env API Keys、Tokens（敏感） ~/.hermes/config.yaml 平台开关、行为配置（非敏感）

7.3 CORS 策略

• API Server: 默认不启用CORS。直接浏览器访问需设置API_SERVER_CORS_ORIGINS
• Dashboard: 仅允许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）