# billion-context: nén ngữ cảnh để chạy phiên agent dài hàng tháng — hướng dẫn cài đặt và dùng

> billion-context là plugin/proxy nén ngữ cảnh, đứng giữa công cụ agent (Claude Code, opencode, pi, codex…) và API mô hình. Mô hình tự quyết định lúc nào nén và nén gì thành bản tóm tắt chi tiết, nên phiên làm việc dài không bị tràn cửa sổ. Cài bằng một lệnh npm, rồi chạy `bili <tên client>` là dùng được.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-09-04 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/billion-context-nen-ngu-canh-phien-agent-dai-huong-dan

`billion-context` là một plugin nén ngữ cảnh cho các agent lập trình. Nó đứng giữa công cụ bạn đang dùng (Claude Code, opencode, pi, codex và nhiều client khác) và API của mô hình, rồi viết lại luồng hội thoại để phần đã qua được gói lại thành bản tóm tắt. Nhờ vậy một phiên làm việc có thể chạy rất lâu mà không tràn cửa sổ ngữ cảnh.

Vấn đề nó giải quyết rất quen thuộc. Phiên làm việc với agent càng dài thì càng tốn token, và khi vượt quá cửa sổ ngữ cảnh thì phiên bắt đầu "ngu đi" hoặc chết hẳn. Cách tóm tắt có sẵn của nhiều công cụ thường cắt thô. `billion-context` làm khác: mô hình tự quyết định lúc nào nén và nén đoạn nào, chứ không có một giới hạn cắt cứng.

Ai nên dùng? Lập trình viên hay chạy agent nhiều giờ, nhiều ngày trên cùng một dự án, hoặc người dùng mô hình có cửa sổ nhỏ (tác giả nói 100K là đủ). Điểm đáng giá nhất là nén có thể giải nén lại khi cần chi tiết gốc, và vẫn giữ được prefix cache. Repo hiện có khoảng 7.174 sao và 588 fork, được cập nhật trong 3 tháng gần đây.

```repo
- repo | ranxianglei/billion-context
- kind | Plugin
- desc | billion-context nằm giữa agent lập trình và API mô hình, nén hội thoại thành bản tóm tắt để một phiên chạy hàng tháng mà cửa sổ 100K vẫn đủ.
- stars | 7.2k
- lang | TypeScript
```

## billion-context làm được gì

Proxy này chèn thêm bốn công cụ quản lý ngữ cảnh vào cuộc hội thoại. Mô hình tự gọi chúng khi ngữ cảnh phình to.

- **`compress`**: gói một đoạn tin nhắn thành bản tóm tắt chi tiết. Lợi ích: phần cũ không còn chiếm chỗ, nhưng ý chính vẫn nằm trong lịch sử.
- **`decompress`**: mở lại đoạn đã nén khi cần chính xác từng chi tiết. Ví dụ bạn cần đúng dòng lỗi từ hai tiếng trước.
- **`search_context`**: tìm theo từ khoá trong các bản tóm tắt và các tin nhắn đang hiển thị. Đỡ phải cuộn tìm hay hỏi lại.
- **`acp_status`**: cho biết ngữ cảnh đang dùng bao nhiêu và đoạn nào còn nén được.

Theo tác giả, cách nén này có ba đặc điểm: tăng dần (từng đoạn nhỏ), đảo ngược được (giải nén theo yêu cầu) và thân thiện với prefix cache. Một phiên khoẻ mạnh giữ tỉ lệ trúng prefix cache khoảng 95–97%, riêng phần nén tốn không quá 2%.

Về số liệu, tác giả công bố một bài báo (đặt trong thư mục `paper/`, giấy phép MIT) và một bộ đánh giá bên thứ ba. Trong đó, trên ContextBench, `billion-context` đứng đầu và chi phí thấp hơn khoảng 58,3% so với đưa toàn bộ ngữ cảnh vào. Đây là số do tác giả công bố, bạn nên xem như tham khảo.

Ngoài ra repo hỗ trợ rất nhiều client: pi, opencode, omp, dsh, kimi, hermes, zcode, claude, codex, jcode, gemini, iflow, qwen, antigravity, mcode, aider, copilot, amp, kiro, crush, zed, goose. Client nào không có chỗ cắm plugin thì dùng chế độ launcher hoặc tiền tố `/bili/` trong URL.

## Cần chuẩn bị gì

Tư liệu nói không nhiều, nên mình chỉ liệt kê đúng những gì có:

- **Node.js từ phiên bản 20 trở lên**, vì `package.json` yêu cầu `>=20`.
- **npm**, để cài gói toàn cục.
- **Một client agent bạn đã dùng sẵn** (ví dụ Claude Code hay opencode). `billion-context` không thay client, nó đứng giữa client và API.
- **Tài khoản/khoá API của mô hình** mà client đó đang dùng. README phần đã cung cấp không ghi thêm yêu cầu khoá riêng nào cho `billion-context`.
- Hệ điều hành: README có hướng dẫn cho Linux, macOS và Windows. Về phần cứng (GPU, RAM), tư liệu chưa nói gì.
- Nếu thích container: repo có sẵn `Dockerfile` ở thư mục gốc.

```note
Proxy này nhìn thấy toàn bộ nội dung hội thoại giữa bạn và mô hình, kể cả khoá API đi qua client. Chỉ cài từ gói chính chủ, và đừng đưa phiên chứa dữ liệu nhạy cảm vào nếu bạn chưa hiểu rõ nó chạy thế nào.
```

## Cài đặt từng bước

```steps
- Cài gói | Chạy npm install -g để có lệnh bili
- Kiểm tra PATH | Bảo đảm thư mục chứa bili nằm trong PATH
- Chọn cách dùng | Native plugin, launcher hoặc đổi URL
- Chạy client | Dùng bili <client> hoặc mở client như thường
```

### Cài gói bằng npm

Mở terminal (Terminal trên macOS/Linux, PowerShell trên Windows). Không cần mở trong thư mục đặc biệt nào, vì đây là cài toàn cục. Trên Linux/macOS, README khuyên dùng tiền tố thư mục người dùng để không cần `sudo`:

```bash
npm install -g billion-context --prefix=~/.local
```

Lệnh này cài gói `billion-context` và tạo lệnh `bili` (còn có bí danh `bili-proxy`). Cờ `--prefix=~/.local` đặt nơi cài là thư mục của bạn, nên tính năng tự cập nhật của `bili` không gặp lỗi quyền.

Nếu bạn dùng Node qua nvm hoặc Homebrew, README nói tiền tố mặc định đã thuộc về bạn, chạy lệnh thường là được:

```bash
npm install -g billion-context
```

Trên Windows, tiền tố mặc định (`%APPDATA%\npm`) cũng ghi được, nên dùng lệnh thường:

```powershell
npm install -g billion-context
```

### Đưa lệnh bili vào PATH

Trên Linux/macOS, lệnh `bili` nằm ở `~/.local/bin`. Phần lớn bản phân phối đã có thư mục này trong PATH. Nếu gõ `bili` mà báo không tìm thấy, thêm dòng sau vào `~/.bashrc` hoặc `~/.zshrc`:

```bash
export PATH="$HOME/.local/bin:$PATH"
```

Sau khi sửa, mở terminal mới để dòng này có hiệu lực. Chỗ người mới hay vấp là sửa file xong mà vẫn dùng cửa sổ terminal cũ.

### Chọn một trong ba cách dùng

README đưa ra ba cách, bạn chọn một:

- **Native plugin**: `bili` trở thành plugin bên trong client. Cài một lần, sau đó mở client như bình thường.
- **Launcher**: một lệnh `bili <client>` bật cả proxy lẫn client, không đụng vào file cấu hình thật của bạn.
- **Đổi URL**: thêm tiền tố là địa chỉ proxy cộng `/bili/` vào baseURL của client. Cách này phổ quát nhất.

Người mới nên bắt đầu bằng launcher vì không sửa cấu hình nào.

### Cách 1: cài native plugin

Các client hỗ trợ native hiện nay: pi, omp, opencode (1.x và 2.x), dsh, kimi, hermes, zcode. Các lệnh trong README:

```bash
bili plugin install pi
bili plugin install omp
bili plugin install opencode
bili plugin install dsh
bili plugin install kimi
bili plugin install hermes
bili plugin install zcode
bili plugin remove <client>
```

Mỗi lệnh `install` ghi mục cấu hình vào đúng client. Ví dụ với opencode, nó đăng ký plugin vào cấu hình thật và tắt tính năng tự nén gốc của opencode. Lệnh `remove` để gỡ, và bản cấu hình gốc được lưu thành file `.bili-bak`.

Với Claude Code, repo này còn là một marketplace plugin. Trong Claude Code, gõ lần lượt:

```bash
/plugin marketplace add ranxianglei/billion-context
/plugin install billion-context@billion-context
/billion-context:bili-setup
```

Lệnh cuối chạy `bili plugin install claude` giúp bạn và nhắc bạn khởi động lại Claude Code.

### Cách 2: dùng launcher

Đây là cách ít phải cấu hình nhất. Với Claude Code hoặc codex:

```bash
bili claude
bili codex
```

Với client khác, README ghi mẫu chung là `bili <client>` (ví dụ `bili opencode`, `bili pi`, `bili aider`). Lệnh này bật proxy cùng client, bạn dùng client như bình thường.

Lưu ý với codex: nếu dùng `bili plugin install codex` thì phải bật bili trước, vì phần mở rộng đó không tự khởi động proxy.

### Cách 3: đổi URL

Với client không có chỗ cắm plugin, bạn thêm tiền tố địa chỉ proxy cộng `/bili/` vào baseURL. Địa chỉ proxy chạy tay bằng `bili start` dùng cổng `8787`; các proxy do plugin hoặc launcher tự bật dùng vùng cổng bắt đầu từ `18787`. Chi tiết từng client nằm ở `docs/clients.md` trong repo.

### Chạy bằng Docker

README phần mình có chưa chép đoạn hướng dẫn Docker (đoạn "Running in Docker" bị cắt). Vì vậy mình không đưa lệnh Docker ở đây. Bạn mở `Dockerfile` và mục Docker trong README của repo để xem cách làm.

## Kiểm tra đã chạy được chưa

README phần mình có không ghi một lệnh kiểm tra phiên bản hay màn hình "thành công" cụ thể. Bạn có thể tự kiểm theo các dấu hiệu sau:

1. Gõ `bili` trong terminal mới. Nếu terminal không báo "command not found" thì lệnh đã vào PATH.
2. Chạy client qua `bili <client>` (hoặc mở client sau khi `bili plugin install ...`) và làm việc như bình thường. Client vẫn phải chạy được.
3. Dùng một lúc, rồi trong phiên gõ `/acp`. README nhắc lệnh này (cùng `/acp-cache`) để xem tình trạng cache.
4. Quan sát tỉ lệ trúng prefix cache. Theo tác giả, phiên khoẻ mạnh đạt khoảng 95–97%. Thấp kéo dài thì kiểm tra theo thứ tự nguyên nhân: cache phía nhà cung cấp hết hạn, đổi mô hình, lỗi của bili (nên báo), hoặc nguyên nhân khác.
5. Bạn có thể bảo mô hình dùng công cụ `acp_status` để xem ngữ cảnh đang dùng bao nhiêu.

## Dùng vào việc thật

### Lập trình viên làm refactor kéo dài nhiều ngày

Bạn dùng Claude Code để dọn một dự án lớn, mỗi lần mở lại phiên đều phải "kể lại từ đầu". Cách làm: thay vì gõ `claude`, bạn khởi động bằng:

```bash
bili claude
```

Khi hội thoại dài ra, mô hình tự gọi `compress` để gói những đoạn đã xong. Kết quả: phiên giữ được mạch việc mà không tràn cửa sổ, và bạn không phải bắt đầu phiên mới liên tục.

> Phiên dài không cần cửa sổ khổng lồ, chỉ cần biết nén đúng chỗ.
>
> — Ông T

### Tìm lại một chi tiết cũ

Bạn nhớ lúc đầu phiên có bàn về cách đặt tên bảng dữ liệu, nhưng đã bị nén. Bạn nhắc mô hình bằng một câu như:

```text
Hãy dùng search_context tìm lại chỗ mình bàn về cách đặt tên bảng, rồi decompress đoạn đó nếu cần chi tiết gốc.
```

Đây là câu mẫu mình gợi ý dựa trên bốn công cụ README mô tả. Kết quả mong đợi là mô hình tìm trong các bản tóm tắt, và mở lại đoạn gốc khi cần độ chính xác.

### Người dùng mô hình có cửa sổ nhỏ

Bạn dùng một mô hình giá rẻ có cửa sổ ngữ cảnh khoảng 100K và hay bị đầy giữa chừng. Bạn cài native plugin cho client đang dùng, ví dụ:

```bash
bili plugin install opencode
```

Theo tác giả, 100K là đủ cho phiên dài. Số liệu của họ cho thấy với mô hình có cửa sổ 204.800 token, không có lần nào vượt cửa sổ trong nghiên cứu của họ. Bạn nên tự thử với công việc của mình trước khi tin hẳn.

### Giữ chi phí trong tầm kiểm soát

Nếu bạn trả tiền theo token, bạn có thể mở `/acp` hoặc `/acp-cache` định kỳ để xem cache có khoẻ không. Cache trúng nhiều nghĩa là phần lớn đầu vào được tính giá rẻ hơn. Nếu tỉ lệ tụt kéo dài, bạn biết cần soi các nguyên nhân README liệt kê.

## Lỗi hay gặp và cách xử lý

### Lỗi EACCES khi cài npm

Thường gặp khi tiền tố npm cũ thuộc về root. README nói cách sửa lâu dài là cài lại với `--prefix=~/.local` (và truyền lại cờ này mỗi lần cài lại sau này). Đừng dùng `sudo`.

### Gõ bili báo không tìm thấy lệnh

Thư mục `~/.local/bin` chưa nằm trong PATH. Thêm dòng `export PATH="$HOME/.local/bin:$PATH"` vào `~/.bashrc` hoặc `~/.zshrc`, rồi mở terminal mới.

### Nén hai lần vì cài trùng

Plugin native (`bili plugin install ...`) và các extension độc lập (`billion-context-pi`, `opencode-acp`) không được bật cùng lúc, vì sẽ nén đôi. Trình cài đặt tự thay các mục cũ và sao lưu cấu hình sang `.bili-bak`. Tuy nhiên bản cài theo từng dự án không bị đụng tới, bạn phải tự gỡ bằng tay.

### Cài tay trên OpenCode 2.x không nạp được

README cảnh báo: với OpenCode 2.x, chỉ ghi tên gói trần sẽ không chạy. Cách dễ nhất là dùng `bili plugin install opencode`, vì nó chọn đúng dạng cho phiên bản của bạn. Nếu cài tay, nhớ đặt thêm `"compaction": { "auto": false }` vào cấu hình và sao lưu file trước.

### Tỉ lệ trúng cache thấp

Kiểm tra bằng `/acp` hoặc `/acp-cache`. Nguyên nhân hay gặp theo README: cache phía nhà cung cấp hết hạn, đổi mô hình giữa chừng, hoặc lỗi của chính bili (nên báo cho tác giả).

## Có nên dùng không

**Điểm mạnh.** Cách nén có thể giải nén lại, nên ít rủi ro mất chi tiết hơn kiểu cắt thô. Hỗ trợ nhiều client, từ plugin native đến launcher hay đổi URL. Có bài báo và bộ đánh giá công khai để bạn đối chiếu. Cài chỉ một lệnh npm.

**Giới hạn.** Tài liệu rất dày và phần lớn viết cho người đã quen agent lập trình, nên người mới có thể thấy rối ở bảng chọn client. Nhiều client chỉ có chế độ launcher hoặc đổi URL chứ không có plugin native. Số liệu hiệu quả là do tác giả tự công bố. Về giấy phép, phần mô tả repo không ghi rõ, nhưng trong repo có file `LICENSE`, bạn nên mở ra xem trước khi dùng cho công việc thương mại.

**Khi nào chọn cách khác.** Nếu phiên của bạn ngắn, hiếm khi chạm giới hạn ngữ cảnh, thì tính năng tóm tắt có sẵn của client là đủ. Còn nếu bạn chạy phiên dài, tốn token và cần tìm lại chi tiết cũ, `billion-context` rất đáng thử, nhất là với launcher vì không đụng cấu hình thật của bạn.

## Câu hỏi thường gặp

### billion-context có miễn phí không?

Gói được cài qua npm và mã nguồn nằm công khai trên GitHub. Phần mô tả repo không ghi rõ giấy phép, nhưng trong repo có file LICENSE nên bạn nên mở xem. Bạn vẫn phải trả phí token cho nhà cung cấp mô hình mà client của bạn dùng.

### Có cần GPU không?

Tư liệu chưa nói về yêu cầu GPU hay phần cứng. Đây là proxy viết bằng TypeScript chạy trên Node từ bản 20 trở lên, nằm giữa client và API mô hình.

### Chạy trên Windows được không?

README có hướng dẫn cài cho Windows: dùng `npm install -g billion-context` vì tiền tố mặc định ở đó đã ghi được. Từng client cụ thể có thể có lưu ý riêng, bạn xem docs/clients.md trong repo.

### Nó khác gì tính năng tóm tắt có sẵn của client?

Theo tác giả, nén ở đây là tăng dần, đảo ngược được và giữ prefix cache. Mô hình tự quyết định lúc nào nén và nén gì, thay vì bị cắt theo giới hạn cứng.

### Dữ liệu của mình có an toàn không?

Proxy nằm giữa client và API nên nhìn thấy toàn bộ nội dung hội thoại. Tư liệu chưa có phần nói về chính sách dữ liệu, nên hãy tự đọc mã nguồn và cẩn thận với dữ liệu nhạy cảm.

### Dùng cùng lúc với tiện ích billion-context-pi hay opencode-acp được không?

Không nên. Plugin native và các extension độc lập loại trừ nhau, bật cả hai sẽ nén hai lần. Trình cài đặt tự thay các mục cũ, nhưng bản cài theo từng dự án thì bạn phải tự gỡ.

### Làm sao biết nén có hoạt động tốt?

Gõ `/acp` hoặc `/acp-cache` trong phiên để xem tình trạng cache. Theo README, phiên khoẻ mạnh giữ tỉ lệ trúng prefix cache khoảng 95–97%.
