Bản mô tả tiếng Việt được tạo từ README.md. Bản tiếng Anh README.en.md và các tài liệu tham chiếu đi kèm source distribution; các link file nội bộ được hiển thị dạng tên tài liệu trên PyPI.

gofile-tool — CLI và Python SDK cho Gofile

Tiếng Việt (mặc định) · English · Chỉ mục tài liệu

Phiên bản: 0.2.0 · Python ≥ 3.9 · Apache-2.0 · stable release channel.

gofile-tool cung cấp thao tác tải xuống, upload, quản lý nội dung thuộc quyền của bạn và kết quả JSON để tích hợp với chương trình khác. Lệnh ngắn là gft; lệnh đầy đủ gofile-tool vẫn hoạt động bình thường, cùng một implementation.

Trạng thái quan trọng: hiện có CLI, SDK và MCP stdio server qua gft-mcp. JSON output, JSON Schema hay ví dụ chạy CLI từ agent không đồng nghĩa hỗ trợ Model Context Protocol. Native Windows/macOS, Docker và soak hoàn tất vẫn chưa được chứng nhận đầy đủ. Bản này chưa được chứng nhận stable trên mọi nền tảng.

Mục lục

1. Tên dự án và phạm vi
2. Tính năng và giới hạn
3. Yêu cầu môi trường
4. Cài đặt và cập nhật
5. Làm quen nhanh
6. Token, quyền sở hữu và mật khẩu
7. Tải xuống, lọc và batch
8. Upload file và thư mục
9. Journal, resume và chống trùng
10. Băng thông, retry, timeout và hủy
11. Các lệnh quản lý
12. JSON, exit code và agent
13. Python SDK
14. MCP: hiện trạng và điều kiện bổ sung
15. Bảo mật và dữ liệu nhạy cảm
16. Cấu trúc dự án và quy ước tên
17. Test và bằng chứng xác minh
18. Build, chuẩn bị PyPI và tình trạng sẵn sàng
19. Xử lý lỗi thường gặp
20. Tài liệu liên quan và giấy phép

1. Tên dự án và phạm vi

Tên	Ý nghĩa
gofile-tool/	Thư mục source chính
gofile-tool	Tên distribution trên PyPI và lệnh CLI đầy đủ
gft	Lệnh viết tắt được ưu tiên trong ví dụ
gf	Alias cũ tiếp tục được giữ để tương thích
gofile_tool	Namespace Python dùng khi import
gofile_tool-<version>...whl	Tên wheel chuẩn hóa; dấu gạch dưới không phải một package khác

Dự án là client không chính thức, không được Gofile bảo trợ hay chứng nhận. Chỉ thao tác trên dữ liệu bạn sở hữu hoặc được phép truy cập. Công cụ không vượt quyền private, password, Premium, frozen hay các giới hạn tài khoản của dịch vụ.

Các chuỗi CONTENT_ID, FILE_ID, FOLDER_ID, ROOT_FOLDER_ID, LINK_ID bên dưới là placeholder cần thay bằng giá trị thật. Không chạy lệnh có tác động remote khi chưa xác định rõ đối tượng.

2. Tính năng và giới hạn

Đã có trong candidate

Nhóm	Khả năng
Download	Streaming, kiểm tra size/MD5, nhiều file song song, partial download có identity manifest, kiểm tra Range và collision
Upload file	Streaming multipart, mở nguồn có kiểm soát, kiểm tra định danh và hash trước/sau, không tự replay upload
Upload thư mục	Kế hoạch offline, lọc file, tạo thư mục lồng nhau/rỗng, executor tuần tự với destination thuộc quyền sở hữu
Job upload	Journal riêng, khóa process, ghi atomic, resume sau các commit đã được ghi nhận
Chống trùng	Trong cùng job, rehash local và xác minh metadata remote trước khi bỏ qua file đã hoàn tất
Băng thông	Bộ lập lịch byte dùng chung trong một client, có kiểm tra deadline/hủy khi chờ
Refresh link	Opt-in, tối đa một lần/file sau HTTP 401/403, giữ nguyên credential và định danh file
CLI	Alias, JSON cho automation, output dễ đọc trên terminal, shell completion
Quản lý	Account/server, folder, thuộc tính, copy/move/import/search, direct link, restore/recycle theo quyền dịch vụ

Chưa có hoặc không được cam kết

