Интеграция с Lark Bot

Привяжите агента Предиктор Икс к боту Lark (飞书), чтобы общаться с ним через личные сообщения или группы — упоминайте бота через @, общайтесь в естественной манере или используйте команду /issue для создания задачи в Предиктор Икс, не покидая Lark.

Привяжите любого агента к боту Lark (飞书), и ваша команда сможет работать с ним прямо из Lark: пишите боту в личные сообщения, упоминайте его через @ в группе или используйте команду /issue для создания задачи Предиктор Икс, не открывая основное приложение. Ответы агента транслируются в чат в виде интерактивной карточки, которая обновляется в процессе работы.

Каждый бот привязывается в соотношении один к одному к конкретному агенту Предиктор Икс. Привязка второго агента создает второго бота; один агент не может иметь двух ботов.

Что делает эта интеграция

Область	Поведение
Агент → Интеграции	На странице сведений об агенте есть вкладка Интеграции (и соответствующий раздел на боковой панели). Владельцы и администраторы видят там кнопку Привязать к Lark; после привязки она сменяется значком Подключено к Lark со ссылкой Управление в Lark.
Личные сообщения боту	Участник рабочего пространства пишет боту напрямую в Lark. Каждый диалог становится сессией чата с агентом в Предиктор Икс; агент отвечает в ветке обсуждения.
Упоминание @ в группе	Добавьте бота в группу Lark и упомяните его через @. Бот считывает только сообщение, в котором он был упомянут — он не следит за всей перепиской в группе.
Команда `/issue`	Ввод команды `/issue <заголовок>` (опционально с описанием) создает новую задачу в рабочем пространстве Предиктор Икс от вашего имени.
Интерактивная карточка ответа	Бот публикует интерактивную карточку и обновляет ее по мере работы агента — отображается прогресс, финальный ответ или ошибка.

Привязка агента (владелец / администратор)

Привязка выполняется через сканирование QR-кода — не нужно копировать секретные ключи приложений или заходить в консоль разработчика.

Откройте агента в разделе Агенты → ваш агент.
Перейдите на вкладку Интеграции (или используйте раздел Интеграции на боковой панели) и нажмите Привязать к Lark.
Появится QR-код. Откройте на телефоне Lark → Scan, затем авторизуйте нового бота PersonalAgent.
После завершения сканирования диалоговое окно закроется, а агент отобразит статус Подключено к Lark. Ваша учетная запись Lark автоматически привязывается к аккаунту Предиктор Икс, поэтому вы можете сразу начать общение с ботом.

QR-код является одноразовым и действует ограниченное время. Если время истекло до того, как вы успели его авторизовать, нажмите Сканировать снова для получения нового кода.

После подключения агента кнопка Привязать к Lark заменяется ссылкой Управление в Lark. Используйте ее, чтобы открыть страницу настроек бота в Lark, если нужно изменить области доступа (scopes), переименовать его или запросить дополнительные разрешения — повторное сканирование намеренно отключено, чтобы не создавать дубликаты.

Использование бота (участники)

Первое сообщение: привязка учетной записи Lark

При первом сообщении боту он ответит карточкой с предложением привязать вашу учетную запись Lark. Перейдите по ссылке, войдите в Предиктор Икс, и ваш аккаунт Lark будет связан с вашей учетной записью в Предиктор Икс. Это позволяет агенту действовать от вашего имени — например, создавать задачи через /issue под вашим авторством.

Использовать бота могут только участники рабочего пространства. Если вы не являетесь участником или пропустили этап привязки учетной записи, бот не ответит — ваше сообщение будет проигнорировано (но записано в аудит без содержания самого текста).

Чат и `/issue`

Задавайте агенту любые вопросы — пишите боту в личные сообщения или упоминайте его через @ в группе. Диалог превращается в обычную сессию чата с агентом; агент отвечает прямо в карточке.
Создание задачи — отправьте /issue Исправить редирект на странице логина, и Предиктор Икс создаст соответствующую задачу в рабочем пространстве. Добавьте строки после заголовка, чтобы указать описание.
Наблюдение за работой — карточка ответа обновляется в процессе выполнения работы, поэтому вы видите прогресс и результат прямо в чате.

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

Управление и отключение

Управление на уровне рабочего пространства находится в Настройки → Интеграции:

Подключенные боты — список всех ботов в рабочем пространстве и агентов, к которым они привязаны. Список виден всем участникам.
Отключение доступно только владельцам / администраторам. Отключение прекращает передачу сообщений боту из Lark и разрывает соединение; запись об установке сохраняется для аудита, и вы можете позже снова привязать того же агента.

Разрешения

Привязка / отключение требуют прав владельца или администратора рабочего пространства. Участники видят список ботов, но не имеют элементов управления для привязки или отключения.
Общение с ботом требует наличия прав участника рабочего пространства с привязанной учетной записью Lark. Все остальные сообщения игнорируются.
Интеграция никогда не сохраняет тело сообщений для проигнорированных запросов — только причину отклонения для целей аудита.

Настройка для самостоятельного хостинга (Self-host)

В облачной версии Предиктор Икс Cloud интеграция уже доступна — этот раздел можно пропустить.

Для самостоятельного хостинга Lark отключен, пока вы не зададите ключ шифрования данных. Этот ключ шифрует секрет приложения каждого бота перед тем, как он попадет в базу данных.

Создайте 32-байтовый ключ и установите его на API-сервере:
```
Предиктор Икс_LARK_SECRET_KEY=<base64-encoded 32-byte key>
```
Перезапустите API. Пока ключ не установлен, в разделе Настройки → Интеграции будет отображаться уведомление "Интеграция с Lark не включена", а элементы для привязки будут скрыты.

Feishu и международный Lark, бок о бок. Облако, к которому относится бот — материковый Feishu (open.feishu.cn) или международный Lark (open.larksuite.com) — определяется автоматически при сканировании QR-кода, сохраняется в параметрах установки и используется для каждого вызова этого бота. Единое развертывание поддерживает оба варианта одновременно, поэтому команды из любого клиента могут выполнять привязку без дополнительной настройки.

Переменные среды PREDICTORX_LARK_HTTP_BASE_URL / PREDICTORX_LARK_CALLBACK_BASE_URL остаются только в качестве опциональной глобальной переопределяющей настройки (прокси или имитация); оставьте их не заданными для нормальной работы, чтобы каждая установка продолжала взаимодействовать со своим облаком.

Обновление с настройки на одно облако? Если вы ранее использовали развертывание для международного Lark, установив эти переменные в https://open.larksuite.com, сервер при первом запуске после обновления перенастроит существующие установки на регион Lark — после этого вы можете удалить эти параметры. Для материковых развертываний никаких действий не требуется.

Агенты — каждый бот привязан ровно к одному агенту
Чат — как диалог с ботом отображается внутри Предиктор Икс
Задачи — что создает команда /issue
Переменные окружения — полная справочная информация по настройке самостоятельного хостинга