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
Bài này là một góc nhìn khác về ranxianglei/billion-context — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: billion-context: nén ngữ cảnh cho phiên agent chạy hàng tuần — hướng dẫn cài đặt và dùng →

Tóm tắt nhanh
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.
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.
ranxianglei/billion-context
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 đủ.
I.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.
compressgó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ử.decompressmở 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_contexttì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_statuscho 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.
II.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.jsonyê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-contextkhô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.
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.
III.Cài đặt từng bước
- Cài góiChạy npm install -g để có lệnh bili
- Kiểm tra PATHBảo đảm thư mục chứa bili nằm trong PATH
- Chọn cách dùngNative plugin, launcher hoặc đổi URL
- Chạy clientDùng bili <client> hoặc mở client như thường
A.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:
npm install -g billion-context --prefix=~/.localLệ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:
npm install -g billion-contextTrên Windows, tiền tố mặc định (%APPDATA%\npm) cũng ghi được, nên dùng lệnh thường:
npm install -g billion-contextB.Đư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:
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ũ.
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
bilitrở thành plugin bên trong client. Cài một lần, sau đó mở client như bình thường. - Launchermộ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 URLthê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.
D.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:
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:
/plugin marketplace add ranxianglei/billion-context
/plugin install billion-context@billion-context
/billion-context:bili-setupLệ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.
E.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:
bili claude
bili codexVớ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.
F.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.
G.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.
IV.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:
- Gõ
bilitrong terminal mới. Nếu terminal không báo "command not found" thì lệnh đã vào PATH. - Chạy client qua
bili <client>(hoặc mở client sau khibili plugin install ...) và làm việc như bình thường. Client vẫn phải chạy được. - 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. - 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.
- 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.
V.Dùng vào việc thật
A.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:
bili claudeKhi 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
B.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ư:
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.
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ụ:
bili plugin install opencodeTheo 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.
D.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ê.
VI.Lỗi hay gặp và cách xử lý
A.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.
B.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.
C.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.
D.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.
E.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ả).
VII.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%.