• MCP hiện chỉ có stdio và các tool có phạm vi quyền rõ ràng; chưa có HTTP/SSE hay remote mutation tools.
• Không có history/dedup toàn cục giữa các job, incremental sync hoặc persistent download-job queue.
• Không có TUI/web dashboard, exporter HTML/CSV hoàn chỉnh hay chức năng archive/share chỉ vì các ý tưởng đó xuất hiện trong nghiên cứu upstream.
• Upload thư mục hiện tuần tự; --workers điều khiển download, không biến upload thành song song.
• Không tự đối soát/replay mutation đang ở trạng thái chưa rõ kết quả.
• Không đảm bảo throughput cụ thể trên mạng/Gofile thực tế.
• Native Windows/macOS, Docker và một bài soak liên tục hoàn tất chưa được chứng nhận trong lần chuẩn bị này.
• Coverage 100% không chứng minh phần mềm không còn lỗi.

3. Yêu cầu môi trường

• Python 3.9 trở lên; matrix Linux đã được chạy trên 3.9–3.14.
• Dung lượng đĩa cho dữ liệu tải về, file .part, journal và fixture nếu chạy stress.
• Quyền đọc nguồn upload và quyền ghi thư mục output/job.
• Kết nối tới dịch vụ đối với thao tác remote; upload dry-run và job-status là các thao tác local.
• Browser authentication mặc định cần extra browser, Chromium và các thư viện hệ điều hành tương ứng.

--auth-mode api không sử dụng browser signing provider nhưng không phải cách vượt hạn chế quyền truy cập. Endpoint/tài khoản có thể cần quyền hoặc gói dịch vụ khác.

Công cụ không tự chạy pip, apt, brew, không tự nâng quyền, không tự khởi động Tor và không tự tắt Chromium sandbox.

4. Cài đặt và cập nhật

4.1. Cài từ wheel

Từ thư mục gofile-tool/, dùng environment riêng:

python -m venv .venv
# Kích hoạt environment theo shell của bạn trước khi tiếp tục.
python -m pip install 'artifacts/gofile_tool-0.2.0-py3-none-any.whl[browser]'
python -m playwright install chromium

gft --version
gofile-tool --version
gf --version
gft --help

Ví dụ kích hoạt:

# Linux/macOS, shell tương thích POSIX
source .venv/bin/activate

# Windows PowerShell; tuân thủ execution policy của máy bạn
.\.venv\Scripts\Activate.ps1

Đây là hướng dẫn cài đặt đa nền tảng, không phải bằng chứng đã test native Windows/macOS. Không thay đổi policy hệ thống chỉ để bỏ qua cảnh báo mà chưa hiểu tác động.

Trên Linux, nếu Chromium thiếu thư viện hệ thống, operator có thể xem xét:

python -m playwright install-deps chromium

Lệnh trên có thể cần quyền quản trị; phải do operator chủ động thực hiện. Nếu chỉ lập kế hoạch local hoặc dùng API mode phù hợp, có thể cài wheel không có [browser].

4.2. Cài từ PyPI

python -m pip install --upgrade 'gofile-tool[browser]==0.2.0'
python -m playwright install chromium

Kiểm tra version có sẵn trên PyPI trước khi dùng lệnh pin. Nếu đang thử artifact local chưa có trên registry, dùng cách cài wheel ở mục 4.1.

0.2.0 là version không có hậu tố prerelease. Có thể cập nhật bằng pip install -U gofile-tool; không cần --pre và không đổi distribution name thành gft.

4.3. Cài cho phát triển

cd gofile-tool
python -m pip install -e '.[browser,dev,mcp]'

Nếu đã đứng trong thư mục dự án thì bỏ dòng cd. Sau khi di chuyển checkout, cần cài lại editable package hoặc dựng environment mới: các .pth và console-script shebang có thể chứa đường dẫn tuyệt đối cũ.

5. Làm quen nhanh

# Xem metadata nội dung được phép truy cập
gft info CONTENT_ID --json

# Cùng CLI, dùng tên đầy đủ
gofile-tool download CONTENT_ID -o ./downloads --json

# Xem cây và danh sách link; đây là thao tác metadata remote
gft tree CONTENT_ID --json
gft links CONTENT_ID --json

# Kế hoạch upload local, chưa gửi byte lên dịch vụ
gft upload ./photos --recursive --dry-run --include '*.jpg' --json

# Kiểm tra cấu hình; doctor có thể gọi dịch vụ/tạo guest account
gft doctor --json

Alias subcommand: i/ls → info, dl → download, up → upload, rm → delete. Các alias executable gft, gofile-tool, gf cùng trỏ về entrypoint chung.

6. Token, quyền sở hữu và mật khẩu

Owner token

Ưu tiên cung cấp GOFILE_TOKEN qua secret manager hoặc cơ chế environment đáng tin cậy. --token vẫn được hỗ trợ, nhưng argv có thể hiện trong process list/history. Không ghi token thật vào README, source, notebook chia sẻ hay log.

