Kiến trúc
Trang này là bản đồ cấp cao nhất về nội bộ của Đại lý Hermes. 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. │ │ 70+ tools │ │
│ │ │ │ Anthropic │ │ 28 toolsets │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────┴─────────────────┴─────────────────┴───────────────────────┘
│ │
▼ ▼
┌───────────────────┐ ┌──────────────────────┐
│ Session Storage │ │ Tool Backends │
│ (SQLite + FTS5) │ │ Terminal (7 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
`text
Hermes-agent/
├── run_agent.py # AIAgent — core conversation loop (large file)
├── CLI.py # HermesCLI — interactive terminal UI (large file)
├── 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_engine.py # ContextEngine ABC (pluggable)
│ ├── context_compressor.py # Default engine — lossy summarization
│ ├── 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 (large file)
│ ├── 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 (large file)
│ ├── 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 # 10 browser automation tools
│ ├── code_execution_tool.py # execute_code sandbox
│ ├── delegate_tool.py # Subagent delegation
│ ├── MCP_tool.py # MCP CLIent (large file)
│ ├── 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 (large file)
│ ├── 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/ # Extension point for always-registered hooks (none shipped)
│ └── platforms/ # 20 adapters: Telegram, Discord, Slack, WhatsApp,
│ # Signal, Matrix, Mattermost, email, sms,
│ # DingTalk, Feishu, WeCom, WeCom_callback, weixin,
│ # BlueBubbles, qqbot, homeassistant, webhook, API_server,
│ # yuanbao
│
├── ACP_adapter/ # ACP server (VS Code / Zed / JetBrains)
├── cron/ # Scheduler (jobs.py, scheduler.py)
├── plugins/memory/ # Memory provider plugins
├── plugins/context_engine/ # Context engine plugins
├── 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
`text
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
`text
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ỳ
`text
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ã:
1. **Trang này** — định hướng cho bản thân
2. **[Agent Loop Internals](./agent-loop.md)** — cách thức hoạt động của AIAgent
3. **[Prompt Assembly](./prompt-assembly.md)** — xây dựng nhắc nhở hệ thống
4. **[Provider Runtime Resolution](./provider-runtime.md)** — cách chọn nhà cung cấp
5. **[Adding Providers](./adding-providers.md)** — hướng dẫn thực tế để thêm nhà cung cấp mới
6. **[Tools Runtime](./tools-runtime.md)** — đăng ký công cụ, công văn, môi trường
7. **[Session Storage](./session-storage.md)** — Lược đồ SQLite, FTS5, dòng phiên
8. **[Gateway Internals](./gateway-internals.md)** — cổng nền tảng nhắn tin
9. **[Context Compression & Prompt Caching](./context-compression-and-caching.md)** — nén và lưu vào bộ nhớ đệm
10. **[ACP Internals](./ACP-internals.md)** — Tích hợp IDE
## 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.`→ [Agent Loop Internals](./agent-loop.md)
### 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 dừng 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`→ [Prompt Assembly](./prompt-assembly.md), [Context Compression & Prompt Caching](./context-compression-and-caching.md)
### 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ạ các bộ dữ liệu
(provider, model)
` 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.`→ [Provider Runtime Resolution](./provider-runtime.md)
### Hệ thống công cụ
Cơ quan đăng ký công cụ trung tâm (
`tools/registry.py
) với hơn 70 công cụ đã đăng ký trên ~28 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ác công cụ đầu cuối hỗ trợ 7 chương trình phụ trợ (cục bộ, Docker, SSH, Daytona, Modal, Singularity, Vercel Sandbox).`→ [Tools Runtime](./tools-runtime.md)
### 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.`→ [Session Storage](./session-storage.md)
### Cổng nhắn tin
Quy trình chạy dài với 20 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.`→ [Gateway Internals](./gateway-internals.md)
### 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. Tồn tại hai loại plugin chuyên dụng: nhà cung cấp bộ nhớ (
`plugins/memory/
) và công cụ ngữ cảnh (
`plugins/context_engine/
). Cả hai đều là một lựa chọn duy nhất - mỗi lần chỉ một trong số đó có thể hoạt động, được định cấu hình thông qua
`Hermes plugins
` hoặc
`config.yaml
.`→ [Plugin Guide](/docs/guides/build-a-Hermes-plugin), [Memory Provider Plugin](./memory-provider-plugin.md)`###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.`→ [Cron Internals](./cron-internals.md)
### 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.`→ [ACP Internals](./ACP-internals.md)
### Quỹ đạo
Tạo quỹ đạo có định dạng ShareGPT từ các phiên tác nhân để tạo dữ liệu đào tạo.`→ [Trajectories & Training Format](./trajectory-format.md)
## 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
``` text
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. Bất kỳ tệp
`tools/*.py
` nào có lệnh gọi
`registry.register()
` cấp cao nhất đều được tự động phát hiện - không cần danh sách nhập thủ công.