مرجع الأدوات

يُوسّع 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`	جلسات الأطفال، أحداث التفويض، تشخيصات اختيارية، وذاكرة نتائج اختيارية
`terminal.inspect`	`read-only-local`	مخرج أوامر محدود فقط

السلوك: يُنشئ حلقات وكيل طفل فعلية لمهام فرعية محدودة. جلسات الأطفال معزولة افتراضيًا عن prompt packing للأب، وrecall، وsession_search، والذاكرة. يتلقى الأب نتيجة منظمة تتضمن معرف جلسة الطفل، والحالة، والسبب، والإجابة النهائية، وتشخيصات حدود الأدوات، والدور/العمق، وبيانات timeout أو cancelled، وتحذيرات stale-file، واستخدام رموز المزود عندما يكون متاحًا.

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

{
  "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؛ يجب أن يكون context سلسلة عند وجوده؛ والحقول غير المعروفة مرفوضة.

قدرة الطفل الافتراضية تُحدد بفئة المخاطر لا بأسماء toolset واسعة. بعد التقاطع مع الأدوات المرئية للأب، يحصل الأطفال فقط على أدوات read-only-local وread-only-network، ثم تُزال الأسماء المحظورة، والبادئات المحظورة، ومجموعات الأدوات المستبعدة. مجموعات browser وmedia وmcp مستبعدة افتراضيًا. أسطح الذاكرة/بحث الجلسات، وتعديل المهارات، وتعديل الإعداد، وتعديل cron، وتعديل الثقة، والوصول إلى بيانات الاعتماد، والتحكم بالعمليات، وكتابة مساحة العمل، وتنفيذ shell العام غير متاحة افتراضيًا. terminal.run مستبعد؛ terminal.inspect مشحونة وقد تظهر للأطفال فقط عبر سياسة قراءة فقط ومرئية للأب.

أطفال leaf لا يفوضون أكثر. أطفال orchestrator يرون delegate_task فقط تحت maxSpawnDepth؛ الطلبات التي تتجاوز العمق تفشل قبل إنشاء جلسة طفل.

سياسة موافقات الطفل غير تفاعلية وتفشل مغلقة: تُقيّم hardline denies أولًا، وأي شيء كان سيطلب موافقة أو يعتمد على منح موافقة الأب يُرفض داخل بيئة الطفل.

تنفيذ الدُفعات محدود بـ maxBatchTasks وmaxConcurrentChildren. النتائج تحفظ ترتيب الإدخال. حالات الأطفال timeout وcancelled محفوظة في metadata حتى عندما تكون حالة الدفعة الإجمالية failed. أوصاف مخططات المزود تعرض حدود التفويض النشطة، بما فيها عمق الإنشاء وحدود الدفعة. maxDelegateCallsPerTurn يحد عدة استدعاءات delegate_task منفصلة في دور مزود واحد.

تشخيصات timeout محلية للملف التعريفي، ومحدودة، ومنقّحة من الأسرار. هي مفعّلة افتراضيًا، لكن معاينات prompt الكاملة معطّلة ما لم تُضبط صراحة.

ينسخ استخدام رموز المزود من metadata التنفيذ المنظمة. دفعات التفويض تجمع حقول token الرقمية وتعلّم الاستخدام غير المتاح صراحة. محاسبة USD دائمة أو تقديرية غير مشحونة.

modelOverride يدعم اختيار نموذج طفل على المزود نفسه ومسارات طفل مراجعة عبر مزود آخر. التجاوزات عبر مزود آخر تحفظ إعداد المزود الهدف، وتستخدم بيانات اعتماد apiKeyEnv الموجودة، وتحترم authMethod: "none"، وترفض enableNetwork: false قبل تنفيذ الطفل، وتعطل fallbacks لذلك الطفل. metadata محدودة ومنقّحة.

ذاكرة النتائج معطلة افتراضيًا. عند تفعيلها، يسجل التفويض معاينة محدودة للمهمة وملخص حالة/سبب حتمي فقط، وليس raw child output، أو prompts، أو transcripts، أو tool arguments، أو محتوى ملفات، أو diagnostic payloads.

تحذيرات stale-file هي metadata استشارية. تُلتقط قراءات ملفات الأب قبل التفويض؛ كتابات/استبدالات/حذف الطفل المتعقبة لتلك المسارات تنشئ تحذيرات دون تغيير حالة التفويض. كتابات shell/process لا تُكتشف ما لم تمثلها file-state tracker.

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

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

أخطاء شائعة

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

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

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

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

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

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

صفحات ذات صلة