Cloudflare Workers

​

ما الذي يعمل وما الذي لا يعمل

​

المزوّدون والأدوات

• المزوّدون: mock وopenai وanthropic وopenrouter. المزوّدون الحقيقيون مبنيون على الدالتين generateText/streamText من حزمة Vercel ai SDK مع @ai-sdk/openai/@ai-sdk/anthropic (وopenrouter هو @ai-sdk/openai موجَّه إلى https://openrouter.ai/api/v1)، وهي تنفيذات تعتمد على fetch() ومعايير الويب فقط دون أي استيراد node:*، فتُجمَّع وتعمل على Workers بسلاسة؛ ويتحقق فحص التسرّب في البناء من كل حزمة. المزوّد ollama غير مدعوم هنا: فنقطته الافتراضية محلية http://localhost:11434 ولا يستطيع الـ Worker الوصول إليها؛ استخدم node-server أو docker معه؛
• الأدوات: current-date وday-name وhttp. الأداة web-fetch غير مدعومة. على Node ترفض http وweb-fetch الوجهات الخاصة بإجراء استعلام DNS خاص بهما (node:dns داخل Agent من undici) يفحص كل عنوان يُحلَّ إليه المضيف ويتصل بالعنوان الذي فحصه، فلا يستطيع هجوم DNS rebinding تجاوز الفحص. أما الـ Worker فلا يملك أيًّا من ذلك: إذ يحلّ fetch() الأسماء داخل شبكة Cloudflare ولا يتيح أي نقطة وصول لرؤية العنوان أو تثبيته. وما يستطيع الـ Worker فحصه هو عنوان URL (البروتوكول، واسم المضيف، والمضيف بصيغة عنوان IP)؛ أما ما لا يستطيع ضمانه فهو العنوان الذي يتصل به اسم المضيف، فالاسم الذي يُحلَّ إلى عنوان داخلي لن يُكتشف. لذلك فإن http في الـ Worker (باسم الأداة http_request ومدخلاتها نفسها كما على Node) أداة مختلفة: فهي لا تصل إلا إلى أسماء المضيفين التي تدرجها. وفي أول عنوان URL وعند كل إعادة توجيه ترفض:
  • أي بروتوكول غير http: وhttps:؛
  • مضيفًا بصيغة عنوان IP (http://10.0.0.1/ وhttp://[::1]/)، حتى لو كان مدرجًا: لا يوجد فحص للعناوين، لذا لا يُسمح إلا بالأسماء؛
  • مضيفًا لا يطابق الربط LOUSHO_HTTP_ALLOW، وهو قائمة مفصولة بفواصل من أسماء المضيفين (api.github.com) وبدائل *. العامة (*.example.com، وهي تطابق النطاقات الفرعية فقط ولا تطابق example.com). إذا كان الربط غير مضبوط أو فارغًا رُفض كل طلب (الإغلاق عند الفشل)؛ والإدخال الذي ليس اسم مضيف يُفشل كل طلب بخطأ يسمّيه.
  وبذلك لا يستطيع النموذج اختيار مضيف عشوائي ولا مضيف يستغل DNS rebinding، لأن الأسماء التي أدرجتها وحدها تمرّ؛ والاسم المدرج موثوق أينما حُلَّ، فلا تُدرج إلا مضيفين تتحكم بهم أو تثق بهم. يُتحقَّق من TLS دائمًا (لا يوجد خيار validateSSL) وتعمل الأداة دون بيئة معزولة. أما أداة من كتابتك تستدعي fetch() داخل Worker فلا تحصل من الـ SDK على أي حماية من SSRF.

​

البناء والنشر

cd .lousho/build/cloudflare-worker
npx wrangler dev       # local workerd runtime
npx wrangler deploy    # requires a Cloudflare account (`wrangler login`)

npx lousho build ./my-agent --target=cloudflare-worker
cd .lousho/build/cloudflare-worker && npx wrangler deploy

• يجب أن يسمّي model في الإعدادات مزوّدًا من الجدول أعلاه ("model": "openai/gpt-4o-mini")، مع مفتاحه في الربط OPENAI_API_KEY؛ أو أن يضبط agent.ts الخاصية provider على نسخة. لا توجد بيئة يُختار منها نموذج افتراضي، لذلك يُرفض المجلد الذي يخلو من الأمرين.
• يفحص lousho build إعدادات JSON/YAML؛ أما إعدادات agent.ts فتُفحص عند بدء الـ Worker، فيُبلغ wrangler deploy عن المشكلة.
• تُرفض subagents/ وschedules/ وchannels/ وmemory/ وprojectInstructions، مع تسمية المجلد أو المفتاح. استخدم node-server أو docker لها.
• تُجمَّع ملفات الأدوات من مواضعها، فتُحلّ استيراداتها النسبية و node_modules الخاصة بها كما في التطوير. والأداة التي تستورد وحدة Node مدمجة تُفشل فحص التسرّب في البناء، الذي يسمّي الملف.
• داخل أداة أو agent.ts، تكون @lousho/build-ai-agent مجموعة جزئية من الحزمة آمنة للـ Worker: defineTool وisDefinedTool وalways وnever وonce وdefineSkill وcreateMockProvider و MockLLMProvider وOpenAIProvider وAnthropicProvider وOpenRouterProvider وfromAiSdk و LLMProviderRegistry وtextOf وSDKError وConfigurationError وToolExecutionError و ValidationError. ويُفشل استيراد أي اسم آخر البناء مع عرض هذه القائمة؛ أما استيرادات الأنواع فقط فتعمل لكل نوع.

​

الارتباطات

[vars]
LOUSHO_HTTP_ALLOW = "api.github.com,*.example.com"

cd .lousho/build/cloudflare-worker
npx wrangler secret put LOUSHO_API_TOKEN
npx wrangler secret put OPENAI_API_KEY
npx wrangler deploy
curl -N https://<your-worker>.workers.dev/chat \
  -H "Authorization: Bearer $LOUSHO_API_TOKEN" -H 'Content-Type: application/json' \
  -d '{ "sessionId": "alice", "input": "Hello" }'

​

الجلسات ونقاط الحفظ والموافقات

import { createAgent } from '@lousho/build-ai-agent';
import { KVStore, type KVBinding } from '@lousho/build-ai-agent/kv';

interface Env {
  AGENT_KV: KVBinding;
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const agent = createAgent({ provider, store: new KVStore(env.AGENT_KV) });
    const { sessionId, input } = (await request.json()) as { sessionId: string; input: string };
    const { text } = await agent.session({ id: sessionId }).send(input);
    return Response.json({ text });
  },
};

​

التشغيلات المجدولة

import { createAgent, createMockProvider, defineSchedule, handleScheduled } from '@lousho/build-ai-agent';
import type { ScheduledContext, ScheduledController } from '@lousho/build-ai-agent';

const agent = createAgent({ instructions: 'You write reports.', provider: createMockProvider() });
const schedules = [defineSchedule({ name: 'weekly', cron: '0 9 * * MON', prompt: 'Summarise last week.' })];

export default {
  scheduled: (controller: ScheduledController, _env: unknown, ctx: ScheduledContext) =>
    handleScheduled(agent, schedules, controller, ctx),
};

​

الاتساق

​

حجم الحزمة ووحدات Node المدمجة