xdrop

Visão geral da skill xdrop

O que a xdrop faz

A skill xdrop ajuda um agente a enviar arquivos ou diretórios locais para um servidor Xdrop e a baixar arquivos de volta a partir de um link de compartilhamento do Xdrop, incluindo a descriptografia local de transferências criptografadas. Ela é mais indicada para automação de arquivos via terminal, quando você quer um comando repetível, uma URL de compartilhamento limpa e, opcionalmente, saída legível por máquina.

Quem deve instalar a skill xdrop

Instale esta skill xdrop se você:

• move arquivos por uma instância Xdrop a partir de scripts ou fluxos de trabalho com agentes
• recebe links Xdrop como /t/<transferId>#k=... e quer baixar e descriptografar localmente
• precisa de flags de CLI estáveis como --json, --quiet, --output, --expires-in ou --api-url
• quer um caminho concreto para upload/download em vez de improvisar chamadas HTTP brutas

Trabalho real que ela resolve

A maioria dos usuários não está procurando “uma skill de compartilhamento de arquivos” em abstrato. O que eles precisam é automatizar, com confiabilidade, uma de duas tarefas:

1. transformar arquivos locais em um link de compartilhamento Xdrop pelo terminal
2. pegar um link Xdrop já existente e restaurar os arquivos localmente sem precisar adivinhar o protocolo

É aí que a xdrop é útil: ela empacota o fluxo em dois scripts executáveis, em vez de deixar o agente tentar deduzir o formato do compartilhamento.

Por que a xdrop é diferente de um prompt genérico

Um prompt genérico pode descrever como o Xdrop talvez funcione. A skill xdrop entrega scripts executáveis que já cobrem o caminho prático:

• upload via scripts/upload.mjs
• parsing de links de compartilhamento e download via scripts/download.mjs
• uso do endpoint de API esperado por padrão
• suporte a saída silenciosa e JSON para pipelines mais amigáveis à automação

Principais restrições para saber antes

Antes de adotar a xdrop, confirme estes requisitos:

• bun é necessário para executar os scripts incluídos
• o agente precisa de acesso ao sistema de arquivos local
• o agente precisa de acesso de rede ao servidor Xdrop de destino
• os uploads são voltados a servidores compatíveis com Xdrop, não a hosts de arquivos arbitrários

Se o seu ambiente não consegue executar Bun ou não consegue acessar o servidor de destino, este guia da xdrop não é o caminho certo.

Como usar a skill xdrop

Instale a skill xdrop no seu setup de skills

Se você usa o sistema de Skills, instale a xdrop com:

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

Depois, trabalhe a partir destes arquivos do diretório da skill:

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

Instale os requisitos de runtime para usar a xdrop

A skill em si é baseada em scripts, então o pré-requisito prático é o Bun. Verifique se o Bun está disponível antes de tentar usar a xdrop:

bun --version

Também confirme que:

• você consegue ler os arquivos locais que quer enviar
• você consegue gravar no diretório de saída dos downloads
• o servidor Xdrop está acessível a partir do seu ambiente

Leia estes arquivos primeiro

Para uma avaliação rápida, leia nesta ordem:

1. SKILL.md para entender o fluxo suportado e as flags
2. scripts/upload.mjs para ver os argumentos de upload e os limites
3. scripts/download.mjs para entender o parsing do link de compartilhamento e o comportamento da saída

Essa ordem de leitura normalmente já basta para decidir se a xdrop para Automação de Arquivos se encaixa no seu pipeline.

Entenda os dois pontos de entrada principais

A skill xdrop é propositalmente enxuta. Na prática, você vai chamar um destes comandos:

• Upload:

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

• Download:

  bun scripts/download.mjs <share-url>
  

Esse escopo restrito é uma vantagem quando você quer automação de transferência de arquivos confiável, e não um SDK amplo.

Faça upload de arquivos com a xdrop

Um upload básico fica assim:

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

Você também pode enviar vários caminhos de uma vez:

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

Use isso quando o objetivo do usuário for “compartilhe estes arquivos locais e me devolva um link”, e não quando ele precisar de sincronização de armazenamento, navegação ou recursos de gerenciamento de conta.

Use flags de upload amigáveis para automação

As flags mais úteis para automação real são:

• --json para parsing estruturado nas etapas seguintes
• --quiet para manter o stdout limpo
• --expires-in <sec> para controlar a duração da transferência
• --name <value> para definir um rótulo da transferência
• --api-url <url> caso o endpoint da API não seja o padrão
• --concurrency <n> para ajustar o comportamento de upload em paralelo

