كيفاش تستعمل qz-browser-agent فالبحث فالويب والأوتوماسيون ديال المتصفح محلياً

شنو هو qz-browser-agent؟

qz-browser-agent، اللي كيتسمّى حتى 轻舟 أو «القارب الخفيف»، هو إضافة ديال Chrome محلية بالأساس للبحث فالويب، وأتمتة المتصفح، واستخراج البيانات المنظّمة. كتمكّنك تستعمل مزوّد النموذج ديالك، وتتفاعل مع المواقع من خلال لوحة جانبية فالمتصفح، وتوسّع الوكيل باستعمال Skills قابلة لإعادة الاستخدام أو إمكانيات TypeScript.

الجلسات وSkills والبيانات المجموعة كيتخزنو فالمتصفح ديالك. طلبات النموذج تقدر تتضمّن البرومبت ديالك وأي محتوى ديال صفحة أو ملف كتضيفو لسياق المهمة. Skills واتصالات MCP يقدرو يتبادلو البيانات مع الخدمات اللي كتكوّنها، لذلك راجع وثائق الصلاحيات وتدفّق البيانات ديال المشروع قبل ما تستعمل الخدمات الخارجية.

الميزات الرئيسية

• أتمتة المتصفح: تفاعل مع عناصر DOM أو لقطات الشاشة، عمّر الاستمارات، وخدم بين التبويبات فواجهات سطح المكتب أو الهاتف.
• المهام الفرعية المتوازية: شغّل المهام بالتوازي، وقاطعها أو وجّهها أو زِدها بالسياق بينما الخدمة مازال جارية.
• البيانات المنظّمة: استخرج الجداول والوسائط ومحتوى الصفحات لمجموعات محلية، ومن بعد عاين النتائج وعدّلها وصدّرها من اللوحة الجانبية.
• Skills: جمّع التعليمات والسكريبتات والأدوات وواجهة مخصّصة للوحة الجانبية فمسارات عمل قابلة لإعادة الاستخدام، مع إمكانية التفعيل فالمواقع المطابقة.
• اختيار النموذج: ربط المزوّدين اللي كيدعمو بروتوكول API متوافق واستدعاء الأدوات، بما فيهم خوادم النماذج المحلية.
• إمكانيات TypeScript: زِد أدوات للوكيل، وواجهات للوحة، وصفحات الإعدادات، أو مزوّدي النماذج.
• جسر MCP: إلى بغيتي، عرّض أدوات المتصفح وعناصر التحكّم فالمهام للوكلاء الخارجيين عبر جسر MCP المحلي.

ثبّت إضافة Chrome

استعمل آخر إصدار

1. نزّل آخر إصدار ديال qz-browser-agent.
2. فكّ ضغط أرشيف ZIP اللي نزّلتي.
3. حلّ chrome://extensions فـ Chrome.
4. فعّل وضع المطوّر.
5. كليك على Load unpacked واختار المجلد المفكوك qz-browser-agent-extension.

بنِ من المصدر

باش تبني qz محلياً، ثبّت Node.js 24 LTS وnpm، ومن بعد نسخ أو نزّل المستودع. من داخل مجلد المشروع، ثبّت الاعتماديات وصايب نسخة الإضافة:

npm ci
npm run build

ملي يكمل البناء، رجع لـ chrome://extensions، اختار Load unpacked، واختار المجلد الناتج dist/extension/.

كوّن مزوّد النموذج

1. حلّ اللوحة الجانبية ديال qz من شريط أدوات الإضافة.
2. حلّ Settings.
3. اختار مزوّد النموذج ودخل بيانات الاعتماد ديالو.
4. إلى كنت كتستعمل نقطة نهاية مخصّصة، عطِ الرابط ديالها والبروتوكول اللي كتدعمو بجوج.
5. اختار نموذج وحفظ الإعدادات.

qz مصمّم يخدم مع المزوّدين اللي كيوفّرو بروتوكول API مدعوم واستدعاء الأدوات. تقدر تستعمل مزوّداً مستضافاً متوافقاً أو خادماً محلياً للنموذج، على حساب الإعداد ديالك.

شغّل أول مهمة فالمتصفح

من بعد ما تكوّن المزوّد، بدا بطلب بسيط للبحث والاستخراج:

حلّ example.com واستخرج العنوان الرئيسي ديالو فجدول.

الوكيل يقدر يمشي للصفحة المطلوبة، يفحص المحتوى ديالها، ويحط النتيجة المستخرجة فمجموعة محلية. استعمل اللوحة الجانبية باش تعاين البيانات المجموعة أو تعدّلها، وصدّرها ملي تكون المجموعة واجدة.

فالبحث الأكثر تعقيداً، طلب من qz يخدم بين صفحات أو تبويبات متعددة. ملي كتكون المهمة فيها أجزاء مستقلة، تقدر المهام الفرعية المتوازية تعاون فمعالجتها فآن واحد. وتقدر حتى تقاطع مهمة خدامة، توجّهها، أو تزيدها بسياق إضافي.

وسّع qz باستعمال Skills

Skills هي حزم قابلة لإعادة الاستخدام لمسارات العمل المتكررة. الـSkill يقدر يجمع التعليمات وأتمتة JavaScript والأدوات وعناصر تفاعلية مخصّصة فاللوحة الجانبية. ويمكن حتى إعداد Skills ديال المواقع باش تتفعّل فالمواقع المطابقة.

