> ## Documentation Index
> Fetch the complete documentation index at: https://comfyui-mcp.artokun.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# التطبيقات (التطبيقات المصغّرة)

> حوّل سير عمل إلى تطبيق بنقرة واحدة: بيان، ونموذج تشغيل معروض، ولقطة موجّه API تُرقَّع القيم فيها في كل تشغيل. حوّل في اللوحة، وشغّل من اللوحة أو الهاتف أو وكيل، وانشر في سجل عام.

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

| الملف           | ما هو                                                                               |
| --------------- | ----------------------------------------------------------------------------------- |
| `manifest.json` | الاسم، والوصف، و`appMode {inputs, outputs}`، و`deps`، و`hideWorkflow`، و`published` |
| `prompt.json`   | **لقطة** الموجّه بصيغة API — تُرقَّع القيم فيها في كل تشغيل                         |
| `workflow.json` | مخطط واجهة litegraph — **غائب** حين يُضبَط `hideWorkflow`                           |
| `thumbnail.png` | فن بطاقة اختياري                                                                    |

تعيش الحزم تحت دليل مستخدم ComfyUI على
`<user>/comfyui-mcp-panel/apps/<app-id>/` — عمدًا **ليس** دليل مسارات سير العمل،
فلا يظهر تطبيق مخفي أبدًا في متصفّح مسارات سير العمل.

```
workflow ⇄ convert (panel) ⇄ app bundle on disk ⇄ run form ⇄ patch snapshot ⇄ ComfyUI queue
                                    ⇅
                        publish / install ⇄ public registry
```

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

<Note>
  هناك تنفيذ تخزين وتشغيل **واحد** — مسارات HTTP الخاصة بحزمة اللوحة
  (`/comfyui_mcp_panel/apps/*`). ولوحة سطح المكتب، وتبويب التطبيقات في الجوّال،
  وأدوات MCP المسمّاة `apps_*` كلها عملاء له، فيتصرّف التطبيق بالطريقة نفسها أينما
  أطلقته منه.
</Note>

## المتطلبات

تخدم التطبيقات **حزمة اللوحة** (`comfyui-mcp-panel`)، لا خادم MCP وحده. إن سبقت
الحزمة على ComfyUI لديك الميزة، يفشل `apps` مع `action:"list"` برسالة صريحة
*«حزمة اللوحة على ComfyUI هذا أقدم من ميزة التطبيقات»* — حدّث الحزمة وأعد تشغيل
ComfyUI.

## تحويل سير عمل إلى تطبيق

في اللوحة، يفتح زر شريط الأدوات **التطبيقات** (بجانب Civitai) شبكة التطبيقات.
وتحويل سير العمل المفتوح يفعل ثلاثة أشياء:

1. **يستورد إعداد وضع APP في ComfyUI** إن كان سير العمل يحمله أصلًا، وإلا يختار
   المدخلات والمخرجات **استدلاليًا** (عناصر تحكّم الموجّه، والبذور، وإعدادات
   العيّنة؛ وعقد فئة `SaveImage` كمخرجات). وتُحترَم مدخلات وضع APP المستوردة على
   **أي** نوع عقدة، فتنجو نقاط وصول العقد المخصّصة من التحويل.
2. **يمسح الاعتماديات** — النماذج وحزم العقد المخصّصة التي يحتاجها المخطط —
   في `manifest.deps`.
3. **يلتقط لقطة الموجّه** بصيغة API. وتصير قيم عناصر التحكّم وقت التحويل
   `default` النموذج لكل مدخل.

يحمل كل مدخل في `appMode.inputs` قيم `nodeId` و`widget` و`label` و`kind` من
`text` أو `number` أو `combo` أو `toggle` أو `image` أو `model`؛ وتحمل القوائم
أيضًا `choices`. وهذا ما يعرض منه نموذج التشغيل — على سطح المكتب وعلى الجوّال.

### إخفاء سير العمل

يسقط `hideWorkflow` ملف `workflow.json` من الحزمة بالكامل، فلا يُسلَّم المخطط
لمن يشغّل التطبيق أو يثبّته.

<Warning>
  **`hideWorkflow` تعتيم، لا أمان أبدًا.** فما يزال موجّه API مرئيًا لأي من يشغّل
  التطبيق عبر `/history` الخاص بـ ComfyUI، والنماذج والعقد المخصّصة التي يثبّتها
  التطبيق تكشف اعتماديات المخطط. عامله كـ «لا تزدحم متصفّح مسارات سير العمل لدي»،
  لا كحماية لمخطط لا تستطيع تحمّل تسرّبه.
</Warning>

## تشغيل تطبيق

يرقّع التشغيل قيم نموذجك في اللقطة المخزَّنة ويدرج النتيجة في قائمة الانتظار.
ومفاتيح الترقيع هي `"<nodeId>.<widget>"` — مثلًا `{"6.text": "a cat",
"3.seed": 42}`. ينقسم المفتاح عند **أول** نقطة فقط، فتبقى أسماء عناصر التحكّم
التي تحتوي نقاطًا (مكدّسات LoRA، `lora_1.model`) سليمة.

والترقيع **صارم**: مفتاح يخاطب عقدة أو مدخلًا غير موجود في اللقطة خطأ قاطع، لا
تخطي صامت. والخطأ يعني أن البيان انحرف عن اللقطة، والفشل بصوت أعلى خير من التشغيل
بقيم بالية. والمدخلات التي تحذفها تحتفظ بافتراضيات وقت التحويل.

يُرجع التشغيل `prompt_id`؛ استطلعه للحالة (`pending` → `running` → `done`، أو
`unknown` إن لم يسمع ComfyUI عنه قط) وللمخرجات المجمَّعة تحت كل عقدة مخرجات.

### التشغيل على Pod في RunPod

يعيد مسار **التشغيل على RunPod** في اللوحة استخدام محرّك الترقيع نفسه في الوضع
**الجاف**: تطلب اللوحة الموجّه المرقَّع *دون* إدراجه محليًا، وتدفع أي اعتماديات
مثبَّتة الإصدار إلى الـ Pod، وتدرج الموجّه هناك بدلًا من ذلك.

<Warning>
  ترفض التطبيقات ذات **مدخل صورة** التشغيل على Pod. فالرفوعات تهبط على ComfyUI
  **المحلي**، الذي لا يستطيع الـ Pod الوصول إليه — فترفض اللوحة بصدق بدل إدراج
  تشغيل سيفشل على ملف ناقص.
</Warning>

## النشر والاستكشاف

تبويب **الاستكشاف** في اللوحة سجل عام (عامل Cloudflare مدعوم بـ D1 + R2) بقوائم
الرائج / الجديد / الأكثر نجومًا وبحث. والرائج هو `stars * 3 + runs` لسبعة أيام.
ويرفع النشر الحزمة — البيان، والموجّه، وسير العمل ما لم يكن مخفيًا، والصورة
المصغّرة — تحت هوية منشئ مفتاحها sha256.

ويعرض التثبيت من الاستكشاف **مربع موافقة على الاعتماديات** أولًا: تُ*بلَّغ*
`deps` التطبيق، ولا تُثبَّت بصمت أبدًا. ولا يثبّت شيء نموذجًا أو حزمة عقد مخصّصة
على جهازك لأنك ضغطت بطاقة.

<Note>
  يوجد `pricing_json` و`hosted_only` في مخطط البيان ويُمرَّران دون تغيير، لكن لا
  شيء يقرأهما. يحجزان مساحة لمرحلة تحقيق دخل تصميمية فقط — ولا يوجد سلوك تطبيق
  مدفوع اليوم.
</Note>

## أداة MCP المسمّاة `apps`

أداة واحدة بخمسة إجراءات، كلها وكلاء رقيقة فوق واجهة التطبيقات في اللوحة. وهي
السطح **بلا لوحة رسم**: ما يستخدمه تطبيق الجوّال ووكيل يُقاد مباشرة. وهي على
قائمة السماح لـ `call_tool` لدى المنسّق — `list`/`get`/`run_status` للقراءة فقط،
ويحمل `run` وضع المخاطر نفسه الذي يحمله `enqueue_workflow` (يدرج مهمة ضغطها
المستخدم صراحة).

| الإجراء               | الأثر                                                                                                                                                      |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `action:"list"`       | اسرد كل تطبيق مسجَّل على ComfyUI هذا — كل مدخل هو البيان الكامل إضافةً إلى `has_workflow` / `has_prompt` / `has_thumbnail`. بلا معاملات أخرى. للقراءة فقط. |
| `action:"get"`        | بيان تطبيق واحد + حقائق الحزمة بالمعرّف. `appMode.inputs` هو نموذج التشغيل. للقراءة فقط.                                                                   |
| `action:"run"`        | رقّع `values` في اللقطة وأدرجها. يُرجع `prompt_id`.                                                                                                        |
| `action:"run_status"` | استطلع تشغيلًا واحدًا بـ `prompt_id`: `status` إضافةً إلى مخرجات التشغيل (مراجع ملفات صورة/فيديو لكل عقدة مخرجات، ومخرجات نص). للقراءة فقط.                |
| `action:"import"`     | ثبّت تطبيقًا من السجل العام على ComfyUI هذا.                                                                                                               |

### المعاملات

`action` هو المعامل الوحيد المطلوب في المخطط — يحتاج كل إجراء إلى مجموعة فرعية
مختلفة، لذا فالبقية اختيارية في المخطط ويُفرَض حضورها في المعالج، الذي يسمّي
الحقل الناقص.

| الإجراء      | المعامل        | النوع                  | ملاحظات                                                         |
| ------------ | -------------- | ---------------------- | --------------------------------------------------------------- |
| `get`        | `app_id`       | `string` (uuid)، مطلوب | من `action:"list"`                                              |
| `run`        | `app_id`       | `string` (uuid)، مطلوب |                                                                 |
|              | `values`       | `object`، اختياري      | مفاتيح `"<nodeId>.<widget>"`؛ والمفاتيح المجهولة تفشل بصوت عالٍ |
| `run_status` | `app_id`       | `string` (uuid)، مطلوب |                                                                 |
|              | `prompt_id`    | `string`، مطلوب        | يجب أن يطابق `^[0-9a-zA-Z-]{1,64}$`                             |
| `import`     | `registry_url` | `string` (URL)، مطلوب  | يجب أن يكون السجل الافتراضي أو أصلًا في قائمة السماح            |
|              | `app_id`       | `string` (uuid)، مطلوب | uuid التطبيق في **السجل**                                       |
|              | `slug`         | `string`، اختياري      | يُسجَّل في البيانات الوصفية المحلية                             |
|              | `version`      | `integer`، اختياري     | يُسجَّل في البيانات الوصفية المحلية                             |

يُفرَض قيد شكل `prompt_id` **مرتين** — عند حدود المخطط ومرة أخرى داخل المعالج —
لأن المعرّف يُدرَج في مسار رابط. ويجب ألا يصل «معرّف موجّه» بشكل اجتياز إلى باني
الرابط حتى لو تجاوز مستدعٍ المخطط.

للمرجع المولَّد لمخطط كل أداة، راجع
[أدوات التطبيقات](/docs/docs/tools/apps).

### الاستيراد من السجل

يجلب `action:"import"` حزمة السجل من جانب الخادم وينشئها تطبيقًا محليًا. و**يصير
معرّف السجل هو المعرّف المحلي**، فإعادة استيراد تطبيق لديك أصلًا تبلّغ عن تعارض
معرّف بدل نسخه. وتعيش الصورة المصغّرة على نقطة نهاية سجل منفصلة وتُجلَب وتُمرَّر
منفصلة، فيحتفظ تطبيق مثبَّت بفن بطاقته.

**لا** تُثبَّت الاعتماديات. تُرجع الأداة `deps` البيان حتى يستطيع المستدعي
الإبلاغ عنها ويدع المستخدم يثبّتها عمدًا.

<Warning>
  `registry_url` قائمة سماح، لا رابط حر. يحدث الجلب **على الخادم**، فرابط اعتباطي
  سيكون بدائي SSRF — عناوين محلية أو شبكة محلية، أو رابط عام يعيد التوجيه إلى
  واحد. ولا يُقبل إلا السجل العام الافتراضي ما لم يُدرِج المشغّل أصولًا إضافية عبر
  `COMFYUI_MCP_REGISTRY_URLS` (مفصولة بفواصل، مخصّصة للتطوير/التجهيز). وتُرفَض
  إعادة التوجيه رفضًا قاطعًا بدل اتّباعها.
