زر واحد، وسير عملك الخاص

إنشاء سير عمل قابل للاستدعاء

1. محفز مسمّىStream Deck / API
2. الشروط والإجراءاتEvent Flow المحفوظ لديك
3. الوجهةFlow Actions أو OBS أو تكامل آخر

1. افتح Event Flow من SSN. أنشئ تدفقًا مخصصًا أو اختر قالب زر Stream Deck / API .
2. أضف التشغيل من Stream Deck / API ضمن مجموعة محفزات Stream Deck وAPI .
3. سمِّه intermission. تتطابق الأسماء تمامًا وهي حساسة لحالة الأحرف؛ استخدم اسمًا قصيرًا ووصفيًا.
4. اربط مخرجه بـ عرض نص (Show Text). اضبط النص على Back in five minutes، واختر المدة والطبقة المطلوبتين.
5. احفظ التدفق ثم فعّله. التدفق غير المحفوظ موجود في المحرر فقط؛ ولا يمكن استدعاء تدفق معطل. قالب البداية معطل عمدًا حتى تنتهي من الإعداد.
6. افتح تراكب Flow Actions باستخدام رابط SSN المُنشأ. أضف ذلك الرابط كمصدر متصفح OBS للجمهور. المحرر نفسه ليس التراكب.

التدفقات التي لا تحتوي على هذا المحفز المسمّى غير قابلة للاستدعاء عبر API لسير العمل. لا يحقن استدعاء سير عمل دردشة وهمية في لوحة الإرساء. تواصل أحداث OBS الحالية والدردشة العادية استخدام محفزاتها الحالية.

يمكن لتدفق الجمع بين محفزه المسمّى وعوامل تصفية عبر عقد المنطق. أبقِ الأتمتة غير المرتبطة في تدفقات منفصلة: تُقيَّم جميع فروع المحفزات والمنطق في التدفق المحدد بحدث API. تبدأ الضغطات المتكررة عمليات تشغيل منفصلة؛ ضع محدد المعدل (Rate Limiter) بعد المحفز إذا أردت فترة انتظار.

ربط مفتاح Stream Deck

1. هيّئ إجراء الإعداد في الإضافة بجلسة SSN وكلمة المرور الاختيارية. استخدم اختبار الاتصال (Test Connection).
2. اسحب أمر مسبق (Preset Command) إلى مفتاح.
3. اختر سير عمل Event Flow → تشغيل سير عمل (Event Flow workflows → Run workflow).
4. اختر تحديث سير العمل (Refresh workflows)، ثم حدد التدفق والمحفز المحفوظين. يخزّن المفتاح معرّف التدفق واسم المحفز معًا.
5. اضغط مرة واحدة وراقب تراكب Flow Actions. تعني علامة الصح على المفتاح أن SSN قبل التشغيل.

يحتفظ محدد سير العمل بالاختيارات المفقودة. بعد إعادة تسمية تدفق أو تعطيله أو حذفه أو استيراده، حدّثه وأعد اختياره. يملك التدفق المستورد كتدفق جديد معرّفًا مختلفًا. استخدم حقل Value للاستهداف بالاسم عبر عدة تدفقات بدلًا من ذلك.

أمر مخصص: اضبط Action على triggerWorkflow، واترك Target فارغًا، وأدخل {"trigger":"intermission"} كقيمة Value، وفعّل انتظار الاستجابة (Wait for response). يوفر الإعداد المسبق اختيارًا موجّهًا وتصفية حسب الإمكانات.

إجراءات متعددة: يُقر كل طلب سير عمل بالقبول سريعًا. يمكن أن تبدأ خطوة Stream Deck التالية قبل اكتمال إجراءات سير العمل المؤجلة. ضع التسلسل والتأخيرات داخل Event Flow عندما يكون الترتيب مهمًا.

تمرير قيم مخصصة

في حقل Value للمفتاح أو طلب API:

{
  "trigger": "intermission",
  "flowId": "YOUR_SAVED_FLOW_ID",
  "data": { "name": "Back in five minutes", "minutes": 5 }
}

اضبط Show Text على {meta.workflow.data.name}. يستطيع Compare Property قراءة meta.workflow.data.minutes. Data كائن JSON اختياري؛ يبقى في meta.workflow.data ولا يمكنه استبدال هوية الحدث أو منح امتيازات دردشة.

