// tier: helix-primary · order 12

LLMOrchestrator betalicense: Apache-2.0

Go (1.25)Go stdlib (+ testify, yaml.v3)Pipe transport (JSON-lines over stdio)File transport (inbox/outbox/shared)sync.Mutex / sync.CondCircuit breaker + HealthMonitorpkg/i18n TranslatorChallenge harness

Source

• HelixDevelopment/LLMOrchestrator
• HelixDevelopment/HelixConstitution

// architecture

طائرة تحكم موحّدة لكل وكيل برمجي CLI غير مرئي.

LLMOrchestrator هو وحدة Go مستقلة وقابلة لإعادة الاستخدام لإنشاء وإدارة والتواصل مع الوكلاء البرمجيين CLI غير المرئيين (OpenCode، Claude Code، Gemini، Junie، Qwen Code) عبر بروتوكول هجين يجمع بين الأنابيب والملفات، مع قواطع دوائر لكل وكيل، واختيار مقدمي الخدمة القابل للتوصيل، وفصل تجريد الترجمة الدولية، وضمانات اختبارات مكافحة الخداع.

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

LLMOrchestrator هو البنية التحتية المشتركة لتنسيق الوكلاء البرمجيين CLI غير المرئيين — البنية الأساسية التي تحتاجها كل أنظمة الوكلاء المتعددة بهدوء وغالباً ما يعاد بناؤها بشكل سيئ. بدلاً من إعادة تنفيذ إنشاء العمليات وإطار الرسائل وتحليل النتائج لكل مشروع لأدوات مثل OpenCode، Claude Code، Gemini CLI، Junie، وQwen Code، توفر هذه الوحدة واجهة Agent موحّدة، ومجمع وكلاء AgentPool آمن للخيوط، ومجمع MultiProviderPool الذي يجمع الوكلاء من عدة مقدمي خدمات خلف واجهة واحدة. التوجيه قابل للتوصيل عبر AgentSelector — جولة تناوب تتخطى مقدمي الخدمة الذين يفشلون في تلبية المتطلبات، أو ترتيب تفضيلي مع احتياطي — بحيث تكون طريقة توزيع العمل سياسة تختارها أنت، وليست افتراضاً ثابتاً. كل وكيل ملموس هو محول رفيع فوق BaseAdapter المشترك الذي يدير دورة حياة العملية بالكامل: البدء بإعداد الأنبوب، الإيقاف السلس عبر SIGTERM ثم SIGKILL، إعادة التشغيل، وصيانة النشاط — الجزء المعقد والمعرض للأخطاء، تم حله مرة واحدة.

التواصل مصمم ليكون هجيناً عن قصد، بما يتناسب مع المهمة ونوع النقل. ينقل نقل الأنابيب رسائل JSON مفصولة بسطور جديدة مع مهلة قراءة لكل طلب وحد أقصى لطول الاستجابة للرسائل التفاعلية السريعة، بينما يستخدم نقل الملفات مجلدات الوارد/الصادر/المشترك لكل جلسة للملفات الكبيرة أو الثابتة التي لا ينبغي أن تبقى في الأنبوب. المرونة ليست فكرة لاحقة — بل هي هيكلية: يفتح قاطع الدائرة لكل وكيل بعد ثلاث إخفاقات متتالية لمدة تبريد تبلغ 60 ثانية قبل إجراء اختبار نصف مفتوح، ومراقب صحة في الخلفية يرسل إشارات إلى الوكلاء بحيث يمكن للوكيل المتعطل أن يتعافى دون انتظار حركة المرور الواردة لاكتشاف ذلك. يمنع الحصول على الوكيل من المجمع الحظر على متغير شرط بدلاً من إهدار وحدة المعالجة المركزية في انتظار مشغول، ومحلل الاستجابة عديم الحالة وآمن للاستدعاء المتزامن. الوحدة مفصولة تماماً — لا يُسمح بتسرب أي تفاصيل خاصة بالمستهلك — وكل سلسلة نصية ظاهرة للمستخدم تمر عبر مترجم ترجمة دولية Translator قابل للتوصيل، مع NoopTranslator يعيد معرّفات الرسائل كما هي بحيث تظهر الترجمة المفقودة بوضوح بدلاً من الاختفاء.

