بناء شات بوت ذكاء اصطناعي مجاني لموقعك عبر Cloudflare Workers

💡 جديد على Cloudflare؟ دليل Workers Quickstart الرسمي وتوثيق Vectorize مرجعان ممتازان إذا أردت التعمّق بعد هذا الشرح.

Terminal

npm create cloudflare@latest support-widget
cd support-widget
npm install --save-dev tailwindcss wrangler

Terminal

npm install -g wrangler
wrangler login

Terminal

npx wrangler vectorize create support-faq --dimensions=768 --metric=cosine
npx wrangler kv namespace create CHAT_HISTORY

wrangler.jsonc

{
  "name": "support-widget",
  "main": "src/worker.js",
  "compatibility_date": "2026-01-01",
  "assets": { "directory": "./public", "binding": "ASSETS" },
  "ai": { "binding": "AI" },
  "vectorize": [
    { "binding": "FAQ_INDEX", "index_name": "support-faq" }
  ],
  "kv_namespaces": [
    { "binding": "CHAT_HISTORY", "id": "ضع_معرّف_KV_هنا" }
  ]
}

💡 ماذا تفعل كل خدمة (Binding)؟ ASSETS يخدّم ملفات الواجهة الثابتة، AI يمنح الـ Worker صلاحية تشغيل النماذج، FAQ_INDEX يربطه بقاعدة البيانات المتجهية، و CHAT_HISTORY هو مكان تخزين محادثات الزوّار.

src/worker.js

const SYSTEM_PROMPT = "أنت مساعد دعم فني مختصر وودود. استخدم سياق الأسئلة الشائعة المرفق إن وُجد. إن لم تكن متأكدًا، قل ذلك بدل التخمين.";
const SESSION_TTL = 60 * 60 * 24 * 14; // 14 يومًا

// نطاق الـ widget يختلف غالبًا عن نطاق الموقع المُضمَّن فيه، لذا نعكس
// الـ Origin الحقيقي للطلب بدل استخدام علامة النجمة (*) — فالنجمة لا يمكن
// دمجها مع طلبات تحمل بيانات اعتماد (كوكيز).
function corsHeaders(request) {
  return {
    "Access-Control-Allow-Origin": request.headers.get("Origin") || "*",
    "Access-Control-Allow-Credentials": "true",
    "Vary": "Origin",
    "X-Content-Type-Options": "nosniff",
  };
}

function getSessionId(request) {
  const match = request.headers.get("Cookie")?.match(/widget_sid=([^;]+)/);
  return match ? match[1] : null;
}

async function findRelevantFaq(env, question) {
  const embedded = await env.AI.run("@cf/baai/bge-base-en-v1.5", { text: [question] });
  if (!embedded?.data?.length) return "";
  const matches = await env.FAQ_INDEX.query(embedded.data[0], { topK: 3, returnMetadata: true });
  return matches.matches
    .filter((m) => m.score > 0.6) // نتجاهل التطابقات الضعيفة بدل إرباك النموذج بضجيج
    .map((m) => `Q: ${m.metadata?.question}\nA: ${m.metadata?.answer}`)
    .join("\n\n");
}

// خدمة Workers AI تبثّ أحداث SSE، لكن حدود الأجزاء (Chunks) لا تحترم حدود الأسطر —
// سطر "data: {...}" واحد قد يصل مقسّمًا على جزأين. التخزين المؤقت وتحليل الأسطر
// المكتملة فقط يمنع فقدان أجزاء من النص بصمت.
function createSseLineBuffer(onEvent) {
  let buffer = "";
  return {
    push(text) {
      buffer += text;
      const lines = buffer.split("\n");
      buffer = lines.pop();
      for (const line of lines) {
        if (line.startsWith("data: ") && !line.includes("[DONE]")) {
          try { onEvent(JSON.parse(line.slice(6))); } catch (_) {}
        }
      }
    },
  };
}

