xdrop

Tổng quan về skill xdrop

xdrop làm được gì

Skill xdrop giúp agent tải tệp hoặc thư mục cục bộ lên máy chủ Xdrop, đồng thời tải tệp từ một liên kết chia sẻ Xdrop về máy, bao gồm cả bước giải mã cục bộ cho các phiên truyền đã mã hóa. Đây là lựa chọn phù hợp nhất cho các tác vụ tự động hóa file qua terminal khi bạn cần một lệnh có thể lặp lại, URL chia sẻ gọn gàng và tùy chọn đầu ra ở dạng máy có thể đọc được.

Ai nên cài skill xdrop

Hãy cài skill xdrop này nếu bạn:

• chuyển file qua một instance Xdrop từ script hoặc workflow của agent
• nhận các liên kết Xdrop dạng /t/<transferId>#k=... và muốn tải xuống kèm giải mã ngay trên máy cục bộ
• cần các cờ CLI ổn định như --json, --quiet, --output, --expires-in, hoặc --api-url
• muốn một quy trình upload/download cụ thể thay vì tự ghép các lệnh gọi HTTP thô

Nhu cầu thực tế mà xdrop giải quyết

Phần lớn người dùng không tìm “một skill chia sẻ file” theo nghĩa chung chung. Họ thường cần tự động hóa ổn định một trong hai việc sau:

1. biến file cục bộ thành liên kết chia sẻ Xdrop ngay từ terminal
2. lấy một liên kết Xdrop có sẵn và khôi phục file về máy mà không phải đoán giao thức hoạt động ra sao

Đó là lúc xdrop phát huy tác dụng: nó đóng gói workflow thành hai script có thể chạy trực tiếp, thay vì buộc agent phải tự lần ngược định dạng chia sẻ.

Vì sao xdrop khác với một prompt chung chung

Một prompt chung chung có thể mô tả Xdrop có thể hoạt động thế nào. Skill xdrop thì cung cấp các script thực thi được, đã xử lý sẵn đường đi thực tế:

• upload qua scripts/upload.mjs
• phân tích liên kết chia sẻ và tải xuống qua scripts/download.mjs
• mặc định dùng đúng API root mong đợi
• hỗ trợ đầu ra quiet và JSON để dễ đưa vào pipeline tự động hóa

Những ràng buộc quan trọng cần biết trước

Trước khi dùng xdrop, hãy xác nhận các yêu cầu sau:

• cần có bun để chạy các script đi kèm
• agent phải có quyền truy cập filesystem cục bộ
• agent phải có quyền truy cập mạng tới máy chủ Xdrop đích
• chức năng upload được thiết kế cho máy chủ tương thích Xdrop, không phải mọi dịch vụ lưu trữ file bất kỳ

Nếu môi trường của bạn không chạy được Bun hoặc không truy cập được máy chủ đích, thì hướng dẫn xdrop này không phải lộ trình phù hợp.

Cách dùng skill xdrop

Cài skill xdrop vào hệ thống skills

Nếu bạn đang dùng hệ thống Skills, hãy cài xdrop bằng:

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

Sau đó làm việc với các file trong thư mục skill:

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

Cài các yêu cầu runtime để dùng xdrop

Bản thân skill này chạy dựa trên script, nên điều kiện tiên quyết thực tế là Bun. Hãy kiểm tra Bun đã sẵn sàng trước khi bắt đầu dùng xdrop:

bun --version

Đồng thời xác minh thêm:

• bạn đọc được các file cục bộ muốn upload
• bạn ghi được vào thư mục đầu ra dùng cho download
• máy chủ Xdrop có thể truy cập được từ môi trường hiện tại

Nên đọc những file nào trước

Nếu cần đánh giá nhanh, hãy đọc theo thứ tự này:

1. SKILL.md để nắm workflow và các cờ được hỗ trợ
2. scripts/upload.mjs để xem tham số upload và các giới hạn
3. scripts/download.mjs để xem cách phân tích share link và hành vi đầu ra

Thứ tự này thường đã đủ để quyết định liệu xdrop cho File Automation có hợp với pipeline của bạn hay không.