account, các mutation quản lý và upload thư mục cần credential thuộc chủ sở hữu. Server là bên quyết định quyền thực tế; có token không có nghĩa sở hữu mọi folder.

# Khi environment đã có owner token hợp lệ
gft account --json
gft servers --json

Guest upload một file

CLI yêu cầu lưu credential quản lý vào một file mới:

gft upload ./document.pdf --export-token ./guest.token --json

• File token được tạo theo chính sách create-only, không ghi đè file có sẵn.
• Credential được ghi sớm sau khi account được tạo, không chỉ khi chương trình thoát.
• POSIX sử dụng mode private; Windows ACL vẫn cần operator quản lý.
• Không commit file token vào Git hoặc đưa vào gói publish.
• Upload thư mục không tự tạo guest thay cho owner token.
• Upload --dry-run không tạo file token, kể cả khi có --export-token.

Password của nội dung

Đặt password trong một environment variable bằng cơ chế secret phù hợp, rồi truyền tên biến:

gft info CONTENT_ID --password-env GOFILE_FOLDER_PASSWORD --json
gft dl CONTENT_ID -o ./downloads --password-env GOFILE_FOLDER_PASSWORD --json

Không truyền password literal vào --password-env. Công cụ xử lý hash theo metadata protocol; đây không phải client-side encryption cho file của bạn.

Proxy

--proxy hoặc GOFILE_PROXY chọn proxy rõ ràng; hỗ trợ các scheme đã được parser cho phép như HTTP/HTTPS/SOCKS5/SOCKS5H, với host và port cụ thể. Proxy explicit là tuyến độc quyền, không âm thầm fallback trực tiếp khi lỗi.

Nếu không có proxy explicit, Requests có thể dùng cấu hình environment/default. Browser và Requests có giới hạn hỗ trợ proxy khác nhau, đặc biệt với SOCKS có authentication. Không quảng cáo “Tor hoạt động” chỉ từ việc bootstrap Tor thành công.

7. Tải xuống, lọc và batch

Download thông thường

gft download CONTENT_ID -o ./downloads --workers 4 --json

--workers nhận 1–32, mặc định 4. Đây là song song giữa các file, không phải tách một file thành nhiều multipart download.

Công cụ kiểm tra metadata, reserve đường dẫn, lock destination, xử lý partial/Range, xác minh size và MD5 khi có, rồi publish output atomically. File đích khác nội dung không bị âm thầm ghi đè.

Nếu server không cung cấp MD5, kết quả sẽ thể hiện cảnh báo kiểm tra size-only. --no-verify chủ động giảm mức kiểm tra xuống size-only; không dùng mặc định chỉ để làm lỗi integrity biến mất.

Bộ lọc

gft dl CONTENT_ID -o ./downloads \
  --include '*.jpg' --exclude '*thumbnail*' \
  --min-size 1024 --max-size 10485760 --max-files 500 --json

Flag	Ý nghĩa
--include	Một glob trên đường dẫn tương đối dạng POSIX
--exclude	Một glob loại trừ
--min-size	Size tối thiểu, tính theo byte
--max-size	Size tối đa, tính theo byte
--max-files	Giới hạn số file được chọn; mặc định 100.000

Glob dùng fnmatchcase, phân biệt hoa/thường; *.jpg có thể khớp cả đường dẫn có thư mục. Không tự coi cú pháp brace {jpg,png} là phép OR. Mỗi flag nhận một pattern; lặp lại flag không tạo danh sách pattern. Nên quote pattern để shell không mở rộng trước.

Dry-run của download khác dry-run của upload

gft dl CONTENT_ID -o ./downloads --dry-run --json

Download dry-run vẫn gọi metadata API và có thể cần authentication/guest account, nhưng không tải nội dung hay tạo output file. Upload dry-run chỉ kiểm tra metadata local; không gọi API.

Batch download

Tạo targets.txt UTF-8, mỗi dòng một URL/code; dòng trống và dòng comment bắt đầu bằng # được bỏ qua:

CONTENT_ID_ONE
https://gofile.io/d/CONTENT_ID_TWO

gft batch ./targets.txt -o ./downloads --workers 4 --json

Danh sách có giới hạn 1.000 target và 2.048 ký tự/dòng, được chuẩn hóa và bỏ trùng. Mỗi target có output dưới thư mục riêng theo code. Job lỗi được giữ trong kết quả data.jobs; không giả vờ cả batch thành công.

--refresh-links được mô tả cho lệnh download; không mặc định suy ra mọi tùy chọn global đã được áp dụng cho mọi command, bao gồm batch.

Link hết hạn

gft dl CONTENT_ID -o ./downloads --refresh-links --json

