xdrop

xdropスキルの概要

xdropができること

xdropスキルは、ローカルのファイルやディレクトリをXdropサーバーへアップロードし、Xdropの共有リンクからファイルをダウンロードして、暗号化された転送内容をローカルで復号するのに役立ちます。とくに、ターミナル主導のファイル自動化で、再実行しやすいコマンド、すっきりした共有URL、必要に応じた機械可読な出力がほしい場面に向いています。

xdropスキルを入れるべき人

次のような場合は、このxdropスキルの導入が適しています。

• スクリプトやエージェントのワークフローから、Xdropインスタンス経由でファイルをやり取りしたい
• /t/<transferId>#k=... のようなXdropリンクを受け取り、ローカルでダウンロードと復号を行いたい
• --json、--quiet、--output、--expires-in、--api-url といった安定したCLIフラグが必要
• 生のHTTP呼び出しをその場しのぎで組むのではなく、はっきりしたアップロード／ダウンロード手段がほしい

実際に片づけたい仕事

多くのユーザーは、抽象的な意味で「ファイル共有スキル」を探しているわけではありません。実際には、次のどちらかを確実に自動化したいはずです。

1. ターミナルからローカルファイルをXdrop共有リンクに変換する
2. 既存のXdropリンクを受け取り、プロトコルを推測せずにローカルへ復元する

xdropが役立つのはこの部分です。共有形式をエージェントにリバースエンジニアリングさせるのではなく、実行可能な2本のスクリプトとしてワークフローをまとめています。

xdropが汎用プロンプトと違う理由

汎用プロンプトでも、Xdropの仕組みを説明することはできます。ですがxdropスキルには、実運用に必要な流れをそのまま実行できるスクリプトが含まれています。

• scripts/upload.mjs でアップロード
• scripts/download.mjs で共有リンクを解析してダウンロード
• 既定では想定されたAPIルートを利用
• 自動化しやすいように --quiet とJSON出力をサポート

最初に把握しておきたい制約

xdropを採用する前に、次の条件を確認してください。

• 同梱スクリプトの実行には bun が必要
• エージェントにローカルファイルシステムへのアクセス権が必要
• エージェントに対象のXdropサーバーへのネットワークアクセスが必要
• アップロード先は任意のファイルホストではなく、Xdrop互換サーバーを前提としている

Bunを実行できない環境や、対象サーバーへ接続できない環境なら、このxdropガイドは適した選択肢ではありません。

xdropスキルの使い方

Skills環境にxdropスキルをインストールする

Skillsシステムを使っている場合、xdropは次のコマンドで導入できます。

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

導入後は、次のスキルディレクトリ内のファイルを起点に作業します。

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

xdrop利用に必要な実行環境を確認する

このスキルはスクリプトベースなので、実用上の前提条件はBunです。xdropを使い始める前に、まずBunが利用可能か確認してください。

bun --version

あわせて次も確認しておくと安全です。

• アップロードしたいローカルファイルを読み取れる
• ダウンロード先の出力ディレクトリへ書き込める
• 実行環境からXdropサーバーへ到達できる

まず読むべきファイル

短時間で見極めるなら、読む順番は次のとおりです。

1. サポートされるワークフローとフラグを確認するために SKILL.md
2. アップロード引数と制限を見るために scripts/upload.mjs
3. 共有リンク解析と出力挙動を確認するために scripts/download.mjs

この順で読めば、File Automation向けのxdropが自分のパイプラインに合うかどうかは、たいてい判断できます。

xdropの2つの主要エントリーポイントを理解する

xdropスキルの役割は意図的に絞られています。基本的に呼び出すのは次のどちらかです。

• Upload:

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

• Download:

  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
• stdoutを汚さないための --quiet
• 転送の有効期限を制御する --expires-in <sec>
• 転送ラベルを設定する --name <value>
• APIルートが既定でない場合の --api-url <url>
• 並列アップロード挙動を調整する --concurrency <n>

例:

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

