CLI-Anything: بناء برمجيات أصلية للعملاء من الصفر إلى الإنتاج

حوّل أي قاعدة برمجية إلى واجهة سطر أوامر حتمية وقابلة للتحكم بالذكاء الاصطناعي مع إخراج منظم بتنسيق JSON — دليل خطوة بخطوة للمهندسين

جدول المحتويات

• ما الذي نبنيه: خط الأنابيب لواجهة سطر الأوامر الأصلية للعملاء
• المتطلبات الأساسية: الأدوات والإصدارات وإعداد البيئة
• المرحلة 1: تحليل قاعدة البرمجية وتصميم واجهة سطر الأوامر
• المرحلة 2: التنفيذ الآلي لواجهة سطر الأوامر والاختبار
• المرحلة 3: النشر على CLI-Hub وتكامل العملاء
• التكوين المتقدم: الأداء والحتمية
• الاختبار والتحقق: ضمان موثوقية العملاء
• معالجة الأخطاء وتصحيحها: المرونة على مستوى الإنتاج
• تعزيز الإنتاج: الأمان والتوسع والامتثال
• المراقبة والملاحظة: مقاييس لأنظمة العملاء
• التكلفة والأداء: استراتيجيات التحسين
• الخطوات التالية: الإضافات ونداء العمل لشركة Hyperion Consulting

ما الذي نبنيه: خط الأنابيب لواجهة سطر الأوامر الأصلية للعملاء

المتطلبات الأصلية للعملاء

يواجه النظام البيئي للبرمجيات الحديثة عدم توافق معماري أساسي: التطبيقات المصممة للتفاعل البشري من خلال واجهات المستخدم الرسومية يجب أن تخدم الآن العملاء المستقلين كمستخدمين رئيسيين. هذا التحول يتطلب أكثر من مجرد أغلفة سطحية لواجهات برمجة التطبيقات أو أتمتة واجهة المستخدم الرسومية الهشة — بل يتطلب إعادة تصور جذرية لكيفية كشف البرمجيات عن قدراتها. تعالج CLI-Anything هذه الحاجة من خلال خط أنابيب آلي مكون من 7 مراحل يحول أي قاعدة برمجية إلى واجهة سطر أوامر أصلية للعملاء، مكتملة بإخراج منظم بتنسيق JSON، ومعالجة الأخطاء الموحدة، وإدارة الحالة الواعية لسير العمل.

في جوهرها، تحل CLI-Anything ثلاث مشكلات حاسمة في تفاعل العملاء مع البرمجيات:

1. الحتمية: أدوات أتمتة واجهة المستخدم الرسومية مثل Selenium أو PyAutoGUI تقدم أنماط فشل غير حتمية بسبب تبعيات التوقيت وكشف العناصر البصرية. توفر واجهات CLI-Anything المُنشأة عمليات ذرية ومتطابقة مع نتائج يمكن التنبؤ بها.

2. الملاحظة: يحتاج العملاء إلى إخراج قابل للقراءة آليًا لاتخاذ القرارات. بينما تصدر معظم واجهات سطر الأوامر نصًا غير منظم، تفرض CLI-Anything علامة --json على كل أمر، مما ينتج استجابات منسقة باستمرار مع رموز الحالة، ورسائل الأخطاء، وحمولات البيانات المُكتبة CLI Anything.

3. قابلية الاكتشاف: لا يمكن للعملاء استنتاج الوظائف من الواجهات البصرية. يولد خط أنابيب التوثيق الآلي لـ CLI-Anything مخططات OpenAPI، ومراجع Markdown، وإدخالات سجل CLI-Hub التي تمكن من اكتشاف القدرات برمجيًا.

خط الأنابيب الآلي المكون من 7 مراحل

يعمل خط أنابيب CLI-Anything كآلة حالة حتمية تعالج قاعدة برمجية للتطبيق المستهدف عبر سبع مراحل متميزة. تنتج كل مرحلة قطعًا فنية يمكن التحقق منها تغذي المراحل اللاحقة، مع تغطية اختبار شاملة لضمان الموثوقية من البداية إلى النهاية. يوضح الرسم البياني التالي لهيكل Mermaid بنية خط الأنابيب وتدفق البيانات:

المرحلة 1: التحليل (طبقة الاستشعار)

تبدأ العملية بتحليل ثابت لقاعدة برمجية للتطبيق المستهدف، لاستخراج المعلومات الهيكلية والسلوكية:

