HarnessRouter واجهة موحدة لوكلاء الذكاء الاصطناعي: التثبيت والمراقبة

HarnessRouter واجهة موحدة لوكلاء الذكاء الاصطناعي: التثبيت عبر Docker بحسب README، وترخيص Apache 2.0، وما يمكن مراقبته من رموز وسجلات وتتبعات.
HarnessRouter interface unifiée agents IA : installer et observer

HarnessRouter واجهة موحدة لوكلاء الذكاء الاصطناعي: يقدّم المستودع HarnessRouter/harnessrouter طبقة قابلة للاستضافة الذاتية تدير عدة حزم وكلاء (Codex وClaude Code وHermes ونحو ثلاثين غيرها) خلف واجهة برمجية واحدة. يضم المستودع نحو 3700 نجمة و395 تفرعًا (fork) في نهاية أكتوبر 2026، بترخيص Apache 2.0. وهو مستودع فتي: تعرض صفحة الإصدارات نحو عشرة إصدارات 0.36 و0.37 نُشرت بين 23 و27 أكتوبر 2026، منها v0.37.6 في 27 أكتوبر.

بالنسبة إلى مهندس SRE الفائدة بسيطة: نقطة دخول واحدة لتشغيل مهام الوكلاء ومتابعتها وإلغائها، بدل تكامل منفصل لكل أداة. ثم يأتي السؤال التالي مباشرة: ماذا يمكن مراقبته من هذه النقطة؟ تتبع هذه المقالة ملف README ودليل الاستضافة الذاتية وملف LICENSE كما قرأناها في 27 أكتوبر 2026.

توضيح للأمانة: لم تثبّت span.observer أداة HarnessRouter. الأوامر مأخوذة من README، والصور الثلاث أدناه منشورة في مجلد docs/images بالمستودع نفسه، وهو بترخيص Apache 2.0.

HarnessRouter واجهة موحدة لوكلاء الذكاء الاصطناعي: ما يقوله المستودع

  • الدور: يصفه README بأنه «الواجهة الموحدة لحزم الوكلاء». الحزمة هنا وكيل يعمل في سطر الأوامر مثل Codex أو Claude Code. يعرضها HarnessRouter عبر واجهة متوافقة مع OpenAI Responses API، مع جلسات دائمة وبث للتقدم وملفات وإلغاء وأخطاء منظمة.
  • البروتوكول: ينفّذ Unified Harness Protocol (UHP). يحتوي المستودع على التنفيذ المرجعي والمخططات ومجموعة اختبارات التوافق.
  • الترخيص: Apache 2.0 (قرأنا ملف LICENSE، ومعه ملف NOTICE للتبعيات). أدوات الوكلاء التي تُثبَّت عند أول تشغيل تحتفظ بتراخيصها الخاصة: يذكر الدليل مثلًا شروط Anthropic لـ Claude Code، ويطلب التحقق من ترخيص Hermes.
  • الأرقام: نحو 3700 نجمة و395 تفرعًا و789 commit على الفرع الرئيسي، مقروءة من صفحة المستودع. لا تعرض الصفحة توزيع اللغات، لذلك لا نذكر لغة.
  • النطاق: نحو 30 قاعدة وكلاء مدرجة (Codex وClaude Code وHermes وPi وOpenCode وGemini CLI وCline وgoose وAider وOpenHands وغيرها). وتبيّن مصفوفة الدعم أيها يعمل مع أي مزوّد.

جولة في الواجهة

تستمع وحدة التحكم على الويب إلى المنفذ 3000. يصف README ثلاث خطوات: ربط مفتاح مزوّد النماذج («Bring your own key»)، ثم وصف ما يجب أن يفعله الوكيل في جملة واحدة، ثم إرسال أول مهمة.

وحدة تحكم HarnessRouter واجهة موحدة لوكلاء الذكاء الاصطناعي: نافذة Set up an agent harness مع Agent harness وModel على Auto وجملة تصف ملخصًا أسبوعيًا لآراء العملاء
Source : github.com

بحسب README، يكتب HarnessRouter بعد ذلك تعليمات الوكيل، ويختار الحزمة والنموذج والمهارات والأدوات، ويترك طلبًا تجريبيًا. تُثبَّت الحزمة عند حفظ الإعداد: لتغييرها، يُنشأ إعداد آخر.

وحدة تحكم HarnessRouter: شاشة Setup saved مع حزمة Hermes والنموذج gpt-6.1-sol والتعليمات، ثم Sandbox وOrchestration وSessions وStreaming وFiles وartifacts وCancellation وerrors
Source : github.com

يقدم README أيضًا ثلاثة أمثلة يعيد طلبها عرض تشغيل مسجَّل، لرؤية مهمة منتهية دون إنفاق رموز (tokens). تُظهر الصورة التالية أحدها: ملف ناتج، وشارة «Recorded»، ومدة 105.2 ثانية.