احذف flowId لاستدعاء كل تدفق مفعّل يحمل اسم المحفز المطابق تمامًا. وجود عدة عقد محفز مطابقة في تدفق واحد يظل يقيّم ذلك التدفق مرة واحدة فقط. لتشغيل تدفق واحد فقط، احتفظ بمعرّفه من المحدد أو استجابة الاكتشاف.

يحمل الحدث المستخدم داخل التدفق المحدد type: "api", event: "workflow_trigger", chatname: "Stream Deck / API"، وقيمة فارغة لـ chatmessage، والبيانات أعلاه. لا تستطيع الدردشة العادية التي تنسخ تلك الحقول تفعيل محفز API المسمّى.

أمثلة API

أبقِ SSN مفعّلًا وقيد التشغيل. هذه استدعاءات تحكم عن بُعد في Social Stream؛ ولا تستخدم واجهة الذكاء الاصطناعي المحلية API/MCP المنفصلة في SSApp. حافظ على خصوصية معرّف جلستك الحقيقي.

اكتشاف المحفزات المتاحة

{"action":"getWorkflowTriggers","get":"list-1","apiid":"YOUR_SESSION"}

يتضمن استدعاء الرجوع result.payload.triggers:

{"triggers":[{"flowId":"flow-123","flowName":"Intermission","trigger":"intermission"}]}

تشغيل سير عمل مسمّى

{
  "action": "triggerWorkflow",
  "value": {"trigger":"intermission","flowId":"flow-123","data":{"name":"Back shortly"}},
  "get": "run-1",
  "apiid": "YOUR_SESSION"
}

استخدم قيمة فريدة لـ get لكل طلب. يحتوي استدعاء الرجوع الناجح على result.ok: true, result.status: "accepted"، و result.payload.matchedFlows. يعني القبول العثور على التدفق المفعّل وجدولته. ولا يعني اكتمال كل إجراء مؤجل أو خطاف ويب أو استدعاء OBS أو تشغيل وسائط.

WebSocket

تفعيل التحكم في الإضافة عن بُعد عبر API في SSN. اتصل بـ wss://io.socialstream.ninja. انضم باستخدام {"join":"YOUR_SESSION","out":1,"in":2}، ثم أرسل الطلب أعلاه. تنقل القناة 1 أوامر التحكم؛ وتنقل القناة 2 استدعاءات الرجوع. لا تحتاج إلى تفعيل قناة الدردشة لسير العمل.

HTTP

فعّل إعداد التحكم عن بُعد عبر API نفسه. استبدل النص النائب للجلسة قبل الاستخدام:

POST https://io.socialstream.ninja/YOUR_SESSION
Content-Type: application/json

{"action":"triggerWorkflow","value":{"trigger":"intermission","data":{"name":"Back shortly"}}}

لمحفز مسمّى بسيط، يمكنك أيضًا استخدام GET https://io.socialstream.ninja/YOUR_SESSION/triggerWorkflow/null/intermission. يمكن أن يتضمن الجزء الرابع من المسار JSON بترميز URL للقيم المنظمة. رمّز قيمة JSON كلها باستخدام encodeURIComponent(JSON.stringify(value)). تستخدم قنوات الإرسال المخصصة ?channel=N.

P2P

يرسل وضع P2P الافتراضي للإضافة الحمولة نفسها عبر نقل قناة البيانات الحالي لـVDO.Ninja في SSN. لا يلزم مفتاح WebSocket API المستضاف لوضع P2P. ينبغي لعملاء P2P الحاليين إرسال هذا الطلب عبر اتصال تحكم SSN القائم؛ ولا يلزم فتح API الذكاء الاصطناعي المحلية.

الأخطاء والتوافق

• WORKFLOW_NOT_FOUND: لا يوجد تدفق محفوظ ومفعّل يطابق المحفز أو معرّف التدفق.
• INVALID_VALUE: محفز مفقود أو غير صالح، أو JSON مشوه، أو معرّف تدفق غير صالح، أو بيانات ليست كائنًا.
• CONTROL_UNAVAILABLE: SSN أو التحكم عن بُعد للمضيف معطل.
• TARGET_UNAVAILABLE: لا يزال Event Flow يُحمَّل.
• قد لا تعلن ملفات Social Stream الأقدم هذه الإجراءات. تحقق من getCapabilities → ssn.actions.triggerWorkflow و getWorkflowTriggers. يجب تثبيت المحفز الجديد والإضافة المحدّثة معًا؛ رقم إصدار SSApp وحده لا يحدد ملفات Social Stream المحمّلة عن بُعد.

