xdrop

xdrop skill 概覽

xdrop 能做什麼

xdrop skill 可協助 agent 將本機檔案或目錄上傳到 Xdrop 伺服器，也能從 Xdrop 分享連結把檔案下載回來，包含在本機端解密加密傳輸內容。它特別適合以終端機為核心的檔案自動化情境：你需要可重複執行的指令、乾淨好分享的 URL，以及可選的機器可讀輸出。

哪些人適合安裝 xdrop skill

如果你符合以下情況，建議安裝這個 xdrop skill：

• 會在 script 或 agent workflow 中透過 Xdrop instance 傳遞檔案
• 會收到像 /t/<transferId>#k=... 這類 Xdrop 連結，並希望在本機完成下載與解密
• 需要穩定的 CLI 參數，例如 --json、--quiet、--output、--expires-in 或 --api-url
• 想要一條明確可執行的上傳／下載路徑，而不是自行拼湊 raw HTTP calls

真正要解決的工作

多數使用者其實不是在抽象地尋找「檔案分享 skill」。他們通常是想可靠地自動化以下兩件事之一：

1. 在終端機中把本機檔案轉成 Xdrop 分享連結
2. 取得既有的 Xdrop 連結後，在不猜協定細節的前提下，把檔案完整還原到本機

xdrop 的價值就在這裡：它把整個流程封裝成兩支可直接執行的 script，而不是讓 agent 自己反推分享格式。

為什麼 xdrop 和一般 prompt 不一樣

一般 prompt 可以描述 Xdrop 可能怎麼運作；xdrop skill 則直接提供可執行的 script，已經把實務流程處理好：

• 透過 scripts/upload.mjs 上傳
• 透過 scripts/download.mjs 解析分享連結並下載
• 預設使用預期的 API root
• 支援安靜模式與 JSON 輸出，方便串進自動化 pipeline

先確認的關鍵限制

在採用 xdrop 之前，請先確認以下要求：

• 執行內附 script 需要 bun
• agent 必須能存取本機檔案系統
• agent 必須能連到目標 Xdrop 伺服器
• 上傳流程是針對相容 Xdrop 的伺服器，不是任意檔案主機

如果你的環境無法執行 Bun，或無法連到目標伺服器，這份 xdrop 指南就不是適合的路線。

如何使用 xdrop skill

把 xdrop skill 安裝到你的 skills 環境

如果你使用 Skills system，可用以下方式安裝 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 本質上是以 script 為核心，因此實際上的前置條件是 Bun。開始使用 xdrop 前，先確認 Bun 可用：

bun --version

也請一併確認：

• 你能讀取準備上傳的本機檔案
• 你能寫入下載目的地目錄
• 你的環境可以連到 Xdrop 伺服器

先看這些檔案

如果你想快速評估，建議依照以下順序閱讀：

1. SKILL.md：確認支援的 workflow 與 flags
2. scripts/upload.mjs：看上傳參數與限制
3. scripts/download.mjs：看分享連結解析方式與輸出行為

通常照這個順序讀完，就足以判斷 xdrop for File Automation 是否適合你的 pipeline。

先理解 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 的定位。

使用適合自動化的 xdrop 上傳參數

在實際自動化裡，最有用的 flags 包括：

• --json：提供結構化輸出，方便下游解析
• --quiet：讓 stdout 保持乾淨
• --expires-in <sec>：控制傳輸有效期限
• --name <value>：設定傳輸名稱
• --api-url <url>：API root 不是預設值時使用
• --concurrency <n>：調整平行上傳行為

範例：

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

對 agent workflow 來說，--json 特別重要，因為它會直接回傳像 transferId、shareUrl、expiresAt 這類欄位，不必再用脆弱的文字擷取方式硬拆輸出。

從分享連結下載並解密

xdrop 最核心的下載情境，是處理包含 key fragment 的完整 Xdrop 分享 URL：

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

這支 script 會解析分享連結、抓取 transfer metadata、下載加密內容，並在本機端完成解密。這也是比起手寫 prompt，更應該使用 xdrop skill 的主因：帶 key 的連結格式已經替你處理好了。

用 xdrop 精準控制下載輸出

預設情況下，下載內容會放到像 ./xdrop-<transferId> 這樣的目錄。若你的 workflow 需要固定路徑，請明確覆寫：

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

實用 flags：

• --output <dir>：固定檔案落點，方便後續流程
• --json：輸出機器可讀結果
• --quiet：讓 log 更乾淨
• --api-url <url>：當 API root 與 <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 使用 prompt 通常會包含：

• 伺服器 URL 或完整分享 URL
• 精確的本機檔案路徑
• 期望的輸出目錄
• 要純文字輸出還是 JSON
• 上傳是否有過期時間需求

最適合 xdrop for File Automation 的工作流程

實務上建議這樣使用：

1. 先確認 Bun 和網路連線能力
2. 先用小檔案測試
3. 指令能正常跑通後，再切換成 --json
4. 若 stdout 會被其他 script 或 agent 解析，再加上 --quiet
5. 最後才擴大到大檔案或多檔案傳輸