1. تحليل شجرة النحو المجردة (AST): باستخدام وحدة ast في Python وقواعد Tree-sitter، تبني CLI-Anything جدول رموز كامل للوظائف والفئات وهياكل البيانات. بالنسبة لتطبيقات C/C++ (مثل Blender)، تستفيد من LibTooling لـ Clang لتوليد AST دقيق GitHub - HKUDS/CLI-Anything.

2. رسم خرائط إجراءات واجهة المستخدم الرسومية: من خلال مزيج من:

   • الاستبطان لـ Qt/Cocoa/GTK (لتطبيقات سطح المكتب)
   • تحليل DOM المستند إلى WebDriver (لتطبيقات Electron)
   • فحص واجهة برمجة تطبيقات الوصول (macOS AXUIElement، Windows IAccessible) تنشئ CLI-Anything سجلاً بالإجراءات القابلة للتنشيط من قبل المستخدم مع تواقيع الإدخال/الإخراج الخاصة بها.

3. رسم بياني للتبعيات: يتم بناء رسم بياني موجه لا دوري (DAG) لاستدعاءات الوظائف وتدفقات البيانات باستخدام تحليل الرسم البياني الثابت للاستدعاءات (عبر pycg لـ Python، CodeViz لـ C++).

نمط الفشل: تحدث الإيجابيات الكاذبة في كشف إجراءات واجهة المستخدم الرسومية عندما تكشف واجهات برمجة تطبيقات الوصول عناصر تحكم غير موجهة للمستخدم. تخفف CLI-Anything من ذلك من خلال نظام تسجيل الثقة (0-1) بناءً على:

• تكرار الإجراء في القياسات عن بُعد للمستخدم (إذا كانت متاحة)
• وجودها في قوائم/أشرطة أدوات التطبيق
• تعقيد معلمات الإدخال (الإجراءات الموجهة للمستخدم عادةً ما تحتوي على عدد أقل من المعلمات الأبسط)

المرحلة 2: التصميم (طبقة الاستدلال)

ترجم مرحلة التصميم القطع الفنية الناتجة عن التحليل إلى مواصفات واجهة سطر الأوامر:

1. تجميع الأوامر: باستخدام التجميع الهرمي على شجرة النحو المجردة، يتم تجميع الوظائف ذات الصلة في أوامر فرعية. على سبيل المثال، تصبح عمليات الطبقات في GIMP gimp layer create|delete|merge.

2. نموذج الحالة: يتم اشتقاق آلة الحالة المحدودة (FSM) من هياكل البيانات الأساسية للتطبيق. تمثل CLI-Anything ذلك كمخطط JSON مع:

   {
     "type": "object",
     "properties": {
       "current_document": {"$ref": "#/definitions/Document"},
       "clipboard": {"$ref": "#/definitions/ClipboardItem"},
       "undo_stack": {"type": "array", "items": {"$ref": "#/definitions/Action"}}
     },
     "required": ["current_document"]
   }
   

   Copy

3. مخططات الإدخال/الإخراج: يتم صياغة معلمات وقيم الإرجاع لكل أمر كمخططات JSON. تفرض CLI-Anything:

   • قيود الأنواع الأولية (مثل width: {"type": "integer", "minimum": 1})
   • القيم المعدودة للخيارات المنفصلة (مثل format: {"enum": ["png", "jpg", "tiff"]})
   • التحقق من صحة مسارات الملفات باستخدام أنماط pathlib.Path

المفاضلة: يجب على مرحلة التصميم موازنة الاكتمال مع قابلية الاستخدام. تجميع الأوامر بشكل دقيق للغاية (مثل أوامر منفصلة لكل مرشح في GIMP) يخلق عبئًا إدراكيًا على العملاء. تستخدم CLI-Anything مقياس كثافة الأوامر (الأوامر لكل مجموعة منطقية) لتقسيم أو دمج المجموعات تلقائيًا عندما يتجاوز هذا المقياس 15.

المرحلة 3: التنفيذ (طبقة الحساب)

تولد مرحلة التنفيذ واجهة سطر أوامر جاهزة للإنتاج باستخدام Click مع الخصائص الرئيسية التالية:

1. واجهة REPL الموحدة: ترث جميع واجهات سطر الأوامر المُنشأة من فئة AgentCLI الأساسية التي توفر:

   • سجل الأوامر (عبر readline)
   • مؤشرات التقدم (دوارات العمليات الطويلة)
   • المساعدة المنظمة (--help يولد نصًا قابلاً للقراءة البشرية وإخراج JSON قابل للقراءة آليًا)
   • الإكمال التلقائي للأوامر الفرعية والمعلمات

