الأدوات

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

تشرح هذه الصفحة كيفية تنظيم الأدوات، ومتى تكون متاحة، وماذا يحدث عندما تفشل.

ما هي الأدوات

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

الأدوات ليست قدرات حرة. يتم تقييدها من قبل الإعدادات، وجاهزية المزود، وثقة مساحة العمل، ووضع الأمان.

فئات الأدوات

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

الأدوات المدمجة تأتي مع EstaCoda وتكون مسجلة دائمًا. يعتمد التوفر على الإعدادات وحالة المزود.

الأداة	فئة المخاطر	ملاحظات
`file.read`	`safe`	تقرأ الملفات داخل مساحة العمل
`file.write`	`caution`	تكتب الملفات؛ تخضع للمراقبة في الوضع adaptive/strict
`file.replace`	`caution`	تعدل الملفات؛ تخضع للمراقبة في الوضع adaptive/strict
`file.search`	`safe`	بحث بسيط للتوافق باستخدام نص أو regex
`file.glob`	`read-only-local`	يعثر على ملفات workspace حسب glob pattern
`file.grep`	`read-only-local`	بحث محتوى محدود ومبني على ripgrep
`notebook.edit`	`workspace-write`	يحرر خلايا في دفاتر `.ipynb` داخل workspace
`web.search`	`read-only-network`	بحث ويب عبر المزود المُهيأ
`web.extract`	`read-only-network`	يستخرج المحتوى من عناوين URL
`web.crawl`	`read-only-network`	يزحف إلى صفحات الويب
`browser.*`	`external-side-effect`	يتطلب إعداد متصفح backend
`image.generate` / `image.edit`	`external-side-effect`	يتطلب بيانات اعتماد مزود الصور؛ ويتطلب التعديل نموذجًا محددًا يدعم التعديل
`voice.speak`	`external-side-effect`	يتطلب TTS مُعدًا؛ بيانات الاعتماد تعتمد على المزود
`voice.transcribe`	`safe`	يتطلب مزود STT أو نموذج محلي
`execute_code`	`caution`	ينفذ التعليمات البرمجية في sandbox
`memory.*`	`safe`	تنظيم الذاكرة والضغط
`session_search`	`read-only-local`	تصفح/بحث/تمرير خام في الجلسات التاريخية
`skill.*`	`safe`	عمليات إنشاء/قراءة/تحديث/حذف المهارات
`cronjob`	`caution`	جدولة وإدارة مهام cron

أدوات مدعومة من المزود

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

أدوات MCP

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

استخدام الأداة المختارة من المهارة

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

البحث في ملفات workspace

استخدم أدوات ملفات workspace عندما تكون المهمة عن الكود، التوثيق المحلي، fixtures، notebooks، أو أي ملف تحت workspace النشط. كل المسارات تبقى محصورة داخل workspace. محاولات مثل ../outside أو المسارات المطلقة خارج workspace تُرفض قبل القراءة أو الكتابة أو تشغيل عملية بحث.

هذه الأدوات لا تغير معنى ثقة workspace. file.glob و file.grep أدوات قراءة محلية فقط. notebook.edit أداة workspace-write.

`file.search`

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

ما الذي قد يفشل:

regex غير صالح يُرفض.
البحث الواسع جدًا أقل ملاءمة من file.grep.
ليس مناسبًا لتعديل خلايا notebook أو لاكتشاف الملفات فقط.

الاسترداد: ضيّق الاستعلام أو المسار. في المستودعات الكبيرة استخدم file.grep لبحث المحتوى و file.glob لاكتشاف الملفات.

`file.glob`

file.glob يعثر على الملفات باستخدام glob pattern ويعيد مسارات نسبية إلى workspace. عندما يكون ripgrep متاحًا يستخدم rg --files -g <pattern>. هذا أسرع في المستودعات الكبيرة ويحترم .gitignore. عندما لا يكون ripgrep متاحًا يستخدم EstaCoda fallback أصغر في Node يدعم * و ** و ? ومجموعات {a,b} الأساسية.

السلوك:

الملفات المخفية مستبعدة افتراضيًا.
include_hidden: true يمكنه إدخال الملفات المخفية غير الحساسة.
الملفات الشبيهة بالأسرار تبقى مستبعدة حتى عند تفعيل الملفات المخفية.
مجلدات VCS والمجلدات المولدة مستبعدة.
النتائج ترتب حسب المسار افتراضيًا؛ sort: "modified" يرتب حسب وقت التعديل من الأحدث إلى الأقدم.
limit و offset يطبقان بعد الترتيب.

استثناءات الأسرار تشمل .env و .env.* و *.pem و *.key ومفاتيح SSH مثل id_rsa و id_ed25519 و *.p12 و *.pfx. استثناءات VCS والمولدات تشمل .git و node_modules و dist و build و .next و .turbo ومجلدات مشابهة.

ما الذي قد يفشل: قد لا يطابق النمط أي ملف، أو قد يكون المسار المحدد ملفًا لا مجلدًا، أو قد لا يدعم fallback في Node صيغة glob متقدمة. الاسترداد: تحقق من نطاق المسار، بسّط glob، أو استخدم file.grep إذا كان الهدف الحقيقي هو البحث في المحتوى.

`file.grep`

file.grep يبحث في محتوى الملفات باستخدام ripgrep. استخدمه عندما تحتاج إلى matches مع ترشيح ملفات، أو أوضاع إخراج، أو context، أو pagination، أو حدود صارمة لحجم النتيجة. يستخدم rg مباشرة ولا يملك fallback للبحث في المحتوى عبر Node. إذا كان ripgrep مفقودًا، ترجع الأداة خطأ واضحًا؛ استخدم file.search كبديل أبسط.

السلوك:

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

حدود الإخراج:

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

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

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

سلوك المهلة: يستخدم file.grep مهلة 30000ms. عند المهلة أو الإلغاء، تُقتل عملية ripgrep المولدة وترجع الأداة خطأ منظمًا أو metadata تشير إلى الاقتطاع.

ما الذي قد يفشل: regex غير صالح، إخراج مقتطع، غياب rg، أو استثناءات تخفي ملفات أسرار أو ملفات مولدة عمدًا. الاسترداد: ضيّق pattern أو glob أو path؛ زد offset؛ استخدم output_mode: "files" لفحص مجموعة الملفات؛ أو ارجع إلى file.search عندما لا يتوفر ripgrep.

تحرير notebooks

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

تقرأ الأداة notebook كـ JSON بترميز UTF-8 وتتحقق من الشكل الأدنى:

الجذر object.
cells array.
nbformat رقم.
nbformat_minor رقم.

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

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

البحث عن الخلية يفضل cell ID الحقيقي في notebook. عند الحاجة، cell-N يشير إلى فهرس صفري للخلية. الخلايا المدرجة تكون cell_type: "code" افتراضيًا إلا إذا وفرت cell_type: "markdown" صراحةً. خلايا code المدرجة تحتوي الحقول الدنيا الصالحة لخلايا code؛ خلايا markdown لا تحصل على حقول outputs الخاصة بالكود. عندما يدعم تنسيق notebook معرفات الخلايا، تولد الأداة IDs للخلايا المدرجة.

استبدال خلية code يعيد execution_count ويجعل outputs مساوية لـ []. استبدال خلية markdown لا يضيف outputs. الحقول غير المعروفة على مستوى notebook أو الخلية تُحفظ.

استخدم expected_mtime_ms للحماية من التحرير القديم. إذا تغير notebook منذ ذلك الوقت، ترفض الأداة التعديل. الكتابة الناجحة تستخدم ملفًا مؤقتًا ثم rename، وترجع metadata مختصرة مع fileChangePreview.

ما الذي قد يفشل: JSON غير صالح، شكل notebook غير صالح، expected_mtime_ms قديم، cell_id مفقود، أو مرجع cell-N غير صالح. الاسترداد: اقرأ أو افحص notebook مرة أخرى، استخدم cell ID حقيقيًا عند وجوده، أو أعد المحاولة باستخدام mtime الحالي من metadata.

بحث الجلسات

session_search أداة قراءة فقط للتصفح والبحث والتمرير الحتمي في الجلسات التاريخية. تعيد سياقًا تاريخيًا خامًا كمرجع؛ لا تلخص، ولا تستخدم مزود auxiliary/model، ولا تجعل محتوى الجلسات القديمة مصدر سلطة.

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

