Herramienta de extracción de documentos en la nube de Feishu (Feishu Reader)

Esta es una aplicación de escritorio escrita en Python y PyQt6, diseñada para ayudar a los usuarios a extraer rápidamente documentos de Feishu (Docx / Wiki) y convertirlos al formato Markdown para su almacenamiento local.

🌟 Características

• Interfaz gráfica de usuario: Proporciona una interfaz de escritorio PyQt6 sencilla y fácil de usar.

• Extracción con un clic: Admite pegar enlaces de documentos/bases de conocimiento de Feishu, capturar y generar archivos en formato .md con un solo clic.

• Soporte completo de formatos: El análisis admite texto, encabezados multinivel, bloques de código, listas, citas, tablas, diagramas Mermaid y otros elementos comunes de los documentos de Feishu.

• Localización de imágenes: Descarga automáticamente las imágenes del documento al directorio local assets_<doc_token>/ y genera referencias de rutas relativas en Markdown.

• Permisos y autenticación:

  • Ingrese el App ID y el App Secret de la aplicación Feishu directamente en la interfaz para obtener el Access Token con un clic.

  • Admite la entrada manual de tokens y la opción de "recordar" para guardar las credenciales localmente.

• Almacenamiento local: Genera automáticamente nombres de archivo con marca de tiempo y los guarda en el directorio especificado por el usuario.

🔑 Configuración de la aplicación Feishu

Esta herramienta accede a los documentos a través de una aplicación autoconstruida en la plataforma abierta de Feishu. Para el primer uso, se requiere la siguiente configuración.

Paso 1: Crear una aplicación autoconstruida

1. Abra la Plataforma abierta de Feishu e inicie sesión con una cuenta de administrador.

2. Vaya al Panel de desarrollador → haga clic en Crear aplicación en la esquina superior derecha → seleccione Aplicación autoconstruida.

3. Ingrese el nombre de la aplicación (por ejemplo, "Herramienta de extracción de documentos"), la descripción, cargue un icono y haga clic en Confirmar creación.

4. Vaya a la página de detalles de la aplicación y, en la pestaña Credenciales e información básica, copie:

   • App ID (por ejemplo, cli_xxxxxxxxxxxxxxxx)

   • App Secret (haga clic en "Ver" y luego copie)

Paso 2: Habilitar los permisos necesarios

Vaya a la página de detalles de la aplicación → Gestión de permisos → busque y habilite los siguientes permisos:

Nota: Después de habilitar los permisos, vaya a la pestaña Gestión de versiones y publicación, cree y publique una versión para que los permisos entren en vigor.

Paso 3: Compartir el documento con la aplicación

Por defecto, los documentos de Feishu solo son visibles para las personas con permisos. Debe compartir el documento (o base de conocimiento) de destino con el bot de la aplicación:

1. Abra el documento de Feishu de destino y haga clic en Compartir en la esquina superior derecha.

2. En la ventana emergente de compartir, busque el nombre de su aplicación y establezca el permiso en Puede ver.

3. Haga clic en Confirmar y la aplicación podrá acceder al documento.

Si es un documento de base de conocimiento (Wiki), debe agregar el bot de la aplicación en la Gestión de miembros de la base de conocimiento y otorgarle permisos de visualización.

🛠️ Instalación y ejecución

Requisitos del entorno

• Python 3.10 o superior

Instalar dependencias

pip install -r requirements.txt

Iniciar la aplicación de escritorio

python main.py

🔌 Modo servidor MCP

Admite la ejecución como servidor MCP, lo que facilita su llamada directa en herramientas de IA como Claude o Cursor.

Configurar variables de entorno

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

Iniciar el servidor MCP

python mcp_server.py

Configurar en Claude / Cursor

Agregue lo siguiente en ~/.claude.json o en la configuración MCP del proyecto:

{
  "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"
    }
  }
}

📖 Guía de uso

1. Ingresar credenciales: Ingrese el App ID y el App Secret de la aplicación autoconstruida de Feishu en la parte superior de la interfaz (se guardarán automáticamente después del primer uso).

2. Obtener Token: Haga clic en el botón [Actualizar] a la derecha de la línea Access Token para obtener y completar el token automáticamente; también puede pegar un token existente manualmente.

3. Pegar enlace del documento: Pegue el enlace del documento de Feishu o de la página de la base de conocimiento en el cuadro de entrada "URL del documento" (admite enlaces tipo /docx/, /doc/, /wiki/).

4. Iniciar extracción: Haga clic en [Iniciar extracción] y seleccione el directorio donde guardar el archivo Markdown en la ventana emergente.

5. Esperar a que finalice: El área de registro en la parte inferior mostrará el progreso en tiempo real. Una vez finalizado, encontrará el archivo .md y el directorio de imágenes assets_xxx/ en el directorio de destino.

📄 Estructura del proyecto

💡 Notas

• Esta herramienta es compatible con el nuevo formato de documento de Feishu (basado en la API abierta /docx/v1/documents); los documentos antiguos pueden tener desviaciones de formato.

• La descarga de imágenes requiere que la aplicación tenga habilitado el permiso docs:document.media:download y que el documento se haya compartido correctamente con el bot de la aplicación; de lo contrario, la descarga de imágenes se omitirá y se indicará el motivo del error en el registro.

• La llamada a la interfaz tiene límites de frecuencia (5 QPS / 10,000 veces al día); no extraiga documentos grandes repetidamente con frecuencia.

• El token tiene una validez predeterminada de aproximadamente 2 horas; después de que caduque, haga clic en [Actualizar] para obtener uno nuevo.