بيئة تشغيل الأدوات

بيئة تشغيل الأدوات هي الحد الفاصل بين خرج المزوّد والفعل المحلي. تسجل الأدوات المتاحة، وتحول استدعاءات أدوات المزوّد النهائية إلى خطط، وتطبق سياسة الأمان، وتنفّذ الأدوات الموافق عليها، وتحزم النتائج، وتسجل بنية كافية للمتابعة الآمنة والسجل الآمن لإعادة التمرير.

تركز هذه الصفحة على سلوك بيئة التشغيل. قائمة الأدوات الموجهة للمستخدم موجودة في الأدوات.

ما الذي تغطيه هذه الصفحة

استخدم هذه الصفحة عندما تحتاج إلى فحص:

ما الأدوات التي سُجلت لبيئة تشغيل معينة
كيف تتحول استدعاءات أدوات المزوّد إلى خطط قابلة للتنفيذ
لماذا سُمح لأداة، أو رُفضت، أو حُجبت، أو أُجلت
كيف تفشل استدعاءات الأدوات المشوهة أو غير المعروفة
كيف تُطبّع معرفات استدعاءات الأدوات
كيف يمكن للأدوات الآمنة أن تعمل بالتوازي
كيف تُحزم نتائج الأدوات وتُحفظ
كيف تصطف نتائج الأدوات مع السجل الأصلي للمزوّد

هذه الصفحة ليست كتالوجًا لكل أداة متاحة. إنها تشرح مسار التنفيذ الذي تمر عبره الأدوات المطلوبة من المزوّد.

تركيب بيئة التشغيل

تُجمع الأدوات أثناء إنشاء بيئة التشغيل. ينشئ AgentLoopBuilder سجل الأدوات ويضع مراحل التسجيل حول إعداد بيئة التشغيل.

الأجزاء المهمة في التركيب هي:

السطح	الدور
`ToolRegistry`	يحتفظ بتعريفات الأدوات المسجلة.
`ToolExecutor`	يطبق السياسة وينفّذ أداة مسجلة بعد الموافقة عليها.
`ToolCallPlanner`	يحول استدعاءات أدوات المزوّد النهائية إلى خطط قابلة للتنفيذ.
`ToolPlanRunner`	يشغّل استدعاءات أدوات المزوّد المخططة، ويصدر أحداث النشاط، ويتعامل مع التوازي الآمن، ويعيد حالة التنفيذ.
`NativeToolExecutor`	ينفّذ أدوات القصد الأصلي الحتمية التي يختارها موجّه بيئة التشغيل.

التسجيل مرحلي حتى تتمكن بيئة التشغيل من تسجيل الأدوات الأساسية، وتطبيق رؤية المهارات، وإرفاق الأدوات المعتمدة على الذاكرة أو المزوّد، وإنهاء توصيل المنفّذ دون أن يمتلك كل نظام فرعي السجل كاملًا.

مراحل التسجيل

يتم تسجيل مزوّدي الأدوات في مراحل مسماة:

المرحلة	الغرض
`pre-skill-visibility`	يسجل الأدوات الأساسية قبل حساب رؤية المهارات.
`post-skill-visibility`	يسجل الأدوات التي تعتمد على مجموعة مهارات الجلسة المرئية.
`post-memory-provider`	يسجل الأدوات التي تعتمد على توصيل مزوّد الذاكرة.
`post-tool-executor`	يسجل الأدوات التي تحتاج إلى المنفّذ أو مدير التفويض.

تُسجل أدوات MCP قبل مراحل تسجيل الأدوات المخططة. بعد التسجيل، تأخذ بيئة التشغيل لقطة من الأدوات المتاحة وتبني schemas الأدوات التي يمكن عرضها على النموذج.

مسار التنفيذ

يبدأ تنفيذ الأدوات المطلوبة من المزوّد فقط بعد إنهاء خرج المزوّد:

يعيد المزوّد استدعاءات أدوات نهائية.
تُطبّع معرفات استدعاءات الأدوات المفقودة مرة واحدة.
يحوّل ToolCallPlanner كل استدعاء إلى خطة أداة.
يجمع ToolPlanRunner استدعاءات أدوات المزوّد المخططة.
يطبق ToolExecutor سياسة الأمان، وحالة الموافقة، وثقة المساحة العملية، وسلامة الأمر.
تستدعي الأدوات المسموح بها handler الأداة المسجلة.
تُحفظ حزمة النتيجة وتُرسل مرة أخرى عبر المتابعة.