2. عقد إخراج JSON: يدعم كل أمر علامة --json التي تُرجع:

   {
     "status": "success|error",
     "code": 200,
     "data": {"layer_id": 42, "name": "background"},
     "warnings": ["deprecated_parameter: استخدم 'format' بدلاً من 'type'"]
     "timestamp": "2026-04-05T14:30:45Z"
   }
   

   Copy

3. إدارة الحالة: تستقبل الأوامر الحالة وتُحدثها من خلال كائن السياق:

   @cli.command()
   @click.pass_context
   def layer_create(ctx, name: str, width: int, height: int):
       """إنشاء طبقة جديدة في المستند الحالي."""
       state = ctx.obj["state"]
       layer = state["current_document"].create_layer(name, width, height)
       return {"layer_id": layer.id}
   

   Copy

المقاييس المرجعية: تظهر قياسات وقت بدء التشغيل لواجهات سطر الأوامر المُنشأة أداءً متسقًا عبر التطبيقات:

المراحل 4-7: الاختبار والتوثيق والنشر (طبقة التنسيق)

تضمن المراحل المتبقية أن تلبي واجهة سطر الأوامر المُنشأة معايير الإنتاج:

1. تخطيط الاختبار: يولد ملف TEST.md يحتوي على:

   • قوالب اختبار الوحدة لكل أمر
   • سيناريوهات نهاية إلى نهاية (مثل "إنشاء مستند، إضافة ثلاث طبقات، تصدير كملف PNG")
   • مصفوفات الحالات الحدية (مدخلات غير صالحة، انتقالات الحالة)

2. تنفيذ الاختبار: ينتج مجموعة pytest مع:

   • 1,073 اختبار وحدة (اختبار الأوامر الفردية بمعزل)
   • 435 اختبار نهاية إلى نهاية (التحقق من سير العمل متعدد الأوامر)
   • اختبارات قائمة على الخصائص باستخدام Hypothesis للتحقق من صحة الإدخال

3. التوثيق: يُحدّث TEST.md بما يلي:

   • جداول مرجعية للأوامر
   • أمثلة على الاستدعاءات
   • مواصفات OpenAPI 3.1 للوصول البرمجي

4. النشر: ينشئ:

   • setup.py مع بيانات PyPI
   • Dockerfile للنشر المحصور
   • إدخال سجل CLI-Hub (registry.json)

نمط الفشل: ينتج توليد الاختبار أحيانًا اختبارات غير مستقرة عندما يكون للتطبيقات سلوك غير حتمي (مثل محاكاة الفيزياء في Blender). تعالج CLI-Anything ذلك من خلال:

• المهلة الزمنية للعمليات الطويلة
• منطق إعادة المحاولة مع التراجع الأسي
• اختبار المعيار الذهبي للمخرجات البصرية

CLI-Hub: السجل المركزي (طبقة الاتصال)

يعمل CLI-Hub كحلقة الوصل في Physical AI Stack، مما يمكّن العملاء من اكتشاف وتثبيت وتشغيل واجهات سطر الأوامر الأصلية للعملاء من خلال واجهة موحدة. تتبع بنية السجل المبادئ التالية:

1. المساهمة اللامركزية: يضيف المطورون واجهات سطر أوامر جديدة من خلال تقديم طلب سحب (PR) مع ملف registry.json:

   {
     "name": "gimp-cli",
     "version": "2.10.34",
     "description": "واجهة سطر أوامر أصلية للعملاء لـ GIMP",
     "install": {
       "pip": "gimp-cli>=2.10.0",
       "npx": "@clianything/gimp@latest"
     },
     "commands": ["layer", "filter", "export"],
     "tags": ["إبداعي", "تحرير الصور"],
     "license": "GPL-3.0"
   }
   

   Copy

2. التحقق الآلي: يتحقق خط أنابيب CI لـ CLI-Hub من استجابة واجهة سطر الأوامر (--help تُرجع خلال 500 مللي ثانية) CLI-Anything/CONTRIBUTING.md.

3. تكامل العملاء: يتفاعل العملاء مع CLI-Hub من خلال:

   • واجهة برمجة التطبيقات REST (/api/v1/search?q=تحرير+صور)
   • واجهة سطر الأوامر (clihub install gimp-cli)
   • مجموعة أدوات Python (from clihub import Registry)

مقاييس التبني: اعتبارًا من مارس 2026، يستضيف CLI-Hub واجهات سطر أوامر أصلية للعملاء لـ 18 تطبيقًا عبر مجالات مختلفة:

سير العمل من البداية إلى النهاية: من قاعدة البرمجية إلى تنفيذ العميل

يوضح الرسم البياني التالي للتسلسل سير عمل كامل حيث يستخدم عميل ذكاء اصطناعي CLI-Anything لإجراء تحرير الصور في GIMP: