Проектирование каналов

Внешние интеграции с мессенджерами для Qwen Code — взаимодействие с агентом через Telegram, WeChat и другие платформы.

Документация для пользователей: Обзор каналов.

Обзор

Канал соединяет внешнюю платформу обмена сообщениями с агентом Qwen Code. Настраивается в settings.json, управляется через подкоманды qwen channel, поддерживает многопользовательский режим (каждый пользователь получает изолированную ACP-сессию).

Архитектура


┌──────────┐                        ┌─────────────────────────────────────┐
│ Telegram │    Platform API        │        Channel Service              │
│ User A   │◄──────────────────────►│                                     │
├──────────┤  (WebSocket/polling)   │  ┌───────────┐    ┌──────────────┐  │
│ WeChat   │◄──────────────────────►│  │ Platform   │    │  ACP Bridge  │  │
│ User B   │                        │  │ Adapter    │    │  (shared)    │  │
└──────────┘                        │  │            │    │              │  │
                                    │  │ - connect  │    │  - spawns    │  │
                                    │  │ - receive  │    │    qwen-code │  │
                                    │  │ - send     │    │  - manages   │  │
                                    │  │            │    │    sessions  │  │
                                    │  └─────┬──────┘    └──────┬───────┘  │
                                    │        │                  │          │
                                    │        ▼                  ▼          │
                                    │  ┌─────────────────────────────────┐ │
                                    │  │  SenderGate · GroupGate         │ │
                                    │  │  SessionRouter · ChannelBase    │ │
                                    │  └─────────────────────────────────┘ │
                                    └─────────────────────────────────────┘
                                                     │
                                                     │ stdio (ACP ndjson)
                                                     ▼
                                    ┌─────────────────────────────────────┐
                                    │        qwen-code --acp              │
                                    │   Session A (user alice, id: "abc") │
                                    │   Session B (user bob,   id: "def") │
                                    └─────────────────────────────────────┘

Platform Adapter — подключается к внешнему API, преобразует сообщения в формат Envelope и обратно. ACP Bridge — запускает qwen-code --acp, управляет сессиями, генерирует события textChunk/toolCall/disconnected. Session Router — сопоставляет отправителей с ACP-сессиями через ключи с пространством имён (<channel>:<sender>). Sender Gate / Group Gate — контроль доступа (allowlist / pairing / open) и фильтрация упоминаний. Channel Base — абстрактный базовый класс, реализующий шаблонный метод (Template Method): плагины переопределяют connect, sendMessage, disconnect. Channel Registry — Map<string, ChannelPlugin> с проверкой на коллизии.

Envelope

Нормализованный формат сообщений, к которому приводятся данные со всех платформ:

Идентификация: senderId, senderName, chatId, channelName
Содержимое: text, опционально imageBase64/imageMimeType, опционально referencedText
Контекст: isGroup, isMentioned, isReplyToBot, опционально threadId

Обязанности плагина: senderId должен быть стабильным и уникальным; chatId должен различать личные сообщения и группы; логические флаги должны быть точными для работы гейтов; @упоминания удаляются из text.

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


Inbound:  User message → Adapter → GroupGate → SenderGate → Slash commands → SessionRouter → AcpBridge → Agent
Outbound: Agent response → AcpBridge → SessionRouter → Adapter → User

Слеш-команды (/clear, /help, /status) обрабатываются в ChannelBase до передачи агенту.

Сессии

Один процесс qwen-code --acp с несколькими ACP-сессиями. Область видимости на канал: user (по умолчанию), thread или single. Ключи маршрутизации используют пространство имён в формате <channelName>:<key>.

Обработка ошибок

Сбои подключения — логируются; сервис продолжает работу, если подключён хотя бы один канал
Падения Bridge — экспоненциальная задержка (макс. 3 попытки), вызов setBridge() для всех каналов, восстановление сессий
Сериализация сессий — цепочки промисов для каждой сессии предотвращают коллизии одновременных запросов

Система плагинов

Архитектура расширяема: новые адаптеры (в том числе сторонние) можно добавлять без изменения ядра. Встроенные каналы используют тот же интерфейс плагинов (dogfooding).

Контракт плагина

Плагин ChannelPlugin объявляет channelType, displayName, requiredConfigFields и фабрику createChannel(). Плагины реализуют три метода:

Метод	Ответственность
`connect()`	Подключение к платформе и регистрация обработчиков сообщений
`sendMessage(chatId, text)`	Форматирование и отправка ответа агента
`disconnect()`	Очистка ресурсов при завершении работы

