> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wolffi.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# إضافة المتصفح

> تحكّم بمتصفح Chrome أو Brave الحقيقي للمستخدم بـ 49 أداة — تنقّل، نقر، قراءة، لقطات شاشة، وضع المُنقّح، أنسنة، والمزيد

# متصفحك الحقيقي، لا بيئة معزولة

إضافة وولف فيش للمتصفح تمنح الوكيل تحكّمًا مباشرًا بمتصفحك الحقيقي. على عكس قدرة المتصفح المبنية على Playwright (التي تعمل في جلسة معزولة)، الإضافة تعمل في متصفحك الفعلي — ملفات تعريف الارتباط وتسجيلات الدخول والإضافات والتبويبات المفتوحة كلها متاحة.

<Info>
  الوكيل يفضّل تلقائيًا أدوات `ext_*` على أدوات Playwright `browser_*` عندما تكون الإضافة متصلة. لا حاجة لأي إعداد.
</Info>

## لماذا هذه الإضافة

التحكم بالحاسوب — حيث يلتقط الذكاء الاصطناعي لقطات شاشة ويحرّك الماوس ويكتب — يعمل، لكنه بطيء ومكلف وهشّ. كل إجراء يتطلب لقطة شاشة كاملة تُرسل لنموذج رؤية، والنموذج يخمّن أين ينقر بناءً على إحداثيات البكسل، والأخطاء تتراكم لأنه لا يفهم بنية الصفحة.

الإضافة تستبدل كل ذلك بتحكّم مباشر بالمتصفح. لا حاجة للقطات شاشة للتنقل. لا تخمين. الوكيل يرسل `ext_click('.submit-btn')` والإضافة تنقر على العنصر الفعلي. يرسل `ext_read_page({ format: 'text' })` ويحصل على نص نظيف — وليس لقطة شاشة بحجم 2 ميجابايت.

الميزة الحقيقية هي **إعادة استخدام الجلسة**. متصفحك مسجّل الدخول فعلاً في كل شيء — Gmail، LinkedIn، Reddit، GitHub، Notion، أدوات شركتك الداخلية. الإضافة تمنح الوكيل وصولاً لكل ذلك بدون تخزين بيانات اعتماد أو إدارة OAuth أو تشغيل متصفحات مؤقتة.

### أمثلة واقعية

* **"لخّص صفحتي الرئيسية في Reddit"** — الوكيل يفتح Reddit (أنت مسجّل الدخول فعلاً)، يقرأ المنشورات، يمرّر لتحميل المزيد، ويعطيك ملخصًا. بدون مفتاح API، بدون OAuth.
* **"ابحث في Reddit عن مراجعات MacBook Air M4"** — ينتقل للبحث، يقرأ النتائج، يدخل المواضيع، يستخرج التعليقات المفيدة.
* **"نظّف محادثات LinkedIn — احذف التي لم أرد عليها منذ 6 أشهر"** — يفتح الرسائل، يقرأ المعاينات، يحدد القديمة، ويحذفها.
* **"اقبل طلبات الاتصال المعلّقة من أشخاص في مجالي"** — يفتح صفحة الدعوات، يقرأ كل طلب، يتحقق من العنوان، يقبل المناسبين.
* **"تحقق من إشعارات GitHub وأغلق المشاكل المحلولة"** — يفتح الإشعارات، يقرأ كل واحد، يتابع الرابط، يتحقق ويغلق.
* **"ابحث في Hacker News عن أوراق الذكاء الاصطناعي اليوم واحفظ الروابط"** — لا يوجد API لهذا. الإضافة تقرأ الصفحة كما تفعل أنت.

هذه ليست افتراضية — هي سير العمل التي بُنيت الإضافة من أجلها.

## التكلفة: لماذا اختيار النموذج مهم

أتمتة المتصفح تولّد سياقات كبيرة بسرعة. كل `ext_read_page` يعيد النص الكامل. كل `ext_screenshot` يضيف صورة للسياق. جلسة تصفح نموذجية بـ 20-30 استدعاء أداة يمكن أن تدفع السياق لأكثر من 100 ألف رمز.

