دوز مباشرة للمحتوى الرئيسي
دروس فالذكاء الاصطناعي

استضف Skillbox ذاتياً: بنِ مكتبة مهارات بإصدارات لوكلاء الذكاء الاصطناعي

تعلّم كيفاش تنشّر Skillbox باستعمال Docker، وتنشئ مهارات بإصدارات واتصالات مقيّدة النطاق للعملاء، وتستعمل الواجهات ديال CLI وMCP، وتكوّن توصيات Jev الاختيارية، وتحمي البيانات ديالك أو تنقلها.

حوالي 25 دقايق ديال القراية
استضف Skillbox ذاتياً: بنِ مكتبة مهارات بإصدارات لوكلاء الذكاء الاصطناعي

شنو هو Skillbox؟

Skillbox هي مكتبة ديال المهارات بترخيص MIT، كتستضاف محلياً وكتستعملها وكلاء الذكاء الاصطناعي. كتوفر ليك بلاصة مركزية باش تنشئ، تستورد، تدير الإصدارات، توزّع، وتراجع حزم المهارات القابلة لإعادة الاستعمال. التطبيق مبني باستعمال React وBun وHono وPostgreSQL.

التثبيت الجديد كيكون خاوي عن قصد. ما فيه لا مهارات شخصية، لا حسابات المستخدمين، لا مفاتيح العملاء، لا نقاط نهاية ديال الخدمات الخارجية، ولا بيانات اعتماد ديال مزوّدي الذكاء الاصطناعي المؤدى عنهم. Skillbox كتوزع محتوى المهارات ولكن عمرها كتنفذ كود المهارات المرفوع.

الخصائص الرئيسية

  • تحرير بإصدارات: عدّل ملفات Markdown والملفات المساندة بإصدارات غير قابلة للتغيير، مع كشف التعارضات والاسترجاع.
  • ولوج محدود النطاق: أنشئ ملفات شخصية فيها صلاحيات للمهارات أو الحزم، وفصل بين صلاحيات الإنشاء والتحديث والأرشفة والاقتراح.
  • عملاء قابلون للإلغاء: أنشئ مفاتيح خاصة بكل عميل، راجع الاستعمال، وألغِ الولوج المستقبلي عند الحاجة.
  • ولوج عبر MCP وCLI: استعمل MCP عبر HTTP مباشرة، أو ربط عبر جسر Node أو Bun باستعمال stdio، أو حمّل الحزم مع التحقق من المجموعات الاختبارية.
  • موارد MCP: عرّض المهارات المصرح بها والمتوافقة عبر عرض وقراءة موارد MCP الأساسية.
  • توصيات اختيارية: استعمل Jev مع Vercel AI Gateway أو مفتاح TypeSafe AI ديالك.
  • قابلية نقل البيانات: استورد وصدّر المجلدات الأصلية، وأنشئ نسخاً احتياطية محمية، واسترجع البيانات بشكل صريح.
  • نشر مستضاف ذاتياً: شغّل التطبيق باستعمال Docker Compose، ويمكنك اختيارياً وضع Caddy أمامه من أجل HTTPS، أو تحضير حزمة Umbrel.

Skillbox مصممة كتطبيق مستضاف ذاتياً ومملوك لمالك واحد، مع عملاء محدودي النطاق. ماشي منصة SaaS عامة متعددة المستأجرين.

المتطلبات المسبقة

التثبيت الموصى به كيحتاج Docker Engine أو Docker Desktop مع Compose v2، وزيد عليهم Bash فـ Linux أو macOS أو WSL. ما محتاجش تثبّت Bun أو Node.js فالجهاز المضيف باش تستعمل الإعداد المبني على Docker.

ثبّت وشغّل Skillbox

  1. نسخ المستودع ودخل للمجلد ديالو:

    git clone https://github.com/kitze/skillbox.git
