AI Agents · درس

قراءة الملفات وكتابتها في سياق الوكيل

open() وpathlib.Path وقراءة ملفات CSV/JSON/TXT من أدوات الوكيل

الدرس 1 من 413 خطوة

قراءة الملفات وكتابتها في سياق الوكيل درس مجاني في AI Agents على CoddyKit. هذا هو الدرس 1 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في AI Agents، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة AI Agents 4 دروس في المجموع.

أهمية إدخال وإخراج الملفات للوكلاء

يحتاج الوكلاء كثيرًا إلى قراءة الإعدادات وتخزين النتائج الوسيطة وكتابة تقارير المخرجات. توفر Python طريقتين أساسيتين للعمل مع الملفات: الدالة المضمنة open() والوحدة الحديثة pathlib. ومن الضروري معرفة كلتيهما.

يجب أن تستخدم كل عملية على ملف مدير سياق، أي عبارة with، لضمان إغلاق الملف حتى عند حدوث خطأ.

with open('config.txt', 'w', encoding='utf-8') as f:
    f.write('model=gpt-4o-mini\nmax_steps=20\n')

with open('config.txt', 'r', encoding='utf-8') as f:
    content = f.read()

from pathlib import Path
content = Path('config.txt').read_text(encoding='utf-8')

print(content)

قراءة الملفات باستخدام open()

تتلقى الدالة open() اسم ملف ووضعًا. لقراءة النص، استخدم الوضع 'r'. يمكنك قراءة الملف بأكمله دفعة واحدة باستخدام .read()، أو قراءته سطرًا سطرًا باستخدام .readline()، أو قراءة جميع الأسطر في قائمة باستخدام .readlines().

حدّد دائمًا encoding='utf-8' لتجنب مفاجآت الترميز الخاصة بالمنصة.

with open('report.txt', 'w', encoding='utf-8') as f:
    f.write('Quarterly agent report body text.')
with open('large_log.txt', 'w', encoding='utf-8') as f:
    f.write('INFO: started\nERROR: timeout\nINFO: done\n')
with open('tasks.txt', 'w', encoding='utf-8') as f:
    f.write('task one\ntask two\n')

with open('report.txt', 'r', encoding='utf-8') as f:
    full_text = f.read()
    print(f'Read {len(full_text)} characters')

with open('large_log.txt', 'r', encoding='utf-8') as f:
    for line in f:
        line = line.rstrip('\n')
        if 'ERROR' in line:
            print('Found error:', line)

with open('tasks.txt', 'r', encoding='utf-8') as f:
    tasks = f.readlines()
    tasks = [t.strip() for t in tasks]
print('Tasks:', tasks)

كتابة الملفات باستخدام open()

استخدم الوضع 'w' للكتابة (ينشئ الملف أو يستبدله)، والوضع 'a' للإلحاق، والوضع 'x' للإنشاء الحصري (يفشل إذا كان الملف موجودًا). يقتطع الوضع 'w' محتوى الملف أولًا، لذا توخَّ الحذر عند وجود بيانات فيه.

# Write a new file (or overwrite)
results = ['Task 1 complete', 'Task 2 complete', 'Task 3 failed']

with open('results.txt', 'w', encoding='utf-8') as f:
    for result in results:
        f.write(result + '\n')

# Append to existing file (add without overwriting)
with open('agent_log.txt', 'a', encoding='utf-8') as f:
    f.write('2026-05-29 14:30: Agent completed batch\n')

# Create exclusively — error if file already exists
try:
    with open('unique_report.txt', 'x', encoding='utf-8') as f:
        f.write('This file is new')
except FileExistsError:
    print('File already exists, skipping')

# --- demo ---
print('results.txt contents:')
with open('results.txt', encoding='utf-8') as f:
    print(f.read())

# Try the exclusive create again now that the file exists
try:
    with open('unique_report.txt', 'x', encoding='utf-8') as f:
        f.write('This file is new')
