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

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

يستلهم هذا النظام من امتدادات GitHub 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> في الجذر.

لا يتم دعم امتدادات سكربتات Shell على نظام Windows. إذا كان امتدادك يجب أن يعمل على Windows، فاجعله امتداد Python بدلاً من ذلك.

مثال مبسط

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

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

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

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

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

>>> 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 في جذر المستودع لتوفير وصف (انظر إضافة وصف).
• التبعيات الخارجية (مثل fzf، jq، إلخ) لا يتم تثبيتها تلقائيًا مع إضافة الخاص بك. تحقق من الأدوات المطلوبة في بداية سكربتك، وإذا كانت مفقودة، فافشل بأناقة مع رسالة خطأ مفيدة.

لمثال واقعي، راجع 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:

[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:

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 امتدادك وينفذه.

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

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

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

لمثال واقعي، راجع alvarobartt/hf-mem — وهو امتداد بلغة بايثون يقدّر متطلبات الذاكرة أثناء الاستدلال لنماذج HF.

أضف وصفاً

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

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

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

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

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

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

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

في حالة امتدادات Python، فإن تعيين description في pyproject.toml هو النهج الأكثر طبيعية. في حالة امتدادات سكربتات shell، استخدم ملف manifest.json أو اضبط وصف مستودع GitHub.

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

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

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

هذا هو اتفاق مجتمعي يسهّل تصفح جميع الامتدادات المتاحة على صفحة موضوع hf-extension.

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

>>> 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 الخاص بك:

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

استخدم --force لتجاوز النسخة المثبتة سابقًا عند اختبار التحديثات.

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

بمجرد تثبيت إضافة، يمكنك تحديثها إلى أحدث إصدار منشور على GitHub:

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

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

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