這樣可以有效減少除錯時間，因為大多數失敗都來自環境問題、路徑錯誤或伺服器不可達，而不是傳輸邏輯本身。

xdrop 的實際限制與取捨

從 script 的訊號來看，xdrop 是為了直接、單純的傳輸流程而最佳化，不是拿來做無上限的大量搬運。上傳 script 目前定義了：

• 最大並行數上限為 6
• 最大傳輸大小為 256 * 1024 * 1024 bytes

也就是說，這份 xdrop 指南更適合短期分享與自動化任務，不特別適合超大規模的封存型工作流程。

xdrop skill 常見問題

xdrop skill 對新手友善嗎

如果你已經能在終端機執行 Bun script，那麼算是友善。介面本身很簡單，但新手仍可能需要協助處理以下問題：

• 安裝 Bun
• 傳入正確的檔案系統路徑
• 理解 site URL 和 API URL 的差別
• 保留分享連結中的 #k=... fragment

什麼情況下 xdrop 比一般 prompt 更好

當你需要的是「可執行的結果」，而不是「概念說明」時，xdrop skill 會更好。一般 prompt 可以解釋 Xdrop，但這個 skill 直接提供具體的上傳／下載路徑，必要 flags 與本機解密流程也都已經編碼進去。

使用 xdrop 時，我需要提供哪些輸入

上傳時需要：

• 透過 --server 提供公開可用的 Xdrop site URL
• 一個或多個本機檔案或目錄路徑

下載時需要：

• 完整的分享 URL，最好包含 key fragment
• 視需要提供輸出目錄與 API override

缺少這些輸入時，agent 就只能猜，而 xdrop 的使用品質會很快下降。

下載時一定要提供完整分享 URL 嗎

是的，實務上你應該提供完整的 Xdrop 連結。下載 script 明確預期收到完整分享連結，並用它推導 transfer ID、origin 與 key material。只有裸的 transfer ID，不足以完成整個本機解密流程。

xdrop 適合用在 CI 或 script pipeline 嗎

適合。這其實是安裝 xdrop 最充分的理由之一。它支援 --json 與 --quiet，因此很適合 shell scripts、CI jobs，以及需要讓 stdout 保持可解析的 agent chains。

什麼情況下不該使用 xdrop

如果符合以下情況，建議不要使用 xdrop：

• 你無法執行 Bun
• 你需要的是以瀏覽器為主的使用體驗，而不是終端機自動化
• 你需要的不只是上傳／下載自動化
• 你的目標不是相容 Xdrop 的伺服器
• 你的 workflow 涉及超出 script 預期傳輸限制的檔案

如何改善 xdrop skill 的使用效果

給 xdrop 完整且沒有歧義的輸入

想讓 xdrop 更快產生正確結果，最有效的方法就是一開始就把操作所需資訊講清楚：

• 精確檔案路徑
• 精確伺服器或分享 URL
• 期望的過期時間
• 期望的輸出目錄
• 是否需要 JSON
• stdout 是否必須保持安靜

這能去掉大部分猜測空間，也能避免來回修正。

保留分享 URL 的 fragment

xdrop 使用中一個很常見的失敗模式，就是在不同工具間複製連結時把 #k=... fragment 弄丟。只要這段遺失，即使 transfer ID 是有效的，本機解密仍可能失敗。請明確提醒使用者：傳入完整 URL，且不要改動。

下游要自動化時，優先使用 JSON

如果後續還有其他工具、script 或 agent 要接手結果，建議優先：

• 上傳使用 --json
• 下載使用 --json

這樣可靠度會更高，因為你不必去解析面向人類的 console 文字。

先用小型傳輸驗證，再往上擴大

若想讓 xdrop for File Automation 跑得更穩，先用小檔案驗證完整 round trip：

1. 上傳一個小型測試檔案
2. 擷取回傳的分享 URL
3. 把它下載到暫存目錄
4. 確認檔案內容符合預期

這樣你可以在花時間排查大檔案問題前，先把環境與伺服器層面的問題隔離出來。

有意識地使用 output 和 quiet 參數

有兩個小選擇，往往能大幅提升品質：

• 當後續步驟在意下載位置時，使用 --output
• 當 log 會干擾機器解析時，使用 --quiet

這些 flags 表面上看起來不大，但在真實 pipeline 裡影響很大。

只有在必要時才調整 concurrency

上傳 script 支援 --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 root 是否需要 --api-url
6. 是否超出傳輸大小或環境限制

通常照這個順序排查，會比把整個 repository 全部讀完更快找到問題。

第一次結果不理想後，該改什麼

如果第一次執行 xdrop 的結果很亂或不完整，可以優先調整：

• 如果輸出解析很脆弱，就加上 --json
• 如果 log 汙染了 stdout，就加上 --quiet
• 如果檔案落在錯誤位置，就加上 --output
• 把模糊的檔案描述改成精確路徑
• 先對本機或已知正常的 Xdrop 伺服器測試，不要一開始就怪 script

這些調整通常比整個 workflow 重寫一次，更能有效改善第二次執行結果。