except FileExistsError:
    print('File already exists, skipping')

pathlib.Path — عمليات الملفات الحديثة

يوفّر pathlib.Path أسلوبًا موجّهًا للكائنات للتعامل مع مسارات الملفات. وهو أكثر قابلية للقراءة من os.path، ويتعامل تلقائيًا مع فواصل المسارات المختلفة بين الأنظمة الأساسية. وبالنسبة إلى عمليات القراءة والكتابة البسيطة، يُعدّ استخدام read_text() وwrite_text() الأسلوب الأنظف.

from pathlib import Path

base = Path('agent_workspace')
base.mkdir(exist_ok=True)
config_file = base / 'config.json'
config_file.write_text('{"model": "gpt-4o-mini"}', encoding='utf-8')

if config_file.exists():
    content = config_file.read_text(encoding='utf-8')
    print('Config:', content)

output = base / 'output' / 'report.txt'
output.parent.mkdir(parents=True, exist_ok=True)
output.write_text('Agent report\nLine 2', encoding='utf-8')

Path('image.png').write_bytes(b'\x89PNG\r\n\x1a\n' + bytes(range(100)))
binary_data = Path('image.png').read_bytes()
print(f'File size: {len(binary_data)} bytes')

قراءة ملفات JSON وكتابتها

يتبادل الوكلاء البيانات المنظّمة غالبًا في صورة ملفات JSON. استخدم json.load() لتحليل ملف JSON، وjson.dump() لكتابة ملف JSON. استخدم دائمًا indent=2 لإخراج يسهل على الإنسان قراءته، وensure_ascii=False للحفاظ على أحرف Unicode.

import json
from pathlib import Path

config_path = Path('agent_config.json')
config_path.write_text(json.dumps({'max_retries': 5, 'model': 'gpt-4o-mini'}), encoding='utf-8')

with open(config_path, 'r', encoding='utf-8') as f:
    config = json.load(f)

print('Max retries:', config.get('max_retries', 3))
print('Model:', config.get('model', 'gpt-4o-mini'))

results = {
    'run_id': 'run-001',
    'status': 'completed',
    'items_processed': 142,
    'errors': []
}

with open('results.json', 'w', encoding='utf-8') as f:
    json.dump(results, f, indent=2, ensure_ascii=False)

print('Results written to results.json')

مديرو السياق — الأسلوب الصحيح

تضمن تعليمة with (مدير السياق) إغلاق الملف عند انتهاء الكتلة، حتى في حال حدوث استثناء أثناء القراءة. ومن دونها، قد تظل الملفات مفتوحة وتتسبب في تسرّب واصفات الملفات، مما يؤدي إلى حدوث أعطال في الأنظمة التي تفرض حدودًا على مقابض الملفات.

with open('data.txt', 'w', encoding='utf-8') as f:
    f.write('sample content')

f = open('data.txt', 'r')
try:
    content = f.read()
finally:
    f.close()

with open('data.txt', 'r', encoding='utf-8') as f:
    content = f.read()

with open('input.txt', 'w', encoding='utf-8') as f:
    f.write('hello\nworld\n')

with open('input.txt', 'r') as infile, \
     open('output.txt', 'w') as outfile:
    for line in infile:
        processed = line.upper()
        outfile.write(processed)

print('Done:', content)

التعامل مع الملفات الثنائية

استخدم الوضع 'rb' لقراءة الملفات الثنائية (الصور وملفات PDF والملفات الصوتية)، والوضع 'wb' لكتابتها. لا تحاول مطلقًا فك ترميز المحتوى الثنائي على أنه نص؛ استخدم read_bytes()/write_bytes() مع pathlib، أو الأوضاع الثنائية مع open().

from pathlib import Path
import base64

image_path = Path('screenshot.png')
image_path.write_bytes(b'\x89PNG\r\n\x1a\n' + bytes(range(50)))

