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

من يحتاج هذه الصفحة

أي شخص عنده كود مكتوب على 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.
الـ CI يقارن التقارير في كل pull request، فأي تغيير في السطح العام يكون دائمًا diff مقصود ومُراجَع.