cd skillbox

  2. ولّد ملف البيئة المحلي:

    bash scripts/skillbox.sh setup

    هاد الأمر كينشئ .env فيه بيانات اعتماد عشوائية وفريدة، كيحدد الصلاحيات ديالو على 0600، وكيرفض الكتابة فوق ملف موجود من قبل.

  3. شغّل خدمات Docker:

    bash scripts/skillbox.sh start

  4. حلّ http://127.0.0.1:4791 فالمتصفح ديالك.

  5. قرا SKILLBOX_ADMIN_TOKEN من ملف .env المحلي واستعملو باش تدخل. سكريبت الإعداد ما كيظهرش هاد الرمز عن قصد.

خلي .env خاص. رمز المالك كيتحكم فالولوج الإداري، وكيساهم حتى فحماية بيانات اعتماد التكاملات المخزنة.

النشر عن بُعد

فالتثبيت عن بُعد، عيّن SKILLBOX_ORIGIN على أصل HTTPS ديال النشر، وضبط وكيلاً عكسياً لـ TLS. ما تعرّضش نسخة الإنتاج عبر HTTP غير المشفر. راجع ملاحظات النشر فالمستودع باش تعرف تفاصيل النشر المدعومة.

التطوير المحلي بلا إعداد التطبيق الخاص بـ Docker

إلى كان عندك من قبل Bun وقاعدة بيانات PostgreSQL 16 أو أحدث، ثبّت التبعيات وشغّل التطبيق مباشرة:

bun install --frozen-lockfile
# Set DATABASE_URL
# Set SKILLBOX_ADMIN_TOKEN to at least 32 random characters
# Set SKILLBOX_ORIGIN=http://127.0.0.1:4791
bun run build
bun run start

خزّن القيم الثلاثة المطلوبة فبيئة محمية، وما تلتزمش بها فالمستودع ديال الكود.

أنشئ المهارات والعملاء محدودي النطاق

من بعد ما تدخل، أنشئ مهارة فالمحرر أو استورد حزمة مهارات موجودة. إصدارات المهارات غير قابلة للتغيير، وبهذا يقدرو العملاء يحمّلو أو يجيبو إصداراً محدداً بلا ما يعتمدوا على محتوى كيتبدل.

من بعد، أنشئ ملفاً شخصياً ومنحو الولوج للمهارات أو الحزم المطلوبة. عيّن صلاحيات الإنشاء والتحديث والأرشفة والاقتراح بشكل مستقل حسب الغرض من العميل. وأخيراً، أنشئ اتصالاً للعميل باستعمال داك الملف الشخصي.

مفاتيح العملاء كيبانو غير مرة وحدة، وSkillbox كتخزن غير التجزئات ديالهم. حفظ كل مفتاح مباشرة فإعدادات محمية ديال العميل. استعمل مفتاحاً منفصلاً لكل عميل، وما توزعش رمز المالك.

ضبط CLI

CLI كتقرا إعدادات بصيغة JSON فيها رابط Skillbox ومفتاح العميل. المسار الافتراضي ديالها هو ~/.config/skillbox/config.json.

{
  "url": "https://skills.example.com",
  "token": "YOUR_CLIENT_KEY"
}

عيّن صلاحيات الملف على 0600. متغيرا البيئة SKILLBOX_URL وSKILLBOX_TOKEN كيتغلبو على القيم الموجودة فملف الإعدادات. إلا ما تضبط حتى رابط، CLI كتوجّه بأمان لـ localhost بلا ما تمشي لخدمة ديال شي شخص آخر.

خلي cli/skillbox.mjs وcli/package.mjs مجموعين. من بعد تقدر تستكشف المهارات المصرح بها وتجيبها:

node cli/skillbox.mjs list
node cli/skillbox.mjs search "database migration"
node cli/skillbox.mjs load my-skill
node cli/skillbox.mjs manifest my-skill
node cli/skillbox.mjs fetch my-skill@REVISION

