Интеграция с Lark / Feishu — документация AIKraft Agents

Lark (международная версия) и Feishu (Китай) — это одна и та же платформа на разных доменах: Lark работает на open.larksuite.com, Feishu — на open.feishu.cn. Они используют один и тот же SDK, типы сообщений и протокол событий. Приложение зарегистрировано в одной из систем — выбирайте нужный регион при настройке.

AIKraft Agents использует официальный долгосрочный режим соединения (WebSocket) из @larksuiteoapi/node-sdk — никакой публичной webhook-URL или обратного туннеля не требуется. Жизненный цикл совпадает с адаптером Telegram, только вместо него разговор идёт с Lark.

Два способа настройки

Рекомендуется: Готово для агентов быстрого создания

На странице создания приложений Open Platform найдите баннер «Готово для агентов. Готово к подключению» с кнопкой Create. Нажатие на неё создаёт приложение с правильными разрешениями и настройками событий, предварительно сконфигурированными — вы полностью пропускаете этапы настройки областей действия и подписки на события.

Затем переходите прямо к разделу Подключить в приложении ниже, чтобы вставить App ID и Secret в AIKraft Agents.

Ручная настройка

Создайте Custom App и настройте области действия и события сами. Это полезно, если баннер агента ещё не отображается в интерфейсе вашего тенанта, или если вы хотите точно контролировать, какие разрешения предоставляете.

Полное пошаговое руководство ниже.

Вы всё равно копируете App ID + Secret обоими способами. Lark/Feishu выдаёт учётные данные для каждого тенанта независимо от выбранного способа создания — путь быстрого создания агента экономит только настройку разрешений и событий, а не вставку учётных данных.

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

Откройте Open Platform
- Lark: open.larksuite.com
- Feishu: open.feishu.cn
Войдите с тем рабочим/тенантским аккаунтом, которым должен принадлежать бот.
Создайте Custom App
Developer Console → Create Custom App. Укажите имя и иконку.
Скопируйте App ID и App Secret
На домашней странице приложения скопируйте App ID (начинается с cli_) и App Secret (32-символьная строка). Храните секрет так же, как пароль.
Включите необходимые области действия
В разделе Permissions & Scopes включите:
- im:message — чтение событий сообщений
- im:message.group_at_msg — получение @упоминаний в группах
- im:message:send_as_bot — отправка сообщений от имени бота
Пропуск любого из этих пунктов приведёт к тому, что бот молча пропустит события или не сможет отправлять сообщения.
Подпишитесь на события сообщений в режиме длинного соединения
В разделе Events & Callbacks установите способ доставки — Long connection mode (НЕ webhooks). Затем добавьте подписку на:
- im.message.receive_v1
Оставьте поле Encrypt Key пустым. Режим длинного соединения не использует шифрование полезной нагрузки webhook — заполнение Encrypt Key здесь сломает входящие события без понятной ошибки.
Опубликуйте версию приложения
Lark/Feishu требует опубликовать версию (или использовать dev-тенант), прежде чем бот сможет получать сообщения. Отправьте на ревью или активируйте dev-режим.

Подключить в приложении

Откройте Settings → Messaging в AIKraft Agents
Вы увидите третью карточку помимо Telegram и WhatsApp: Lark / Feishu.
Нажмите Connect
Откроется диалог с селектором региона и двумя полями для секретов.
Выберите регион
Lark (международный) использует open.larksuite.com; Feishu (Китай) — open.feishu.cn. Бот принадлежит либо одному, либо другому — это отдельные экосистемы.
Вставьте App ID + App Secret, затем Test
AIKraft Agents обменивает их на tenant_access_token. При успехе кнопка отображает зелёную галочку; при ошибке вы увидите сообщение об ошибке Lark дословно.
Нажмите Save
Учётные данные сохраняются в вашем workspace keychain, и адаптер Lark запускает сокет длинного соединения.

Первая беседа

