# إنشاء امتداد لسطر الأوامر

يدعم سطر الأوامر `hf` الامتدادات، وهي أوامر مخصصة يوفرها المجتمع وتتكامل بسلاسة مع سطر الأوامر. تُستضاف الامتدادات كمستودعات عامة على GitHub ويمكن تثبيتها بأمر واحد. بمجرد تثبيتها، تظهر كأوامر `hf` من المستوى الأعلى تمامًا مثل الأوامر المدمجة.

يستلهم هذا النظام من [امتدادات GitHub CLI](https://docs.github.com/en/github-cli/github-cli/creating-github-cli-extensions). في هذا الدليل، ستتعلم كيفية إنشاء امتدادك الخاص، ونشره، وجعله قابلاً للاكتشاف.

> [!TIP]
> للحصول على وثائق موجهة للمستخدمين حول تثبيت وإدارة الإضافات، راجع [مرجع سطر الأوامر الخاص بـ `hf extensions`](../package_reference/cli#hf-extensions).

## نظرة عامة

هناك نوعان من الإضافات:

1. **امتدادات سكربتات shell**: ملف قابل للتنفيذ واحد (سكربت bash، ملف ثنائي مُجمَّع، إلخ) يُوضع في جذر المستودع.
2. **امتدادات بايثون**: حزمة بايثون قياسية تتضمن `pyproject.toml`. يتم تثبيتها في بيئة افتراضية معزولة حتى لا تتعارض التبعيات مع نظام المستخدم.

تتشارك النوعان نفس المعايير:

- يجب أن يكون اسم مستودع GitHub **هو** `hf-<name>` (على سبيل المثال، `hf-claude`، `hf-mem`).
- بعد التثبيت، يشغّل المستخدمون الامتداد باستخدام `hf <name>` (على سبيل المثال، `hf claude`).
- يُدرج الامتداد في `hf --help` تحت "أوامر الامتدادات".

عندما يُشغّل المستخدم `hf extensions install [OWNER/]hf-<name>`، يبحث النظام أولاً عن ملف ثنائي/نص برمجي باسم `hf-<name>` في جذر المستودع. وإذا وُجد، يتم تثبيته كتوسعة لنص برمجي للصدفة. وإلا، يتم اللجوء إلى تثبيت المستودع كحزمة Python.

## إنشاء امتداد لسكربت shell

امتداد سكربت الصدفة هو أبسط نوع. كل ما تحتاجه هو مستودع GitHub يحتوي على ملف قابل للتنفيذ باسم `hf-<name>` في الجذر.

> [!WARNING]
> لا يتم دعم امتدادات سكربتات Shell على نظام Windows. إذا كان امتدادك يجب أن يعمل على Windows، فاجعله [امتداد Python](#create-a-python-extension) بدلاً من ذلك.

### مثال مبسط

أنشئ مستودعًا باسم `hf-hello` على GitHub يحتوي على ملف واحد:

**`hf-hello`** (في جذر المستودع):

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

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

هذا كل شيء! يمكن للمستخدمين الآن تثبيت النموذج وتشغيله:

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

### نصائح حول امتدادات سكربتات الطرفية

- ابدأ دائمًا بـ shebang (`#!/usr/bin/env bash`) و`set -euo pipefail` من أجل السلامة.
- يستقبل السكربت جميع الحُجج الإضافية التي يمررها المستخدم. على سبيل المثال، يمرر `hf hello --name world` الحُجج `--name world` إلى السكربت.
- يمكنك الوصول إلى رمز Hugging Face الخاص بالمستخدم عبر متغير البيئة `HF_TOKEN` إذا كان مسجلاً الدخول.
- أضف `manifest.json` في جذر المستودع لتوفير وصف (انظر [إضافة وصف](#add-a-description)).
- التبعيات الخارجية (مثل `fzf`، `jq`، إلخ) لا يتم **تثبيتها** تلقائيًا مع إضافة الخاصية. تحقق من الأدوات المطلوبة في بداية سكربت الخاص بك، وإذا كانت مفقودة، فافشل بأناقة مع رسالة خطأ مفيدة.

> [!TIP]
> لمثال واقعي، راجع [hanouticelina/hf-claude](https://github.com/hanouticelina/hf-claude) — وهو امتداد لسكربت shell يُطلق Claude Code مع مزودي الاستدلال من HF.

## إنشاء امتداد بلغة بايثون

امتدادات Python هي حزم Python كاملة تُثبَّت في بيئة افتراضية معزولة. وهذا هو الخيار الأمثل عندما يحتوي امتدادك على تبعيات Python أو منطق أكثر تعقيدًا.

### مثال مبسط

أنشئ مستودعاً باسم `hf-hello` على GitHub بهيكلية كهذه:

```
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()
```

الجزء الحاسم هو نقطة الدخول `[project.scripts]`: **يجب** أن يُسمّى `hf-<name>` (وهنا `hf-hello`). بهذه الطريقة يكتشف `hf` CLI امتدادك وينفذه.

يقوم المستخدمون بتثبيته وتشغيله بالطريقة نفسها:

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

### كيف يتم تثبيت امتدادات بايثون

عندما يقوم مستخدم بتثبيت إضافة بلغة بايثون، يحدث ما يلي:

1. يتم إنشاء بيئة افتراضية في `~/.local/share/hf/extensions/hf-<name>/venv/`.
2. يتم تثبيت حزمة الخاص بك عبر `pip install` من أرشيف مستودع GitHub.
3. يتحقق النظام من أن سكربت وحدة التحكم `hf-<name>` تم إنشاؤه في بيئة افتراضية (venv).

هذا يعني أن تبعيات امتدادك معزولة تمامًا — فلن تتعارض مع حزم بايثون الأخرى الخاصة بالمستخدم.

> [!TIP]
> لمثال واقعي، راجع [alvarobartt/hf-mem](https://github.com/alvarobartt/hf-mem) — وهو امتداد بلغة بايثون يقدّر متطلبات الذاكرة أثناء الاستدلال لنماذج HF.

## أضف وصفاً

يساعد الوصف المستخدمين على فهم ما تفعله إضافة الإضافة. يظهر في `hf extensions list` وفي `hf --help`.

يبحث النظام عن وصف بالترتيب التالي:

1. **`manifest.json`** في جذر المستودع:

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

2. حقل `description` في **`pyproject.toml`** (للإضافات المكتوبة بلغة بايثون):

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

3. وصف مستودع **GitHub** (الحقل "About" في صفحة المستودع).

للإضافات المكتوبة بلغة بايثون، يُعدّ تعيين `description` في `pyproject.toml` الطريقة الأكثر طبيعية. أما لإضافات سكربتات الشل، فاستخدم ملف `manifest.json` أو عيّن وصف مستودع GitHub.

## اجعل امتدادك قابلاً للاكتشاف

لمساعدة المستخدمين على العثور على امتدادك، أضف موضوع **`hf-extension`** إلى مستودع GitHub الخاص بك:

1. انتقل إلى مستودعك على GitHub.
2. انقر على أيقونة الترس الموجودة بجانب "حول" في الشريط الجانبي الأيمن.
3. أضف `hf-extension` تحت "المواضيع".

هذا هو اتفاق مجتمعي يسهّل تصفح جميع الامتدادات المتاحة على [صفحة موضوع hf-extension](https://github.com/topics/hf-extension).

يمكن للمستخدمين بعد ذلك اكتشاف امتدادك مباشرةً من سطر الأوامر باستخدام `hf extensions search`، الذي يعرض جميع مستودعات GitHub الموسومة بموضوع `hf-extension`، مرتبة حسب عدد النجوم:

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

تُظهر العمود `INSTALLED` الامتدادات المثبتة محليًا بالفعل. ومن هناك، يمكن للمستخدمين تثبيت أي امتداد مدرج باستخدام `hf extensions install <repo>`.

## اختبر امتدادك

أثناء التطوير، يمكنك تثبيت امتدادك مباشرةً من مستودع GitHub الخاص بك:

```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]
> استخدم `--force` لتجاوز النسخة المثبتة سابقًا عند اختبار التحديثات.

## تحديث الامتدادات المثبتة

بمجرد تثبيت إضافة، يمكنك تحديثها إلى أحدث إصدار منشور على 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` يحدّث فقط الامتدادات المثبّتة مسبقًا. إذا لم يكن الامتداد مثبّتًا، فسيتم رفع خطأ. وتُتخطّى الامتدادات التي هي بالفعل محدّثة.

إصدار الامتداد هو الالتزام (commit) الذي تم تثبيته منه، ويُعرض على شكل SHA مختصر في عمود `VERSION` من `hf extensions list`. يتم فحص عمود `LATEST` عندما لا يتوفر أي التزام أحدث على GitHub، وعند تشغيل امتداد قديم، يُطبع تلميح يقترح `hf extensions update <name>`. للبقاء ضمن حدود معدل GitHub للطلبات غير المصادق عليها، يبحث `hf` عن أحدث التزام لكل امتداد مرة واحدة في اليوم كحد أقصى. اضبط `HF_HUB_DISABLE_UPDATE_CHECK=1` لتعطيل هذه الفحوصات.

إذا توقف امتداد بايثون عن العمل لأن نسخة بايثون التي تم تثبيته بها قد حُذفت (على سبيل المثال بعد ترقية Homebrew)، فإن الأمر `hf extensions update <name>` يعيد إنشاء بيئته الافتراضية.

## قواعد التسمية

يجب أن تتبع أسماء الامتدادات هذه القواعد:

- يجب أن يكون اسم مستودع GitHub `hf-<name>`.
- يجب أن يبدأ `<name>` بحرف أو رقم.
- يمكن أن يحتوي `<name>` على أحرف وأرقام و`.` و`_` و`-`.
- `<name>` لا يمكن أن يتعارض مع أمر `hf` مدمج (مثل `download`، `upload`، `auth`).

عند التثبيت، يمكن للمستخدمين إما تحديد `OWNER/hf-<name>` الكامل أو مجرد `hf-<name>` (والذي يتخذ افتراضيًا منظمة `huggingface`).

## الإضافات الموجودة

فيما يلي بعض امتدادات المجتمع التي يمكنك استخدامها كمرجع:

| امتداد | النوع | الوصف |
|-----------|------|-------------|
| [hanouticelina/hf-claude](https://github.com/hanouticelina/hf-claude) | سكربت shell | إطلاق Claude Code مع مزودي الاستدلال من HF |
| [alvarobartt/hf-mem](https://github.com/alvarobartt/hf-mem) | Python | تقدير متطلبات الذاكرة للاستدلال على نماذج HF |