عملية الجلب كتحقق من المسارات، وتجزئات الملفات، والأحجام، وعلامات التنفيذ، والمجموع الاختباري ديال الحزمة قبل ما تكتب الملفات بشكل ذري. ما كتنفذش الكود وما كتنصبش التبعيات.

نشر مهارة محدّثة

نشر مجلد محلي بإدخال معرّف المهارة والإصدار اللي متوقع تحدّثو:

node cli/skillbox.mjs publish ./my-skill my-skill EXPECTED_REVISION

المراجعة المتوقعة كتدعم كشف التعارضات. النشر كيعتمد حتى هو على الصلاحيات الممنوحة لملف تعريف العميل.

التوافق مع التدقيق

المالك يقدر يشغّل تدقيق التوافق بلا ما يبدّل حتى حاجة:

node cli/skillbox.mjs audit

الأمر كيخرج بالحالة 1 ملي كيلقى حزم ما متوافقةش. وكيعاونك تقيّم توافق MCP Skills بلا ما تعاود تكتب الحزم الموجودة.

ربط وكيل ذكاء اصطناعي عبر MCP

ثبّت bootstrap/SKILL.md كإقلاع skills-library ديال الوكيل. العملاء اللي كيدعمو HTTP MCP يقدرو يتاصلو بنقطة النهاية /mcp ديال النسخة ديالك، ويصيفطو مفتاح العميل كرمز bearer:

Authorization: Bearer YOUR_CLIENT_KEY

بالنسبة لعميل MCP اللي كيحتاج stdio، جهّز الجسر المرفق:

{
  "mcpServers": {
    "skillbox": {
      "command": "node",
      "args": [
        "/absolute/path/to/skillbox/cli/skillbox.mjs",
        "mcp"
      ],
      "env": {
        "SKILLBOX_URL": "https://skills.example.com",
        "SKILLBOX_CONFIG": "/absolute/path/to/protected-client-config.json"
      }
    }
  }
}

أدوات MCP الأساسية كتشمل search_skills وrecommend_skills وload_skill وread_skill_file وreport_skill_use. أدوات الكتابة والاقتراحات كتبان غير ملي ملف تعريف العميل كيمنح الصلاحيات المناسبة.

Skillbox كيعرض حتى المهارات المتوافقة والمصرّح بها عبر موارد MCP الأساسية resources/list وresources/read. الملفات الثنائية والكبيرة المدعومة يمكن الوصول ليها كموارد، ولكن قراية مورد ما كتفعّلش مهارة وما كتشغّلهاش.

الدعم الكامل ديال io.modelcontextprotocol/skills مازال ما تعلنش عليه. التطبيق الحالي كيوفّر خصائص الجاهزية عبر بروتوكول MCP الأساسي، بينما الاكتشاف والتفاوض الأصليين مازالين مرتبطين بترقية SDK والبروتوكول.

استعمل البحث والاقتراحات بشكل صحيح

فبداية أي مهمة، خاص الوكلاء يبقاو كيناديو على search_skills باش يحصرو المهارات المصرّح بها والمرتبطة بالمهمة. الاقتراحات كتزيد على البحث وما كتعاوضوش. قبل ما تطبّق مهارة مختارة، حمّلها باستعمال المراجعة غير القابلة للتغيير اللي رجّعها Skillbox.

إلى ما كانش مزوّد اقتراحات خارجي، تقدر تقلب من CLI:

node cli/skillbox.mjs search "database migration"

باش تطلب اقتراحات واعية بالمهمة:

node cli/skillbox.mjs recommend "Fix choppy scrolling in an Expo app"

العملية المكافئة فـ MCP هي recommend_skills({task, limit?, offset?}). عملاء HTTP يقدرو يصيفطو نفس جسم JSON الموثّق إلى POST /api/skill-recommendations.

إعداد اقتراحات Jev الاختيارية

  1. حلّ Settings → Jev recommendations.

  2. اختار Vercel AI Gateway، وهو الاختيار الافتراضي، ولا TypeSafe AI.

  3. دخل مفتاح API ديالك للمزوّد المختار وحفظو.