Найдите бота в Lark / Feishu
Найдите бота по имени в приложении Lark/Feishu. Отправьте ему личное сообщение.
Отправьте /pair
Бот ответит подсказкой по использованию.
Сгенерируйте код в AIKraft Agents
Откройте меню любой сессии → Pair with Messaging → Lark. Скопируйте 6-значный код.
Введите команду pair в Lark
Бот подтверждает привязку в чате.
Отправьте любое сообщение
AIKraft Agents получает его. Ответ ассистента потоково возвращается в тот же чат.

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

В группах бот получает только сообщения, где его @упомянули — это стандартное поведение области действия im:message.group_at_msg. Без @упоминания событие не доставляется на сервере, поэтому адаптер не имеет шанса его упустить. Сообщения, адресованные боту, работают так же, как и личные сообщения.

Богатый текст

Ответы агента сохраняют распространённое форматирование при отправке в Lark:

жирный, курсив, ~~зачёркнутый~~ отображаются нативно через тип сообщения Lark post
[Ссылки](https://example.com) становятся кликабельными
Блоки кода с указанием языка ( ```python ... ``` ) отображаются с тегом языка
Разрывы абзацев сохраняются

Что не переводится (отправляется как обычный текст внутри post):

Заголовки (#, ##, …) — у Lark post нет элемента заголовка
Маркированные и нумерованные списки — маркеры отображаются как обычные • или 1.
Таблицы — отображаются как текст с пробелами
Встроенный `code` — отображается как жирный текст (у Lark post нет элемента встроенного кода)

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

Интерактивные карточки

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

Ограничения фазы 2:

До 10 кнопок на карточку
Метки кнопок усекаются до 30 символов

Вложения

Поддерживаются в обоих направлениях в личных сообщениях и @упоминаниях в группах:

Входящие: отправляйте изображения и файлы боту. Они скачиваются на сервере и становятся доступными агенту в рабочей папке сессии.
Исходящие: агент может отправлять изображения и документы обратно. Подписи к файлам отправляются как последующее текстовое сообщение (API Lark не может объединить подпись и файл в одном сообщении).

Ограничения, установленные адаптером:

Максимальный размер вложения: 20 МБ (соответствует ограничению чтения рендерера)
Аудио, видео и стикеры отбрасываются с понятным логом «неподдерживаемое вложение»

Ограничения

Lark и Feishu — это отдельные домены: бот принадлежит либо одному, либо другому, но не обоим
Бот видит только @упоминания в группах (стандартная область действия im:message.group_at_msg; расширить без одобрения на уровне предприятия невозможно)
Изменения сообщений старше 24 часов молча отбрасываются (ограничение API Lark)
Заголовки, списки и таблицы Markdown отображаются как обычный текст внутри post (у Lark post нет нативных эквивалентов)

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

«Бот не получает сообщения» — проверьте, включено ли im:message, и подписаны ли вы на im.message.receive_v1 в разделе Events & Callbacks. Убедитесь, что выбран режим доставки Long connection, а не webhooks.
«Ошибка подключения при Test» — если App Secret был пересоздан в Open Platform, скопируйте новое значение. Если вы сменили тенант приложения, старые учётные данные аннулируются.
«Бот получил моё личное сообщение, но игнорирует групповое» — боту нужна область действия im:message.group_at_msg, И сообщение должно @упоминать бота.
«Карточки приходят, но нажатия на кнопки не достигают агента» — убедитесь, что приложение опубликовано (или тенант находится в dev-режиме). Карточки из черновика могут отображаться, но обратные вызовы действий не срабатывают.
«`lark_send_card_failed` с `code: 230099` и `unknown property, property: elements`» — происходит, когда что-то ниже генерирует полезную нагрузку карточки схемы 1.0 внутри конверта `schema: '2.0'`. Исправление заключается в обёртке тела карточки в `body: { elements: [...] }` (уже реализовано; эта заметка существует для тех, кто форкает адаптер).
«Не могу отправить файл больше ~20 МБ» — это жёсткий лимит адаптера. Сжимайте или разбивайте файл перед отправкой.
Логи: ~/.craft-agent/logs/messaging-gateway.log — ищите по component:"lark-adapter" или event:"lark_*".