واجهة برمجة تطبيقات التحكم في المتصفح

لإعداد الأداة وتهيئتها واستكشاف أخطائها وإصلاحها، راجع Browser. هذه الصفحة هي مرجع واجهة HTTP API المحلية للتحكم، وCLI OmeniaClaw browser، وأنماط البرمجة النصية (اللقطات، والمراجع، والانتظارات، وتدفقات التصحيح).

واجهة التحكم API (اختيارية)

للتكاملات المحلية فقط، يوفّر Gateway واجهة HTTP API صغيرة عبر loopback:

• الحالة/البدء/الإيقاف: GET /, POST /start, POST /stop
• علامات التبويب: GET /tabs, POST /tabs/open, POST /tabs/focus, DELETE /tabs/:targetId
• اللقطة/لقطة الشاشة: GET /snapshot, POST /screenshot
• الإجراءات: POST /navigate, POST /act
• الخطافات: POST /hooks/file-chooser, POST /hooks/dialog
• التنزيلات: POST /download, POST /wait/download
• الأذونات: POST /permissions/grant
• التصحيح: GET /console, POST /pdf
• التصحيح: GET /errors, GET /requests, POST /trace/start, POST /trace/stop, POST /highlight
• الشبكة: POST /response/body
• الحالة: GET /cookies, POST /cookies/set, POST /cookies/clear
• الحالة: GET /storage/:kind, POST /storage/:kind/set, POST /storage/:kind/clear
• الإعدادات: POST /set/offline, POST /set/headers, POST /set/credentials, POST /set/geolocation, POST /set/media, POST /set/timezone, POST /set/locale, POST /set/device

تقبل جميع نقاط النهاية ?profile=<name>. يطلب POST /start?headless=true تشغيلاً headless لمرة واحدة للملفات الشخصية المحلية المُدارة دون تغيير تهيئة المتصفح المحفوظة؛ وترفض ملفات التعريف attach-only وremote CDP والجلسات الموجودة هذا التجاوز لأن OmeniaClaw لا يشغّل عمليات المتصفح تلك.

إذا كانت مصادقة Gateway بالسر المشترك مهيأة، فإن مسارات HTTP للمتصفح تتطلب المصادقة أيضًا:

• Authorization: Bearer <gateway token>
• x-OmeniaClaw-password: <gateway password> أو مصادقة HTTP Basic باستخدام تلك كلمة المرور

ملاحظات:

• لا تستهلك واجهة loopback المستقلة هذه للمتصفح ترويسات هوية trusted-proxy أو Tailscale Serve.
• إذا كان gateway.auth.mode هو none أو trusted-proxy، فإن مسارات loopback هذه للمتصفح لا ترث تلك الأوضاع الحاملة للهوية؛ أبقِها loopback-only.

عقد أخطاء /act

يستخدم POST /act استجابة خطأ منظمة لفشل التحقق على مستوى المسار وفشل السياسات:

{ "error": "<message>", "code": "ACT_*" }

قيم code الحالية:

• ACT_KIND_REQUIRED (HTTP 400): kind مفقود أو غير معروف.
• ACT_INVALID_REQUEST (HTTP 400): فشل تطبيع حمولة الإجراء أو التحقق منها.
• ACT_SELECTOR_UNSUPPORTED (HTTP 400): استُخدم selector مع نوع إجراء غير مدعوم.
• ACT_EVALUATE_DISABLED (HTTP 403): evaluate (أو wait --fn) معطل بواسطة التهيئة.
• ACT_TARGET_ID_MISMATCH (HTTP 403): يتعارض targetId على المستوى الأعلى أو ضمن الدُفعات مع هدف الطلب.
• ACT_EXISTING_SESSION_UNSUPPORTED (HTTP 501): الإجراء غير مدعوم لملفات تعريف الجلسات الموجودة.

قد تعيد حالات فشل التشغيل الأخرى { "error": "<message>" } دون حقل code.

متطلب Playwright

تتطلب بعض الميزات (التنقل/الإجراء/لقطة AI/لقطة الدور، ولقطات شاشة العناصر، وPDF) وجود Playwright. إذا لم يكن Playwright مثبتًا، فتعيد نقاط النهاية هذه خطأ 501 واضحًا.

