Команды-расширения Vibium: Пользовательские расширения протокола BiDi

Updated Jul 2026

Как WebDriver BiDi поддерживает расширения

Спецификация WebDriver BiDi явно допускает определение пользовательских команд реализациями:

"An implementation may define extension modules. These must have a module name that contains a single colon ':' character."

Vibium определяет три команды-расширения, которые обрабатываются бинарником Go (clicker), а не пересылаются в Chrome:

Поток сообщений

Стандартная команда BiDi (проход насквозь)

Client                      Clicker Proxy                      Chrome
  │                               │                               │
  │── browsingContext.navigate ──►│                               │
  │                               │── browsingContext.navigate ──►│
  │                               │◄── success ───────────────────│
  │◄── success ───────────────────│                               │

Стандартные BiDi-команды проходят через прокси напрямую.

Команда-расширение Vibium (перехват)

Client                    Clicker Proxy                   Chrome
  │                           │                              │
  │── vibium:click ──────────►│                              │
  │                           │                              │
  │                           │  ┌─ ЦИКЛ ИНТЕРАКТИВНОСТИ ─┐  │
  │                           │  │                       │   │
  │                           │──│─ script.callFunction ─│──►│  (проверка visible)
  │                           │◄─│─ result ──────────────│───│
  │                           │──│─ script.callFunction ─│──►│  (проверка stable T1)
  │                           │◄─│─ result ──────────────│───│
  │                           │  │  sleep 50ms           │   │
  │                           │──│─ script.callFunction ─│──►│  (проверка stable T2)
  │                           │◄─│─ result ──────────────│───│
  │                           │──│─ script.callFunction ─│──►│  (receivesEvents)
  │                           │◄─│─ result ──────────────│───│
  │                           │──│─ script.callFunction ─│──►│  (enabled)
  │                           │◄─│─ result ──────────────│───│
  │                           │  └───────────────────────┘   │
  │                           │                              │
  │                           │── input.performActions ─────►│  (фактический клик)
  │                           │◄── success ──────────────────│
  │                           │                              │
  │◄── success ───────────────│                              │

Прокси перехватывает команды vibium:*, выполняет множество BiDi-подкоманд к Chrome и возвращает клиенту единственный ответ — успех или ошибку.

Детали реализации

Формат запроса

{
  "id": 1,
  "method": "vibium:click",
  "params": {
    "context": "browsing-context-id-123",
    "selector": "button.submit",
    "timeout": 30000
  }
}

Ответ об успехе

{
  "id": 1,
  "type": "success",
  "result": {
    "clicked": true
  }
}

Ответ об ошибке (тайм-аут)

{
  "id": 1,
  "type": "error",
  "error": {
    "error": "timeout",
    "message": "timeout after 30s waiting for 'button.submit': check 'ReceivesEvents' failed — obscured by div.modal-overlay"
  }
}

Расположение кода в репозитории

Клиентская сторона (отправка команд):

• clients/javascript/src/vibe.ts#L69 — client.send('vibium:find', { ... })

Серверная сторона (обработка команд):

• clicker/internal/proxy/router.go#L150 — Router направляет vibium:find в обработчик
• clicker/internal/proxy/router.go#L303 — Реализация handleVibiumFind()

Паттерн Router

// Упрощено из router.go
func (r *Router) OnClientMessage(msg []byte) {
    var req struct {
        Method string `json:"method"`
        // ...
    }
    json.Unmarshal(msg, &req)

    switch req.Method {
    case "vibium:find":
        r.handleVibiumFind(req)
    case "vibium:click":
        r.handleVibiumClick(req)
    case "vibium:type":
        r.handleVibiumType(req)
    default:
        // Стандартная BiDi-команда — перенаправить в Chrome
        r.forwardToChrome(msg)
    }
}

Добавление собственной команды-расширения

Если вам нужна пользовательская команда (например, vibium:drag):

1. Клиент отправляет {"method": "vibium:drag", "params": {...}}
2. Добавить case в switch OnClientMessage в router.go
3. Реализовать обработчик, использующий стандартные BiDi-команды внутри
4. Вызвать sendSuccess() или sendError() для ответа

Почему эта архитектура важна

Для клиентов: Простота

Реализация клика в JavaScript-клиенте тривиальна:

async click(options?: { timeout?: number }): Promise<void> {
  await this.client.send('vibium:click', {
    context: this.context,
    selector: this.selector,
    timeout: options?.timeout,
  });
}

Никаких циклов повторов, никаких проверок интерактивности, никакого сложного управления состоянием. Просто отправить команду и ждать.

Для CLI: Та же простота

Когда вы запускаете vibe-check click "button", CLI:

1. Подключается к WebSocket daemon
2. Отправляет vibium:click с селектором
3. Ждёт успеха или ошибки
4. Выводит результат и завершается

CLI — просто ещё один BiDi-клиент.

Для навыка: Максимальная эффективность токенов

Агент запускает Bash("vibe-check click 'button'") и получает обратно:

• Код выхода 0 + минимальный вывод (успех)
• Код выхода 1 + описательная ошибка (неудача)

Никаких накладных расходов на JSON-схемы. Никаких деревьев доступности. Просто shell-команда и её вывод.

Сравнение с подходом Playwright

Подход Vibium более согласован с веб-стандартами. По мере созревания BiDi и его нативной реализации в большем количестве браузеров расширения протокола Vibium потенциально могут быть стандартизованы.

Тезис для собеседования

«Vibium расширяет протокол WebDriver BiDi пользовательскими командами — vibium:find, vibium:click, vibium:type — используя официальный механизм расширений спецификации. Бинарник Go выступает как BiDi-прокси: стандартные команды проходят насквозь к Chrome, а команды vibium:* перехватываются и обрабатываются на стороне сервера. Одна команда vibium:click на уровне протокола запускает многошаговый цикл проверки интерактивности — пять проверок в цикле опроса, затем фактический клик через BiDi input.performActions. Это означает, что клиенты отправляют одно сообщение и получают один ответ, со всей сложностью, скрытой в прокси. Это чёткое разделение ответственности: протокол обеспечивает транспорт, прокси обеспечивает интеллект, клиент обеспечивает UX.»