Refresh tối đa một lần/file sau 401/403, dưới cùng credential. Metadata mới phải đúng ID/type/size/MD5 và vẫn được phép truy cập. Không coi mọi 403 là link hết hạn; không chuyển sang guest để vượt quyền; không tiếp tục partial nếu identity đổi.

8. Upload file và thư mục

Upload một file

gft upload ./document.pdf --folder-id FOLDER_ID --json

Nguồn được mở có kiểm soát và kiểm tra là regular file. Các kiểm tra identity/hash trước/sau cùng read-time guards giúp phát hiện nguồn thay đổi. Nếu source hoặc kết quả remote không khớp, không tự gửi lại để che giấu lỗi.

--public của upload một file là lựa chọn rõ ràng, có thể publish cả parent. Chỉ dùng khi bạn hiểu và có quyền thay đổi phạm vi truy cập đó. Không dùng public=null trong kết quả để kết luận file chắc chắn private; đó có thể chỉ là trạng thái chưa xác định.

Lập kế hoạch thư mục trước

gft up ./photos --recursive --dry-run \
  --include '*.jpg' --max-files 500 --json

Plan báo file, path tương đối, size, source identity, directory inventory, tổng byte và số entry đã scan. Không đọc toàn bộ file để hash trong bước metadata-only này.

Mặc định scan tối đa 100.000 entry, tính cả root và entry bị filter loại; độ sâu directory tối đa 64. Symlink/special file quan sát được bị từ chối, kể cả khi tên sẽ bị exclude. Đây không phải snapshot filesystem nguyên tử.

Thực thi upload thư mục thật

gft up ./photos --recursive --folder-id FOLDER_ID \
  --job-dir ./transfer-jobs/photos --limit-rate 1048576 --json

Điều kiện:

1. Có owner token và destination là folder được phép sử dụng.
2. --job-dir nằm ngoài source để journal không bị upload hoặc làm đổi plan.
3. Job mới không ghi đè job đã có; dùng --resume khi phù hợp.
4. Mọi file được chọn được mở và hash preflight trước mutation đầu tiên.
5. Tối đa 10.000 file cho một durable upload job; journal tối đa 8 MiB.

Thư mục lồng nhau và thư mục rỗng được giữ. Filter chọn payload file không prune directory inventory; thư mục chỉ chứa file bị exclude vẫn có thể được tạo remote. Upload diễn ra tuần tự. Recursive --public bị từ chối nhằm tránh publish nhầm parent hiện có.

Không tự bỏ qua .env, private keys hay dữ liệu nhạy cảm dựa vào .gitignore. Chọn source hẹp, xem dry-run và dùng filter rõ ràng. Đừng upload cả home/repository một cách mù quáng.

9. Journal, resume và chống trùng

gft job-status --job-dir ./transfer-jobs/photos --json

gft up ./photos --recursive --folder-id FOLDER_ID \
  --job-dir ./transfer-jobs/photos --resume --json

Journal chính nằm tại JOB_DIR/state.part.json. Tên .part.json ở đây là định dạng checkpoint của store, không có nghĩa đó là file download tạm có thể xóa tùy ý.

Journal có schema version, binding của source/plan/content/account/destination, directory mapping, trạng thái từng file và inflight. Không lưu token/password plaintext; filename, ID và hash vẫn là metadata cần bảo vệ.

Tình huống	Hành vi
File đã commit và journal ghi nhận	Hash lại local, xác minh remote, rồi mới skip
Process chết sau checkpoint commit	Resume có thể dùng checkpoint đã xác minh
Process chết trong cửa sổ mutation	Giữ inflight, dừng để đối soát, không tự replay
Nguồn/plan/account/destination thay đổi	Từ chối reuse job không tương thích
Remote file biến mất hoặc đổi identity/hash	Dừng, không tự tạo bản thay thế
Journal hỏng/quá lớn/không đúng version	Báo lỗi thay vì đoán dữ liệu
Hai process cùng job	Advisory lock từ chối writer thứ hai

inflight được lưu trước request tạo folder/upload. Crash ngay trước request cũng có thể bị đánh dấu chưa rõ kết quả: đây là lựa chọn bảo thủ để tránh duplicate, không phải bằng chứng remote chắc chắn đã commit.

Không xóa journal hoặc sửa inflight chỉ để ép chạy tiếp. Đối soát đúng destination/ID, kiểm tra metadata và tải lại để xác minh SHA-256 khi cần. Candidate chưa có lệnh tự động reconcile mutation chưa rõ kết quả.

Dedup hiện chỉ trong cùng job không thay đổi, không phải global cache hay incremental backup. File nguồn mới/thay đổi không tự được ghép vào job cũ. Giữ journal cho tới khi đã xác minh và chấp nhận kết quả.

