لتحويل حركة مرور الشبكة على موقع ما إلى مواصفة API، دع وكيل برمجي يشغّل متصفحك الحقيقي عبر OpenCode Browse: يبدأ التقاطًا من نوع network على تبويب، ثم تتنقّل أنت في الموقع أثناء تسجيل دخولك، وبعدها يوقف الوكيل الالتقاط للحصول على كل طلب مع إخفاء بيانات الاعتماد. ثم يكتب الوكيل ملف OpenAPI من تلك التبادلات، ويستورد Apidog CLI الملف ويشغّل اختبارًا عليه.
يستعرض هذا الدليل تلك الدورة بأمر واحد موجَّه للوكيل: ما يلتقطه Browse، وما يخفيه، وأوامر apidog التي تكمل المهمة.
ما هو OpenCode Browse؟
OpenCode Browse هو خادم MCP مع إضافة لمتصفح Chromium تمكّن وكيلك البرمجي من استخدام متصفحك الحقيقي، بتبويباتك وتسجيلات دخولك وإضافاتك. تفتح الوكلاء تبويبات في الخلفية، ويقرؤون الصفحات، وينقرون، ويكتبون، ويلتقطون لقطات شاشة، ويسجّلون التبويبات ويحصلون على حركة مرور الشبكة. وعندما تتطلب خطوة تدخلك (تسجيل دخول، أو رسالة تحقق ثنائي، أو عملية دفع)، يسلّم الوكيل التبويب إليك وينتظر حتى تنقر «متابعة».

| البند | ما يقوله المصدر |
|---|---|
| الرخصة | MIT (ملف LICENSE في المستودع) |
| أول كود عام | أُنشئ المستودع في 27 أكتوبر 2026 |
| الإصدار الحالي | v0.1.0، نُشر في 16 نوفمبر 2026 (إعادة كتابة كملف تنفيذي Rust واحد) |
| المتصفحات | Chrome وEdge وBrave وArc وHelium وVivaldi وOpera وChromium |
| الوكلاء | OpenCode وClaude Code وCodex وCursor وZed ونحو 30 عميل MCP إضافي |
| الأسعار | غير مذكورة على صفحة المنتج |
لا تعرض صفحة المنتج أي سعر أو تاريخ إطلاق، لذا اعتبر رخصة MIT المؤشر الوحيد على التكلفة يمكنك تأكيده اليوم. وإذا كنت تقارنه بطريق DevTools، فإن دليلنا حول Chrome DevTools MCP مع Claude يغطي البديل.
لماذا تلتقط حركة المرور من متصفحك الحقيقي؟
معظم واجهات API غير الموثّقة تقف خلف تسجيل دخول. يبدأ المتصفح بدون واجهات (headless) بلا كوكيز، فيصطدم وكيلك بجدار تسجيل الدخول. أما Browse فيعمل داخل الملف الشخصي الذي تستخدمه أصلًا، فيرى الوكيل نفس الطلبات المصادَق عليها التي تراها أنت. وهذا يفيد في ثلاث مهام:
- توثيق أداة داخلية لم تكن لديها مواصفة قط، حتى يتوقف الزملاء الجدد عن قراءة كود JavaScript مُصغَّر (minified).
- بناء تكامل مع لوحة تحكم SaaS لا تغطي واجهتها البرمجية العامة سوى جزء مما تغطيه واجهتها الأمامية.
- كتابة اختبارات انحدار (regression) لتطبيق ويب قبل إعادة هيكلة الواجهة الخلفية.
الطريقة اليدوية هي تصدير HAR من DevTools؛ انظر دليلنا حول الهندسة العكسية لواجهات API. أما نسخة الوكيل فتكتب المواصفة عنك.

