قراءة الملفات

أداة FileReadTool تقرأ الملفات من نظام الملفات المحلي.

​

نظرة عامة

لا نزال نعمل على تحسين الأدوات، لذا قد يتغير السلوك.

تقرأ أداة FileReadTool ملفًا محليًا وتعيد محتواه كنص. استخدمها لمعالجة الملفات النصية، أو قراءة ملفات التكوين، أو تحميل البيانات للتحليل. تعمل مع أي صيغة نصية، مثل .txt و .csv و .json و .md. تعيد الأداة دائمًا نصًا عاديًا. إذا احتجت بيانات منظمة (مثل JSON)، فقم بتحليلها في الـ Agent أو في التعليمات البرمجية الخاصة بك.

للملفات الكبيرة، يمكن للـ Agent تمرير start_line و line_count لقراءة نطاق من الأسطر فقط. تتوقف الأداة بمجرد الحصول على تلك الأسطر، لذا لا تمسح بقية الملف.

​

التثبيت

uv add 'crewai[tools]'

​

مثال على الاستخدام

Code

from crewai_tools import FileReadTool

# Agent chooses the file path at runtime
tool = FileReadTool()

# OR set a default file the agent can read with no path argument
tool = FileReadTool(file_path='path/to/your/file.txt')

# OR let the agent read any file under a directory
tool = FileReadTool(base_dir='/data')

امنح الأداة لـ Agent. في وقت التشغيل يمرر الـ LLM قيمة file_path، واختياريًا start_line و line_count.

​

المعاملات

يمكن للـ Agent تمرير هذه المعاملات في وقت التشغيل:

• file_path: (اختياري) مسار الملف المراد قراءته. المسارات المطلقة والنسبية صالحة فقط عندما تُحل داخل بيئة الحماية base_dir. يُحل المسار النسبي بالنسبة إلى base_dir عند تعيينه، وإلا بالنسبة إلى مجلد العمل الحالي (بيئة الحماية الافتراضية). احذفه لقراءة الملف الافتراضي المحدد عند الإنشاء. إذا لم يكن هناك افتراضي، تعيد الأداة خطأ يفيد بعدم توفير مسار.
• start_line: (اختياري) أول سطر للقراءة. تبدأ أرقام الأسطر من 1. الافتراضي هو 1.
• line_count: (اختياري) عدد الأسطر المراد قراءتها. إذا حُذف، تقرأ الأداة من start_line حتى نهاية الملف.

يمكنك تعيين هذه المعاملات عند إنشاء الأداة:

• file_path: (اختياري) الملف الافتراضي للقراءة عندما يستدعي الـ Agent الأداة بدون مسار. يُحل المسار النسبي بالنسبة إلى base_dir عند توفير base_dir، وإلا بالنسبة إلى مجلد العمل الحالي.
• base_dir: (اختياري) المجلد الذي يجب أن تبقى داخله مسارات وقت التشغيل. الافتراضي هو مجلد العمل الحالي. تحل الأداة هذا المسار عند إنشائها، لذا لا يؤدي تغيير لاحق لمجلد العمل إلى نقل بيئة الحماية.
• encoding: (اختياري) ترميز النص المستخدم لفك تشفير الملف. الافتراضي هو utf-8. إذا فشل فك التشفير، تعيد الأداة خطأ وتقترح تمرير encoding مختلف.

تعيد حالات الفشل الشائعة (ملف مفقود، رفض الإذن، ترميز خاطئ، أو مسار خارج بيئة الحماية) سلسلة خطأ. ولا تُثير استثناءً.

​

المسارات المسموح بها

عادةً ما يختار الـ LLM مسار الملف في وقت التشغيل، لذا تقتصر عمليات القراءة على بيئة حماية:

• يجب أن تُحل مسارات وقت التشغيل داخل base_dir (الافتراضي: مجلد العمل الحالي). تحل الأداة مقاطع .. والروابط الرمزية قبل فحص المسار، لذا لا يمكنها الخروج من بيئة الحماية.
• مسار file_path الذي تمرره إلى المُنشئ مسموح به دائمًا، حتى لو كان خارج base_dir. قد تفشل القراءة نفسها إذا كان الملف مفقودًا أو مجلدًا أو لا يمكن الوصول إليه. يُثبَّت هذا المسار عند إنشاء الأداة، لذا لا يغيّر تغيير لاحق لمجلد العمل الملف الذي يشير إليه. يمكن للـ Agent قراءته بحذف file_path، أو باستخدام الاسم الظاهر في وصف الأداة. إعلان ملف واحد لا يتيح الوصول إلى ملفات أخرى في نفس المجلد.

للسماح لـ Agent بقراءة ملفات خارج مجلد العمل، عيّن base_dir عند إنشاء الأداة (انظر المثال أعلاه).

كحل أخير، عيّن CREWAI_TOOLS_ALLOW_UNSAFE_PATHS=true لإيقاف فحوصات المسار. ينطبق هذا الإعداد على كل أداة من crewai-tools في العملية، بما في ذلك حماية SSRF على أدوات جلب عناوين URL. فضّل base_dir بدلاً من ذلك.