> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nagare.smtdfc.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Tổng quan plugin

> Cách plugin Nagare hoạt động, cấu trúc gói plugin, quyền (feature) và cách cài đặt, quản lý 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](https://docs.nagare.smtdfc.net/plugins/go-sdk.md) hoặc [Rust](https://docs.nagare.smtdfc.net/plugins/rust-sdk.md).

## Cấu trúc dự án

```text theme={null}
my-plugin/
├── metadata.json
├── go.mod            # hoặc Cargo.toml
└── main.go           # hoặc src/main.rs
```

### metadata.json

```json theme={null}
{
  "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:

```bash theme={null}
nagare plugin build
```

Lệnh này:

1. Đọc và kiểm tra `metadata.json`.
2. 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.
3. Tính checksum SHA-256 của tệp thực thi.
4. Đóng gói thành `<package_name>.nagare_plugin`.

Để ký số gói, thêm `--sign`. Xem [Ký số plugin](https://docs.nagare.smtdfc.net/plugins/signing.md).

## 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](https://docs.nagare.smtdfc.net/plugins/signing.md#canh-bao-khi-cai-dat).

## 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](https://github.com/smtdfc/nagare/tree/main/plugins/telegram).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.