Поддерживаемые возможности платформы

• Входящие события: Внешняя система POST-запрос к callback_path → преобразуется в событие OneBot12 (прозрачный проход json/text-сегментов)
• Исходящие события: Модуль Send → POST-запрос к outgoing_url (двойной мост)
• API: Мост с информацией об идентификации и статусе выполнения (минимальный набор)

Обновление парадигмы v5 (4.2.0)

• Минимальный набор DSL API: get_self_info/get_status/get_version/get_supported_actions
• Мягкая зависимость от фреймворка: При запуске проверяется наличие ErisPulse>=2.7.1 и выводится предупреждение; в логе выводится версия
• Обновлен путь импорта до Core.Bases

Описание функциональных возможностей платформы — универсальный адаптер-мост Webhook

В этом документе подробно описаны двунаправленный протокол моста, сопоставление полей и особенности реализации Webhook-адаптера.

Обзор

Webhook-адаптер является протокольным мостом, не привязанным к какой-либо конкретной платформе. Он отправляет и получает сообщения через HTTP, позволяя любому системе, способной инициировать HTTP-запросы, подключиться к ErisPulse.

Направление входящих событий            Направление исходящих событий
────────                                ────────
Внешняя система                        Модуль ErisPulse
   │                                       │
   │ POST JSON                             │ Send.Text(...)
   ▼                                       ▼
┌──────────────────────────────────────────────────┐
│              WebhookAdapter                       │
│  ┌──────────────────┐   ┌──────────────────┐    │
│  │ Входящие маршруты │   │ Передача исходящих │    │
│  │ GET  (проверка здоровья) │   │ client.post()    │    │
│  │ POST (прием событий) │   │ → outgoing_url   │    │
│  └────────┬─────────┘   └────────▲─────────┘    │
│           │                      │               │
│           ▼                      │               │
│  ┌──────────────────┐   ┌──────────────────┐    │
│  │ WebhookConverter │   │ Класс Send        │    │
│  │ JSON → OneBot12  │   │ Сегменты сообщений → JSON │    │
│  └────────┬─────────┘   └────────▲─────────┘    │
└───────────┼──────────────────────┼───────────────┘
            ▼                      │
     adapter.emit(event)    call_api("send_message")
            │                      │
            ▼                      │
       Система событий ErisPulse ◄────────┘

Модель нескольких аккаунтов

Каждый аккаунт представляет собой независимую конфигурацию моста, не влияющую друг на друга:

При запуске каждый аккаунт регистрирует маршруты и отдельно отправляет событие connect.

Входящий протокол

1. Проверка здоровья (GET)

• Путь: {callback_path}
• Метод: GET
• Аутентификация: отсутствует
• Ответ:

{"status": "ok", "account": "default"}

2. Прием событий (POST)

• Путь: {callback_path}
• Метод: POST
• Content-Type: application/json
• Аутентификация (при наличии секрета): Заголовок X-Webhook-Secret или параметр запроса ?secret=

Тело запроса

{
  "user_id": "u123",
  "user_nickname": "用户名",
  "group_id": "群组ID（仅群组会话）",
  "detail_type": "private",
  "message": [
    {"type": "text", "data": {"text": "消息内容"}}
  ],
  "raw": {}
}

Ответ

{"status": "ok"}

Ошибочные ответы с HTTP-статусом:

3. Сопоставление полей (входящий JSON → событие OneBot12)

Исходящий протокол

1. Отправка сообщений

При вызове методов модуля Send.To(...).Text(...) и т.д. адаптер отправляет POST-запрос на outgoing_url:

• Метод: POST
• Content-Type: application/json
• Заголовок аутентификации (при наличии секрета): X-Webhook-Secret: {secret}

Тело запроса

{
  "target_type": "private",
  "target_id": "target_user_id",
  "account": "default",
  "message": [
    {"type": "text", "data": {"text": "消息内容"}}
  ],
  "timestamp": 1700000000
}

2. Стандартизация ответа

Адаптер преобразует ответ от цели в стандартный формат ErisPulse:

{
  "status": "ok",
  "retcode": 0,
  "data": {"message_id": "...", ...},
  "message_id": "...",
  "message": "",
  "webhook_raw": {}
}

Из JSON-ответа цели извлекается message_id. Если message_id не возвращается, значение будет пустой строкой.

При ошибке запроса возвращается ответ с status: "failed", retcode: 33001.

Методы Send

Модификаторы At / AtAll / Reply предоставляются базовым классом фреймворка и объединяются в сегменты сообщения через _apply_modifiers.

Расширенные методы события (WebhookEventMixin)

Матрица функциональных возможностей

Примечания

1. Односторонняя отправка: Если outgoing_url оставлен пустым, аккаунт будет принимать только входящие события, попытка отправки сообщения вернет ошибку
2. Безопасность секрета: secret хранится в конфигурации в зашифрованном виде (metadata secret), рекомендуется использовать HTTPS при передаче
3. Уникальность пути: callback_path для нескольких аккаунтов должен быть уникальным, чтобы избежать конфликтов маршрутов
4. Идемпотентность: Адаптер не гарантирует уникальность входящих событий, внешняя система должна самостоятельно обрабатывать повторные запросы
5. Таймаут: Исходящие запросы используют встроенный клиент ErisPulse и наследуют глобальные настройки таймаута