Tiếng Anh | 中文

Tìm hiểu Hermes Agent

Xây dựng một AI agent tự động ở cấp độ sản xuất từ đầu bằng Python. hướng dẫn ưu tiên code gồm 27 chương bao gồm vòng lặp agent, hệ thống công cụ, tính bền vững của phiên, bộ nhớ, kỹ năng, nén ngữ cảnh, MCP, cổng đa nền tảng (Telegram / Discord / Slack / WeChat) và khả năng tự tiến hóa dựa trên RL — lấy cảm hứng từ Hermes Agent.

Mỗi chương đều có một triển khai tham chiếu có thể chạy được trong agents/sNN_*.py, đi kèm với lời giải thích bằng văn xuôi bên dưới docs/en/ (và docs/zh/ cho nhánh tiếng Trung). Đọc, chạy, chỉnh sửa, lặp lại.

repo này không cố gắng phản ánh mọi chi tiết sản phẩm từ cơ sở mã Hermes Agent. Nó tập trung vào các cơ chế thực sự quyết định liệu một agent có thể hoạt động tự chủ trên các nền tảng hay không:

• vòng hội thoại
• đăng ký và gửi công cụ
• tính kiên trì của phiên
• lắp ráp prompt
• nén ngữ cảnh
• quản lý trí nhớ và kỹ năng
• hệ thống kỹ năng
• sự cho phép và an toàn
• cổng đa nền tảng
• backend terminal
• lập kế hoạch
• định tuyến khả năng bên ngoài

Mục tiêu rất đơn giản:

hiểu rõ về cốt lõi thiết kế thực sự để bạn có thể tự xây dựng lại nó.

Repo này thực sự dạy gì

Đầu tiên là một câu:

Mô hình thực hiện lý luận. harness mang lại cho mô hình một môi trường làm việc trải rộng trên các nền tảng, duy trì qua các phiên và quản lý các kỹ năng của chính mô hình đó.

Môi trường làm việc đó được tạo thành từ một số bộ phận hợp tác:

• Agent Loop: gửi tin nhắn đến mô hình, thực hiện lệnh gọi công cụ, nối kết quả, tiếp tục
• Tool System: lớp điều phối tự đăng ký - bàn tay của agent
• Session Store: SQLite với FTS5 — bộ nhớ hội thoại vẫn tồn tại khi khởi động lại
• Prompt Builder: tập hợp các lời nhắc hệ thống từ tính cách, bộ nhớ, cấu hình và ngữ cảnh
• Context Compression: giữ cửa sổ hoạt động nhỏ khi cuộc trò chuyện kéo dài
• Memory & Skills: kiến thức bền vững và các tập tin kỹ năng do agent quản lý
• Permission System: phát hiện các lệnh nguy hiểm trước khi thực hiện
• Gateway: một vòng lặp agent duy nhất lắng nghe trên Telegram, Discord, Slack, WeChat, v.v.
• Terminal Backends: chạy lệnh cục bộ, trong Docker, qua SSH hoặc trên nền tảng không có máy chủ
• Cron / MCP / Voice: phát triển lõi agent đơn thành một nền tảng làm việc đầy đủ

Đây là lời hứa giảng dạy của repo:

• dạy dòng chính theo thứ tự rõ ràng
• giải thích các khái niệm xa lạ trước khi dựa vào chúng
• bám sát cấu trúc hệ thống thực
• tránh khiến người học chìm đắm trong những chi tiết không liên quan về sản phẩm

Repo này cố tình không dạy điều gì

Repo này không cố gắng bảo tồn mọi chi tiết tồn tại trong hệ thống sản xuất.

Nếu một chi tiết không phải là trọng tâm trong mô hình hoạt động cốt lõi của tổng đài viên thì chi tiết đó sẽ không chiếm ưu thế trong quá trình giảng dạy. Điều đó bao gồm những thứ như:

• đóng gói, mảnh Nix và cơ chế phát hành
• trang đích và tài sản tiếp thị
• đăng ký doanh nghiệp và nối dây thanh toán
• đo từ xa và phân tích
• Đường dẫn đào tạo RL và nội bộ người chạy hàng loạt
• các yêu cầu API dành riêng cho nền tảng (phân tích cú pháp XML của WeChat, bàn phím nội tuyến Telegram)
• mỹ phẩm da / công cụ chủ đề
• logic di cư lịch sử

Những chi tiết đó có thể quan trọng trong sản xuất. Họ không thuộc về trung tâm của lộ trình giảng dạy 0-1.

Đây là dành cho ai

Người đọc giả định:

• biết Python cơ bản
• hiểu các hàm, lớp, cơ bản về async/await
• có thể hoàn toàn mới đối với hệ thống agent hoặc bot đa nền tảng

Vì vậy, repo cố gắng giữ một số quy tắc giảng dạy mạnh mẽ:

• giải thích một khái niệm trước khi sử dụng nó
• giữ một khái niệm được giải thích đầy đủ ở một nơi chính
• bắt đầu từ "nó là gì", sau đó là "tại sao nó tồn tại", rồi "làm thế nào để triển khai nó"
• tránh buộc người mới bắt đầu phải lắp ráp hệ thống từ các mảnh rời rạc

Thứ tự đọc đề xuất

• Tổng quan: docs/en/s00-architecture-overview.md
• Thứ tự đọc mã: docs/en/s00f-code-reading-order.md
• Bảng thuật ngữ: docs/en/glossary.md
• Phạm vi giảng dạy: docs/en/teaching-scope.md
• Cấu trúc dữ liệu: docs/en/data-structures.md

Nếu đây là chuyến thăm đầu tiên của bạn, hãy bắt đầu ở đây

Đừng mở các chương ngẫu nhiên trước.

Con đường an toàn nhất là:

1. Đọc docs/en/s00-architecture-overview.md để có bản đồ hệ thống đầy đủ.
2. Đọc docs/en/s00f-code-reading-order.md để bạn biết nên mở tệp nguồn nào trước.
3. Thực hiện theo năm giai đoạn theo thứ tự: s01-s06 -> s07-s11 -> s12-s15 -> s16-s20 -> s21-s27.
4. Sau mỗi giai đoạn, hãy dừng lại và tự mình xây dựng lại phiên bản nhỏ nhất trước khi tiếp tục.

Nếu chương giữa và chương cuối bắt đầu mờ cùng nhau, hãy đặt lại theo thứ tự sau:

1. docs/en/data-structures.md
2. docs/en/entity-map.md
3. sau đó quay lại nội dung chương

Năm giai đoạn

1. s01-s06: xây dựng lõi agent đơn hoạt động bền bỉ
2. s07-s11: thêm thông tin — bộ nhớ, kỹ năng, an toàn, ủy quyền và cấu hình
3. s12-s15: đa nền tảng - cổng, bộ điều hợp, backend terminal và lập lịch
4. s16-s20: thêm các khả năng nâng cao - MCP, trình duyệt, giọng nói, tầm nhìn và đánh giá lý lịch
5. s21-s27: tự cải thiện — tạo kỹ năng, hook, quỹ đạo/RL, plugin, đánh giá và tối ưu hóa

Chương chính

Mục lục chương: Cần tập trung vào điều gì trong mỗi chương

Nếu đây là lần đầu tiên bạn học tài liệu này một cách có hệ thống, đừng dồn sự chú ý của bạn vào tất cả các chi tiết. Mỗi chương tập trung vào 3 nội dung:

1. Chương này bổ sung thêm những khả năng mới nào.
2. Nơi sinh sống của nhà nước chủ chốt.
3. Sau khi làm xong bạn có thể tự tay viết cơ chế tối thiểu này được không?

Phương pháp đọc cho người mới bắt đầu

Cách tiếp cận 1: Đường chính ổn định

Tốt nhất cho độc giả lần đầu tiên tiếp xúc với hệ thống agent.

Đọc theo thứ tự sau:

s00 -> s01 -> ... -> s20 -> s21 -> ... -> s27 (theo các con số; s24 chỉ là tài liệu).

Cách tiếp cận 2: Xây dựng trước, hoàn thiện sau

Tốt nhất cho độc giả "chạy rồi điền vào chỗ trống".

Đọc theo thứ tự sau:

1. s01-s06: xây dựng một agent cốt lõi với tính bền bỉ và nén ngữ cảnh
2. s07-s11: thêm bộ nhớ, kỹ năng, an toàn, ủy quyền và cấu hình
3. s12-s15: đa nền tảng, tìm hiểu cách thực thi trên nhiều môi trường
4. s16-s20: khả năng nâng cao cộng với khả năng tự đánh giá cơ bản
5. s21-s27: bước vào quá trình tự phát triển - tạo kỹ năng, móc nối, quỹ đạo, đánh giá và tối ưu hóa

Cách tiếp cận 3: Khi bạn gặp khó khăn

Nếu bạn gặp phải bức tường ở chương giữa hoặc chương cuối, đừng tiến về phía trước một cách mù quáng.

Đặt lại theo thứ tự sau:

1. docs/en/s00-architecture-overview.md
2. docs/en/data-structures.md
3. docs/en/entity-map.md
4. chương bạn đang mắc kẹt

Khi người đọc thực sự gặp khó khăn, thường thì đó không phải là "Tôi không thể đọc được mã" mà là:

• cơ chế này cắm vào lớp nào?
• cấu trúc dữ liệu nào giữ trạng thái này?
• sự khác biệt giữa thuật ngữ này và thuật ngữ khác trông giống nhau là gì?

Bắt đầu nhanh

git clone <repo-url>
cd learn-hermes-agent
pip install -r requirements.txt
cp .env.example .env