مفاتيح المزوّدين كتتخزّن بشكل منفصل. اختيار TypeSafe ما كيعطيش مفتاح Gateway المحفوظ لـ TypeSafe، وتبديل المزوّدين كيخلّي المفتاح المحفوظ من قبل. حذف مفتاح المزوّد المختار كيعطّل استدعاءات النماذج ديال داك المزوّد.

المفتاح كيتشفّر فـ PostgreSQL باستعمال AES-256-GCM، بمادة مفتاح مشتقة من SKILLBOX_ADMIN_TOKEN. ما كيرجعوش API ديال الإعدادات وما كيدخلش فحزم المتصفح. تبديل رمز المالك بلا اتباع مسطرة التدوير الموثّقة كيخلّي بيانات اعتماد التكامل المخزّنة ما تبقاش قابلة للقراية.

حفظ المفتاح ما كيتحققش من الولوج للمزوّد ولا من شراء الرصيد. Jev كيصيفط نص المهمة ووصف المهارات النشيطة والمصرّح بها للمزوّد المختار، وبالتالي شروط الفوترة ومعالجة البيانات ديال داك المزوّد هي اللي كتطبّق.

فهم نتائج الاقتراحات والبدائل الاحتياطية

Jev كيقيّم الكتالوج الكامل ديال الأوراق المصرّح بها والمفعّلة وغير المؤرشفة، حتى لـ 200 ورقة أو 120,000 حرف متسلسل. الكتالوجات الأكبر كتمشي صراحة للبديل الاحتياطي بلا ما يتدار ترتيب لجزء غير معلن.

  • الملاءمة هي نقطة غير معايرة من 0 حتى 4، وماشي احتمال.
  • النتائج اللي النقطة ديالها 3 ولا أكثر كترجع بترتيب تنازلي حسب النقطة، ومن بعد حسب المعرّف.
  • noMatch=true كتعني حتى مرشح من اللي تقيّمو ما وصلش للعتبة.
  • مفتاح ناقص، أو خطأ فالمزوّد، أو جواب غير سليم، أو تجاوز حدّ المعدل، أو تجاوز حدّ السعة، أو مهلة من 8 ثواني، كيطلّق البديل الاحتياطي ديال البحث فـ PostgreSQL.
  • نتائج البديل الاحتياطي كتستعمل method=search وrelevance=null وfallbackReason.

الكاش المحلي ديال العملية كيحتافظ بحد أقصى بـ 128 إدخال لمدة 5 دقايق. Skillbox كيسمح بجوج تقييمات متزامنة وبـ 10 طلبات بلا كاش لكل نطاق فالدقيقة، بلا إعادة محاولات تلقائية. منح الصلاحيات، وحالة دورة الحياة، والمراجعات كيتفحصو قبل وبعد استدعاءات النموذج، حتى فحالات إصابة الكاش.

استيراد البيانات وتصديرها وإنشاء نسخ احتياطية

إلى كان Bun متوفر، استورد مجلّد ديال المهارات بهاد الأمر:

bun scripts/import.ts /path/to/skills

الاستيرادات كتحافظ على بايتات الملفات وعلى الواجهة الأمامية غير المعروفة، وكتتجاوز الروابط الرمزية وملفات ومخرجات التشغيل، وكتحط الأنماط المعروفة ديال الأسرار فالحجر. هاد الكشف إرشادي، وماشي بديل على تدقيق كامل للأسرار. عمرك تحط كلمات السر ولا الرموز فحزم المهارات.

صدّر محتوى المهارات إلى وجهة خاوية:

SKILLBOX_EXPORT_DIR=/path/to/empty-export bun scripts/export.ts

قاعدة بيانات PostgreSQL كتبقى هي المصدر الرسمي للحقيقة. تعديل مجلّد مُصدّر ما كيبدّلش قاعدة البيانات حتى يعاود المحتوى يتنشر.