ما يزال يعمل دون Playwright:

• لقطات ARIA
• لقطات إمكانية الوصول بنمط الدور (--interactive, --compact, --depth, --efficient) عندما يكون WebSocket لكل علامة تبويب عبر CDP متاحًا. هذا بديل للفحص واكتشاف المراجع؛ ويبقى Playwright محرك الإجراءات الأساسي.
• لقطات شاشة الصفحة لمتصفح OmeniaClaw المُدار عندما يكون WebSocket لكل علامة تبويب عبر CDP متاحًا
• لقطات شاشة الصفحة لملفات تعريف existing-session / Chrome MCP
• لقطات شاشة existing-session القائمة على المرجع (--ref) من مخرجات اللقطة

ما يزال يحتاج إلى Playwright:

• navigate
• act
• لقطات AI التي تعتمد على تنسيق لقطة AI الأصلي في Playwright
• لقطات شاشة عناصر محدد CSS (--element)
• تصدير PDF كامل للمتصفح

ترفض لقطات شاشة العناصر أيضًا --full-page؛ يعيد المسار fullPage is not supported for element screenshots.

إذا رأيت Playwright is not available in this gateway build، فهذا يعني أن Gateway المعبأ يفتقد تبعية تشغيل المتصفح الأساسية. أعد تثبيت OmeniaClaw أو حدّثه، ثم أعد تشغيل Gateway. بالنسبة إلى Docker، ثبّت أيضًا ملفات Chromium الثنائية كما هو موضح أدناه.

تثبيت Playwright في Docker

إذا كان Gateway لديك يعمل في Docker، فتجنب npx playwright (تعارضات تجاوز npm). بالنسبة إلى الصور المخصصة، ضمّن Chromium داخل الصورة:

OmeniaClaw_INSTALL_BROWSER=1 ./scripts/docker/setup.sh

بالنسبة إلى صورة موجودة، ثبّت عبر CLI المضمن بدلاً من ذلك:

docker compose run --rm OmeniaClaw-cli \  node /app/node_modules/playwright-core/cli.js install chromium

لاستبقاء تنزيلات المتصفح، عيّن PLAYWRIGHT_BROWSERS_PATH (على سبيل المثال، /home/node/.cache/ms-playwright) وتأكد من استبقاء /home/node عبر OmeniaClaw_HOME_VOLUME أو bind mount. يكتشف OmeniaClaw تلقائيًا Chromium المستبقى على Linux. راجع Docker.

كيف يعمل (داخليًا)

يقبل خادم تحكم صغير عبر loopback طلبات HTTP ويتصل بالمتصفحات المبنية على Chromium عبر CDP. تمر الإجراءات المتقدمة (النقر/الكتابة/اللقطة/PDF) عبر Playwright فوق CDP؛ وعند غياب Playwright، لا تتوفر إلا العمليات غير المعتمدة على Playwright. يرى الوكيل واجهة مستقرة واحدة بينما تتبدل المتصفحات والملفات الشخصية المحلية/البعيدة بحرية تحتها.

مرجع سريع لـ CLI

تقبل جميع الأوامر --browser-profile <name> لاستهداف ملف تعريف محدد، و--json لإخراج قابل للقراءة آليًا.

OmeniaClaw browser statusOmeniaClaw browser startOmeniaClaw browser start --headless # one-shot local managed headless launchOmeniaClaw browser stop            # also clears emulation on attach-only/remote CDPOmeniaClaw browser tabsOmeniaClaw browser tab             # shortcut for current tabOmeniaClaw browser tab newOmeniaClaw browser tab select 2OmeniaClaw browser tab close 2OmeniaClaw browser open https://example.comOmeniaClaw browser focus abcd1234OmeniaClaw browser close abcd1234

