الانتقال إلى المحتوى الرئيسي
لم تُحدَّث ترجمة هذه الصفحة بعد، والنسخة الإنجليزية هي الأحدث والأصح، وقد يختلف المحتوى أدناه عنها. اقرأ النسخة الإنجليزية.

المتطلبات

  • Node.js 22.19 أو أحدث (engines.node في package.json، والرقم مفروض من الاعتمادية undici@8، التي تضع هي نفسها engines على >=22.19.0. ميزات Node الأخرى المرتبطة بإصدار معيّن والتي تستخدمها الـ SDK هي node:sqlite لـ SqliteStore (22.13) وإزالة الأنواع المدمجة (native type stripping) لملفات الـ agent بصيغة .ts (22.18)، وكلتاهما تحت هذا الحد الأدنى، فخفضه يعني تخفيف قيد اعتمادية undici أولًا. وundici لا تُحمَّل إلا عندما ترسل الأداة http_request أو web_fetch طلبًا، راجع Optional peers).
  • TypeScript اختيارية لكننا ننصح بها — الـ SDK تأتي مع type definitions كاملة.

تثبيت الحزمة

ai (وهي Vercel AI SDK: ^4.3.19 أو ^6.0.0 أو ^7.0.0) وzod (^3.25.76 || ^4.0.0) peer dependencies إجبارية. الإصدار ai 5 غير مدعوم. أي schema من الإصدارين الرئيسيين لـ zod تعمل في كل مكان تقبل فيه الـ SDK schema: defineTool({ input })، وoutput منظَّم، وأدوات MCP. يشمل هذا schemas من zod 4 عبر zod/v4 مع zod 3.25 مثبت، وschemas من zod 3 عبر zod/v3 على zod 4. حقل input في defineTool يمكن أن يكون أيضًا schema من مكتبة Standard Schema أخرى، إذا كانت تكشف الـ JSON Schema الخاصة بها (~standard.jsonSchema). الـ model يحتاج JSON Schema، فأي Standard Schema بلا واحدة تُرفض — استخدم zod لتلك الأدوات. حزم الـ providers الخاصة بـ ai 4 تعلن zod 3 كـ peer dependency، فاقرن zod 4 مع ai 6 أو 7.

حزم الـ providers

كل provider حقيقي لـ LLM يعتمد على peer dependency اختيارية، بالإصدار الرئيسي الذي يتوافق مع إصدار ai لديك. ثبّت الزوج من صف واحد: على الإصدار الرئيسي الحالي من ai مثلًا:
Ollama على ai 6/7 يحتاج zod 4. الحزمة ollama-ai-provider-v2 (حزمة Ollama لـ ai 6 و7) تعلن zod ^4 كـ peer dependency. الـ SDK تقبل zod 4، فثبّتها مع zod 4، مثلًا npm install ai@^7.0.0 ollama-ai-provider-v2@^4.0.0 zod@^4.0.0. مع zod 3 استخدم ai@^4.3.19 مع ollama-ai-provider@^1.2.0. وlousho init --provider ollama ينشئ المشروع بـ ai@^7.0.0 وollama-ai-provider-v2@^4.0.0 وzod 4. ما يختبره CI. كل تركيبة تقبلها نطاقات الـ peers تُثبَّت فعلًا وتمر على فحص الأنواع والـ build ومجموعة الاختبارات كاملة، مع كل تغيير: ai 4 مع zod 3 (هو تثبيت التطوير) ومع zod 4، وai 6 مع zod 3 ومع zod 4، وai 7 مع zod 3 ومع zod 4. حالتا zod 4 على ai 6 و7 تثبّتان أيضًا ollama-ai-provider-v2 (3.x و4.x) وتشغّلان provider الخاص بـ Ollama عليه، فدعم Ollama على ai 6/7 مُختبَر فعلًا وليس مفترَضًا. الـ peers تُحمَّل عند الطلب: استيراد lousho (أو أي من مداخلها الفرعية) لا يحمّل أي حزمة provider، فثبّت فقط التي تستخدمها. حزمة كل provider تُحمَّل أول مرة يجري فيها ذلك الـ provider استدعاء. إذا كانت ناقصة، يفشل الاستدعاء بـ MissingPeerDependencyError يحمل الأمر الدقيق الذي عليك تشغيله، بما يناسب إصدار ai الرئيسي المثبت عندك. بادئة النموذج vendor/ هي التي تحدد الـ provider؛ مع OpenRouter استخدم openrouter/<vendor>/<model> (مثل openrouter/openai/gpt-4o-mini). مع ai 4:

Optional peers

هذه الحزم أيضًا peer dependencies اختيارية. مشروع لا يستخدم أبدًا Docker sandboxing ولا MCP ولا OpenTelemetry tracing ولا bindings لـ React أو Vue ولا lousho build ولا أسئلة lousho init ولا code mode، لا يثبّت أيًّا منها: مثل حزم الـ providers، كل واحدة تُحمَّل عند أول استخدام وليس وقت الاستيراد. الناقصة منها تفشل ذلك الاستدعاء بـ MissingPeerDependencyError يذكر الميزة والأمر الدقيق، مثلًا:
npm create lousho يثبّت prompts بنفسه، فالـ scaffolding به لا يحتاج شيئًا إضافيًّا. وlousho doctor يسرد كل peer dependency اختيارية: ماذا تتيح وهل هي مثبتة (غياب dockerode خطأ فقط إذا كان ملف مواصفات الـ agent يستخدم أداة داخل sandbox). undici وyaml تبقيان اعتماديتين عاديتين. yaml تحلّل ملفات مواصفات الـ agents وملفات agent.yaml والـ skills، وليس في Node parser مدمج لـ YAML. أما undici فتُحمَّل عند أول طلب تجريه http_request أو web_fetch: كلتاهما تتصل عبر Agent من undici يفحص العنوان في DNS lookup ويثبّت الاتصال عليه، وhttp_request تحصر أيضًا validateSSL: false في ذلك Agent. الـ fetch العامة لا توفّر أيًّا من هذين السلوكين.

حجم الحزمة

الـ tarball حجمه نحو 4 MB مضغوطًا (15 MB بعد فك الضغط). هذه مقايضة مقصودة ومعلنة، لا مصادفة: المجلد src/ يُشحن لأن lousho build يجمّع src/deploy/runtime.worker.ts وsrc/index.ts من الحزمة المثبتة، ولأن source maps في dist/ تشير إليه (الـ maps لا تحمل الكود المصدري مضمَّنًا فيها؛ وتضمينه بدلًا من ذلك مع حذف src/ أعطى حجمًا أكبر عند القياس، 5.2 MB مضغوطًا). أما apps/agent-forge/ فهي لوحة التحكم المبنية مسبقًا التي يقدّمها lousho studio. والملف llms-full.txt بحجم 1 MB موجود في المستودع، لا في الحزمة.

نقاط الدخول تتشارك الكود (ESM وCJS)

مداخل الحزمة (. و./hooks و./tools و./mcp وغيرها) مبنية بـ code splitting: تستورد chunks مشتركة من dist/. لذلك class أو singleton مثل HookRegistry أو SDKError أو globalToolRegistry هو الكائن نفسه أيًّا كان المدخل الذي يصدّره وتستورده أنت منه، ضمن صيغة modules واحدة (globalToolRegistry يصدّره ./executor و./tools، لا الجذر). لكن import من ESM وrequire من CJS للحزمة في عملية واحدة يحمّلان نسختين منفصلتين (dual-package hazard المعروف في Node)، فالـ class من إحداهما ليس === نظيره من الأخرى. instanceof SDKError، وinstanceof لكل subclass من SDKError تصدّرها الـ SDK (ValidationError وTimeoutError وRateLimitError وLLMProviderError وMissingPeerDependencyError وغيرها)، وinstanceof HookRegistry، كلها آمنة بين النسختين لأنها تفحص علامة Symbol.for؛ لبقية الـ classes استخدم صيغة modules واحدة في العملية. نقاط الدخول التي يصرّح بها exports، وماذا تحتوي كل واحدة:

إعدادات TypeScript