エージェントのワークフローでは、--json が特に重要です。人間向けテキストを無理に抜き出すのではなく、transferId、shareUrl、expiresAt のようなフィールドをそのまま受け取れます。

xdropの共有リンクからダウンロードして復号する

ダウンロードの中心的なケースは、キー断片を含む完全なXdrop共有URLです。

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

このスクリプトは共有リンクを解析し、転送メタデータを取得して、暗号化されたコンテンツをダウンロードし、ローカルで復号します。手書きのプロンプトよりxdropスキルを選ぶ大きな理由はここで、キー付きリンク形式の扱いがすでに組み込まれています。

xdropのダウンロード出力をきれいに制御する

既定では、ダウンロード先は ./xdrop-<transferId> のようなディレクトリになります。ワークフロー上、保存先を固定したいなら上書きしてください。

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

便利なフラグ:

• 保存先を明示する --output <dir>
• 機械可読な結果を返す --json
• ログを抑える --quiet
• APIルートが <share-origin>/api/v1 と異なる場合の --api-url <url>

あいまいな依頼を実行しやすいxdropプロンプトに変える

弱い依頼:

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で返すか
• アップロード時に必要な有効期限

File Automation向けxdropのおすすめ運用フロー

実運用では、次の流れにすると進めやすいです。

1. Bunとネットワーク到達性を確認する
2. まず小さいファイルで試す
3. コマンドが通ったら --json に切り替える
4. 別スクリプトやエージェントがstdoutを読むなら --quiet を追加する
5. そのあとで大きい転送や複数ファイル転送に進む

こうすると、デバッグ時間を減らせます。実際の失敗原因の多くは、転送ロジックそのものより、環境の問題、パス指定ミス、サーバー到達性にあります。

実用上の制限とトレードオフ

スクリプトの内容を見る限り、xdropは無制限の大容量転送ではなく、わかりやすい転送処理に最適化されています。アップロードスクリプトには次の定義があります。

• 最大並列数は 6 に制限
• 最大転送サイズは 256 * 1024 * 1024 bytes

つまり、このxdropガイドが特に合うのは、非常に大きなアーカイブ用途よりも、短期共有や自動化タスクです。

xdropスキル FAQ

xdropスキルは初心者にも扱いやすい？

はい。ターミナルからBunスクリプトを実行することに抵抗がなければ、扱いやすい部類です。インターフェース自体はシンプルですが、初心者がつまずきやすい点はあります。

• Bunのインストール
• 正しいファイルシステムパスの指定
• site URL と API URL の違いの理解
• 共有リンクの #k=... 断片を欠かさず保持すること

xdropは普通のプロンプトよりどんなときに有利？

xdropスキルが有利なのは、「説明」ではなく「実行」が必要なときです。普通のプロンプトでもXdropの説明はできますが、このスキルなら適切なフラグを備えた具体的なアップロード／ダウンロード手順と、ローカル復号の流れまでコード化されています。

xdropを使うには何を渡せばいい？

アップロード時:

• --server で公開されたXdropサイトURL
• 1つ以上のローカルファイルまたはディレクトリパス

ダウンロード時:

• できればキー断片を含む完全な共有URL
• 必要に応じて出力ディレクトリとAPI上書き設定

これらがないと、エージェント側で推測が増え、xdropの実行品質はすぐに落ちます。

ダウンロードには完全な共有URLが必要？

はい。実運用では完全なXdropリンクを渡すべきです。ダウンロードスクリプトは完全な共有リンクを前提にしており、そこから transfer ID、origin、鍵情報を導出します。ローカル復号まで含めた完全なフローには、単なる transfer ID だけでは足りません。

xdropはCIやスクリプトパイプラインに組み込める？

はい。xdropを導入する大きな理由のひとつです。--json と --quiet をサポートしているので、stdoutをパース可能なまま保ちたいシェルスクリプト、CIジョブ、エージェント連携に向いています。

xdropを使わないほうがいいのはどんなとき？

次の条件に当てはまるなら、xdropは見送ったほうがよいでしょう。

