cliff-byte/alipay-doc-fetcher

Extraire la documentation de la plateforme ouverte Alipay

Le site de documentation d'Alipay est un SPA rendu en JavaScript. Les outils WebFetch/curl ne peuvent pas récupérer le corps du texte ; le code et les paramètres dépendent du chargement paresseux et des interactions de pliage/dépliage. Ce skill utilise un outil Playwright prêt à l'emploi pour extraire en une seule étape un Markdown structuré.

Quand l'utiliser

• L'utilisateur souhaite "télécharger localement", "extraire" ou "convertir en Markdown" une API Alipay, un guide d'intégration, un code d'erreur ou une documentation produit.
• L'utilisateur colle un lien opendocs.alipay.com ou opendoc.alipay.com et veut en obtenir le contenu.
• L'extraction web normale (WebFetch / curl, etc.) ne renvoie que le titre pour la documentation Alipay, le corps étant vide.

Comment l'utiliser

Soit $SKILL le répertoire d'installation de ce skill (ex. ~/.claude/skills/fetch-alipay-doc, Codex : ~/.codex/skills/..., Cursor : ~/.cursor/skills/...).

1. Première utilisation : Installer les dépendances une fois dans $SKILL (une seule fois, indépendamment du répertoire d'exécution) :

   (cd "$SKILL" && npm install && npx playwright install chromium)   # Peut être ignoré si Playwright est déjà installé globalement
   

2. Collecter les URL à extraire. Pour plusieurs pages, créer un fichier JSON de configuration (ex. urls.json) contenant un tableau [{ "name": "...", "url": "..." }, ...]. Le champ name détermine le nom du fichier de sortie (optionnel, par défaut utilise le H1 de la page).

3. Exécuter depuis le répertoire du projet de l'utilisateur (en utilisant le chemin absolu pour appeler le script ; les fichiers produits seront dans le projet et visibles par l'utilisateur). Ne pas exécuter cd $SKILL puis lancer la commande – cela écrirait la documentation dans le répertoire d'installation du skill (l'outil refusera). Spécifier la sortie avec --out dans le projet, en organisant par produit/thème :

   # Une seule page
   node "$SKILL/scripts/fetch-alipay-docs.cjs" --url "<URL documentation Alipay>" --name "<nom fichier>" --out ./alipay-docs/<nom produit>
   # Traitement par lot
   node "$SKILL/scripts/fetch-alipay-docs.cjs" --config urls.json --out ./alipay-docs/<nom produit>
   

   Node résout les dépendances Playwright à partir de l'emplacement du fichier de script pour trouver node_modules, indépendamment du répertoire d'exécution. Il suffit donc d'appeler avec le chemin absolu depuis le répertoire du projet.

4. Les fichiers produits sont dans le répertoire --out : <name>.md + images/. Par défaut, --out est ./alipay-docs dans le répertoire courant.

Principes clés

• Fidélité : Le texte du corps doit provenir à 100% de la page. Il est interdit d'inventer, résumer, reformuler ou interpréter. L'outil ne fait qu'un formatage mécanique.

Liste de vérification post-extraction

Pour chaque page extraite, vérifier chaque point. En cas de problème, appliquer la section "Dépannage" ou recommencer l'extraction :

• Aucun placeholder @@...@@ résiduel (placeholders non remplacés = code/tableau/image manquants).
• Aucune ligne de bruit UI (favoris / s'abonner aux mises à jour / mes documents / onglets cURL·Java·C# / "Cet exemple est fourni à titre indicatif uniquement" / "Réduire toutes les propriétés" etc.).
• Toutes les références d'images pointent vers un fichier local dans images/ (pas de liens cassés).
• Les paramètres métier de l'API incluent les sous-propriétés imbriquées et les valeurs d'énumération et sont complets (comparer avec l'état après avoir cliqué sur "Développer toutes les propriétés" dans la page).
• Les tableaux des paramètres de requête/réponse courants, l'exemple de requête Java et le tableau des codes d'erreur sont complets.
• L'alignement rowspan des tableaux est correct (chaque ligne de code correspond exactement à son sub_code, sans décalage).

Dépannage

• Code / paramètres manquants → Probablement dû au chargement paresseux non défilé ou aux sections pliées (énumérations "Plus", sous-propriétés imbriquées) non développées. Vérifier que le processus d'extraction effectue un défilement complet de la page et un clic individuel réel sur chaque élément à développer.
• Images non téléchargées → cdn.nlark.com (le CDN d'images Yque) échoue avec le module https de Node. Cet outil utilise curl (avec UA/Referer) à la place. Vérifier que curl est installé sur le système.
• Structure de page d'interface anormale (ex. pages de notification/rappel où la section est "Propriétés du message / Réponse à la notification" au lieu des requête/réponse standard) → L'outil est compatible avec les sections H2 génériques, sans avoir à coder en dur le nom de la section.

Note pour le mainteneur : L'expérience complète des pièges, leurs causes et les justifications de conception se trouvent dans le fichier PLAYBOOK.md à la racine du dépôt (non distribué avec l'installation du skill ; à lire impérativement avant de modifier le code).