وحدة تحكم HarnessRouter: مهمة Product images نفّذها Hermes مع gpt-5.4، وشارة Recorded، وثلاثة ملفات PNG ناتجة، وDone in 105.2 s
Source : github.com

التثبيت خطوة بخطوة

المتطلبات بحسب README: Docker ونحو 4 غيغابايت من القرص ومفتاح API من مزوّد نماذج. لا حاجة إلى حساب HarnessRouter، ولا يُرفق أي نموذج أو مفتاح تجريبي. لا يفصّل README إجراءً لكل نظام: كل شيء يمر عبر Docker.

الخطوة 1 — تشغيل الحاوية

docker run -d --name harnessrouter \
  -p 127.0.0.1:3000:3000 \
  -v harnessrouter:/data \
  harnessrouter/harnessrouter

يحفظ الحجم المسمّى قاعدة البيانات والملفات وأدوات الوكلاء المثبّتة ومساحات العمل. لا تضف --user: تحتاج نقطة الدخول إلى root لإدارة مستخدم لكل جلسة. أبقِ الربط على 127.0.0.1 ما دمت لم تغيّر كلمة المرور الأولية.

الخطوة 2 — انتظار انتهاء أول تشغيل

docker logs -f harnessrouter

يثبّت أول تشغيل أدوات الوكلاء. تابع عندما يعرض السجل [harnessrouter] ready on :3000. يسرد السطر backends available: ما ثُبّت فعلًا.

الخطوة 3 — فتح وحدة التحكم وتغيير كلمة المرور

افتح http://localhost:3000. بيانات الدخول الأولية في README هي harnessrouter لاسم المستخدم ولكلمة المرور معًا. غيّرها من Profile قبل كشف أي شيء؛ يكرر السجل تحذيرًا ما دامت كلمة المرور الافتراضية قائمة.

الخطوة 4 — استدعاء الواجهة البرمجية من منتجك

أنشئ مفتاحًا في API Keys واحتفظ به على الخادم في HARNESSROUTER_API_KEY. تُختار الحزمة عبر metadata.harness_id:

export HARNESSROUTER_BASE_URL=http://localhost:3000/api/harness

curl --fail-with-body -sS "$HARNESSROUTER_BASE_URL/v1/responses" \
  -H "Authorization: Bearer ${HARNESSROUTER_API_KEY:?}" \
  -H 'content-type: application/json' \
  -d '{
    "input":"Reply with exactly: it works.",
    "metadata":{"harness_id":"codex"},
    "model":"gpt-5.4-mini",
    "stream":false
  }'

تغيير الوكيل يعني تغيير harness_id (والنموذج). هذا هو التوجيه: الاستدعاء نفسه، وحزمة أخرى. تظهر المهمة ونصّها في وحدة التحكم. ولإعادة محاولة طلب دون تنفيذه مرتين، أرسل رأس Idempotency-Key نفسه؛ ومفتاح أُعيد استخدامه مع جسم مختلف يعيد الخطأ 409.

مراقبة HarnessRouter: السجلات والرموز والتتبعات

هذا ما تصفه وثائق المستودع، ولا شيء غيره.

  • سجلات الحاوية: يعرض docker logs -f harnessrouter تثبيت الحزم والسطر ready on :3000 والحزم المتاحة وحالات التثبيت الفاشلة. يذكر الدليل أن السجل يسمّي التثبيت الذي فشل.
  • الرموز لكل مهمة: تحتوي استجابة الواجهة على كائن usage فيه input_tokens وoutput_tokens وtotal_tokens؛ ويعرض الدليل أيضًا reasoning_tokens، وهو عدّ المزوّد نفسه ويغيب إن لم يقدمه. هذه هي الحقول التي تُجمع عند المستدعي لمتابعة التكلفة.
  • سياق التتبع W3C: إذا حمل الطلب الرأسين traceparent وtracestate، تتلقى استدعاءات النموذج في المهمة ابنًا لذلك التتبع: المعرّف نفسه للتتبع، ومعرّف span جديد، مع بقاء علم أخذ العينات. تُهمل القيمة غير الصالحة دون إفشال المهمة. ولا يُقرأ الرأس baggage أبدًا.
  • سجل التنفيذ: يعيد GET /v1/sessions/{session_id}/turns الأدوار؛ ويعيد GET /v1/traces/{session_id}/all تدفق أحداث الحزمة المخزَّن بصيغة JSON مفصولة بأسطر، حدث في كل سطر.
  • بيانات المنتج: تعطّل النسخة المجتمعية تحليلات وحدة التحكم.

هناك حدّان يجب معرفتهما. أولًا، يذكر الدليل أن مسارات (spans) استدعاءات المزوّد، أي طلبات النموذج خلف كل دور، تتبع مراقبة الخدمة المستضافة لا هذه النسخة. ثانيًا، لم نجد في README والدليل اللذين قرأناهما أي تصدير OTLP ولا مقاييس Prometheus: تُربط التتبعات عند المستدعي بحقن traceparent، ويُجمع usage بوسائلك. ولهذا الجمع، راجع تكلفة وكيل ذكاء اصطناعي بالرموز مع OpenTelemetry ومراقبة وكلاء MCP باستخدام OpenTelemetry.

