xdrop

Visión general de la skill xdrop

Qué hace xdrop

La skill xdrop ayuda a un agente a subir archivos o directorios locales a un servidor Xdrop y a descargar archivos desde un enlace compartido de Xdrop, incluida la desencriptación local de transferencias cifradas. Encaja mejor en automatizaciones de archivos desde terminal cuando necesitas un comando repetible, una URL de compartición limpia y, opcionalmente, salida legible por máquinas.

Quién debería instalar la skill xdrop

Instala esta skill xdrop si:

• mueves archivos a través de una instancia de Xdrop desde scripts o flujos de trabajo de agentes
• recibes enlaces de Xdrop como /t/<transferId>#k=... y quieres descarga local más desencriptación
• necesitas flags de CLI estables como --json, --quiet, --output, --expires-in o --api-url
• quieres una ruta concreta de subida y descarga en lugar de improvisar llamadas HTTP en bruto

La tarea real que resuelve

La mayoría de usuarios no buscan “una skill para compartir archivos” en abstracto. Necesitan automatizar de forma fiable una de estas dos tareas:

1. convertir archivos locales en un enlace compartido de Xdrop desde la terminal
2. tomar un enlace existente de Xdrop y restaurar los archivos localmente sin tener que adivinar el protocolo

Ahí es donde xdrop resulta útil: empaqueta el flujo en dos scripts ejecutables en lugar de obligar al agente a reconstruir por ingeniería inversa el formato de compartición.

Por qué xdrop es diferente de un prompt genérico

Un prompt genérico puede describir cómo podría funcionar Xdrop. La skill xdrop aporta scripts ejecutables que ya resuelven la parte práctica:

• subir mediante scripts/upload.mjs
• analizar enlaces compartidos y descargar mediante scripts/download.mjs
• usar por defecto la raíz de API esperada
• admitir salida silenciosa y en JSON para pipelines más aptos para automatización

Restricciones clave que debes conocer primero

Antes de adoptar xdrop, confirma estos requisitos:

• se necesita bun para ejecutar los scripts incluidos
• el agente necesita acceso al sistema de archivos local
• el agente necesita acceso de red al servidor Xdrop de destino
• las subidas están pensadas para servidores compatibles con Xdrop, no para hosts de archivos arbitrarios

Si tu entorno no puede ejecutar Bun o no puede acceder al servidor de destino, esta guía de xdrop no es la vía adecuada.

Cómo usar la skill xdrop

Instalar la skill xdrop en tu entorno de skills

Si usas el sistema Skills, instala xdrop con:

npx skills add https://github.com/xixu-me/skills --skill xdrop

Después, trabaja desde los archivos del directorio de la skill:

• skills/xdrop/SKILL.md
• skills/xdrop/scripts/upload.mjs
• skills/xdrop/scripts/download.mjs

Instalar los requisitos de ejecución para usar xdrop

La skill se basa en scripts, así que el requisito práctico principal es Bun. Comprueba que Bun está disponible antes de intentar usar xdrop:

bun --version

Verifica también que:

• puedes leer los archivos locales que quieres subir
• puedes escribir en el directorio de salida de las descargas
• el servidor Xdrop es accesible desde tu entorno

Lee primero estos archivos

Para evaluar rápido la skill, léelos en este orden:

1. SKILL.md para entender el flujo compatible y los flags
2. scripts/upload.mjs para ver los argumentos de subida y sus límites
3. scripts/download.mjs para revisar el análisis de enlaces compartidos y el comportamiento de salida

Ese orden de lectura suele bastar para decidir si xdrop para automatización de archivos encaja en tu pipeline.

Entiende los dos puntos de entrada principales

La skill xdrop es deliberadamente acotada. En la práctica, llamarás a uno de estos dos comandos:

• Subida:

  bun scripts/upload.mjs --server <xdrop-site-url> <file-or-directory> [...]
  

• Descarga:

  bun scripts/download.mjs <share-url>
  

Ese alcance limitado es una ventaja si buscas una automatización fiable de transferencias de archivos, y no un SDK amplio.

Subir archivos con xdrop

Una subida básica se ve así:

bun scripts/upload.mjs --server http://localhost:8080 ./dist/report.pdf

También puedes subir varias rutas:

bun scripts/upload.mjs --server https://xdrop.example.com ./photo.jpg ./notes.txt

Úsalo cuando el objetivo del usuario sea “comparte estos archivos locales y dame un enlace”, no cuando necesite sincronización de almacenamiento, navegación o funciones de gestión de cuenta.

Usar flags de subida pensados para automatización

Los flags más útiles para automatización real son:

• --json para análisis estructurado aguas abajo
• --quiet para mantener limpio stdout
• --expires-in <sec> para controlar la vida útil de la transferencia
• --name <value> para definir una etiqueta de transferencia
• --api-url <url> si la raíz de API no es la predeterminada
• --concurrency <n> para ajustar el comportamiento de subida en paralelo

Ejemplo:

bun scripts/upload.mjs \
  --server http://localhost:8080 \
  --expires-in 600 \
  --json \
  --quiet \
  ./notes.txt

En flujos de trabajo con agentes, --json importa mucho porque devuelve campos como transferId, shareUrl y expiresAt en lugar de obligarte a extraer texto de forma frágil.

Descargar y desencriptar desde un enlace compartido

El caso principal de descarga es una URL completa de compartición de Xdrop que incluya el fragmento de clave:

bun scripts/download.mjs "http://localhost:8080/t/abc#k=..."

El script analiza el enlace compartido, recupera los metadatos de la transferencia, descarga el contenido cifrado y lo desencripta localmente. Esta es la razón principal para preferir la skill xdrop frente a un prompt escrito a mano: el formato de enlace con clave ya viene resuelto.

Controlar con precisión la salida de descarga

Por defecto, las descargas van a un directorio como ./xdrop-<transferId>. Cámbialo cuando tu flujo espere una ruta concreta:

bun scripts/download.mjs --output ./downloads "http://localhost:8080/t/abc#k=..."

Flags útiles:

• --output <dir> para ubicar los archivos en una ruta determinista
• --json para salida de resultados legible por máquinas
• --quiet para logs más limpios
• --api-url <url> cuando la raíz de API difiere de <share-origin>/api/v1

Convertir una intención vaga en un buen prompt para xdrop

Solicitud débil:

upload this file to xdrop

Mejor solicitud:

Use the xdrop skill to upload ./build/app.tar.gz to https://xdrop.example.com, set expiry to 600 seconds, return JSON only, and keep stdout quiet.

Solicitud débil:

fetch this xdrop link

Mejor solicitud:

Use xdrop to download https://xdrop.example.com/t/abc#k=..., save it under ./artifacts/incoming, and return the output path as JSON.

Los buenos prompts de uso de xdrop incluyen:

• la URL del servidor o la URL completa de compartición
• rutas locales exactas de los archivos
• el directorio de salida deseado
• si la salida debe ser texto plano o JSON
• requisitos de expiración para las subidas

Mejor flujo de trabajo con xdrop para automatización de archivos

Un flujo práctico es:

1. verificar Bun y el acceso de red
2. probar primero con un archivo pequeño
3. cambiar a --json una vez que el comando funcione
4. añadir --quiet si otro script o agente va a analizar stdout
5. solo entonces pasar a transferencias grandes o de varios archivos

Esto reduce el tiempo de depuración porque la mayoría de fallos vienen del entorno, de rutas incorrectas o de problemas de acceso al servidor, no de la lógica de transferencia en sí.

Límites prácticos y compromisos

Por las señales que dan los scripts, xdrop está optimizado para transferencias directas, no para mover volúmenes ilimitados. El script de subida define:

• concurrencia máxima limitada a 6
• tamaño máximo de transferencia de 256 * 1024 * 1024 bytes

Eso significa que esta guía de xdrop encaja mejor con tareas de compartición efímera y automatización que con flujos de archivado muy grandes.

Preguntas frecuentes sobre la skill xdrop

¿La skill xdrop es fácil de usar para principiantes?

Sí, si te sientes cómodo ejecutando scripts de Bun desde la terminal. La interfaz es simple, pero aun así quien empieza puede necesitar ayuda con:

• instalar Bun
• pasar rutas correctas del sistema de archivos
• entender la diferencia entre la URL del sitio y la URL de la API
• conservar el fragmento #k=... en un enlace compartido

¿Cuándo es mejor xdrop que un prompt normal?

La skill xdrop es mejor cuando necesitas ejecución, no explicación. Un prompt normal puede describir Xdrop, pero esta skill ofrece una ruta concreta de subida y descarga con los flags adecuados y el flujo de desencriptación local ya incorporado.

¿Qué datos necesita xdrop por mi parte?

Para subir:

• una URL pública del sitio Xdrop mediante --server
• una o más rutas locales de archivos o directorios

Para descargar:

• una URL completa de compartición, idealmente con el fragmento de clave incluido
• opcionalmente, un directorio de salida y una API alternativa

Sin esos datos, un agente tendrá que adivinar, y la calidad de uso de xdrop cae rápidamente.

¿Necesito la URL completa de compartición para descargar?

Sí. En la práctica, deberías proporcionar el enlace completo de Xdrop. El script de descarga espera explícitamente un enlace completo y lo usa para derivar el ID de transferencia, el origen y el material de clave. Un transferId sin más no basta para completar todo el flujo de desencriptación local.