أجزاء البث، والبث غير المكتمل، وJSON المشوه، واستدعاءات الأدوات المقتطعة بسبب الطول لا تتجاوز هذا المسار. إذا لم يكن استدعاء الأداة نهائيًا، فهو غير قابل للتنفيذ.

التخطيط والسياسة

ToolCallPlanner هو أول حد منظم بعد إنهاء خرج المزوّد. يتحقق من استدعاء المزوّد، ويحل الأداة المسجلة، ويحلل الوسائط، وينتج خطة يمكن لبيئة التشغيل تنفيذها أو رفضها.

تحمل خطط الأدوات اسم الأداة، والوسائط المحللة، والمصدر، والحالة، ولاحقًا النتيجة أو حالة الخطأ. تأتي فئة الخطر، ومجموعات الأدوات، وقرار الأمان من تعريف الأداة المسجل وسجل التنفيذ.

فئات الخطر قيم صريحة في بيئة التشغيل، وتشمل:

read-only-local
read-only-network
workspace-write
external-side-effect
credential-access
destructive-local
shared-state-mutation
spend-money
sandbox-escape

هذه هي فئات سياسة بيئة التشغيل المستخدمة في تنفيذ الأدوات. قد تجمعها الوثائق الأعلى مستوى ضمن تسميات أوسع موجهة للمستخدم.

تقرر سياسة الأمان، وحالة الموافقة، وثقة المساحة العملية، وسلامة الأمر، ووضع الموافقة في بيئة التشغيل هل يمكن للتنفيذ أن يتابع. الأدوات عالية الخطر أو المحجوبة يجب أن تفشل باتجاه المنع بدل أن تهبط بصمت إلى التنفيذ.

فشل التخطيط

يمكن لاستدعاء أداة من المزوّد أن يفشل قبل التنفيذ إذا كان اسم الأداة غير معروف، أو كانت الوسائط مشوهة، أو كانت وسائط مطلوبة مفقودة، أو فشل التحقق من schema، أو حجبت السياسة الأداة المحلولة.

تُبلغ حالات فشل التخطيط عبر حلقة جولات المزوّد كحالة نتيجة أداة حيث يكون ذلك مناسبًا. لا تُنفّذ، ولا تتجاوز السياسة بالرجوع إلى shell، أو تنفيذ قصد أصلي، أو مسار أداة آخر.

مشغّل خطط الأدوات

يملك ToolPlanRunner تنفيذ خطط الأدوات المطلوبة من المزوّد داخل جولة مزوّد.

هو مسؤول عن:

تخطيط استدعاءات أدوات المزوّد عبر ToolCallPlanner
إصدار أحداث نشاط الأدوات
تجميع أدوات المزوّد الآمنة لتنفيذ متوازٍ محدود
استدعاء ToolExecutor للأدوات الموافق عليها
تحزيم خرج تنفيذ الأدوات
تتبع الخطر المرصود
إعادة نتائج الأدوات وحالة الفشل إلى حلقة جولات المزوّد

تُفرض ميزانيات فشل الأدوات المتكرر بواسطة ProviderTurnLoop باستخدام النتائج الراجعة من تنفيذ الأدوات. يبلّغ المشغّل عما حدث؛ وتقرر حلقة المزوّد هل تجاوزت حالات الفشل المتكررة ميزانية الجولة.

توازي الأدوات الآمنة

يمكن لبعض الأدوات المطلوبة من المزوّد أن تعمل بالتوازي. التوازي محدود عمدًا.

يقتصر التجميع المتوازي الآمن على فئات الخطر الخاصة بالقراءة فقط:

read-only-local
read-only-network

ما زالت بيئة التشغيل تستبعد الأدوات التي يجب أن تبقى متسلسلة حتى لو بدت للقراءة فقط من حيث فئة الخطر. أدوات الأوامر والعمليات لا تُجمع ضمن المجموعة المتوازية الآمنة.

