Инструмент для извлечения облачных документов Feishu (Feishu Reader)

Это настольное приложение, написанное на Python и PyQt6, предназначенное для того, чтобы помочь пользователям быстро извлекать документы Feishu (Docx / Wiki) и преобразовывать их в формат Markdown для локального хранения.

🌟 Функциональные особенности

• Графический интерфейс пользователя: Предоставляет простой и удобный интерфейс на базе PyQt6.

• Извлечение в один клик: Поддержка вставки ссылок на документы/базы знаний Feishu, получение и создание файлов в формате .md одним нажатием.

• Полная поддержка форматов: Парсинг поддерживает текст, многоуровневые заголовки, блоки кода, списки, цитаты, таблицы, диаграммы Mermaid и другие распространенные элементы документов Feishu.

• Локализация изображений: Автоматическая загрузка изображений из документа в локальную директорию assets_<doc_token>/ с генерацией относительных путей в Markdown.

• Права доступа и аутентификация:

  • Прямой ввод App ID и App Secret приложения Feishu в интерфейсе для получения Access Token в один клик.

  • Поддержка ручного ввода токена и опция «Запомнить» для сохранения учетных данных локально.

• Локальное хранилище: Автоматическая генерация имен файлов с временными метками и сохранение в указанную пользователем директорию.

🔑 Настройка приложения Feishu

Этот инструмент обращается к документам через собственное приложение (self-built app) на открытой платформе Feishu. Для первого использования необходимо выполнить следующую настройку.

Шаг 1: Создание собственного приложения

1. Откройте открытую платформу Feishu и войдите под учетной записью администратора.

2. Перейдите в консоль разработчика → нажмите Создать приложение в правом верхнем углу → выберите Собственное приложение.

3. Введите название приложения (например, "Инструмент извлечения документов"), описание, загрузите иконку и нажмите «Подтвердить создание».

4. Перейдите на страницу сведений о приложении, на вкладке Учетные данные и базовая информация скопируйте:

   • App ID (например, cli_xxxxxxxxxxxxxxxx)

   • App Secret (нажмите «Просмотреть», чтобы скопировать)

Шаг 2: Предоставление необходимых прав

Перейдите на страницу сведений о приложении → Управление правами → найдите и активируйте следующие права:

Примечание: После активации прав перейдите на вкладку Управление версиями и публикация, создайте и опубликуйте версию, чтобы права вступили в силу.

Шаг 3: Предоставление приложению доступа к документу

По умолчанию документы Feishu видны только авторизованным пользователям. Необходимо предоставить доступ к целевому документу (или базе знаний) роботу приложения:

1. Откройте нужный документ Feishu, нажмите Поделиться в правом верхнем углу.

2. В появившемся окне найдите название вашего приложения и установите права на Просмотр.

3. Нажмите «Подтвердить», после чего приложение сможет получить доступ к документу.

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

🛠️ Установка и запуск

Системные требования

• Python 3.10 или выше

Установка зависимостей

pip install -r requirements.txt

Запуск настольного приложения

python main.py

🔌 Режим сервера MCP

Поддерживается запуск в качестве сервера MCP для удобного вызова непосредственно в ИИ-инструментах, таких как Claude или Cursor.

Настройка переменных окружения

export FEISHU_APP_ID="cli_xxxxxxxxxxxxx"
export FEISHU_APP_SECRET="xxxxxxxxxxxxxxxx"

Запуск сервера MCP

python mcp_server.py

Настройка для Claude / Cursor

Добавьте в ~/.claude.json или в конфигурацию MCP проекта:

{
  "mcpServers": {
    "feishu-reader": {
      "command": "python",
      "args": ["mcp_server.py"],
      "env": {
        "FEISHU_APP_ID": "cli_xxxxxxxxxxxxx",
        "FEISHU_APP_SECRET": "xxxxxxxxxxxxxxxx"
      },
      "workingDirectory": "/path/to/feishu-reader-mcp"
    }
  }
}

📖 Руководство пользователя

1. Ввод учетных данных: Введите App ID и App Secret вашего приложения Feishu в верхней части интерфейса (сохраняются автоматически после первого использования).

2. Получение токена: Нажмите кнопку [Обновить] справа от строки Access Token для автоматического получения и заполнения токена; также можно вставить токен вручную.

3. Вставка ссылки на документ: Вставьте ссылку на документ или страницу базы знаний Feishu в поле «URL документа» (поддерживаются ссылки типов /docx/, /doc/, /wiki/).

4. Начало извлечения: Нажмите [Начать извлечение] и выберите директорию для сохранения Markdown-файла в появившемся окне.

5. Ожидание завершения: В нижней области логов будет отображаться прогресс в реальном времени. После завершения вы найдете .md файл и директорию с изображениями assets_xxx/ в целевой папке.

📄 Структура проекта

💡 Примечания

• Инструмент адаптирован для нового формата документов Feishu (на базе OpenAPI /docx/v1/documents), в старых версиях документов возможны отклонения в форматировании.

• Для загрузки изображений приложению требуются права docs:document.media:download, а документ должен быть правильно предоставлен роботу приложения, иначе загрузка изображений будет пропущена, а причина ошибки будет указана в логах.

• Существуют ограничения на частоту вызовов API (5 запросов в секунду / 10 000 в день), пожалуйста, не извлекайте крупные документы слишком часто.

• Срок действия токена по умолчанию составляет около 2 часов, после истечения срока просто нажмите [Обновить] для повторного получения.