ملفات الـ declarations تجتاز فحص الأنواع مع skipLibCheck: false على zod 3 وzod 4، ومع moduleResolution بالقيم bundler وnodenext وnode16 (ESM). تركيبة واحدة فقط تفشل، وسببها من المصدر الأعلى (upstream): مشروع CommonJS (بلا "type": "module") مع module/moduleResolution: "node16" وai 7. فـ ai 7 تُشحن كـ ES modules فقط، ووضع node16 في TypeScript لا يسمح لكود CommonJS باستيراد تلك الأنواع (الخطأ TS1479 داخل declarations الخاصة بالـ SDK). استخدم "module": "nodenext" (يحلّها) أو "moduleResolution": "bundler"، أو أضف "type": "module"، أو أبقِ skipLibCheck: true (وهو ما تستخدمه مشاريع lousho init). declarations المدخل الجذر تستخدم أنواع Node (Buffer، واستيرادات من node:crypto وnode:http وnode:net)، فثبّت @types/node. TypeScript 6 لم تعد تحمّل كل حزم @types افتراضيًّا (القيمة الافتراضية لـ types صارت [])، فعلى TypeScript 6 وما بعدها أضفها أيضًا في tsconfig.json، وإلا سيُبلغ skipLibCheck: false عن Cannot find name 'Buffer' وCannot find module 'node:http' داخل declarations الخاصة بالـ SDK:

التثبيت من build محلي

لتجربة commit غير منشور، اعمل build للـ SDK وحزّمها من checkout محلي لهذا المستودع، ثم ثبّت الـ tarball في مشروعك. هي الطريقة نفسها التي يستخدمها lousho init --sdk-path في المشاريع التي ينشئها. الـ CI يتحقق منها عبر npm run pack-smoke، الذي يثبّت الـ tarball في مشروع جديد ويحمّل كل نقطة دخول، في ESM وCJS:
ولعمل scaffold لمشروع جديد بالطريقة نفسها، من الـ checkout: node bin/lousho.js init ../my-agent --sdk-path .. على Windows، الأمر npx C:\abs\path\create-lousho-<version>.tgz لا يفعل شيئًا بصمت (سلوك غريب في npm مع المسارات المطلقة التي تبدأ بحرف قرص). استخدم بدلًا منه مسارًا نسبيًّا (npx ./create-lousho-<version>.tgz my-agent) أو صيغة file: (npx file:C:/abs/path/create-lousho-<version>.tgz my-agent). الأمر npm install github:LinuxDevil/lousho لا يعمل: dist/ غير موجود في git، وليس في المستودع خطوة prepare تعمل build، فينتهي التثبيت بلا نقاط دخول.

إنشاء مشروع جديد

lousho init ينشئ مشروعًا جاهزًا للتشغيل: package.json (ESM، ويعتمد على هذه الـ SDK بنطاق إصدار)، وtsconfig.json strict، وsrc/agent.ts يستدعي createAgent({ model, instructions }) مع أداة مثال معرَّفة بـ defineTool()، وsrc/agent.test.ts يعمل offline باستخدام mockModel، و.env.example يذكر اسم متغير مفتاح الـ provider عندك، و.gitignore، وREADME، وملف AGENTS.md (ومعه ملف CLAUDE.md من سطر واحد يستورده) يعرّف coding agents بملفات المشروع وسكربتاته وأعرافه. بعدها يثبّت الاعتماديات ويشغّل git init.
create-lousho (packages/create-lousho) مجرد غلاف بسيط يشغّل lousho init بنفس الوسائط.

الـ CLI lousho

تثبيت الحزمة يثبّت أيضًا أمر lousho: init وdoctor وdev وchat وacp وadd وmcp وeval وtraces وbuild وstudio. راجع الـ CLI لما يفعله كل واحد وخياراته. الـ build يحتاج tsup، وهي peer dependency اختيارية (راجع الجدول أعلاه): npm install --save-dev tsup.

استكشاف الأخطاء: lousho doctor

