مرجع نظام الأدوات

file_read

القدرات:

• قراءة محتوى الملف كاملًا أو نطاقات أسطر محددة
• ضروري لفهم الكود قبل إجراء التعديلات
• تعامل فعّال مع الملفات الكبيرة عبر تحديد النطاق

حالات الاستخدام:

• قراءة ملفات التهيئة قبل التعديل
• فهم أنماط التنفيذ الحالية
• مراجعة ملفات الاختبار لفهم التغطية

مثال:

# Read entire file
file_read("src/components/Button.tsx")

# Read specific range for large files
file_read("package-lock.json", start_line=1, max_lines=50)

file_edit

القدرات:

• استبدال نصي دقيق باستخدام تطابق سلاسل نصية مطابق تمامًا
• عمليات استبدال متعددة باستخدام علم multiple
• الحفاظ على هيكل الملف وتنسيقه

حالات الاستخدام:

• تحديث تنفيذ الدوال
• تعديل قيم التهيئة
• إعادة تسمية المتغيرات عبر الملفات

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

file_write

القدرات:

• إنشاء ملفات جديدة من الصفر
• استبدال محتوى الملفات الحالية بالكامل
• التعامل مع أي صيغة نصية

حالات الاستخدام:

• إنشاء مكونات أو وحدات جديدة
• إنشاء ملفات التهيئة
• كتابة ملفات الاختبار

تحذير: يستبدل الملفات الحالية بالكامل. استخدم file_edit للتعديلات الجزئية.

glob

القدرات:

• البحث عن الملفات المطابقة للأنماط: **/*.ts، src/**/*.js
• التصفية حسب مسار المجلد
• استبعاد الأنماط لتضييق النتائج
• التحكم في عدد النتائج

حالات الاستخدام:

• إيجاد جميع المكونات في المشروع
• تحديد موقع ملفات الاختبار
• تحديد ملفات التهيئة عبر المجلدات

أنماط مثال:

**/*.tsx          # All TypeScript React files
src/**/*.test.js  # All test files in src
**/config.*       # All config files anywhere

grep_content

القدرات:

• البحث في محتوى الملفات باستخدام أنماط regex
• عرض أسطر السياق قبل/بعد المطابقات (العلمان -B، -A)
• البحث بدون حساسية لحالة الأحرف
• التصفية حسب نوع الملف باستخدام أنماط glob

حالات الاستخدام:

• إيجاد تعريفات الدوال
• تحديد موقع تنفيذ نقاط نهاية API
• البحث عن رسائل خطأ محددة
• تحديد أنماط الأمان

مثال:

# Find authentication-related code
grep_content("auth.*login", glob="**/*.ts")

# Search with context
grep_content("TODO", glob="src/**", context_before=2, context_after=2)

grep_file

القدرات:

• سرد الملفات التي تحتوي على مطابقات للنمط
• أسرع من grep_content عندما تحتاج فقط إلى مواقع الملفات
• دعم أنماط regex
• تصفية glob لأنواع الملفات

حالات الاستخدام:

• تحديد الملفات التي تحتاج إلى إعادة هيكلة
• إيجاد الملفات التي تستورد وحدات محددة
• تحديد موقع الملفات التي تحتوي على أنماط قديمة

أفضل ممارسة: استخدم grep_file أولًا لتحديد الملفات ذات الصلة، ثم file_read للفحص التفصيلي.

list_dir

القدرات:

• عرض التسلسل الهرمي للمجلدات
• التحكم في العمق باستخدام معامل max_depth
• أنماط الاستبعاد لتصفية المخرجات

حالات الاستخدام:

• فهم هيكل المشروع
• التحقق من تنظيم المجلدات
• إيجاد مجلدات فرعية محددة

bash

القدرات:

• تنفيذ أوامر shell
• الحد الأقصى للمهلة الزمنية: 120 ثانية (دقيقتان، حد صارم)
• تسلسل الأوامر باستخدام && للاعتماديات
• تقديم ملخصات وصفية للوضوح

حالات الاستخدام:

• تشغيل الاختبارات
• بناء المشاريع
• تثبيت التبعيات
• عمليات Git
• عمليات ترحيل قواعد البيانات