المقابض محدودة عمدًا:

الوضع	المقابض
`browse`	`limit`, `sort`
`search`	`query`, `limit`, `sort`, `role_filter`
`scroll`	`session_id`, `around_message_id`, `window`

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

تفويض المهام

delegate_task يسمح لـ EstaCoda ببدء وكلاء أطفال محدودين لمهام فرعية، بينما تبقى الإجابة النهائية مملوكة لدور الأب. استخدمه عندما يمكن تقسيم المهمة إلى عمل فحص أو بحث مستقل.

مهمة واحدة:

{
  "task": "Read the runtime tests and report the risky assumptions.",
  "context": "Focus on behavior, not style.",
  "role": "leaf"
}

مهام دفعة:

{
  "tasks": [
    { "task": "Inspect config defaults." },
    { "task": "Inspect gateway interrupt behavior." },
    { "task": "Inspect delegation timeout behavior." }
  ]
}

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

الوكلاء الأطفال أضيق عمدًا من الأب. افتراضيًا يمكنهم استخدام أدوات قراءة محلية وشبكية مرئية للأب، مثل قراءة/بحث الملفات، وسجلات/قائمة العمليات، وبحث الويب، وterminal.inspect عندما تكون الأداة مرئية للأب. لا يحصلون على أدوات كتابة مساحة العمل، أو الذاكرة/بحث الجلسات، أو تعديل المهارات، أو تعديل الإعدادات، أو تعديل cron، أو تعديل الثقة، أو browser، أو media، أو mcp، أو بيانات الاعتماد، أو التحكم بالعمليات، أو تنفيذ shell عام. terminal.run مستبعد افتراضيًا.

أطفال leaf لا يمكنهم إنشاء أطفال آخرين. أطفال orchestrator يمكنهم التفويض فقط ضمن حد العمق المضبوط. الطلبات التي تتجاوز حد العمق تفشل قبل إنشاء جلسة طفل جديدة.

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

إذا انتهت مهلة الطفل أو أُلغي، فالنتيجة منظمة. تشخيصات timeout تُكتب تحت مسارات تشخيص محلية للملف التعريفي عندما تكون مفعّلة. معاينات prompt معطلة افتراضيًا، والتشخيصات محدودة ومنقّحة من الأسرار. عمل الأطفال الطويل يصدر progress وheartbeat metadata محدودة حتى يبقى دور الأب قابلاً للمراقبة دون كشف raw provider token streams.

سلوك gateway محمي أيضًا: إذا كانت قناة بعيدة مضبوطة لمقاطعة الأدوار النشطة، تُصفّ الرسائل العادية في الطابور بينما يحتوي الدور النشط على عمل أطفال. أوامر التحكم الصريحة مثل /stop ما زالت تلغي الدور النشط وعمل الأطفال النشط.

نتائج التفويض تتضمن metadata منظمة للحالة/السبب، ومعرّفات جلسات الأطفال عند إنشائها، وmetadata الأدوات الفعلية للطفل، وتفاصيل timeout/cancelled، وفهارس الدفعة، وتحذيرات stale-file، واستخدام رموز المزود عندما يكون متاحًا. دفعات المهام تجمع حقول token usage الرقمية وتعلّم الاستخدام غير المتاح صراحة. محاسبة USD دائمة أو تقديرية غير مشحونة.

تجاوزات نموذج الطفل مدعومة عبر modelOverride. التجاوزات على المزود نفسه والمسارات المراجعة عبر مزود آخر تستخدم المزودين المضبوطين فقط ولا تنشئ credential pools. التجاوز عبر مزود آخر يحفظ إعداد المزود الهدف، ويرفض المسارات ذات enableNetwork: false قبل تنفيذ الطفل، ويعطل fallbacks لذلك الطفل.

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

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

موافقات الطفل بوساطة الأب غير مشحونة. يبقى الأطفال غير تفاعليين ويفشلون مغلقًا للإجراءات التي تحتاج موافقة.

فحص Terminal للقراءة فقط

