# 2 · Cloudflare Workers: خلّي موقعك يفكّر ⚡

> ملف مراجعة من ورشة «من جهازك إلى العالم» · مجتمع الـ Vibe Coding

---

## الفكرة ببساطة

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

موقعك على Pages **واجهة صامتة**: جميل لكنه لا يفكّر. الـ Worker هو العقل الصغير الذي يضيف الحياة.

**المجاني:** 100,000 طلب يوميًا، أكثر بكثير مما يحتاجه أي مشروع شخصي أو تجريبي.

---

## أهم سبب تحتاجه: إخفاء مفاتيح الـ API

هذه النقطة وحدها تستحق الورشة كلها.

أي مفتاح API تضعه في كود صفحتك، أي زائر يقدر يقرأه بضغطة واحدة (كليك يمين ← عرض المصدر). لا يوجد أي حيلة تخفيه في المتصفح. أبدًا.

الـ Worker يشتغل **على السيرفر**، لا في متصفح الزائر. فيصير:

```
الزائر ← موقعك ← الـ Worker (المفتاح هنا 🔑) ← Gemini / OpenAI / أي خدمة
```

الزائر يرى نتيجة الطلب فقط. المفتاح لا يغادر الـ Worker إطلاقًا.

> جرّب الآن: افتح أدوات المطوّر في صفحة الورشة وابحث عن مفتاح Gemini. لن تجده.

---

## كيف تبدأ بدون معاناة؟

1. في لوحة **Workers & Pages** اختر **Create** ثم **Worker**
2. يفتح لك **محرر داخل المتصفح**، لا تحتاج تثبيت أي شيء
3. اطلب من أداتك المفضلة: «اكتب لي Cloudflare Worker يفعل كذا»، والصق الكود
4. اضغط **Deploy**، وصار عندك رابط مباشر للـ Worker

---

## أبسط Worker ممكن

```js
export default {
  async fetch(request, env) {
    return new Response("أهلًا من الـ Worker!");
  },
};
```

هذا كل شيء. ثلاثة أسطر، وصار عندك سيرفر يشتغل في 330 مدينة.

---

## Worker يخفي مفتاح API

هذا النمط هو الذي تحتاجه 90٪ من الوقت:

```js
export default {
  async fetch(request, env) {
    const { question } = await request.json();

    const res = await fetch(
      "https://generativelanguage.googleapis.com/v1beta/interactions",
      {
        method: "POST",
        headers: {
          "x-goog-api-key": env.GEMINI_API_KEY,
          "content-type": "application/json",
        },
        body: JSON.stringify({
          model: "gemini-3.6-flash",
          input: question,
        }),
      }
    );

    const data = await res.json();
    const text = data.steps
      .flatMap((s) => s.content || [])
      .filter((c) => c.type === "text")
      .map((c) => c.text)
      .join("");

    return Response.json({ answer: text });
  },
};
```

**`env.GEMINI_API_KEY`** يأتي من مكان آمن اسمه **Secrets**، تضبطه من لوحة التحكم:
صفحة الـ Worker ← **Settings** ← **Variables and Secrets** ← **Add** ← اختر النوع **Secret**.

بعد حفظه لا تقدر تقرأه مرة ثانية، حتى أنت. هذا مقصود.

---

## استدعاء الدوال: «السحر» الذي شفته في الورشة

عادةً النموذج يرد بنص. لكن تقدر تعطيه **قائمة دوال** يختار منها، فيرد بطلب تنفيذ دالة بدل الكلام.

تُعرّف الدالة هكذا داخل طلبك:

```js
tools: [
  {
    type: "function",
    name: "set_vibe",
    description: "يغيّر ألوان الصفحة",
    parameters: {
      type: "object",
      properties: {
        mood:   { type: "string" },
        accent: { type: "string", description: "لون hex" },
      },
      required: ["mood", "accent"],
    },
  },
]
```

فيرد النموذج داخل `steps` بخطوة من نوع `function_call`:

```json
{
  "type": "function_call",
  "name": "set_vibe",
  "arguments": { "mood": "صحراوي", "accent": "#C98A3E" }
}
```

ثم **المتصفح** ينفّذ الدالة ويغيّر الصفحة. النموذج لا يكتب HTML أبدًا، هو فقط يختار من قائمة أفعال عرّفتها أنت. هذا يجعله آمنًا ومتوقّعًا، وهذا هو الفرق بين «ذكاء اصطناعي يكتب كلام» و«ذكاء اصطناعي يسوّي أشياء».

---

## ثلاث ملاحظات تقنية مهمة

**1. الأدوات تُرسل كل مرة.** إذا استخدمت `previous_interaction_id` لمواصلة المحادثة، فهو يحفظ **سجل الرسائل فقط**. أما `tools` و `system_instruction` و `generation_config` فلازم ترسلها في كل طلب، وإلا اختفت الأدوات فجأة في الرسالة الثانية.

**2. خفّف التفكير للسرعة.** نماذج Gemini 3 تفكّر افتراضيًا. أمام جمهور مباشر، التأخير أسوأ من إجابة أذكى بقليل:

```js
generation_config: { thinking_level: "low" }
```

**3. مخرجات النموذج نص غير موثوق.** إذا وضعته في الصفحة، استخدم `textContent` وليس `innerHTML`. وإلا فتحت بابًا لهجمات الحقن.

---

## أفكار عملية للـ Worker

- نموذج تواصل يرسل الرسائل إلى بريدك
- عدّاد زوار أو جدار أسماء (مع KV للتخزين)
- وسيط آمن بينك وبين خدمات الذكاء الاصطناعي
- اختصار روابط
- API بسيط يخزّن ويسترجع بيانات

---

## التخزين: Workers KV

لو احتجت تحفظ بيانات بين الطلبات:

```js
await env.MY_KV.put("count", "42");
const value = await env.MY_KV.get("count");
```

**الحدود المجانية:** 100,000 قراءة يوميًا، لكن **1,000 كتابة فقط**. القراءة رخيصة والكتابة غالية، صمّم على هذا الأساس.

---

## روابط

- التوثيق: `developers.cloudflare.com/workers`
- توثيق Gemini: `ai.google.dev/gemini-api/docs`