image_bytes = image_path.read_bytes()
print(f'Image size: {len(image_bytes)} bytes')

image_b64 = base64.b64encode(image_bytes).decode('utf-8')
print(f'Base64 length: {len(image_b64)}')

response_bytes = b'...binary content from API...'
output_path = Path('output') / 'generated_image.png'
output_path.parent.mkdir(exist_ok=True)
output_path.write_bytes(response_bytes)
print('Wrote', output_path)

معالجة مشكلات الترميز ومحارف السطر الجديد

تستخدم الأنظمة المختلفة محارف مختلفة للسطر الجديد (\n في Linux/macOS، و\r\n في Windows). حدّد دائمًا encoding='utf-8'، ودع Python يتعامل مع الأسطر باستخدام newline=None (وهو الإعداد الافتراضي). وبالنسبة إلى الملفات التي تحتوي على BOM (علامة ترتيب البايتات)، استخدم encoding='utf-8-sig'.

with open('data.txt', 'w', encoding='utf-8') as f:
    f.write('hello world')
with open('windows_export.csv', 'wb') as f:
    f.write('name,email\n'.encode('utf-8'))
with open('unknown_encoding.txt', 'wb') as f:
    f.write('cafe resume'.encode('latin-1'))

with open('data.txt', 'r', encoding='utf-8') as f:
    text = f.read()

with open('windows_export.csv', 'r', encoding='utf-8-sig') as f:
    content = f.read()

try:
    with open('unknown_encoding.txt', 'r', encoding='utf-8') as f:
        text = f.read()
except UnicodeDecodeError:
    with open('unknown_encoding.txt', 'r',
               encoding='utf-8', errors='replace') as f:
        text = f.read()
    print('Warning: file had encoding errors (replaced with ?)')

print('All reads completed. csv content:', repr(content))

المعالجة الفعّالة سطرًا بسطر

بالنسبة إلى الملفات الكبيرة (مثل ملفات السجل ومجموعات البيانات)، تجنّب تحميل كل المحتوى إلى الذاكرة باستخدام .read(). كرّر مباشرةً على كائن الملف؛ إذ يقرأ Python سطرًا واحدًا في كل مرة، مما يحافظ على ثبات استخدام الذاكرة بغض النظر عن حجم الملف.

from pathlib import Path

def process_large_log(log_path):
    error_count = 0
    processed = 0

    with open(log_path, 'r', encoding='utf-8') as f:
        for line in f:  # reads one line at a time
            line = line.strip()
            if not line:
                continue

            processed += 1
            if '[ERROR]' in line:
                error_count += 1
                # Process error immediately without storing all lines
                handle_error(line)

    print(f'Processed {processed} lines, {error_count} errors')

def handle_error(line):
    print(f'Error found: {line[:80]}')

# --- demo ---
with open('demo_agent.log', 'w', encoding='utf-8') as f:
    f.write('[INFO] agent started\n')
    f.write('[ERROR] timeout calling tool search_web\n')
    f.write('[INFO] retrying\n')
    f.write('[ERROR] tool search_web failed again\n')

process_large_log('demo_agent.log')

إنشاء المجلدات وإدارتها

قبل كتابة الملفات، تأكّد من وجود المجلد الأب. استخدم Path.mkdir(parents=True, exist_ok=True) لإنشاء المجلدات المتداخلة من دون أخطاء إذا كانت موجودة مسبقًا. وهذه خطوة إعداد شائعة في بداية أي وكيل يُنتج ملفات إخراج.

from pathlib import Path
import datetime

# Create output directory structure
today = datetime.date.today().isoformat()  # '2026-05-29'
output_dir = Path('agent_output') / today / 'reports'
output_dir.mkdir(parents=True, exist_ok=True)

print(f'Output directory: {output_dir}')

# Now write files safely
for i in range(3):
    report_path = output_dir / f'report_{i:02d}.json'
    report_path.write_text(
        '{"status": "ok"}',
        encoding='utf-8'
    )

