الأدوات

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

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

ما هي الأدوات

الأداة هي وظيفة يمكن للوكيل استدعاؤها. الأدوات تقرأ الملفات، و تكتب الملفات، و تبحث في الويب، و تنفذ التعليمات البرمجية، و تدير الذاكرة، و تجدول مهام 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 مهام Tasks دائمة لأعمال الفحص أو البحث أو البرمجة المستقلة. يبدأ التفضيل الافتراضي auto التنفيذ في عملية EstaCoda التفاعلية الحالية، ويحفظ التقدم بحيث تستطيع بوابة مؤهلة المتابعة عند خروج العملية. استخدم "executionPreference": "background" لإرسال العمل إلى البوابة منذ البداية.

مهمة واحدة:

{
  "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." }
  ]
}

تتحول الدفعة إلى Task دائمة واحدة تحتوي على Step مستقلة لكل عنصر. يفرض المجدول حدود التوازي والمهلة وإعادة المحاولة والإلغاء والاستخدام والموافقات والنتائج. تتضمن نتيجة الأداة معرف Task وحالة دورة الحياة وتفضيل التنفيذ والملكية الحالية (foreground أو background أو waiting) وجاهزية المتابعة في الخلفية وعدد Steps وما إذا كان الاستدعاء أنشأ Task جذرية أم Task فرعية مرتبطة. ولا تدّعي المتابعة المستقلة إذا لم يُكتشف مضيف مؤهل.

يمكن إضافة Step تركيب ثابتة وصريحة عندما يجب أن تعيد Task إجابة واحدة مدمجة:

{
  "tasks": [
    { "task": "Research option A." },
    { "task": "Research option B." },
    { "task": "Research option C." }
  ],
  "synthesis": {
    "objective": "Compare the durable worker results and return one recommendation."
  }
}

للبحث المقيّد بالأدلة، امنح كل عامل research.scope مميزة وصرّح بنوع الدليل المطلوب:

{
  "tasks": [
    {
      "task": "Check the current upstream documentation.",
      "allowedTools": ["web.search"],
      "research": {
        "scope": "Current upstream behavior",
        "requireLiveSources": true,
        "requireRepositoryEvidence": false
      }
    },
    {
      "task": "Trace the local implementation and tests.",
      "allowedTools": ["file.read", "file.grep"],
      "research": {
        "scope": "Local implementation",
        "requireLiveSources": false,
        "requireRepositoryEvidence": true
      }
    }
  ]
}

يفشل إنشاء Task إذا كانت الأدوات الفعالة المفوضة لا تستطيع تنفيذ العقد. لا تُقبل Result العامل إلا عندما تكون روابط HTTP(S) ومسارات المستودع النسبية إلى workspace قد ظهرت في نتائج أدوات ناجحة. يؤدي غياب استخدام الأدوات أو الادعاءات المبنية على training knowledge فقط أو المراجع الملفقة إلى مخرج diagnostic فقط بالتصنيف evidence-contract-unsatisfied. لا تستطيع synthesis استخدام ذلك المخرج، وتذكر research scope غير المتاحة بدلًا منه.

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

بعد إنشاء Task جذرية غير نهائية لها Step نتيجة رئيسية، تملك تلك Task الإجابة المطلوبة. تنتهي provider turn الحالية بإقرار حتمي يعرض معرّف Task وحالة التنفيذ؛ ولا يمكنها المتابعة بتركيب بديل بينما لا يزال العاملون قيد التنفيذ. تصل الإجابة الدائمة عبر مسار إكمال CLI أو channel المعتاد. وإذا اكتملت Task من دون إجابة مقبولة، يرسل ذلك المسار إشعار فشل حتميًا بدلًا من نص diagnostic أو إجابة مرتجلة. وتبقى Tasks الفرعية داخل Task المالكة.

صلاحية العمل المفوض أضيق عمدًا من صلاحية Runtime المنشئة. تتقاطع قائمة الأدوات النهائية المرئية للمزوّد مع الأدوات المطلوبة وسياسة المخاطر الافتراضية قبل حفظ Step. تعامل allowedTools وallowedToolsets كمتطلبات: إذا لم تتوفر إحداها، أو كانت مجموعة الأدوات الناتجة فارغة، يفشل إنشاء Task مع diagnostics منظمة ولا يُوضع عامل في الطابور. يحفظ الإنشاء الناجح سجل وصول محدودًا، ويرفض إنشاء العامل وصولًا فارغًا أو أوسع قبل الاتصال بالمزوّد. لا يمكن لـ Steps بدور worker التفويض. ويمكن لـ Steps بدور orchestrator إنشاء Tasks فرعية مرتبطة فقط ما دامت الصلاحية المحفوظة تتضمن عمقًا متبقيًا؛ ولا يجوز أن تتجاوز workspace أو الصلاحية أو الميزانية الخاصة بالطفل حدود Step الأصلية النشطة. تُحجز ميزانيات استدعاءات المزوّد وtokens والتكلفة المقدّرة ذريًا، لذلك تقسم الاستدعاءات المتكررة سقف الأصل الواحد بدل إنشاء ميزانية جديدة. ويُفرض التزامن الفعلي والوقت المنقضي والاستخدام الحقيقي على شجرة Task كاملة.

تجعل معرفات استدعاءات أدوات المزوّد الإنشاء idempotent، ويكون تفضيل التنفيذ جزءًا من التعريف غير القابل للتغيير. تعيد إعادة تشغيل الاستدعاء نفسه Task الموجودة، بينما يفشل تغيير التفضيل أو أي جزء من التعريف تحت الهوية نفسها باتجاه المنع. لا تتوفر delegate_task عندما لا يتوفر تخزين Tasks الدائم المرتبط بالملف الشخصي؛ ولا يوجد fallback داخل الذاكرة.

استخدم task.status مع معرّف Task المُعاد لفحص التقدم المحدود من جلسة مرتبطة. يعرض أعداد Steps والعمل النشط واكتمال الاستخدام ومقابض النتائج من دون كشف المسارات المحلية أو المطالبات أو مدخلات الأدوات أو بيانات الاعتماد أو أجسام النتائج الكاملة.

لا تُنشأ جلسات العامل إلا بعد أن يحجز المجدول Step. تبقى معزولة عن prompt packing للأصل، وrecall، وsession_search، والذاكرة canonical. يُحفظ modelOverride على Step ويُتحقق منه عبر مسار المزوّد وبيانات الاعتماد المضبوطين عند إنشاء العامل.

فحص 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 للقراءة فقط​

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

توفر الأداة​

أوضاع الفشل​

الفحص​

مرتبطات​