cliff-byte/alipay-doc-fetcher

Obtener documentación de la plataforma abierta de Alipay

El sitio de documentación de Alipay es una SPA renderizada con JS, por lo que WebFetch/curl no pueden obtener el contenido real; los códigos y parámetros dependen de carga diferida e interacciones de plegado. Este Skill utiliza una herramienta Playwright empaquetada para convertir la documentación a Markdown estructurado de una sola vez.

Cuándo usarlo

• El usuario desea "descargar", "extraer" o "convertir a Markdown" una API, guía de integración, código de error o documento de producto de Alipay.
• El usuario pega un enlace de opendocs.alipay.com o opendoc.alipay.com y solicita su contenido.
• Se ha detectado que la captura web normal (WebFetch / curl) solo devuelve el título del documento de Alipay, con el cuerpo vacío.

Cómo usarlo

Suponga que el directorio de instalación de este Skill es $SKILL (por ejemplo, ~/.claude/skills/fetch-alipay-doc, en Codex ~/.codex/skills/..., en Cursor ~/.cursor/skills/...).

1. Primer uso: Instale las dependencias una vez en $SKILL (solo una vez, independientemente del directorio de ejecución):

   (cd "$SKILL" && npm install && npx playwright install chromium)   # Puede omitirse si ya tiene playwright instalado globalmente
   

2. Reúna las URL a capturar. Para múltiples documentos, cree un archivo JSON de configuración (por ejemplo, urls.json) con el formato de array [{ "name": "...", "url": "..." }, ...]. El campo name determina el nombre del archivo de salida (opcional; por defecto usa el H1 de la página).

3. Ejecute desde el directorio del proyecto actual (llame al script con la ruta absoluta; los archivos generados caerán dentro del proyecto, visibles para el usuario). No haga cd a $SKILL para ejecutar — eso escribiría los documentos en el directorio de instalación del skill (la herramienta lo rechazará). Especifique la salida con --out dentro del proyecto, organizando por producto/tema:

   # Documento único
   node "$SKILL/scripts/fetch-alipay-docs.cjs" --url "<URL_documento_Alipay>" --name "<nombre_archivo>" --out ./alipay-docs/<nombre_producto>
   # Lote
   node "$SKILL/scripts/fetch-alipay-docs.cjs" --config urls.json --out ./alipay-docs/<nombre_producto>
   

   Nota: Node resuelve las dependencias de playwright desde la ubicación del archivo de script buscando node_modules, no desde el directorio de ejecución. Por lo tanto, basta con invocar el script con ruta absoluta desde el directorio del proyecto.

4. El resultado se encuentra en el directorio --out: <nombre>.md + images/. El valor predeterminado de --out es ./alipay-docs en el directorio actual.

Principios clave

• Fidelidad: El texto del contenido debe provenir 100% de la página. Prohibido inventar, resumir, reescribir o interpretar. La herramienta solo realiza formateo mecánico.

Lista de verificación posterior a la captura

Después de cada captura, revise cada elemento. Si hay problemas, trátelos según la sección "Solución de problemas" o vuelva a capturar:

• Sin marcadores de posición @@...@@ residuales (marcador no reemplazado = código/tabla/imagen perdida).
• Sin líneas de ruido de UI (favoritos / suscribirse a actualizaciones / mis documentos / pestañas cURL·Java·C# / "Este ejemplo es solo de referencia" / "Ocultar todas las propiedades" etc.).
• Todas las referencias a imágenes apuntan a archivos locales images/ (sin enlaces rotos).
• Los parámetros comerciales de la API incluyen subpropiedades anidadas y valores de enumeración completos (comparar con el estado de la página después de hacer clic en "Expandir todas las propiedades").
• Tablas de parámetros de solicitud/respuesta comunes, ejemplos de solicitud en Java y tabla de códigos de error completos.
• Alineación correcta de rowspan en tablas (cada código code corresponde uno a uno con su sub_code, sin desfase).

Solución de problemas

• Falta código/parámetros → Probablemente la carga diferida no se desplazó o los elementos plegados (enumeración "Más", subpropiedades anidadas) no se expandieron; confirme que el proceso de captura realiza desplazamiento completo de la página y clics uno por uno en los elementos expandibles.
• Las imágenes no se descargan → cdn.nlark.com (almacenamiento de imágenes de Yuque) falla con node https; esta herramienta usa curl (con User-Agent/Referer); confirme que curl está instalado en el sistema.
• Estructura de página de API anómala (por ejemplo, páginas de notificación/retrollamada, donde la sección es "Propiedades del mensaje / Respuesta de notificación" en lugar de solicitud/respuesta estándar) → Esta herramienta es compatible con secciones H2 genéricas, no necesita codificar nombres de sección.

Nota del mantenedor: La experiencia completa de dificultades, sus causas y fundamentos de diseño se encuentran en PLAYBOOK.md en la raíz del repositorio (no se distribuye con la instalación del Skill; léalo antes de modificar el código).