كيف تحوّل حركة مرور موقع إلى مواصفة API: 5 خطوات
- ثبّت Browse واربط الإضافة بمتصفحك.
- اطلب من وكيلك فتح الموقع في تبويب Browse وبدء التقاط
networkمُصفّى على XHR وFetch. - تنقّل في الميزات التي تريد توثيقها، ثم اطلب من الوكيل إيقاف الالتقاط.
- دع الوكيل يجمع التبادلات في مسارات ويكتب
openapi.json. - استورد المواصفة عبر Apidog CLI، وأنشئ حالة اختبار وشغّلها.
الخطوة 1: تثبيت Browse وربط وكيلك
يُثبَّت Browse بسكربت واحد على macOS وLinux:
curl -fsSL https://opencode.ai/browse/install | bash
على Windows، شغّل irm https://opencode.ai/browse/install.ps1 | iex في PowerShell. يمكنك أيضًا استخدام npm i -g @opencode/browse ثم browse install.
يضع الأمر browse install الملف التنفيذي في مكانه، ويضيف خادم Browse MCP إلى الوكلاء التي يجدها، ويربط إضافة Chrome Web Store. وللتخطي للمحدد التفاعلي:
browse install -a claude codex # Claude Code and Codex only
browse install -y # every agent found on this computer
أعد تشغيل وكيلك بعدها. ويُخبرك الأمر browse status عما إذا كان المُرحِّل والإضافة والربط بحالة سليمة.
تفصيل واحد يغيّر طريقة عمل وكيلك. يحصل OpenCode على أدوات مباشرة (navigate وsnapshot وclick وnetwork وغيرها). بينما يحصل Claude Code وCodex وCursor وسائر العملاء على execute وstatus وtabs، حيث يشغّل execute كود JavaScript يمكنه استدعاء كل أدوات Browse. وفي الحالتين، يصل الوكيل إلى التقاط network نفسه.
الخطوة 2: بدء التقاط شبكة مُصفّى
تأخذ أداة network قيمة action من نوع start أو status أو stop أو cancel، والتقاط واحد لكل تبويب. مع start يمكنك تضييق ما يسجّله:
| الخيار | ما يفعله | الافتراضي |
|---|---|---|
urlFilter |
التقاط عناوين URL التي تحتوي هذا النص فقط | لا شيء |
resourceTypes |
التقاط هذه الأنواع فقط، مثل ["XHR", "Fetch"] |
كل الأنواع |
methods |
التقاط أساليب HTTP هذه فقط | كل الأساليب |
bodies |
التقاط هياكل الطلب والاستجابة | true |
maxDurationMs |
إنهاء الالتقاط وإ discard بعد هذه المدة | 1,800,000 (30 دقيقة) |
صفِّ على XHR وFetch، وأضف urlFilter مثل /api/ لتجاهل إشارات التحليلات. تبدو الاستدعاء هكذا:
{
"action": "start",
"tab": "<tabId>",
"resourceTypes": ["XHR", "Fetch"],
"urlFilter": "/api/"
}
لإبقاء الوكيل على موقع واحد، افتح التبويب مع allowedOrigins. يوضح README الخاص بـ Browse أن هذا يقيّد التنقّل، لا الطلبات التي يجريها الصفحة نفسها، لذا فهو ضابط احترازي وليس حدودًا للبيانات.
الخطوة 3: تنقّل في الموقع ثم أوقف الالتقاط
الآن استخدم الموقع في تبويب الوكيل: افتح قائمة، وصفِّها، واطلع على صفحة تفاصيل، وأنشئ سجلًا تجريبيًا واحذفه. إذا طلب الموقع منك تسجيل الدخول في منتصف الجلسة، يستدعي الوكيل handoff، فتكمل أنت تسجيل الدخول وتنقر «متابعة».
عند الانتهاء، يرسل الوكيل {"action": "stop"}. فيعيد كل تبادل: الأسلوب، وعنوان URL، والترويسات، والحالة، والهياكل. من المفيد معرفة الحدود:
- حتى 1,000 طلب لكل التقاط.
- هياكل JSON والنماذج وmultipart تُعاد كنص، حتى 1 ميغابايت لكل هيكل و25 ميغابايت لكل التقاط.
- الHTML والسكربتات وCSS والصور لا تُجلب أبدًا، بل يُوصف نوعها حسب MIME وحجمها فقط.
تُستبدل بيانات الاعتماد دائمًا بـ [redacted]: ترويسات authorization ومفاتيح API، وكل قيمة كوكي، وحقول الاستعلام وJSON والنماذج ذات الأسماء السرية، والمقاطع الشبيهة بالرموز (tokens) في المسار. يحذّر README من أن سرًّا مخزّنًا تحت اسم حقل عادي قد ينجو، لذا اقرأ المواصفة قبل مشاركتها.
تغيير يجب التخطيط له: أزالت الإصدار 0.0.17 (14 نوفمبر 2026) ميزة تصدير HAR، وتعيد عمليات الالتقاط الآن حركة المرور المُخفاة مباشرة. إذا احتجت ملف HAR، صدّره من DevTools واستخدم دليلنا حول استيراد ملف HAR إلى Apidog.
الخطوة 4: دع الوكيل يكتب مواصفة OpenAPI
حركة المرور الخام ليست مواصفة. الطلبات إلى /api/orders/1042 و/api/orders/877 و/api/orders/15 يجب أن تصبح مسارًا واحدًا، /api/orders/{orderId}، بمخطط استجابة واحد. الوكيل البرمجي بارع في هذا تحديدًا: اكتشاف النمط واستنتاج الأنواع من الاستجابات الحقيقية.

