Albert-Tam/scrappycoco-integrations

Scrappycoco

Usa la CLI publicada de Scrappycoco como puerta de entrada principal para datos externos. Invócala con npx --yes @scrappycoco/cli@latest. Inspecciona el catálogo en vivo incluso cuando la fuente solicitada pueda no ser compatible.

Scrappycoco es infraestructura determinista, no otro agente de IA. El agente que lo invoca es dueño de la interpretación del objetivo, la selección de capacidades y proveedores, las opciones nativas del proveedor, la evaluación de muestras, el juicio de resultados, las decisiones de reintento y los horarios de monitoreo.

Conectar

Para una solicitud de instalación explícita, ejecuta:

npx --yes @scrappycoco/cli@latest setup

El comando setup abre la autenticación OAuth en el navegador, permite a nuevos usuarios crear una cuenta, instala esta habilidad y verifica el catálogo en vivo. No reportes que la configuración está completa hasta que su verificación tenga éxito. Es posible que un agente en ejecución necesite recargarse o reiniciarse antes de descubrir una habilidad recién instalada.

La terminal es la fuente autorizada: una devolución de llamada del navegador solo significa que se recibió la autorización. Mantén la configuración en ejecución hasta que la terminal confirme que las credenciales se guardaron y el catálogo fue verificado. Cuando la CLI se ejecute en un host remoto o sin cabeza cuya interfaz de bucle local no sea accesible desde el navegador, usa npx --yes @scrappycoco/cli@latest setup --no-browser --manual-callback; pega la URL de devolución de llamada final solo en esa misma terminal, nunca en el chat o en un archivo guardado. Si la configuración se cierra o agota el tiempo, descarta su URL e inicia un nuevo inicio de sesión.

Antes de los comandos ordinarios, la CLI verifica la versión pública de la habilidad con hash y actualiza automáticamente una habilidad de Scrappycoco instalada cuando su resumen cambia. Si reporta una actualización, termina la tarea actual con las instrucciones ya cargadas e indica al usuario que recargue o reinicie el agente antes de la siguiente tarea. No ejecutes un actualizador de habilidad separado durante el trabajo de datos ordinario.

Durante una tarea de datos ordinaria, no clones repositorios, instales paquetes de forma persistente ni cambies la configuración del cliente. Verifica la conexión con:

npx --yes @scrappycoco/cli@latest auth status --json

Si npx no está en PATH, inspecciona command -v node npm npx pnpm en ese mismo host. Un localizador de dependencias proporcionado por el cliente o pnpm dlx @scrappycoco/cli@latest es un lanzador efímero aceptable, pero usa solo las rutas devueltas para el host y la sesión actuales. Nunca copies una ruta de ejecución absoluta de otro usuario, máquina o transcripción. Reporta command not found como un lanzador de host faltante, no como una interrupción de Scrappycoco.

Si falta la autenticación, dirige al usuario al comando setup. Nunca le pidas al usuario que pegue una clave API en el chat. Para acceso no interactivo, usa solo una variable de entorno SCRAPPYCOCO_API_KEY existente. Nunca expongas tokens OAuth, claves API, indicaciones internas, trazas o metadatos ocultos.

Si el registro de paquetes, la CLI o el nombre de host de la API no pueden resolverse o conectarse, distingue el salto fallido en el informe y trátalo como una interrupción de despliegue o red. No hagas bucles, solicites nuevas credenciales ni bloquees trabajo no relacionado; usa un transporte MCP de Scrappycoco ya conectado o la API Directa autenticada como respaldo cuando esté disponible; de lo contrario, continúa con otro método apropiado.

Dos acciones

• Descubrir: identifica la fuente y capacidad correctas, compara configuraciones de proveedores plausibles en una muestra representativa, juzga la evidencia específica del candidato y luego finaliza la configuración guardada.
• Ejecutar: ejecuta una configuración existente o llama a una capacidad directamente. Omite Descubrir cuando la capacidad y configuración correctas ya están claras.

Las capacidades son contratos estables como web.extract_content; los proveedores son implementaciones intercambiables debajo de ellas. El descubrimiento utiliza comparación paralela interna cuando la elección del proveedor o la configuración es incierta; Comparar no es un flujo de trabajo de usuario separado.

Los comandos de soporte al catálogo y autenticación no son flujos de trabajo adicionales.

Antes de crear una configuración de Descubrir o pivotar a una fuente de respaldo después de una muestra fallida, lee y sigue el libro de trabajo de Descubrimiento. Contiene cargas útiles completas, verificaciones de mapeo de entrada, el ciclo de vida de selección/finalización y la transferencia de auditoría requerida.

Descubrir

