> ## 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.

# Công cụ tích hợp

> Danh sách công cụ Nagare dùng để thao tác với hệ thống và cơ chế phê duyệt trước khi chạy thao tác có rủi ro.

Công cụ (tool) là các hành động mà Nagare có thể thực hiện trên máy của bạn. Bạn không cần gọi công cụ trực tiếp: chỉ cần mô tả việc muốn làm bằng ngôn ngữ tự nhiên, Nagare sẽ chọn và gọi công cụ phù hợp.

## Cách Nagare tìm công cụ

Công cụ được nhóm theo **danh mục (category)**. Thay vì nạp toàn bộ công cụ vào mỗi lượt trò chuyện, Nagare dùng hai công cụ định tuyến:

1. `find_tool_by_categories`: tìm các công cụ thuộc một hoặc nhiều danh mục.
2. `execute_tool`: gọi công cụ vừa tìm được theo tên, kèm tham số.

Plugin có thể đăng ký thêm công cụ và danh mục mới. Xem [Tổng quan plugin](https://docs.nagare.smtdfc.net/plugins/overview.md).

## Danh sách công cụ

> [!NOTE]
>
> Công cụ có dấu ✅ ở cột **Phê duyệt** luôn hỏi bạn trước khi chạy.

### Quản lý tiến trình (`process_management`)

| Công cụ | Mô tả | Phê duyệt |
| - | - | - |
| `list_process_tool` | Liệt kê tiến trình, lọc theo RAM (`min_memory_mb`), CPU (`min_cpu_percent`), tên (`name_query`, `exclude_name`), sắp xếp theo `ram` hoặc `cpu` và giới hạn số kết quả. | |
| `create_process_tool` | Khởi chạy một tiến trình tách rời và trả về PID. Nhận `command`, `args` và `working_dir`; không dùng cú pháp shell. | ✅ |
| `kill_process_tool` | Kết thúc tiến trình theo PID. | ✅ |

### Tệp tin (`filesystem`)

| Công cụ | Mô tả | Phê duyệt |
| - | - | - |
| `get_user_directories_tool` | Lấy các thư mục người dùng: home, downloads, desktop, documents, temp, config, cache. | |
| `list_directory_tool` | Liệt kê tệp và thư mục tại một đường dẫn. | |
| `read_file_tool` | Đọc nội dung tệp văn bản. | |
| `write_file_tool` | Tạo hoặc cập nhật tệp văn bản (`overwrite` để ghi đè). | ✅ |
| `delete_file_tool` | Xóa một tệp. Không cho phép xóa thư mục. | ✅ |

### Hệ thống

| Công cụ | Danh mục | Mô tả | Phê duyệt |
| - | - | - | - |
| `power_control_tool` | `power_control` | Tắt máy, khởi động lại, ngủ (suspend), ngủ đông (hibernate) hoặc đăng xuất. | ✅ |
| `volume_control_tool` | `audio_management` | Đặt, đọc, tắt/bật tiếng, tăng hoặc giảm âm lượng. | |
| `get_active_display_tool` | `system` | Lấy số màn hình đang hoạt động. | |
| `screenshot_tool` | `system` | Chụp màn hình theo chỉ số và lưu ảnh PNG vào thư mục `~/.nagare/artifacts`. | |
| `open_browser_tool` | `browser` | Mở một hoặc nhiều URL trong trình duyệt. | ✅ |
| `time_tool` | `timing` | Lấy ngày giờ hiện tại, có thể theo múi giờ. | |

### Thông tin và tra cứu

| Công cụ | Danh mục | Mô tả |
| - | - | - |
| `weather_tool` | `weather` | Lấy thời tiết hiện tại (nhiệt độ, gió, độ ẩm, mã thời tiết) theo vĩ độ và kinh độ. |
| `search_tool` | `research` | Tìm kiếm thông tin từ một nguồn. Hiện hỗ trợ `Wikipedia`. |
| `fetch_content_tool` | `research` | Lấy toàn bộ nội dung của một kết quả tìm kiếm theo ID. |

### Lịch định kỳ (`cronjob_management`)

| Công cụ | Mô tả |
| - | - |
| `create_cronjob_tool` | Tạo cron job chạy một yêu cầu theo lịch. Xem [Cron job](https://docs.nagare.smtdfc.net/guides/cronjobs.md). |

## Phê duyệt công cụ

Với các công cụ có thể thay đổi hệ thống, Nagare dừng lại và gửi **yêu cầu phê duyệt** (human-in-the-loop) đến kênh bạn đang trò chuyện:

* **Giao diện web / desktop**: hiển thị hộp phê duyệt ngay trong cuộc trò chuyện.
* **Telegram**: gửi tin nhắn có nút **Approve / Reject**, hoặc dùng lệnh `/approve <request-id>` và `/reject <request-id>`.

Quy tắc:

* Nếu bạn không phản hồi trong **5 phút**, yêu cầu hết hạn và công cụ **không** được chạy.
* Nếu không có kênh nào nhận được yêu cầu phê duyệt, công cụ bị từ chối (fail closed) thay vì chạy âm thầm.
* `write_file_tool` và `delete_file_tool` còn yêu cầu tham số `confirm` bằng `true`.


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