‏Larapanda: مرورگر بی‌سر Lightpanda برای لاراول

Larapanda یه SDK لاراوله برای کار با Lightpanda، یه مرورگر هدلس (headless browser — مرورگری که بدون رابط گرافیکی اجرا می‌شه و برای اسکرپینگ و تست استفاده می‌شه) که با زبان Zig نوشته شده. این پکیج یه لایه‌ی حرفه‌ای روی Lightpanda می‌ذاره که مدیریت پروفایل، انتخاب runtime، و نتایج تایپ‌سیف رو یه‌جا جمع می‌کنه.

پروفایل‌بندی instance یکی از ویژگی‌های اصلیه. می‌شه چند پروفایل مجزا تعریف کرد — مثلاً یه پروفایل برای کرالر با CLI، یکی برای MCP با Docker — و هر کدوم تنظیمات مستقل خودشون رو داشته باشن:

// config/larapanda.php
'instances' => [
    'default' => [],
    'crawler' => [
        'runtime'     => 'cli',
        'binary_path' => '/absolute/path/to/lightpanda',
    ],
    'mcp' => [
        'runtime' => 'docker',
    ],
],

برای انتخاب runtime، حالت auto اول دنبال باینری CLI می‌گرده و اگه پیدا نکرد، به Docker فال‌بک می‌کنه. البته می‌شه runtime رو صریحاً هم روی cli یا docker پین کرد.

متد fetchRequest() یه شیء FetchResult برمی‌گردونه که نتیجه رو با فرمت انتخاب‌شده تحویل می‌ده — مثل Markdown یا Semantic Tree. اگه اکسسوری رو که با فرمت انتخابی جور نیست صدا بزنی، به‌جای برگردوندن داده‌ی اشتباه، یه exception می‌ده. پشتیبانی از پراکسی هم به‌صورت per-request موجوده.

$result = $client->fetchRequest('https://example.com')
    ->withOptions(
        dump: FetchDumpFormat::Markdown,
        obeyRobots: true,
        waitMs: 2000,
    )
    ->run();

$markdown = $result->asMarkdown();

یکپارچگی با Laravel AI SDK اجازه می‌ده Lightpanda رو به‌عنوان ابزار (tool) در اختیار مدل‌های زبانی بذاری. آداپتور session-aware هست، یعنی با پاس‌دادن یه session_id یکسان بین چند tool call، سشن مرورگر باز می‌مونه — چیزی که برای تسک‌های چند مرحله‌ای مهمه. ابزارهایی مثل lightpanda_markdown، lightpanda_click و lightpanda_semantic_tree به‌صورت خودکار ثبت می‌شن و می‌شه از طریق config محدودشون کرد.

آداپتور MCP server هم ابزارهای Lightpanda رو با container لاراول یکپارچه می‌کنه و session pool و تنظیمات پراکسی رو با آداپتور AI به اشتراک می‌ذاره. مدیریت session هم از طریق config قابل کنترله.

نکات کلیدی:

• SDK لاراول برای مرورگر هدلس Lightpanda (نوشته‌شده با Zig)
• پروفایل‌بندی instance برای تنظیمات مجزای CLI/Docker
• نتایج تایپ‌سیف با FetchResult و exception به‌جای داده‌ی اشتباه
• پشتیبانی از پراکسی به‌ازای هر درخواست
• یکپارچگی با Laravel AI SDK و MCP server برای استفاده در پایپلاین‌های هوش مصنوعی