10. Băng thông, retry, timeout và hủy

Tham số	Mặc định	Phạm vi
--limit-rate	0	Byte/giây chung trong một client; 0 = không throttle
--timeout	30	Timeout HTTP connect/read, không phải SLA toàn job
--deadline	300	Hard wall-clock watchdog của CLI đã cài
--retries	2	GET retries, 0–10; không cho phép replay mutation
--workers	4	Download file workers, 1–32

Limiter dùng monotonic scheduling, không mắc điều kiện phải nhét toàn bộ chunk lớn vào một bucket nhỏ. Các worker của cùng client chia sẻ budget. Tuy nhiên đây là pacing application bytes, không phải firewall/NIC cap; upload tính cả multipart, download tính body bytes. Hai process/client khác nhau không tự chia sẻ một budget toàn máy.

CLI có watchdog process; SDK dùng deadline/cancellation mang tính cooperative. Blocking OS/HTTP call không phải lúc nào cũng bị ngắt tức thì. retryable=true chỉ là thông tin chẩn đoán, không phải giấy phép tự replay upload/delete/mkdir.

Hủy bằng Ctrl+C trong CLI. SDK có thể truyền threading.Event() vào cancel_event và set event để ngắt tại các điểm kiểm tra.

11. Các lệnh quản lý

Các lệnh sau cần owner scope, trừ server discovery và những thao tác read cụ thể. Quyền Premium/feature availability do server quyết định. Ví dụ dùng JSON string literal đã quote cho shell POSIX; trên shell khác có thể dùng --value-file để tránh khác biệt quoting.

Lệnh	Mục đích / ví dụ dạng rút gọn
account	Metadata account: gft account --json
servers	Server discovery: gft servers --json
mkdir	gft mkdir ROOT_FOLDER_ID --value '"Photos"' --json
rename	gft rename CONTENT_ID --value '"new-name"' --json
set	gft set CONTENT_ID --attribute description --value '"Description"' --json
copy	gft copy CONTENT_ID --destination FOLDER_ID --json
move	gft move CONTENT_ID --destination FOLDER_ID --json
import	gft import CONTENT_ID --json
search	gft search FOLDER_ID --query photo --json
public	gft public CONTENT_ID --json; thay đổi phạm vi truy cập
delete / rm	gft delete FILE_ID --yes --json; có thể dùng danh sách ID phân cách dấu phẩy
direct-link	Tạo direct-link với options JSON phù hợp API, ví dụ --value '{}'
update-link	Cần CONTENT_ID, --link-id LINK_ID, --value hoặc --value-file
delete-link	Cần CONTENT_ID, --link-id LINK_ID, --yes
restore	Yêu cầu restore qua API, không tự đảm bảo account hỗ trợ
empty-recycle	gft empty-recycle --yes --json; thao tác phá hủy rõ ràng

Các attribute được hỗ trợ gồm name, public, password, expiry, tags, description, modTime, nhưng giá trị và quyền thực tế phụ thuộc API. Không để password nhạy cảm trong argv; --value-file phải có permission phù hợp. Không đăng nội dung file cấu hình nhạy cảm lên issue.

Các lệnh hỗ trợ khác:

gft verify ./file.bin --sha256 EXPECTED_SHA256 --json
gft schema --json
gft completion bash --json
gft completion zsh --json
gft completion fish --json

Completion trả về script trong response; kiểm tra trước khi đưa vào cấu hình shell. verify tính SHA-256 local và có thể so với hash kỳ vọng. schema là schema envelope của CLI, không phải MCP tool schema.

12. JSON, exit code và agent

Mặc định auto: output Rich trên terminal, JSON khi redirect/pipe. Dùng --json rõ ràng cho automation. --format auto|json|plain|rich và --no-color cũng được hỗ trợ; --json được ưu tiên.

Envelope v1 minh họa một plan rỗng:

{
  "schema_version": "1",
  "ok": true,
  "command": "upload",
  "data": {
    "planned": true,
    "operation": "upload",
    "files": [],
    "directories": [],
    "total": 0,
    "total_bytes": 0,
    "scanned_entries": 1,
    "failed": 0
  },
  "error": null,
  "warnings": []
}

Đây là ví dụ cấu trúc, không phải một lần upload remote đã diễn ra. Schema authoritative nằm tại src/gofile_tool/schema.json và được đóng trong wheel.

Exit code	Ý nghĩa
0	Thành công
2	Input/path không hợp lệ hoặc collision
3	Auth/access, not-found, password, expiry/frozen/Premium
4	Network, rate limit, deadline hoặc busy
5	Partial failure hoặc integrity failure
6	Schema, internal, filesystem, provider/worker failure
130	Cancelled