| النموذج         | \~30 استدعاء | \~50 استدعاء |
| --------------- | ------------ | ------------ |
| Claude Opus 4.6 | \~25\$       | \~40\$+      |
| GPT-4o          | \~8\$        | \~15\$       |
| DeepSeek V3     | \~1.30\$     | \~2.50\$     |
| MiniMax-M1      | \~1.50\$     | \~3\$        |

<Warning>
  جلسة تصفح واحدة تبدو روتينية — "تحقق من 5 إعلانات وظائف وقارنها بملفي" — يمكن أن تتضمن 30+ استدعاء أداة و10+ قراءات صفحة ولقطتي شاشة+. على Opus هذا 25$ للمرة الواحدة. على DeepSeek 1.30$ لنفس النتيجة.
</Warning>

ننصح بـ **DeepSeek** أو **MiniMax** أو **Kimi** لسير العمل الكثيف على المتصفح. تتعامل مع التصفح المعقّد متعدد الخطوات بموثوقية وبجزء بسيط من التكلفة. فرق الجودة لمهام "تنقّل، اقرأ، استخرج، لخّص" ضئيل. احتفظ بالنماذج المتقدمة للمهام التي تحتاج فعلاً لتفكير أعمق.

<Tip>
  يمكنك تعيين نماذج مختلفة لكل محادثة في وولف فيش. استخدم DeepSeek لجلسات التصفح وClaude للمهام المعقدة — لا تحتاج لاختيار نموذج واحد لكل شيء.
</Tip>

## البنية

الإضافة تتصل بتطبيق وولف فيش عبر WebSocket محلي.

```
الوكيل → الإضافة (أدوات ext_*) → WebSocket (localhost:23151) → Service Worker → Chrome APIs / Content Script → النتيجة
```

| المكوّن            | الموقع                                         | الدور                                              |
| ------------------ | ---------------------------------------------- | -------------------------------------------------- |
| **خادم WebSocket** | `channels/extension/server.ts` (أساسي)         | إدارة الاتصال، نبض القلب، توجيه الأوامر            |
| **مسجّل الأحداث**  | `channels/extension/log.ts` (أساسي)            | تسجيل الأحداث لكل محادثة                           |
| **الإضافة**        | `cerebellum/browser-extension/` (قابل للتعديل) | تعريفات الأدوات، منطق التنفيذ، معالجة لقطات الشاشة |
| **الإضافة**        | `~/.wolffish/workspace/extension/`             | إضافة Chrome المحمّلة في المتصفح                   |

## الإعداد

1. افتح **الإعدادات → الخدمات → إضافة المتصفح**
2. انقر **عرض في فايندر** للوصول لمجلد الإضافة
3. افتح Chrome أو Brave → `chrome://extensions`
4. فعّل **وضع المطور** → **رفع غير مضغوطة** → اختر مجلد الإضافة
5. الإضافة تتصل تلقائيًا — النقطة تتحول للأخضر

<Tip>
  الإضافة تعيد الاتصال تلقائيًا عند إعادة تشغيل التطبيق. تحتاج لتحميلها مرة واحدة فقط.
</Tip>

## التحديث التلقائي

الإضافة تحدّث نفسها تلقائيًا عند تحديث وولف فيش — بدون أي خطوات يدوية.

1. كل إصدار من وولف فيش يتضمن أحدث ملفات الإضافة داخل التطبيق
2. عند كل تشغيل، الملفات تُنسخ إلى `~/.wolffish/workspace/extension/` فوق النسخة السابقة
3. عند اتصال الإضافة، الخادم يقارن إصدارها بالإصدار الموجود على القرص
4. إذا اختلفا، يرسل الخادم أمر إعادة تحميل — الإضافة تستدعي `chrome.runtime.reload()` وتلتقط الكود الجديد وتعيد الاتصال تلقائيًا