async function handleChat(request, env) {
  const cors = corsHeaders(request);
  const { message } = await request.json();
  if (!message?.trim()) {
    return new Response(JSON.stringify({ error: "الرسالة مطلوبة" }), { status: 400, headers: { "Content-Type": "application/json", ...cors } });
  }

  let sessionId = getSessionId(request);
  let session = sessionId ? await env.CHAT_HISTORY.get(sessionId, "json") : null;

  // needsCookie يجب أن يتتبّع ما إذا أنشأنا جلسة جديدة فعلًا — وليس فقط
  // ما إذا كان هناك كوكي موجود. فإذا بقي الكوكي لكن انتهت صلاحية سجل KV،
  // فإن الكود القديم كان سيبدأ جلسة جديدة بصمت دون إعادة إصدار الكوكي،
  // مما يكسر الذاكرة نهائيًا.
  let needsCookie = false;
  if (!session) {
    sessionId = crypto.randomUUID();
    session = { history: [] };
    needsCookie = true;
  }

  session.history.push({ role: "user", content: message.trim() });
  const faqContext = await findRelevantFaq(env, message);
  const promptMessages = [
    { role: "system", content: SYSTEM_PROMPT + (faqContext ? `\n\nسياق الأسئلة الشائعة:\n${faqContext}` : "") },
    ...session.history.slice(-8),
  ];

  const modelStream = await env.AI.run("@cf/meta/llama-3-8b-instruct", { messages: promptMessages, stream: true });
  let fullReply = "";
  const decoder = new TextDecoder();
  const lineBuffer = createSseLineBuffer((chunk) => { fullReply += chunk.response || ""; });

  const { readable, writable } = new TransformStream({
    transform(chunk, controller) {
      lineBuffer.push(decoder.decode(chunk, { stream: true }));
      controller.enqueue(chunk);
    },
    async flush() {
      if (fullReply) {
        session.history.push({ role: "assistant", content: fullReply });
        await env.CHAT_HISTORY.put(sessionId, JSON.stringify(session), { expirationTtl: SESSION_TTL });
      }
    },
  });

  modelStream.pipeTo(writable).catch((err) => console.error("خطأ بث:", err));

  const headers = { "Content-Type": "text/event-stream", ...cors };
  // SameSite=None + Secure مطلوب (وليس Lax) لأن هذا طلب Cross-Site من نطاق
  // الموقع المُضيف إلى نطاق الـ Worker. كوكيز Lax تُحجب في طلبات fetch
  // العابرة للنطاقات، وهذا يكسر الذاكرة بصمت.
  if (needsCookie) headers["Set-Cookie"] = `widget_sid=${sessionId}; Path=/; HttpOnly; SameSite=None; Secure; Max-Age=${SESSION_TTL}`;
  return new Response(readable, { headers });
}

async function handleHistory(request, env) {
  const cors = corsHeaders(request);
  const sessionId = getSessionId(request);
  const session = sessionId ? await env.CHAT_HISTORY.get(sessionId, "json") : null;
  return new Response(JSON.stringify({ history: session?.history || [] }), { headers: { "Content-Type": "application/json", ...cors } });
}

async function handleSeed(request, env) {
  const cors = corsHeaders(request);
  const providedKey = request.headers.get("X-Seed-Key");
  if (!env.SEED_KEY || providedKey !== env.SEED_KEY) {
    return new Response(JSON.stringify({ error: "غير مصرَّح" }), { status: 401, headers: { "Content-Type": "application/json", ...cors } });
  }

  const { faq } = await request.json(); // faq: [{ question, answer }, ...]
  if (!Array.isArray(faq) || !faq.length) {
    return new Response(JSON.stringify({ error: "أرسل مصفوفة faq غير فارغة" }), { status: 400, headers: { "Content-Type": "application/json", ...cors } });
  }

  const vectors = [];
  for (const entry of faq) {
    const embedded = await env.AI.run("@cf/baai/bge-base-en-v1.5", { text: [entry.question] });
    vectors.push({
      id: crypto.randomUUID(),
      values: embedded.data[0],
      metadata: { question: entry.question, answer: entry.answer },
    });
  }

  await env.FAQ_INDEX.upsert(vectors);
  return new Response(JSON.stringify({ seeded: vectors.length }), { headers: { "Content-Type": "application/json", ...cors } });
}