При получении входящих сообщений плагины формируют Envelope и вызывают this.handleInbound(envelope) — базовый класс обрабатывает остальное: контроль доступа, фильтрацию групп, сопряжение (pairing), маршрутизацию сессий, сериализацию запросов, слеш-команды, внедрение инструкций, контекст ответа и восстановление после сбоев.

Точки расширения

Пользовательские слеш-команды через registerCommand()
Индикаторы активности через обёртку handleInbound() с отображением статуса набора текста/реакций
Хуки вызова инструментов через onToolCall()
Обработка медиапутём прикрепления к Envelope перед вызовом handleInbound()

Обнаружение и загрузка

Внешние плагины представляют собой расширения, управляемые ExtensionManager, и объявляются в qwen-extension.json:


{
  "name": "my-channel-extension",
  "version": "1.0.0",
  "channels": {
    "my-platform": {
      "entry": "dist/index.js",
      "displayName": "My Platform Channel"
    }
  }
}

Последовательность загрузки при qwen channel start: загрузка настроек → регистрация встроенных → сканирование расширений → динамический импорт + валидация → регистрация (отклонение коллизий) → валидация конфигурации → createChannel() → connect().

Плагины выполняются в том же процессе (без песочницы), модель доверия аналогична npm-зависимостям.

Конфигурация


{
  "channels": {
    "my-telegram": {
      "type": "telegram",
      "token": "$TELEGRAM_BOT_TOKEN", // ссылка на переменную окружения
      "senderPolicy": "allowlist", // allowlist | pairing | open
      "allowedUsers": ["123456"],
      "sessionScope": "user", // user | thread | single
      "cwd": "/path/to/project",
      "model": "qwen3.5-plus",
      "instructions": "Keep responses short.",
      "groupPolicy": "disabled", // disabled | allowlist | open
      "groups": { "*": { "requireMention": true } },
    },
  },
}

Аутентификация зависит от плагина: статический токен (Telegram), учётные данные приложения (DingTalk), вход по QR-коду (WeChat), прокси-токен (TMCP).

CLI-команды


# Каналы
qwen channel start [name]                     # запуск всех или одного канала
qwen channel stop                             # остановка работающего сервиса
qwen channel status                           # отображение каналов, сессий и времени работы
qwen channel pairing list <ch>                # ожидающие запросы на сопряжение
qwen channel pairing approve <ch> <code>      # подтверждение запроса
 
# Расширения
qwen extensions install <path-or-package>     # установка
qwen extensions link <local-path>             # создание симлинка для разработки
qwen extensions list                          # отображение установленных
qwen extensions remove <name>                 # удаление

Структура пакета


packages/channels/
├── base/                    # @qwen-code/channel-base
│   └── src/
│       ├── AcpBridge.ts     # жизненный цикл процесса ACP, управление сессиями
│       ├── SessionRouter.ts # сопоставление отправителя и сессии, сохранение
│       ├── SenderGate.ts    # allowlist / pairing / open
│       ├── GroupGate.ts     # политика групповых чатов + фильтрация упоминаний
│       ├── PairingStore.ts  # генерация и подтверждение кодов сопряжения
│       ├── ChannelBase.ts   # абстрактный базовый класс: маршрутизация, слеш-команды
│       └── types.ts         # Envelope, ChannelConfig и т.д.
├── telegram/                # @qwen-code/channel-telegram
├── weixin/                  # @qwen-code/channel-weixin
└── dingtalk/                # @qwen-code/channel-dingtalk

Планы на будущее

Безопасность и групповые чаты

Ограничения инструментов для каждой группы — списки запрета/разрешения tools/toolsBySender для каждой группы
История контекста группы — кольцевой буфер последних пропущенных сообщений, добавляемый при @упоминании
Шаблоны упоминаний через регулярные выражения — резервный mentionPatterns для ненадёжных метаданных @упоминаний
Инструкции для каждой группы — поле instructions в GroupConfig для настройки персонажей групп
Команда /activation — переключение requireMention во время выполнения с сохранением на диск

Операционные инструменты

qwen channel doctor — валидация конфигурации, проверка переменных окружения, токенов ботов и сетевого подключения
qwen channel status --probe — реальная проверка подключения для каждого канала

Расширение поддержки платформ

Discord — Bot API + Gateway, серверы/каналы/личные сообщения/ветки
Slack — Bolt SDK, Socket Mode, рабочие пространства/каналы/личные сообщения/ветки

Мультиагентность

Маршрутизация между несколькими агентами — несколько агентов с привязками к каналу/группе/пользователю
Группы с широковещательной рассылкой — несколько агентов отвечают на одно и то же сообщение

Экосистема плагинов

Шаблон плагина от сообщества — инструмент генерации create-qwen-channel
Реестр и обнаружение плагинов — qwen extensions search, проверка совместимости версий