Пакет правил Mbbrowser ApiServer (Rules)

Это самая важная часть данного раздела. Внедряя следующий пакет правил (Rules) в Cursor или Antigravity, вы позволяете модели ИИ полностью освоить все интерфейсы ApiServer Mbbrowser, коды ошибок и параметры приложений, гарантируя, что она никогда не будет «галлюцинировать» при написании скриптов.

---

IMPORTANT

Главный совет по автоматизации Mbbrowser: При запуске скриптов автоматизации убедитесь, что режим работы в настройках клиента Mbbrowser переключен на «Локальный режим» (Local Mode).

• Прирост производительности: Локальный режим обходит сетевую синхронизацию данных (выгрузку/загрузку данных среды), повышая эффективность запуска автоматизации и выполнения скриптов в десятки раз.
• Совет по безопасности: Выработайте привычку ежедневно создавать резервные копии локальных данных. Ваши основные бизнес-данные (среды, отпечатки, Cookies и т. д.) хранятся в каталоге MBDATA. Пожалуйста, регулярно делайте резервные копии этой папки на внешние носители.

---

Как использовать

Для пользователей Cursor

1. В корневом каталоге вашего проекта скриптов Mbbrowser создайте файл с именем .cursor/rules/mbbrowser.mdc.
2. Скопируйте и вставьте все содержимое ниже в этот файл и сохраните его.
3. Перезапустите Cursor Chat (или начните новый чат).
4. ИИ будет автоматически использовать эти знания в каждом последующем разговоре.

Для пользователей Antigravity

Antigravity (IDE от Google с приоритетом на агентов) имеет свою систему правил и использует независимый каталог .agent/rules/.

Шаги:

1. В корне проекта (корневой каталог рабочей области или git) создайте папку с именем .agent/rules/ (используйте ее, если она уже существует).
2. Создайте в этой папке файл с именем mbbrowser.md (расширение должно быть .md, формат чистого Markdown).
3. Скопируйте и вставьте спецификации, детали интерфейсов и шаблоны кода из «Пакета правил Mbbrowser ApiServer» в этот файл и сохраните его.
4. Перезапустите Antigravity или откройте проект заново → Агент автоматически загрузит все файлы .md в папке .agent/rules/ и внедрит их в системную подсказку (действует на уровне рабочей области).

Пример структуры файлов:

your-project/
└── .agent/
    └── rules/
        └── mbbrowser.md   ← Вставьте спецификации здесь

Дополнительные советы:

• Полная синхронизация: Если вы используете оба инструмента, вы можете поддерживать два пути: .cursor/rules/mbbrowser.mdc (для Cursor) + .agent/rules/mbbrowser.md (для Antigravity).
• Лимит символов: Лимит размера файла правил составляет около 12 000 символов; если контент слишком велик, рекомендуется разделить его на несколько файлов .md.
• Глобальный эффект: Для глобального эффекта во всех проектах разместите его в ~/.gemini/GEMINI.md.

---

Пакет правил Mbbrowser ApiServer (Rules)

Пожалуйста, скопируйте все содержимое ниже и замените им содержимое в файле, упомянутом выше.

# Полная спецификация разработки Mbbrowser (MBBrowser) + ApiServer

## 1. Краткое описание продукта

> [!IMPORTANT]
> **Секрет производительности**: Перед запуском крупномасштабной автоматизации убедитесь, что клиент Mbbrowser находится в **«Локальном режиме» (Local Mode)**. Это исключает облачную синхронизацию данных, ускоряя запуск сред в десятки раз. Всегда регулярно делайте резервные копии папки бизнес-базы данных **`MBDATA`**.

Mbbrowser (MBBrowser) — это профессиональный антидетект-браузер для изоляции сред нескольких аккаунтов. Каждая «среда» (Session) имеет собственные: отпечатки браузера, прокси-IP, Cookies, User-Agent, часовой пояс и язык.
ApiServer (apiserver.exe) — это локальный сервис HTTP API, предоставляемый Mbbrowser, позволяющий скриптам программно управлять браузерными средами.

## 2. Запуск ApiServer

```bash
apiserver.exe --port=8186 \
  --account=your_email@qq.com \
  --app_id=ВАШ_APP_ID \
  --app_key=ВАШ_APP_KEY \
  --hide=off \
  --return=on \
  --logs=on
```