Exemplo:

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

Em fluxos com agentes, --json faz bastante diferença porque retorna campos como transferId, shareUrl e expiresAt, em vez de obrigar você a extrair informação de texto livre de forma frágil.

Faça download e descriptografe a partir de um link de compartilhamento

O caso principal de download é uma URL completa de compartilhamento Xdrop contendo o fragmento da chave:

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

O script interpreta o link de compartilhamento, busca os metadados da transferência, baixa o conteúdo criptografado e o descriptografa localmente. Esse é o principal motivo para preferir a skill xdrop a um prompt escrito à mão: o formato do link com a chave já é tratado para você.

Controle com precisão a saída do download

Por padrão, os downloads vão para um diretório como ./xdrop-<transferId>. Substitua isso quando o seu fluxo esperar um caminho específico:

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

Flags úteis:

• --output <dir> para posicionamento determinístico dos arquivos
• --json para saída de resultado legível por máquina
• --quiet para logs mais limpos
• --api-url <url> quando o endpoint da API for diferente de <share-origin>/api/v1

Transforme uma intenção vaga em um bom prompt para xdrop

Pedido fraco:

faça upload deste arquivo para xdrop

Pedido melhor:

Use a skill xdrop para enviar ./build/app.tar.gz para https://xdrop.example.com, definir expiração de 600 segundos, retornar apenas JSON e manter o stdout silencioso.

Pedido fraco:

busque este link xdrop

Pedido melhor:

Use xdrop para baixar https://xdrop.example.com/t/abc#k=..., salvar em ./artifacts/incoming e retornar o caminho de saída em JSON.

Bons prompts de uso da xdrop incluem:

• a URL do servidor ou a URL completa de compartilhamento
• os caminhos locais exatos dos arquivos
• o diretório de saída desejado
• se a saída deve ser texto simples ou JSON
• a necessidade de expiração no upload

Melhor fluxo de trabalho com xdrop para Automação de Arquivos

Um fluxo prático é:

1. verificar Bun e acesso de rede
2. testar primeiro com um arquivo pequeno
3. mudar para --json quando o comando estiver funcionando
4. adicionar --quiet se outro script ou agente for fazer parsing do stdout
5. só então partir para transferências maiores ou com múltiplos arquivos

Isso reduz o tempo de depuração porque a maioria das falhas vem de problemas de ambiente, erros de caminho ou falta de acesso ao servidor, e não da lógica de transferência em si.

Limites práticos e trade-offs

Pelos sinais do script, a xdrop é otimizada para transferências diretas, não para movimentação em massa sem limites. O script de upload define:

• concorrência máxima limitada a 6
• tamanho máximo de transferência de 256 * 1024 * 1024 bytes

Isso significa que este guia da xdrop se encaixa melhor em tarefas de compartilhamento temporário e automação do que em fluxos de arquivamento muito grandes.

FAQ da skill xdrop

A skill xdrop é amigável para iniciantes?

Sim, se você se sente confortável executando scripts Bun pelo terminal. A interface é simples, mas iniciantes ainda podem precisar de ajuda com:

• instalação do Bun
• passagem correta dos caminhos no sistema de arquivos
• entendimento da diferença entre URL do site e URL da API
• preservação do fragmento #k=... em um link de compartilhamento

Quando a xdrop é melhor do que um prompt normal?

A skill xdrop é melhor quando você precisa de execução, não de explicação. Um prompt normal pode descrever o Xdrop, mas esta skill entrega um caminho concreto de upload/download, com as flags corretas e o fluxo de descriptografia local já codificados.

Que entrada a xdrop precisa de mim?

Para upload:

• uma URL pública do site Xdrop via --server
• um ou mais caminhos locais de arquivo ou diretório

Para download:

• uma URL completa de compartilhamento, de preferência incluindo o fragmento da chave
• opcionalmente, um diretório de saída e um override da API

Sem essas entradas, o agente terá de adivinhar, e a qualidade de uso da xdrop cai rapidamente.

Preciso da URL completa de compartilhamento para fazer download?

Sim. Na prática, você deve fornecer o link completo do Xdrop. O script de download espera explicitamente um link de compartilhamento completo e o usa para derivar o ID da transferência, a origem e o material de chave. Um transferId isolado não basta para o fluxo completo de descriptografia local.