Hiểu hai điểm vào cốt lõi của xdrop

Skill xdrop được thiết kế có chủ đích theo hướng hẹp và rõ ràng. Về cơ bản bạn sẽ gọi một trong hai lệnh sau:

• Upload:

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

• Download:

  bun scripts/download.mjs <share-url>
  

Phạm vi hẹp này lại là điểm mạnh nếu bạn cần tự động hóa truyền file đáng tin cậy, thay vì một SDK rộng nhưng khó kiểm soát hơn.

Upload file với xdrop

Một lệnh upload cơ bản trông như sau:

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

Bạn cũng có thể upload nhiều đường dẫn cùng lúc:

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

Hãy dùng theo cách này khi mục tiêu của người dùng là “chia sẻ các file cục bộ này và trả cho tôi một link”, chứ không phải khi họ cần đồng bộ lưu trữ, duyệt nội dung hay các tính năng quản lý tài khoản.

Dùng các cờ upload thân thiện với tự động hóa

Những cờ hữu ích nhất cho tự động hóa thực tế là:

• --json để parse có cấu trúc ở bước sau
• --quiet để giữ stdout sạch
• --expires-in <sec> để kiểm soát thời gian sống của phiên truyền
• --name <value> để đặt nhãn cho transfer
• --api-url <url> nếu API root không phải mặc định
• --concurrency <n> để tinh chỉnh mức upload song song

Ví dụ:

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

Trong workflow của agent, --json đặc biệt quan trọng vì nó trả về các trường như transferId, shareUrl, và expiresAt, thay vì buộc bạn phải trích xuất từ văn bản console dễ vỡ.

Tải xuống và giải mã từ share link

Trường hợp download chính là dùng một URL chia sẻ Xdrop đầy đủ, có chứa fragment khóa:

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

Script sẽ phân tích liên kết chia sẻ, lấy metadata của transfer, tải nội dung đã mã hóa và giải mã ngay trên máy cục bộ. Đây là lý do lớn nhất để chọn skill xdrop thay vì một prompt tự viết: định dạng link có chứa khóa đã được xử lý sẵn cho bạn.

Kiểm soát đầu ra download gọn gàng

Mặc định, file tải về sẽ nằm trong một thư mục kiểu ./xdrop-<transferId>. Hãy ghi đè hành vi này nếu workflow của bạn cần một đường dẫn cụ thể:

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

Các cờ hữu ích:

• --output <dir> để đặt vị trí file một cách xác định
• --json để lấy kết quả ở dạng máy có thể đọc
• --quiet để log gọn hơn
• --api-url <url> khi API root khác với mặc định <share-origin>/api/v1

Biến yêu cầu mơ hồ thành prompt xdrop mạnh

Yêu cầu yếu:

upload file này lên xdrop

Yêu cầu tốt hơn:

Dùng skill xdrop để upload ./build/app.tar.gz lên https://xdrop.example.com, đặt thời hạn hết hạn là 600 giây, chỉ trả về JSON và giữ stdout ở chế độ quiet.

Yêu cầu yếu:

lấy link xdrop này về

Yêu cầu tốt hơn:

Dùng xdrop để tải https://xdrop.example.com/t/abc#k=... xuống, lưu vào ./artifacts/incoming, và trả về đường dẫn đầu ra dưới dạng JSON.

Một prompt dùng xdrop tốt thường nên có:

• URL máy chủ hoặc URL chia sẻ đầy đủ
• đường dẫn file cục bộ chính xác
• thư mục đầu ra mong muốn
• đầu ra cần là text thường hay JSON
• nhu cầu hết hạn đối với upload

Workflow tốt nhất cho xdrop trong File Automation

Một quy trình thực tế là:

1. kiểm tra Bun và quyền truy cập mạng
2. thử trước với một file nhỏ
3. chuyển sang --json khi lệnh đã chạy đúng
4. thêm --quiet nếu sẽ có script hoặc agent khác parse stdout
5. chỉ sau đó mới chuyển sang transfer lớn hơn hoặc nhiều file