العملية سلسة بالكامل. سترى انقطاعًا قصيرًا في اللوحة الجانبية (أقل من ثانية) أثناء إعادة تشغيل الإضافة، ثم تعيد الاتصال بالإصدار الجديد. يمكنك أيضًا تشغيل إعادة التحميل يدويًا من **الإعدادات → الخدمات → إضافة المتصفح → تحديث الإضافة**.

## 49 أداة

الوكيل يراها كأدوات `ext_*`. الإضافة تترجمها لأوامر `browser_*` عبر البروتوكول.

### التنقل

`ext_navigate` · `ext_back` · `ext_forward` · `ext_reload`

### التفاعل مع الصفحة

`ext_click` · `ext_type` · `ext_select` · `ext_hover` · `ext_scroll` · `ext_focus` · `ext_keypress` · `ext_drag_drop` · `ext_file_upload`

### قراءة الصفحة

`ext_read_page` · `ext_query_selector` · `ext_get_attribute` · `ext_get_value` · `ext_get_url` · `ext_get_page_info`

### إدارة التبويبات والنوافذ

`ext_tabs_list` · `ext_tab_open` · `ext_tab_close` · `ext_tab_switch` · `ext_tab_duplicate` · `ext_tab_move` · `ext_windows_list` · `ext_window_open` · `ext_window_close` · `ext_window_resize`

### الالتقاط

`ext_screenshot` · `ext_pdf` · `ext_download`

### البيانات والتخزين

`ext_cookies_get` · `ext_cookies_set` · `ext_cookies_remove` · `ext_storage_get` · `ext_storage_set` · `ext_clipboard_read` · `ext_clipboard_write`

### متقدم

`ext_execute_js` · `ext_wait_for` · `ext_wait_for_navigation` · `ext_wait_for_network_idle` · `ext_notify`

### وضع المُنقّح

`ext_debugger_attach` · `ext_debugger_detach` · `ext_debugger_status`

### الماوس والأنسنة

`ext_mouse_move` · `ext_humanize`

## وضع المُنقّح (Debugger Mode)

وضع المُنقّح يربط بروتوكول أدوات المطور في Chrome (CDP) بتبويب ويستبدل التفاعلات عبر content script بأحداث إدخال منخفضة المستوى. عند تفعيل المُنقّح، النقرات والكتابة والتمرير والتحويم والضغطات تُرسل عبر أوامر `Input.dispatch*` في CDP بدلاً من واجهات DOM.

### لماذا يوجد

تفاعلات content script مثل `element.click()` و `element.value = '...'` قابلة للاكتشاف. المواقع تستطيع التمييز بين الأحداث البرمجية وإدخال المستخدم الحقيقي عبر فحص خصائص مثل `isTrusted`، أو مراقبة ترتيب الأحداث، أو استخدام مكتبات كشف البوتات. أحداث CDP تتجاوز كل هذا — تدخل خط أنابيب الإدخال في المتصفح بنفس مستوى أحداث لوحة المفاتيح والماوس الفعلية.

### كيف يعمل

1. الوكيل يستدعي `ext_debugger_attach` مع معرّف التبويب
2. Chrome يربط بروتوكول المُنقّح بالتبويب (سترى شريط "... is debugging this tab")
3. جميع استدعاءات `ext_click` و `ext_type` و `ext_scroll` و `ext_hover` و `ext_keypress` على ذلك التبويب تُوجَّه تلقائيًا عبر CDP بدلاً من content script
4. حركات الماوس تتبع منحنيات بيزيه مع توقيت بتوزيع غاوسي — وليس خطوطًا مستقيمة بتأخيرات ثابتة
5. الكتابة تُرسل تسلسلات `keyDown`/`char`/`keyUp` لكل حرف بتأخيرات متغيرة بين المفاتيح
6. عند الانتهاء، استدعِ `ext_debugger_detach` لتحرير المُنقّح

```
الوكيل يستدعي ext_click('.btn')
  ↓
الإضافة تتحقق: هل المُنقّح مفعّل؟
  ├─ نعم → يحدد إحداثيات العنصر → مسار بيزيه للماوس → CDP mousePressed/mouseReleased
  └─ لا  → content script → element.click()
```

