Подключение Feishu Drive

feishu_drive / lark_drive синхронизируют документы и файлы из указанной папки в базу знаний. Для пространств Wiki используются коннекторы feishu / lark; общий процесс синхронизации см. в Синхронизации источников данных.

Идентичность приложения и права на папки

Используйте App ID и App Secret корпоративного самостоятельно созданного приложения соответствующего региона; учётные данные Feishu и Lark нельзя смешивать. Права открываются в разделе «Управление правами» открытой платформы, все они только для чтения; после открытия прав необходимо создать и опубликовать новую версию приложения, чтобы они вступили в силу.

Необходимые права:

Право	Режим blocks (по умолчанию)	Режим export	Проявление при отсутствии
drive:drive:readonly	Обязательно: перечисление папок, скачивание обычных файлов, скачивание встроенных изображений/вложений docx	Обязательно: перечисление папок, скачивание обычных файлов	При загрузке папки или синхронизации ошибка 403 с подсказкой «сначала предоставьте папку группе, в которой находится приложение»
docx:document:readonly	Обязательно: разбор основного текста новых документов через blocks API	Не требуется	Не удаётся разобрать облачный документ docx
drive:export:readonly	По мере необходимости: экспорт таблиц/многомерных таблиц в xlsx; резервный экспорт при сбое blocks или пустом основном тексте	Обязательно: docx/doc/sheet/bitable полностью идут через асинхронный экспорт	Синхронизация таблиц не удаётся; резервный путь blocks недоступен

Коннектору облачного диска не требуется право wiki:wiki:readonly (это право коннектора базы знаний).

Необязательные улучшающие права (реальные имена участников при упоминании через @ — contact:user.base:readonly, заголовки ссылок на облачные документы — drive:drive.metadata:readonly, экспорт досок — board:whiteboard:node:read, преобразование встроенных электронных таблиц/многомерных таблиц в таблицы Markdown — sheets:spreadsheet:readonly / bitable:app:readonly): используются только на пути отрисовки blocks; при их отсутствии синхронизация не падает, деградирует только соответствующее содержимое. Полная матрица прав коннектора базы знаний приведена в разделе Синхронизация источников данных, подраздел Feishu/Lark.

После настройки прав опубликуйте версию приложения и авторизуйте целевую папку в пределах, доступных приложению. Если общий доступ предоставляется через группу, в которой находится приложение, проверьте отношения авторизации между приложением, управляющим папки и группой. Права API и права доступа к файлам — это две отдельные проверки: получение tenant access token не означает возможность читать произвольную папку.

Тест подключения внутри aihelpme.ru проверяет учётные данные приложения; доступ к папкам проверяется только при последующей загрузке дерева ресурсов. Если подключение успешно, но каталог возвращает 403, сначала проверьте область общего доступа и состояние публикации прав.

Настройка в базе знаний

1. Настройки базы знаний → Источник данных → Создать, выберите «Feishu Drive» или «Lark Drive».
2. Заполните App ID и App Secret, выполните тест подключения.
3. Введите folder_token конкретной папки или полную ссылку /drive/folder/<token>, загрузите дерево ресурсов и выберите область синхронизации. Нельзя оставлять пустым для использования корневого каталога облачного пространства.
4. Выберите полную/инкрементальную синхронизацию, расписание синхронизации, стратегию конфликтов и синхронизацию удаления; после сохранения сначала вручную синхронизируйте небольшое число файлов и проверьте журнал и результаты разбора.

При инкрементальной синхронизации старый курсор сверяется с текущим деревом файлов: исчезнувшие файлы помечаются как удалённые, только если перечисление выбранных ресурсов прошло полностью успешно; при неудачном перечислении подкаталога обнаружение откладывается. Удаление элементов знаний, соответствующих текущему источнику данных, выполняется только при включённой синхронизации удаления; при выключенной они сохраняются. Полная синхронизация (в том числе полная повторная синхронизация, запускаемая при обновлении) также сохраняет старый курсор для сверки удалений; у первой синхронизации нет исторической базы для сравнения, поэтому более ранние удаления обнаружить нельзя. При неудачном удалении по-прежнему следует проверить журнал синхронизации и оставшиеся элементы.