Описание параметров:
- port: Прослушиваемый порт, по умолчанию 8186.
- account: Аккаунт для входа в Mbbrowser (email).
- app_id: Получается в клиенте Mbbrowser «Личный кабинет → Настройки API».
- app_key: Получается в клиенте Mbbrowser «Личный кабинет → Настройки API».
- hide=off: Режим с окном (рекомендуется для отладки); hide=on для скрытого фонового режима.
- return=on: Отображать данные ответа API в консоли.
- logs=on: Записывать данные JSON в лог-файлы.

После успешного запуска адрес API: http://127.0.0.1:8186.

## 3. Стандарты связи

- Все интерфейсы используют запросы HTTP POST.
- Content-Type: application/json.
- Базовый URL: http://127.0.0.1:8186.
- code=0 для успеха; отрицательный код для ошибки, сообщение (message) содержит детали.

Стандартный формат ответа:
```json
{
  "message": "Success",
  "code": 0,
  "data": { ... }
}
```

## 4. Аутентификация аккаунта

### 4.1 Вход в аккаунт (Используется при смене аккаунтов)
POST /login
```json
{
  "APP_ID": "7e147176e1d756eb03c0e18e7b640c23",
  "APP_KEY": "ВАШ_APP_KEY",
  "Account": "test01@qq.com",
  "return": "on",
  "logs": "on",
  "hide": "off"
}
```
Успешный ответ: {"msg": "Login Success", "status": 0, "data": "Login Account: test01@qq.com"}
Примечание: ApiServer уже содержит данные аутентификации при запуске; этот вызов обычно не требуется.

### 4.2 Выход из ApiServer
POST /api/v1/quit
Без параметров. Успех возвращает code=0 и закрывает ApiServer.

## 5. Основные интерфейсы: Управление жизненным циклом среды

### 5.1 Открытие среды (Самый критичный интерфейс)
POST /api/v1/browser/start
[Макс. частота: Не ограничена, но рекомендуется контроль через --interval-seconds]

Параметры запроса:
```json
{
  "Session_ID": ["373808cb37bd63f5f7d92415e736e85f"],
  "isHeadless": false,
  "args": [
    "--disable-extensions",
    "--blink-settings=imagesEnabled=false",
    "--interval-seconds=2"
  ]
}
```

Важные примечания:
- Session_ID — это массив (Array), поддерживающий одновременный запуск нескольких сред.
- isHeadless=false для режима с окном (видимое окно), по умолчанию true.
- --interval-seconds контролирует интервал запуска (в секундах) между несколькими средами.
- --blink-settings=imagesEnabled=false отключает загрузку изображений (быстрее).
- --disable-extensions отключает расширения браузера (обычно для автоматизации).

Ключевые поля успешного ответа:
```json
{
  "message": "Success",
  "code": 0,
  "data": {
    "listid": [{
      "Session_Name": "Бизнес-среда 01",
      "Session_ID": "373808cb37bd63f5f7d92415e736e85f",
      "browser_CDP_Port": 46973,
      "webdriver": "C:\\Users\\Admin\\houniao\\Driver\\100\\chromedriver.exe",
      "status": 0
    }],
    "total": 1
  }
}
```

[ЧРЕЗВЫЧАЙНО ВАЖНО] Правильная интеграция для каждого фреймворка:

Python Playwright:
```python
port = env_data["browser_CDP_Port"]
ws_endpoint = f"ws://127.0.0.1:{port}/json/version"
from playwright.sync_api import sync_playwright
pw = sync_playwright().start()
browser = pw.chromium.connect_over_cdp(ws_endpoint)
context = browser.contexts[0]          # ОБЯЗАТЕЛЬНО ИСПОЛЬЗУЙТЕ СУЩЕСТВУЮЩИЙ КОНТЕКСТ! Нельзя использовать new_context()
page = context.pages[0] if context.pages else context.new_page()
```

