ErisPulse ErisPulse
Открыть интерактивную версию →
Разделы страницы
Статическое зеркало — интерактивная версия является основной Открыть интерактивную версию →

Документация ErisPulse

ErisPulse — это фреймворк асинхронного модульного робота, основанный на событиях — бизнес-код пишется один раз, а через адаптеры разворачивается на QQ, Telegram, Kook, Yunhu и других платформах. Система плагинов, горячая перезагрузка и полноценный инструментарий разработчика предоставляются из коробки.

Впервые используете? Просто посмотрите 5-минутное руководство — от установки до запуска первого робота, шаг за шагом.


Выберите свой путь

Выберите учебный путь в зависимости от ваших целей. Внутри каждого пути темы расположены от простого к сложному.

[!IMPORTANT] Не нужно читать все документы. Большинству разработчиков достаточно прочитать пять основных статей уровня L1 (около 1–2 часов), чтобы самостоятельно разрабатывать 90% функциональности; остальные документы — это справочная информация по конкретным сценариям — читайте по мере необходимости. В начале каждой статьи указано, когда нужно читать эту статью.

Пять основных статей уровня L1: Введение в разработку модулей → Основные понятия → Обёртка событий → Описание файла конфигурации → Обработка исключений

Авторам адаптеров дополнительно: Введение в разработку адаптеров → Конвертер событий → Подробное руководство по SendDSL

1. Я хочу использовать робота

Запустите робота, установите модули, настройте.

Стадия Документ Описание
① Основы 5-минутное руководство Установка, инициализация, запуск — единственный входной путь
Прямая установка Клиент ErisPulse-App Официальный клиент для всех платформ: графический интерфейс на телефоне / компьютере для запуска и управления без терминала
② Глубже Создание первого робота Написание первого обработчика команд
③ Понятия Основные понятия Понимание архитектуры адаптера / модуля / событий
④ Практика Примеры распространённых задач Хранение данных, планирование задач, управление правами
Справочник Описание файла конфигурации · Команды CLI · Руководство по развертыванию Читайте по мере необходимости
Справочник Руководство по особенностям платформ Различия между платформами (Yunhu / QQ / Telegram и др.)
Выбор Руководство по выбору Сравнение и миграция с NoneBot2 / AstrBot / LangBot

2. Я хочу разработать модуль / адаптер

Разработка расширений для ErisPulse, которые можно распространять.

Тип Введение Дополнительно
Разработка модулей (рекомендуется) Введение в разработку модулей Основные понятия · Обёртка событий · Лучшие практики
Разработка адаптеров Введение в разработку адаптеров Основные понятия · Подробное руководство по SendDSL · Конвертер событий · Лучшие практики
Технические стандарты Обзор стандартов Стандарты, которые адаптеры обязаны соблюдать: Типы сессий · Конвертация событий · Методы отправки · Ответы API · Действия запроса
Тестирование и отладка Тестирование модулей (ErisPulse-Testing) Решение проблем с цепочкой распределения: почему команда не срабатывает
Публикация Публикация и магазин модулей Публикация на PyPI и в магазин модулей

3. Я хочу глубже понять принципы работы

Понимание внутренней работы фреймворка. Сначала ознакомьтесь с архитектурой и API-справочником, затем переходите к специализированным темам по таблице.

Архитектура и API-справочник

Документ Описание
Обзор архитектуры Визуальные диаграммы: основная архитектура, процесс инициализации, обработка событий, жизненный цикл, стратегия загрузки модулей (включая ленивую активацию по событиям activate_on), локальные папки плагинов и архитектура горячей перезагрузки модулей (поддержка всех источников модулей)
Система событий Полный API для пяти основных типов событий
Система адаптеров Регистрация, запуск, остановка адаптеров, вызов API
Основные модули Базовые возможности Storage / Config / Logger / Router и др.

L2 обязательные статьи (необходимо для написания продакшн-модулей)

Документ Описание
Области видимости (scope) Трёхмерный контроль доступа: доступность модуля / допуск событий / ограничение исходящих действий (включая тонкие правила на уровне методов, наследование и слияние)
Система принадлежности (owner) Принадлежность ресурсов и автоматическая очистка: контекст owner, карта принадлежности ресурсов, последовательность очистки при выгрузке, границы проектирования и руководство для авторов модулей
Управление жизненным циклом Система событий жизненного цикла: что делать при загрузке, выгрузке, перезагрузке, отключении модуля / адаптера
Система интерактивных сессий Подробное объяснение wait_reply, таймеры сессий (remind/escalate), многоканальное ожидание (select), взаимоисключающие сессии, почтовый ящик, транзакции сообщений, трассировка цепочки