كل نظام متعدد الوكلاء يحتاج إلى تشغيل والتواصل مع وكلاء CLI بشكل موثوق. إعادة حل مسائل الإنشاء والتأطير والتحليل والتعامل مع الإخفاقات لكل مشروع هو مضيعة للجهد وعرضة للأخطاء. تجمع LLMOrchestrator هذه المهام في وحدة مستقلة وقابلة لإعادة الاستخدام، مسؤوليتها المتخصصة تجعلها قابلة لإعادة الاستخدام — وهذه القابلية لإعادة الاستخدام تُدمر لحظة تسرب أي تفاصيل خاصة بالمستهلك.

المحتوى

إنه يحول مهمة "تشغيل جيش من عملاء CLI المتباينين" من عملية هندسية مخصصة لكل مشروع إلى مجرد استيراد مكتبة واحدة — حيث تُحلّ مسائل التجميع، وكسر الدوائر، وإدارة دورة الحياة، والتوجيه القابل للتوصيل مسبقاً وتُعزّز بالموثوقية. ولأن اختبارات مكافحة الخداع تُمارس النظام الحقيقي من البداية إلى النهاية بدلاً من الاكتفاء بـ"إنه يُترجَم"، تحصل على تجريد يمكنك الوثوق به فعلياً للعمل تحت ظروف التوازي والأعطال، وليس مجرد شيء يبدو صحيحاً على الرسم البياني.

• بروتوكول هجين يجمع بين الأنابيب والملفات — سرعة تفاعلية (أسطر JSON عبر stdin/stdout، مواعيد نهائية للقراءة، حدود للاستجابة) *و* تبادل قائم على الملفات الدائمة (صندوق الوارد/صندوق الصادر/مشاركة) للقطع الكبيرة، بحيث لا تضطر أبداً إلى التضحية بالزمن الاستجابة مقابل المتانة أو العكس.
• مجمع متعدد المزودين مع محددات قابلة للتوصيل — واجهة موحدة لعدة مزودي CLI، مع توجيه بالتناوب أو حسب ترتيب الأفضلية يُختار كسياسة بدلاً من أن يكون مدمجاً.
• قاطع دوائر لكل عميل + مراقب صحة في الخلفية — تدهور *و* استعادة تلقائية (3 إخفاقات → فتح لمدة 60 ثانية → اختبار نصف مفتوح)، بحيث يُعزل العميل غير المستقر ثم يُعاد دمجه بهدوء دون تدخل يدوي.
• تجميع دون انتظار نشط — Acquire يحظر على sync.Cond حتى يتوفر عميل مطابق وصحي أو يُلغى السياق، بحيث لا يكلّف الانتظار أي وحدة معالجة مركزية.
• فصل صارم + مكافحة الخداع في الترجمة — يُرجع NoopTranslator معرّفات الرسائل كما هي بحيث يستحيل تفويت الترجمة المفقودة بدلاً من تركها فارغة بصمت.
• الأمان افتراضياً — قائمة بيضاء بمسارات الملفات الثنائية تعني عدم وجود استيفاء للقشرة وبالتالي عدم وجود سطح حقن الأوامر، مدعومة بحماية من اجتياز المسارات، وحد أقصى للاستجابة يبلغ 1 ميغابايت لمنع الإخراج الجامح، وإخفاء مفاتيح API في السجلات.
• منصة اختبار مكافحة الخداع — جولات حقيقية على القرص/JSON/المُحلّل عبر خمس لغات، مع بوابة تحوير مقترنة يجب أن تخرج برقم غير صفري عند تعطل الميزة — اختبار يثبت أنه قادر فعلياً على الفشل.

