المتصفح

EstaCoda تُؤتمت المتصفحات عبر بروتوكول Chrome DevTools (CDP). local-cdp مُنفّذ، ويمكن لمسار CDP المحلي المُشرف عليه تشغيل Chrome/Chromium تلقائيًا، وBrowserbase مُنفّذ خلف موافقة صريحة على إنفاق السحابة. المتصفح أداة مُشرف عليها بحدود أمان صريحة.

---

ما هو مُنفّذ

المحرك	الحالة	ملاحظات
local-cdp	live-proven	يتصل بـ Chrome/Chromium محلي عبر CDP. يمكن للوضع المُشرف عليه تشغيل Chrome/Chromium تلقائيًا.
mock	implemented	واجهة اختبار لاختبارات الدخان. لا متصفح حقيقي.
Browserbase	implemented	يتطلب بيانات اعتماد وموافقة صريحة على إنفاق السحابة قبل إنشاء جلسات قد تترتب عليها تكلفة.
browser-use	unsupported	نموذج مسجّل. غير مُنفّذ.
Firecrawl (browser)	unsupported	نموذج مسجّل. غير مُنفّذ.
Camofox	unsupported	نموذج مسجّل. غير مُنفّذ.

تُنشأ جلسات Browserbase فقط عبر محرك المتصفح حتى يمكن فرض browser.cloudSpendApproved. تبقى browser-use وFirecrawl وCamofox مزودات مؤجلة.

---

بحث الويب منفصل

web.search وweb.extract أدوات بحث ويب، وليست خلفيات لأتمتة المتصفح. يمكن لـ Brave Search وDDGS توفير web.search حي، ويوفر fetch الاستخراج الحارس. إعداد المتصفح لا يضبط Brave أو DDGS، وإعداد بحث الويب لا يوافق على إنفاق Browserbase ولا يشغّل جلسة متصفح.

---

عمليات CDP المحلي

عند تكوين CDP المحلي وتوصيله، تُدعم العمليات التالية:

• status — فحص حالة اتصال المتصفح
• navigate — تحميل عنوان URL
• snapshot — التقاط لقطة شجرة الوصول مع رجوع احتياطي إلى DOM
• click — النقر على عنصر باستخدام ref
• type — كتابة نص في حقل إدخال
• scroll — تمرير الصفحة
• key press — إرسال ضغطة مفتاح
• back — التنقل للخلف
• image listing — سرد الصور في الصفحة
• console capture — قراءة إخراج وحدة تحكم المتصفح
• raw CDP method call — تنفيذ أمر CDP عشوائي
• screenshot — التقاط لقطة شاشة للصفحة
• dialog handling — قبول/رفض مربعات الحوار

جميع العمليات باستثناء status تتطلب جلسة متصفح. أدوات المتصفح تشتق مفاتيح جلسات المتصفح من جلسة وقت التشغيل الحالية، لذلك تحصل جلسات الأب والجلسات المفوضة على حالة متصفح معزولة افتراضيًا. تمرير sessionId صريح يشارك تلك الجلسة المسماة عمدًا.

تستخدم الجلسات المُشرف عليها CDP Browser Contexts معزولة. تنشئ EstaCoda Browser Context لكل مفتاح جلسة متصفح، وتفتح page target داخل ذلك السياق، وتلغي السياق أثناء التنظيف حتى لا تتسرب ملفات تعريف الارتباط وحالة browser-context بين جلسات الأب/الجلسات المفوضة.

يمكن لـ CDP المحلي المُشرف عليه تشغيل Chrome/Chromium تلقائيًا عندما تكون browser.autoLaunch === true. يبحث الاكتشاف في الإعدادات المنظمة، ومتغيرات البيئة، والثنائيات المحلية، وافتراضات المنصة. يستخدم التشغيل مصفوفات وسائط منظمة، ولا يحلل browser.launchCommand كأمر shell، ولا يستخدم exec، وينشئ دليل بيانات مستخدم معزولًا، ولا يقتل إلا عمليات Chrome التي شغّلتها EstaCoda أثناء التنظيف.

اللقطات

تفضّل لقطات المتصفح شجرة الوصول من Accessibility.getFullAXTree. تعرض عناصر اللقطة مراجع حتمية مثل @e1، وقد تتضمن role وname وvalue وdisabled وchecked. يتم تخطي عقد AX المتجاهلة أو قليلة الفائدة.

يبقى مسار لقطة DOM رجوعًا احتياطيًا عندما تكون AX غير متاحة، أو فارغة، أو مشوهة، أو لا يمكن ربط المراجع القابلة للتنفيذ. تكون المراجع قابلة للتنفيذ عندما تُعرض.

