Feishu (Lark)

Это руководство описывает настройку канала Qwen Code в Feishu (飞书) / Lark.

Предварительные требования

Учётная запись организации Feishu
Приложение Feishu с App ID и App Secret (см. ниже)

Создание приложения

Перейдите на Feishu Open Platform
Создайте новое приложение (или используйте существующее)

В приложении включите возможность Bot (添加应用能力 → 机器人)

В разделе Event Subscriptions (事件与回调) выберите Long Connection (使用长连接接收事件)

Добавьте событие im.message.receive_v1 (接收消息)

Запомните App ID (Client ID) и App Secret (Client Secret) со страницы учётных данных приложения

Необходимые разрешения

Включите следующие разрешения в разделе Permissions & Scopes (权限管理):

im:message — Чтение и отправка сообщений
im:message:send_as_bot — Отправка сообщений от имени бота
im:resource — Доступ к ресурсам сообщений (изображения, файлы)

Публикация приложения

После настройки разрешений и событий создайте версию и опубликуйте её. Бот не будет работать, пока приложение не опубликовано и не одобрено.

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

Добавьте канал в ~/.qwen/settings.json:


{
  "channels": {
    "my-feishu": {
      "type": "feishu",
      "clientId": "<your-app-id>",
      "clientSecret": "<your-app-secret>",
      "senderPolicy": "open",
      "sessionScope": "user",
      "cwd": "/path/to/your/project",
      "groupPolicy": "open",
      "collapsible": true,
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

Параметры конфигурации

Параметр	Описание
`clientId`	App ID приложения Feishu
`clientSecret`	App Secret приложения Feishu
`collapsible`	Сворачивать длинные ответы в раскрывающиеся секции (по умолчанию: `false`)
`collapsibleThreshold`	Порог количества символов для сворачивания (по умолчанию: `500`)
`webhookPort`	Если установлен, используется режим HTTP webhook вместо WebSocket
`verificationToken`	Токен верификации для режима webhook
`encryptKey`	Ключ шифрования для режима webhook

Запуск


# Запустить только канал Feishu
qwen channel start my-feishu
 
# Или запустить все настроенные каналы вместе
qwen channel start

Откройте Feishu и отправьте сообщение боту. Вы увидите потоковую интерактивную карточку с ответом.

Режимы подключения

WebSocket (по умолчанию)

Режим WebSocket использует исходящее долгое соединение — не требуется публичный URL или сервер. Это рекомендуемый режим для большинства развёртываний.

Webhook

Если вам нужен режим webhook (например, для общих приложений), задайте webhookPort в конфигурации:


{
  "channels": {
    "my-feishu": {
      "type": "feishu",
      "webhookPort": 9321,
      "verificationToken": "<from-feishu-console>",
      "encryptKey": "<from-feishu-console>"
    }
  }
}

Затем установите URL запроса в Feishu Open Platform на http://<your-server>:9321.

Групповые чаты

Боты Feishu работают как в личных сообщениях, так и в групповых беседах. Чтобы включить поддержку групп:

Установите groupPolicy в "allowlist" или "open" в конфигурации канала
Добавьте бота в группу Feishu
Упомяните бота через @ в группе, чтобы вызвать ответ

По умолчанию бот требует упоминания @ в групповых чатах (requireMention: true). Установите "requireMention": false для конкретной группы, чтобы бот отвечал на все сообщения.

Возможности

Потоковая передача интерактивных карточек

Ответы отображаются в виде интерактивных карточек Feishu с обновлениями в реальном времени. Во время генерации ответа карточка показывает индикатор «generating», а также кнопку Stop для отмены генерации.

Контекст цитирования/ответа

Когда вы отвечаете на (цитируете) сообщение, цитируемое содержимое автоматически включается в контекст для агента. Это работает для:

Текстовых и форматированных сообщений
Интерактивных карточек (предыдущие ответы бота)

Изображения и файлы

Вы можете отправлять боту фотографии и документы:

Изображения: Анализируются с помощью мультимодальных функций зрения
Файлы: Скачиваются и сохраняются локально для чтения агентом

Одновременные сообщения

Несколько пользователей могут отправлять сообщения одновременно в одном и том же групповом чате. Каждое сообщение получает свою независимую карточку и ответ — они не мешают друг другу.

Ключевые отличия от DingTalk

Формат ответа: Используются интерактивные карточки Feishu (схема v2) с нативной поддержкой Markdown, включая таблицы
Потоковая передача: Содержимое карточки обновляется на месте с регулируемыми PATCH-запросами (интервал 1.5 с)
Подключение: WebSocket через @larksuiteoapi/node-sdk — та же модель исходящего соединения, не требуется публичный URL
Индикатор работы: При обработке добавляется реакция-эмодзи «OnIt»
Контекст цитирования: Поддерживается цитирование как текстовых сообщений, так и интерактивных карточек

Устранение неполадок

Бот не подключается

Проверьте правильность App ID и App Secret
Убедитесь, что в Event Subscriptions выбран Long Connection
Проверьте, подписаны ли вы на событие im.message.receive_v1
Посмотрите вывод терминала на предмет ошибок подключения

Бот не отвечает в группах

Убедитесь, что groupPolicy установлен в "allowlist" или "open" (по умолчанию — "disabled")
Упомяните бота через @ в групповом сообщении
Проверьте, что бот добавлен в группу

Карточка остаётся в состоянии «generating»

Обычно это означает, что ответ завершён, но финальное обновление карточки не удалось
Проверьте журналы терминала на предмет ошибок API (ограничение частоты запросов, лимиты размера карточки)
Очень длинные ответы с большим количеством таблиц могут превысить лимиты элементов карточки Feishu

Цитирование не включает содержимое карточки

Бот читает содержимое карточки через параметр API card_msg_content_type=user_card_content
Убедитесь, что у бота есть разрешение im:message на чтение сообщений