xdrop

xdrop skill 概览

xdrop 能做什么

xdrop skill 用于帮助 agent 将本地文件或目录上传到 Xdrop 服务器，也可以通过 Xdrop 分享链接把文件下载回本地，并在本地完成加密传输的解密。它尤其适合终端驱动的文件自动化场景：你需要可重复执行的命令、简洁可分享的 URL，以及可选的机器可读输出。

谁适合安装 xdrop skill

如果你符合以下情况，建议安装这个 xdrop skill：

• 需要在脚本或 agent 工作流中，通过 Xdrop 实例传输文件
• 经常收到类似 /t/<transferId>#k=... 的 Xdrop 链接，希望在本地完成下载和解密
• 需要稳定的 CLI 参数，比如 --json、--quiet、--output、--expires-in 或 --api-url
• 想要一个明确可用的上传/下载路径，而不是临时拼 raw HTTP 请求

xdrop 要解决的真实任务

多数用户并不是在抽象地寻找“文件分享 skill”。他们通常是想稳定自动化完成下面两件事之一：

1. 在终端里把本地文件转成一个 Xdrop 分享链接
2. 拿到现成的 Xdrop 链接后，不用猜协议细节，就能把文件完整恢复到本地

xdrop 的价值就在这里：它把这套流程封装成了两个可直接运行的脚本，而不是让 agent 自己去反向推断分享格式。

为什么 xdrop 不同于普通 prompt

普通 prompt 只能描述 Xdrop 大概会怎么工作；xdrop skill 则直接提供了可执行脚本，已经覆盖了实际操作路径：

• 通过 scripts/upload.mjs 上传
• 通过 scripts/download.mjs 解析分享链接并下载
• 默认使用预期的 API 根路径
• 支持安静模式和 JSON 输出，更适合自动化流水线

使用 xdrop 前先确认这些限制

在采用 xdrop 之前，请先确认以下前提：

• 运行附带脚本必须依赖 bun
• agent 需要有本地文件系统访问权限
• agent 需要能访问目标 Xdrop 服务器的网络
• 上传目标应为兼容 Xdrop 的服务器，而不是任意文件托管站点

如果你的环境无法运行 Bun，或者无法访问目标服务器，那么这份 xdrop 指南就不适合你的路径。

如何使用 xdrop skill

将 xdrop skill 安装到你的 skills 环境中

如果你使用 Skills 系统，可以通过下面的命令安装 xdrop：

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

安装后，重点查看这些 skill 目录文件：

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

为 xdrop 使用安装运行时依赖

这个 skill 本质上是基于脚本的，因此实际前置条件是 Bun。开始使用 xdrop 之前，先确认 Bun 可用：

bun --version

另外也请确认：

• 你能读取需要上传的本地文件
• 你能向下载输出目录写入文件
• 当前环境能够访问 Xdrop 服务器

先读这些文件，能更快判断是否适合

如果你想快速评估 xdrop，建议按这个顺序阅读：

1. SKILL.md：了解支持的工作流和参数
2. scripts/upload.mjs：确认上传参数和限制
3. scripts/download.mjs：了解分享链接解析和输出行为

通常按这个顺序读完，就足够判断 xdrop for File Automation 是否适合你的流水线。

先理解 xdrop 的两个核心入口

xdrop skill 的定位很明确，范围也刻意收窄。你主要会调用下面两个入口之一：

• 上传：

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

• 下载：

  bun scripts/download.mjs <share-url>
  

如果你要的是可靠的文件传输自动化，而不是一个覆盖面很广的 SDK，这种聚焦反而是优势。

用 xdrop 上传文件

最基础的上传命令如下：

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

也可以一次上传多个路径：

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

这种方式适合用户需求是“把这些本地文件分享出去，并给我一个链接”，而不适合需要存储同步、文件浏览或账号管理功能的场景。

在自动化场景中优先使用这些 xdrop 上传参数

真正用于自动化时，最有价值的参数通常是：