Sau đó định cấu hình khóa API của bạn trong .envvà chạy:

python agents/s01_agent_loop.py

Thứ tự đề xuất:

1. Chạy s01 và đảm bảo vòng lặp tối thiểu thực sự hoạt động.
2. Đọc s00, sau đó di chuyển qua s01 -> s06 theo thứ tự.
3. Chỉ sau khi lõi agent đơn cộng với tính bền bỉ của nó cảm thấy ổn định, hãy tiếp tục vào s07 -> s11.
4. Chuyển sang các chương về cổng và nền tảng s12 -> s15 chỉ sau khi agent cốt lõi có ý nghĩa.
5. Tiếp tục s16 -> s20, sau đó là các chương tự tiến hóa s21 -> s27.

Cách đọc từng chương

Mỗi chương sẽ dễ tiếp thu hơn nếu bạn giữ nguyên nhịp đọc:

1. vấn đề gì sẽ xuất hiện nếu không có cơ chế này
2. khái niệm mới có ý nghĩa gì
3. việc triển khai đúng nhỏ nhất sẽ như thế nào
4. nơi nhà nước thực sự sống
5. cách nó cắm lại vào vòng lặp
6. Dừng lại ở đâu trước, và điều gì có thể đợi đến sau

Nếu bạn tiếp tục hỏi:

• "Đây là cốt lõi chính hay chỉ là chi tiết phụ?"
• "Tiểu bang này thực sự sống ở đâu?"

quay lại:

• docs/en/teaching-scope.md
• docs/en/data-structures.md
• docs/en/entity-map.md

Cấu trúc repository

learn-hermes-agent/
├── agents/              # runnable Python reference implementations per chapter (s24 is an exception, see below)
├── docs/zh/             # Chinese mainline docs
├── docs/en/             # English docs
├── illustrations/       # chalkboard-style diagrams for each chapter
├── tests/               # smoke tests
├── web/                 # web teaching platform (optional)
├── .env.example         # environment variable template
└── requirements.txt     # Python dependencies

Lưu ý: s24 Plugin Architecture hiện chỉ gửi kèm tài liệu (docs/en/s24-plugin-architecture.md và đối tác Trung Quốc). không có agents/s24_*.py thực hiện tham khảo. Tài liệu độc lập và không chặn phần còn lại của thứ tự đọc.

Dạy đánh đổi

Để đảm bảo "có thể xây dựng từ 0 đến 1", repo này thực hiện sự cân bằng có chủ ý:

• Dạy phiên bản đúng tối thiểu trước, sau đó giải thích ranh giới mở rộng.
• Nếu cơ chế thực sự phức tạp nhưng ý tưởng cốt lõi thì không, hãy dạy ý tưởng cốt lõi trước.
• Nếu một thuật ngữ nâng cao xuất hiện, hãy giải thích nó - đừng cho rằng người đọc đã biết.
• Nếu một trường hợp biên trong hệ thống thực có giá trị giảng dạy thấp, hãy loại bỏ nó hoàn toàn.

Điều này có nghĩa là repo nhằm mục đích:

Độ trung thực cao trên các cơ chế cốt lõi, cân bằng có chủ ý ở các chi tiết ngoại vi.

Trạng thái ngôn ngữ

Tiếng Trung là dòng dạy kinh điển và là phiên bản chuyển động nhanh nhất.

• zh: được đánh giá nhiều nhất và đầy đủ nhất
• en: tất cả các chương s00-s27 đều có sẵn; Tiếng Trung được cập nhật đầu tiên

Nếu bạn muốn có lộ trình giải thích đầy đủ và được cải tiến thường xuyên nhất, trước tiên hãy sử dụng tài liệu tiếng Trung.

Mục tiêu cuối cùng

Đến cuối repo, bạn sẽ có thể trả lời rõ ràng những câu hỏi sau:

• trạng thái tối thiểu mà một agent tự trị cần duy trì qua các phiên là gì?
• tại sao sổ đăng ký công cụ lại là trung tâm năng lực của agent?
• làm cách nào để một vòng lặp hội thoại có thể mở rộng tới hơn 15 nền tảng nhắn tin?
• mỗi bộ nhớ, kỹ năng, quyền, nén ngữ cảnh và khôi phục lỗi giải quyết được vấn đề gì?
• làm thế nào để phần phụ trợ của terminal loại bỏ môi trường thực thi?
• khi nào hệ thống một agent nên phát triển thành cổng, lập lịch, MCP và thoại?

Nếu bạn có thể trả lời những câu hỏi đó một cách rõ ràng và tự mình xây dựng một hệ thống tương tự thì repo này đã hoàn thành công việc của nó.

---

Đây không phải là "sao chép từng dòng mã nguồn." Đây là "nắm bắt những thiết kế thực sự quan trọng rồi tự mình xây dựng nó."