شغّل npx lousho doctor مباشرة بعد التثبيت. يطبع سطرًا لكل فحص مع حالته (ok أو warn أو FAIL) وما وجده، ولكل شيء غير سليم يطبع الأمر الذي تشغّله أو الإعداد الذي تغيّره:
ما يفحصه:
  1. إصدار Node عندك مقابل engines.node في الحزمة.
  2. الـ peers الإجبارية ai وzod: مثبتة وضمن نطاق peerDependencies الخاص بالـ SDK (يُحلَّ من المجلد الحالي).
  3. حزم الـ providers الاختيارية (@ai-sdk/openai و@ai-sdk/anthropic، وollama-ai-provider على ai 4 أو ollama-ai-provider-v2 على ai 6/7)، مع أمر npm install لكل ناقصة. حزمة provider لا تتوافق مع ai المثبت (مثلًا ai 7 مع @ai-sdk/openai 1.x) تُعلَّم مع الإصدار الذي عليك تثبيته بدلًا منها.
  4. هل متغير مفتاح API لكل provider مضبوط. يُطبع فقط اسم المتغير وset أو not set، ولا تُطبع القيمة أبدًا. وعندما يكون OPENAI_BASE_URL أو ANTHROPIC_BASE_URL مضبوطًا (سيرفر محلي أو متوافق مع OpenAI)، يعرض سطر ذلك الـ provider أيضًا الـ base URL، بلا أي بيانات اعتماد أو query string فيه. ويعرض أيضًا أي provider سيختاره createAgent() افتراضيًّا في بيئتك. ويُعرض OPENAI_BASE_URL عندما يكون مضبوطًا (بلا أي بيانات اعتماد أو query فيه).
  5. مع مسار ملف مواصفات (lousho doctor agent.yaml): تُتحقَّق صحة الملف مع مسارات الحقول لكل خطأ، وتُفحص حزمة الـ provider والمفتاح (الناقص منهما يصبح إخفاقًا)، ويجب أن تكون عناصر tools أدوات مدمجة، وأن يكون أي أمر في mcpServers قابلًا للحل. أما مجلد agent أو module لـ agent بصيغة .ts/.js (lousho doctor src/agent.ts، وهو ما يشغّله npm run doctor في مشروع مُنشأ بـ scaffold) فيُحمَّل بالطريقة التي يحمّله بها lousho dev، وتُفحص حزمة الـ provider الخاصة بالـ model ومفتاحه بالطريقة نفسها. بدون مسار، غياب المفتاح مجرد تحذير، لأن doctor لا يمكنه معرفة أي provider يستخدمه الـ agent عندك.
  6. إمكانية الوصول إلى Ollama — فقط إذا استخدم ملف المواصفات Ollama أو كان OLLAMA_HOST مضبوطًا.
  7. توفر Docker — تحذير فقط إذا استخدم ملف المواصفات أداة داخل sandbox.
  8. مع --ping: طلب GET لكل provider متغيره مضبوط، بمهلة 5 ثوانٍ، إلى endpoint يتطلب المفتاح: /models لـ OpenAI وAnthropic، و/api/v1/key لـ OpenRouter (لأن /models عنده يجيب بلا مفتاح). المفتاح المرفوض (HTTP 401/403) إخفاق؛ والسيرفر الذي لا يمكن الوصول إليه تحذير. مع ضبط OPENAI_BASE_URL يُرسل ping إلى <base>/models، ويوضّح السطر أنه يبيّن إمكانية الوصول فقط، لأن السيرفر المحلي قد لا يتحقق من المفاتيح. المفاتيح تُرسل إلى الـ provider الخاص بها فقط ولا تُطبع أبدًا.
على Windows تستخدم أسطر الإصلاح صيغة PowerShell ($env:OPENAI_API_KEY="<your key>") بدلًا من export. رمز الخروج 1 إذا فشل أي فحص و0 غير ذلك (التحذيرات لا تفشل)، فيصلح بوابة لـ CI. أضف --json لمخرجات تقرؤها الآلة. الألوان تُستخدم فقط عندما يكون stdout على terminal وNO_COLOR غير مضبوط. للمشكلات غير المتعلقة بالتثبيت، راجع استكشاف الأخطاء وإصلاحها. قادم من إصدار 1.0.0-alpha.*؟ راجع الترقية إلى 1.0 للواردات التي انتقلت وواجهات API المحذوفة والمعاد تسميتها. التالي: البدء السريع.