تفاصيل مشروع Trae Agent

نظرة عامة على المشروع

Trae Agent هو وكيل ذكي مفتوح المصدر من ByteDance، يعتمد على نماذج اللغة الكبيرة (LLM)، ومصمم خصيصًا لمهام هندسة البرمجيات العامة. يوفر هذا المشروع واجهة سطر أوامر قوية قادرة على فهم تعليمات اللغة الطبيعية وتنفيذ مهام سير عمل هندسة البرمجيات المعقدة.

عنوان GitHub: https://github.com/bytedance/trae-agent

الميزات الأساسية

🌊 Lakeview

• يوفر وظيفة تلخيص واضحة وموجزة لخطوات الوكيل.
• يساعد المستخدمين على فهم عملية تنفيذ الوكيل بسرعة.

🤖 دعم نماذج لغة كبيرة متعددة (Multi-LLM Support)

• يدعم واجهة برمجة تطبيقات OpenAI الرسمية.
• يدعم واجهة برمجة تطبيقات Anthropic الرسمية.
• آلية اختيار نموذج مرنة.

🛠️ نظام بيئي غني بالأدوات

• وظائف تحرير الملفات.
• تنفيذ أوامر Bash.
• التفكير المتسلسل (Sequential Thinking).
• المزيد من الأدوات القابلة للتوسيع.

🎯 وضع التفاعل (Interactive Mode)

• واجهة محادثة تدعم التطوير التكراري.
• تفاعل في الوقت الفعلي لتحسين تجربة التطوير.

📊 تسجيل المسار (Trajectory Recording)

• يسجل جميع عمليات الوكيل بالتفصيل.
• يدعم التصحيح والتحليل.
• يولد تقارير التنفيذ تلقائيًا.

⚙️ إعدادات مرنة (Flexible Configuration)

• نظام إعدادات قائم على JSON.
• يدعم إعدادات متغيرات البيئة.
• أولويات إعدادات متعددة المستويات.

🚀 سهولة التثبيت

• عملية تثبيت بسيطة تعتمد على pip.
• يوصى باستخدام UV لإعداد المشروع.

دليل التثبيت

طريقة التثبيت الموصى بها (باستخدام UV)

git clone https://github.com/bytedance/trae-agent.git
cd trae-agent
uv sync

إعداد متغيرات البيئة

# مفتاح API الخاص بـ OpenAI
export OPENAI_API_KEY="your-openai-api-key"

# مفتاح API الخاص بـ Anthropic
export ANTHROPIC_API_KEY="your-anthropic-api-key"

طريقة الاستخدام

تنفيذ المهام الأساسية

# مهمة بسيطة
trae-cli run "Create a hello world Python script"

# تحديد المزود والنموذج
trae-cli run "Fix the bug in main.py" --provider anthropic --model claude-sonnet-4-20250514

# تحديد دليل العمل
trae-cli run "Add unit tests for the utils module" --working-dir /path/to/project

# حفظ ملف المسار للتصحيح
trae-cli run "Refactor the database module" --trajectory-file debug_session.json

# فرض إنشاء تصحيح (patch)
trae-cli run "Update the API endpoints" --must-patch

وضع التفاعل

# بدء جلسة تفاعلية
trae-cli interactive

# استخدام إعدادات مخصصة
trae-cli interactive --provider openai --model gpt-4o --max-steps 30

أوامر وضع التفاعل

• أدخل وصف المهمة لتنفيذها
• status - عرض معلومات الوكيل
• help - عرض الأوامر المتاحة
• clear - مسح الشاشة
• exit أو quit - إنهاء الجلسة

إدارة الإعدادات

# عرض الإعدادات الحالية
trae-cli show-config

# استخدام ملف إعدادات مخصص
trae-cli show-config --config-file my_config.json

ملف الإعدادات

يستخدم Trae Agent ملف إعدادات JSON (trae_config.json) للإعدادات:

{
  "default_provider": "anthropic",
  "max_steps": 20,
  "model_providers": {
    "openai": {
      "api_key": "your_openai_api_key",
      "model": "gpt-4o",
      "max_tokens": 128000,
      "temperature": 0.5,
      "top_p": 1
    },
    "anthropic": {
      "api_key": "your_anthropic_api_key",
      "model": "claude-sonnet-4-20250514",
      "max_tokens": 4096,
      "temperature": 0.5,
      "top_p": 1,
      "top_k": 0
    }
  }
}

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

1. وسائط سطر الأوامر (الأولوية القصوى)
2. قيم ملف الإعدادات
3. متغيرات البيئة
4. القيم الافتراضية (الأولوية الأدنى)

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

str_replace_based_edit_tool - أداة عمليات الملفات

• view - عرض محتوى الملف أو قائمة الدليل
• create - إنشاء ملف جديد
• str_replace - استبدال النص في الملف
• insert - إدراج نص في سطر محدد

bash - تنفيذ أوامر Shell

• تنفيذ الأوامر والسكريبتات
• معالجة الحالة المستمرة
• التعامل مع العمليات طويلة الأمد
• التقاط المخرجات والأخطاء

sequential_thinking - حل المشكلات المنظم

• تقسيم المشكلات المعقدة
• التفكير التكراري ووظائف التصحيح
• توليد الفرضيات والتحقق منها

task_done - إشارة إنجاز المهمة

• وضع علامة على إكمال المهمة بنجاح
• توفير النتائج النهائية والملخص

تسجيل المسار

يسجل Trae Agent تلقائيًا مسار التنفيذ المفصل لأغراض التصحيح والتحليل:

# إنشاء ملف المسار تلقائيًا
trae-cli run "Debug the authentication module"
# يتم الحفظ في: trajectory_20250612_220546.json

# ملف مسار مخصص
trae-cli run "Optimize the database queries" --trajectory-file optimization_debug.json

محتوى ملف المسار

• تفاعل LLM: جميع الرسائل والاستجابات واستدعاءات الأدوات.
• خطوات الوكيل: تحولات الحالة ونقاط القرار.
• استخدام الأدوات: الأدوات التي تم استدعاؤها ونتائجها.
• البيانات الوصفية (Metadata): الطوابع الزمنية، استخدام الرموز (tokens)، ومقاييس التنفيذ.

دليل المساهمة

عملية المساهمة

1. انسخ المستودع (Fork repository)
2. أنشئ فرعًا للميزة (git checkout -b feature/amazing-feature)
3. قم بإجراء التغييرات
4. أضف اختبارات للميزات الجديدة
5. قم بتثبيت التغييرات (git commit -m 'Add amazing feature')
6. ادفع إلى الفرع (git push origin feature/amazing-feature)
7. أرسل طلب سحب (Pull Request)

معايير التطوير

• اتبع دليل نمط PEP 8
• أضف اختبارات للميزات الجديدة
• حدث الوثائق حسب الحاجة
• استخدم تلميحات النوع (type hints) بشكل مناسب
• تأكد من اجتياز جميع الاختبارات قبل الإرسال

متطلبات النظام

• Python 3.12+
• مفتاح API الخاص بـ OpenAI (لنماذج OpenAI)
• مفتاح API الخاص بـ Anthropic (لنماذج Anthropic)

استكشاف الأخطاء وإصلاحها

أخطاء الاستيراد (Import Errors)

# حاول تعيين PYTHONPATH
PYTHONPATH=. trae-cli run "your task"

مشاكل مفتاح API

# تحقق مما إذا كانت مفاتيح API مضبوطة
echo $OPENAI_API_KEY
echo $ANTHROPIC_API_KEY

# تحقق من الإعدادات
trae show-config

أخطاء الأذونات

# تأكد من الأذونات المناسبة لعمليات الملفات
chmod +x /path/to/your/project