¿Puede xdrop encajar en CI o en pipelines con scripts?

Sí. De hecho, esta es una de las mejores razones para instalar xdrop. La compatibilidad con --json y --quiet lo hace adecuado para scripts de shell, trabajos de CI y cadenas de agentes donde stdout debe seguir siendo analizable.

¿Cuándo no debería usar xdrop?

Omite xdrop si:

• no puedes ejecutar Bun
• necesitas una experiencia prioritaria en navegador en lugar de automatización por terminal
• necesitas funciones más allá de la automatización de subida y descarga
• tu destino no es un servidor compatible con Xdrop
• tu flujo implica archivos que superan los límites de transferencia previstos por el script

Cómo mejorar la skill xdrop

Da a xdrop entradas completas y sin ambigüedades

La forma más rápida de mejorar los resultados con xdrop es especificar desde el principio todas las entradas operativas:

• rutas exactas de archivos
• URL exacta del servidor o del enlace compartido
• expiración deseada
• directorio de salida deseado
• si quieres JSON
• si stdout debe permanecer silencioso

Eso elimina la mayor parte de las suposiciones y evita correcciones posteriores.

Conserva el fragmento de la URL compartida

Un fallo habitual al usar xdrop es perder el fragmento #k=... al copiar enlaces entre herramientas. Si ese fragmento falta, la desencriptación local puede fallar aunque el ID de transferencia sea válido. Indica claramente a los usuarios que deben pasar la URL completa sin modificar.

Prioriza JSON para automatización aguas abajo

Si otra herramienta, script o agente va a consumir el resultado, conviene usar:

• subida con --json
• descarga con --json

Esto mejora la fiabilidad porque evita tener que analizar texto de consola pensado para humanos.

Prueba con una transferencia pequeña antes de escalar

Para obtener mejores resultados con xdrop para automatización de archivos, valida primero la vuelta completa con un archivo pequeño:

1. sube un archivo de prueba pequeño
2. captura la share URL devuelta
3. descárgalo en un directorio temporal
4. confirma que el contenido del archivo coincide con lo esperado

Así aislas problemas del entorno y del servidor antes de perder tiempo depurando transferencias grandes.

Usa deliberadamente los flags de salida y silencio

Dos decisiones pequeñas mejoran mucho la calidad:

• usa --output cuando la ruta descargada importe para pasos posteriores
• usa --quiet cuando los logs puedan interferir con el análisis automático

Sobre el papel parecen flags menores, pero en pipelines reales tienen mucho impacto.

Ajusta la concurrencia solo cuando haga falta

El script de subida admite --concurrency, pero más alto no siempre significa mejor. Auméntalo solo si tienes claro que el servidor y la red pueden manejar más trabajo en paralelo. Si no, mantén el comportamiento predeterminado y prioriza una finalización predecible.

Detecta pronto las diferencias de API específicas del servidor

Si tu despliegue de Xdrop expone la API en un lugar distinto del predeterminado <server>/api/v1, establece --api-url desde el principio en vez de depurar fallos confusos más tarde. Es una de las primeras cosas que conviene revisar cuando xdrop parece correcto pero no logra comunicarse con el servidor.

Mejora los primeros prompts con detalles ejecutables

Una guía sólida de xdrop para redactar prompts se vería así:

Use the xdrop skill. Upload `./release.zip` to `https://xdrop.example.com`.
Set `--expires-in 1800`, return `--json`, and suppress progress with `--quiet`.
If the upload succeeds, report only `shareUrl` and `expiresAt`.

Por qué funciona:

• nombra la skill de forma directa
• aporta la ruta de origen concreta
• especifica servidor, expiración y formato de salida
• define la forma esperada de la respuesta

Diagnostica primero los puntos de fallo más probables

Si xdrop falla, comprueba esto en este orden:

1. Bun está instalado y se puede ejecutar
2. las rutas locales realmente existen
3. la URL del servidor es accesible
4. la URL completa de compartición incluye #k=...
5. la raíz de API necesita --api-url
6. se están superando los límites de transferencia o las restricciones del entorno

Ese orden suele resolver incidencias más rápido que ponerse a leer todo el repositorio.

Qué cambiar después de un primer resultado flojo

Si la primera ejecución de xdrop sale desordenada o incompleta:

• añade --json si analizar la salida fue frágil
• añade --quiet si los logs ensuciaron stdout
• añade --output si los archivos acabaron en el lugar equivocado
• sustituye referencias vagas a archivos por rutas exactas
• prueba contra un servidor Xdrop local o conocido antes de culpar al script

Estos cambios suelen mejorar más la segunda ejecución que reescribir todo el flujo.