مرجع الأدوات

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

ما هي الأداة

للأداة:

اسم (مثل file.read، web.search)
مخطط إدخال (JSON Schema متوافق مع OpenAI)
فئة مخاطر (safe، caution، read-only-network، external-side-effect)
مجموعة من toolsets (مثل core، web، browser)
دالة توفر (availability predicate)

يسجّل التشغيل الأدوات على مراحل:

pre-skill visibility (مُدمجة، workspace، web، media، voice، vision، cron، memory، config)
post-skill visibility (أدوات مختارة من المهارات)
post-memory provider (أدوات المعرفة)
post-tool executor (التفويض، execute_code)

يُكتشف خوادم MCP عند إنشاء التشغيل ويُسجّلون إلى جانب الأدوات المُدمجة.

فئات الأدوات

الأدوات المُدمجة

أدوات ثابتة تُسجّل دائمًا إذا كان موفرها محمّلًا.

الأداة	المخاطر	الحالة المُعدّلة
`playbook.plan`	`read-only-local`	لا شيء
`trajectory.record`	`read-only-local`	SQLite (أحداث المسار)

أدوات workspace

عمليات نظام الملفات ضمن حدود workspace وتحت قيود الثقة.

الأداة	المخاطر	الحالة المُعدّلة
`file.read`	`read-only-local`	لا شيء
`file.write`	`workspace-write`	ملفات workspace
`file.replace`	`workspace-write`	ملفات workspace
`file.search`	`read-only-local`	لا شيء
`file.glob`	`read-only-local`	لا شيء
`file.grep`	`read-only-local`	لا شيء
`notebook.edit`	`workspace-write`	ملفات notebook داخل workspace

حد الثقة: مسارات workspace تُحل داخل workspace النشط. traversal خارج workspace والمسارات المطلقة خارج workspace تُرفض قبل القراءة أو الكتابة أو تشغيل البحث. file.write و file.replace و notebook.edit أدوات workspace-write وتحتفظ بنفس دلالة ثقة workspace لبقية الكتابات المحلية. file.glob و file.grep أدوات قراءة محلية فقط.

التصليب: يُمسك file.search التعبيرات النمطية غير الصالحة قبل التنفيذ. البحث التكراري يبقى آمنًا من حلقات symlink. file.glob و file.grep يستبعدان ملفات الأسرار المعروفة والمجلدات المولدة. file.grep يحد الصفوف، وطول السطر، وحجم النتيجة الكلي، وحجم الملف المفرد، ووقت التشغيل.

`file.search`

file.search هو أداة بحث النص البسيطة وأداة التوافق. استخدمه لاستعلامات literal أو regex مباشرة عندما لا تحتاج إلى سلوك ripgrep الخاص.

القيود والاسترداد:

لا يوفر أوضاع إخراج file.grep، أو context، أو pagination، أو type filters الخاصة بـ ripgrep.
أقل ملاءمة للمستودعات الكبيرة.
استخدم file.grep لبحث محتوى محدود ومبني على ripgrep.
استخدم file.glob عندما يكون الهدف اكتشاف الملفات لا فحص المحتوى.

`file.glob`

file.glob يعثر على ملفات workspace باستخدام glob pattern ويعيد مسارات نسبية إلى workspace مفصولة بأسطر.

سلوك التنفيذ:

backend الأساسي: rg --files -g <pattern>.
ripgrep يحترم .gitignore.
الملفات المخفية مستبعدة افتراضيًا.
include_hidden: true يمرر --hidden.
إذا لم يتوفر ripgrep، يُستخدم fallback أصغر في Node.
fallback في Node يدعم * و ** و ? ومجموعات {a,b} الأساسية.
fallback في Node أصغر عمدًا من ripgrep؛ لا يعد بسلوك glob المتقدم.

النطاق والترتيب:

path افتراضيًا . ويجب أن يحل إلى مجلد داخل workspace.
النتائج نسبية إلى workspace.
الترتيب الافتراضي lexicographic حسب المسار.
sort: "modified" يفحص الملفات المطابقة ويرتبها حسب mtime من الأحدث.
offset و limit يطبقان بعد الترتيب.

الاستثناءات:

الملفات الشبيهة بالأسرار مستبعدة حتى عند تفعيل الملفات المخفية: .env و .env.* و *.pem و *.key ومفاتيح SSH مثل id_rsa و id_ed25519 و *.p12 و *.pfx.
مجلدات VCS والمجلدات المولدة مستبعدة، ومنها .git و .svn و .hg و .bzr و .jj و .sl و node_modules و dist و build و .next و .turbo.

أنماط الفشل:

pattern مفقود أو فارغ يرجع خطأ إدخال.
path خارج workspace يُرفض.
path الذي لا يشير إلى مجلد يُرفض.
عدم وجود مطابقات نتيجة ناجحة فارغة، وليس فشل تنفيذ.