يُهيأ الحد الأقصى للتوازي الآمن عبر باني بيئة التشغيل. هذا يمنع أعمال الفحص منخفضة الخطر من أن تصبح عنق زجاجة تسلسليًا دون السماح للأدوات ذات الآثار الجانبية بأن تتسابق.

منفّذ الأدوات الأصلي

NativeToolExecutor منفصل عن استدعاءات الأدوات المطلوبة من المزوّد.

يتعامل مع تنفيذ القصد الأصلي الحتمي الذي يختاره موجّه بيئة التشغيل. مسار القصد الأصلي الحالي ليس بديلًا عامًا عن استدعاءات أدوات المزوّد، أو أوامر slash، أو تخطيط الأدوات. استدعاءات الأدوات التي ينتجها المزوّد ما زالت تمر عبر الإنهاء، والتخطيط، والسياسة، والتنفيذ، والمتابعة.

حافظ على هذا الفصل واضحًا:

المسار	المصدر	سطح بيئة التشغيل
استدعاء أداة من المزوّد	استجابة مزوّد نهائية	`ToolCallPlanner` و`ToolPlanRunner`
قصد أصلي	قرار موجّه بيئة التشغيل	`NativeToolExecutor`
أمر slash	معالجة أوامر CLI/الجلسة	أسطح أوامر الجلسة

قد تستخدم هذه المسارات بعض الأدوات المسجلة نفسها، لكنها ليست مسار التحكم نفسه.

المعرفات الثابتة

تعتمد إعادة التمرير الأصلية للمزوّد على اتساق المعرفات. عندما لا يرسل المزوّد معرف استدعاء أداة، يشتق EstaCoda معرفًا باستخدام stableToolCallId().

تُستخدم المعرفات المطبّعة نفسها في:

جولة استدعاءات أدوات المزوّد المحفوظة
ToolCallPlanner
metadata.tool_call_id في نتيجة الأداة
مطابقة باني السجل الأصلي
serialization الخاص بـ OpenAI-compatible Chat Completions

لا يوجد مسار معرفات منفصل خاص بالتخطيط فقط. إذا تباعدت المعرفات، يجب أن تفشل إعادة التمرير الأصلية باتجاه المنع بدل اختراع رابط.

حفظ استدعاءات أدوات المزوّد

عند وجود استدعاءات أدوات نهائية، تحفظ بيئة التشغيل جولة استدعاءات أدوات مزوّد واحدة قبل تنفيذ الأدوات. تحتوي رسالة الجلسة على:

role: "agent"
metadata.kind: "provider-tool-call-turn"
metadata.providerToolCalls
metadata.nativeReplaySafe

يُحفظ محتوى assistant غير الفارغ على تلك الرسالة. لا تنشئ طبقة إعادة التمرير نتائج أدوات اصطناعية. ما زال تنفيذ الأدوات يسجل النتيجة الفعلية عبر مسار النتائج القائم.

هذا الترتيب مهم: تحتاج إعادة التمرير الأصلية إلى جولة استدعاءات أدوات assistant الدقيقة التي أنتجها المزوّد، بينما ما زال تنفيذ الأدوات يحتاج إلى بوابات الأمان وسلوك الموافقة العاديين.

السجل الآمن لإعادة التمرير

أمان إعادة التمرير الأصلية على مستوى الجولة لأن نتائج الأدوات يجب أن تطابق مجموعة استدعاءات أدوات assistant بدقة. إذا كان استدعاء واحد داخل جولة مزوّد متعددة الاستدعاءات غير آمن، تصبح المجموعة الأصلية كلها غير آمنة.

مجموعات الأدوات وحدات ذرية في السجل الأصلي:

agent(provider-tool-call-turn)
tool(result for call A)
tool(result for call B)

تُحفظ المجموعات الكاملة كاملة أو تُضغط كاملة. لا تُقسّم المجموعات متعددة الاستدعاءات. المجموعات النشطة، أو غير المكتملة، أو غير الآمنة لا تُسلسل كسجل أصلي.

راجع بيئة تشغيل المزوّد لقواعد echo الخاصة بالمزوّد، وقواعد serializer، وحدود الضغط، وتشخيصات إعادة التمرير الأصلية.