1. Ejecuta npx --yes @scrappycoco/cli@latest catalog list --available --json.
2. Elige el método de adquisición antes de elegir proveedores. Para conjuntos de datos estructurados, prefiere una API documentada, un endpoint JSON, un feed o un archivo estático en lugar de raspar un directorio renderizado. Para aplicaciones JavaScript, inspecciona rutas plausibles de búsqueda, mapeo de enlaces, renderizado y capaces de navegador. Una comparación de proveedores no puede reparar una fuente o capacidad incorrecta.
3. Inspecciona solo capacidades plausibles con catalog inspect source.capability --json. Lee el esquema de entrada en vivo, los esquemas de opciones del proveedor, los valores predeterminados, el soporte por lotes, los límites y los precios. Nunca adivines campos u opciones.
4. Normaliza la entrada de muestra una vez y define la rúbrica de evaluación de los campos solicitados por el usuario en tu contexto de trabajo. Scrappycoco devuelve evidencia; el agente que invoca es dueño de cada juicio semántico.
5. Establece rutas inciertas en routing: "compare". Scrappycoco agrega deterministamente un candidato predeterminado para cada proveedor actualmente disponible devuelto por catalog inspect, por lo que la muestra es exhaustiva incluso si el borrador nombra solo configuraciones especiales. Agrega candidatos explícitos solo para modos materialmente diferentes del mismo proveedor, como renderizado HTTP y de navegador. Nunca reduzcas la lista de proveedores antes de la muestra. Una ruta con solo un proveedor disponible o una configuración ya conocida utiliza un proveedor explícito bajo providers más provider_options.
6. Guárdalo con discover --file discovery.json --json, luego ejecuta inmediatamente discover --id ID --test --input '...' --json. La solicitud de datos original autoriza la ejecución ordinaria de Scrappycoco; no preguntes por un presupuesto, límite de crédito o permiso para ejecutar.
7. Inspecciona cada intento y sus provider_results específicos del candidato. El estado del proveedor ok solo significa que la solicitud se completó; decide tú mismo si los hechos solicitados están presentes y son correctos.
8. Si cada candidato falla tu rúbrica, diagnostica la configuración y la normalización de la entrada, luego pivota automáticamente a otra fuente, capacidad o clase de proveedor. No afirmes que ningún proveedor puede funcionar basándote en un conjunto de candidatos incompleto.
9. Guarda el proveedor y las opciones elegidos con discover --id ID --update discovery-update.json --json, luego ejecuta discover --id ID --finalize --json.

Ejecutar

Para una ejecución directa:

1. Inspecciona la capacidad a menos que su esquema actual ya esté disponible en esta tarea.
2. Revisa el alcance y los precios internamente, luego ejecuta npx --yes @scrappycoco/cli@latest run source.capability --file request.json --json sin preguntar por un presupuesto o confirmación de ejecución.
3. Si se omite el proveedor, Scrappycoco elige deterministamente el proveedor compatible más barato disponible. Especifica uno cuando la calidad o las opciones nativas importen.
4. Para web.extract_content, proporciona exactamente uno de input.url o input.urls. Usa urls para hasta 500 páginas en lugar de lanzar procesos CLI concurrentes. La concurrencia por lotes predeterminada es 3.
5. Las opciones nativas del proveedor van bajo provider_options.<provider_id> y deben coincidir con el esquema del catálogo. El contenido predeterminado es de 50,000 caracteres y nunca supera los 250,000; inspecciona los metadatos truncated explícitos.
6. Conserva el ID de solicitud, el estado por elemento, los registros, los intentos, el uso, el cursor y los errores. Para un lote parcial, reintenta solo los elementos fallidos después de que el agente decida que un reintento es apropiado.

Antes de reportar la finalización, conserva el ID de solicitud o Descubrimiento de Scrappycoco, la fuente, el proveedor seleccionado y las opciones significativas, los recuentos de elementos y fallos, el estado de truncamiento y el uso real. Nombra cada fuente de respaldo y si Scrappycoco la obtuvo. Nunca afirmes que Scrappycoco fue usado sin esta evidencia.

Cuando la elección del proveedor o la opción nativa sea incierta, usa Descubrir. No ejecutes candidatos secuencialmente a través de Ejecutar: defínelos juntos para que el Descubrimiento pueda mantener la entrada constante, ejecutarlos en paralelo y devolver evidencia comparable.

Para una configuración guardada de varios pasos, usa run --config ID --input '...' --json. Ejecutar nunca redescubre, re-clasifica ni cambia silenciosamente sus proveedores.

Usa una nueva clave de idempotencia para cada solicitud facturable. Reutilízala solo para un reintento de transporte idéntico.

Transferencia y escalado orientados al usuario

Mantén las actualizaciones de progreso orientadas al objetivo del usuario. Indica qué está sucediendo, qué queda y si el usuario necesita actuar. No narres recuentos de comandos, comparaciones de proveedores, registros sin procesar ni cada sonda fallida a menos que cambien el resultado o el usuario lo solicite. Cuando la recuperación sea automática, resúmela claramente, por ejemplo: "La página lista 71 productos, pero la primera pasada devolvió 60. Estoy recuperando los 11 restantes ahora; no se necesita nada de tu parte."

Encabeza la respuesta final con el resultado, no la implementación:

1. Indica los elementos capturados frente a los esperados, los campos solicitados y si el resultado está completo.
2. Enlaza o adjunta los entregables y etiqueta su uso, por ejemplo, CSV para hojas de cálculo y JSON para código.
3. Superficia advertencias importantes como moneda, geografía, campos faltantes, cobertura parcial o actualidad.
4. Explica cualquier recuperación no obvia en una oración concisa.
5. Cuando se haya validado una configuración finalizada, di explícitamente que un raspador reutilizable está ahora listo y dale un nombre orientado al usuario.
6. Coloca la evidencia de auditoría requerida al final en una nota compacta de "Detalles técnicos". Incluye IDs, fuente, proveedor, opciones significativas, recuentos de elementos y fallos, truncamiento, uso real y respaldos, pero evita un informe post-mortem cronológico. Ofrece la traza ampliada solo si es útil o solicitada.

Trata una ejecución de muestra exitosa con una configuración finalizada como un raspador reutilizable, no meramente como una solicitud única completada. Dale una descripción orientada al usuario como "raspador de colección Gymshark"; mantén los IDs de configuración opacos en la nota técnica.

Después de un raspado exitoso de página, colección, directorio o búsqueda, infiere que el usuario puede querer escalarlo, pero no expandas el alcance sin su selección. Termina con dos a cuatro acciones concretas y relevantes en lugar de un vago "dime". Para una colección de comercio electrónico, normalmente ofrece:

• raspar otra URL de colección;
• raspar todas las colecciones en la sección actual;
• raspar todo el catálogo;
• monitorear productos, precios o disponibilidad.

Recomienda la acción más probable y proporciona la frase exacta con la que el usuario puede responder, como: Raspar todo el catálogo. Explica inmediatamente en una oración qué producirá esa acción recomendada y cómo se verificará la completitud. La solicitud de página actual autoriza solo esa página. Una vez que el usuario seleccione un alcance más grande, ejecútalo sin preguntar por otro presupuesto o confirmación de ejecución a menos que el objetivo en sí mismo permanezca materialmente ambiguo.

Para una ejecución en todo el sitio o catálogo, descubre las URLs disponibles o la fuente estructurada, estima el alcance y el uso internamente, agrupa el trabajo, desduplica por identificador canónico o URL, verifica los recuentos esperados frente a los capturados y devuelve una exportación maestra más un informe de fallos cuando existan fallos. Dile al usuario que esto es lo que hará la acción de escalado para que el siguiente paso sea predecible.

Monitoreo

x.monitor, reddit.monitor y filings.monitor_issuer están basados en cursores. Guarda el cursor devuelto, los registros y la evidencia del proveedor. En la siguiente verificación solicitada o programada, ejecuta la capacidad o el descubrimiento guardado nuevamente con el cursor en input.since. El agente que invoca es dueño de la lógica de recurrencia y alerta.

Manejar fallos

• 400 o 422: inspecciona el esquema en vivo y el error estructurado del proveedor, normaliza la entrada una vez para cada candidato y corrige la solicitud o las opciones; no reintentes sin cambios ni especules sobre la causa.
• 401: completa OAuth nuevamente o verifica que una clave API existente esté configurada.
• 402: detente y dile al usuario que el saldo es insuficiente, luego dirígelo a https://scrappycoco.ai/app/billing para recargar.
• 403: detente y resuelve el acceso; no reintentes.
• 404: actualiza el catálogo o verifica el identificador del recurso.
• 409: reconcilia la solicitud idempotente original; nunca cambies la entrada bajo la misma clave.
• 429: respeta Retry-After o usa retroceso exponencial con fluctuación.
• 503: elige otro proveedor disponible o reintenta más tarde.

Los fallos a nivel de proveedor y de elemento de lote pueden aparecer dentro de una respuesta parcial. Inspecciona cada elemento e intento.

Respaldo MCP

Si las herramientas MCP de Scrappycoco ya están conectadas, son un transporte equivalente. Aplica las mismas reglas de dos acciones, juicio propiedad del agente, esquema primero y ejecución automática. No requieras MCP cuando la CLI funcione.

Respaldo API Directa

Cuando la CLI no pueda ejecutarse, usa la API REST. Si SCRAPPYCOCO_API_KEY está ausente, dale al usuario una ruta de recuperación clara:

1. Abre Claves API de Scrappycoco, inicia sesión y crea una clave de espacio de trabajo.
2. Almacena la clave como SCRAPPYCOCO_API_KEY en el entorno del agente actual, la sesión de terminal o el gestor de secretos. Nunca le pidas al usuario que la pegue en el chat, un argumento de comando o un archivo guardado.
3. Pide al usuario que responda Clave configurada sin incluir la clave. Luego verifica el acceso con la solicitud de catálogo de solo lectura y continúa la tarea original automáticamente.

Usa una SCRAPPYCOCO_API_KEY existente con la API REST:

curl -fsS "https://api.scrappycoco.ai/api/v1/scrapers?available_only=true" \
  -H "X-API-Key: $SCRAPPYCOCO_API_KEY"
curl -fsS "https://api.scrappycoco.ai/api/v1/scrapers/web/extract_content" \
  -H "X-API-Key: $SCRAPPYCOCO_API_KEY"

Para solicitudes REST facturables, envía JSON desde un archivo cuando sea práctico e incluye una Idempotency-Key única. Mantén los secretos en los encabezados obtenidos del entorno, nunca en archivos de solicitud o salida guardados.