`file.grep`

file.grep أداة بحث محتوى مبنية على ripgrep. استخدمها للمستودعات الكبيرة، والبحث المحدد بمسار، وأوضاع الإخراج، وcontext، والنتائج المحدودة. تتطلب ripgrep. لا يوجد fallback للبحث في المحتوى عبر Node.

سلوك التنفيذ:

يشغل rg و cwd مضبوط على workspace النشط.
يمرر الهدف المحدد كمسار نسبي إلى workspace.
يمرر النمط عبر -e <pattern>.
glob يتحول إلى --glob.
type يتحول إلى --type.
ignore_case يتحول إلى -i.
multiline يتحول إلى -U --multiline-dotall.
الملفات الثنائية تُتخطى بسلوك ripgrep الافتراضي.
الملفات المخفية مستبعدة افتراضيًا.
include_hidden: true يمرر --hidden.
استثناءات الأسرار والمجلدات المولدة المدمجة تُطبق بعد glob الخاص بالمستخدم حتى لا يستطيع الإدخال إعادة إدخال المسارات المستبعدة.

أوضاع الإخراج:

الوضع	السلوك
`content`	الافتراضي. يتضمن أرقام الأسطر افتراضيًا. context يعمل هنا فقط.
`files`	يستخدم مطابقة الملفات فقط في ripgrep ويعيد المسارات المطابقة.
`count`	يعيد عدد المطابقات لكل ملف.

الحدود:

الإدخال	الافتراضي	السلوك
`limit`	`50`	يحد صفوف النتائج المنطقية.
`offset`	`0`	يتجاوز صفوف النتائج المنطقية قبل العرض.
`max_result_chars`	`100000`	يحد إخراج الأداة المعروض.
`max_line_chars`	`500`	يقتطع سطور النتيجة المفردة.
`max_filesize`	`2M`	يمرر إلى ripgrep كـ `--max-filesize`.

المهلة والإلغاء:

المهلة 30000ms.
عملية rg المولدة تُقتل عند المهلة.
إذا أُلغيت إشارة تنفيذ الأداة، تُقتل عملية rg المولدة.
عند المهلة أو الاقتطاع تُرجع metadata مع تلميح للتضييق عند الحاجة.

أنماط الفشل والاسترداد:

regex غير صالح: يرجع ripgrep خطأ. أصلح النمط.
لا توجد مطابقات: نتيجة no-match ناجحة.
ripgrep مفقود: استخدم file.search كبديل توافق أو ثبّت ripgrep.
إخراج مقتطع: ضيّق pattern أو glob أو path؛ زد offset؛ أو استخدم output_mode: "files".
ملفات أسرار أو ملفات مولدة لا تظهر في النتائج: هذا مقصود. الاستثناءات جزء من نموذج الأمان.

`notebook.edit`

notebook.edit يحرر Jupyter notebooks ضمن نطاق workspace النشط. فضّل مسارات .ipynb النسبية إلى workspace في الأمثلة والإرشاد الموجه للنموذج. يستخدم نموذج الاحتواء نفسه في file.read: أي مسار ينتهي حله خارج workspace، بما في ذلك traversal أو المسارات المطلقة خارج workspace، يُرفض.

التحقق:

يقرأ notebook كـ UTF-8.
يحلل JSON.
يرفض JSON غير الصالح برسالة واضحة.
يتطلب root object، و cells array، و nbformat رقمًا، و nbformat_minor رقمًا.
يرفض المسارات غير .ipynb.

أوضاع التحرير:

الوضع	الإدخال المطلوب	السلوك
`replace`	`cell_id`, `new_source`	يستبدل مصدر الخلية الهدف.
`insert`	`new_source`	يدرج في البداية بدون `cell_id`؛ ويدرج بعد الهدف مع `cell_id`.
`delete`	`cell_id`	يحذف الخلية الهدف.

استهداف الخلايا:

تُفضل cell IDs الحقيقية في notebook.
cell-N مدعوم كفهرس صفري fallback.
cell_id غير الصالح يُرفض في replace و delete.
الخلايا المدرجة تكون cell_type: "code" افتراضيًا ما لم توفر cell_type: "markdown" صراحةً.
خلايا code المدرجة تحتوي الحقول الدنيا الصالحة لخلايا code.
خلايا markdown المدرجة تحتوي الحقول الدنيا الصالحة لخلايا markdown ولا تنشئ outputs للكود.
تُولد cell IDs للخلايا المدرجة عندما يدعم تنسيق notebook ذلك.

سلوك الكتابة:

الحقول غير المعروفة على مستوى notebook والخلية تُحفظ.
استبدال خلية code يعيد execution_count ويجعل outputs مساوية لـ [].
استبدال خلية markdown لا يضيف outputs.
expected_mtime_ms يرفض التحريرات القديمة عندما يختلف mtime الحالي.
الكتابة ذرية: ملف مؤقت ثم rename.
metadata النتيجة مختصرة وتتضمن fileChangePreview.

أنماط الفشل والاسترداد:

JSON غير صالح أو شكل notebook غير صالح: افحص الملف وأصلحه قبل التحرير.
تحرير قديم: أعد قراءة notebook وأعد المحاولة بالـ metadata الحالية.
خلية مفقودة: استخدم cell ID حقيقيًا عند وجوده أو fallback صالحًا مثل cell-N.
تنسيق المصدر: new_source يتحول إلى حقل source عادي في .ipynb مع تمثيل JSON متوافق مع الأسطر الجديدة.

أدوات الويب

عمليات قراءة من الشبكة. لا تُعدّل الحالة البعيدة.

الأداة	المخاطر	الحالة المُعدّلة
`web.search`	`read-only-network`	لا شيء
`web.extract`	`read-only-network`	لا شيء
`web.crawl`	`read-only-network`	لا شيء

التوفر: يتطلب مزود ويب مكوّنًا أو مكتشفًا تلقائيًا ومتاحًا. يمكن لـ web.search استخدام Brave Search مع اعتماد محلول عبر web.brave.apiKeyEnv، أو DDGS عندما تكون قدرة Python المُدارة ddgs مثبتة ومتحققًا منها. يمكن لـ web.extract استخدام fallback الحارس fetch.

أنماط الفشل:

مفتاح المزود المفقود يُرجع خطأً واضحًا مع متغير البيئة المتوقع.
قدرة DDGS المفقودة ترجع تلميح إصلاح لـ estacoda python-env setup ddgs.
حدود المعدل تظهر كأخطاء أدوات مع إرشادات إعادة المحاولة.
أدوات المزود غير المدعومة تُرجع أخطاء عدم توفر.

أدوات المتصفح

أتمتة المتصفح المحلي عبر CDP أو backend متصفح بعيد.

الأداة	المخاطر	الحالة المُعدّلة
`browser.*`	`external-side-effect`	حالة جلسة المتصفح

تشمل أدوات المتصفح المُنفذة browser.status وbrowser.navigate وbrowser.snapshot وbrowser.click وbrowser.type وbrowser.scroll وbrowser.press وbrowser.back وbrowser.get_images وbrowser.console وbrowser.cdp وbrowser.screenshot وbrowser.vision وbrowser.dialog.

التوفر: يتطلب backend متصفح مُهيّأ. يدعم local-cdp اتصال CDP اليدوي والتشغيل التلقائي المُشرف عليه. Browserbase مُنفّذ عبر خلفية المتصفح ويبقى محظورًا حتى تكون browser.cloudSpendApproved === true. تبقى browser-use وFirecrawl browser وCamofox مزودات مؤجلة مسجلة.

اللقطات: تُرجع browser.snapshot إخراجًا مضغوطًا افتراضيًا. الإخراج المضغوط هو مجموعة AX محدودة من العناصر القابلة للتنفيذ مع مراجع مثل @e1؛ وليس ترشيحًا حقيقيًا للعناصر المرئية في منفذ العرض بعد. تمرير full: true يطلب مسار اللقطة الكاملة الأكبر. يوسم الإخراج المعروض اللقطات المضغوطة والكاملة، ويقص النص الضخم، وقد يلخص النتائج الكبيرة عندما يسمح browser.summarizeSnapshots وbrowser.snapshotSummarizeThreshold بذلك.

تنقل Browserbase: يمكن لتنقل HTTP(S) العام إنشاء جلسة Browserbase فقط عندما يكون Browserbase مُعدًا، وتتوفر BROWSERBASE_API_KEY وBROWSERBASE_PROJECT_ID، وتكون موافقة إنفاق السحابة مفعّلة. بيانات الاعتماد والإعداد وحدهما لا ينشئان جلسات. الموافقة المفقودة تُرجع خطأ بوابة الإنفاق ولا ترجع إلى المحلي. إخفاقات Browserbase المؤهلة قد ترجع إلى المحلي فقط عندما تكون browser.cloudFallback === true.

metadata للتوجيه الهجين: حيث تظهر، يمكن لحالة المتصفح أو metadata الأداة أن تتضمن نوع backend الأخير، وحالة browser.hybridRouting، ومزود/سبب fallback، وحالة موافقة/توفر Browserbase. لا تُرجع الأسرار ولا أجسام استجابات Browserbase الخام.

أنماط الفشل:

عدم وجود backend مُهيّأ يُرجع حالة غير متاحة.
فشل اتصال CDP يظهر كخطأ تنفيذ.
يحظر أمان URL العناوين الخاصة/الداخلية ما لم تكن security.allowPrivateUrls مفعّلة صراحةً.
نقاط metadata محظورة دائمًا في المحلي والسحابة والتوجيه الهجين.
تُفرّغ التحويلات غير الآمنة إلى about:blank عندما يمكن ذلك؛ وإلا تُغلق الجلسة غير الآمنة.

أدوات الوسائط

توليد الصور وتحليل الرؤية.

الأداة	المخاطر	الحالة المُعدّلة
`image.generate`	`external-side-effect`	كتابة ملفات الصور
`image.edit`	`external-side-effect`	كتابة ملفات الصور
`vision.analyze`	`safe`	لا شيء

التوفر: image.generate يتطلب مزود توليد صور مُهيّأ ومفتاح API. image.edit يتطلب مزود صور مُهيّأ ونموذجًا محددًا يدعم التعديل وصورًا مصدرية بعناوين HTTPS آمنة أو artifacts تحتوي على عناوين مصدر من المزود. vision.analyze يتطلب مسار نموذج يدعم الرؤية.

أدوات الصوت

تحويل النص إلى كلام والكلام إلى نص.

الأداة	المخاطر	الحالة المُعدّلة
`voice.speak`	`external-side-effect`	قد يشغّل صوتًا أو يكتب ملفات
`voice.transcribe`	`safe`	لا شيء

التوفر: مزودو TTS المستضافون الذين يحتاجون بيانات اعتماد يستخدمون مفاتيح مزود. Edge TTS لا يتطلب مفتاح API، لكنه شبكي ويرسل نص التوليف إلى خدمة Microsoft Edge speech. STT المحلي يستخدم faster-whisper المُدار تحت ~/.estacoda/python-env افتراضياً، أو محرك أمر صريح. جاهزية الصوت تُعرض من خلال أسطح حالة CLI، وليس من خلال isAvailable().

المزودون المُطبّقون:

TTS: OpenAI، ElevenLabs، MiniMax، Gemini، xAI، Edge
STT مستضاف: OpenAI، Groq، xAI
STT محلي: faster-whisper مُدار افتراضياً، وcommand عند ضبط stt.local.engine: "command" صراحةً
مؤجل: مزودا TTS المحليان/offline neutts و kittentts، و Mistral TTS/STT

تنفيذ الكود

الأداة	المخاطر	الحالة المُعدّلة
`execute_code`	`caution`	لا شيء (تنفيذ معزول)
`python`	`caution`	لا شيء (تنفيذ معزول)

السلوك: يشغّل الكود في عملية فرعية مع تصعيد المهلة (SIGTERM ثم SIGKILL). المُخرج مُقتطع قبل الإرجاع. لا يكتب ملفات ما لم يفعل الكود ذلك بنفسه.

أنماط الفشل:

المهلة المُنقضية تُرجع مُخرجًا مُقتطعًا مع علامة مهلة.
رموز الخروج غير الصفرية تظهر كأخطاء أدوات مع stderr مُعقّم.

أدوات Cron

الأداة	المخاطر	الحالة المُعدّلة
`cronjob`	`caution`	مخزن cron للملف التعريفي، سجل التنفيذ

الإجراءات: create، list، update، pause، resume، run، remove.

السلوك: المهام المُنشأة عبر الأداة تستخدم نفس التخزين والتحقق من أوامر cron CLI. يُطبّق فحص أمان الموجهات. تدعم الأداة مهام script في وضع no-agent، وتعليمات skills، وcontextFrom من مهام سابقة، وmodel overrides، وenabled toolsets، وworkdir موثوق ومحصور. المهام المدعومة بـ runtime تعمل داخل runtimes معزولة للـ cron حيث تكون toolsets: cron وmessaging وclarify معطلة إجباريًا. مهام no-agent لا تنشئ runtime trajectories.

راجع المهام المجدولة للنموذج الكامل للأتمتة المجدولة.

أدوات الذاكرة

الأداة	المخاطر	الحالة المُعدّلة
`memory.curate`	`workspace-write`	ملفات ذاكرة الملف التعريفي
`memory.read`	`read-only-local`	لا شيء
`memory.search`	`read-only-local`	لا شيء
`memory.file_compact`	`workspace-write`	إنشاء نسخة احتياطية للضغط
`memory.file_compaction_restore`	`workspace-write`	الاستعادة من النسخة الاحتياطية

سلوك القراءة/البحث: يستخدم memory.read و memory.search استرجاع الذاكرة المحلي اللفظي. يقرأ memory.read ذاكرة محلية محدودة حسب المصدر. يبحث memory.search في الذاكرة المحلية لفظيًا. كلاهما يقبل maxChars، ويُحد داخليًا. يقبل memory.search أيضًا maxResults المحدود.

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