export default {
  async fetch(request, env) {
    const path = new URL(request.url).pathname;
    const cors = corsHeaders(request);

    if (request.method === "OPTIONS") {
      return new Response(null, { headers: { ...cors, "Access-Control-Allow-Methods": "GET,POST,OPTIONS", "Access-Control-Allow-Headers": "Content-Type, X-Seed-Key" } });
    }
    if (path === "/api/chat" && request.method === "POST") return handleChat(request, env);
    if (path === "/api/history") return handleHistory(request, env);
    if (path === "/api/seed" && request.method === "POST") return handleSeed(request, env);
    return env.ASSETS.fetch(request);
  },
};

⚠️ الخطأ الذي يكسر الذاكرة بصمت: استخدام علامة النجمة Access-Control-Allow-Origin: * مع طلب يحمل بيانات اعتماد (كوكيز) يُرفض من كل متصفح حديث — وبما أن نطاق الـ widget نادرًا ما يطابق نطاق الموقع المُضمَّن فيه، فهذا طلب Cross-Site بطبيعته. أضف إلى ذلك أن كوكي SameSite=Lax يُحجب تمامًا في طلبات fetch العابرة للنطاقات. أخطئ في أي من الاثنين وسيبدو الشات بوت يعمل في أول رسالة، ثم ينسى كل شيء بهدوء في الرسالة التالية — بلا أي خطأ ظاهر. لهذا السبب يعكس الكود أعلاه الـ Origin الحقيقي ويستخدم SameSite=None; Secure.

tailwind.config.js

module.exports = {
  content: ["./public/**/*.{html,js}"],
  darkMode: "class",
  theme: { extend: {} },
};

src/styles.css

@tailwind base;
@tailwind components;
@tailwind utilities;

package.json (قسم scripts)

"scripts": {
  "build:css": "npx tailwindcss -i ./src/styles.css -o ./public/widget.css --minify",
  "dev": "npm run build:css && wrangler dev",
  "deploy": "npm run build:css && wrangler deploy"
}

public/widget.js

