انتقل إلى المحتوى

⚡ واجهة برمجة تطبيقات سجل وتوزيع تايدي فاكتور (TidyFactor Registry REST API v1)

المواصفات البرمجية الرسمية والقطعية لاكتشاف، وتثبيت، وفحص، ونشر مهارات وكلاء الذكاء الاصطناعي (AI Agent Skills) عبر كافة بيئات التطوير الذاتية (Google Antigravity و Claude Code و Cursor و Codex و Windsurf).

🏛️ نظرة عامة والمعمارية التشغيلية

توفر واجهة برمجة التطبيقات المستضافة ذاتياً لـ تايدي فاكتور (/api/v1/*) خدمة سجل برمجي فائقة السرعة وقابلة للتخزين المؤقت في خوادم الحافة (Edge Cache) وبدون أي اعتمادات خارجية. تُمكن الواجهة حزم الـ CLI (@tidyfactor/cli)، وإضافات بيئات التطوير، وسكربتات الأتمتة من التفاعل البرمجي المباشر مع كتالوج المهارات.

graph TD
    CLI["💻 أداة TidyFactor CLI / أي عميل"]
    API["🌐 tidyfactor.com /api/v1/*"]
    REG["📄 registry.json (سجل المهارات)"]
    PACKS["📦 packs.json (الحزم الجاهزة)"]
    CDN["💾 /downloads/skills/*.skill (تخزين CDN)"]

    CLI -->|GET /api/v1/skills| API
    CLI -->|GET /api/v1/packs| API
    CLI -->|GET /api/v1/install.sh| API
    API --> REG
    API --> PACKS
    API -->|تحويل / تنزيل مباشر| CDN

السياسات العامة والترويسات (Headers)

السياسة القيمة والسلوك
الرابط الأساسي (Base URL) https://tidyfactor.com/api/v1
المصادقة (Authentication) بدون مصادقة (سجل عام للقراءة فقط)
مشاركة الموارد (CORS) Access-Control-Allow-Origin: * (متاح عالمياً)
صيغة البيانات (Data Format) application/json; charset=UTF-8
سياسة التخزين المؤقت (Cache) Cache-Control: public, max-age=300 (5 دقائق)
ترميز النصوص ترميز UTF-8 صارم مع دعم كامل للغة العربية

📋 جدول ملخص الـ Endpoints

الطريقة المسار التخزين المؤقت الوصف
GET /api/v1/skills max-age=300 الكتالوج الشامل لجميع المهارات الـ 12 مع أرقام الإصدارات والبصمات المشفرة.
GET /api/v1/skills/{id} max-age=300 البيانات الوصفية، والاعتمادات، وروابط التثبيت لمهارة محددة.
GET /api/v1/skills/search max-age=60 البحث النصي المرن (Fuzzy Search) في أسماء وتصنيفات ووصف المهارات.
GET /api/v1/packs max-age=300 الحزم المجمعة للتثبيت السريع للوكلاء (design، saas، growth...).
GET /api/v1/install.sh max-age=600 سكربت التثبيت الفوري لأنظمة Linux و macOS عبر الطرفية.
GET /api/v1/install.ps1 max-age=600 سكربت التثبيت الفوري لأنظمة Windows عبر PowerShell.

🔍 تفاصيل المسارات البرمجية

1. GET /api/v1/skills

استرجاع قائمة كافة مهارات الوكلاء البرمجية المعتمدة.

مثال الطلب

curl -fsSL https://tidyfactor.com/api/v1/skills

الاستجابة (200 OK)

{
  "registry_version": "1.0.0",
  "skills_count": 12,
  "skills": [
    {
      "id": "tidyfactor-cinematic",
      "name": "TidyFactor Cinematic",
      "npm_package": "@tidyfactor/cinematic",
      "version": "3.6.0",
      "description": "مهارة الوكيل لبناء صفحات الهبوط الفاخرة بطراز Apple x Cartier بدون خطوات بناء.",
      "category": "Frontend Experience",
      "color": "000000",
      "archive_url": "https://tidyfactor.com/downloads/skills/tidyfactor-cinematic.skill",
      "sha256": "8f3b2a1c...",
      "install_oneliner_sh": "curl -fsSL https://tidyfactor.com/api/v1/install.sh | bash -s -- tidyfactor-cinematic",
      "install_oneliner_ps1": "irm https://tidyfactor.com/api/v1/install.ps1 | iex -Skill tidyfactor-cinematic"
    }
  ]
}

2. GET /api/v1/skills/{id}

استرجاع معلومات مفصلة وروابط الحزم لمهارة معينة.

curl -fsSL https://tidyfactor.com/api/v1/skills/tidyfactor-next

3. GET /api/v1/packs

استرجاع الحزم المجمعة لتثبيت مجموعات المهارات المتكاملة في خطوة واحدة.

curl -fsSL https://tidyfactor.com/api/v1/packs

4. GET /api/v1/install.sh و GET /api/v1/install.ps1

سكربتات التثبيت المباشرة للطرفية دون الحاجة لبيئة Node.js مسبقة.

# macOS / Linux
curl -fsSL https://tidyfactor.com/api/v1/install.sh | bash

# Windows PowerShell
irm https://tidyfactor.com/api/v1/install.ps1 | iex