دبّر Skills من واجهة qz أو ثبّتها من مستودعات Git. استعمل Skills ملي كيحتاج مسار العمل لسلوك ثابت عبر مهام البحث المتكررة، بحال جمع المعلومات من موقع معيّن أو عرض النتائج من خلال مكوّن مخصّص فاللوحة.

زِد إمكانيات TypeScript

إمكانيات TypeScript كتخلّي المطوّرين يساهمو بوظائف جديدة فالإضافة. تقدر توفّر أدوات للوكيل، ومصيّرات لنتائج الأدوات، وصفحات للإعدادات، وواجهات للوحة، أو مزوّدي النماذج.

باش تبدا، نسخ مثال الإمكانيات ديال المشروع إلى src/capabilities/، بدّل أسماء التسجيلات، وخلي غير المساهمات اللي محتاجها الميزة ديالك. ملف إدخال بسيط يقدر يصدّر الأدوات والمصيّرات بهاد الشكل:

// src/capabilities/<your-feature>/index.ts
export { default as tools } from "./tools.js";
export { default as renderers } from "./renderers.js";

البناء كيكتشف هاد التصريحات أوتوماتيكياً. معالجات الأدوات كتشغل فـ background service worker وتقدر تفوّض الإجراءات أو تنفيذ السكريبتات للتبويبات النشيطة. المصيّرات كتركّب بطاقات تفاعلية للنتائج فاللوحة الجانبية.

باش تعرف تفاصيل SDK والعقود الحالية ديال الإضافات، راجع دليل القدرات ووثائق المساهمين فالمشروع. هاد الواجهات البرمجية ما زالت تجريبية، لذلك خذ بعين الاعتبار التغييرات المحتملة ملي كتبني إضافة.

سيرورة التطوير

وجد بيئة الاختبار ديال المشروع باتباع وثائق الأوامر وخيارات البناء. أوامر التطوير الرئيسية هي:

npm run dev       # عاود البناء ملي كيتبدلو المصادر
npm test          # شغّل مجموعات الاختبار الافتراضية
npm run verify    # دير فحص للأنواع وشغّل الاختبارات الآلية مع التغطية

من بعد إعادة البناء، عاود حمّل الإضافة من chrome://extensions وعاود حلّ اللوحة الجانبية ديال qz. بهاد الطريقة كتضمن باللي Chrome كيستعمل آخر ملفات الإضافة المولّدة.

نصائح للاستعمال المتقدم

• استعمل مطالبات منظمة: وصف الصفحات المستهدفة، والحقول اللي بغيتي تجمع، والصيغة المطلوبة للإخراج، باش تقدر تنظم البيانات المستخرجة فمجموعة مفيدة.
• اختار نمط التفاعل المناسب: التفاعل المعتمد على DOM مفيد لعناصر الصفحات والاستمارات، بينما التفاعل المعتمد على لقطات الشاشة يقدر يعاون ملي كيكون السياق البصري مهم.
• فرّق بين سيرورات العمل القابلة للتكرار: حوّل التعليمات والسكربتات المتكررة لـ Skills بلا ما تعاودها فكل مطالبة.
• استعمل العمل المتوازي بحذر: فوّض مهام البحث المستقلة فآن واحد، ومن بعد راجع النتائج المجمعة فاللوحة الجانبية.
• فضّل الخدمات المحلية ملي تكون مناسبة: qz كيدعم خوادم النماذج المحلية، وهاد الشي يقدر يعاونك تخلي حركة النماذج داخل البنية التحتية اللي كتتحكم فيها.
• راجع اتصالات البيانات: محتوى الصفحات، والملفات، وSkills، وتكاملات MCP يقدرو يتضمنو فالطلبات أو يتبادلو مع الخدمات المهيأة. راجع الأذونات قبل ما تتعامل مع معلومات حساسة.
• عاود التحميل من بعد تغييرات المصدر: إعادة البناء بنجاح ما كتحدّثش الإضافة أوتوماتيكيا؛ عاود حمّلها فـ Chrome قبل الاختبار.

تكامل MCP اختياري

جسر MCP المحلي الاختياري كيوفّر أدوات المتصفح وعناصر التحكم فالمهام للوكلاء الخارجيين. استعملو ملي تحتاج وكيل أو تطبيق آخر متوافق مع MCP يتحكم فـ qz. حيث إن اتصالات MCP تقدر تتبادل البيانات مع الخدمات المهيأة، راجع وثائق الجسر وتأثيرات تدفق البيانات قبل ما تفعّلو.

الخلاصة

qz-browser-agent كيجمع بين لوحة جانبية ديال Chrome، وأتمتة المتصفح المعتمدة على النماذج، ومجموعات محلية منظمة، ومهام فرعية متوازية، وإمكانية التوسعة باستعمال Skills وTypeScript. ثبّت الإصدار باش تبدا بسرعة، وهيّأ مزوّد نماذج متوافق، وجرّب مطالبة مركزة لاستخراج البيانات. إلا كنت محتاج سيرورات عمل أو تكاملات مخصصة، بنِ المشروع من المصدر ووسّعو باستعمال Skills أو القدرات أو جسر MCP الاختياري.