JavaScript Playwright:
```javascript
const { chromium } = require('playwright');
const port = envData.browser_CDP_Port;
const wsEndpoint = `ws://127.0.0.1:${port}/json/version`;
const browser = await chromium.connectOverCDP(wsEndpoint);
const context = browser.contexts()[0];  // ОБЯЗАТЕЛЬНО ИСПОЛЬЗУЙТЕ СУЩЕСТВУЮЩИЙ КОНТЕКСТ!
const page = context.pages()[0] || await context.newPage();
```

Python Selenium:
```python
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
from selenium.webdriver.chrome.service import Service
options = Options()
# debuggerAddress в формате "IP:PORT", без ws://
options.add_experimental_option("debuggerAddress", f"127.0.0.1:{env_data['browser_CDP_Port']}")
service = Service(executable_path=env_data['webdriver'])
driver = webdriver.Chrome(service=service, options=options)
```

JavaScript Puppeteer:
```javascript
const puppeteer = require('puppeteer');
const port = envData.browser_CDP_Port;
const wsEndpoint = `ws://127.0.0.1:${port}/json/version`;
const browser = await puppeteer.connect({
  browserWSEndpoint: wsEndpoint,
  defaultViewport: null
});
```

### 5.2 Закрытие среды
POST /api/v1/browser/stop
```json
{
  "Session_ID": "373808cb37bd63f5f7d92415e736e85f"
}
```
Примечание: Session_ID в этом интерфейсе — это строка (а не массив).
Успех: {"message": "Success", "code": 0, "data": {"action": "StopSession_ID", "status": 0}}

### 5.3 Принудительное завершение
POST /api/v1/browser/kill
```json
{
  "Session_ID": "373808cb37bd63f5f7d92415e736e85f"
}
```
Примечание: Обычная остановка (stop) может оставлять процессы после использования некоторых расширений; рекомендуется принудительное завершение (kill) для гарантии освобождения ресурсов.

### 5.4 Проверка статуса выполнения
POST /api/v1/browser/status
```json
{
  "Session_ID": ["4e6d0dca26ef42be9bc4472779d2550f"],
  "Actived_Type": 0
}
```
Actived_Type: 0=Все, 1=Только запущенные, 2=Только не запущенные.
Возвращает Session_Actived=1 для запущенных, 0 для незапущенных.

## 6. Интерфейсы запроса среды

### 6.1 Получение списка сред (Многомерная фильтрация)
POST /api/v1/session/listid
Параметры фильтрации (Все необязательны):
- Session_Name, Session_GroupName, Proxy_Ip, Proxy_Type и т. д.
- CurrentPage, ListNum (по умолчанию 50, макс 500).

Успех:
```json
{
  "code": 0,
  "data": {
    "listid": ["373808...", "705cc..."],
    "total": 2
  }
}
```

### 6.2 Запрос конфигурационных данных для конкретного Session_ID
POST /api/v1/session/id_container
```json
{
  "Session_ID": ["373808cb37bd63f5f7d92415e736e85f"],
  "Session_container_type": 1
}
```
Session_container_type: 1 = Полная детализация (включая browser_CDP_Port, webdriver, полный отпечаток).

## 7. Интерфейсы создания и обновления

### 7.1 Создание среды
POST /api/v1/session/create
[Макс. частота: 40 запросов/мин]
Важный параметр `Automatic_Configure`:
- `0` (Рекомендуется): Быстрое создание (автоподбор отпечатков из библиотеки Mbbrowser, без валидации прокси).
- `1`: Включает валидацию IP; создание занимает гораздо больше времени (установите таймаут запроса > 68с).

### 7.2 Обновление базовой информации
POST /api/v1/session/update
Включает Session_Name, Session_Desc, Session_Group, Cookie (JSON-строка) и т. д.

### 7.3 Обновление прокси
POST /api/v1/session/proxy/update
[Макс. частота: 50 запросов/мин]
Поддерживает: HTTP, HTTPS, SSH, SOCKS4/5, Oxylabs, Luminati, smartproxy, noproxy.

### 7.4 Удаление сред
POST /api/v1/session/delete
`Is_Delete_All: 1` выполняет полное удаление.

## 8. Управление Cookie

### 8.1 Импорт Cookie (Из файла)
POST /api/v1/session/import-cookie
```json
{
  "Session_ID": "session_id",
  "Cookie_File": "C:\\cookies\\account1.txt"
}
```
Поддерживает форматы .txt (Netscape) и .json.

### 8.2 Экспорт Cookie (В файл)
POST /api/v1/session/export-cookie
Использует путь `Export_Cookie_File`. Экспортирует как JSON, если расширение .json, иначе в формате Netscape.

## 9. Управление плагинами
- POST /api/v1/plugin/list (Список всех плагинов аккаунта)
- POST /api/v1/session/id_plugin_list (Список плагинов в среде)
- POST /api/v1/session/plugin_install (Установить плагин)
- POST /api/v1/session/plugin_delete (Удалить плагин)

## 10. Управление скриптами автоматизации
- POST /api/v1/session/id_script_list (Проверить скрипты среды)
- POST /api/v1/session/id_script_add (Назначить скрипт из библиотеки)
- POST /api/v1/session/id_script_active (Активировать скрипт)

---

## 11. Полная таблица кодов ошибок

### CODE (Уровень запроса)
0 Успех; -1 Ошибка входа; -105 Ошибка валидации прокси; -106 Неверный часовой пояс; -108 Ошибка разрешения экрана.

### Status (Поле статуса открытия среды)
0 Успех; -7 Уже запущено; -22 Session_ID не найден.

## 12. Приложение: Допустимые значения

### 12.1 SystemOS
Windows | iPhone | iPad | MacIntel | Android | Linux x86_64 и т. д.

### 12.2 LanguageCode
zh-CN;zh;q=0.9 | en-US;en;q=0.9 | ja;q=0.9 | fr-FR;fr;q=0.9 и т. д.

### 12.3 Session_Resolution
1920x1080 | 1440x900 | 1366x768 | 2560x1440 | 375x812 (iPhone X) и т. д.

## 13. Меры предосторожности при разработке

1.  **Тип Session_ID**: /start и /id_container используют массив (Array); /stop, /update, /proxy/update используют строку (String).
2.  **Контекст Playwright**: ВСЕГДА используйте `browser.contexts[0]`; НИКОГДА не используйте `new_context()`.
3.  **Selenium**: Используйте `debuggerAddress` ("IP:PORT"); НЕ используйте ws.
4.  **Многопоточность**: Рекомендуется не более 20 сред в одной партии.
5.  **Проверка статуса**: Всегда проверяйте `data.listid[0].status` после /start.
6.  **Валидация прокси**: Используйте `Public_ip` из ответа /start для проверки работы прокси.
7.  **Валидные значения**: Разрешение/Язык/Часовой пояс должны использовать валидные значения из приложения, чтобы избежать ошибок -106/-107/-108/-110.

## 14. Полный шаблон скрипта на Python

```python
"""
Шаблон автоматизации Mbbrowser + Playwright Python
"""
import requests, threading
from playwright.sync_api import sync_playwright