Luôn kiểm tra exit code và ok. info giữ envelope dịch vụ nên metadata nằm dưới data.data; download dùng data.files; batch dùng data.jobs.

Với upload job, data.files chỉ giữ kết quả đã xác nhận, completed tính cả verified skip; failed=1 nghĩa job dừng vì một lỗi, không có nghĩa mọi file còn lại đã được thử. Xem data.error/inflight để quyết định xử lý, không chỉ đếm danh sách result.

Agent có thể gọi subprocess với timeout ngoài rồi parse JSON; xem examples/cli_download.py. Không parse bảng terminal và không đặt secret vào prompt/log. Đây là cách tích hợp CLI, không phải MCP.

13. Python SDK

Read và download

from gofile_tool import Gofile, GofileError

client = Gofile(timeout=20, deadline=120, limit_rate=1048576)

try:
    metadata = client.info("CONTENT_ID")
    files = client.download(
        "CONTENT_ID",
        "downloads",
        workers=4,
        refresh_links=True,
    )
    if not all(item["ok"] for item in files):
        # Decide recovery from structured results; do not blindly replay mutations.
        print("Some downloads failed")
except GofileError as error:
    print(error.code, error.retryable)

Client lấy GOFILE_TOKEN nếu có; khi thiếu có thể tạo guest cho các luồng được phép. Không dùng ví dụ trên để cam kết access tới một ID bất kỳ.

Upload job có owner token và cancellation

import threading
from gofile_tool import Gofile

cancel = threading.Event()
client = Gofile(deadline=300, limit_rate=1048576, cancel_event=cancel)
# Supply GOFILE_TOKEN through your secret manager before running this code.

result = client.upload_tree(
    source="photos",
    destination="FOLDER_ID",
    job_dir="transfer-jobs/photos",
    resume=False,
    include="*.jpg",
    max_files=500,
)

if result["failed"]:
    print("Job stopped; inspect the journal before resuming")

Set cancel từ thread điều khiển nếu cần hủy cooperative. Không chia sẻ một client cho các caller threads tùy ý: download có worker pool được quản lý sau bước auth/planning; public SDK không hứa thread-safe cho mọi thay đổi auth/state đồng thời.

Import public từ gofile_tool; module nội bộ có thể được tổ chức lại. core.py chỉ giữ một số compatibility exports, không đảm bảo mọi internal API đời cũ tồn tại.

14. MCP: hiện trạng và điều kiện bổ sung

Đã triển khai MCP stdio server thật bằng MCP Python SDK 1.30.x, entrypoint gft-mcp. Core vẫn hỗ trợ Python 3.9+; MCP yêu cầu Python 3.10+ và optional extra [mcp].

python -m pip install -e '.[mcp,browser]'
python -m playwright install chromium
# Dùng một thư mục riêng đã tồn tại, không cấp toàn bộ home:
gft-mcp --read-root /ABS/gofile-mcp/read

Mặc định chỉ có gofile_plan_upload và gofile_job_status, không mạng, không payload upload. Thêm --allow-network và credential GOFILE_TOKEN đã có để mở gofile_info; thêm --download-root /ABS/gofile-mcp/downloads để mở gofile_download. Root và quyền là policy do operator cấu hình, không nhận từ model qua arguments.

• Handshake, tools/list, tools/call đã được thử bằng MCP client và child process thật.
• Live GoFile: fixture riêng → info/download qua MCP → SHA-256 khớp → xóa fixture thành công.
• Chặn path traversal/symlink, extra arguments, malformed journal; bounded output và lỗi có redaction.
• Download chọn tối đa 1.000 file, bỏ file >64 MiB; 2 MiB/s, SDK deadline 60s, cooperative cancellation. Đây không phải hard process watchdog.
• Không cung cấp upload/delete/publish qua MCP; không HTTP server/multi-tenant auth; root policy không thay thế OS sandbox.

Xem hướng dẫn MCP đầy đủ và bằng chứng mới. gft mcp không phải entrypoint; dùng gft-mcp.

15. Bảo mật và dữ liệu nhạy cảm

