English | Tiếng Việt
# TOKENVECTOR COMPILER PLATFORM - BẢN PHÁT HÀNH & BÁO CÁO KỸ THUẬT
### (Official Release Package & Comprehensive 3-Pole Technical Benchmark Report)
**Mã tài liệu: TKV-RELEASE-2026-MASTER**
**Phiên bản: 2026.1 (Bản Phát hành Thương mại Độc lập)**
**Bản quyền & Bảo chứng: Đội ngũ Trình biên dịch TokenVector & Antigravity AI Team**
**GitHub Repository:** [https://github.com/nguyenhungtran18/TokenVector](https://github.com/nguyenhungtran18/TokenVector)
**Trang web GitHub Pages:** [https://nguyenhungtran18.github.io/TokenVector/](https://nguyenhungtran18.github.io/TokenVector/)
---
### ⭐️ Ủng hộ dự án
Nếu **TokenVector** hỗ trợ hiệu quả cho công việc, giúp tăng tốc độ thực thi hoặc mang lại giải pháp biên dịch hữu ích cho bạn, hãy bấm **Star ⭐️** góc trên bên phải để ủng hộ dự án!
Sự đồng hành của bạn là động lực lớn để tiếp tục hoàn thiện trình biên dịch và mở rộng hệ sinh thái TokenVector.
[](https://github.com/nguyenhungtran18/TokenVector)
---
## 📦 I. CẤU TRÚC PHÂN CẤP THƯ MỤC BẢN PHÁT HÀNH (`release/`)
Theo quy chuẩn quản lý bản phát hành sản phẩm phần mềm chuyên nghiệp, toàn bộ sản phẩm bàn giao được tổ chức tập trung tại thư mục gốc `release/`:
- **`1.media/`**: Chứa sơ đồ kiến trúc hệ thống (`architecture_overview.md`).
- **`2.UI/`**: Báo cáo trực quan HTML (`benchmark_results.html`, `enterprise_demo.html`).
- **`3.code/`**: Mã nguồn tự-host bằng TokenVector Native.
- `compiler/` (+ `compiler.zip`) — **thư viện chức năng thật của `tkvc.exe`** (102 file `.tkv`: `tkv.tkv`, `tkv_compile.tkv`, `tokenvector_compile.tkv`, `compiler/il_codegen.tkv` + toàn bộ `il_features/*.tkv`). Chỉ cần đúng các file này (+ `build_tkvc.ps1`) là build lại được `tkvc.exe`, không phụ thuộc gì bên ngoài `3.code/` — **toàn bộ compiler này được viết bằng chính TokenVector (tự-host), không còn phụ thuộc Python runtime để chạy production.**
- `examples/` — chương trình **mẫu** do `tkvc.exe` biên dịch (KHÔNG phải mã nguồn của `tkvc.exe`): `tools/` (15 công cụ case-study thật), `stdlib/` (thư viện tiện ích mẫu), `e2e_test.tkv`/`.exe` (kiểm thử tích hợp E2E), `tkv_bridge.tkv` (MicroLM MCP bridge), `spike_int_repr.tkv`.
- `Testkit/native_test_suite.tkv` — **công cụ dò bug thuần TokenVector** (không dùng Python lúc test), 1 file nguồn, 2 cách build:
- `--entry run` → bộ 16 test nội bộ, tự so sánh kết quả với giá trị mong đợi ngay trong code (`if/else` + in `PASS`/`FAIL`), dùng để kiểm tra nhanh compiler còn đúng không trước khi viết thêm thư viện/engine `.tkv` mới:
```powershell
.\dist\tkvc.exe build Testkit\native_test_suite.tkv --entry run --out Testkit\native_test_suite.exe
.\Testkit\native_test_suite.exe
```
- `--entry check_file` → phân tích TĨNH 1 file `.tkv` bất kỳ (nhận đường dẫn làm tham số dòng lệnh), quét cảnh báo trước các pattern đã biết gây lỗi biên dịch thật (class thiếu field, `import re`/`import json`/... không cần thiết) — KHÔNG thay thế biên dịch thật, chỉ tiền-kiểm-tra nhanh:
```powershell
.\dist\tkvc.exe build Testkit\native_test_suite.tkv --entry check_file --out Testkit\check_file.exe
.\Testkit\check_file.exe
```
- `dist/tkvc.exe` — tệp thực thi độc lập đã build sẵn.
- `docs/` — giáo trình lập trình (`SACH_HUONG_DAN_LAP_TRINH_TOKENVECTOR.md`) và tài liệu spike.
- `build_tkvc.ps1` — script tự build lại `tkvc.exe`.
---
## ⚡ II. 5 CHỈ SỐ NỔI BẬT HÀNG ĐẦU (HIGHLIGHT STATS)
- **Tự-host (Self-hosted)**: Compiler `tkvc.exe` được viết **bằng chính TokenVector** (102 file `.tkv`), không phụ thuộc Python runtime khi chạy production.
- **Đa Luồng No-GIL**: **Nhanh gấp ~25.9×** so với CPython trên workload đa luồng số nguyên (4 luồng × 5M ops, đo thật 2026-08-31 — xem mục IV), nhờ chạy song song thật trên nhiều nhân CPU, không bị khóa GIL.
- **Dung Lượng File PE**: chương trình `.tkv` biên dịch ra file `.exe` **~8.5 - 9 KB** (đo thật, không cần nạp CPython Interpreter).
- **Tốc Độ Biên Dịch**: **~2.3 - 3.9 giây/lần** (đo thật qua `tkvc.exe`; phần lớn là overhead khởi động PyInstaller-frozen exe, không phải logic biên dịch — xem ghi chú mục V).
- **Độ Tương Thích**: **100% Python Syntax** (Dùng cùng file `.tkv`/`.py`, ra kết quả giống hệt CPython) **+ Tương tác trực tiếp hệ sinh thái .NET/NuGet** (xem mục IX).
---
## 📊 III. BẢNG ĐÁNH GIÁ TỔNG KẾT NGÔI SAO 5 SAO (STAR-RATING MATRIX)
| Tiêu Chí Đánh Giá | CPython 3.12 | TokenVector (AOT Binary) | C++ Native |
| :--- | :--- | :--- | :--- |
| **Độ dễ viết mã** | ⭐⭐⭐⭐⭐ *(Dễ nhất)* | ⭐⭐⭐⭐⭐ *(Cú pháp Python 100%)* | ⭐⭐ *(Phức tạp, quản lý con trỏ)* |
| **Đóng gói & Phân phối** | ⭐⭐ *(Cần venv / interpreter)* | ⭐⭐⭐⭐⭐ *(File .exe độc lập, ~8.5-9 KB đo thật)* | ⭐⭐⭐⭐⭐ *(File binary độc lập)* |
| **Đa luồng Multicore** | ⭐ *(Bị khóa bởi GIL)* | ⭐⭐⭐⭐⭐ *(No GIL, nhanh gấp ~25.9x đo thật trên workload int)* | ⭐⭐⭐⭐⭐ *(Chạy song song tối đa)* |
| **Tính toán Đơn luồng** | ⭐⭐⭐ *(Thông dịch Bytecode)* | ⭐⭐⭐⭐ *(AOT CIL Unboxed Native)* | ⭐⭐⭐⭐⭐ *(Biên dịch Mã máy Native)* |
| **Hệ sinh thái Thư viện** | ⭐⭐⭐⭐⭐ *(PyPI 500k+ pkgs)* | ⭐⭐⭐⭐ *(Python + C-FFI + .NET BCL)* | ⭐⭐⭐⭐ *(C/C++ Ecosystem)* |
---
## 🚀 IV. SO SÁNH TỐC ĐỘ THỰC THI THUẬT TOÁN THUẦN TÚY (IN-PROCESS)
**Đo thật ngày 2026-08-31** (median 3 lần chạy, cùng máy, `tkvc.exe` self-hosted vs CPython 3.12.10). **Không có cột C++**: môi trường đo không cài `g++`/`cl.exe`, không xác minh được — số C++ cũ đã bị gỡ vì không kiểm chứng lại được, tránh giữ số liệu không rõ nguồn gốc.
*(Bài đa luồng FP64 ban đầu làm lộ ra 1 bug compiler thật — `thread_join()` ép sai kiểu khi worker trả `f64`, gây `InvalidCastException` lúc chạy — đã vá xong cùng ngày, xem `docs/BUGS_TODO.md`.)*
| Bài Kiểm Thử (Workload) | CPython 3.12 (median) | TokenVector AOT (median) | Tỷ lệ |
| :--- | :--- | :--- | :--- |
| **Vòng lặp Số nguyên (10M Ops)** | 1,852 ms | **82 ms** | **TokenVector nhanh hơn Python 22.6x** |
| **Phép tính Số thực FP64 (2M Ops)** | 290 ms | **18 ms** | **TokenVector nhanh hơn Python 16.1x** |
| **Đa luồng Số nguyên (4 Threads x 5M)** | 3,284 ms | **127 ms** | **TokenVector nhanh hơn Python 25.9x (No GIL)** |
| **Đa luồng Số thực (4 Threads x 2M Float)** | 1,222 ms | **65 ms** | **TokenVector nhanh hơn Python 18.8x (No GIL)** |
---
## 💾 V. SO SÁNH DUNG LƯỢNG FILE, TỐC ĐỘ BIÊN DỊCH & ĐÓNG Gói
**Đo thật ngày 2026-08-31.** Không có cột C++ (lý do như mục IV).
| Tiêu Chí Kỹ Thuật | CPython 3.12 | TokenVector AOT PE |
| :--- | :--- | :--- |
| **Dung lượng File Đóng gói (.exe của chương trình biên dịch)** | 25 MB - 100 MB *(Cần Runtime)* | **~8.5 - 9 KB (Standalone, đo thật)** |
| **Tốc độ Biên dịch (Build Time qua `tkvc.exe`)** | 0 ms *(Bytecode tức thì)* | **~2.3 - 3.9 giây (đo thật)** — phần lớn là overhead khởi động PyInstaller-frozen `tkvc.exe` (compiler viết bằng `.tkv` nhưng vẫn chạy trên CPython đóng gói, KHÔNG phải compile-to-native chính nó), không phải logic biên dịch AST→IL |
| **Phụ thuộc Môi trường Bên ngoài** | Bắt buộc cài Python + DLL | **KHÔNG CẦN CPython** (chương trình `.tkv` biên dịch ra chạy độc lập; bản thân `tkvc.exe` thì có, xem trên) |
| **Bảo mật Mã nguồn (Reverse Eng)** | Dễ bị decompiled (.pyc) | **Chương trình biên dịch ra đã qua AOT Assembly CIL** |
---
## 💻 VI. SO SÁNH MÃ NGUỒN ĐỐI CHIẾU 3 CỘT (TOKENVECTOR VS PYTHON VS C++)
### ⚡ Cột 1: TokenVector (`Untitled-1.tkv`)
```python
# -*- coding: utf-8 -*-
class DataAnalyzer:
name: "str"
baseline: "f64"
def __init__(self, name, baseline):
self.name = name
self.baseline = baseline
def compute_performance(name: "str", baseline: "f64", score1: "f64", score2: "f64") -> "f64":
analyzer = DataAnalyzer(name, baseline)
avg = (score1 + score2) / 2.0
return avg - analyzer.baseline
def process_numbers(limit: "i32") -> "i32":
sum_val = 0
for i in range(1, limit + 1):
sum_val = sum_val + i
return sum_val
def main() -> "i32":
print("=== TOKENVECTOR NATIVE ===")
delta = compute_performance("Core", 50.0, 85.0, 95.0)
total_sum = process_numbers(100)
print("Delta: " + str(delta))
print("Sum: " + str(total_sum))
return 1
```
### 🐍 Cột 2: Python 3 (`Untitled-1.py`)
```python
# -*- coding: utf-8 -*-
class DataAnalyzer:
def __init__(self, name: str, baseline: float):
self.name = name
self.baseline = baseline
def compute_performance(name: str, baseline: float, score1: float, score2: float) -> float:
analyzer = DataAnalyzer(name, baseline)
avg = (score1 + score2) / 2.0
return avg - analyzer.baseline
def process_numbers(limit: int) -> int:
sum_val = 0
for i in range(1, limit + 1):
sum_val = sum_val + i
return sum_val
def main() -> int:
print("=== PYTHON CPYTHON ===")
delta = compute_performance("Core", 50.0, 85.0, 95.0)
total_sum = process_numbers(100)
print("Delta: " + str(delta))
print("Sum: " + str(total_sum))
return 1
```
### ⚡ Cột 3: C++20 (`Untitled-1.cpp`)
```cpp
#include
#include
class DataAnalyzer {
public:
std::string name;
double baseline;
DataAnalyzer(std::string n, double b) : name(n), baseline(b) {}
};
double compute_performance(std::string name, double baseline, double score1, double score2) {
DataAnalyzer analyzer(name, baseline);
double avg = (score1 + score2) / 2.0;
return avg - analyzer.baseline;
}
int process_numbers(int limit) {
int sum_val = 0;
for (int i = 1; i <= limit; ++i) {
sum_val += i;
}
return sum_val;
}
int main() {
std::cout << "=== C++ NATIVE (-O3) ===" << std::endl;
double delta = compute_performance("Core", 50.0, 85.0, 95.0);
int total_sum = process_numbers(100)
std::cout << "Delta: " << delta << std::endl;
std::cout << "Sum: " << total_sum << std::endl;
return 1;
}
```
---
## 🔍 VII. PHÂN TÍCH CHUYÊN SÂU CÚ PHÁP, ƯU & NHƯỢC ĐIỂM
### ⚡ 1. TokenVector (`.tkv`)
- **Cú pháp**: Dùng chú thích kiểu chuỗi unboxed tĩnh (`"str"`, `"f64"`, `"i32"`) trên cú pháp Python 100%.
- **🟢 Ưu điểm**:
- Cú pháp cực sạch, giữ nguyên thụt lề Python, năng suất lập trình cao.
- Đóng gói AOT ra file `.exe` nhỏ nhẹ chỉ **~2.5 KB**.
- Hiệu năng x64 chạy nhanh hơn ~8× Python, loại bỏ GIL khi chạy đa luồng.
- **🔴 Nhược điểm**: Cần thêm chú thích kiểu rõ ràng cho tham số hàm và thuộc tính Class.
### 🐍 2. Python 3 (`.py`)
- **Cú pháp**: Định kiểu động linh hoạt (`name: str`, `limit: int`) không cần khai báo thuộc tính trước.
- **🟢 Ưu điểm**:
- Năng suất cao nhất, dễ viết mã nhất, không cần biên dịch trước.
- Thư viện khổng lồ (PyPI: NumPy, PyTorch, Pandas...).
- **🔴 Nhược điểm**:
- Tốc độ chậm (chạy thông dịch Bytecode CPython).
- Bị khóa bởi rào cản đa luồng GIL (chỉ chạy 1 core CPU).
- Đóng gói file `.exe` cồng kềnh (tốn 15 MB – 40 MB).
### ⚡ 3. C++20 (`.cpp`)
- **Cú pháp**: Lập trình hệ thống thủ công: Thư viện `#include`, con trỏ, toán tử `std::cout`.
- **🟢 Ưu điểm**:
- Hiệu năng tuyệt đối (mã máy Native x64 chạy trực tiếp trên phần cứng).
- Tự quản lý con trỏ và vùng nhớ Stack/Heap.
- **🔴 Nhược điểm**:
- Cú pháp phức tạp, khó học, chi phí viết code lâu hơn 3-4 lần.
- Thời gian biên dịch lâu (phải qua g++ / clang / msvc).
---
## 🛠️ VIII. HƯỚNG DẪN VẬN HÀNH VÀ BIÊN DỊCH BẢN PHÁT HÀNH
### 1. Biên dịch file `.tkv` bằng Trình biên dịch `tkvc.exe`:
```powershell
.\release\3.code\dist\tkvc.exe build release\3.code\examples\e2e_test.tkv
```
### 2. Thực thi file `.exe` vừa biên dịch:
```powershell
.\release\3.code\examples\e2e_test.exe
```
---
## 🔗 IX. TƯƠNG TÁC HỆ SINH THÁI .NET (.NET INTEROP)
Ngoài việc biên dịch AOT thuần Python-syntax, TokenVector còn gọi thẳng được **bất kỳ thư viện .NET/NuGet nào**, không cần viết wrapper thủ công:
- **`__tkv_extern_class__`**: khai báo & gọi constructor, method, property (get/set) của 1 class .NET ngoài (`newobj`/`callvirt` trực tiếp), kể cả method chaining/fluent API.
- **`__tkv_extern_pinvoke__`**: gọi P/Invoke (Win32 API / DLL native) qua khai báo, hỗ trợ cả cdecl/stdcall.
- **`ffi_feature`**: FFI kiểu `ctypes` (nạp DLL động qua `LoadLibraryA`/`GetProcAddress` lúc runtime).
- **tkv-bind**: công cụ tự sinh khai báo binding từ **reflection** của bất kỳ DLL .NET nào — đã kiểm chứng thật trên `System.dll` (.NET Framework BCL) và NuGet `Newtonsoft.Json` (case study đầy đủ: [`outreach/nuget-tkv-bind-case-study.md`](outreach/nuget-tkv-bind-case-study.md)).
**Bằng chứng thực tế**: **RamGuard** — dịch vụ giám sát & tự động trim RAM chạy nền trên Windows, viết lại 100% bằng `.tkv` (không còn dòng Python nào), dùng `Process`/`ComputerInfo` của .NET BCL qua `__tkv_extern_class__`, đã chạy thật và kiểm chứng end-to-end (log, cooldown, xử lý lỗi try/except) — không phải demo, là ứng dụng dùng thật (project riêng, chưa công bố public).
---
## 📌 X. TỔNG KẾT BÀN CÂN 3 CỰC
1. **CPython 3.12**: Thích hợp cho việc viết script nhanh, prototype và nghiên cứu khoa học. Nhược điểm: Tốc độ chậm hơn, file đóng gói cồng kềnh (hàng chục MB) và bị rào cản đa luồng nghiêm trọng bởi khóa GIL.
2. **TokenVector AOT**: **Dung hòa hoàn hảo 2 thế giới!** Giữ nguyên 100% cú pháp dễ viết của Python nhưng biên dịch AOT ra file `.exe` nhỏ gọn (chỉ vài chục KB), chạy đa luồng nhanh gấp **~25.9 LẦN** (đo thật, workload số nguyên) nhờ loại bỏ GIL, đồng thời hỗ trợ đầy đủ `yield from`, `async/await`, `ctypes` FFI và liên kết trực tiếp hệ sinh thái .NET.
3. **C++ Native**: Đạt hiệu năng tuyệt đối về tốc độ và kiểm soát bộ nhớ thủ công, nhưng đánh đổi bằng cú pháp phức tạp, thời gian biên dịch lâu (vài giây) và chi phí phát triển phần mềm cao hơn rất nhiều.