لا تعِد محاولة استدعاء يغيّر الحالة تلقائيًا بعد فقدان الإقرار: قد يكون سير العمل بدأ بالفعل. تحقق من مخرجه أولًا. لا توفر API هذه قائمة انتظار لحالة التنفيذ.

ما يحتاجه كل تكامل

دليل Event Flow الكامل · وصفات · مرجع API

إيماءات المؤقت والدردشة

المؤقت: أدر نقرة واحدة لتغيير ±10 ثوانٍ افتراضيًا؛ اضغط القرص باستمرار أثناء تدويره لتغيير ±1 دقيقة (6 أضعاف الخطوة المُهيَّأة). اضغط وأفلت دون تدوير للبدء أو الإيقاف المؤقت. انقر شاشة المؤقت لتحديثها؛ واضغط مطولًا على العرض لإعادة التعيين. الضغط المطول على القرص المادي وحده لا يعيد التعيين.

مراجعة الدردشة: أدره لليسار للدردشة الأقدم ولليمين للأحدث؛ واضغط القرص لتثبيت الرسالة التي تراجعها. انقر الشاشة لإبراز الرسالة المثبتة التالية؛ واضغط الشاشة مطولًا لإلغاء تثبيت الرسالة التي تراجعها. أبقِ لوحة الإرساء الافتراضية مفتوحة. في وضع WebSocket، فعّل تمرير الدردشة على القناة 4.

افتح المساعدة والتشخيص → دليل عناصر التحكم والأيقونات وسير العمل (Help and diagnostics → Controls, icons and workflow guide) في الإضافة للدليل الكامل دون اتصال، وأنواع الإجراءات الخمسة، وكل إعداد مسبق وأيقونة، وسلوك إعادة التعيين، والإعدادات الافتراضية وحل المشكلات.

مرجع لوحة أدوات Event Flow

تتضمن لوحة الأدوات 45 محفزًا و67 إجراء وخمس عقد منطق وأربع عقد حالة. لكل إدخال تسمية نصية إلى جانب رمزه. حدد عقدة لرؤية إعداداتها ومتطلبات تكاملها؛ وجود أيقونة في لوحة الأدوات لا يثبت اتصال الوجهة.

المحفزات تحدد متى يبدأ التدفق. اربط الشروط بـAND/OR عند الحاجة. الإجراءات تُنفَّذ حسب ترتيب اتصالها. عقد الحالة تتذكر القيم بين الأحداث. لفترة انتظار لزر، اختر محدد المعدل (Rate Limiter) (THROTTLE)، وليس إجراء Delay: يؤخر Delay كل تشغيل ولا يمنع الضغطات المتكررة.

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

لتفاصيل الربط، راجع دليل Event Flow, دليل عقد الحالة, دليل ذاكرة المستخدم، و دليل OBS.

معالجة حالة فشل

1. استخدم تدفق Show Text بسيطًا أولًا وتحقق من مخرجه.
2. احفظ وفعّل؛ ثم حدّث قائمة سير العمل في Stream Deck. تأكد من اسم المحفز ومعرّف التدفق معًا.
3. تأكد من أن SSN مفعّل وأن الاتصال Online وأن تراكب الوجهة متصل بالجلسة نفسها.
4. افحص استدعاء رجوع API أو تشخيص الإضافة بحثًا عن أخطاء العثور أو التحقق. لحالات الفشل بعد القبول، افحص الوجهة وسجلات تشغيل Event Flow.
5. أضف تكاملات أخرى واحدًا تلو الآخر. اختبر الضغطات المتكررة وتدفقًا معطلًا وإعادة الاتصال قبل الاستخدام المباشر.

ترسل لوحة اختبار الدردشة العادية في المحرر حدث دردشة. ولا تنتحل محفز API مسمّى. اختبر هذا المحفز عبر Stream Deck أو API للتحقق من المسار الكامل.