Feishu-Dokumenten-Extraktionstool (Feishu Reader)

Dies ist eine Desktop-Anwendung, die auf Python und PyQt6 basiert und Benutzern dabei helfen soll, Feishu-Dokumente (Docx / Wiki) schnell zu extrahieren und zur lokalen Speicherung in das Markdown-Format zu konvertieren.

🌟 Funktionen

• Grafische Benutzeroberfläche: Bietet eine einfache und benutzerfreundliche PyQt6-Desktop-Oberfläche.

• Ein-Klick-Extraktion: Unterstützt das Einfügen von Feishu-Dokumenten-/Wissensdatenbank-Links, um diese mit einem Klick abzurufen und als .md-Datei zu generieren.

• Umfassende Formatunterstützung: Die Analyse unterstützt Text, mehrstufige Überschriften, Codeblöcke, Listen, Zitate, Tabellen, Mermaid-Diagramme und andere gängige Feishu-Dokumentenelemente.

• Lokalisierung von Bildern: Lädt Bilder innerhalb des Dokuments automatisch in ein lokales assets_<doc_token>/-Verzeichnis herunter und generiert relative Pfadreferenzen in Markdown.

• Berechtigungen und Authentifizierung:

  • Geben Sie die App ID und das App Secret der Feishu-App direkt in der Oberfläche ein, um mit einem Klick ein Access Token zu erhalten.

  • Unterstützt die manuelle Eingabe von Token und das Speichern der Anmeldedaten lokal durch Aktivieren der Option "Merken".

• Lokale Speicherung: Generiert automatisch Dateinamen mit Zeitstempeln und speichert diese im vom Benutzer angegebenen Verzeichnis.

🔑 Konfiguration der Feishu-App

Dieses Tool greift über eine selbst erstellte App auf der Feishu Open Platform auf Dokumente zu. Für die erstmalige Nutzung ist die folgende Konfiguration erforderlich.

Schritt 1: Erstellen einer selbst erstellten App

1. Öffnen Sie die Feishu Open Platform und melden Sie sich mit einem Administratorkonto an.

2. Gehen Sie zum Entwickler-Backend → Klicken Sie oben rechts auf App erstellen → Wählen Sie Selbst erstellte App.

3. Geben Sie den App-Namen (z. B. "Dokumenten-Extraktionstool") und eine Beschreibung ein, laden Sie ein Symbol hoch und klicken Sie auf Bestätigen.

4. Gehen Sie zur Detailseite der App und kopieren Sie unter dem Reiter Anmeldedaten & Basisinformationen:

   • App ID (z. B. cli_xxxxxxxxxxxxxxxx)

   • App Secret (nach dem Klicken auf "Anzeigen" kopieren)

Schritt 2: Erforderliche Berechtigungen aktivieren

Gehen Sie zur Detailseite der App → Berechtigungsverwaltung → Suchen und aktivieren Sie die folgenden Berechtigungen:

Hinweis: Nachdem die Berechtigungen aktiviert wurden, gehen Sie zum Reiter Versionsverwaltung & Veröffentlichung, erstellen und veröffentlichen Sie eine Version, damit die Berechtigungen wirksam werden.

Schritt 3: Dokumente für die App freigeben

Feishu-Dokumente sind standardmäßig nur für autorisierte Personen sichtbar. Sie müssen das Zieldokument (oder die Wissensdatenbank) für den App-Bot freigeben:

1. Öffnen Sie das Feishu-Zieldokument und klicken Sie oben rechts auf Teilen.

2. Suchen Sie im Freigabefenster nach Ihrem App-Namen und setzen Sie die Berechtigung auf Kann anzeigen.

3. Klicken Sie auf Bestätigen, damit die App auf das Dokument zugreifen kann.

Bei Wiki-Dokumenten müssen Sie den App-Bot in der Mitgliederverwaltung der Wissensdatenbank hinzufügen und ihm Anzeigerechte erteilen.

🛠️ Installation und Ausführung

Systemanforderungen

• Python 3.10 oder höher

Abhängigkeiten installieren

pip install -r requirements.txt

Desktop-Anwendung starten

python main.py

🔌 MCP-Server-Modus

Unterstützt den Betrieb als MCP-Server, um den direkten Aufruf in KI-Tools wie Claude oder Cursor zu ermöglichen.

Umgebungsvariablen konfigurieren

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

MCP-Server starten

python mcp_server.py

Konfiguration für Claude / Cursor

Fügen Sie dies in ~/.claude.json oder in die MCP-Konfiguration des Projekts ein:

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

📖 Benutzerhandbuch

1. Anmeldedaten eingeben: Geben Sie oben in der Oberfläche die App ID und das App Secret Ihrer selbst erstellten Feishu-App ein (wird nach der ersten Nutzung automatisch gespeichert).

2. Token abrufen: Klicken Sie auf die Schaltfläche [Aktualisieren] rechts neben der Access-Token-Zeile, um das Token automatisch abzurufen und einzufügen; Sie können ein vorhandenes Token auch manuell einfügen.

3. Dokumenten-Link einfügen: Fügen Sie den Link zum Feishu-Dokument oder zur Wissensdatenbank-Seite in das Eingabefeld "Dokumenten-URL" ein (unterstützt Links vom Typ /docx/, /doc/, /wiki/).

4. Extraktion starten: Klicken Sie auf [Extraktion starten] und wählen Sie im Popup-Fenster das Speicherverzeichnis für die Markdown-Datei aus.

5. Warten auf Abschluss: Der Protokollbereich unten zeigt den Fortschritt in Echtzeit an. Nach Abschluss finden Sie die .md-Datei und das assets_xxx/-Bildverzeichnis im Zielverzeichnis.

📄 Projektstruktur

💡 Hinweise

• Dieses Tool ist für das neue Feishu-Dokumentenformat (basierend auf /docx/v1/documents OpenAPI) optimiert; bei älteren Dokumenten kann es zu Formatabweichungen kommen.

• Für den Bild-Download muss die Berechtigung docs:document.media:download für die App aktiviert sein und das Dokument muss korrekt für den App-Bot freigegeben sein, andernfalls wird der Bild-Download übersprungen und der Grund im Protokoll angegeben.

• Es gibt Ratenbegrenzungen für API-Aufrufe (5 QPS / 10.000 Aufrufe pro Tag); bitte extrahieren Sie große Dokumente nicht zu häufig.

• Das Token ist standardmäßig etwa 2 Stunden gültig; nach Ablauf einfach auf [Aktualisieren] klicken, um ein neues zu erhalten.