Группировка по сценариям (читайте по мере необходимости)

Группа Документ Проблемы, которые могут возникнуть, если не понимать первую статью
Запуск и управление Процесс запуска и ручное управление · Ленивая загрузка Не понимание цепочки запуска (Finder / Loader / Manager / Router), модуль может не загрузиться, и разработчик будет смотреть в логи, ничего не понимая
Коммуникация Взаимодействие между модулями · Пул подключений и бродкаст · Система маршрутизации Не понимание белого списка сервисов (meta.services), вызовы module.call между модулями будут отклоняться ошибкой ServiceNotProvidedError без объяснения
Хранение данных Хранилища данных · SQL-строитель · Сетевые клиенты Не понимание семантики кулдауна при сбоях подключения, при джиттере базы данных можно ошибочно решить, что фреймворк "сломался" (на самом деле операции с хранилищем быстро завершаются с ошибкой, а затем автоматически переподключаются)
Диалоги Многошаговые диалоги (Conversation) · Почтовый ящик сессий · MessageBuilder · Международизация Не понимание взаимоисключающих сессий, два модуля могут пересекать друг друга при ожидании ответа одного и того же пользователя
Производительность Бенчмарки и оптимизация производительности Не проверяя бенчмарки перед развертыванием, планирование мощности будет основано на догадках; не сравнивая результаты после обновления, невозможно обнаружить падение производительности
Серый деплой Серый модуль и серый деплой Не понимание пяти уровней изоляции, ранняя активация серого модуля приведёт к тому, что исходящие сообщения серого модуля попадут к реальным пользователям

Таблица отношений между подсистемами

Когда неясно, какая подсистема отвечает за что, смотрите в эту таблицу:

Подсистема Отвечает на вопрос Односложный мемориал
Коммуникация (module-communication) Как модули могут вызывать друг друга, как отправлять события в определённый модуль? Для взаимодействия между модулями используйте module.call; если другой модуль объявил meta.services, можно вызывать только методы из белого списка
Права доступа (scope) Кто может использовать этот модуль, кто может запускать события, какие действия можно выполнять? Три шлагбаума — привязка модуля, допуск по идентичности, ограничение исходящих действий, всё определяется конфигурацией пользователя
Принадлежность (ownership) Что происходит с подключениями, таймерами, подписками после выгрузки модуля? Всё, что зарегистрировано, принадлежит, при выгрузке всё автоматически очищается, без висящих ресурсов
Ленивая загрузка и сон (lazy-loading) Когда модуль загружается, и куда он уходит в состоянии бездействия? activate_on — модуль активируется при необходимости, dormant_after — модуль уходит в спящий режим при бездействии
Интерактивность (interaction) Как ожидать следующего ответа пользователя, как писать многошаговые сборы? wait_reply — ожидание одного сообщения, .got() — цепочка сбора нескольких сообщений, сессионные аренды гарантируют отсутствие конфликтов
Серый деплой (shadow) Как можно протестировать новый модуль, не влияя на рабочую версию? Серый модуль получает копии данных, исходящие сообщения записываются, но не отправляются реальным пользователям, promote — активация по решению человека
Хранилище (storage-backends) Где хранятся данные, как можно менять хранилище? Один и тот же API хранения, переключение между sqlite / mysql / postgres производится через конфигурацию

4. Экосистема и официальный клиент

Официальный клиент + модули экосистемы, устанавливаемые по требованию и готовые к использованию (ни один из них не входит в состав фреймворка).

Документ Описание
Обзор экосистемы Как устанавливать модули экосистемы, почему они не входят в состав фреймворка
ErisPulse-QvQChat Общий модуль для интеллектуальных агентов: цикл инструментов / MCP / долгосрочная память / база знаний, модули, объявляющие сервисы, автоматически становятся инструментами для ИИ
ErisPulse-ApiMCP Открытие робота в качестве инструмента MCP, чтобы клиенты ИИ, такие как Claude, могли управлять им напрямую
ErisPulse-App Официальный клиент для всех платформ (Android / Windows / Linux / macOS): нативный интерфейс для управления несколькими экземплярами, можно запускать прямо с телефона, в трее на рабочем столе
ErisPulse-Dashboard Веб-панель управления + API регистрации виджетов (модули могут регистрировать собственные страницы в боковой панели)
ErisPulse-Cron Модуль планирования задач: однократные / периодические / Cron-выражения, передача параметров в обратный вызов, SQLite для сохранения, другие модули могут делегировать обратные вызовы
ErisPulse-Takumi Рендеринг изображений (HTML / дерево узлов / SVG / анимация, встроенные шрифты на китайском и английском языках)