Обновление самого документа также очищает исчезнувшие дочерние элементы вложений в режиме blocks; это часть обновления содержимого и не управляется указанным выше переключателем синхронизации удаления исходных документов.

Файлы и режимы разбора

Обычные файлы после скачивания попадают в процесс разбора в зависимости от типа файла; таблицы/многомерные таблицы экспортируются в xlsx, папки обходятся рекурсивно, ярлыки разрешаются до целевого файла. Неподдерживаемые типы облачных документов пропускаются — следует посмотреть причину пропуска в журнале синхронизации.

У новой версии docx есть два пути, которые выбираются для каждого источника данных в «Настройки базы знаний → Редактирование источника данных → Режим разбора» (сохраняется в settings.parse_mode источника данных); по умолчанию blocks, и режим влияет одновременно на коннекторы Wiki и Drive:

Режим	Путь	Применимость и ограничения
blocks (по умолчанию)	Преобразование через blocks API в Markdown; при сбое API, пустом основном тексте или превышении 30 изображений/досок — откат к экспорту	Изображения и доски попадают в базу вместе с родительским документом и связываются с ним; разбираемые вложения (pdf/office и др.) сохраняются как отдельные элементы и взаимно связываются с родительским документом; встроенные электронные таблицы/многомерные таблицы преобразуются в таблицы Markdown внутри документа
export	Асинхронный экспорт docx, затем разбор документа	Изображения разбираются вместе с родительским документом; экспорт и разбор занимают больше времени; вложения во встроенных file block не сохраняются при экспорте; электронные таблицы/многомерные таблицы становятся встроенными таблицами docx и не разбираются как таблицы

Устаревшая переменная окружения FEISHU_DOCX_PARSE_MODE теперь читается только как резервное значение, если для источника данных не настроен режим разбора (выводится предупреждение об устаревании; в следующих версиях будет удалена). Деплои, явно установившие export в .env, после обновления продолжают работать так же.

После изменения фактического режима разбора следующая синхронизация (в том числе инкрементальная) заново загружает уже существующие docx; сохранение только остальных настроек не запускает смену режима. При откате к экспорту из-за превышения бюджета встроенных изображений вложения file block, уже перечисленные через blocks API, по-прежнему сохраняются отдельно и связываются с родительским документом; ограничения формата основного текста при экспорте совпадают с режимом export. Возможность поиска по содержимому изображений зависит также от объектного хранилища, обработки OCR/мультимодальности и состояния индекса, см. Разбор документов.

Частые вопросы

Симптом	Решение
Token недействителен или тест учётных данных не проходит	Проверьте регион Feishu/Lark, App ID/Secret и адрес частного прокси
Не удаётся загрузить папку	Используйте ссылку на конкретную папку; проверьте права API и авторизацию общего доступа к папке
Облачные документы не проходят, а обычные файлы в порядке	Проверьте права на экспорт; режиму blocks дополнительно нужны права на чтение docx
Число синхронизированных меньше числа файлов в каталоге	Проверьте неподдерживаемые типы, авторизацию подкаталогов, статистику неудач/пропусков
Изображения не извлекаются вместе с основным текстом	Убедитесь в состоянии объектного хранилища, обработки OCR/мультимодальности и индекса; в обоих режимах разбора изображения связываются с родительским документом
После изменения документа он на короткое время недоступен для поиска	Обновление может удалить старое знание и заново добавить его в базу; дождитесь завершения разбора новой версии и индексации

Справочник по реализации: internal/datasource/connector/feishu/drive/, core/shared.go и internal/application/service/datasource_service.go.