• Chỉ thao tác trên dữ liệu được phép; không bypass entitlement hoặc kiểm tra password/private.
• Giữ token/password ngoài source, argv dễ lộ, log, issue và gói publish.
• Link, filename, remote ID, journal và JSON metadata cũng có thể nhạy cảm, dù không chứa token trực tiếp.
• POSIX source/output protection dùng descriptor anchoring/no-follow; fallback trên Windows yếu hơn trước race/reparse-point.
• Identity/hash checks không biến một file đang bị ghi thành snapshot immutable.
• MD5 là kiểm tra tương thích provider, không phải bảo đảm chống collision chủ động. SHA-256 được dùng cho local hash/roundtrip verification.
• Advisory locks không ngăn một process cùng quyền cố tình bỏ qua lock hoặc sửa journal.
• Chromium sandbox mặc định được giữ. --browser-no-sandbox là opt-in nguy hiểm, chỉ dùng trong isolation đã được operator đánh giá.
• Download lock files .gft-lock-* có thể tồn tại sau job; không xóa lock inode khi process khác còn dùng nó.
• Không gắn ok=true cho một mutation chỉ vì đã gửi request; mất kết nối sau khi gửi có thể để lại remote content.

Đọc SECURITY.md trước khi chạy unattended với dữ liệu quan trọng.

16. Cấu trúc dự án và quy ước tên

gofile-tool/
├── README.md                    # tài liệu chính tiếng Việt
├── README.en.md                 # tài liệu tiếng Anh phụ
├── pyproject.toml               # metadata, dependencies, entrypoints, quality policy
├── src/gofile_tool/
│   ├── api/                     # transport, contents, owner management
│   ├── authentication/          # signing provider, isolated browser worker
│   ├── filesystem/              # path policy, guarded source/store, locks
│   ├── transfers/               # plan, upload/download, limiter, identity refresh
│   │   └── download_worker.py   # thực thi tải một file
│   ├── jobs/                    # private upload journal
│   ├── cli/
│   │   ├── extended_commands.py # batch, metadata export, verification, management
│   │   └── subprocess_worker.py # child process của CLI watchdog
│   ├── client.py                # public Gofile facade
│   ├── core.py                  # compatibility exports có chủ đích
│   └── errors.py                # structured errors và exit codes
├── tests/                       # unit, integration, security, platform, fixtures
├── tools/
│   ├── quality/                 # chạy matrix interpreter
│   ├── smoke/                   # validate_live_*: external tests có opt-in
│   ├── benchmark/               # local transfer stress/soak
│   ├── workspace/               # check_workspace_budget.py
│   └── research/                # thu thập/phân tích evidence, không là runtime deps
├── docs/                        # reference, guides, development, release
├── research/                    # nghiên cứu upstream và provenance
├── reports/                     # evidence theo từng checkpoint
├── artifacts/                   # wheel/sdist candidate và checksum
└── examples/                    # ví dụ subprocess CLI và Python SDK

Quy ước: module/function dùng snake_case, tên theo trách nhiệm; class dùng PascalCase. Script dùng động từ có ý nghĩa: run_ cho orchestration, validate_ cho smoke, check_ cho guard, build_/sync_/audit_ cho công việc tương ứng.

Comment/docstring giải thích contract, lý do hoặc invariant an toàn, tập trung vào quyết định thiết kế thay vì mô tả lại từng dòng code. Giữ các giải thích về credential persistence, no-replay, atomic publication và lock lifetime.

Phân tích cấu trúc ghi rõ mapping tên cũ/mới và các tên được giữ để tránh phá compatibility.

17. Test và bằng chứng xác minh

python -m pip install -e '.[dev,mcp]'
python -m pytest -q
python -m pytest --cov=gofile_tool --cov-branch --cov-report=term-missing
python -m ruff check src tests tools examples
python -m ruff format --check src tests tools examples

• Suite offline không cần token thật, paid account hoặc GoFile traffic.
• Candidate đã có 373 tests pass, 1.730 statements / 642 branches, coverage runtime 100% (bao gồm MCP, cần Python ≥3.10 và extra [mcp]). Coverage bao gồm toàn bộ runtime; maintenance scripts được kiểm tra riêng.
• Linux Python 3.9–3.14 có matrix evidence; việc refactor phải kiểm tra lại chứ không dùng báo cáo cũ để tự chứng nhận build mới.
• Maintenance tools ở ngoài mẫu số coverage runtime; kết quả riêng được ghi theo scope.
• Local HTTP fixtures, subprocess crash, malformed responses, source replacement, locks, throttling và refresh identity có regression tests.
• Live owned fixtures trước refactor đã pass upload/resume/download/cleanup và private/public/password/expiry; refactor tên không được gọi là một lần live run mới.
• Stress local >2 GiB đã pass; không phải bằng chứng tốc độ GoFile thực tế.
• Soak dài còn phải đọc final report đúng scope; progress hoặc run bị ngắt không được tính là pass.

Các lệnh maintenance hiện hành:

python tools/quality/run_python_matrix.py
python tools/workspace/check_workspace_budget.py --root . --limit-mib 32
python tools/benchmark/run_transfer_stress.py --mib 16 --seconds 7200 --batch-pause 1 \
  --output reports/latest/soak-2h.json

# Live mutations chỉ trên fixture mới do test sở hữu; operator phải opt-in.
python tools/smoke/validate_live_upload_jobs.py --allow-remote-mutations \
  --output reports/latest/live-upload-job.json

CI Windows/macOS/Docker được chuẩn bị nhưng không được tính là đã chạy tại workspace Linux này. Xem testing guide và evidence hiện hành. Báo cáo trong reports/ thuộc checkout/workspace, không mặc định được đóng trong wheel/sdist.

18. Build, chuẩn bị PyPI và tình trạng sẵn sàng

python -m pip install build twine
python -m build --outdir artifacts
python -m twine check artifacts/*.whl artifacts/*.tar.gz

README tiếng Việt là mặc định của repository. Long description PyPI dùng bản tiếng Việt độc lập tại docs/release/PYPI_DESCRIPTION.md, tránh relative links không dùng được trên PyPI. Bản phụ tiếng Anh nằm tại README.en.md; chỉ công bố URL repository/documentation đã được maintainer xác minh.

Trước khi publish cần:

1. Chốt version chưa từng upload; 0.2.0 là version phát hành không có hậu tố rc/dev.
2. Xác minh quyền maintainer và cơ chế xác thực/Trusted Publishing.
3. Test, lint, build, metadata/README rendering, entrypoints và clean wheel/sdist install.
4. Kiểm tra artifact không chứa token, .env, journal cá nhân, cache hoặc dữ liệu tải thử.
5. Xác nhận phạm vi CLI/SDK và MCP stdio, cùng các giới hạn được công bố.
6. Đóng hoặc công bố trung thực các gate native platform/soak còn thiếu.
7. Upload là thao tác riêng, cần phê duyệt phát hành của maintainer.

Kênh phát hành: stable (0.2.0). Nhãn version không đồng nghĩa mọi nền tảng đã được chứng nhận; xem giới hạn nền tảng và vận hành trước khi sử dụng. Chi tiết: hướng dẫn publish, checklist, readiness/MCP.

19. Xử lý lỗi thường gặp

Hiện tượng	Cách kiểm tra đúng
gft không có trong PATH	Xác định environment đang dùng, cài lại package, kiểm tra Scripts/bin; thử python -m gofile_tool --help
PyPI vẫn cài version cũ	Kiểm tra version đã publish chưa; prerelease cần pin/--pre; không đổi distribution name
Thiếu Chromium/Playwright	Cài extra browser và browser riêng; kiểm tra OS deps; không tự tắt sandbox
AUTH_REQUIRED khi upload thư mục	Cung cấp owner token, đúng destination và --job-dir; không dùng guest thay owner
ACCESS_DENIED/PREMIUM_REQUIRED	Kiểm tra quyền/tier/content; không bypass hoặc retry vô hạn
PASSWORD_REQUIRED	Cấp đúng environment variable và password; không echo password vào log
COLLISION khi tải	File đích khác nội dung; dùng output riêng hoặc tự đối soát, không auto-clobber
BUSY	Có writer khác giữ lock; kiểm tra process trước khi can thiệp
Source changed / plan mismatch	Dừng process đang ghi source, lập plan mới; không ép bỏ integrity checks
Job có inflight	Đối soát remote trước; không xóa journal để replay mù quáng
DEADLINE	Xem job/checkpoint và khả năng remote đã commit; tăng budget chỉ sau khi hiểu nguyên nhân
Không có gft mcp	Dùng gft-mcp (có dấu gạch nối), Python ≥3.10 và extra [mcp]

Khi báo lỗi, gửi version, OS/Python, command đã redact, error code, input tối thiểu và loại test (offline/live). Không gửi token, password, private URL hoặc toàn bộ journal chưa xem xét.

20. Tài liệu liên quan và giấy phép

• English README
• Chỉ mục tài liệu
• CLI reference và Automation/SDK contract
• Migration, Architecture, Workspace policy
• Structure review, Readiness/MCP
• Changelog, Contributing, Security
• Nghiên cứu 36 package PyPI: bài học/giới hạn/license, không phải 36 integrations đã được kiểm thử runtime.

Giấy phép Apache License 2.0. Giữ attribution và provenance theo license. Không tự nhận là client chính thức hoặc cam kết vượt giới hạn của dịch vụ.

Thông báo MIT của phần code gốc được giữ nguyên tại LICENSES/MIT-original.txt; xem NOTICE. Thay đổi này không thu hồi quyền MIT của các bản đã phát hành và không đổi giấy phép dependency/upstream.