Документация 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-минутное руководство.
Прочее
- Руководство по стилю документации — правила написания при вкладе в документацию
- Вклад в ErisPulse — вход в проект для совместной работы
- Поддержка разработки с помощью ИИ — получение подсказок для ИИ-ассистентов программирования
Получить помощь
- GitHub-репозиторий: https://github.com/ErisPulse/ErisPulse
- Сообщение об ошибке: создать Issue
- Техническое обсуждение: посмотреть Discussions