اطلب من الوكيل اتباع قواعد قليلة ليستورد الناتج بسلاسة:
- اكتب JSON بصيغة OpenAPI 3.x، بمسار واحد لكل أسلوب ونمط مسار.
- حوّل المعرفات الرقمية وUUID والـ slugs في عناوين URL إلى معاملات مسار.
- ابنِ المخططات تحت
components/schemasمن هياكل الاستجابة التي رآها، وضع علامة «مطلوب» على الحقل فقط إذا وُجد في كل العينات. - صرّح بمخطط المصادقة الذي يستخدمه الموقع (bearer أو cookie أو مفتاح API) تحت
securitySchemes، دون أي قيم حقيقية. - اجعل
info.titleثابتًا، لأن Apidog يستخدمه اسمًا للوحدة عند الاستيراد.
الخطوة 5: استورد المواصفة واختبرها عبر Apidog CLI
بمجرد وجود openapi.json، سلّم الباقي للوكيل نفسه. يمنحه Apidog CLI أوامر لاستيراد المواصفات، وإنشاء حالات الاختبار وتشغيلها، وكل أمر يطبع JSON منظّمًا يستطيع وكيلك قراءته.
اضبطه مرة واحدة:
npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install
ثم أعطِ وكيلك أمرًا واحدًا يغطي المهمة كاملة:
Open https://app.example.com in a Browse tab limited to app.example.com.
Start a network capture for XHR and Fetch requests whose URL contains /api/.
Hand the tab to me, wait while I use the orders pages, then stop the capture.
Write openapi.json (OpenAPI 3.1, info.title "Example Orders API") with path
parameters for IDs and schemas from the real responses. Create an AI branch in
Apidog project <projectId>, import the spec there, create a test case for
GET /api/orders/{orderId} that asserts status 200 and a numeric id, run it
against environment <envId> and summarize any failures.
يشغّل الوكيل الأوامر التالية. كل علم (flag) هنا مأخوذ من apidog <cmd> --help في Apidog CLI إصدار 2.2.12:
apidog branch create --project <projectId> --type ai \
--name "ai/20261117-from-main-orders-capture" --from main
apidog import --project <projectId> --branch "ai/20261117-from-main-orders-capture" \
--format openapi --file ./openapi.json
apidog endpoint list --project <projectId> --branch "ai/20261117-from-main-orders-capture" \
--path-contains /api/orders
apidog test-case category --project <projectId> --branch "ai/20261117-from-main-orders-capture"
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --branch "ai/20261117-from-main-orders-capture" \
--file case.json
apidog run --test-case <caseId> --project <projectId> --branch "ai/20261117-from-main-orders-capture" \
-e <envId> -r cli,json
الاستيراد إلى فرع AI يُبقي المواصفة الملتقطة بعيدًا عن تصميمك الرئيسي حتى تراجعها. وإذا أعدت الالتقاط لاحقًا واستوردت مجددًا، أبقِ info.title دون تغيير أو مرّر --module-map "<info.title>=<moduleId>"، ليحدّث Apidog نقاط النهاية في مكانها بدل إنشاء نسخة ثانية من كل واحدة.
بمجرد نجاح الاختبار، يمكن إدراج الأمر نفسه apidog run ... -r junit مباشرة في CI. يعرض دليلنا Apidog CLI CI/ guide إعداد خط الأنابيب، ويغطي Apidog CLI في Claude Code جانب الوكيل بتفصيل أكبر.
نصائح للحصول على مواصفة ملتقطة أنظف
- التقط ميزة واحدة في كل مرة. جلسة مركّزة مدتها 5 دقائق على «الطلبات» تعطي مواصفة أدق من 30 دقيقة من النقر في كل مكان.
- فعّل مسارات الأخطاء. أرسل نموذجًا غير صالح أو افتح سجلًا محذوفًا لتتضمن المواصفة استجابات 4xx، لا رموز 200 فقط.
- تحقق من الإخفاء بنفسك. ابحث في
openapi.jsonعن سلاسل نصية طويلة عشوائية قبل إضافته إلى مستودعك. - احترم شروط الموقع. التقط فقط التطبيقات التي تملكها، أو يُسمح لك بالتكامل معها، أو تختبرها بإذن.
الأسئلة الشائعة
هل OpenCode Browse مجاني؟ المستودع مرخّص بموجب MIT، وصفحة المنتج لا تذكر أي سعر. هذا كل ما يؤكده المصدر حتى 17 نوفمبر 2026، لذا تحقق من الصفحة مجددًا قبل التخطيط بناءً على التكلفة.
هل يعمل OpenCode Browse مع Claude Code أم مع OpenCode فقط؟ يعمل مع Claude Code وCodex وCursor وZed ونحو 30 عميل MCP آخر. يضبط browse install -a claude إعدادات Claude Code. يحصل OpenCode على أدوات مباشرة، بينما يحصل العملاء الآخرون على أداة execute تستدعي الأدوات نفسها من JavaScript.
هل يمكن لـ Browse تصدير ملف HAR؟ لم يعد ذلك ممكنًا. أزالت الإصدار 0.0.17 تصدير HAR، وتعيد أداة network الآن حركة المرور المُخفاة مباشرة كبيانات منظّمة. للحصول على ملف HAR، احفظ واحدًا من Chrome DevTools واستورده عبر apidog import --format har.
هل ستنتهي كوكيز جلستي أو رموز التوكن في المواصفة؟ يخفي Browse ترويسات authorization ومفاتيح API، وكل قيم الكوكيز، والحقول ذات الأسماء السرية، والمقاطع الشبيهة بالتوكن في المسار. لكن سرًّا مخزّنًا تحت اسم حقل عادي قد يظهر، لذا راجع الملف قبل مشاركته.
ما صيغة الاستيراد في Apidog التي ينبغي أن أستخدمها لناتج الوكيل؟ استخدم --format openapi للمواصفة التي يكتبها الوكيل. يقبل Apidog CLI أيضًا Postman وHAR وInsomnia وSwagger 2.0 وأكثر من 20 صيغة أخرى عبر أمر apidog import نفسه.
