Tổng quan plugin

Plugin mở rộng Nagare bằng công cụ mới, kênh trò chuyện mới (như Telegram) hoặc system prompt riêng. Mỗi plugin là một tiến trình độc lập do gateway khởi chạy, giao tiếp với gateway qua IPC:

Linux/macOS: Unix socket ~/.nagare/nagare-plugin.sock.
Windows: named pipe \\.\pipe\nagare-plugin.

Bạn có thể viết plugin bằng Go hoặc Rust.

Cấu trúc dự án

my-plugin/
├── metadata.json
├── go.mod            # hoặc Cargo.toml
└── main.go           # hoặc src/main.rs

metadata.json

{
  "package_name": "com.example.hello",
  "name": "Hello plugin",
  "version": "1.0.0",
  "api_version": "1",
  "author": "Your Name",
  "features": ["plugin_tool"]
}

Trường	Bắt buộc	Mô tả
`package_name`	Có	Định danh duy nhất. Chỉ gồm chữ, số, `_`, `.`, `-`; phải bắt đầu và kết thúc bằng chữ hoặc số; không chứa `..` hay dấu gạch chéo.
`name`	Có	Tên hiển thị.
`version`	Có	Phiên bản plugin.
`api_version`	Có	Phiên bản API plugin, hiện là `"1"`.
`author`	Có	Tác giả.
`features`	Không	Danh sách quyền plugin yêu cầu (xem bên dưới).
`bin`	Không	Bản đồ hệ điều hành → đường dẫn tương đối tới tệp thực thi. `nagare plugin build` tự điền trường này.

Feature (quyền)

Plugin chỉ được dùng các chức năng mà nó khai báo trong features:

Feature	Cho phép
`plugin_tool`	Đăng ký công cụ và danh mục công cụ mới.
`chat`	Mở kênh trò chuyện, gửi tin nhắn, nhận phản hồi và gửi kết quả phê duyệt.
`model_provider`	Đọc danh sách nhà cung cấp mô hình.
`system_prompt`	Chèn hoặc xóa system prompt của plugin.

Build gói plugin

Trong thư mục plugin, chạy:

nagare plugin build

Lệnh này:

Đọc và kiểm tra metadata.json.
Build tệp thực thi: go build nếu có go.mod, hoặc cargo build --release nếu có Cargo.toml. Thư mục không được chứa cả hai.
Tính checksum SHA-256 của tệp thực thi.
Đóng gói thành <package_name>.nagare_plugin.

Để ký số gói, thêm --sign. Xem Ký số plugin.

Quản lý plugin

Vào Settings → Plugins:

Thao tác	Mô tả
Install Plugin	Giao diện web: tải lên tệp `.nagare_plugin` (có thể kèm tệp chữ ký `.sig`). Ứng dụng desktop: nhập đường dẫn tuyệt đối tới gói.
Kích hoạt / Tắt	Bật hoặc dừng tiến trình plugin.
Cập nhật	Tải lên gói phiên bản mới. Các phiên trò chuyện được giữ nguyên.
Trạng thái	Xem PID, mức dùng CPU và bộ nhớ của plugin.
Gỡ cài đặt	Xóa plugin.

Khi cài đặt, bạn có thể nhận cảnh báo nếu gói chưa ký (unsigned) hoặc chưa xác minh được (unverified). Xem Ký số plugin.

Môi trường chạy

Gateway kiểm tra checksum tệp thực thi trước mỗi lần khởi chạy. Nếu không khớp, plugin bị đánh dấu thất bại và các plugin khác vẫn chạy bình thường. Plugin kế thừa biến môi trường của gateway, cộng thêm:

Biến	Giá trị
`NAGARE_PLUGIN_CONNECT_CODE`	Mã dùng khi bắt tay (handshake) với gateway.
`NAGARE_PLUGIN_SOCKET_PATH`	Đường dẫn socket/pipe IPC.
`NAGARE_PLUGIN_LOG_FILE`	`~/.nagare/logs/plugins/<package_name>.log`
`NAGARE_PLUGIN_CONFIG_DIR`	`~/.nagare/configs/plugins/<package_name>`
`NAGARE_PLUGIN_DATA_DIR`	`~/.nagare/data/plugins/<package_name>`

Các SDK đọc những biến này tự động.

Tin nhắn trò chuyện

Với feature chat, plugin nhận phản hồi của agent dưới dạng các đoạn JSON. Mỗi đoạn có trường type:

`type`	Nội dung
`TEXT_MESSAGE`	Đoạn văn bản (`content`).
`APPROVAL_REQUEST_MESSAGE`	Yêu cầu phê duyệt công cụ (`requestID`, `title`).
`AGENT_ERROR_MESSAGE`	Lỗi (`code`, `error`).
`AGENT_STARTED_MESSAGE`, `AGENT_COMPLETED_MESSAGE`	Agent bắt đầu, hoàn tất.
`TOOL_CALL_MESSAGE`, `TOOL_RESULT_MESSAGE`	Gọi công cụ và kết quả.
`REASONING_MESSAGE`	Nội dung suy luận của mô hình.

Plugin Telegram tích hợp sẵn là ví dụ hoàn chỉnh. Xem mã nguồn tại plugins/telegram.

Bắt đầu

Hướng dẫn sử dụng

Phát triển plugin

Tham chiếu

Tổng quan plugin

Cấu trúc dự án

metadata.json

Feature (quyền)

Build gói plugin

Quản lý plugin

Môi trường chạy

Tin nhắn trò chuyện

​Cấu trúc dự án

​metadata.json

​Feature (quyền)

​Build gói plugin

​Quản lý plugin

​Môi trường chạy

​Tin nhắn trò chuyện

Cấu trúc dự án

metadata.json

Feature (quyền)

Build gói plugin

Quản lý plugin

Môi trường chạy

Tin nhắn trò chuyện