(function () {
  const config = {
    baseUrl: window.SUPPORT_WIDGET_URL || "",
    title: window.SUPPORT_WIDGET_TITLE || "الدعم الفني",
    greeting: window.SUPPORT_WIDGET_GREETING || "أهلًا! كيف يمكنني مساعدتك؟",
  };
  let messages = [];
  let isOpen = false;
  let isSending = false;

  // محتوى الرسائل يأتي من الزائر ومن النموذج معًا — كلاهما غير موثوق.
  // بدون الإفلات (Escaping)، كتابة "<img src=x onerror=alert(1)>" في
  // مربع الدردشة سيُنفَّذ كسكربت حقيقي على الموقع المُضيف.
  function escapeHtml(str) {
    return str
      .replace(/&/g, "&")
      .replace(/</g, "<")
      .replace(/>/g, ">")
      .replace(/"/g, """)
      .replace(/'/g, "'");
  }

  function injectMarkup() {
    const styleLink = document.createElement("link");
    styleLink.rel = "stylesheet";
    styleLink.href = config.baseUrl + "/widget.css";
    document.head.appendChild(styleLink);

    const root = document.createElement("div");
    root.id = "support-widget-root";
    root.innerHTML = `
      <button id="sw-toggle" class="fixed bottom-6 right-6 w-14 h-14 bg-emerald-600 rounded-full shadow-xl z-[99999] text-2xl">💬</button>
      <div id="sw-panel" class="fixed bottom-24 right-6 w-96 max-w-[calc(100vw-2rem)] h-[560px] max-h-[75vh] rounded-2xl shadow-2xl bg-white hidden flex-col z-[99999]">
        <div class="flex items-center justify-between px-4 py-3 border-b font-semibold">
          <span>${escapeHtml(config.title)}</span>
          <button id="sw-close" class="text-gray-400 hover:text-gray-700 text-lg leading-none">✕</button>
        </div>
        <div id="sw-messages" class="flex-1 overflow-y-auto p-4 space-y-3"></div>
        <form id="sw-form" class="flex gap-2 p-3 border-t">
          <input id="sw-input" class="flex-1 border rounded-full px-4 py-2 text-sm" placeholder="اكتب رسالة..." autocomplete="off" />
          <button type="submit" class="px-4 bg-emerald-600 text-white rounded-full text-sm">إرسال</button>
        </form>
      </div>`;
    document.body.appendChild(root);
  }

  function renderMessages(showTyping) {
    const container = document.getElementById("sw-messages");
    const bubbles = messages
      .map((m) => `<div class="text-sm ${m.role === "user" ? "text-right" : "text-left"}">
          <span class="inline-block px-3 py-2 rounded-xl ${m.role === "user" ? "bg-emerald-600 text-white" : "bg-gray-100"}">${escapeHtml(m.content)}</span>
        </div>`)
      .join("");
    const typingBubble = showTyping
      ? `<div class="text-left"><span class="inline-block px-3 py-2 rounded-xl bg-gray-100 text-sm text-gray-400">يكتب…</span></div>`
      : "";
    container.innerHTML = bubbles + typingBubble;
    container.scrollTop = container.scrollHeight;
  }

  // إصلاح تخزين مؤقت مماثل لما في الخلفية — حد الجزء قد يقسّم سطر
  // "data: {...}" واحدًا إلى قسمين، لذا نحتفظ بأي سطر ناقص متأخر.
  function createSseLineBuffer(onEvent) {
    let buffer = "";
    return {
      push(text) {
        buffer += text;
        const lines = buffer.split("\n");
        buffer = lines.pop();
        for (const line of lines) {
          if (line.startsWith("data: ") && !line.includes("[DONE]")) {
            try { onEvent(JSON.parse(line.slice(6))); } catch (_) {}
          }
        }
      },
    };
  }

  async function sendMessage(text) {
    if (isSending) return; // يمنع طلبات متداخلة إذا ضغط أحدهم Enter بسرعة
    isSending = true;
    messages.push({ role: "user", content: text });
    renderMessages(true);

    try {
      const response = await fetch(config.baseUrl + "/api/chat", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ message: text }),
        credentials: "include",
      });
      if (!response.ok) throw new Error("فشل الطلب: " + response.status);

      const reader = response.body.getReader();
      const decoder = new TextDecoder();
      let reply = "";
      let index = null;

      const lineBuffer = createSseLineBuffer((chunk) => {
        if (!chunk.response) return;
        reply += chunk.response;
        if (index === null) {
          messages.push({ role: "assistant", content: reply });
          index = messages.length - 1;
        } else {
          messages[index].content = reply;
        }
        renderMessages(false);
      });

      while (true) {
        const { done, value } = await reader.read();
        if (done) break;
        lineBuffer.push(decoder.decode(value, { stream: true }));
      }

      if (index === null) {
        messages.push({ role: "assistant", content: "عذرًا، لم أفهم ذلك — هل يمكنك المحاولة مجددًا؟" });
        renderMessages(false);
      }
    } catch (err) {
      messages.push({ role: "assistant", content: "حدث خطأ في الوصول للدعم. حاول مرة أخرى بعد قليل." });
      renderMessages(false);
    } finally {
      isSending = false;
    }
  }

  function togglePanel(forceOpen) {
    isOpen = typeof forceOpen === "boolean" ? forceOpen : !isOpen;
    const panel = document.getElementById("sw-panel");
    panel.classList.toggle("hidden", !isOpen);
    panel.classList.toggle("flex", isOpen);
    if (isOpen && !messages.length) {
      messages.push({ role: "assistant", content: config.greeting });
      renderMessages(false);
    }
  }

  function bindEvents() {
    document.getElementById("sw-toggle").onclick = () => togglePanel();
    document.getElementById("sw-close").onclick = () => togglePanel(false);
    document.getElementById("sw-form").onsubmit = (e) => {
      e.preventDefault();
      const input = document.getElementById("sw-input");
      const text = input.value.trim();
      if (!text) return;
      input.value = "";
      sendMessage(text);
    };
  }

  async function loadHistory() {
    try {
      const res = await fetch(config.baseUrl + "/api/history", { credentials: "include" });
      if (res.ok) {
        const data = await res.json();
        if (data.history?.length) {
          messages = data.history;
        }
      }
    } catch (_) {}
  }

  async function init() {
    injectMarkup();
    await loadHistory();
    bindEvents();
  }

  document.readyState === "loading" ? document.addEventListener("DOMContentLoaded", init) : init();
})();