Cách này giúp giảm thời gian debug vì phần lớn lỗi đến từ môi trường, sai đường dẫn hoặc máy chủ không truy cập được, chứ không phải do logic truyền file.

Giới hạn thực tế và các đánh đổi

Từ tín hiệu trong script, có thể thấy xdrop được tối ưu cho các phiên truyền thẳng, gọn, chứ không phải luồng chuyển dữ liệu khối lượng lớn không giới hạn. Script upload quy định:

• độ song song tối đa bị chặn ở 6
• kích thước transfer tối đa là 256 * 1024 * 1024 bytes

Điều đó có nghĩa là hướng dẫn xdrop này phù hợp hơn với các tác vụ chia sẻ ngắn hạn và tự động hóa, hơn là các workflow lưu trữ/archive dung lượng rất lớn.

Câu hỏi thường gặp về skill xdrop

Skill xdrop có thân thiện với người mới không

Có, nếu bạn đã quen chạy Bun script từ terminal. Giao diện khá đơn giản, nhưng người mới vẫn có thể cần hỗ trợ ở các điểm sau:

• cài Bun
• truyền đúng đường dẫn filesystem
• hiểu sự khác nhau giữa site URL và API URL
• giữ nguyên fragment #k=... trong share link

Khi nào xdrop tốt hơn một prompt thông thường

Skill xdrop tốt hơn khi bạn cần thực thi, không chỉ cần giải thích. Một prompt thông thường có thể mô tả Xdrop, nhưng skill này cung cấp một lộ trình upload/download cụ thể với đúng cờ và workflow giải mã cục bộ đã được mã hóa sẵn trong script.

xdrop cần tôi cung cấp những đầu vào nào

Đối với upload:

• một site URL Xdrop công khai qua --server
• một hoặc nhiều đường dẫn file/thư mục cục bộ

Đối với download:

• một share URL đầy đủ, lý tưởng nhất là có cả fragment khóa
• tùy chọn thêm thư mục đầu ra và API override

Nếu thiếu các đầu vào này, agent sẽ phải đoán, và chất lượng dùng xdrop sẽ giảm rất nhanh.

Có cần share URL đầy đủ để download không

Có, trên thực tế bạn nên cung cấp liên kết Xdrop đầy đủ. Script download được viết để chờ một share link hoàn chỉnh và dùng nó để suy ra transfer ID, origin và dữ liệu khóa. Chỉ một transfer ID trần là không đủ cho toàn bộ quy trình giải mã cục bộ.

xdrop có phù hợp với CI hoặc pipeline script không

Có. Đây là một trong những lý do thuyết phục nhất để cài xdrop. Việc hỗ trợ --json và --quiet khiến nó phù hợp với shell script, job CI và chuỗi agent nơi stdout cần giữ ở trạng thái dễ parse.

Khi nào không nên dùng xdrop

Hãy bỏ qua xdrop nếu:

• bạn không chạy được Bun
• bạn cần trải nghiệm ưu tiên trình duyệt thay vì tự động hóa qua terminal
• bạn cần tính năng vượt ra ngoài upload/download automation
• đích của bạn không phải máy chủ tương thích Xdrop
• workflow của bạn liên quan tới file vượt quá giới hạn transfer mà script nhắm tới

Cách cải thiện skill xdrop

Cung cấp cho xdrop đầu vào đầy đủ, không mơ hồ

Cách nhanh nhất để cải thiện kết quả với xdrop là nêu rõ mọi đầu vào vận hành ngay từ đầu:

• đường dẫn file chính xác
• server URL hoặc share URL chính xác
• thời hạn hết hạn mong muốn
• thư mục đầu ra mong muốn
• có cần JSON hay không
• stdout có cần giữ yên lặng hay không

Làm vậy sẽ loại bỏ phần lớn suy đoán và tránh phải sửa qua lại ở các bước sau.

Giữ nguyên fragment của share URL

