# Tạo một phần mở rộng CLI

CLI `hf` hỗ trợ các phần mở rộng, là các lệnh tùy chỉnh do cộng đồng cung cấp, tích hợp liền mạch vào CLI. Các phần mở rộng được lưu trữ dưới dạng các kho GitHub công khai và có thể được cài đặt bằng một lệnh duy nhất. Sau khi cài đặt, chúng xuất hiện như các lệnh cấp cao của `hf`, giống hệt như các lệnh tích hợp sẵn.

Hệ thống này được lấy cảm hứng từ [mở rộng của GitHub CLI](https://docs.github.com/en/github-cli/github-cli/creating-github-cli-extensions). Trong hướng dẫn này, bạn sẽ học cách tạo mở rộng của riêng mình, phát hành nó và giúp người dùng dễ dàng tìm thấy.

> [!TIP]
> Để xem tài liệu dành cho người dùng về việc cài đặt và quản lý các phần mở rộng, hãy xem [tham chiếu CLI cho `hf extensions`](../package_reference/cli#hf-extensions).

## Tổng quan

Có hai loại phần mở rộng:

1. **Mở rộng script shell**: một tệp thực thi duy nhất (script bash, binary đã biên dịch, v.v.) được đặt ở gốc của kho lưu trữ.
2. **Mở rộng Python**: một gói Python tiêu chuẩn có `pyproject.toml`. Được cài đặt trong môi trường ảo cách ly để các phụ thuộc không xung đột với hệ thống của người dùng.

Cả hai loại đều chia sẻ cùng các quy ước:

- Kho lưu trữ GitHub **phải** được đặt tên là `hf-<name>` (ví dụ: `hf-claude`, `hf-mem`).
- Sau khi cài đặt, người dùng chạy tiện ích mở rộng bằng `hf <name>` (ví dụ: `hf claude`).
- Phần mở rộng được liệt kê trong `hf --help` dưới mục "Extension commands".

Khi người dùng chạy `hf extensions install [OWNER/]hf-<name>`, hệ thống trước tiên tìm tệp binary/script có tên `hf-<name>` ở gốc repository. Nếu tìm thấy, nó sẽ cài đặt dưới dạng extension shell script. Nếu không, nó sẽ chuyển sang cài đặt repository như một gói Python.

## Tạo một phần mở rộng script shell

Mở rộng script shell là loại đơn giản nhất. Bạn chỉ cần một kho GitHub có chứa tệp thực thi đặt tên là `hf-<name>` ở thư mục gốc.

> [!WARNING]
> Các phần mở rộng script shell không được hỗ trợ trên Windows. Nếu phần mở rộng của bạn phải hoạt động trên Windows, hãy tạo nó thành [phần mở rộng Python](#create-a-python-extension) thay thế.

### Ví dụ tối giản

Tạo một kho có tên `hf-hello` trên GitHub với một tệp duy nhất:

**`hf-hello`** (ở thư mục gốc của kho):

```bash
#!/usr/bin/env bash
set -euo pipefail

echo "Hello from hf-hello extension!"
echo "Arguments: $@"
```

Xong rồi! Người dùng giờ có thể cài đặt và chạy nó:

```bash
>>> hf extensions install <your-username>/hf-hello
>>> hf hello
Hello from hf-hello extension!
Arguments:
```

### Mẹo cho các phần mở rộng của script shell

- Luôn bắt đầu bằng shebang (`#!/usr/bin/env bash`) và `set -euo pipefail` để đảm bảo an toàn.
- Script nhận tất cả các đối số bổ sung do người dùng truyền vào. Ví dụ, `hf hello --name world` sẽ truyền `--name world` cho script.
- Bạn có thể truy cập token Hugging Face của người dùng qua biến môi trường `HF_TOKEN` nếu họ đã đăng nhập.
- Thêm `manifest.json` ở gốc kho để cung cấp mô tả (xem [Thêm mô tả](#add-a-description)).
- Các phụ thuộc bên ngoài (ví dụ: `fzf`, `jq`, v.v.) sẽ **không** được cài đặt tự động cùng với extension của bạn. Hãy kiểm tra các công cụ cần thiết ở đầu script và xử lý lỗi một cách thân thiện với thông báo lỗi hữu ích nếu chúng bị thiếu.

> [!TIP]
> Để xem một ví dụ thực tế, hãy xem [hanouticelina/hf-claude](https://github.com/hanouticelina/hf-claude) — một phần mở rộng shell script khởi chạy Claude Code với HF Inference Providers.

## Tạo một phần mở rộng Python

Các phần mở rộng Python là các gói Python đầy đủ được cài đặt trong môi trường ảo cách ly. Đây là lựa chọn tốt nhất khi phần mở rộng của bạn có các phụ thuộc Python hoặc logic phức tạp hơn.

### Ví dụ tối giản

Tạo một kho có tên `hf-hello` trên GitHub với cấu trúc này:

```
hf-hello/
├── pyproject.toml
└── src/
    └── hf_hello/
        ├── __init__.py
        └── cli.py
```

**`pyproject.toml`**:

```toml
[build-system]
requires = ["setuptools>=64"]
build-backend = "setuptools.backends._legacy:_Backend"

[project]
name = "hf-hello"
version = "0.1.0"
description = "A hello-world hf CLI extension"
requires-python = ">=3.10"

[project.scripts]
hf-hello = "hf_hello.cli:main"
```

**`src/hf_hello/cli.py`**:

```python
import sys

def main():
    print("Hello from hf-hello extension!")
    print(f"Arguments: {sys.argv[1:]}")

if __name__ == "__main__":
    main()
```

Phần quan trọng là điểm vào `[project.scripts]`: nó **phải** được đặt tên là `hf-<name>` (ở đây là `hf-hello`). Đây là cách CLI `hf` phát hiện và thực thi phần mở rộng của bạn.

Người dùng cài đặt và chạy theo cách tương tự:

```bash
>>> hf extensions install <your-username>/hf-hello
>>> hf hello
Hello from hf-hello extension!
Arguments: []
```

### Cách các phần mở rộng Python được cài đặt

Khi một người dùng cài đặt một phần mở rộng Python, các bước sau sẽ diễn ra:

1. Một môi trường ảo được tạo tại `~/.local/share/hf/extensions/hf-<name>/venv/`.
2. Gói của bạn được cài đặt thông qua `pip install` từ kho lưu trữ GitHub.
3. Hệ thống xác minh rằng một script console `hf-<name>` đã được tạo trong venv.

Điều này có nghĩa là các phụ thuộc của phần mở rộng của bạn được cách ly hoàn toàn — chúng sẽ không xung đột với các gói Python khác của người dùng.

> [!TIP]
> Để xem một ví dụ thực tế, hãy xem [alvarobartt/hf-mem](https://github.com/alvarobartt/hf-mem) — một phần mở rộng Python ước tính yêu cầu bộ nhớ suy luận cho các mô hình HF.

## Thêm mô tả

Mô tả giúp người dùng hiểu phần mở rộng của bạn làm gì. Nó xuất hiện trong `hf extensions list` và trong `hf --help`.

Hệ thống tìm kiếm mô tả theo thứ tự sau:

1. **`manifest.json`** ở gốc kho:

```json
{
    "description": "A short description of what your extension does"
}
```

2. **`pyproject.toml`** trường `description` (cho các phần mở rộng Python):

```toml
[project]
description = "A short description of what your extension does"
```

3. **Mô tả kho GitHub** (trường "About" trên trang kho).

Đối với các phần mở rộng Python, việc đặt `description` trong `pyproject.toml` là cách tiếp cận tự nhiên nhất. Đối với các phần mở rộng shell script, hãy sử dụng tệp `manifest.json` hoặc đặt mô tả cho kho GitHub.

## Làm cho phần mở rộng của bạn dễ được tìm thấy

Để giúp người dùng tìm thấy phần mở rộng của bạn, hãy thêm chủ đề **`hf-extension`** vào kho GitHub của bạn:

1. Truy cập kho lưu trữ của bạn trên GitHub.
2. Nhấp vào biểu tượng bánh răng bên cạnh "About" trên thanh bên phải.
3. Trong mục "Topics", thêm `hf-extension`.

Đây là một quy ước của cộng đồng giúp dễ dàng duyệt qua tất cả các phần mở rộng có sẵn trên [trang chủ đề hf-extension](https://github.com/topics/hf-extension).

Người dùng sau đó có thể tìm thấy phần mở rộng của bạn trực tiếp từ CLI bằng `hf extensions search`, liệt kê tất cả các kho GitHub được gắn thẻ với chủ đề `hf-extension`, sắp xếp theo số sao:

```bash
>>> hf extensions search
NAME   REPO                    STARS DESCRIPTION                         INSTALLED
------ ----------------------- ----- ----------------------------------- ---------
claude hanouticelina/hf-claude     2 Extension for `hf` CLI to launch... yes
agents hanouticelina/hf-agents       HF extension to run local coding...
```

Cột `INSTALLED` hiển thị các phần mở rộng đã được cài đặt cục bộ. Từ đó, người dùng có thể cài đặt bất kỳ phần mở rộng nào được liệt kê bằng `hf extensions install <repo>`.

## Kiểm tra phần mở rộng của bạn

Trong quá trình phát triển, bạn có thể cài đặt phần mở rộng của mình trực tiếp từ kho GitHub của bạn:

```bash
# Install from your repo
>>> hf extensions install <your-username>/hf-<name>

# Run it
>>> hf <name>

# Reinstall after making changes (push to GitHub first)
>>> hf extensions install <your-username>/hf-<name> --force

# Update to the latest version (only if a newer commit is available)
>>> hf extensions update <name>

# List installed extensions
>>> hf extensions list

# Remove when done
>>> hf extensions remove <name>
```

> [!TIP]
> Sử dụng `--force` để ghi đè lên phiên bản đã cài đặt trước đó khi kiểm tra các bản cập nhật.

## Cập nhật các phần mở rộng đã cài đặt

Sau khi cài đặt một phần mở rộng, bạn có thể cập nhật nó lên phiên bản mới nhất được phát hành trên GitHub:

```bash
# Update a single extension (accepts `<name>`, `hf-<name>` or `OWNER/hf-<name>`)
>>> hf extensions update hf-claude

# Check every installed extension and update the outdated ones
>>> hf extensions update
```

`hf extensions update` chỉ cập nhật các extension đã được cài đặt. Nếu extension chưa được cài đặt, một lỗi sẽ được ném ra. Các extension đã ở phiên bản mới nhất sẽ bị bỏ qua.

Phiên bản của một extension là commit mà nó được cài đặt từ đó, hiển thị dưới dạng SHA ngắn trong cột `VERSION` của `hf extensions list`. Cột `LATEST` được kiểm tra khi không có commit mới hơn nào khả dụng trên GitHub, và việc chạy một extension cũ sẽ in ra một gợi ý đề xuất `hf extensions update <name>`. Để nằm trong giới hạn tần suất yêu cầu của GitHub cho các yêu cầu không xác thực, `hf` chỉ tra cứu commit mới nhất của mỗi extension tối đa một lần mỗi ngày. Đặt `HF_HUB_DISABLE_UPDATE_CHECK=1` để tắt các kiểm tra này.

Nếu một phần mở rộng Python ngừng hoạt động vì phiên bản Python được dùng để cài đặt nó đã bị xóa (ví dụ: sau khi nâng cấp Homebrew), `hf extensions update <name>` sẽ tạo lại môi trường ảo của nó.

## Quy tắc đặt tên

Tên phần mở rộng phải tuân theo các quy tắc sau:

- Kho GitHub phải được đặt tên là `hf-<name>`.
- `<name>` phải bắt đầu bằng một chữ cái hoặc chữ số.
- `<name>` có thể chứa chữ cái, chữ số, `.`, `_` và `-`.
- `<name>` không được xung đột với lệnh `hf` tích hợp (ví dụ: `download`, `upload`, `auth`).

Khi cài đặt, người dùng có thể chỉ định đầy đủ `OWNER/hf-<name>` hoặc chỉ `hf-<name>` (mặc định là tổ chức `huggingface`).

## Các phần mở rộng hiện có

Dưới đây là một số phần mở rộng của cộng đồng mà bạn có thể tham khảo:

| Mở rộng | Loại | Mô tả |
|-----------|------|-------------|
| [hanouticelina/hf-claude](https://github.com/hanouticelina/hf-claude) | Shell script | Khởi chạy Claude Code với các nhà cung cấp suy luận HF |
| [alvarobartt/hf-mem](https://github.com/alvarobartt/hf-mem) | Python | Ước tính yêu cầu bộ nhớ suy luận cho các mô hình HF |

