Настройка Feishu / Lark

Hermes Agent интегрируется с Feishu и Lark в качестве полнофункционального бота. После подключения вы можете общаться с агентом в личных сообщениях или групповых чатах, получать результаты cron-задач в домашнем чате, а также отправлять текст, изображения, аудио и файлы через стандартный gateway-канал.

Интеграция поддерживает оба режима подключения:

• websocket — рекомендуется; Hermes открывает исходящее соединение, и вам не нужна публичная webhook-точка

• webhook — полезно, когда вы хотите, чтобы Feishu/Lark отправлял события в ваш gateway через HTTP

Как работает Hermes

Это поведение в общих чатах контролируется в config.yaml:

group_sessions_per_user: true

Установите значение false, только если вы явно хотите одну общую беседу на чат.

Шаг 1: Создайте приложение Feishu / Lark

Рекомендуется: Сканирование для создания (одна команда)

hermes gateway setup

Выберите Feishu / Lark и отсканируйте QR-код с помощью мобильного приложения Feishu или Lark. Hermes автоматически создаст приложение-бота с правильными разрешениями и сохранит учётные данные.

Альтернатива: Ручная настройка

Если сканирование недоступно, мастер переключится на ручной ввод:

1. Откройте консоль разработчика Feishu или Lark:
2. Feishu: https://open.feishu.cn/

3. Lark: https://open.larksuite.com/

4. Создайте новое приложение.

5. В разделе Credentials & Basic Info скопируйте App ID и App Secret.

6. Включите возможность Bot для приложения.

7. Запустите hermes gateway setup, выберите Feishu / Lark и введите учётные данные по запросу.

Шаг 2: Выберите режим подключения

Рекомендуется: Режим WebSocket

Используйте режим WebSocket, когда Hermes запущен на вашем ноутбуке, рабочей станции или частном сервере. Публичный URL не требуется. Официальный Lark SDK открывает и поддерживает постоянное исходящее WebSocket-соединение с автоматическим переподключением.

FEISHU_CONNECTION_MODE=websocket

Требования: Пакет Python websockets должен быть установлен. SDK управляет жизненным циклом соединения, heartbeat'ами и автоматическим переподключением.

Как это работает: Адаптер запускает WebSocket-клиент Lark SDK в фоновом потоке-исполнителе. Входящие события (сообщения, реакции, действия с карточками) отправляются в основной asyncio-цикл. При отключении SDK автоматически попытается переподключиться.

Опционально: Режим Webhook

Используйте режим webhook только если Hermes уже запущен за доступной HTTP-точкой.

FEISHU_CONNECTION_MODE=webhook

В режиме webhook Hermes запускает HTTP-сервер (через aiohttp) и обслуживает endpoint Feishu по адресу:

/feishu/webhook

Требования: Пакет Python aiohttp должен быть установлен.

Вы можете настроить адрес привязки и путь webhook-сервера:

FEISHU_WEBHOOK_HOST=127.0.0.1   # по умолчанию: 127.0.0.1
FEISHU_WEBHOOK_PORT=8765         # по умолчанию: 8765
FEISHU_WEBHOOK_PATH=/feishu/webhook  # по умолчанию: /feishu/webhook

Когда Feishu отправляет запрос проверки URL (type: url_verification), webhook отвечает автоматически, чтобы вы могли завершить настройку подписки в консоли разработчика Feishu.

Шаг 3: Настройте Hermes

Вариант A: Интерактивная настройка

hermes gateway setup

Выберите Feishu / Lark и следуйте подсказкам.

Вариант B: Ручная настройка

Добавьте следующее в ~/.hermes/.env:

FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=secret_xxx
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket

# Опционально, но настоятельно рекомендуется
FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy
FEISHU_HOME_CHANNEL=oc_xxx

FEISHU_DOMAIN принимает:

• feishu для Feishu China

• lark для Lark international

Шаг 4: Запустите Gateway

hermes gateway

Затем отправьте сообщение боту в Feishu/Lark, чтобы подтвердить, что соединение активно.

Домашний чат

Используйте /set-home в чате Feishu/Lark, чтобы назначить его домашним каналом для результатов cron-задач и кроссплатформенных уведомлений.

Вы также можете настроить его заранее:

FEISHU_HOME_CHANNEL=oc_xxx

Безопасность

Белый список пользователей

Для production-использования задайте белый список Feishu Open ID:

FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy

Если оставить белый список пустым, любой, кто может связаться с ботом, сможет его использовать. В групповых чатах белый список проверяется по open_id отправителя перед обработкой сообщения.