تستخدم browser.snapshot لقطة مضغوطة افتراضيًا. اللقطات المضغوطة هي مجموعة AX محدودة من العناصر القابلة للتنفيذ، وليست ترشيحًا حقيقيًا للعناصر المرئية في منفذ العرض بعد. تمرير full: true يطلب مسار اللقطة الكاملة. يوسم إخراج الأداة اللقطات المضغوطة والكاملة، ويقص النتائج الكبيرة، وقد يلخص اللقطات الضخمة عند تفعيل الإعداد.

تتحكم الإعدادات التالية في تلخيص اللقطات:

• browser.summarizeSnapshots: false أو true أو "auto"
• browser.snapshotSummarizeThreshold: عتبة الأحرف قبل التفكير في التلخيص

في وضع "auto"، يعمل التلخيص فقط عندما يتوفر مسار نموذج مساعد ويتجاوز عرض اللقطة العتبة. تُحجب عناوين URL التي تحتوي أسرارًا والقيم الحساسة قبل استدعاءات المزود.

---

أمان عناوين URL

تفرض عمليات التنقل في المتصفح قواعد أمان URL. النظام لا يثق بعناوين URL ضمنيًا.

البروتوكولات المسموحة

فقط http: و https: مسموح بها. يتم رفض البروتوكولات الأخرى قبل التنقل.

المحظورة افتراضيًا

عناوين URL الخاصة والداخلية محظورة ما لم يُفعّل security.allowPrivateUrls صراحةً:

• localhost
• 127.0.0.1
• *.local
• 10.0.0.0/8، 172.16.0.0/12، 192.168.0.0/16

محظورة دائمًا

نقاط نهاية بيانات التعريف السحابية محظورة دائمًا، بغض النظر عن security.allowPrivateUrls:

• metadata.google.internal
• metadata.goog
• 169.254.169.254
• 169.254.170.2
• 169.254.169.253
• fd00:ec2::254
• 100.100.100.200

كشف الأسرار

عناوين URL التي تحتوي على علامات تشبه الأسرار (مفاتيح API، رموز، كلمات مرور) تُحذف أو تُحجب بواسطة مسارات الأدوات المحمية.

قوائم حظر المواقع

قوائم الحظر تدعم النطاقات الدقيقة، ونطاقات البدل، والملفات المشتركة. يتم فحص قائمة الحظر قبل التنقل.

يستخدم التوجيه الهجين المصنف نفسه. عناوين HTTP(S) العامة تُوجّه إلى Browserbase/السحابة عندما يكون Browserbase مُعدًا وموافقة الإنفاق مفعّلة. عناوين URL الخاصة/الداخلية تُوجّه إلى المحلي فقط عندما تكون security.allowPrivateUrls === true. تبقى نقاط البيانات التعريفية محظورة. فشل موافقة الإنفاق السحابي لا يرجع إلى المحلي. يمكن لفشل Browserbase الرجوع إلى المحلي عندما تكون browser.cloudFallback === true. التحويلات غير الآمنة تُفرّغ إلى about:blank عندما يمكن ذلك؛ وإلا تُغلق الجلسة غير الآمنة.

---

بوابة الموافقة

browser.cdp محمي بوابة موافقة افتراضيًا. يمكن لأمر CDP الخام تنفيذ أوامر متصفح غير مقيدة، لذا يتطلب موافقة صريحة ما لم يكن وضع الأمان open ويمر الأمر عبر الأرضية الصلبة.

عمليات المتصفح القياسية (navigate، click، type، scroll) تتبع سياسة موافقة الأداة العادية. لا يتم حمايتها بنفس درجة CDP الخام.

---

الإعداد

إعداد المتصفح يقع تحت browser في إعداد الملف الشخصي.

يدعم محرر الإعداد أربعة أوضاع للمتصفح ويكتب شكل الإعداد المسطح نفسه:

• متصفح محلي مُشرف عليه يكتب backend: "local-cdp"، وsupervised: true، وقيمة autoLaunch التي تمت مراجعتها، وcdpUrl الاختياري، وخيارات التشغيل التي تمت مراجعتها.
• متصفح CDP موجود يكتب backend: "local-cdp"، وsupervised: true، وautoLaunch: false، وcdpUrl الذي تمت مراجعته.
• متصفح Browserbase السحابي يكتب backend: "browserbase"، وcloudProvider: "browserbase"، وhybridRouting: true، وcloudFallback: true، وcloudSpendApproved: false.
• تعطيل أدوات المتصفح / محرك المتصفح غير مهيأ يكتب backend: "unconfigured".