مثال:

# Run tests
bash("npm test", timeout=60000, summary="Run Jest test suite")

# Chain dependent commands
bash("npm install && npm run build", timeout=120000)

الأمان: يتم تنفيذ الأوامر بصلاحيات المستخدم. راجع الأوامر في Manual Accept Mode.

spawn_subagent

القدرات:

• تشغيل وكلاء فرعيين متخصصين بسياقات معزولة
• الأنواع: explorer، verifier، code-reviewer
• تفويض المهام المعقدة دون تلويث السياق الرئيسي
• تنفيذ متوازٍ للوكلاء الفرعيين لتحقيق الكفاءة

حالات الاستخدام:

• الوكيل الفرعي الاستكشافي: البحث في قواعد الكود الكبيرة عن الأنماط
• وكيل التحقق الفرعي: التحقق من صحة منطق التنفيذ
• وكيل مراجعة الكود الفرعي: تقييم الأمان والجودة

أفضل ممارسة: فوّض مهام البحث الاستكشافي إلى الوكيل الفرعي الاستكشافي للحفاظ على سياق المحادثة الرئيسية.

todo_update

القدرات:

• إنشاء وإدارة قوائم المهام
• تحديث حالة المهمة (معلّقة، قيد التنفيذ، مكتملة)
• تتبع التقدم عبر عمليات التنفيذ المعقدة

حالات الاستخدام:

• تقسيم الميزات المتعددة الخطوات
• تتبع تقدم إعادة الهيكلة
• إدارة مهام الترحيل

web_search

القدرات:

• الاستعلام في محركات البحث على الإنترنت
• التحكم في عدد النتائج
• التصفية حسب الحداثة (الأيام الأخيرة)

حالات الاستخدام:

• إيجاد الوثائق لـAPIs غير المألوفة
• البحث عن رسائل الخطأ
• التحقق من أفضل الممارسات الحالية

web_fetch

القدرات:

• استرجاع محتوى صفحات الويب
• تحليل المحتوى باستعلامات محددة
• استخراج معلومات منظّمة

حالات الاستخدام:

• قراءة صفحات الوثائق
• تحليل وثائق API
• استخراج أمثلة من الدروس التعليمية

صيغ البيانات

ملفات البناء والحزم

كفاءة file_read

أفضل الممارسات:

• استخدم نطاقات الأسطر للملفات التي تزيد عن 500 سطر لتجنب إثقال السياق
• اقرأ فقط الأقسام ذات الصلة اللازمة للمهمة
• للملفات الكبيرة، استخدم grep_content أولًا لتحديد أرقام الأسطر ذات الصلة

# Good: Read specific section
file_read("large-config.json", start_line=100, max_lines=50)

# Less efficient: Read entire large file
file_read("large-config.json")  # May consume excessive context

دقة file_edit

أفضل الممارسات:

• تأكد من التطابق الدقيق للسلاسل النصية لتجنب فشل التعديلات
• للتغييرات المتشابهة المتعددة، استخدم علم multiple=true
• تحقق من مسارات الملفات قبل التعديل

أمان file_write

أفضل الممارسات:

• تحقق مرتين من المسارات لمنع الاستبدال العرضي
• استخدمها فقط للملفات الجديدة أو إعادة الكتابة الكاملة
• للتعديلات، يُفضّل استخدام file_edit لمزيد من الأمان

تحديد أنماط glob

أفضل الممارسات:

• استخدم أنماطًا محددة لتضييق النطاق: src/**/*.ts بدلًا من **/*
• استبعد المجلدات بأنماط استبعاد: !**/node_modules/**
• حدّد النتائج لتجنب إخراج مفرط

# Good: Specific scope
glob("src/components/**/*.tsx", max_results=50)

# Less efficient: Too broad
glob("**/*")  # Returns thousands of results

استراتيجية grep

سير العمل الموصى به:

1. استخدم grep_file لتحديد الملفات ذات الصلة
2. اقرأ الملفات المحددة باستخدام file_read
3. استخدم grep_content عندما تحتاج إلى السياق المحيط

نصائح الأداء:

• قد تستغرق أنماط regex وقتًا أطول من السلاسل النصية الحرفية
• البحث بدون حساسية لحالة الأحرف أبطأ
• قيّد أسطر السياق (-A، -B) بما هو ضروري فقط

أفضل ممارسات bash

تنفيذ الأوامر بأمان:

• قدّم ملخصات واضحة لوصف الأوامر
• عيّن مهلًا زمنية مناسبة للعمليات الطويلة
• سلسِل الأوامر المرتبطة باستخدام &&
• راجع الأوامر الهدّامة بعناية (rm، drop، truncate)

# Good: Clear summary, reasonable timeout
bash("npm run build", timeout=120000, summary="Build production bundle")

# Good: Chained dependencies
bash("npm install && npm run test", timeout=180000)

اعتبارات الأمان

قواعد الأمان الحرجة:

• يتم تنفيذ الأوامر بصلاحيات المستخدم
• لا تشغّل أبدًا أوامر غير موثوقة
• استخدم Manual Accept Mode للمراجعة في قواعد الكود المشتركة
• تجنب الأوامر التي تعرّض بيانات الاعتماد أو المعلومات الحساسة

كفاءة تفويض الوكلاء الفرعيين

متى تستخدم الوكلاء الفرعيين:

• الوكيل الفرعي الاستكشافي: عمليات البحث في قاعدة الكود، أسئلة الهيكلية (يحافظ على السياق الرئيسي)
• وكيل التحقق الفرعي: فحوصات التحقق السريعة (تحقق معزول)
• وكيل مراجعة الكود الفرعي: مراجعات الأمان والجودة (تحليل تفصيلي)
• الوكيل الفرعي العام: المهام المتعددة الخطوات المعقدة (تنفيذ متوازٍ)

أفضل ممارسة: فوّض مهام البحث والاستكشاف إلى الوكلاء الفرعيين للحفاظ على سياق المحادثة الرئيسية لأعمال التطوير النشطة.

إدارة السياق

الاستخدام الاستراتيجي للأدوات:

• اقرأ الملفات بشكل استراتيجي - فقط ما هو ضروري
• استخدم الوكلاء الفرعيين للبحث في الخلفية
• راقب استهلاك السياق خلال الجلسات الطويلة
• قسّم العمليات المعقدة إلى خطوات باستخدام todo_update

سير العمل الفعّال:

1. التخطيط: استخدم glob/grep لتحديد النطاق
2. القراءة: اقرأ فقط الملفات/الأقسام ذات الصلة
3. التنفيذ: فوّض إلى الوكلاء الفرعيين عند الحاجة
4. التحقق: فحوصات سريعة باستخدام وكيل التحقق الفرعي

حدود حجم الملف

التعامل مع الملفات الكبيرة: يجب قراءة الملفات الكبيرة جدًا (أكثر من 10,000 سطر) على أقسام لتجنب:

• استنفاد نافذة السياق
• أوقات استجابة بطيئة
• مشكلات الذاكرة

الإعدادات الافتراضية لمهلة الأدوات

حدود الأدوات:

• مهلة bash: 120 ثانية (دقيقتان) كحد أقصى
• عمليات الملفات: لا توجد حدود للحجم (تُقرأ الملفات الكبيرة تلقائيًا على دفعات)
• التعامل مع الملفات الكبيرة: الملفات التي تزيد عن 256 كيلوبايت تُعيد أول 256 كيلوبايت من المحتوى فقط
• نتائج البحث: لا توجد حدود لنتائج glob أو grep_content
• الوكلاء الفرعيون المتزامنون: لا توجد حدود للتنفيذ المتوازي

تهيئة المهلة الزمنية:

• عيّن مهلًا زمنية واضحة للعمليات الطويلة
• راقب العمليات المعلّقة
• سيتم إنهاء الأوامر التي تتجاوز مهلة الدقيقتين

العمليات المتزامنة

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

فوائد الأداء:

• تقليل وقت التنفيذ الإجمالي للمهام متعددة الخطوات
• استخدام فعّال للموارد
• تنظيم آلي للمهام
• لا توجد حدود لعدد الوكلاء الفرعيين المتزامنين