Ключ шифрования Webhook

При работе в режиме webhook установите ключ шифрования для проверки подписи входящих webhook-запросов:

FEISHU_ENCRYPT_KEY=your-encrypt-key

Этот ключ находится в разделе Event Subscriptions конфигурации вашего приложения Feishu. При установке адаптер проверяет каждый webhook-запрос с помощью алгоритма подписи:

SHA256(timestamp + nonce + encrypt_key + body)

Вычисленный хеш сравнивается с заголовком x-lark-signature с использованием время-безопасного сравнения. Запросы с недействительными или отсутствующими подписями отклоняются с HTTP 401.

Токен верификации

Дополнительный уровень аутентификации, который проверяет поле token внутри webhook-запросов:

FEISHU_VERIFICATION_TOKEN=your-verification-token

Этот токен также находится в разделе Event Subscriptions вашего приложения Feishu. При установке каждый входящий webhook-запрос должен содержать соответствующий token в своём объекте header. Несовпадающие токены отклоняются с HTTP 401.

Оба параметра FEISHU_ENCRYPT_KEY и FEISHU_VERIFICATION_TOKEN могут использоваться вместе для многоуровневой защиты.

Политика групповых сообщений

Переменная окружения FEISHU_GROUP_POLICY управляет тем, как и отвечает ли Hermes в групповых чатах:

FEISHU_GROUP_POLICY=allowlist   # по умолчанию

Во всех режимах бот должен быть явно упомянут через @ (или @all) в группе, прежде чем сообщение будет обработано. Личные сообщения всегда обходят этот фильтр.

Установите FEISHU_REQUIRE_MENTION=false, чтобы разрешить Hermes читать весь групповой трафик без необходимости @упоминания:

FEISHU_REQUIRE_MENTION=false

Для контроля на уровне каждого чата установите require_mention в записи group_rules — см. Контроль доступа по группам ниже.

Идентификация бота

Hermes автоматически определяет open_id и отображаемое имя бота при запуске. Вам нужно устанавливать их вручную только если автоопределение не может связаться с API Feishu, или если ваше приложение использует tenant-scoped user ID:

FEISHU_BOT_OPEN_ID=ou_xxx     # только если автоопределение не сработало
FEISHU_BOT_USER_ID=xxx        # требуется, если приложение использует sender_id_type=user_id
FEISHU_BOT_NAME=MyBot         # только если автоопределение не сработало

Обмен сообщениями между ботами

По умолчанию Hermes игнорирует сообщения, отправленные другими ботами. Включите обмен сообщениями между ботами, если вы хотите, чтобы Hermes участвовал в A2A-оркестрации или получал уведомления от других ботов в той же группе.

FEISHU_ALLOW_BOTS=mentions   # по умолчанию: none

Также настраивается как feishu.allow_bots в config.yaml (переменная окружения имеет приоритет, если заданы оба значения).

Ботов-отправителей не нужно добавлять в FEISHU_ALLOWED_USERS — этот белый список применяется только к пользователям-людям.

Предоставьте область application:bot.basic_info:read, чтобы отображать имена ботов-отправителей; без неё боты-отправители всё равно будут корректно маршрутизироваться, но будут отображаться как их open_id.

Интерактивные действия с карточками

Когда пользователи нажимают кнопки или взаимодействуют с интерактивными карточками, отправленными ботом, адаптер маршрутизирует эти действия как синтетические события команды /card:

• Нажатия кнопок преобразуются в: /card button {"key": "value", ...}

• Полезная нагрузка value из определения карточки включается как JSON.

• Действия с карточками дедуплицируются с окном в 15 минут для предотвращения двойной обработки.

Запросы на подтверждение обновления от gateway используют нативную карточку Feishu Да / Нет вместо обычных текстовых ответов. Когда hermes update --gateway требует подтверждения, адаптер записывает выбранный ответ в файл .update_response и заменяет карточку на resolved-состояние.

События действий с карточками отправляются с типом MessageType.COMMAND, поэтому они проходят через обычный конвейер обработки команд.

Также работает подтверждение команд — когда агенту нужно выполнить опасную команду, он отправляет интерактивную карточку с кнопками Allow Once / Session / Always / Deny. Пользователь нажимает кнопку, и callback действия с карточкой доставляет решение о подтверждении обратно агенту.

Требуемая конфигурация приложения Feishu