⚠️ لا تتخطَّ أبدًا إفلات محتوى الدردشة (HTML-escaping): كل من رسالة الزائر ورد النموذج تُدرَجان في الصفحة عبر innerHTML. لو أدرجت هذا النص كما هو دون إفلات، فإن زائرًا يكتب وسمًا مثل <img onerror=...> في مربع الدردشة سيُنفَّذ كـ HTML حقيقي على أي موقع مُضمَّن فيه الـ widget — وهذه ثغرة XSS مخزّنة. دالة escapeHtml() أعلاه ليست تحسينًا اختياريًا؛ تخطَّها وستكون قد شحنت ثغرة أمنية في كل موقع يثبّت الـ widget الخاص بك.

public/index.html

<!doctype html>
<html lang="ar" dir="rtl">
<head>
  <meta charset="utf-8" />
  <title>شات بوت الدعم — تجربة محلية</title>
</head>
<body style="font-family: sans-serif; padding: 40px; max-width: 640px; margin: 0 auto;">
  <h1>صفحة تجربة محلية</h1>
  <p>هذه الصفحة موجودة فقط ليعرض عليها خادم التطوير شيئًا في الجذر.
    فقاعة الدردشة يجب أن تظهر في الزاوية السفلية — اضغط عليها للتجربة.</p>
  <script>
    window.SUPPORT_WIDGET_URL = ""; // نفس النطاق أثناء الاختبار المحلي
    window.SUPPORT_WIDGET_TITLE = "اسألنا أي شيء";
  </script>
  <script src="/widget.js"></script>
</body>
</html>

Terminal

npm run dev
# يفتح على http://localhost:8787

⚠️ ملاحظة اختبار محلي — الكوكيز لا تعمل على HTTP العادي: الكوكي يُضبط بخاصية SameSite=None; Secure، وهي مطلوبة للطلبات العابرة للنطاقات في الإنتاج. لكن المتصفحات الحديثة ترفض خاصية Secure على اتصالات http://localhost العادية. هذا يعني أن كوكي الجلسة لن يُضبط أثناء الاختبار المحلي عبر wrangler dev، وسيبدو الشات بوت وكأنه ينسى المحادثة بعد كل رسالة. هذا أمر متوقّع — يعمل الكوكي بشكل صحيح فور النشر على نقطة نهاية HTTPS من Cloudflare. للاختبار محليًا مع استمرارية جلسة كاملة، استخدم wrangler dev --remote (يستخدم حسابك الفعلي في Cloudflare عبر HTTPS) أو مرِّر الاتصال عبر أداة مثل ngrok.

Terminal

npm run deploy

Terminal

npx wrangler secret put SEED_KEY
# ألصق أي نص عشوائي عند السؤال — ستستخدمه لاحقًا

Terminal

curl -X POST https://support-widget.YOUR-SUBDOMAIN.workers.dev/api/seed \
  -H "Content-Type: application/json" \
  -H "X-Seed-Key: YOUR_SECRET_HERE" \
  -d '{
    "faq": [
      { "question": "ما مدة الشحن؟", "answer": "تُشحن الطلبات خلال يومي عمل وتصل خلال 3 إلى 7 أيام حسب الموقع." },
      { "question": "هل تتوفر إمكانية الاسترجاع؟", "answer": "نعم، استرجاع كامل خلال 30 يومًا من الشراء." },
      { "question": "كيف أتواصل مع الدعم؟", "answer": "راسلنا على [email protected] أو استخدم هذا الشات بوت." }
    ]
  }'

HTML

<script>
  window.SUPPORT_WIDGET_URL = "https://support-widget.YOUR-SUBDOMAIN.workers.dev";
  window.SUPPORT_WIDGET_TITLE = "اسألنا أي شيء";
</script>
<script src="https://support-widget.YOUR-SUBDOMAIN.workers.dev/widget.js"></script>

📬

أعجبك الأسلوب العملي؟

انضم إلى مئات المشتركين واحصل على أحدث الأدلة التقنية والذكاء الاصطناعي والأمن السيبراني — مشاريع حقيقية لا نظريات — تصلك مباشرة على بريدك.

نعم، أشترك! ✉️

🔒 لا رسائل مزعجة أبداً. نحترم صندوق بريدك.

📌 وجدتَ هذا الدليل مفيدًا؟ شاركه مع من سئم من دفع اشتراك شهري مقابل widget دردشة، واستكشف المزيد من أدلة الذكاء الاصطناعي والأتمتة العملية على وادي التكنولوجيا.