التحقق الثابت في الإعداد لا يفتح صفحات، ولا يتصل بـ CDP، ولا يستدعي Browserbase، ولا ينشئ جلسات سحابية. وضع CDP الموجود يحظر روابط CDP المفقودة وغير المحلية؛ المضيفون المقبولون هم localhost و127.0.0.1 و::1.

إعداد المتصفح اختياري أثناء التهيئة الأولى. تستخدم التهيئة الأولى تدفق أوضاع المتصفح نفسه الذي يستخدمه محرر الإعداد، لكن فشل إعداد المتصفح أو بقاؤه غير مكتمل لا يحظر إكمال التهيئة الأساسية. إذا بقيت خطوة المتصفح غير مكتملة، تعرض التهيئة ذلك في الملخص، وتحذف مسودة المتصفح غير المكتملة، وتحذف أي كتابات سرية جزئية مؤجلة لـ Browserbase، ثم تسمح للمستخدم بالمتابعة. يمكن للمستخدم إعداد أدوات المتصفح لاحقًا من محرر الإعداد.

هذا الفصل مقصود:

• يبقى محرر الإعداد صارمًا. إعداد المتصفح غير الصالح يحظر تغيير المتصفح الذي تجري مراجعته.
• تبقى التهيئة الأولى متسامحة. إعداد المتصفح الاختياري غير المكتمل لا يجعل التهيئة الأولى تفشل.

اختيار تعطيل أدوات المتصفح نتيجة مقصودة. يكتب backend: "unconfigured" ويظهر كحالة غير مفعّل، وليس كفشل في إعداد المتصفح.

{
  "browser": {
    "backend": "local-cdp",
    "cdpUrl": "http://localhost:9222",
    "supervised": true,
    "autoLaunch": true,
    "launchExecutable": "/path/to/chrome",
    "launchArgs": ["--headless=new"],
    "chromeFlags": ["--no-first-run"],
    "summarizeSnapshots": "auto",
    "snapshotSummarizeThreshold": 8000
  }
}

المفتاح	الافتراضي	الوصف
backend	unconfigured	محرك المتصفح المستخدم.
cdpUrl	غير مضبوط	نقطة نهاية CDP لمتصفح يعمل يدويًا.
supervised	true	استخدام CDP المحلي المُشرف عليه عندما يكون backend هو local-cdp.
autoLaunch	false	ما إذا كان CDP المحلي المُشرف عليه قد يشغّل Chrome/Chromium تلقائيًا.
launchExecutable	غير مضبوط	مسار Chrome/Chromium الصريح والمفضل.
launchArgs	غير مضبوط	مصفوفة وسائط تشغيل منظمة.
chromeFlags	غير مضبوط	مصفوفة خيارات Chrome المتقدمة.
launchCommand	غير مضبوط	بيانات توافق مهملة فقط. لا تُقسم ولا تُحلل كـ shell.
summarizeSnapshots	"auto"	ما إذا كان يمكن تلخيص اللقطات المعروضة الضخمة.
snapshotSummarizeThreshold	8000	عتبة أحرف عرض اللقطة للتلخيص.

استخدم أمر الإعداد المنظم لمسار التشغيل التلقائي المحلي:

estacoda browser setup --backend local-cdp --auto-launch --launch-executable /path/to/chrome
estacoda browser setup --backend local-cdp --launch-executable /path/to/chrome --launch-arg --headless=new --chrome-flag --no-first-run --auto-launch

يبقى launchCommand مقبولًا للإعدادات القديمة، لكنه ليس مسار الإعداد الطبيعي.

يسجل الشكل القصير الملف التنفيذي ويفعّل التشغيل التلقائي المُشرف عليه. أضف --launch-arg و--chrome-flag بشكل متكرر عندما يحتاج المشغل إلى خيارات تشغيل محددة مثل headless mode أو --no-first-run.

إعداد Browserbase:

{
  "browser": {
    "backend": "browserbase",
    "cloudProvider": "browserbase",
    "cloudSpendApproved": false,
    "cloudFallback": true,
    "hybridRouting": true
  }
}

يتطلب Browserbase كلًا من BROWSERBASE_API_KEY وBROWSERBASE_PROJECT_ID. بيانات الاعتماد وحدها لا توافق على الإنفاق. يكتب الإعداد الإنفاق المعلق أو غير الموافق عليه كـ cloudSpendApproved: false؛ وتظل الإعدادات القديمة التي تحتوي cloudSpendApproved: "pending" قابلة للتحميل ومحظورة. شغّل estacoda browser approve-cloud للسماح بإنشاء جلسات متصفح سحابية، وestacoda browser revoke-cloud لحظرها مرة أخرى. قد تترتب على جلسات Browserbase تكلفة. الإعداد وحده لا ينشئ جلسات؛ الإنشاء كسول عندما تحتاج عملية متصفح إلى المحرك السحابي. تستخدم EstaCoda شكل API المُتحقق منه في docs/browserbase-api-notes.md.

