من يحتاج هذه الصفحة
أي شخص عنده كود مكتوب على1.0.0-alpha.8 أو إصدار 1.0.0-alpha.*
أقدم. بين هذه الإصدارات وخط 1.0 (التغييرات المذكورة تحت
1.0.0-alpha.19 في الـ changelog، والتي نُشرت أول مرة في 1.0.0-alpha.15)
أعدنا تنظيم السطح العام للحزمة. الـ imports انتقلت إلى subpaths. حذفنا
الـ APIs الميتة أو التي أصبح لها بديل. وأصبح اسم الـ patch guardrails
patch checks. createAgent() وخياراتها لم تتغير — الـ agent الذي لا يستخدم إلا
createAgent({ model, instructions, tools }) وagent.send() يترقّى
بتغيير رقم الإصدار فقط.
أنت أصلاً على 1.0.0-alpha.19؟ انتقل مباشرة إلى
الترقية من alpha.19 لتعرف ما تغيّر على main
بعده.
مسارات الـ import التي انتقلت
جذر الحزمة الآن فيهcreateAgent() والأسماء التي تستخدمها إعداداتها
ونتائجها. كل ما في الجدول أدناه انتقل إلى subpath خاص به. التعريفات نفسها لم
تتغير، لكن مكانها تغيّر.
الـ subpath
lousho/core لم يعد موجودًا؛ كل ما كان
يصدّره أصبح تحت /executor.
APIs محذوفة وبدائلها
AgentTypeوAgentTypeDescriptorوAgentConfig.agentTypeوAgentBuilder.setType()والـ agent-type registry (agentTypesRegistry,getAgentTypeDescriptor,getAllAgentTypeDescriptors,isValidAgentType,validateAgentConfig,validateAgentTools). لم يكن لها أي أثر في الـ runtime: احذف استدعاءsetType(...)وحقلagentType. الـ checkpoint (نقطة الحفظ) المحفوظ معagentTypeيُفتح بشكل عادي؛ الحقل يُتجاهَل.ExecuteOptions.onEventونوعاExecutionEvent/ExecutionEventType. مرّرonAgentEventلـAgentExecutor.execute()/stream()/resumeAfterApproval()بدلها؛ الأحداث التي تصلك الآن هيAgentEvent. جدول مقابلة أسماء الأحداث في Streaming. ومعcreateAgent()، الـonEventأصلاً يستقبلAgentEventولم يتغير.createDelegateTool()وDelegateAgentOptionsوDelegateAgentResultوDelegationDepthExceededError. استخدم خيارsubagentsفيcreateAgent()أوAgentExecutor.execute(): الـ model يحصل على tool باسمtaskلكل sub-agent (وكيل فرعي)، مع حد للعمق (maxSubagentDepth، الافتراضي1) بدل الخطأ الذي كان يُرمى. انظر Sub-agents.- أنواع لم ينفّذها ولم يستخدمها أي كود: واجهات الـ repository
(
IRepository,IAgentRepository,ISessionRepository,IResultRepository,SessionData,ResultData,SDKRepositories)، وDataLoadingStatus، وPaginationParams، وPaginatedResponse، وDeepPartial، وTimestamped، وIdEntity، وAgentExecutionOptions، وAgentExecutionResult، وAgentDefinitionوToolSetting. لو كودك يستخدم واحد منها، انسخ تعريفه إلى مشروعك.
APIs بأسماء جديدة
أصبح اسم الـ patch guardrails هو patch checks، لكي لا تعني كلمة guardrail إلا الـ guardrails الخاصة بالمدخلات والمخرجات والأدوات فيcreateAgent({ guardrails }). المعاملات والنتائج والسلوك نفسها لم
تتغير. وSECRET_PATTERNS احتفظ باسمه. انظر
Guardrails والـ sandbox.
الانتقال من الـ triggers
حذفناWebhookTriggerAdapter وSlackTriggerAdapter وCronTriggerAdapter وأنواع الخيارات والـ handle الخاصة بها من lousho/triggers. أما TriggerAdapter وTriggerRegistry وhelpers الخاصة بـWebhookAuth وverifySlackSignature() وparseCronExpression() فباقية. انظر Triggers.
Deprecated لكنها ما زالت تعمل في 1.x
هذه الأسماء تعمل في 1.x وتُحذف في 2.0. انتقل عنها بمجرد أن تعدّل الكود؛ ولن ينكسر شيء لو لم تفعل.تغييرات أخرى في السلوك منذ alpha.8
القائمة الكاملة في CHANGELOG. هذه هي البنود التي تغيّر سلوك الـ runtime أو أنواعًا قد يعتمد عليها كودك، سطر لكل بند:- النقل والحذف وإعادة التسمية الواردة أعلاه هي قسم
### Breaking. والملاحظات الواردة أدناه هي بنود### Changedالتي تغيّر السلوك. - إذا كانت
executeفي tool تُرجع async generator، فأصبح يُستهلك بالتكرار - آخر قيمة يُخرجها هي النتيجة - وأصبحAgentEventيحتويtool.partial(ToolPartialEvent). إذا كنت تقصد إرجاع generator كقيمة، فغلّفه:{ items: generator }. انظر Tools وStream events. - أصبح
AgentEventيحتوي حدثhandoff، وأصبحExecutionResultيحتوي الحقل الاختياريagentName: إذا كان لديكswitchشامل علىevent.typeفيجب أن تضيف case لـhandoff. انظر Handoffs. - أصبح
McpServerStatusيحتوي'needs-auth'، وأصبحAgentOAuthيحتويmcpSignInUrl(server): الـswitchالشامل علىconnectMcp().status()يحتاج الـ case الجديدة. انظر MCP وOAuth. - أصبح
ToolExecutionContextيحتويgetToken(provider)وrequireAuth(provider)، وأصبحApprovalKindيحتوي'sign-in': إذا كنت تبني tool context بنفسك في test، فيجب أن تضيف الدالتين (أو تُجري cast). انظر OAuth. - مع listener (
createAgent({ onEvent }),onAgentEvent)، أصبحتsend()وexecute()تبثّان استدعاءات الـ model: يصلك نص الخطوة على عدة أحداثtext.deltaبدل حدث واحد.execute({ streamModelCalls: false })يُعيد الشكل القديم. انظر Stream events. MockLLMProvider/createMockProvider(): أصبحتstream()تبث الخطوة نفسها التي تُرجعهاgenerate()- نفس الـ tool calls والـ finish reason والـ usage - فالـ run المبثوث بـmock يستدعي الـ tools مثلsend(). انظر Testing.- الـ runs في Agent Forge تبث استدعاءات نماذجها؛ عروض المحادثة والسجلات والـ trace لم تتغيّر. انظر Agent Forge.
lousho init --provider ollamaأصبح يجهّزai@^7معollama-ai-provider-v2@^4وzod@^4(كانai@^4معollama-ai-provider@^1وzod 3). لا تتأثر المشاريع القائمة. انظر Installation.- عندما يتوقف run داخل sub-agent، يُقارَن الـ sub-agent عند الاستئناف
بتعريفه الحالي، حسب
onAgentDriftلدى الـ lead - ومع'error'أصبح الـ sub-agent المتغيّر يرفضagent.approvals.resolve()أيضًا. انظر Durable execution. lousho addيفرض الـ permission manifest الخاص بالـ registry وقت التثبيت، ومجلد الـ agent المحمَّل يشغّل tools كل عنصر داخل الـ manifest المقبول الخاص به (الـ approval مفعّل دائمًا لعناصرexec/needsApproval/غير الموثقة، وfetchوprocess.envمحصورين بنطاق التصريح المعلن)؛ الكود غير المطابق يُرفض بـLOUSHO_REGISTRY_MANIFEST_MISMATCH، و--yesيحتاج--allowللصلاحيات المرتفعة. انظر Registry.- متابعة run محفوظ بـcheckpoint وغير مكتمل بـ
principalمختلف عن الذي حُفظ معه أصبحت ترميLOUSHO_CONFIG_INVALID؛ الـ checkpoints وsnapshots الخاصة بالـ approval تخزّن الـ principal الخاص بالـ run. انظر Route auth and principals. - أصبحت الـ memory slots تخزّن عناصرها تحت
<slot name>#<scope key>(notes#global) بدل مفتاح النطاق وحده (global)، فلم يعد slotان لهما النطاق نفسه يتشاركان العناصر. العناصر التي كتبها1.0.0-alpha.19أو أقدم لم تعد تُقرأ؛ شغّلmigrateMemoryKeys(slot)مرة واحدة لكل slot لتنسخها. انظر Memory. - أصبحت الحزمة المنشورة أصغر: ملفات الاختبار لم تعد تُشحن، والـ
source maps لم تعد تضمّن
sourcesContent(لكنsourcesفيها ما زالت تشير إلىsrc/المشحون). لا يوجد تغيير في الـ API.
الترقية من alpha.19
1.0.0-alpha.19 هو آخر إصدار على npm. التغييرات على main من بعده
(قسم [Unreleased] في CHANGELOG) أغلبها إصلاحات
وإضافات، لكن بعضها يغيّر قيمة افتراضية أو سلوكًا قد يعتمد عليه كودك.
كلٌّ منها مذكور أدناه مع طريقة الرجوع إلى السلوك القديم، إن وُجدت.
التغيير المعلَّم بـ”لا يمكن تعطيله” سدّ ثغرة أمنية أو خللًا يضيّع البيانات.
الـ HTTP routes والسيرفرات والـ channels
الـ sessions والـ approvals والمتانة
الـ providers واستدعاءات الـ model
الـ tools والـ MCP والتتبّع
الـ CLI والـ evals وAgent Forge
ما تعد به 1.0
من إصدار 1.0، الحزمة تتبع semver على سطحها العام:- عام (public): كل entry point يعلنه
exports- الجذرloushoوالـ subpaths/executorو/toolsو/flowsو/integrationsو/utilsو/mcpو/typesو/testingو/otelو/hooksو/sqliteو/authو/kvو/workerو/tracesو/triggersو/reactو/vueو/svelte- وكل اسم في تقارير الـ API المودعة في المستودع (api/index.api.md,api/executor.api.md, … في المستودع). حذف واحد منها أو إعادة تسميته أو تغيير توقيعه يحتاج major version. - داخلي (internal): كل شيء آخر، بما فيه الـ deep imports داخل
dist/أوsrc/(أي مسار لا يذكرهexports) والأسماء التي يستخدمها توقيع عام لكن لا يصدّرها (بنودae-forgotten-exportفي التقارير). هذه قد تتغير في أي إصدار. - Deprecated: الأسماء المعلّمة بـ
@deprecatedتظل تعمل طوال 1.x وتُحذف في 2.0.