> ## Documentation Index
> Fetch the complete documentation index at: https://crewai-cursor-simplify-filereadtool-docs-ac84.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

## نظرة عامة

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

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

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

## التثبيت

```shell theme={null}
uv add 'crewai[tools]'
```

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

```python Code theme={null}
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` بدلاً من ذلك.