SOUL.md مفهرس كمحمي ومستبعد افتراضيًا. لا تُعاد المدخلات المحمية إلا عندما تكون includeProtected صريحة، وتبقى المقتطفات المحمية محدودة. AGENTS.md ليس ذاكرة ولا يُفهرس أبدًا كذاكرة.

سلوك الكتابة/الضغط: يكتب memory.curate الذاكرة المحلية المنظمة عبر persistence واعٍ بالانحراف. التعديلات الخارجية على القرص تفشل مغلقة افتراضيًا، والتشخيصات لا تكشف محتوى الذاكرة الخام. memory.file_compact يضغط USER.md أو MEMORY.md. يدعم dry-run، ويفحص المُخرج المُنشأ قبل الكتابة، ويُنشئ نسخًا احتياطية. لا يستهدف SOUL.md أو AGENTS.md أبدًا. يستخدم المسار المساعد memory_compaction.

أدوات المهارات

الأداة	المخاطر	الحالة المُعدّلة
`skill.*`	`safe`	لا شيء (فحص فقط)

السلوك: تسرد، تفحص، وتستدعي مهارات. رؤية المهارات تعتمد على الحزم المُفعّلة والملف التعريفي الحالي.

أدوات التفويض

الأداة	المخاطر	الحالة المُعدّلة
`delegate_task`	`shared-state-mutation`	رسم Task مملوك للملف الشخصي، وروابط المنشئ/الأصل، وTask journal
`task.status`	`read-only-local`	حالة محدودة لـ Task مرتبطة بالجلسة النشطة
`terminal.inspect`	`read-only-local`	مخرج أوامر محدود فقط

السلوك: ينشئ رسم Task ثابتًا ودائمًا داخل معاملة واحدة ويعيد مقبضه فورًا. تتحول المهمة الواحدة إلى Step واحدة، وتتحول الدفعة إلى Steps مستقلة تحت Task واحدة. يضيف synthesis.objective الاختياري Step تركيب نهائية تعتمد منذ المراجعة الأولى على جميع العاملين. تمنع هوية استدعاء أداة المزوّد تكرار الإنشاء. لا يبقى تنفيذ متزامن للعامل ولا fallback للتخزين داخل الذاكرة.

تعمل Step التركيب باتجاه المنع: تحصل على مراجع Results المقبولة والمحدودة مع مدخلات task.result.read الدقيقة، ولا يمكنها التفويض، ولا تعمل قبل اكتمال جميع العاملين. يؤدي فشل عامل إلى تخطي التركيب وبقاء Task بالحالة partial. تُعرض المخرجات الآمنة المستردة من Attempt فاشلة باسم المخرجات المستردة وتبقى متاحة للفحص المصرّح به، لكنها لا تحقق الاعتماديات ولا تصبح Result ناجحة أو رئيسية. لا تُسترد تلقائيًا مخرجات رفض الموافقة أو حظر السياسة أو فشل أداة مُغيِّرة. وعند النجاح تُوسم Result الخاصة بالتركيب بأنها النتيجة الرئيسية، بينما تبقى Results الوسيطة المقبولة متاحة عبر مقابض opaque.

عندما تحدد metadata المعادة Task جذرية غير نهائية مع primaryResultStepId، تملك تلك Task الإجابة المطلوبة. توقف EstaCoda provider loop للأصل بعد الإنشاء وتعيد إقرارًا حتميًا يفيد بإنشاء Task ويعرض معرّفها وحالة التنفيذ الحالية. لا يستطيع المزوّد إنشاء إجابة بديلة بينما لا يزال العاملون قيد التنفيذ. تُسلَّم Result الرئيسية المقبولة عبر outbox الحالي للـ CLI أو channel عند اكتمال Task؛ وإذا لم توجد إجابة مقبولة، يُسلَّم إشعار فشل حتمي. تبقى Tasks الفرعية داخل Task المالكة، ويبقى synthesis: false مخصصًا للفحص فقط ويحافظ على سلوك continuation المعتاد.

مدخل مهمة واحدة:

{
  "task": "Inspect the failing test and summarize the likely cause.",
  "context": "Keep the answer short.",
  "allowedTools": ["file.read", "file.grep"],
  "role": "leaf"
}

مدخل دفعة:

{
  "tasks": [
    { "task": "Inspect config tests." },
    { "task": "Inspect runtime tests." },
    { "task": "Inspect gateway tests.", "context": "Focus on interrupt behavior." }
  ]
}

يمكن أن تكون tasks أيضًا سلسلة JSON عندما يكون recoverJsonStringTasks مفعّلًا. الاسترداد صارم: كل مهمة مستردة يجب أن تكون كائنًا يحتوي فقط على task وcontext وallowedToolsets وallowedTools وrole وmodelOverride وresearch؛ يجب أن يكون context سلسلة عند وجوده؛ والحقول غير المعروفة مرفوضة.