الحدود والنقاط المفتوحة

  • ما يجب التنبيه إليه: مستودع حديث جدًا، وإصداراته تُنشر شبه يوميًا. العبارات الواردة في README («أول واجهة موحدة في العالم»، وتكلفة أقل بنسبة 99.8% وسرعة أكبر 3.2 مرات عبر ثماني تهيئات) هي ادعاءات من المشروع نفسه. المنهجية على harnessrouter.ai/benchmarks ولم نتحقق منها؛ ويوضح README أن الأرخص والأسرع يختلفان بحسب المهمة.
  • لا سقف للتكلفة: يقول الدليل إن شيئًا لا يحدّ دورًا بحسب تكلفته؛ وتُرفض الحزمة التي تحمل max_cost_usd. يُحدّ الدور بـ max_step وtimeout_seconds؛ وتُضبط حدود الإنفاق عند المزوّد.
  • الأمان: كلمة مرور افتراضية، وحاوية تحتاج إلى root، وجلسات مفصولة بمستخدم نظام لا بحاوية. يحذّر README من أن سرًّا يستطيع الوكيل قراءته يمكن أن يرسله إلى مكان آخر إذا طُلب منه ذلك: أعطه رموزًا قصيرة العمر وبأقل الصلاحيات.
  • النسخة المجتمعية: الفوترة وتعدد المستخدمين وتعدد النسخ تتبع الخدمة المستضافة المدفوعة. أما حزم البدء (Slides وSheets وDashboards وVideos وMy Workplace) فلها شروط مختلفة عن شروط النسخة المجتمعية.
  • تراخيص المصدر: كل أداة وكيل تحتفظ بترخيصها؛ ولا يحل Apache 2.0 محلها.

لتحديد موقع المشروع، انظر OpenClaw (وكيل وقنواته)، وPaperclip (تنسيق أسطول)، وOrca (قيادة وكلاء البرمجة)، وRuflo (الأسراب)، وECC (تحسين الحزم)، وwshobson/agents (سوق إضافات). وفي السلسلة، يعالج OpenBot الحاجة نفسها على سطح المكتب. أما HarnessRouter فيقع في جهة الخادم، كبوابة API.

أفضل الممارسات

  • أبقِ 127.0.0.1 وغيّر كلمة المرور قبل نشر المنفذ؛ وضع الباقي خلف TLS كما يصف الدليل.
  • حدّ الحزم المثبّتة بـ HR_BACKENDS: الحزمة التي لم تُثبَّت تفشل في أول مهمة.
  • أرسل traceparent مع كل استدعاء لتجد المهمة في تتبعاتك.
  • سجّل usage لكل استجابة وحدّد سقوف الإنفاق عند المزوّد.
  • استخدم Idempotency-Key في كل إعادة محاولة.
  • أعطِ الوكلاء رموزًا قصيرة العمر وبأقل الصلاحيات.

الأسئلة الشائعة

هل HarnessRouter مفتوح المصدر؟

النسخة المجتمعية بترخيص Apache 2.0 بحسب ملف LICENSE. أما حزم البدء فلها شروط مختلفة، وتحتفظ أدوات الوكلاء بتراخيصها الأصلية.

هل يصدّر HarnessRouter تتبعات OpenTelemetry؟

يصف README نشر سياق W3C (traceparent وtracestate) إلى استدعاءات النموذج. ويذكر الدليل أن مسارات استدعاءات المزوّد محجوزة للخدمة المستضافة. ولا يوجد تصدير OTLP موثّق في الصفحات التي قرأناها.

كيف أتابع تكلفة الرموز؟

اقرأ كائن usage في كل استجابة. لا سقف للتكلفة في هذه النسخة: حدّده عند مزوّد النماذج.

الخلاصة

يقدم HarnessRouter نقطة دخول واحدة لعدة وكلاء برمجة، مع توجيه عبر harness_id وواجهة برمجية مألوفة. وتبقى المراقبة شيئًا يُبنى حوله: سجلات الحاوية، وusage، وسياق التتبع الذي يحقنه المستدعي. جرّبه محليًا أولًا دون كشف المنفذ. المصادر: مستودع HarnessRouter/harnessrouter ودليل الاستضافة الذاتية.

span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC ولا للمشاريع المذكورة. العلامات التجارية المذكورة ملك لأصحابها. الأدوات تتطور بسرعة: تحقق من الأوامر والخيارات في وثائقها الرسمية.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
ThinkRail IDE vibe coding : installer, observer, limites

ThinkRail IDE vibe coding: التثبيت والمراقبة والحدود

Next Post
Skill Recorder skill agent : relire et auditer un skill

Skill Recorder مهارات الوكلاء: مراجعة المهارة وتدقيقها

Related Posts