• --json：便于下游结构化解析
• --quiet：保持 stdout 干净
• --expires-in <sec>：控制传输有效期
• --name <value>：设置传输名称
• --api-url <url>：当 API 根路径不是默认值时使用
• --concurrency <n>：调整并行上传行为

示例：

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

对于 agent 工作流来说，--json 非常关键，因为它会直接返回 transferId、shareUrl、expiresAt 等字段，而不需要你再去做脆弱的文本提取。

通过分享链接下载并解密 xdrop 内容

最主要的下载场景，是使用带有 key fragment 的完整 Xdrop 分享 URL：

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

这个脚本会解析分享链接、拉取传输元数据、下载加密内容，并在本地完成解密。这正是相比手写 prompt，更值得优先使用 xdrop skill 的原因：带 key 的链接格式已经替你处理好了。

用 xdrop 干净地控制下载输出

默认情况下，下载结果会进入类似 ./xdrop-<transferId> 这样的目录。如果你的工作流要求固定路径，就应显式覆盖：

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

常用参数包括：

• --output <dir>：把文件稳定落到指定目录
• --json：输出机器可读结果
• --quiet：让日志更干净
• --api-url <url>：当 API 根路径不是 <share-origin>/api/v1 时使用

把模糊需求改写成高质量的 xdrop prompt

较弱的请求：

upload this file to xdrop

更好的请求：

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.

较弱的请求：

fetch this xdrop link

更好的请求：

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

高质量的 xdrop 使用请求通常会包含：

• 服务器 URL 或完整分享 URL
• 精确的本地文件路径
• 期望的输出目录
• 输出是纯文本还是 JSON
• 上传是否需要过期时间

xdrop for File Automation 的最佳工作流

一个更实用的工作流是：

1. 先确认 Bun 和网络访问正常
2. 先用小文件测试
3. 命令跑通后再切到 --json
4. 如果 stdout 还要被其他脚本或 agent 解析，再加上 --quiet
5. 最后再处理更大的传输或多文件传输

这样可以明显减少排错时间，因为大多数失败都来自环境问题、路径错误或服务器不可达，而不是传输逻辑本身。

xdrop 的实际限制与取舍

从脚本体现出的信号来看，xdrop 优化的是直接、明确的传输流程，而不是无限制的大规模搬运。上传脚本定义了：

• 最大并发上限为 6
• 最大传输大小为 256 * 1024 * 1024 字节

这意味着，这份 xdrop 指南更适合短期分享和自动化任务，而不是超大体量的归档型工作流。

xdrop skill 常见问题

xdrop skill 对新手友好吗

如果你已经能熟练在终端里运行 Bun 脚本，那么是友好的。接口本身并不复杂，但新手仍然可能在下面这些地方需要帮助：

• 安装 Bun
• 传入正确的文件系统路径
• 理解 site URL 和 API URL 的区别
• 在分享链接中保留 #k=... 这一段

什么情况下 xdrop 比普通 prompt 更合适

当你需要的是执行，而不是解释时，xdrop skill 更合适。普通 prompt 可以描述 Xdrop，但这个 skill 直接提供了具体的上传/下载路径，并且已经内置了正确参数和本地解密流程。

使用 xdrop 时我需要提供哪些输入

上传时需要：

• 通过 --server 提供公开可访问的 Xdrop 站点 URL
• 一个或多个本地文件或目录路径

下载时需要：

• 一个完整的分享 URL，最好包含 key fragment
• 可选的输出目录和 API 覆盖参数

缺少这些输入时，agent 就不得不猜，而 xdrop 的使用质量会很快下降。

下载时必须提供完整的分享 URL 吗

是的，实际使用中应当提供完整的 Xdrop 链接。下载脚本明确要求完整分享链接，并依赖它来提取 transfer ID、origin 和 key material。只有裸的 transfer ID，并不足以完成整套本地解密流程。