OmeniaClaw browser screenshotOmeniaClaw browser screenshot --full-pageOmeniaClaw browser screenshot --ref 12        # or --ref e12OmeniaClaw browser screenshot --labelsOmeniaClaw browser snapshotOmeniaClaw browser snapshot --format aria --limit 200OmeniaClaw browser snapshot --interactive --compact --depth 6OmeniaClaw browser snapshot --efficientOmeniaClaw browser snapshot --labelsOmeniaClaw browser snapshot --urlsOmeniaClaw browser snapshot --selector "#main" --interactiveOmeniaClaw browser snapshot --frame "iframe#main" --interactiveOmeniaClaw browser console --level errorOmeniaClaw browser errors --clearOmeniaClaw browser requests --filter api --clearOmeniaClaw browser pdfOmeniaClaw browser responsebody "**/api" --max-chars 5000

OmeniaClaw browser navigate https://example.comOmeniaClaw browser resize 1280 720OmeniaClaw browser click 12 --double           # or e12 for role refsOmeniaClaw browser click-coords 120 340        # viewport coordinatesOmeniaClaw browser type 23 "hello" --submitOmeniaClaw browser press EnterOmeniaClaw browser hover 44OmeniaClaw browser scrollintoview e12OmeniaClaw browser drag 10 11OmeniaClaw browser select 9 OptionA OptionBOmeniaClaw browser download e12 report.pdfOmeniaClaw browser waitfordownload report.pdfOmeniaClaw browser upload /tmp/OmeniaClaw/uploads/file.pdfOmeniaClaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'OmeniaClaw browser dialog --acceptOmeniaClaw browser wait --text "Done"OmeniaClaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"OmeniaClaw browser evaluate --fn '(el) => el.textContent' --ref 7OmeniaClaw browser highlight e12OmeniaClaw browser trace startOmeniaClaw browser trace stop

OmeniaClaw browser cookiesOmeniaClaw browser cookies set session abc123 --url "https://example.com"OmeniaClaw browser cookies clearOmeniaClaw browser storage local getOmeniaClaw browser storage local set theme darkOmeniaClaw browser storage session clearOmeniaClaw browser set offline onOmeniaClaw browser set headers --headers-json '{"X-Debug":"1"}'OmeniaClaw browser set credentials user pass            # --clear to removeOmeniaClaw browser set geo 37.7749 -122.4194 --origin "https://example.com"OmeniaClaw browser set media darkOmeniaClaw browser set timezone America/New_YorkOmeniaClaw browser set locale en-USOmeniaClaw browser set device "iPhone 14"

ملاحظات:

• upload وdialog هما استدعاءا تسليح؛ شغّلهما قبل النقر/الضغط الذي يطلق منتقي الملفات/الحوار.
• تتطلب click/type/إلخ وجود ref من snapshot (رقمي 12، أو مرجع دور e12، أو مرجع ARIA قابل للتنفيذ ax12). محددات CSS غير مدعومة عمدًا للإجراءات. استخدم click-coords عندما يكون موضع منفذ العرض المرئي هو الهدف الموثوق الوحيد.
• تقيَّد مسارات التنزيل والتتبع والرفع بجذور OmeniaClaw المؤقتة: /tmp/OmeniaClaw{,/downloads,/uploads} (البديل: ${os.tmpdir()}/OmeniaClaw/...).
• يمكن لـ upload أيضًا تعيين مدخلات الملفات مباشرة عبر --input-ref أو --element.

تظل معرّفات علامات التبويب والتسميات المستقرة باقية بعد استبدال Chromium للهدف الخام عندما يستطيع OmeniaClaw إثبات علامة التبويب البديلة، مثل نفس URL أو تحوّل علامة تبويب قديمة واحدة إلى علامة تبويب جديدة واحدة بعد إرسال نموذج. تظل معرّفات الأهداف الخام متقلبة؛ فضّل suggestedTargetId من tabs في السكربتات.

نظرة سريعة على أعلام اللقطات:

• --format ai (الافتراضي مع Playwright): لقطة AI بمراجع رقمية (aria-ref="<n>").
• --format aria: شجرة إمكانية الوصول مع مراجع axN. عندما يكون Playwright متاحًا، يربط OmeniaClaw المراجع بمعرّفات DOM الخلفية إلى الصفحة الحية لكي تتمكن إجراءات المتابعة من استخدامها؛ وإلا فتعامل مع الإخراج بوصفه للفحص فقط.
• --efficient (أو --mode efficient): إعداد مسبق للقطة دور مدمجة. عيّن browser.snapshotDefaults.mode: "efficient" لجعل هذا هو الافتراضي (راجع تهيئة Gateway).
• تفرض --interactive, --compact, --depth, --selector لقطة دور بمراجع ref=e12. يحدد --frame "<iframe>" نطاق لقطات الدور إلى iframe.
• تضيف --labels لقطة شاشة لمنفذ العرض فقط مع تسميات مراجع متراكبة (تطبع MEDIA:<path>).
• تضيف --urls وجهات الروابط المكتشفة إلى لقطات AI.

اللقطات والمراجع

يدعم OmeniaClaw نمطين من "اللقطات":

• لقطة AI (مراجع رقمية): OmeniaClaw browser snapshot (افتراضي؛ --format ai)

  • الإخراج: لقطة نصية تتضمن مراجع رقمية.
  • الإجراءات: OmeniaClaw browser click 12, OmeniaClaw browser type 23 "hello".
  • داخليًا، يُحل المرجع عبر aria-ref في Playwright.

• لقطة الدور (مراجع دور مثل e12): OmeniaClaw browser snapshot --interactive (أو --compact, --depth, --selector, --frame)

  • الإخراج: قائمة/شجرة قائمة على الدور مع [ref=e12] (و[nth=1] اختياريًا).
  • الإجراءات: OmeniaClaw browser click e12, OmeniaClaw browser highlight e12.
  • داخليًا، يُحل المرجع عبر getByRole(...) (إضافة إلى nth() للتكرارات).
  • أضف --labels لتضمين لقطة شاشة لمنفذ العرض مع تسميات e12 متراكبة.
  • أضف --urls عندما يكون نص الرابط ملتبسًا ويحتاج الوكيل إلى أهداف تنقل ملموسة.

• لقطة ARIA (مراجع ARIA مثل ax12): OmeniaClaw browser snapshot --format aria

  • الناتج: شجرة إمكانية الوصول كعُقد منظمة.
  • الإجراءات: يعمل OmeniaClaw browser click ax12 عندما يستطيع مسار اللقطة ربط المرجع عبر Playwright ومعرفات DOM لخلفية Chrome.

• إذا لم يكن Playwright متاحًا، يمكن أن تظل لقطات ARIA مفيدة للفحص، لكن قد لا تكون المراجع قابلة للتنفيذ. أعد أخذ اللقطة باستخدام --format ai أو --interactive عندما تحتاج إلى مراجع إجراءات.

• إثبات Docker لمسار الرجوع الخام-CDP: يبدأ pnpm test:docker:browser-cdp-snapshot Chromium مع CDP، ويشغّل browser doctor --deep، ويتحقق من أن لقطات الأدوار تتضمن عناوين URL للروابط، والعناصر القابلة للنقر المرفوعة بالمؤشر، وبيانات iframe الوصفية.

سلوك المراجع:

• المراجع ليست ثابتة عبر عمليات التنقل؛ إذا فشل شيء ما، فأعد تشغيل snapshot واستخدم مرجعًا جديدًا.
• يعيد /act قيمة targetId الخام الحالية بعد الاستبدال الناتج عن الإجراء عندما يمكنه إثبات علامة التبويب البديلة. واصل استخدام معرفات/تسميات علامات التبويب الثابتة للأوامر اللاحقة.
• إذا أُخذت لقطة الدور باستخدام --frame، فإن مراجع الأدوار تكون محصورة بذلك iframe حتى لقطة الدور التالية.
• تفشل مراجع axN المجهولة أو القديمة بسرعة بدلًا من المتابعة إلى محدد aria-ref في Playwright. شغّل لقطة جديدة على علامة التبويب نفسها عندما يحدث ذلك.

تعزيزات الانتظار

يمكنك الانتظار على أكثر من مجرد الوقت/النص:

• انتظر عنوان URL (يدعم Playwright أنماط glob):
  • OmeniaClaw browser wait --url "**/dash"
• انتظر حالة التحميل:
  • OmeniaClaw browser wait --load networkidle
