cliff-byte/alipay-doc-fetcher

Abrufen der Alipay Open Platform Dokumentation

Die Alipay-Dokumentationsseite ist eine JS-gerenderte SPA. WebFetch/curl erhalten keinen Textinhalt; Code und Parameter hängen von Lazy-Loading und ausklappbaren Interaktionen ab. Dieser Skill verwendet ein gekapseltes Playwright-Tool, um in einem Schritt strukturiertes Markdown zu erfassen.

Wann verwenden

• Der Benutzer möchte eine Alipay-API / einen Integrationsleitfaden / einen Fehlercode / ein Produktdokument „lokal herunterladen“, „abrufen“ oder „in Markdown konvertieren“.
• Der Benutzer fügt einen Link von opendocs.alipay.com oder opendoc.alipay.com ein und möchte dessen Inhalt.
• Es wurde bereits festgestellt, dass normales Web-Scraping (WebFetch / curl usw.) bei Alipay-Dokumenten nur den Titel zurückgibt, der Textinhalt jedoch leer ist.

Wie verwenden

Angenommen, das Installationsverzeichnis dieses Skills ist $SKILL (z. B. ~/.claude/skills/fetch-alipay-doc, für Codex ~/.codex/skills/..., für Cursor ~/.cursor/skills/...).

1. Erstmalige Verwendung: Abhängigkeiten einmalig unter $SKILL installieren (unabhängig vom Arbeitsverzeichnis):

   (cd "$SKILL" && npm install && npx playwright install chromium)   # Überspringen, wenn playwright bereits global installiert ist
   

2. Sammeln der abzurufenden URLs. Bei mehreren Seiten eine JSON-Konfigurationsdatei (z. B. urls.json) mit einem Array [{ "name": "...", "url": "..." }, ...] erstellen. Der name bestimmt den Ausgabedateinamen (kann weggelassen werden, standardmäßig wird die H1-Überschrift der Seite verwendet).

3. Im aktuellen Projektverzeichnis des Benutzers ausführen (das Skript mit absolutem Pfad aufrufen, die Ausgabe landet im Projekt und ist für den Benutzer sichtbar). Nicht cd in $SKILL verwenden – das würde die Dokumente in das Skill-Installationsverzeichnis schreiben (das Tool lehnt dies ab). Ausgabe mit --out in das Projektverzeichnis legen, nach Produkt/Thema geordnet:

   # Einzelseite
   node "$SKILL/scripts/fetch-alipay-docs.cjs" --url "<Alipay-Dokumentations-URL>" --name "<Dateiname>" --out ./alipay-docs/<Produktname>
   # Batch
   node "$SKILL/scripts/fetch-alipay-docs.cjs" --config urls.json --out ./alipay-docs/<Produktname>
   

   node löst die Playwright-Abhängigkeiten vom Speicherort der Skriptdatei aus (node_modules), unabhängig vom Arbeitsverzeichnis. Daher reicht es, das Skript vom Projektverzeichnis aus mit absolutem Pfad aufzurufen.

4. Ausgabe im --out-Verzeichnis: <name>.md + images/. Standardmäßig ist --out das aktuelle Verzeichnis mit ./alipay-docs.

Wichtige Prinzipien

• Treu: Der Text muss zu 100 % von der Seite stammen. Kein Erfinden / Zusammenfassen / Umformulieren / Interpretieren. Das Tool führt nur mechanische Formatierung durch.

Checkliste nach dem Abruf

Für jede abgerufene Seite einzeln prüfen. Bei Problemen gemäß „Fehlerbehebung“ verfahren oder erneut abrufen:

• Keine verbleibenden @@...@@-Platzhalter (Platzhalter nicht ersetzt = Code/Tabelle/Bild verloren).
• Keine UI-Rauschzeilen (Lesezeichen / Abonnement-Updates / Meine Dokumente / cURL·Java·C#-Tab-Labels / „Dieses Beispiel dient nur zur Referenz“ / „Alle Eigenschaften ausblenden“ usw.).
• Alle Bildverweise treffen auf lokale images/-Dateien (keine defekten Links).
• API-Geschäftsparameter enthalten verschachtelte Untereigenschaften und Aufzählungswerte und sind vollständig (entspricht dem Zustand nach dem Aufklappen aller Eigenschaften auf der Seite).
• Gemeinsame Anforderungs-/Antwort-Parametertabellen, Java-Anforderungsbeispiele und Fehlercodetabellen sind vollständig.
• rowspan-Ausrichtung in Tabellen korrekt (jeder Code und sein sub_code sind eindeutig zugeordnet, kein Versatz).

Fehlerbehebung

• Fehlender Code / Parameter → Wahrscheinlich wurde nicht vollständig gescrollt oder ausgeklappt („Mehr“-Aufzählungen, „Untereigenschaften“-Verschachtelungen); sicherstellen, dass der Abrufprozess vollständiges Scrollen und schrittweises, echtes Aufklappen durchführt.
• Bilder werden nicht heruntergeladen → cdn.nlark.com (Yuque-Bildserver) schlägt mit node https fehl. Dieses Tool verwendet stattdessen curl (mit UA / Referer); sicherstellen, dass curl auf dem System installiert ist.
• Ungewöhnliche Seitenstruktur (z. B. Benachrichtigungs-/Callback-Seiten, bei denen Abschnitte „Nachrichteneigenschaften / Benachrichtigungsantwort“ statt standardmäßiger Anfrage/Antwort sind) → Das Tool ist generisch nach H2-Abschnitten kompatibel, kein Hardcoding von Abschnittsnamen erforderlich.

Hinweis für Betreuer: Die vollständigen Erfahrungen, Ursachen und Designentscheidungen zu den Stolperfallen finden Sie in der Datei PLAYBOOK.md im Stammverzeichnis des Repositorys (wird nicht mit dem Skill installiert; unbedingt vor Codeänderungen lesen).