التوجيه تلقائي. الوكيل لا يحتاج لتغيير طريقة استدعاء الأدوات — يكفي تفعيل المُنقّح أولاً وكل شيء يتحوّل.

### القيود

* تبويب واحد فقط يمكن ربط المُنقّح به في نفس الوقت — الربط بتبويب جديد يفصل السابق
* Chrome يعرض شريطًا أصفر "debugging" أعلى الصفحة (لا يمكن إخفاؤه)
* صفحات `chrome://` و `chrome-extension://` لا يمكن تنقيحها
* إذا كانت أدوات المطور مفتوحة بالفعل على التبويب، لا يمكن ربط المُنقّح

## الأنسنة (Humanize)

أداة الأنسنة (`ext_humanize`) تحقن سلوكيات بشرية دقيقة بين إجراءات الوكيل. بدلاً من أن ينقر الوكيل ويكتب ويتنقل بدقة آلية وبدون أي وقت خمول، الأنسنة تضيف التوقفات والتمريرات الصغيرة وانزلاقات المؤشر وتأخيرات القراءة التي ينتجها المستخدمون الحقيقيون طبيعيًا.

<Warning>
  **استخدم بمسؤولية.** الأنسنة مصممة للاختبار والبحث والأتمتة الشخصية. بعض المنصات تكتشف السلوك الآلي بنشاط وقد تعاقب أو تقيّد أو تحظر الحسابات التي تنتهك شروط الخدمة. استخدام الأنسنة لتجاوز كشف البوتات على منصات تحظر الأتمتة يكون على مسؤوليتك الخاصة. نحن لا نشجع أو ندعم انتهاك شروط خدمة أي منصة.
</Warning>

### مستويات الشدة

| المستوى    | الإجراءات الدقيقة                                                     | حالة الاستخدام                                           |
| ---------- | --------------------------------------------------------------------- | -------------------------------------------------------- |
| `light`    | توقفات عشوائية، تمريرات دقيقة                                         | أقل بصمة — يضيف تنوعًا أساسيًا في التوقيت                |
| `moderate` | توقفات، تمريرات، حركات مؤشر، تحويم على عناصر غير تفاعلية، تمرير متغير | متوازن — يبدو كمستخدم مشتت                               |
| `heavy`    | كل ما سبق + ارتداد التمرير، انزلاق الخمول، توقفات طويلة               | محاكاة كاملة — توقفات قراءة، تمرير ثم عودة، تجوّل المؤشر |

### الإجراءات الدقيقة

كل استدعاء `ext_humanize` يختار إجراءً عشوائيًا من مجمّع مستوى الشدة وينفذه:

* **توقف عشوائي** — انتظار 0.8-2 ثانية (يحاكي التفكير أو القراءة)
* **تمرير دقيق** — تمرير بمقدار صغير للأعلى أو الأسفل، أحيانًا يعود
* **حركة مؤشر** — يحرك المؤشر لعنصر غير تفاعلي عبر مسار بيزيه
* **تحويم على عنصر خامل** — ينتقل لعنصر غير تفاعلي ويتوقف قليلاً
* **تمرير متغير** — 2-4 خطوات تمرير صغيرة متتالية بتوقيت متغير
* **ارتداد التمرير** — يمرر للأسفل ثم يعود للأعلى (كمن تجاوز أثناء القراءة)
* **انزلاق الخمول** — حركات مؤشر عشوائية صغيرة حول الموضع الحالي
* **توقف طويل** — انتظار 2-5 ثوانٍ (يحاكي قراءة فقرة)

كل التوقيتات تستخدم توزيعات غاوسية — بدون تأخيرات ثابتة. حركات الماوس تتبع منحنيات بيزيه التكعيبية بنقاط تحكم عشوائية.

### مع وضع المُنقّح

الأنسنة تعمل مع أو بدون المُنقّح. عند تفعيل المُنقّح، إجراءات التمرير والمؤشر تستخدم أحداث CDP. بدونه، تعود لتنفيذ content script. الوكيل لا يحتاج للتنسيق — الأنسنة تتحقق من حالة المُنقّح تلقائيًا.