تحافظ سياسة Step الافتراضية على أدوات read-only-local وread-only-network من قائمة الأدوات النهائية المرئية للمزوّد، ثم تطبق الحظر الدقيق وحظر البادئات ومجموعات الأدوات المستبعدة. تمثل allowedTools وallowedToolsets متطلبات صريحة: إذا لم تتوفر قدرة مطلوبة، أو كان التقاطع النهائي فارغًا، فلا تُنشأ Task وتعيد الأداة diagnostics منظمة. تحفظ Steps الناجحة سجل وصول محدودًا، ويُرفض الوصول الفارغ أو الأوسع عند إنشاء العامل وقبل الاتصال بالمزوّد. لا يمكن لـ Steps بدور worker التفويض. ولا تحتفظ Steps بدور orchestrator بأداة delegate_task إلا بوجود صلاحية إنشاء طفل محفوظة وعمق متبقٍ. يجب أن تحافظ Task الفرعية المرتبطة على workspace الأصل وأن تحصل على صلاحية وميزانية أضيق.

يمكن لكل عنصر بحث إضافة عقد research يتضمن scope محدودة والحقلين requireLiveSources وrequireRepositoryEvidence. يجب أن تكون scopes الدفعة مميزة بعد التطبيع. يتطلب البحث من مصادر حية أداة web.search فعالة، ويتطلب دليل المستودع file.read مع واحدة من file.search أو file.grep أو file.glob، وإلا يفشل إنشاء Task. لا تُقبل Result ناجحة إلا إذا طابقت روابط HTTP(S) ومسارات المستودع النسبية إلى workspace ما ظهر في نتائج أدوات ناجحة. يفشل الدليل التدريبي فقط أو الملفق بالتصنيف evidence-contract-unsatisfied؛ ويبقى النص الآمن diagnostic فقط ولا يدخل إلى synthesis. تحتفظ مراجع synthesis المقبولة بـ scope الخاصة بها، وتبقى scopes غير المتاحة صريحة في تغطية النتائج الجزئية.

يمتلك مجدول Tasks التوازي وإعادة المحاولة والإلغاء والموافقات والاستخدام والنتائج والتعافي بعد إعادة التشغيل والتسوية. لا تُنشأ جلسات العامل ولا يُطبق modelOverride إلا بعد حجز Step. نتيجة الإنشاء المعادة هي مقبض محدود، وليست الإجابة النهائية للعامل.

يعرض صف المشغّل الناجح الفوري تم إنشاء المهمة لأن delegate_task تعود بعد القبول الدائم. وتبقى ملخصات تسوية العاملين المرصودة معبّرة عن نتائجها الفعلية. بالنسبة إلى Step النتيجة الرئيسية، يعرض task.status أيضًا الطوابع الزمنية الاختيارية لاكتمال المزوّد، والتقاط النتيجة، وتسجيل النتيجة، وتسوية Attempt، وإنهاء Task، وبدء التسليم، والتسليم إلى الأصل. ولا يكشف مسارات workspace أو المطالبات أو مدخلات الأدوات أو بيانات الاعتماد أو أجسام النتائج الكاملة أو الرسائل الخام أو رسائل الفشل الخام. تعيد المعرّفات المفقودة وغير المصرح بها الخطأ نفسه.

terminal.inspect: فحص terminal محلي للقراءة فقط. الإدخال هو { "argv": ["git", "status", "--short"] }. تعمل دون shell وتسمح فقط بـ pwd، وls، وcat، وhead، وtail، وwc، وstat، وfile، وgit status، وgit diff، وgit log، وgit branch، وgit remote، وgit ls-files، وgit grep. git show غير مسموح. ترفض الأداة shell wrappers، وpipes، وredirection، وchaining، وcommand substitution، وenvironment assignment، وpackage scripts، وinterpreters، وarbitrary binaries، والأوامر المعدّلة للحالة، وglob arguments غير المدعومة، والخروج من workspace. المخرج محدود ومنقّح.

أدوات الإعداد

الأداة	المخاطر	الحالة المُعدّلة
`config.compression.status`	`safe`	لا شيء

السلوك: يُظهر إعدادات الضغط المُسوّاة، وحالة المسار المساعد، وأحدث حالة ضغط جلسة. لا يُعدّل الإعدادات ولا يُفصح عن بيانات الاعتماد.

أداة بحث الجلسات

الأداة	المخاطر	الحالة المُعدّلة
`session_search`	`read-only-local`	لا شيء

السلوك: تصفح/بحث/تمرير حتمي في الجلسات التاريخية الخام. تستخدم قاعدة الجلسات المحلية عبر SessionSearchService؛ وهي منفصلة عن SessionRecallService، ولا تستخدم تلخيصًا عبر auxiliary/model، ولا تجعل محتوى الجلسات التاريخية مصدر سلطة.