5. Я хочу внести вклад в ErisPulse

Сделать фреймворк лучше

Документ Описание
Вклад в ErisPulse Обзор способов вклада: документация / i18n / баги / модули / адаптеры
Первый вклад От форка до отправки PR

Таблица быстрого доступа к продвинутым функциям по версиям

При необходимости определить, какая версия поддерживает определённую функцию, или при переходе на проект, написанный на старой версии, смотрите в эту таблицу (по записям в CHANGELOG.md).

Версия Введённые возможности
2.7 База для продакшна: стандартизированный базовый класс OneBot12 (ApiDSL / BaseConverter), систематизированная горячая перезагрузка конфигурации, грациозное завершение и обработка сигналов SIGTERM/SIGHUP, переопределение конфигурации через переменные окружения, обратные вызовы жизненного цикла, ленивая загрузка Web-стека; в 2.7.1 исправлена надёжность записи конфигурации и управление GC-поколениями
2.8 Основа для прав и коммуникации: трёхмерная система областей видимости (scope), инфраструктура интерактивных сессий (аренда / контрольные точки / транзакции сообщений / почтовый ящик transcript), протокол RPC между модулями (сервисный контракт meta.services / module.call / направленные события emit(to=)), многоадаптерное асинхронное хранилище (sqlite / mysql / postgres, сбой подключения не блокирует фреймворк), очистка принадлежности, сохранение комментариев в конфигурации; последующие версии 2.8 улучшают CLI, скелеты, подкоманды и т.д.
2.9 Основная линия "опыта разработки модулей" (EPRFC-2026-001): декларативные параметры команд (args= / options=) и управление командами (cooldown= / rate_limit=), единая система внедрения зависимостей (Depends), право отклонения событий промежуточными обработчиками, встроенный ORM (автомиграции + отношения), серый модуль и серый деплой, трассировка и диагностика цепочки распределения, официальная поддержка Python 3.14
2.10 Подключение как первого класса ресурса (регистратор connections: бродкаст / деление на группы / передача и повторное использование между модулями / автоматическая очистка при выгрузке), корневой импортный контракт (все основные API можно импортировать через from ErisPulse import), завершение системы принадлежности, политика хранения почтового ящика может быть переопределена во время выполнения; 2.10.2 адаптер локальной папки плагинов (plugins/) + epsdk create pack + tomlclass для без потерь записи конфигурации
2.11 (dev) Замкнутый цикл "изменение кода → просмотр эффекта": горячая перезагрузка с полным семантическим обновлением (предварительная проверка синтаксиса + проверка идентичности кода + перезагрузка зависимостей), ленивая загрузка и сон (dormant_after), горячая перезагрузка кода адаптера (sdk.adapter.reload), синтаксический сахар .got() для командных потоков, epsdk stop / restart для управления во время выполнения
2.12 (dev) Управление жизненным циклом и удобство обслуживания: вложенные жизненные циклы (ownership.nest()), тонкая горячая перезагрузка (определение по одному модулю / адаптеру, изменения в исходном коде фреймворка требуют перезапуска процесса), очередь задач для фоновых операций, автоматическая привязка контекста событий (send_context / api_context / request_context на одном уровне, модули с несколькими аккаунтами без изменений), связь повторных обработок между аккаунтами (framework.cross_account_policy),摄取 и постоянное превращение серого модуля whl, внутренний смягчённый перезапуск epsdk restart в контейнере, SendDSL.Location()

Способы разработки

ErisPulse поддерживает два способа разработки:

  • Разработка модулей (рекомендуется): создание отдельного пакета модуля, установка через менеджер пакетов, удобно для распространения и управления.
  • Встраиваемая разработка: непосредственное написание обработчиков в проекте, подходит для быстрой разработки прототипа. Подробнее см. 5-минутное руководство.

Прочее

Получить помощь

  • GitHub-репозиторий: https://github.com/ErisPulse/ErisPulse
  • Сообщение об ошибке: создать Issue
  • Техническое обсуждение: посмотреть Discussions

Связанные ссылки