المتطلبات
- 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 مثلًا:
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:
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) وما وجده، ولكل شيء غير سليم يطبع الأمر الذي تشغّله أو الإعداد الذي تغيّره:
- إصدار Node عندك مقابل
engines.nodeفي الحزمة. - الـ peers الإجبارية
aiوzod: مثبتة وضمن نطاقpeerDependenciesالخاص بالـ SDK (يُحلَّ من المجلد الحالي). - حزم الـ providers الاختيارية (
@ai-sdk/openaiو@ai-sdk/anthropic، وollama-ai-providerعلىai4 أوollama-ai-provider-v2علىai6/7)، مع أمرnpm installلكل ناقصة. حزمة provider لا تتوافق معaiالمثبت (مثلًاai7 مع@ai-sdk/openai1.x) تُعلَّم مع الإصدار الذي عليك تثبيته بدلًا منها. - هل متغير مفتاح API لكل provider مضبوط. يُطبع فقط اسم المتغير و
setأوnot set، ولا تُطبع القيمة أبدًا. وعندما يكونOPENAI_BASE_URLأوANTHROPIC_BASE_URLمضبوطًا (سيرفر محلي أو متوافق مع OpenAI)، يعرض سطر ذلك الـ provider أيضًا الـ base URL، بلا أي بيانات اعتماد أو query string فيه. ويعرض أيضًا أي provider سيختارهcreateAgent()افتراضيًّا في بيئتك. ويُعرضOPENAI_BASE_URLعندما يكون مضبوطًا (بلا أي بيانات اعتماد أو query فيه). - مع مسار ملف مواصفات (
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 عندك. - إمكانية الوصول إلى Ollama — فقط إذا استخدم ملف المواصفات Ollama أو كان
OLLAMA_HOSTمضبوطًا. - توفر Docker — تحذير فقط إذا استخدم ملف المواصفات أداة داخل sandbox.
- مع
--ping: طلبGETلكل provider متغيره مضبوط، بمهلة 5 ثوانٍ، إلى endpoint يتطلب المفتاح:/modelsلـ OpenAI وAnthropic، و/api/v1/keyلـ OpenRouter (لأن/modelsعنده يجيب بلا مفتاح). المفتاح المرفوض (HTTP 401/403) إخفاق؛ والسيرفر الذي لا يمكن الوصول إليه تحذير. مع ضبطOPENAI_BASE_URLيُرسل ping إلى<base>/models، ويوضّح السطر أنه يبيّن إمكانية الوصول فقط، لأن السيرفر المحلي قد لا يتحقق من المفاتيح. المفاتيح تُرسل إلى الـ provider الخاص بها فقط ولا تُطبع أبدًا.
$env:OPENAI_API_KEY="<your key>") بدلًا من export.
رمز الخروج 1 إذا فشل أي فحص و0 غير ذلك (التحذيرات لا تفشل)، فيصلح بوابة لـ CI. أضف --json لمخرجات تقرؤها الآلة. الألوان تُستخدم فقط عندما يكون stdout على terminal وNO_COLOR غير مضبوط.
للمشكلات غير المتعلقة بالتثبيت، راجع استكشاف الأخطاء وإصلاحها.
قادم من إصدار 1.0.0-alpha.*؟ راجع الترقية إلى 1.0 للواردات التي انتقلت وواجهات API المحذوفة والمعاد تسميتها.
التالي: البدء السريع.