serendipity-88/yuque-power-user

Was macht yuque-power-user?

Automatisierung von Yuque-Dokumenten — Claude Code Skill: MCP-API-Fallstricke, erweiterte YMD-Syntax, Whiteboard-DSL, CLI-Bild-Upload und Playwright-Ergänzungen

MCP-API-Fallstricke

• API-Key handhaben: Stelle sicher, dass der MCP-Server mit dem richtigen Yuque-API-Token gestartet wird (YUQUE_TOKEN Umgebungsvariable).
• Raten-Limit: Yuque erlaubt standardmäßig 200 Requests pro Stunde; plane Puffer bei Batch-Operationen ein.
• Dokument-IDs: Verwende den Blob Pfad (z.B. yuque://...) im MCP-Kontext, nicht die URL.
• Bild-Upload: mcp_upload_image erwartet einen lokalen Pfad und bindet das Bild als temporäre URL ein, die nach 24h verfällt.

YMD Erweiterte Syntax

Yuque verwendet einen erweiterten Markdown-Dialekt. Folgende Elemente sind besonders nützlich:

Code-Blöcke mit Sprachangabe

console.log("Hello Yuque");

Tabellen mit erweiterten Attributen

Spalte A	Spalte B
Wert 1	Wert 2

Datenblock (Info-Tabelle)

Name: Beispielprojekt
Version: 2.1
Status: Aktiv

Grafisches Element (z.B. Checkliste)

• API-Anbindung getestet
• Dokumentation geschrieben

Whiteboard-DSL

Das Skill-Paket enthält eine DSL zur Beschreibung von Yuque-Whiteboards. Standard-Knoten:

• Shape: Rechteck, Kreis, Linie
• Text: Position, Schriftgröße, Inhalt
• Connector: Pfeile, Kurven

Beispiel:

shape rectangle "Hauptcontainer" at (50, 50) size 200x100
shape circle "Ziel" at (300, 150) size 50
connector arrow from "Hauptcontainer" to "Ziel" label "Auslösen"

Die DSL wird durch ein CLI-Tool yuque-dsl in das native Whiteboard-Format übersetzt.

CLI-Bild-Upload

Das Kommando yuque-upload lädt lokale Bilder in einen Yuque-Ordner hoch (Standard: _uploads).

# Ein einzelnes Bild hochladen
$ yuque-upload ./screenshot.png

# Batch-Upload (alle PNGs im Ordner)
$ yuque-upload ./images/*.png

Umgebungsvariablen:

• YUQUE_TOKEN – API-Token (erforderlich)
• YUQUE_NAMESPACE – Namespace des Zielbuchs (z.B. team/docs)

Playwright-Ergänzung

Für Szenarien, die die MCP-API nicht abdeckt (z.B. Login mit 2FA, dynamische Seitenerstellung, Interaktion mit nicht öffentlichen Bereichen), wird ein Playwright-Skript bereitgestellt.

# Installiere Abhängigkeiten
$ pip install playwright

# Führe das Skript aus (z.B. um ein Whiteboard zu erstellen)
$ python yuque_playwright.py --url "https://www.yuque.com/..." --action upload_image --image ./diagram.png

Das Skript öffnet einen Headless-Browser, führt Login durch (Credentials aus .env oder manuelle Eingabe) und führt die gewünschte Aktion aus. Verwende dieses Modul als Fallback, wenn die MCP-API nicht ausreicht.