• Bunを実行できない
• ターミナル自動化よりブラウザ中心のUXが必要
• アップロード／ダウンロード自動化以上の機能が必要
• 対象がXdrop互換サーバーではない
• ワークフロー上のファイルが、スクリプト想定の転送制限を超える

xdropスキルをより良く使うには

xdropには曖昧さのない完全な入力を渡す

xdropの結果を最も手早く改善する方法は、実行に必要な入力を最初から明示することです。

• 正確なファイルパス
• 正確なサーバーURLまたは共有URL
• 希望する有効期限
• 希望する出力ディレクトリ
• JSONが必要かどうか
• stdoutを静かに保つ必要があるか

これだけで推測が大きく減り、あとから修正を重ねる手間も避けられます。

共有URLのフラグメントを失わない

xdrop利用でよくある失敗は、ツール間でリンクをコピーする途中で #k=... フラグメントが欠けることです。この部分がないと、transfer ID が正しくてもローカル復号に失敗する可能性があります。ユーザーには、完全なURLをそのまま渡すよう明示してください。

後段の自動化にはJSONを優先する

別のツール、スクリプト、エージェントが結果を受け取るなら、次を優先してください。

• アップロードは --json
• ダウンロードも --json

こうすると、人間向けのコンソール出力を無理に解析せずに済むため、信頼性が上がります。

xdropの拡張前に小さな転送で往復確認する

File Automation向けxdropの成功率を上げるには、まず小さなファイルで往復動作を確認するのが有効です。

1. 小さなテストファイルをアップロードする
2. 返ってきた共有URLを控える
3. 一時ディレクトリへダウンロードする
4. ファイル内容が期待どおりか確認する

これにより、大きな転送のデバッグに時間を使う前に、環境やサーバーの問題を切り分けられます。

--output と --quiet は意図して使う

小さな違いですが、次の2点で品質はかなり変わります。

• 後続処理で保存先が重要なら --output を使う
• ログが機械的な解析を邪魔するなら --quiet を使う

見た目は地味なフラグでも、実際のパイプラインでは効果が大きいです。

並列数の調整は必要なときだけ行う

アップロードスクリプトは --concurrency をサポートしていますが、高くすればよいとは限りません。サーバーとネットワーク経路が並列処理に耐えられると確信できる場合にだけ増やしてください。そうでなければ既定の挙動を維持し、予測しやすい完了を優先したほうが安全です。

サーバー固有のAPI差異は早めに切り分ける

Xdrop環境のAPI公開先が既定の <server>/api/v1 ではない場合は、不可解な失敗をあとから追うより、最初に --api-url を設定してください。xdropの指定が正しそうなのにサーバーと通信できないとき、最初に疑うべき点のひとつです。

最初のxdropプロンプトから実行可能な粒度で書く

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

この形が機能する理由:

• スキル名を明示している
• 具体的な入力元パスがある
• サーバー、有効期限、出力形式が指定されている
• 期待するレスポンスの形まで定義されている

xdropで失敗したら、まず起こりやすい箇所から確認する

xdropが失敗した場合は、次の順で確認すると効率的です。

1. Bunがインストール済みで実行できる
2. ローカルパスが実在する
3. サーバーURLに到達できる
4. 完全な共有URLに #k=... が含まれている
5. APIルートに --api-url が必要
6. 転送サイズや環境制約を超えている

この順番で見るほうが、リポジトリ全体を最初から読むより早く解決しやすいことが多いです。

xdropの初回結果が弱かったときに見直す点

最初のxdrop実行結果が雑だったり不完全だったりした場合は、次を見直してください。

• 出力解析が不安定だったなら --json を追加する
• ログがstdoutを汚したなら --quiet を追加する
• ファイルの保存先がずれたなら --output を追加する
• あいまいなファイル指定を正確なパスに置き換える
• スクリプトを疑う前に、ローカルまたは既知の正常なXdropサーバーで試す

こうした調整は、ワークフロー全体を書き直すよりも、2回目の実行結果を改善しやすいことがほとんどです。