Metadata-Version: 2.4
Name: gofile-tool
Version: 0.2.0rc4.dev2
Summary: CLI, Python SDK và MCP server cho Gofile với truyền file có kiểm chứng
License-Expression: Apache-2.0
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
License-File: LICENSES/MIT-original.txt
Requires-Dist: requests<3,>=2.31
Requires-Dist: PySocks<2,>=1.7.1
Requires-Dist: requests-toolbelt<2,>=1.0
Requires-Dist: rich<15,>=13.7
Provides-Extra: mcp
Requires-Dist: mcp<1.31,>=1.30; python_version >= "3.10" and extra == "mcp"
Provides-Extra: browser
Requires-Dist: playwright<2,>=1.45; extra == "browser"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=7; extra == "dev"
Requires-Dist: coverage>=7.10; extra == "dev"
Requires-Dist: hypothesis>=6; extra == "dev"
Requires-Dist: build>=1; extra == "dev"
Requires-Dist: ruff>=0.9; extra == "dev"
Requires-Dist: jsonschema>=4; extra == "dev"
Dynamic: license-file

> 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 đang chuẩn bị: `0.2.0rc4.dev2` · Python ≥ 3.9 · Apache-2.0 · development prerelease.**

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

```bash
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.0rc4.dev2-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:

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

```powershell
# 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:

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

```bash
python -m pip install --upgrade --pre 'gofile-tool[browser]==0.2.0rc4.dev2'
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.0rc4.dev2` là development prerelease. `pip install -U gofile-tool` thông thường có thể tiếp tục chọn stable cũ. Không đổi tên package thành `gft` để cập nhật.

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

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

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

```bash
# 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:

```bash
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**:

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

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

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

```bash
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:

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

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

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

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

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

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

```bash
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:

```bash
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:

```json
{
  "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

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

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

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

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

```bash
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:

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

```bash
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.0rc4.dev2` là prerelease, không phải stable.
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: development prerelease.** Bản này dành cho thử nghiệm và tích hợp có kiểm soát; 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.