Một lỗi rất thường gặp khi dùng xdrop là làm mất fragment #k=... khi sao chép link qua các công cụ khác nhau. Nếu fragment này bị mất, việc giải mã cục bộ có thể thất bại ngay cả khi transfer ID vẫn đúng. Hãy nói rõ với người dùng rằng họ phải truyền nguyên vẹn URL đầy đủ.

Ưu tiên JSON cho tự động hóa phía sau

Nếu kết quả sẽ được công cụ, script hoặc agent khác tiêu thụ, hãy ưu tiên:

• upload với --json
• download với --json

Cách này đáng tin cậy hơn vì bạn không phải parse văn bản console vốn dành cho con người đọc.

Kiểm thử bằng transfer nhỏ trước khi mở rộng

Để có kết quả xdrop cho File Automation tốt hơn, hãy xác minh toàn bộ vòng chạy bằng một file nhỏ trước:

1. upload một file test nhỏ
2. lấy share URL được trả về
3. download nó vào thư mục tạm
4. xác nhận nội dung file đúng như mong đợi

Cách này giúp tách bạch vấn đề môi trường và máy chủ trước khi bạn tốn thời gian debug các transfer lớn.

Dùng output và quiet một cách có chủ đích

Hai lựa chọn nhỏ nhưng cải thiện chất lượng đáng kể:

• dùng --output khi đường dẫn file tải về có ảnh hưởng tới các bước sau
• dùng --quiet khi log có thể làm nhiễu quá trình parse bằng máy

Trên lý thuyết đây chỉ là các cờ phụ, nhưng trong pipeline thực tế chúng có tác động rất lớn.

Chỉ chỉnh concurrency khi thực sự cần

Script upload có hỗ trợ --concurrency, nhưng tăng cao không phải lúc nào cũng tốt hơn. Chỉ nên tăng khi bạn chắc chắn máy chủ và đường mạng chịu được mức song song lớn hơn. Nếu không, cứ giữ hành vi mặc định để tối ưu độ ổn định khi chạy.

Xử lý sớm các khác biệt API theo từng máy chủ

Nếu hệ triển khai Xdrop của bạn phơi API ở nơi khác ngoài mặc định <server>/api/v1, hãy đặt --api-url ngay từ đầu thay vì chờ tới lúc debug các lỗi khó hiểu. Đây là một trong những điều đầu tiên cần kiểm tra khi xdrop có vẻ đúng nhưng vẫn không giao tiếp được với máy chủ.

Cải thiện prompt lần đầu bằng chi tiết có thể chạy ngay

Một mẫu hướng dẫn prompt xdrop mạnh nên trông như sau:

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

Vì sao cách này hiệu quả:

• nêu đích danh skill cần dùng
• cung cấp đường dẫn nguồn cụ thể
• chỉ rõ server, thời hạn hết hạn và định dạng đầu ra
• định nghĩa rõ hình dạng phản hồi mong muốn

Chẩn đoán đúng các điểm lỗi có khả năng cao nhất trước

Nếu xdrop gặp lỗi, hãy kiểm tra theo thứ tự sau:

1. Bun đã được cài và chạy được
2. các đường dẫn cục bộ thực sự tồn tại
3. server URL có thể truy cập được
4. share URL đầy đủ có chứa #k=...
5. API root có cần --api-url
6. kích thước transfer hoặc giới hạn môi trường có đang bị vượt quá

Thứ tự này thường giúp xử lý vấn đề nhanh hơn là đọc toàn bộ repository.

Nên thay đổi gì sau lần chạy đầu tiên còn yếu

Nếu lần chạy xdrop đầu tiên còn lộn xộn hoặc thiếu sót:

• thêm --json nếu việc parse đầu ra còn mong manh
• thêm --quiet nếu log làm bẩn stdout
• thêm --output nếu file rơi vào sai chỗ
• thay các tham chiếu file mơ hồ bằng đường dẫn chính xác
• kiểm thử với một máy chủ Xdrop cục bộ hoặc đã biết là hoạt động tốt trước khi đổ lỗi cho script

Những thay đổi này thường cải thiện lần chạy thứ hai nhiều hơn là viết lại toàn bộ workflow.