Plugin

Hermes có một hệ thống plugin để thêm các công cụ, hook và tích hợp tùy chỉnh mà không cần sửa đổi mã lõi.

→ Xây dựng Plugin Hermes — hướng dẫn từng bước với ví dụ hoạt động hoàn chỉnh.

Tổng quan nhanh

Thả một thư mục vào ~/.hermes/plugins/ với mã plugin.yaml và Python:

~/.hermes/plugins/my-plugin/
├── plugin.yaml      

# manifest
├── __init__.py      

# register() — wires schemas to handlers
├── schemas.py       

# tool schemas (what the LLM sees)
└── tools.py         

# tool handlers (what runs when called)

Bắt đầu Hermes — các công cụ của bạn xuất hiện cùng với các công cụ tích hợp sẵn. Người mẫu có thể gọi họ ngay lập tức.

Ví dụ hoạt động tối thiểu

Đây là plugin hoàn chỉnh có thêm công cụ hello_world và ghi lại mọi lệnh gọi công cụ thông qua hook.

** ~/.hermes/plugins/hello-world/plugin.yaml **

name: hello-world
version: "1.0"
description: A minimal example plugin

** ~/.hermes/plugins/hello-world/__init__.py **

"""Minimal Hermes plugin — registers a tool and a hook."""


def register(ctx):
    

# --- Tool: hello_world 

---
    schema = {
        "name": "hello_world",
        "description": "Returns a friendly greeting for the given name.",
        "parameters": {
            "type": "object",
            "properties": {
                "name": {
                    "type": "string",
                    "description": "Name to greet",
                }
            },
            "required": ["name"],
        },
    }

    def handle_hello(params):
        name = params.get("name", "World")
        return f"Hello, {name}! 👋  (from the hello-world plugin)"

    ctx.register_tool("hello_world", schema, handle_hello)

    

# --- Hook: log every tool call 

---
    def on_tool_call(tool_name, params, result):
        print(f"[hello-world] tool called: {tool_name}")

    ctx.register_hook("post_tool_call", on_tool_call)

Thả cả hai tệp vào ~/.hermes/plugins/hello-world/ , khởi động lại Hermes và mô hình có thể gọi ngay hello_world . Móc in một dòng nhật ký sau mỗi lần gọi công cụ.

Các plugin dự án cục bộ trong ./.hermes/plugins/ bị tắt theo mặc định. Chỉ kích hoạt chúng cho các kho lưu trữ đáng tin cậy bằng cách đặt HERMES_ENABLE_PROJECT_PLUGINS=true trước khi khởi động Hermes.

Plugin có thể làm gì

| Năng lực | Như thế nào | |----------||------| | Thêm công cụ | ctx.register_tool(name, schema, handler) | | Thêm móc | ctx.register_hook("post_tool_call", callback) | | Thêm lệnh CLI | ctx.register_cli_command(name, help, setup_fn, handler_fn) — thêm hermes <plugin> <subcommand> | | Tiêm tin nhắn | ctx.inject_message(content, role="user") — xem Chèn tin nhắn | | Gửi tập tin dữ liệu | Path(__file__).parent / "data" / "file.yaml" | | Gói kỹ năng | Sao chép skill.md sang ~/.hermes/skills/ khi tải | | Cổng trên env vars | requires_env: [API_KEY] trong plugin.yaml — được nhắc trong hermes plugins install | | Phân phối qua pip | [project.entry-points."hermes_agent.plugins"] |

Khám phá plugin

Nguồn	Đường dẫn	Trường hợp sử dụng
Người dùng	~/.hermes/plugins/	Plugin cá nhân
Dự án	.hermes/plugins/	Các plugin dành riêng cho dự án (yêu cầu HERMES_ENABLE_PROJECT_PLUGINS=true )
pip	hermes_agent.plugins điểm vào	Gói phân phối

Móc có sẵn

Các plugin có thể đăng ký lệnh gọi lại cho các sự kiện trong vòng đời này. Xem trang Móc sự kiện để biết đầy đủ chi tiết, chữ ký gọi lại và ví dụ.

Móc	Kích hoạt khi
pre_tool_call	Trước khi bất kỳ công cụ nào thực thi
post_tool_call	Sau khi bất kỳ công cụ nào trả về
pre_llm_call	Một lần mỗi lượt, trước vòng lặp LLM - có thể trả về {"context": "..."} cho chèn ngữ cảnh vào tin nhắn người dùng
post_llm_call	Một lần trong lượt, sau vòng LLM (chỉ những lượt thành công)
on_session_start	Đã tạo phiên mới (chỉ lượt đầu tiên)
on_session_end	Kết thúc mỗi cuộc gọi run_conversation + trình xử lý thoát CLI

Quản lý plugin

hermes plugins                  

# interactive toggle UI — enable/disable with checkboxes
hermes plugins list             

# table view with enabled/disabled status
hermes plugins install user/repo  

# install from Git
hermes plugins update my-plugin   

# pull latest
hermes plugins remove my-plugin   

# uninstall
hermes plugins enable my-plugin   

# re-enable a disabled plugin
hermes plugins disable my-plugin  

# disable without removing

Việc chạy hermes plugins không có đối số sẽ khởi chạy một danh sách kiểm tra các lời nguyền tương tác (cùng giao diện người dùng với hermes tools ) nơi bạn có thể bật/tắt plugin bằng phím mũi tên và dấu cách.

Các plugin bị tắt vẫn được cài đặt nhưng bị bỏ qua trong quá trình tải. Danh sách bị vô hiệu hóa được lưu trữ trong config.yaml trong plugins.disabled :

plugins:
  disabled:
    - my-noisy-plugin

Trong phiên đang chạy, /plugins hiển thị plugin nào hiện đang được tải.

Chèn tin nhắn

Các plugin có thể đưa tin nhắn vào cuộc trò chuyện đang diễn ra bằng cách sử dụng ctx.inject_message() :

ctx.inject_message("New data arrived from the webhook", role="user")

Chữ ký: ctx.inject_message(content: str, role: str = "user") -> bool

Nó hoạt động như thế nào:- Nếu tác nhân nhàn rỗi (đợi người dùng nhập), tin nhắn sẽ được xếp hàng đợi làm đầu vào tiếp theo và bắt đầu một lượt mới.

• Nếu tác nhân đang giữa lượt (đang chạy), thông báo sẽ làm gián đoạn hoạt động hiện tại — giống như việc người dùng nhập tin nhắn mới và nhấn Enter.
• Đối với các vai trò không phải "user", nội dung có tiền tố [role] (ví dụ: [system] ... ).
• Trả về True nếu tin nhắn được xếp hàng thành công, False nếu không có tham chiếu CLI (ví dụ: ở chế độ cổng).

Điều này cho phép các plugin như trình xem điều khiển từ xa, cầu nối nhắn tin hoặc trình nhận webhook đưa tin nhắn vào cuộc trò chuyện từ các nguồn bên ngoài.

ghi chú

inject_message chỉ khả dụng ở chế độ CLI. Ở chế độ cổng, không có tham chiếu CLI và phương thức trả về False .

Xem hướng dẫn đầy đủ để biết các hợp đồng xử lý, định dạng lược đồ, hành vi hook, xử lý lỗi và các lỗi phổ biến.