## لقطات الشاشة

لقطات الشاشة تُعالج عبر **sharp** قبل إرسالها للنموذج:

1. الإضافة تلتقط التبويب المرئي عبر `chrome.tabs.captureVisibleTab()`
2. الإضافة تزيل بادئة data URL وتفك الترميز
3. sharp تغيّر الحجم للعرض الأقصى المُعدّ (افتراضي 1280 بكسل)
4. تحويل للصيغة المُعدّة (افتراضي JPEG، جودة 80)
5. تعيد base64 نظيف — يُعرض تلقائيًا في المحادثة

عدّل الدقة والصيغة في **الإعدادات → الخدمات → إضافة المتصفح**.

## اللوحة الجانبية

الإضافة تتضمن لوحة جانبية تعرض:

* **حالة الاتصال** — متصل، بانتظار، أو غير متصل
* **بث الأحداث المباشر** — كل استدعاء أداة يظهر فوريًا أثناء تصفح الوكيل
* **سجل المحادثات** — تصفّح أحداث المحادثات السابقة

الأحداث تُسجّل لكل محادثة في `~/.wolffish/workspace/logs/extension/{conversationId}.jsonl`.

## التخصيص

### تعديل تعليمات الوكيل

عدّل `~/.wolffish/workspace/brain/cerebellum/.browser-extension/SKILL.md`:

* غيّر أوصاف الأدوات لتوجيه الوكيل بشكل مختلف
* أضف أو عدّل كلمات التفعيل
* أضف أنماط الأمان (`danger_patterns`، `confirm_patterns`)
* عدّل نص التعليمات لإجراءات تصفح مخصصة

### تعديل الإضافة

عدّل `~/.wolffish/workspace/brain/cerebellum/.browser-extension/plugin/index.mjs`:

* أضف معالجة قبل/بعد استدعاءات الأدوات
* اجمع أوامر متعددة في أدوات عالية المستوى
* خصّص معالجة لقطات الشاشة
* أضف أدوات جديدة تجمع الأوامر الموجودة

### بناء إضافة مخصصة

خادم WebSocket لا يهتم بمحتوى الأوامر — يمرر أي `{ id, type, params }` للإضافة ويحل عند وصول الاستجابة. يمكنك نسخ الإضافة وإضافة أوامر جديدة وتحديث الإضافة.

راجع [مستودع الإضافة](https://github.com/thewolffish/wolffish-extension) للشفرة المصدرية الكاملة.

## المتصفحات المدعومة

| المتصفح  | الحالة    |
| -------- | --------- |
| Chromium | مدعوم     |
| Chrome   | مدعوم     |
| Brave    | مدعوم     |
| Edge     | مدعوم     |
| Safari   | غير مدعوم |
| Firefox  | غير مدعوم |

## الأمان

الإضافة ترث نظام أمان القدرات القياسي:

* `ext_execute_js` مع `document.cookie` أو `navigator.sendBeacon` → **محظور**
* `ext_execute_js` (أي) → **يتطلب موافقة**
* `ext_download` → **يتطلب موافقة**
* `ext_cookies_set` → **يتطلب موافقة**
* التنقل لمواقع مالية → **يتطلب موافقة**

هذه الأنماط معرّفة في SKILL.md وتُطبّق بواسطة وحدة الأميجدالا. يمكنك تخصيصها.

<Warning>
  **وضع المُنقّح والأنسنة يحملان مخاطر إضافية.** هذه الميزات تجعل التصفح الآلي أقل تمييزًا عن التصفح البشري. رغم فائدتها للاختبار والأتمتة الشخصية، استخدامها لتجاوز أنظمة كشف البوتات أو CAPTCHA على منصات تحظر الأتمتة قد يؤدي لتعليق الحساب أو الحظر الدائم. المسؤولية تقع على المستخدم. استخدم هذه الأدوات بأخلاقية وبما يتوافق مع شروط خدمة كل منصة.
</Warning>