docs/en/entity-map.mdXem bản gốc Bản dịch đầy đủ theo đúng cấu trúc tài liệu; code, liên kết và định danh kỹ thuật được giữ nguyên.
Bản đồ thực thể (Ranh giới thực thể hệ thống)
agent Hermes có nhiều thực thể hơn một agent thông thường vì nó đồng thời phải đối mặt với "nhiều nguồn thông báo" và "nhiều môi trường thực thi".
Tài liệu này giúp bạn tách các thực thể này theo lớp để mọi thứ luôn rõ ràng khi bạn tìm hiểu.
Tổng quan
Message Source Layer
- CLI user input
- Telegram / Discord / WeChat / ... messages
- Scheduled task triggers
Ingress Translation Layer
- Platform Adapter (converts platform messages into a unified format)
- MessageEvent (unified message format)
- Gateway (routes to the correct session)
Conversation Layer
- AIAgent instance (one per message, or one long-lived instance in CLI mode)
- messages[] (current conversation history)
- system prompt (assembled from multiple sources, cached for reuse)
Tools & Intelligence Layer
- Tool Entry (a single tool in the registry)
- Skill (capability file managed by the agent)
- Memory (persistent cross-session knowledge)
- Approval (dangerous command approval)
- Subagent (child executor with isolated context)
Execution Layer
- Terminal Backend (where commands run)
- MCP Server (external capability integration)
Persistence Layer
- SessionDB (SQLite sessions and messages)
- SOUL.md / MEMORY.md / USER.md (files)
- skills/ (skill directory)
- config.yaml + .env (configuration)
- jobs.json (scheduled tasks)
Những khái niệm thường bị nhầm lẫn nhất
Mục nhập CLI so với mục nhập cổng
| CLI | Cổng | |
|---|---|---|
| Người dùng ở đâu | Trong một terminal | Telegram / Bất hòa / WeChat / ... |
| Vòng đời AIAgent | Một phiên bản chạy từ đầu đến cuối | Một phiên bản mới được tạo cho mỗi tin nhắn |
| Lịch sử hội thoại được thông qua như thế nào | Phiên bản duy trì nó trong nội bộ | Được tải từ SQLite và chuyển sang phiên bản mới |
| Họ chia sẻ điều gì | Cuối cùng cả hai đều gọi run_conversation() | Cuối cùng cả hai đều gọi run_conversation() |
Điểm mấu chốt: vòng lặp cốt lõi hoàn toàn giống nhau. Điểm khác biệt duy nhất là cách gửi tin nhắn và cách gửi trả lời.
Bộ điều hợp nền tảng so với phần cuối của terminal
Đây là cặp đôi mà người mới bắt đầu thường nhầm lẫn nhất.
| Bộ điều hợp nền tảng | Phần cuối của terminal | |
|---|---|---|
| Nó quản lý những gì | Thông báo nền tảng nào đến từ | Lệnh chạy ở đâu |
| Ví dụ | Bộ chuyển đổi Telegram, bộ chuyển đổi WeChat | Phụ trợ Docker, phụ trợ SSH |
| Lớp nào | Lớp dịch xâm nhập | Lớp thực thi |
| Họ có phụ thuộc vào nhau không | Không | Không |
Bạn có thể chạy lệnh bên trong Docker trong khi nhận tin nhắn từ Telegram. Hai người hoàn toàn độc lập.
Công cụ so với kỹ năng
| Công cụ | Kỹ năng | |
|---|---|---|
| Ai viết nó | Nhà phát triển, mã hóa cứng | agent tạo/chỉnh sửa khi chạy |
| Nó sống ở đâu | Tệp nguồn Python | SKILL.md trong thư mục Skills/ |
| Cách nó thực thi | Cơ quan đăng ký gửi trực tiếp đến người xử lý | Được thực hiện gián tiếp thông qua các công cụ hiện có (ví dụ: terminal) |
| Nó có thể được sửa đổi | Yêu cầu thay đổi mã | agent có thể tự sửa đổi nó |
Kỹ năng không phải là sự thay thế cho các công cụ. Kỹ năng là "phương pháp mà agent sử dụng để thực hiện mọi việc bằng các công cụ."
Công cụ so với Công cụ MCP
| Công cụ tích hợp | Công cụ MCP | |
|---|---|---|
| Nguồn | Tự đăng ký bằng mã | Được hiển thị bởi Máy chủ MCP bên ngoài |
| model nhìn thấy nó như thế nào | Hoàn toàn giống nhau | Hoàn toàn giống nhau |
| Thực hiện thực tế | Trình xử lý cục bộ | Gửi đến máy chủ bên ngoài thông qua giao thức MCP |
Minh bạch đối với mô hình - nó không biết và không cần biết liệu một công cụ được tích hợp sẵn hay bên ngoài.
Bộ nhớ so với phiên
| Ký ức | Phiên | |
|---|---|---|
| Độ chi tiết | Thông tin chéo phiên được tuyển chọn | Tất cả tin nhắn từ một cuộc trò chuyện hoàn chỉnh |
| Khối lượng | Nhỏ (nên ngắn gọn) | Lớn (một cho mỗi cuộc trò chuyện) |
| Nó sống ở đâu | BỘ NHỚ.md / NGƯỜI DÙNG.md | SQLite |
| Ai viết nó | agent chủ động | Hệ thống, tự động |
Phiên là một ảnh chụp nhanh cuộc trò chuyện hoàn chỉnh. Bộ nhớ là thông tin mà agent coi là "hữu ích trong tương lai".
SOUL.md so với MEMORY.md so với HERMES.md
| SOUL.md | BỘ NHỚ.md | HERMES.md | |
|---|---|---|---|
| Nó là gì | Nhân cách | Ghi chú của agent | Quy tắc dự án |
| Ai viết nó | Người dùng | agent | Nhà phát triển |
| Nó sống ở đâu | HERMES_HOME | HERMES_HOME | Thư mục dự án |
| Tần suất thay đổi | Hiếm | Cập nhật thường xuyên | Đã sửa cho mỗi dự án |
| Mục đích | Xác định ai là agent | Ghi nhớ sở thích của người dùng và bối cảnh dự án | Cho agent biết các quy định của dự án này |
Cả ba đều được đưa vào dấu nhắc hệ thống, nhưng về cơ bản chúng khác nhau về bản chất.
Phiên bản AIAgent so với agent phụ
| AIAgent (chính) | agent phụ | |
|---|---|---|
| Ai tạo ra nó | CLI hoặc Cổng | agent chính, thông qua công cụ đại biểu |
| tin nhắn | Toàn bộ lịch sử của cuộc trò chuyện chính | Danh sách tin nhắn độc lập |
| Mục đích | Thực hiện yêu cầu của người dùng | Hoàn thành một nhiệm vụ phụ và trả về một bản tóm tắt |
| Ngân sách lặp lại | Chia sẻ với phụ huynh | Chia sẻ với phụ huynh |
Giá trị của subagent: chuyển công việc khám phá sang một bối cảnh rõ ràng mà không làm ảnh hưởng đến cuộc trò chuyện chính.
Tham khảo nhanh
| Thực thể | Lớp | Nơi Nó Sống |
|---|---|---|
| Tin nhắn của người dùng | Lớp nguồn tin nhắn | API terminal/nền tảng |
| Tin nhắnSự kiện | Lớp dịch xâm nhập | Nội bộ tới Cổng |
| Bộ điều hợp nền tảng | Lớp dịch xâm nhập | cổng/nền tảng/ |
| agent AIA | Lớp hội thoại | Bộ nhớ runtime |
| tin nhắn[] | Lớp hội thoại | Bộ nhớ runtime |
| lời nhắc hệ thống | Lớp hội thoại | Bộ đệm runtime + SQLite |
| Nhập công cụ | Lớp công cụ & thông minh | Đăng ký công cụ |
| Kỹ năng | Lớp công cụ & thông minh | kỹ năng/ thư mục |
| Ký ức | Lớp công cụ & thông minh | BỘ NHỚ.md / NGƯỜI DÙNG.md |
| Phê duyệt | Lớp công cụ & thông minh | runtime + bộ đệm phiên |
| agent phụ | Lớp công cụ & thông minh | runtime (ví dụ độc lập) |
| Phần cuối của terminal | Lớp thực thi | Quản lý môi trường |
| Máy chủ MCP | Lớp thực thi | Khách hàng MCP |
| Phiên | Lớp kiên trì | SQLite |
| Cấu hình | Lớp kiên trì | config.yaml + .env |
| Công việc định kỳ | Lớp kiên trì | việc làm.json |
Cách sử dụng bản đồ này
Bạn không cần phải ghi nhớ nó. Bất cứ khi nào bạn nhầm lẫn hai thuật ngữ, hãy đến đây để kiểm tra xem chúng có thuộc cùng một lớp hay không. Nếu không thì chúng không phải là cùng một loại -- cho dù tên của chúng trông giống nhau đến đâu.
Trong Một Câu
agent Hermes thêm "Lớp dịch xâm nhập" và "Lớp môi trường thực thi" bên trên một agent thông thường. Hai lớp này cho phép nó chạy trên nhiều nền tảng. Hãy hiểu rõ ranh giới của chúng và các chương còn lại sẽ dễ theo dõi hơn nhiều.