Интерактивные карточки требуют трёх шагов настройки в консоли разработчика Feishu. Отсутствие любого из них вызывает ошибку 200340 при нажатии пользователями кнопок на карточках.

1. Подпишитесь на событие card action: В разделе Event Subscriptions добавьте card.action.trigger в подписанные события.

2. Включите возможность Interactive Card: В разделе App Features > Bot убедитесь, что переключатель Interactive Card включён. Это сообщает Feishu, что ваше приложение может получать callback'и действий с карточками.

3. Настройте Card Request URL (только для webhook-режима): В разделе App Features > Bot > Message Card Request URL установите URL на тот же endpoint, что и для событий webhook (например, https://your-server:8765/feishu/webhook). В режиме WebSocket это обрабатывается автоматически SDK.

Интеллектуальные ответы на комментарии в документах

Помимо чата, адаптер также может отвечать на @-упоминания, оставленные на документах Feishu/Lark. Когда пользователь комментирует документ (локальный выделенный текст или комментарий ко всему документу) и @упоминает бота, Hermes читает документ вместе с окружающей веткой комментариев и публикует ответ LLM непосредственно в ветке.

Работает на основе события drive.notice.comment_add_v1. Обработчик:

• Загружает содержимое документа и историю комментариев параллельно (20 сообщений для комментариев ко всему документу, 12 для комментариев к выделенному тексту).

• Запускает агента с наборами инструментов feishu_doc + feishu_drive, ограниченными рамками одной сессии комментария.

• Разбивает ответы на части по 4000 символов и публикует их как ответы в ветке.

• Кэширует сессии для каждого документа на 1 час с лимитом в 50 сообщений, чтобы последующие комментарии к тому же документу сохраняли контекст.

Трёхуровневый контроль доступа

Ответы на комментарии в документах работают только по явному разрешению — нет неявного режима «разрешить всем». Разрешения разрешаются в следующем порядке (первое совпадение выигрывает, для каждого поля):

1. Точный документ — правило, ограниченное конкретным токеном документа.

2. Wildcard — правило, соответствующее шаблону документов.

3. Верхний уровень — правило по умолчанию для рабочей области.

Две доступные политики для каждого правила:

• allowlist — статический список пользователей / tenant'ов.

• pairing — статический список ∪ runtime-одобренные пользователи. Полезно для поэтапных развёртываний, где модераторы могут предоставлять доступ в реальном времени.

Правила хранятся в ~/.hermes/feishu_comment_rules.json (разрешения pairing — в ~/.hermes/feishu_comment_pairing.json) с hot-reload'ом на основе времени изменения файла — изменения вступают в силу при следующем событии комментария без перезапуска gateway.

CLI:

# Просмотр текущих правил и состояния pairing
python -m gateway.platforms.feishu_comment_rules status

# Симуляция проверки доступа для конкретного документа + пользователя
python -m gateway.platforms.feishu_comment_rules check <fileType:fileToken> <user_open_id>

# Управление pairing-разрешениями в реальном времени
python -m gateway.platforms.feishu_comment_rules pairing list
python -m gateway.platforms.feishu_comment_rules pairing add <user_open_id>
python -m gateway.platforms.feishu_comment_rules pairing remove <user_open_id>

Требуемая конфигурация приложения Feishu

В дополнение к уже предоставленным разрешениям для чата/карточек, добавьте событие drive comment:

• Подпишитесь на drive.notice.comment_add_v1 в разделе Event Subscriptions.

• Предоставьте области docs:doc:readonly и drive:drive:readonly, чтобы обработчик мог читать содержимое документов.

Поддержка медиа

Входящие (получение)

Адаптер получает и кэширует следующие типы медиа от пользователей:

Медиа из сообщений с rich-текстом (post), включая встроенные изображения и вложения файлов, также извлекаются и кэшируются.

Для небольших текстовых документов (.txt, .md) содержимое файла автоматически вставляется в текст сообщения, чтобы агент мог прочитать его напрямую без использования инструментов.

Исходящие (отправка)

Маршрутизация загрузки файлов автоматическая на основе расширения:

• .ogg, .opus → загружается как аудио opus

• .mp4, .mov, .avi, .m4v → загружается как медиа mp4

• .pdf, .doc(x), .xls(x), .ppt(x) → загружается с их типом документа

• Всё остальное → загружается как потоковый файл общего типа

Рендеринг Markdown и резервный Post-режим

Когда исходящий текст содержит markdown-форматирование (заголовки, жирный текст, списки, блоки кода, ссылки и т.д.), адаптер автоматически отправляет его как сообщение Feishu post со встроенным тегом md, а не как обычный текст. Это обеспечивает расширенный рендеринг в клиенте Feishu.

Если API Feishu отклоняет post-полезную нагрузку (например, из-за неподдерживаемых markdown-конструкций), адаптер автоматически переключается на отправку обычного текста с удалённой markdown-разметкой. Этот двухэтапный резервный механизм гарантирует, что сообщения всегда доставляются.

Обычные текстовые сообщения (без обнаруженного markdown) отправляются как простой тип сообщения text.

Реакции статуса обработки

Пока агент работает, бот показывает реакцию Typing на вашем сообщении. Она очищается, когда приходит ответ, или заменяется на CrossMark, если обработка завершилась ошибкой.

Установите FEISHU_REACTIONS=false, чтобы отключить это.

Защита от всплесков и пакетирование

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

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

Когда пользователь отправляет несколько текстовых сообщений подряд, они объединяются в одно событие перед отправкой:

Пакетирование медиа

Несколько вложений медиа, отправленных подряд (например, перетаскивание нескольких изображений), объединяются в одно событие:

Сериализация по чатам

Сообщения внутри одного чата обрабатываются последовательно (по одному за раз) для поддержания связности беседы. У каждого чата своя блокировка, поэтому сообщения в разных чатах обрабатываются параллельно.

Ограничение скорости (Webhook-режим)

В режиме webhook адаптер применяет ограничение скорости по IP для защиты от злоупотреблений:

• Окно: скользящее окно в 60 секунд

• Лимит: 120 запросов на окно для тройки (app_id, путь, IP)

• Лимит отслеживания: До 4096 уникальных ключей (предотвращает неограниченный рост памяти)

Запросы, превышающие лимит, получают HTTP 429 (Too Many Requests).

Отслеживание аномалий Webhook

Адаптер отслеживает последовательные ответы с ошибками для каждого IP-адреса. После 25 последовательных ошибок с одного IP в течение 6-часового окна в лог записывается предупреждение. Это помогает обнаружить неправильно настроенные клиенты или попытки сканирования.

Дополнительные защиты webhook:

• Лимит размера тела: максимум 1 МБ

• Таймаут чтения тела: 30 секунд

• Проверка Content-Type: принимается только application/json

Настройка WebSocket

При использовании режима websocket вы можете настроить поведение переподключения и ping:

platforms:
  feishu:
    extra:
      ws_reconnect_interval: 120   # Секунды между попытками переподключения (по умолчанию: 120)
      ws_ping_interval: 30         # Секунды между WebSocket ping'ами (опционально; SDK по умолчанию, если не задано)

Контроль доступа по группам

Помимо глобальной FEISHU_GROUP_POLICY, вы можете задать детальные правила для каждого группового чата, используя group_rules в config.yaml:

platforms:
  feishu:
    extra:
      default_group_policy: "open"     # По умолчанию для групп, не указанных в group_rules
      admins:                          # Пользователи, которые могут управлять настройками бота
        - "ou_admin_open_id"
      group_rules:
        "oc_group_chat_id_1":
          policy: "allowlist"          # open | allowlist | blacklist | admin_only | disabled
          allowlist:
            - "ou_user_open_id_1"
            - "ou_user_open_id_2"
        "oc_group_chat_id_2":
          policy: "admin_only"
        "oc_group_chat_id_3":
          policy: "blacklist"
          blacklist:
            - "ou_blocked_user"
        "oc_free_chat":
          policy: "open"
          require_mention: false       # переопределяет FEISHU_REQUIRE_MENTION для этого чата

Установите require_mention: false в записи group_rules, чтобы пропустить требование @упоминания для этого конкретного чата. Если не указано, чат наследует глобальное значение FEISHU_REQUIRE_MENTION.

Группы, не указанные в group_rules, используют default_group_policy (по умолчанию равно значению FEISHU_GROUP_POLICY).

Дедупликация

Входящие сообщения дедуплицируются с использованием ID сообщений и TTL в 24 часа. Состояние дедупликации сохраняется между перезапусками в файл ~/.hermes/feishu_seen_message_ids.json.

Все переменные окружения

Настройки WebSocket и ACL по группам настраиваются в config.yaml в разделе platforms.feishu.extra (см. Настройка WebSocket и Контроль доступа по группам выше).

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

Набор инструментов

Feishu / Lark использует предустановку платформы hermes-feishu, которая включает те же основные инструменты, что и Telegram и другие платформы обмена сообщениями на основе gateway.