المتابعة

بعد تشغيل الأدوات، ترسل متابعة المزوّد نتائج الأدوات مرة أخرى إلى النموذج.

للمسارات غير المدعومة، تستخدم المتابعة مسار النص المسطح القائم Executed tool results. للمسارات الأصلية المدعومة، تُدرج مجموعات الأدوات المختارة كسجل assistant/tool منظم. تبقى تعليمة المتابعة النهائية آخر رسالة user.

إذا كانت رسالة tool أصلية مختارة تحمل بالفعل نتيجة أداة، لا تتكرر النتيجة نفسها في كتلة المتابعة المسطحة. تبقى نتائج الأدوات غير المختارة في النص المسطح حتى يستقبلها النموذج.

ما زالت المتابعة مقيّدة بميزانيات جولة المزوّد. يمكن لفشل الأدوات المتكرر، أو كثرة استدعاءات الأدوات، أو كثرة تكرارات المزوّد، أو استنفاد وقت التنفيذ أن توقف الحلقة قبل أي محاولة مزوّد أخرى.

التشخيصات

تشخيصات سجل الأدوات الأصلي هي أحداث جلسة مستمرة تبدأ أسماؤها بـ structured-tool-history-.

هي أعداد/أسباب فقط. يمكن لتشخيص آمن أن يسجل اختيار زوجين أصليين، أو إسقاط orphan واحد، أو غياب echo مطلوب. يجب ألا يسجل وسائط، أو نتائج أدوات، أو استدلالًا خامًا، أو قيم echo، أو حمولات مزوّد، أو محتوى رسائل، أو مسارات، أو hashes، أو أجسام طلبات، أو بصمات مشتقة من المحتوى.

أحداث نشاط الأدوات منفصلة عن تشخيصات إعادة التمرير الأصلية. تصف دورة حياة التنفيذ، لا أهلية إعادة التمرير.

الفحص والاختبارات

ملفات مفيدة:

src/runtime/agent-loop-builder.ts
src/runtime/tool-plan-runner.ts
src/runtime/native-tool-executor.ts
src/runtime/provider-turn-loop.ts
src/tools/tool-call-planner.ts
src/tools/tool-executor.ts
src/contracts/tool.ts
src/prompt/native-history-builder.ts
src/prompt/native-history-selector.ts
src/prompt/semantic-compressor.ts

تشمل الفحوصات المركزة تخطيط الأدوات، وسياسة schemas الأدوات، وأحداث نشاط الأدوات في بيئة التشغيل، وسلوك حلقة جولات المزوّد، وتوصيل حلقة الوكيل، وبناء/اختيار السجل الأصلي، والضغط الدلالي.

pnpm exec vitest run src/tools/tool-call-planner.test.ts
pnpm exec vitest run src/tools/tool-schema.test.ts
pnpm exec vitest run src/runtime/tool-activity-events.test.ts
pnpm exec vitest run src/runtime/provider-turn-loop.test.ts
pnpm exec vitest run src/runtime/agent-loop.test.ts
pnpm exec vitest run src/runtime/agent-loop-builder.test.ts
pnpm exec vitest run src/prompt/native-history-builder.test.ts
pnpm exec vitest run src/prompt/native-history-selector.test.ts
pnpm exec vitest run src/prompt/semantic-compressor.test.ts

عند فحص إعادة التمرير، افحص metadata.kind وmetadata.nativeReplaySafe وmetadata.providerToolCalls[].id وmetadata.tool_call_id في نتيجة الأداة. إذا لم تتطابق هذه القيم، يجب أن تتراجع إعادة التمرير الأصلية بدل ترقيع النص التخاطبي بتخمينات.

ما الذي تغطيه هذه الصفحة​

تركيب بيئة التشغيل​

مراحل التسجيل​

مسار التنفيذ​

التخطيط والسياسة​

فشل التخطيط​

مشغّل خطط الأدوات​

توازي الأدوات الآمنة​

منفّذ الأدوات الأصلي​

المعرفات الثابتة​

حفظ استدعاءات أدوات المزوّد​

السجل الآمن لإعادة التمرير​

المتابعة​

التشخيصات​

الفحص والاختبارات​