أنشئ نسخة احتياطية محمية بهاد الأمر:

bash scripts/backup.sh

التصديرات والنسخ الاحتياطية يقدرو يحتويّو على محتوى خاص بالمهارات. خليهوم منفاصلين على المصدر العمومي ديال التطبيق. سكريبت التصدير الاختياري ديال GitHub كيتطلب checkout خاص ومخصص للتصدير، ومكوَّن بشكل صريح، وما كيتفعّلش أوتوماتيكياً.

نصائح تشغيلية متقدمة

استعمل مفتاح عميل واحد لكل تكامل

المفاتيح المنفصلة كتخلي إلغاء التفعيل وتتبع الاستعمال أكثر فائدة. إلغاء تفعيل مفتاح كيمنع الطلبات الجاية، ولكن ما كيقدرش يرجّع الملفات اللي حمّلها العميل من قبل.

فضّل البروفايلات محدودة النطاق

عطي لكل وكيل غير المهارات والإجراءات اللي محتاجها. الحزم كتتوسّع لمهارات نهائية حالية بلا تكرار، بينما المراجع بوحدها ما كتعطيش صلاحية الولوج.

حمي رمز المالك والنسخ الاحتياطية

رمز المالك كيعطي صلاحية إدارية وكيستخرج مادة التشفير الخاصة ببيانات اعتماد التكاملات المحفوظة. حميه مع قاعدة البيانات ونسخ الإعدادات الاحتياطية، وتبع الإجراء الموثّق ديال التدوير قبل ما تبدّلو.

تعامل مع المهارات كمحتوى، ماشي كبرامج موثوقة

Skillbox كيتحقق من ملفات الحزم وكيوزّعها بلا ما ينفذها. بقا راجع التعليمات والكود اللي تحمّلو قبل ما تستعملهم فمسار عمل ديال وكيل.

استعمل توصيات القياس بحذر

المطوّرين يقدرو يشغلو القياس الاختياري المؤدى عليه باستعمال مفتاح المزوّد ديالهم:

bun scripts/benchmark-recommendations.ts --live --provider vercel
bun scripts/benchmark-recommendations.ts --live --provider typesafe

استعمل AI_GATEWAY_API_KEY مع Vercel، أو TYPESAFE_API_KEY أو JEV_KEY مع TypeSafe. هاد السكريبت ما كيضبطش التطبيق وما كيحفظش بيانات الاعتماد. العينة الاصطناعية ديالو ماشي ضمانة لزمن الاستجابة فالإنتاج ولا لمعايرة الاحتمالات.

تحقّق من النشر أو المساهمة

شغّل فحص الأنواع ومجموعة الاختبارات المعزولة قبل ما تنشر التغييرات:

bun run typecheck
bash scripts/test-isolated.sh

المجموعة المعزولة كتُنشئ وكتحيد مثيل PostgreSQL ديال Docker Compose خاص بها، بلا ما تنشر منافذ قاعدة البيانات. كتغطي التفويض، والمراجعات، وسلوك API وMCP، وCLI، والإعدادات المشفّرة، والتوصيات. ما توجّهش اختبارات قاعدة البيانات للإنتاج نهائياً.

الخلاصة

Skillbox كيوفّر مسار عمل مضبوط ومستضاف ذاتياً لتدبير مهارات قابلة لإعادة الاستعمال ديال وكلاء الذكاء الاصطناعي. بدا بإعداد Docker، وأنشئ مهارات بإصدارات، وعيّن بروفايلات محدودة النطاق، وربط كل وكيل بمفتاح عميل خاص به. من بعد تقدر تزيد الولوج عبر MCP، وتوصيات Jev الاختيارية، ومسارات قابلية النقل، والنسخ الاحتياطية، مع الاحتفاظ بملكية الكاتالوغ وبيانات الاعتماد ديالك.