terminal.inspect أداة فحص terminal محدودة للقراءة فقط. تقبل argv arrays، وتعمل دون shell، وليست مشغّل أوامر عامًا.

{ "argv": ["git", "status", "--short"] }

الأوامر المسموحة هي 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، وcommand chaining، وcommand substitution، وenvironment assignment، وpackage scripts، وinterpreters، وarbitrary binaries، والأوامر المعدّلة للحالة، وglob arguments غير المدعومة، والمسارات خارج workspace. المخرج محدود ومنقّح من الأسرار. قد تكون terminal.inspect متاحة للأطفال فقط عبر سياسة الأدوات نفسها: مرئية للأب وقراءة فقط؛ تبقى terminal.run مستبعدة من مخططات الأطفال الافتراضية.

مسار تنفيذ الأداة

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

سياسة الأمان تعمل قبل التنفيذ. الحد الأرضي الصلب يحظر الأوامر الخطرة قبل تشغيل تنفيذ الأداة. الوضع adaptive قد يطلب موافقة. الوضع open يسمح بالإجراءات غير الصلبة مع الحد الأدنى من المراقبة.

توفر الأداة

الأداة متاحة فقط عندما:

تكون مسجلة في سجل الأدوات.
يكون إعدادها المطلوب موجودًا (بيانات اعتماد المزود، متصفح backend، إلخ).
يكون مسار المزود جاهزًا وقابلًا للتشغيل.
لا تحظره ثقة مساحة العمل.
يسمح وضع الأمان بفئة مخاطرها.

/tools داخل جلسة تفاعلية تدرج الأدوات المتاحة حاليًا. /skills تدرج المهارات المرئية ومجموعات الأدوات المطلوبة.

أوضاع الفشل

أداة غير متاحة: الأداة غير مسجلة أو إعدادها مفقود. تحقق من /tools للتوفر. تحقق من بيانات اعتماد المزود المطلوبة، أو قابلية الوصول إلى نقطة النهاية، أو إعداد متصفح backend، أو حالة خادم MCP.

موافقة مطلوبة: فئة مخاطر الأداة أطلقت بوابة موافقة. رد على المطالبة أو استخدم /approvals لفحص المنح المعلقة.

مرفوضة بواسطة حظر الأمان الصلب: الأمر طابق نمط hardline. الأداة لا تنفذ. غيّر الأمر؛ الحظر غير مشروط.

مفتاح مزود مفقود: أداة مدعومة من مزود يحتاج اعتمادًا تتطلب بيانات اعتماد لم يتم تكوينها. شغّل estacoda model setup أو اضبط متغير البيئة المطلوب في .env الخاص بالملف الشخصي. المسارات بلا اعتماد لا تحتاج مفتاحًا.

stub مزود غير مدعوم: المزود يعلن عن استدعاء الأدوات لكن بيئة التشغيل لا تنفذ بعد مخطط الأداة لهذا المزود. استخدم مزودًا مختلفًا أو أداة مدمجة.

خطأ في تنفيذ الأداة: الأداة تعمل لكنها تصادف خطأ (ملف غير موجود، مهلة شبكة، regex غير صالح). يتم إرجاع الخطأ إلى المزود كناتج منظم.

الفحص

# إدراج الأدوات المتاحة في الجلسة
/tools

# إدراج المهارات المرئية ومجموعات الأدوات
/skills

# إعادة تحميل خوادم MCP
/reload-mcp

# تدقيق أمان
/security debug

مرتبطات

الأمان والموافقات — فئات المخاطر وأوضاع الموافقة
المهارات — مجموعات الأدوات المطلوبة للمهارة
CLI — إدراج الأدوات التفاعلية ومطالبات الموافقة
القنوات — توفر الأداة عبر القناة

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

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

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

أدوات مدعومة من المزود​

أدوات MCP​

استخدام الأداة المختارة من المهارة​

البحث في ملفات workspace​

file.search​

file.glob​

file.grep​

تحرير notebooks​

بحث الجلسات​

تفويض المهام​

فحص Terminal للقراءة فقط​

مسار تنفيذ الأداة​

توفر الأداة​

أوضاع الفشل​

الفحص​

مرتبطات​