</Warning>

## الحدود والتحقّق

أشياء يمكنك الاصطدام بها فعلًا:

| الحد                  | القيمة                | أين                                                                              |
| --------------------- | --------------------- | -------------------------------------------------------------------------------- |
| JSON الحزمة / الموجّه | 16 ميغابايت           | أوسع من مخطط عادي لأن موجّهًا قد يحمل صور base64                                 |
| الصورة المصغّرة       | 5 ميغابايت            | تُفكَّك وتُتحقَّق **قبل** كتابة أي شيء، فلا تترك صورة مصغّرة سيئة حزمة نصف منشأة |
| اسم التطبيق           | 120 حرفًا             | يُقتطَع                                                                          |
| الوصف                 | 4000 حرف              | يُقتطَع                                                                          |
| `choices` القائمة     | 200 مدخل              | تُقتطَع                                                                          |
| جلب السجل             | 16 ميغابايت، 30 ثانية | يُفحَص على `content-length` المعلَن **وعلى** البايتات الفعلية                    |

تحقّق ستلاحظه:

* **يجب أن تكون معرّفات التطبيقات معرفات uuid.** أي شيء آخر يُرفَض قبل بناء مسار،
  ويُعاد فحص مسار الحزمة المحلول للاحتواء تحت جذر التطبيقات.
* **يجب أن يكون الموجّه بصيغة API** — مفاتيح معرّفات عقد رقمية، وكل عقدة كائن
  `{class_type, inputs}`. وتُرفَض مخططات صيغة الواجهة.
* **سير عمل واجهة مطلوب ما لم يُضبَط `hideWorkflow`**.
* **إنشاء تطبيق موجود أصلًا** تعارض، لا استبدال.
* **تحديثات البيان الجزئية جزئية حقًا.** نشر تطبيق أو إخفاؤه يرسل حقوله فقط ولن
  يمسح اسمك أو وصفك أو `appMode`.
* **تُسقَط مفاتيح البيان المجهولة**، ما عدا حقول التمرير المحجوزة، فيتجاهل جهاز
  أقدم حقولًا لا يفهمها بدل الفشل.

يمكن تجاوز جذر التطبيقات بـ `COMFYUI_MCP_APPS_DIR` (أساسًا للاختبارات)؛
وافتراضيًا يُشتَق من دليل مستخدم ComfyUI نفسه، فينجو من التثبيتات المحمولة.

## على الهاتف

يشحن تطبيق الجوّال تبويب **التطبيقات** حقيقيًا — لا معاينة. وله نصفان:

* **تطبيقاتي** — التطبيقات المثبَّتة على جهازك، مسرودة عبر الجسر بواسطة
  `action:"list"`. والضغط على واحد يفتح نموذج تشغيل مولَّد، ويدرجها بـ
  `action:"run"`، ويستطلع `action:"run_status"` كل ثانيتين (محدود بـ 30 دقيقة)
  حتى تُعرض المخرجات.
* **الاستكشاف** — السجل العام، يُضرَب **مباشرة عبر HTTPS** من الهاتف (بلا قفزة
  جسر، فيعمل التصفّح قبل أن تقترن). والتثبيت يذهب الاتجاه الآخر: يجلب الجهاز
  الحزمة نفسه عبر `action:"import"`.

هذا أوضح شيء يستطيع الهاتف فعله مما لا تستطيعه المحادثة — تشغيل سير عمل حقيقي،
بمدخلات حقيقية، بلا لوحة رسم في أي مكان.

## اطّلع أيضًا

* [أدوات التطبيقات](/docs/docs/tools/apps) — المرجع المولَّد لمخطط كل أداة
* [اللوحة الجانبية](/docs/docs/ar/panel) — حيث تُحوَّل التطبيقات وتُنشَر وتُستكشَف
* [تطبيق الجوّال](/docs/docs/ar/mobile) — تبويب التطبيقات في سياقه
* [وحدات Pod في RunPod](/docs/docs/tools/runpod) — الـ Pod الذي يستهدفه مسار «التشغيل على RunPod»
* [خارطة الطريق](/docs/docs/ar/roadmap)