• إدخال/إخراج موثوق لعملية العميل. التواصل مع عملية CLI المولّدة يبدو خادعاً في بساطته؛ تم التغلب عليه باستخدام نقل هجين يجمع بين الأنابيب والملفات، وعقد رسالة/مُحلّل محدد بحيث يتفق الجانبان على تنسيق البيانات، وBaseAdapter الذي يركز دورة حياة العملية بأكملها بما في ذلك مهلة SIGTERM السلسة التي تصعد إلى SIGKILL كملاذ أخير.
• التوازي دون انتظار نشط. تم التغلب عليه باستخدام AgentPool قائم على قفل ومتغير شرط حيث ينام Acquire حتى يتوفر عميل متوافق القدرات بالفعل، مقترناً بمُحلّل عديم الحالة وخالٍ من الآثار الجانبية يمكن استدعاؤه بأمان من عدة روتينات متزامنة في آن واحد.
• عزل فشل المزود. تم التغلب عليه بحيث لا يستطيع مزود سيئ سحب البقية معه: قواطع دوائر لكل عميل تحتوي نطاق الانفجار، وروتين مراقبة صحة في الخلفية يقود عملية الاستعادة حتى عندما لا تصل طلبات لتشغيلها.
• إثبات الصحة، وليس مجرد الترجمة. تم التغلب عليه باستخدام مشغل التحدي: عشرات الثوابت عبر الإنجليزية/الصربية/اليابانية/الإسبانية/الألمانية تمارس النظام الحقيقي، بالإضافة إلى بوابة تحوير مقترنة (LLMORCH_MUTATE_RUNNER=1 يجب أن تفشل → خروج الغلاف برقم 99) تكسر الميزة عمداً لإثبات أن البوابة نفسها ليست خدعة.
• التوطين دون فشل صامت. تم التغلب عليه باستخدام التماس NoopTranslator الذي يعيد المعرّفات كما هي وحقن المُترجم لكل مستهلك، بحيث يكون أي نقص في الترجمات مرئياً دائماً بدلاً من تغطيته.

المحتوى

• Go (الإصدار 1.25) — تم اختياره لقدرته المتميزة على إدارة التوازي والتحكم السلس في العمليات، وهو ما تتطلبه بالضبط عمليات تنسيق العمليات الحية للوكلاء؛ حيث يقوم بتنفيذ الوحدة مع محولات الوكلاء، وسائل النقل، والمُحلِّل.
• مكتبة Go القياسية فقط (+ testify، yaml.v3) — اختيار مقصود للحفاظ على سطح الاعتماديات في أدنى حد ممكن وعدم سحب أي من أدوات تطوير LLM، مما يجعل الوحدة خفيفة الوزن وقابلة للتضمين داخل أي مستهلك دون جرّ أي تبعات بائعية.
• وسيلة النقل عبر الأنابيب (JSON-lines عبر المدخلات/المخرجات القياسية) — تم اختيارها للرسائل التفاعلية السريعة، مع تعزيزها بآجال قراءة محددة وحدود لطول الاستجابة لمنع توقف المتصل بسبب وكيل معلق أو خارج السيطرة.
• وسيلة النقل عبر الملفات (صندوق الوارد/صندوق الصادر/المشترك) — تم اختيارها لتبادل البيانات الكبيرة والموثوقة لكل جلسة، حيث تكون الأنابيب أداة غير مناسبة.
• sync.Mutex/sync.Cond — تم اختيارهما لتنفيذ حجز عادل ومُعَلق لمجموعة الوكلاء دون انتظار نشط.
• قاطع الدائرة + مراقب الصحة — تم اختيارهما معًا لضمان مرونة الوكلاء على مستوى الفرد *و*استعادة نشطة، وليس مجرد اكتشاف الأعطال.
• مترجم pkg/i18n — تم اختياره كواجهة فصل للترجمة لضمان بقاء النصوص الخاصة بالمستهلك خارج النواة.
• إطار اختبار التحديات (challenges/runner) + ملف Makefile (test -race، fuzz، cover) — تم اختياره لإثبات صحة الأداء بناءً على أدلة ملموسة، بما في ذلك اكتشاف حالات التسابق واختبار المُحلِّل العشوائي لضمان صحة الأداء في ظل ظروف معاكسة، وليس مجرد افتراضها.

• الحالة: تجريبية. وحدة مستقلة قابلة لإعادة الاستخدام، تُستخدم كوحدة فرعية في عدة مشاريع Helix/vasic. الرخصة: Apache-2.0؛ مستودع GitHub عام.
• تأتي بيانات تعريف النموذج من LLMsVerifier عبر جسر HelixQA؛ هذه الوحدة لا تستورد LLMsVerifier/VisionEngine/DocProcessor مباشرةً. تُشير مجموعات الأدوات المذكورة في ملف CLAUDE.md الخاص بالتطبيق الرئيسي (Gin/PostgreSQL وغيرها) إلى helix_code وليس هذه الوحدة.

درجة الأولوية: Helix-أساسية (مجموعة البنية التحتية LLM — وحدة مستقلة قابلة لإعادة الاستخدام). تأتي في المرتبة التالية بعد HelixTrack.