# List all created files
for f in output_dir.iterdir():
    print(f'  {f.name}: {f.stat().st_size} bytes')

أفضل ممارسات مسارات الملفات للوكلاء

ينبغي للوكلاء استخدام المسارات المطلقة أو المسارات النسبية إلى مجلد أساسي محدّد بوضوح. لا تعتمد مطلقًا على مجلد العمل الحالي (./)، لأن الوكلاء غالبًا ما يُشغّلون من مواقع مختلفة. استخدم Path(__file__).parent للحصول على مجلد البرنامج النصي واستخدامه أساسًا.

from pathlib import Path

# Get absolute path relative to THIS script's location
SCRIPT_DIR = Path(__file__).parent
DATA_DIR = SCRIPT_DIR / 'data'
OUTPUT_DIR = SCRIPT_DIR / 'output'

# Always resolve to absolute path before use
config = DATA_DIR / 'config.json'
print('Config path:', config.resolve())

# Check if file exists before reading
if config.exists():
    import json
    with open(config, 'r', encoding='utf-8') as f:
        settings = json.load(f)
else:
    print(f'Config not found at {config.resolve()}')
    settings = {}

# Safe output path
result_path = (OUTPUT_DIR / 'result.json').resolve()
print('Will write to:', result_path)

اختبار سريع: مديرو السياق

اختبر مدى فهمك لأفضل ممارسات الإدخال والإخراج للملفات.

مراجعة عمليات الإدخال والإخراج للملفات

أصبح لديك الآن أساس متين لعمليات الملفات في شيفرة الوكلاء:

  • استخدم open('file', 'r', encoding='utf-8') للقراءة، و'w' للكتابة، و'a' للإلحاق
  • استخدم دائمًا تعليمة with لضمان إغلاق الملفات
  • يوفّر pathlib.Path معالجة نظيفة ومتوافقة مع الأنظمة الأساسية للمسارات، باستخدام read_text()/write_text()
  • استخدم json.load(f) / json.dump(data, f, indent=2) للبيانات المنظّمة
  • كرّر على الملفات سطرًا بسطر عند التعامل مع الملفات الكبيرة لتقليل استخدام الذاكرة
  • استخدم Path(__file__).parent مجلدًا أساسيًا لك — ولا تعتمد مطلقًا على cwd
البدء مجانًا

تعلم AI Agents مع معلم ذكاء اصطناعي — مجانًا

اكتب وقم بتشغيل أكوادك الفعلية في المتصفح، واحصل على مساعدة فورية من معلم ذكاء اصطناعي متاح 24/7، واستمر من حيث توقفت على الويب أو في التطبيق.

الدورات
60
الدروس
239

الأسئلة الشائعة

هل درس «قراءة الملفات وكتابتها في سياق الوكيل» مجاني؟

نعم — نص درس «قراءة الملفات وكتابتها في سياق الوكيل» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة AI Agents، انتقل إلى CoddyKit PRO. تتضمن دورة AI Agents 4 دروس في المجموع.

ماذا ستتعلم في «قراءة الملفات وكتابتها في سياق الوكيل»؟

open() وpathlib.Path وقراءة ملفات CSV/JSON/TXT من أدوات الوكيل تتمرن على AI Agents مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ AI Agents؟

لا تُشترط خبرة سابقة. AI Agents على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 1 من أصل 4.

كم من الوقت يستغرق درس «قراءة الملفات وكتابتها في سياق الوكيل»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس AI Agents هذا؟

نعم. كل درس في AI Agents يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

  1. قراءة الملفات وكتابتها في سياق الوكيل
  2. اجتياز المجلدات واكتشاف الملفات
  3. التعامل مع تنسيقات الملفات: CSV وJSON وTXT
  4. عمليات الملفات الآمنة مع معالجة الأخطاء
← العودة إلى AI Agents