• انتظر شرط JS:
  • OmeniaClaw browser wait --fn "window.ready===true"
• انتظر حتى يصبح محدد مرئيًا:
  • OmeniaClaw browser wait "#main"

يمكن دمج هذه الخيارات:

OmeniaClaw browser wait "#main" \  --url "**/dash" \  --load networkidle \  --fn "window.ready===true" \  --timeout-ms 15000

سير عمل التصحيح

عندما يفشل إجراء ما (مثل "غير مرئي"، أو "انتهاك الوضع الصارم"، أو "محجوب"):

1. OmeniaClaw browser snapshot --interactive
2. استخدم click <ref> / type <ref> (فضّل مراجع الأدوار في الوضع التفاعلي)
3. إذا ظل يفشل: OmeniaClaw browser highlight <ref> لترى ما يستهدفه Playwright
4. إذا تصرفت الصفحة بغرابة:
   • OmeniaClaw browser errors --clear
   • OmeniaClaw browser requests --filter api --clear
5. للتصحيح العميق: سجّل تتبعًا:
   • OmeniaClaw browser trace start
   • أعد إنتاج المشكلة
   • OmeniaClaw browser trace stop (يطبع TRACE:<path>)

إخراج JSON

--json مخصص للبرمجة النصية والأدوات المنظمة.

أمثلة:

OmeniaClaw browser status --jsonOmeniaClaw browser snapshot --interactive --jsonOmeniaClaw browser requests --filter api --jsonOmeniaClaw browser cookies --json

تتضمن لقطات الأدوار في JSON refs بالإضافة إلى كتلة stats صغيرة (lines/chars/refs/interactive) حتى تتمكن الأدوات من التفكير في حجم الحمولة وكثافتها.

مقابض الحالة والبيئة

هذه مفيدة لسير عمل "اجعل الموقع يتصرف مثل X":

• ملفات تعريف الارتباط: cookies، وcookies set، وcookies clear
• التخزين: storage local|session get|set|clear
• وضع عدم الاتصال: set offline on|off
• الرؤوس: set headers --headers-json '{"X-Debug":"1"}' (لا يزال set headers --json '{"X-Debug":"1"}' القديم مدعومًا)
• مصادقة HTTP الأساسية: set credentials user pass (أو --clear)
• الموقع الجغرافي: set geo <lat> <lon> --origin "https://example.com" (أو --clear)
• الوسائط: set media dark|light|no-preference|none
• المنطقة الزمنية / اللغة المحلية: set timezone ...، وset locale ...
• الجهاز / إطار العرض:
  • set device "iPhone 14" (إعدادات أجهزة Playwright المسبقة)
  • set viewport 1280 720

الأمان والخصوصية

• قد يحتوي ملف تعريف متصفح OmeniaClaw على جلسات مسجل دخولها؛ عامله كبيانات حساسة.
• ينفّذ browser act kind=evaluate / OmeniaClaw browser evaluate وwait --fn JavaScript عشوائيًا في سياق الصفحة. يمكن لحقن المطالبات توجيه ذلك. عطّله باستخدام browser.evaluateEnabled=false إذا لم تكن بحاجة إليه.
• لتسجيلات الدخول وملاحظات مكافحة الروبوتات (X/Twitter، إلخ)، راجع تسجيل دخول المتصفح + النشر على X/Twitter.
• أبقِ مضيف Gateway/Node خاصًا (local loopback أو tailnet فقط).
• نقاط نهاية CDP البعيدة قوية؛ أنشئ نفقًا إليها واحمها.

مثال الوضع الصارم (حظر الوجهات الخاصة/الداخلية افتراضيًا):

{  browser: {    ssrfPolicy: {      dangerouslyAllowPrivateNetwork: false,      hostnameAllowlist: ["*.example.com", "example.com"],      allowedHostnames: ["localhost"], // optional exact allow    },  },}

ذات صلة

• المتصفح - نظرة عامة، التكوين، الملفات الشخصية، الأمان
• تسجيل دخول المتصفح - تسجيل الدخول إلى المواقع
• استكشاف أخطاء متصفح Linux وإصلاحها
• استكشاف أخطاء متصفح WSL2 وإصلاحها