Kiến trúc
Trang này là bản đồ cấp cao nhất về nội bộ của Hermes Agent. Hãy sử dụng nó để tự định hướng trong cơ sở mã, sau đó đi sâu vào các tài liệu dành riêng cho hệ thống con để biết chi tiết triển khai.
Tổng quan về hệ thống
┌─────────────────────────────────────────────────────────────────────┐
│ Entry Points │
│ │
│ CLI (cli.py) Gateway (gateway/run.py) ACP (acp_adapter/) │
│ Batch Runner API Server Python Library │
└──────────┬──────────────┬───────────────────────┬────────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────┐
│ AIAgent (run_agent.py) │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Prompt │ │ Provider │ │ Tool │ │
│ │ Builder │ │ Resolution │ │ Dispatch │ │
│ │ (prompt_ │ │ (runtime_ │ │ (model_ │ │
│ │ builder.py) │ │ provider.py)│ │ tools.py) │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ ┌──────┴───────┐ ┌──────┴───────┐ ┌──────┴───────┐ │
│ │ Compression │ │ 3 API Modes │ │ Tool Registry│ │
│ │ & Caching │ │ chat_compl. │ │ (registry.py)│ │
│ │ │ │ codex_resp. │ │ 48 tools │ │
│ │ │ │ anthropic │ │ 40 toolsets │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
│ │
▼ ▼
┌───────────────────┐ ┌──────────────────────┐
│ Session Storage │ │ Tool Backends │
│ (SQLite + FTS5) │ │ Terminal (6 backends) │
│ hermes_state.py │ │ Browser (5 backends) │
│ gateway/session.py│ │ Web (4 backends) │
└───────────────────┘ │ MCP (dynamic) │
│ File, Vision, etc. │
└──────────────────────┘
Cấu trúc thư mục
hermes-agent/
├── run_agent.py
# AIAgent — core conversation loop (~9,200 lines)
├── cli.py
# HermesCLI — interactive terminal UI (~8,500 lines)
├── model_tools.py
# Tool discovery, schema collection, dispatch
├── toolsets.py
# Tool groupings and platform presets
├── hermes_state.py
# SQLite session/state database with FTS5
├── hermes_constants.py
# HERMES_HOME, profile-aware paths
├── batch_runner.py
# Batch trajectory generation
│
├── agent/
# Agent internals
│ ├── prompt_builder.py
# System prompt assembly
│ ├── context_compressor.py
# Conversation compression algorithm
│ ├── prompt_caching.py
# Anthropic prompt caching
│ ├── auxiliary_client.py
# Auxiliary LLM for side tasks (vision, summarization)
│ ├── model_metadata.py
# Model context lengths, token estimation
│ ├── models_dev.py
# models.dev registry integration
│ ├── anthropic_adapter.py
# Anthropic Messages API format conversion
│ ├── display.py
# KawaiiSpinner, tool preview formatting
│ ├── skill_commands.py
# Skill slash commands
│ ├── memory_manager.py
# Memory manager orchestration
│ ├── memory_provider.py
# Memory provider ABC
│ └── trajectory.py
# Trajectory saving helpers
│
├── hermes_cli/
# CLI subcommands and setup
│ ├── main.py
# Entry point — all `hermes` subcommands (~5,500 lines)
│ ├── config.py
# DEFAULT_CONFIG, OPTIONAL_ENV_VARS, migration
│ ├── commands.py
# COMMAND_REGISTRY — central slash command definitions
│ ├── auth.py
# PROVIDER_REGISTRY, credential resolution
│ ├── runtime_provider.py
# Provider → api_mode + credentials
│ ├── models.py
# Model catalog, provider model lists
│ ├── model_switch.py
# /model command logic (CLI + gateway shared)
│ ├── setup.py
# Interactive setup wizard (~3,100 lines)
│ ├── skin_engine.py
# CLI theming engine
│ ├── skills_config.py
# hermes skills — enable/disable per platform
│ ├── skills_hub.py
# /skills slash command
│ ├── tools_config.py
# hermes tools — enable/disable per platform
│ ├── plugins.py
# PluginManager — discovery, loading, hooks
│ ├── callbacks.py
# Terminal callbacks (clarify, sudo, approval)
│ └── gateway.py
# hermes gateway start/stop
│
├── tools/
# Tool implementations (one file per tool)
│ ├── registry.py
# Central tool registry
│ ├── approval.py
# Dangerous command detection
│ ├── terminal_tool.py
# Terminal orchestration
│ ├── process_registry.py
# Background process management
│ ├── file_tools.py
# read_file, write_file, patch, search_files
│ ├── web_tools.py
# web_search, web_extract
│ ├── browser_tool.py
# 11 browser automation tools
│ ├── code_execution_tool.py
# execute_code sandbox
│ ├── delegate_tool.py
# Subagent delegation
│ ├── mcp_tool.py
# MCP client (~2,200 lines)
│ ├── credential_files.py
# File-based credential passthrough
│ ├── env_passthrough.py
# Env var passthrough for sandboxes
│ ├── ansi_strip.py
# ANSI escape stripping
│ └── environments/
# Terminal backends (local, docker, ssh, modal, daytona, singularity)
│
├── gateway/
# Messaging platform gateway
│ ├── run.py
# GatewayRunner — message dispatch (~7,500 lines)
│ ├── session.py
# SessionStore — conversation persistence
│ ├── delivery.py
# Outbound message delivery
│ ├── pairing.py
# DM pairing authorization
│ ├── hooks.py
# Hook discovery and lifecycle events
│ ├── mirror.py
# Cross-session message mirroring
│ ├── status.py
# Token locks, profile-scoped process tracking
│ ├── builtin_hooks/
# Always-registered hooks
│ └── platforms/
# 14 adapters: telegram, discord, slack, whatsapp,
│
# signal, matrix, mattermost, email, sms,
│
# dingtalk, feishu, wecom, homeassistant, webhook
│
├── acp_adapter/
# ACP server (VS Code / Zed / JetBrains)
├── cron/
# Scheduler (jobs.py, scheduler.py)
├── plugins/memory/
# Memory provider plugins
├── environments/
# RL training environments (Atropos)
├── skills/
# Bundled skills (always available)
├── optional-skills/
# Official optional skills (install explicitly)
├── website/
# Docusaurus documentation site
└── tests/
# Pytest suite (~3,000+ tests)
Luồng dữ liệu
Phiên CLI
User input → HermesCLI.process_input()
→ AIAgent.run_conversation()
→ prompt_builder.build_system_prompt()
→ 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
Thông báo cổng
Platform event → Adapter.on_message() → MessageEvent
→ GatewayRunner._handle_message()
→ authorize user
→ resolve session key
→ create AIAgent with session history
→ AIAgent.run_conversation()
→ deliver response back through adapter
Công việc định kỳ
Scheduler tick → load due jobs from jobs.json
→ create fresh AIAgent (no history)
→ inject attached skills as context
→ run job prompt
→ deliver response to target platform
→ update job state and next_run
Thứ tự đọc đề xuất
Nếu bạn chưa quen với cơ sở mã:
- Trang này — định hướng cho bản thân
- Agent Loop Internals — cách hoạt động của AIAgent
- Prompt Assembly — xây dựng lời nhắc hệ thống
- Độ phân giải thời gian chạy của nhà cung cấp — cách chọn nhà cung cấp
- Thêm nhà cung cấp — hướng dẫn thực tế để thêm nhà cung cấp mới
- Tools Runtime — đăng ký công cụ, công văn, môi trường
- Bộ nhớ phiên — Lược đồ SQLite, FTS5, dòng phiên
- Gateway Internals — cổng nền tảng nhắn tin
- Nén ngữ cảnh & bộ nhớ đệm nhắc nhở — nén và lưu vào bộ nhớ đệm
- ACP Internals — Tích hợp IDE
- Môi trường, điểm chuẩn & tạo dữ liệu — Đào tạo RL
Các hệ thống con chính
Vòng lặp đại lý
Công cụ điều phối đồng bộ ( AIAgent trong run_agent.py ). Xử lý việc lựa chọn nhà cung cấp, xây dựng nhanh chóng, thực thi công cụ, thử lại, dự phòng, gọi lại, nén và lưu giữ. Hỗ trợ ba chế độ API cho các chương trình phụ trợ của nhà cung cấp khác nhau.
Hệ thống nhắc nhở
Xây dựng và bảo trì nhanh chóng trong suốt vòng đời cuộc trò chuyện:
- **
prompt_builder.py** — Tập hợp lời nhắc hệ thống từ: tính cách (SOUL.md), bộ nhớ (MEMORY.md, USER.md), kỹ năng, tệp ngữ cảnh (AGENTS.md, .hermes.md), hướng dẫn sử dụng công cụ và hướng dẫn dành riêng cho mô hình - **
prompt_caching.py** — Áp dụng các điểm ngắt bộ đệm Anthropic cho bộ đệm ẩn tiền tố - **
context_compressor.py** — Tóm tắt các lượt hội thoại giữa khi ngữ cảnh vượt quá ngưỡng
→ Tập hợp lời nhắc, Nén ngữ cảnh & bộ nhớ đệm nhắc nhở
Giải pháp của nhà cung cấp
Trình phân giải thời gian chạy dùng chung được CLI, cổng, cron, ACP và các lệnh gọi phụ trợ sử dụng. Ánh xạ (provider, model) bộ dữ liệu thành (api_mode, api_key, base_url) . Xử lý hơn 18 nhà cung cấp, luồng OAuth, nhóm thông tin xác thực và phân giải bí danh.
→ Độ phân giải thời gian chạy của nhà cung cấp
Hệ thống công cụ
Cơ quan đăng ký công cụ trung tâm ( tools/registry.py ) với 47 công cụ đã đăng ký trên 20 bộ công cụ. Mỗi tệp công cụ tự đăng ký tại thời điểm nhập. Sổ đăng ký xử lý việc thu thập lược đồ, gửi đi, kiểm tra tính khả dụng và gói lỗi. Công cụ đầu cuối hỗ trợ 6 chương trình phụ trợ (cục bộ, Docker, SSH, Daytona, Modal, Singularity).
Sự kiên trì của phiên
Lưu trữ phiên dựa trên SQLite với tìm kiếm toàn văn FTS5. Các phiên có tính năng theo dõi dòng dõi (phiên gốc/con qua các lần nén), cách ly trên mỗi nền tảng và ghi nguyên tử với khả năng xử lý tranh chấp.
Cổng nhắn tinQuy trình chạy dài với 14 bộ điều hợp nền tảng, định tuyến phiên hợp nhất, ủy quyền người dùng (danh sách cho phép + ghép nối DM), gửi lệnh gạch chéo, hệ thống hook, đánh dấu cron và bảo trì nền.
Hệ thống plugin
Ba nguồn khám phá: ~/.hermes/plugins/ (người dùng), .hermes/plugins/ (dự án) và điểm vào pip. Các plugin đăng ký các công cụ, hook và lệnh CLI thông qua API ngữ cảnh. Nhà cung cấp bộ nhớ là loại plugin chuyên biệt trong plugins/memory/ .
→ Hướng dẫn plugin, Plugin nhà cung cấp bộ nhớ
Cron
Nhiệm vụ tác nhân hạng nhất (không phải nhiệm vụ trình bao). Lưu trữ việc làm dưới dạng JSON, hỗ trợ nhiều định dạng lịch trình, có thể đính kèm các kỹ năng và tập lệnh cũng như phân phối tới bất kỳ nền tảng nào.
Tích hợp ACP
Hiển thị Hermes với tư cách là tác nhân biên tập gốc trên stdio/JSON-RPC cho VS Code, Zed và JetBrains.
RL / Môi trường / Quỹ đạo
Khung môi trường đầy đủ để đánh giá và đào tạo RL. Tích hợp với Atropos, hỗ trợ nhiều trình phân tích cú pháp cuộc gọi công cụ và tạo quỹ đạo định dạng ShareGPT.
→ Môi trường, điểm chuẩn và tạo dữ liệu, Quỹ đạo và định dạng đào tạo
Nguyên tắc thiết kế
| Nguyên tắc | Ý nghĩa của nó trong thực tế |
|---|---|
| Ổn định nhanh chóng | Lời nhắc hệ thống không thay đổi giữa cuộc trò chuyện. Không có đột biến phá bộ đệm ngoại trừ hành động rõ ràng của người dùng ( /model ). |
| Việc thực thi có thể quan sát được | Mọi lệnh gọi công cụ đều được hiển thị cho người dùng thông qua lệnh gọi lại. Cập nhật tiến trình trong CLI (spinner) và cổng (tin nhắn trò chuyện). |
| Có thể gián đoạn | Lệnh gọi API và thực thi công cụ có thể bị hủy giữa chừng do tín hiệu hoặc đầu vào của người dùng. |
| Lõi bất khả tri về nền tảng | Một lớp AIAgent phục vụ máy chủ CLI, cổng, ACP, lô và API. Sự khác biệt về nền tảng tồn tại ở điểm vào chứ không phải ở tác nhân. |
| Khớp nối lỏng lẻo | Các hệ thống con tùy chọn (MCP, plugin, nhà cung cấp bộ nhớ, môi trường RL) sử dụng mẫu đăng ký và kiểm soát cổng check_fn, không phải phần phụ thuộc cứng. |
| Cách ly hồ sơ | Mỗi cấu hình ( hermes -p <name> ) có HERMES_HOME, cấu hình, bộ nhớ, phiên và cổng PID riêng. Nhiều hồ sơ chạy đồng thời. |
Chuỗi phụ thuộc tệp
tools/registry.py (no deps — imported by all tool files)
↑
tools/*.py (each calls registry.register() at import time)
↑
model_tools.py (imports tools/registry + triggers tool discovery)
↑
run_agent.py, cli.py, batch_runner.py, environments/
Chuỗi này có nghĩa là việc đăng ký công cụ diễn ra tại thời điểm nhập, trước khi bất kỳ phiên bản tác nhân nào được tạo. Việc thêm một công cụ mới yêu cầu nhập vào danh sách _discover_tools() của model_tools.py.