حوّل زيارات الشبكة لموقعك إلى مواصفة API باستخدام OpenCode Browse

يتيح لك OpenCode Browse التقاط استدعاءات API التي يجريها الموقع أثناء تسجيل دخولك عبر وكيل البرمجة الخاص بك. إليك كيفية تحويل هذا النطاق إلى مواصفة OpenAPI واختباره باستخدام Apidog CLI، باستخدام وسيط واحد (prompt) للوكيل.

Ashley Innocent

Ashley Innocent

17 نوفمبر 2026

حوّل زيارات الشبكة لموقعك إلى مواصفة API باستخدام OpenCode Browse

Apidog للمؤسسات

النشر على الخوادم المحلية

SSO و RBAC

متوافق مع SOC 2

استكشف Apidog للمؤسسات

لتحويل حركة مرور الشبكة على موقع ما إلى مواصفة 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 فيعمل داخل الملف الشخصي الذي تستخدمه أصلًا، فيرى الوكيل نفس الطلبات المصادَق عليها التي تراها أنت. وهذا يفيد في ثلاث مهام:

الطريقة اليدوية هي تصدير HAR من DevTools؛ انظر دليلنا حول الهندسة العكسية لواجهات API. أما نسخة الوكيل فتكتب المواصفة عنك.

Pipeline diagram: a signed-in browser tab feeds a Browse network capture with credentials redacted, a coding agent writes openapi.json from it, and Apidog CLI imports the file, creates a test case and runs it

كيف تحوّل حركة مرور موقع إلى مواصفة API: 5 خطوات

  1. ثبّت Browse واربط الإضافة بمتصفحك.
  2. اطلب من وكيلك فتح الموقع في تبويب Browse وبدء التقاط network مُصفّى على XHR وFetch.
  3. تنقّل في الميزات التي تريد توثيقها، ثم اطلب من الوكيل إيقاف الالتقاط.
  4. دع الوكيل يجمع التبادلات في مسارات ويكتب openapi.json.
  5. استورد المواصفة عبر 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، والترويسات، والحالة، والهياكل. من المفيد معرفة الحدود:

تُستبدل بيانات الاعتماد دائمًا بـ [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}، بمخطط استجابة واحد. الوكيل البرمجي بارع في هذا تحديدًا: اكتشاف النمط واستنتاج الأنواع من الاستجابات الحقيقية.

Diagram showing three captured GET requests to /api/orders/1042, /api/orders/877 and /api/orders/15 with JSON bodies, grouped by pattern into one OpenAPI path GET /api/orders/{orderId} with an integer orderId parameter and an Order response schema, with the Authorization header shown as redacted

اطلب من الوكيل اتباع قواعد قليلة ليستورد الناتج بسلاسة:

الخطوة 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 جانب الوكيل بتفصيل أكبر.

نصائح للحصول على مواصفة ملتقطة أنظف

الأسئلة الشائعة

هل 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 نفسه.

ممارسة تصميم API في Apidog

اكتشف طريقة أسهل لبناء واستخدام واجهات برمجة التطبيقات