الأوضاع:

الوضع	المدخلات
`browse`	`limit`, `sort`
`search`	`query`, `limit`, `sort`, `role_filter`
`scroll`	`session_id`, `around_message_id`, `window`

المخرج محدود، ومُنقّح من الأسرار، وموسوم بالمصدر، ومعلّم كسياق مرجعي تاريخي غير موثوق. تعليمات الدور الحالي وسياسة التشغيل الحالية أعلى سلطة من محتوى الجلسات التاريخية. يُطبق ترشيح profile/workspace عندما يكون متاحًا، ويُستخدم استبعاد الجلسة النشطة/الحالية عندما يكون مضبوطًا أو متاحًا.

الحدود داخلية باستثناء مقابض عدد النتائج/الرسائل. الوضعان browse و search افتراضيًا يعيدان 10 نتائج ويُحدان عند 20. الوضع scroll افتراضيًا يستخدم نافذة 5 رسائل ويُحد عند 20. يجب ألا يكشف المخطط maxChars؛ مقتطفات الرسائل، ومعاينات الجلسات، وحجم مخرج الأداة الكلي محدودة داخليًا بواسطة الخدمة وحجم نتيجة الأداة المسجل الثابت.

أنماط الفشل: قاعدة الجلسات المفقودة، أو الجلسات المفقودة، أو الرسائل المفقودة تعيد diagnostics منظمة. الرسائل الكبيرة تُقتطف قبل الإرجاع.

أدوات المعرفة

الأداة	المخاطر	الحالة المُعدّلة
`knowledge.*`	`safe`	SQLite (رسم المعرفة)

التوفر: يتطلب workspace root وتهيئة post-memory provider.

أدوات العملية

الأداة	المخاطر	الحالة المُعدّلة
`process`	`caution`	عمليات النظام

السلوك: تسرد، تستطلع، تسجل، تنتظر، تقتل، وترسل إدخالًا إلى العمليات الخلفية. مُقيّدة بصلاحيات عملية المضيف.

فئات المخاطر

الفئة	المعنى	سلوك الموافقة
`safe`	قراءة فقط، محلي، بدون تأثيرات جانبية	لا يتطلب موافقة
`caution`	قد يُعدّل الحالة المحلية أو يشغّل كودًا	يطلب في الوضع normal؛ يُوافق تلقائيًا في الوضع open ما لم يُفعّل حظر صلب
`read-only-network`	يقرأ من الشبكة	يطلب في الوضع normal؛ يُوافق تلقائيًا في الوضع open ما لم يُفعّل حظر صلب
`external-side-effect`	يُعدّل أنظمة خارجية أو يُكلف مالًا	يطلب دائمًا ما لم تُوافق مسبقًا صراحةً

الحواجز الأمنية الصلبة تتجاوز جميع الأوضاع. الحظر الصلب يرفض استدعاء الأداة بغض النظر عن وضع YOLO أو الموافقات المستمرة.

حدود التوفر

قد تكون الأداة مسجلة لكن غير متاحة. يتحقق التشغيل من isAvailable() قبل عرض الأداة للنموذج.

جاهزية المزود

الأدوات التي تعتمد على مسار مزود تتطلب أن يكون المسار مُهيّأً. جاهزية بيانات الاعتماد تعتمد على المزود.

web.search يتطلب مزود بحث متاحًا: Brave يحتاج مرجع اعتماد بيئي، بينما DDGS يحتاج قدرة Python المُدارة ddgs.
image.generate يتطلب مفتاح مزود توليد صور.
voice.speak يتطلب TTS مُعدًا؛ Edge لا يحتاج مفتاح API، بينما المزودون ذوو بيانات الاعتماد يحتاجون مفتاح المزود.
voice.transcribe يتطلب مزود STT، أو faster-whisper محلياً مُداراً، أو أمراً محلياً صريحاً.

ثقة workspace

بعض الأدوات تتطلب ثقة workspace:

file.write و file.replace مُقيّدتان بالثقة في الوضع strict.
ثقة workspace خاصة بالملف التعريفي ومُخزّنة في ~/.estacoda/profiles/<id>/trust.json.

وضع الأمان

وضع الأمان النشط (strict، normal، open) يُغيّر أي الأدوات تطلب، وأيها يُوافق تلقائيًا، وأيها مُحظور تمامًا.

backend مُهيّأ للمتصفح

أدوات المتصفح تتطلب backend مُهيّأ. بدونه، تكون مسجلة لكن غير متاحة.

خوادم MCP

يُكتشف أدوات MCP عند التشغيل. إذا كان خادم MCP مُهيّأً لكن غير قابل للوصول، تكون أدواته مسجلة ومُعلّمة غير متاحة. أوامر CLI الفردية ترى إعدادات MCP الحالية تلقائيًا. الجلسات التفاعلية تحتاج إلى /reload-mcp للتحديث بعد تغييرات الإعدادات.