xdrop 适合接入 CI 或脚本流水线吗

适合。这正是安装 xdrop 的最佳理由之一。对 --json 和 --quiet 的支持，使它非常适用于 shell 脚本、CI 任务，以及要求 stdout 可解析的 agent 链路。

什么情况下不该使用 xdrop

以下情况建议跳过 xdrop：

• 你无法运行 Bun
• 你需要的是浏览器优先的交互体验，而不是终端自动化
• 你需要的不只是上传/下载自动化
• 目标并不是兼容 Xdrop 的服务器
• 你的工作流涉及超出脚本设计传输限制的文件规模

如何提升 xdrop skill 的使用效果

为 xdrop 提供完整且无歧义的输入

提升 xdrop 结果质量的最快方式，就是一开始就把所有操作输入说清楚：

• 精确文件路径
• 精确服务器 URL 或分享 URL
• 期望的过期时间
• 期望的输出目录
• 是否需要 JSON
• stdout 是否必须保持安静

这样可以消除大部分猜测空间，也能减少来回修正。

保留分享 URL 中的 fragment

xdrop 使用中一个很常见的失败模式，是链接在不同工具之间复制时丢失了 #k=... 这段。如果这部分缺失，即使 transfer ID 是有效的，本地解密也可能失败。要明确告诉用户：必须原样传入完整 URL。

下游自动化优先使用 JSON

如果结果还要被其他工具、脚本或 agent 消费，优先选择：

• 上传时加 --json
• 下载时加 --json

这样可靠性更高，因为你不需要再解析面向人的控制台文本。

先用小文件跑通，再逐步放大

为了获得更稳的 xdrop for File Automation 效果，先用小文件验证完整往返流程：

1. 上传一个小测试文件
2. 记录返回的分享 URL
3. 把它下载到临时目录
4. 确认文件内容符合预期

这样能在你投入时间排查大传输之前，先隔离环境和服务器问题。

有意识地使用 output 和 quiet 参数

两个看似很小的选择，往往能显著提升质量：

• 如果后续步骤依赖下载路径，就使用 --output
• 如果日志会干扰机器解析，就使用 --quiet

这些参数看起来不起眼，但在真实流水线里影响很大。

只在必要时调整并发

上传脚本支持 --concurrency，但并不是越高越好。只有在你确定服务器和网络路径能承受更高并行度时，再提高它。否则，保持默认行为，优先换取可预测的完成效果。

尽早处理服务器特定的 API 差异

如果你的 Xdrop 部署把 API 暴露在默认 <server>/api/v1 之外的位置，应当一开始就设置 --api-url，而不是等到后面排查一些看起来莫名其妙的失败。这是 xdrop 看起来没问题、却始终无法和服务器通信时，最该优先检查的点之一。

用可直接执行的细节改进首次 xdrop prompt

一个更强的 xdrop 提示写法如下：

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`.

它之所以有效，是因为：

• 直接点名了 skill
• 提供了明确的源文件路径
• 明确指定了服务器、过期时间和输出格式
• 规定了期望的响应结构

优先排查最可能出错的环节

如果 xdrop 失败，建议按这个顺序检查：

1. Bun 已安装且可运行
2. 本地路径确实存在
3. 服务器 URL 可以访问
4. 完整分享 URL 包含 #k=...
5. API 根路径是否需要 --api-url
6. 是否超出了传输大小或环境限制

通常按这个顺序排查，比通读整个仓库更快定位问题。

首次结果不理想时，下一步该改什么

如果第一次运行 xdrop 的结果混乱或不完整，可以优先这样调整：

• 如果输出难以解析，就加上 --json
• 如果日志污染了 stdout，就加上 --quiet
• 如果文件落到了错误位置，就加上 --output
• 把模糊的文件描述改成精确路径
• 先对本地或已知可用的 Xdrop 服务器测试，再决定是否怀疑脚本本身

这些调整通常比重写整套工作流，更能显著改善第二次运行效果。