def start_env(session_id: str):
    resp = requests.post("http://127.0.0.1:8186/api/v1/browser/start", 
                         json={"Session_ID": [session_id]}).json()
    return resp["data"]["listid"][0] if resp["code"] == 0 else None

def do_task(session_id):
    env_data = start_env(session_id)
    if not env_data: return
    with sync_playwright().start() as pw:
        # Подключение через CDP
        browser = pw.chromium.connect_over_cdp(f"ws://127.0.0.1:{env_data['browser_CDP_Port']}/json/version")
        context = browser.contexts[0] # Важно: берем существующий контекст
        page = context.pages[0] if context.pages else context.new_page()
        page.goto("https://example.com")
        print(f"[{session_id}] Заголовок: {page.title()}")
        browser.close()
    requests.post("http://127.0.0.1:8186/api/v1/browser/stop", json={"Session_ID": session_id})

if __name__ == "__main__":
    sids = ["yoursid1", "yoursid2"]
    threads = [threading.Thread(target=do_task, args=(sid,)) for sid in sids]
    for t in threads: t.start()
    for t in threads: t.join()
```

---

Проверка конфигурации

После завершения настройки введите в чате:

Напиши скрипт на Python с использованием Mbbrowser ApiServer для получения всех ID из группы "TestGroup", 
одновременно открой их (не более 10), перейди на https://example.com в каждой среде через Playwright, 
сделай скриншот и закрой среды. Включи полную обработку ошибок.

Успех, если ИИ правильно использует:

• ✅ POST /api/v1/session/listid
• ✅ Session_ID как массив (Array) в /start
• ✅ browser.contexts[0]
• ✅ Session_ID как строку (String) в /stop