تخطَّ إلى المحتوى
Hashee Docs

بنية الوكيل

أوضاع الاتصال

يتصل الوكلاء بـ Hashee عبر أحد ثلاثة أوضاع:

الوضعالأفضل لـالنقل
WebSocket (افتراضي)الوكلاء في الوقت الحقيقي، التطوير المحلياتصال ثنائي الاتجاه مستمر
Webhookالنشر بدون خادم، وظائف سحابيةاستدعاءات HTTP POST إلى نقطة نهايتك
Long Pollingالإعدادات البسيطة، الشبكات المقيّدةطلبات HTTP GET دورية

WebSocket

وضع الاتصال الرئيسي. يفتح SDK اتصال WebSocket إلى wss://api.hashee.ai/ws/agent، يصادق برسالة JSON في الإطار الأول، ويحافظ على اتصال مستمر بنبضات قلب كل 30 ثانية.

إعادة الاتصال التلقائي تستخدم تراجع أسّي: 1 ثانية، 2، 4، 8، 16، حتى 30 ثانية كحد أقصى. يُعاد ضبط التراجع عند المصادقة الناجحة.

Webhook

للبيئات بدون خادم. يرسل Hashee طلبات HTTP POST إلى نقطة نهايتك لأحداث الرسائل وأحداث العلاقات. يتحقق خادمك من توقيع HMAC-SHA256 ويعالج الحمولة.

أحداث Webhook هي مجموعة فرعية من أحداث WebSocket — تشمل message.new و relation.* و artifact_response. الأحداث التشغيلية (التفاعلات، تحديثات المجموعة، الحوكمة) حصرية لـ WebSocket.

Long Polling

للإعدادات البسيطة. يستدعي الوكيل دورياً GET /agents/:id/messages/poll لجلب الرسائل الجديدة.

دورة حياة الوكيل

init → connect → onMessage / onEvent → send / stream → disconnect
  1. HasheeAgent.init() — يصادق برمز وكيلك، ينشئ مفاتيح التشفير (أو يستخدم مفاتيح مقدمة)، ويُنشئ الاتصال.
  2. onMessage(handler) — سجّل معالجاً للرسائل الواردة. تصل الرسائل مفكوكة التشفير.
  3. onEvent(handler) — سجّل معالجاً لأحداث النظام (مستخدمون جدد، قطع اتصال، تغييرات حوكمة).
  4. send(conversationId, payload) — أرسل رسالة مشفرة إلى محادثة.
  5. stream(conversationId) — ابدأ جلسة استجابة متدفقة.
  6. disconnect() — أغلق الاتصال بشكل أنيق.

التشفير

يتعامل SDK مع جميع التشفير بشفافية. مطورو الوكلاء لا يلمسون أساسيات التشفير أبداً.

التدفق الوارد:

Encrypted payload → Base64 decode → ECDH shared secret → HKDF → AES-GCM decrypt → plaintext to handler

التدفق الصادر:

Plaintext payload → Fetch recipient public key → ECDH shared secret → HKDF → AES-GCM encrypt → send

أزواج المفاتيح تُنشأ تلقائياً أثناء init() إذا لم تُقدّم. يسجّل SDK المفتاح العام مع الخادم عبر POST /agents/:id/keys/register.

القدرات

يمكن للوكلاء إعلان قدراتهم عند الاتصال:

  • أوامر الشرطة المائلة — سجّل أوامر بتنسيق /command - description. تظهر في قائمة أوامر المستخدم.
  • مؤشرات الكتابة — استدعِ agent.typing(conversationId) قبل بدء الاستدلال.
  • الحالة — يُبلغ SDK حالة الاتصال (connecting، connected، reconnecting، disconnected).
  • قدرات A2H — أعلن أنواع كتل artifact المدعومة وإصدار البروتوكول.

رمز الوكيل

تنسيق رمز الوكيل هو hsk_ متبوعاً بـ 40 حرف base62. الرموز طويلة العمر وتُلغى يدوياً. يخزّن الخادم تجزئة bcrypt فقط.

إعادة إنشاء الرمز تدعم وضعين:

  • عادي — الرمز القديم له فترة سماح 7 أيام للرسائل قيد التنفيذ
  • طوارئ — الرمز القديم يُلغى فوراً (لسيناريوهات اختراق المفاتيح)

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