A xdrop funciona bem em CI ou pipelines com scripts?

Sim. Esse é um dos melhores motivos para instalar a xdrop. O suporte a --json e --quiet a torna adequada para scripts shell, jobs de CI e cadeias de agentes em que o stdout precisa continuar parseável.

Quando eu não devo usar a xdrop?

Evite a xdrop se:

• você não consegue executar Bun
• você precisa de uma experiência centrada no navegador, e não em automação via terminal
• você precisa de recursos além da automação de upload/download
• o seu destino não é um servidor compatível com Xdrop
• o seu fluxo envolve arquivos acima dos limites de transferência pretendidos pelo script

Como melhorar o uso da skill xdrop

Dê à xdrop entradas completas e sem ambiguidade

A forma mais rápida de melhorar os resultados com a xdrop é especificar todos os parâmetros operacionais logo de início:

• caminhos exatos dos arquivos
• URL exata do servidor ou do compartilhamento
• expiração desejada
• diretório de saída desejado
• se você quer JSON
• se o stdout deve permanecer silencioso

Isso elimina a maior parte das suposições e evita correções posteriores.

Preserve o fragmento da URL de compartilhamento

Um modo comum de falha no uso da xdrop é perder o fragmento #k=... ao copiar links entre ferramentas. Se esse fragmento estiver ausente, a descriptografia local pode falhar mesmo que o ID da transferência seja válido. Oriente os usuários explicitamente a enviar a URL completa sem alterações.

Prefira JSON para automação downstream

Se outra ferramenta, script ou agente for consumir o resultado, prefira:

• upload com --json
• download com --json

Isso melhora a confiabilidade porque evita parsing de texto de console voltado para humanos.

Teste com uma transferência pequena antes de escalar

Para obter melhores resultados com a xdrop para Automação de Arquivos, valide o ciclo completo primeiro com um arquivo pequeno:

1. envie um pequeno arquivo de teste
2. capture a URL de compartilhamento retornada
3. baixe o arquivo em um diretório temporário
4. confirme que o conteúdo do arquivo corresponde ao esperado

Isso isola problemas de ambiente e de servidor antes que você gaste tempo depurando transferências grandes.

Use --output e --quiet de forma intencional

Duas escolhas pequenas melhoram bastante a qualidade:

• use --output quando o caminho do download for importante para etapas posteriores
• use --quiet quando os logs puderem atrapalhar o parsing automático

Essas flags parecem pequenas no papel, mas têm alto impacto em pipelines reais.

Ajuste a concorrência só quando necessário

O script de upload aceita --concurrency, mas nem sempre aumentar esse valor é melhor. Só aumente se você tiver certeza de que o servidor e o caminho de rede conseguem lidar com mais trabalho em paralelo. Caso contrário, mantenha o comportamento padrão e priorize conclusão previsível.

Trate diferenças de API específicas do servidor logo no início

Se a sua implantação do Xdrop expõe a API em um lugar diferente do padrão <server>/api/v1, defina --api-url imediatamente em vez de perder tempo depurando falhas misteriosas depois. Esse é um dos primeiros pontos a verificar quando a xdrop parece correta, mas não consegue se comunicar com o servidor.

Melhore os prompts iniciais com detalhes executáveis

Um bom guia de prompting para xdrop fica assim:

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 que isso funciona:

• menciona a skill diretamente
• fornece o caminho de origem concreto
• especifica servidor, expiração e formato de saída
• define o formato esperado da resposta

Diagnostique primeiro os pontos de falha mais prováveis

Se a xdrop falhar, verifique nesta ordem:

1. o Bun está instalado e executável
2. os caminhos locais realmente existem
3. a URL do servidor está acessível
4. a URL completa de compartilhamento inclui #k=...
5. o endpoint da API precisa de --api-url
6. os limites de transferência ou restrições do ambiente estão sendo excedidos

Essa ordem normalmente resolve os problemas mais rápido do que ler o repositório inteiro.

O que mudar depois de um primeiro resultado fraco

Se a primeira execução com xdrop sair confusa ou incompleta:

• adicione --json se o parsing da saída estiver frágil
• adicione --quiet se os logs estiverem poluindo o stdout
• adicione --output se os arquivos caírem no lugar errado
• substitua referências vagas a arquivos por caminhos exatos
• teste contra um servidor Xdrop local ou sabidamente funcional antes de culpar o script

Essas mudanças normalmente melhoram mais a segunda execução do que reescrever todo o fluxo.