أدوات مسجلة لكن غير مُطبّقة

بعض المزودين معروفون في الكتالوج لكن غير قابلين للتشغيل:

anthropic، minimax، nous موجودون في البيانات الوصفية لكن غير قابلين للتنفيذ في الإصدار الحالي.
المزودون المخصصون غير المعروفون يُعاملون كمتوافقين مع OpenAI لكنهم يتطلبون baseUrl صريحًا.

أخطاء شائعة

أداة غير متاحة

الأداة مسجلة لكن isAvailable() أرجع false. الأسباب: مفتاح مزود مطلوب مفقود، ثقة workspace مفقودة، backend غير مُهيّأ، نقطة نهاية غير قابلة للوصول، أو خادم MCP غير قابل للوصول.

الاسترداد: تحقق من estacoda doctor، estacoda settings provider، أو estacoda mcp status.

موافقة مطلوبة

استدعاء الأداة وصل إلى بوابة موافقة. يجب على المستخدم الرد بـ once، session، always، أو deny.

الاسترداد: منح الموافقة، أو التبديل إلى وضع أمان أقل تقييدًا، أو إضافة موافقة مستمرة لنمط الإجراء المطابق.

مرفوض بحظر أمان صلب

استدعاء الأداة طابق قاعدة أمان صلبة وتم رفضه بغض النظر عن الوضع أو الموافقات.

الاسترداد: الحواجز الصلبة مقصودة. الإجراء غير آمن. أعد صياغة الطلب أو نفذ العملية يدويًا.

مفتاح مزود مفقود

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

الاسترداد: عيّن متغير البيئة المتوقع أو شغّل estacoda setup / estacoda model setup للمزود.

أداة مزود غير مدعومة

معرف المزود معروف في الكتالوج لكن ليس لديه تنفيذ حي.

الاسترداد: استخدم مزودًا مُثبتًا حيًا. راجع مرجع المزود لملصقات النضج.

تدفق تنفيذ الأداة

يطلب المزود استدعاء أداة.
ToolCallPlanner يحوّل استدعاء المزود إلى ToolCallPlan.
ToolExecutor يشغّل الأداة تحت SecurityPolicy النشط.
النتيجة مُعبّأة ومُرجعة إلى المزود.
النتائج المُخزّنة مُقتطعة إلى maxResultSizeChars.

صفحات ذات صلة

أوامر CLI — أوامر تفحص وتُهيّئ الأدوات
أوامر الشرطة المائلة — /tools و /reload-mcp داخل الجلسة
دليل المستخدم: الأدوات — مفاهيم الأدوات وسير العمل
مرجع المزود — نضج المزود وطريقة الإعداد

ما هي الأداة​

فئات الأدوات​

الأدوات المُدمجة​

أدوات workspace​

file.search​

file.glob​

file.grep​

notebook.edit​

أدوات الويب​

أدوات المتصفح​

أدوات الوسائط​

أدوات الصوت​

تنفيذ الكود​

أدوات Cron​

أدوات الذاكرة​

أدوات المهارات​

أدوات التفويض​

أدوات الإعداد​

أداة بحث الجلسات​

أدوات المعرفة​

أدوات العملية​

فئات المخاطر​

حدود التوفر​

جاهزية المزود​

ثقة workspace​

وضع الأمان​

backend مُهيّأ للمتصفح​

خوادم MCP​

أدوات مسجلة لكن غير مُطبّقة​

أخطاء شائعة​

أداة غير متاحة​

موافقة مطلوبة​

مرفوض بحظر أمان صلب​

مفتاح مزود مفقود​

أداة مزود غير مدعومة​

تدفق تنفيذ الأداة​

صفحات ذات صلة​

ما هي الأداة

فئات الأدوات

الأدوات المُدمجة

أدوات workspace

`file.search`

`file.glob`

`file.grep`

`notebook.edit`

أدوات الويب

أدوات المتصفح

أدوات الوسائط

أدوات الصوت

تنفيذ الكود

أدوات Cron

أدوات الذاكرة

أدوات المهارات

أدوات التفويض

أدوات الإعداد

أداة بحث الجلسات

أدوات المعرفة

أدوات العملية

فئات المخاطر

حدود التوفر

جاهزية المزود

ثقة workspace

وضع الأمان

backend مُهيّأ للمتصفح

خوادم MCP

أدوات مسجلة لكن غير مُطبّقة

أخطاء شائعة

أداة غير متاحة

موافقة مطلوبة

مرفوض بحظر أمان صلب

مفتاح مزود مفقود

أداة مزود غير مدعومة

تدفق تنفيذ الأداة

صفحات ذات صلة