estacoda browser setup --backend browserbase --cloud-provider browserbase
estacoda browser setup --backend browserbase --cloud-provider browserbase --hybrid-routing
estacoda browser approve-cloud
estacoda browser revoke-cloud

يضبط الأمر الأول Browserbase كمحرك المتصفح دون تفعيل browser.hybridRouting. ويفعّل الثاني التوجيه الهجين حتى تستخدم عناوين URL العامة السحابة وتستخدم العناوين الخاصة/الداخلية المسموحة المحلي. مطلوب approve-cloud قبل إنشاء جلسات قد تترتب عليها تكلفة. يحظر revoke-cloud إنشاء جلسات سحابية مستقبلية دون حذف بيانات الاعتماد.

backend: "unconfigured" تعطيل صارم في وقت التشغيل. تبقى أدوات المتصفح معطلة حتى إذا بقيت روابط CDP قديمة، أو إعدادات Browserbase، أو خيارات تشغيل، أو بيانات اعتماد Browserbase في الملف الشخصي أو البيئة.

---

الحالة والملفات

إعداد المتصفح خاص بالملف الشخصي. حالة جلسة المتصفح خاصة بعمر وقت التشغيل:

• حالة جلسة CDP تبقى في الذاكرة خلال عمر وقت التشغيل
• لقطات الشاشة والمنتجات تُكتب إلى دليل temp الخاص بالملف الشخصي النشط
• سجلات وحدة تحكم المتصفح تُلتقط لكل جلسة وتُدرج في تسجيل المنتجات

يستخدم التشغيل التلقائي المُشرف عليه دليل بيانات مستخدم مؤقتًا ومعزولًا لـ Chrome ويزيله أثناء التنظيف. لا يوجد ملف متصفح دائم أو ملف تعريف ارتباط عبر الجلسات إلا إذا استُخدم متصفح خارجي خارج مشغل EstaCoda.

---

أوضاع الفشل

رفض اتصال CDP: Chrome لا يعمل على cdpUrl المُعيّن. شغّل Chrome مع --remote-debugging-port=9222 أو فعّل autoLaunch.

التنقل محظور: عنوان URL انتهك قواعد الأمان. تحقق من قائمة الحظر وسياسة عنوان URL الخاص وقائمة نقاط نهاية البيانات التعريفية.

موافقة CDP الخام مطلوبة: الأمر يحتاج موافقة. وافق عليه، أو غيّر وضع الأمان إذا سمحت الأرضية الصلبة بذلك.

فشل لقطة الشاشة: الصفحة قد لا تكون قد انتهت من التحميل. أداة snapshot تلتقط DOM؛ لقطات الشاشة تلتقط السطح المُصيّر. التوقيت مهم.

فشل التشغيل التلقائي: لم يُعثر على ثنائي Chrome، أو لا توجد صلاحيات كافية للتشغيل. تحقق من which google-chrome أو which chromium-browser.

موافقة إنفاق Browserbase مفقودة: يبلغ محرك المتصفح أن الجلسات السحابية قد تترتب عليها تكلفة وتبقى محظورة حتى تشغيل estacoda browser approve-cloud.

فشل إنشاء جلسة Browserbase: مع browser.cloudFallback: true، يمكن لبعض إخفاقات السحابة الرجوع إلى المحلي. عدم الموافقة على الإنفاق لا يؤدي إلى الرجوع إلى المحلي.

حُظر تحويل هجين: خالف عنوان URL النهائي سياسة أمان المسار. تحاول EstaCoda تفريغ الجلسة إلى about:blank؛ وإذا فشل التفريغ، تُغلق الجلسة غير الآمنة.

الحدود الحالية

• engine: "agent-browser" مقبول في الإعداد لكنه غير مُنفّذ.
• دعم Lightpanda غير مُنفّذ.
• تبقى browser-use وFirecrawl browser وCamofox مزودات مؤجلة.
• اللقطات المضغوطة عبر AX هي مجموعة محدودة قابلة للتنفيذ، وليست ترشيحًا للعناصر المرئية في منفذ العرض.

---

مرتبطات

• الأدوات — نظرة عامة على الأدوات
• الأمان والموافقات — سلوك الموافقة
• مرجع المزودين — جدول نضج المزودين