billion-context: nén ngữ cảnh cho phiên AI coding 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à một plugin/proxy nén ngữ cảnh cho các agent lập trình như Claude Code, pi, opencode, codex. Nó chen vào giữa agent và API mô hình, để chính mô hình tự gom đoạn hội thoại cũ thành bản tóm tắt chi tiết, nhờ vậy phiên dài không bị tràn cửa sổ. Cài bằng một lệnh npm (cần Node 20 trở lên) nên không khó, nhưng phần cấu hình theo từng client khá nhiều.
billion-context là một plugin nén ngữ cảnh cho các agent lập trình. Nó đứng giữa agent của bạn (Claude Code, pi, opencode, codex…) và API của mô hình, rồi viết lại luồng hội thoại để phần cũ được gom thành bản tóm tắt gọn. Lệnh điều khiển của nó tên là bili.
Vấn đề nó giải quyết rất quen với ai hay làm việc lâu với AI. Phiên chat dài thì ngữ cảnh phình to, tiền token tăng theo, và khi vượt cửa sổ ngữ cảnh thì phiên bắt đầu kém đi hoặc chết hẳn. Thay vì cắt cụt, billion-context để chính mô hình quyết định lúc nào nên nén và nén đoạn nào. Tác giả mô tả mục tiêu là chạy một phiên đơn kéo dài hàng tháng, và cửa sổ khoảng 100K là đủ.
Bạn nên đọc bài này nếu đang dùng agent lập trình hằng ngày và hay gặp cảnh phải mở phiên mới, giải thích lại từ đầu. Điểm đáng giá nhất là nén kiểu tăng dần và có thể hoàn lại, nên bạn không mất chi tiết vĩnh viễn. Repo hiện có khoảng 7174 sao và 588 fork, và vẫn được cập nhật trong vài tháng gần đây.
ranxianglei/billion-context
Công cụ nén ngữ cảnh đứng giữa agent lập trình và API mô hình, giúp một phiên làm việc chạy hàng ngày mà không tràn cửa sổ ngữ cảnh.
I.billion-context làm được gì
Cơ chế chính là proxy 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 thấy ngữ cảnh đầy dần:
compressgom một đoạn tin nhắn thành bản tóm tắt chi tiết. Lợi ích là phần việc đã xong không còn chiếm chỗ, nhưng ý chính vẫn nằm trong lịch sử.decompresskhôi phục đoạn đã nén khi bạn cần lại chi tiết chính xác. Nhờ đó nén không phải là quyết định một chiều.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ị. Hợp khi bạn nhớ mang máng đã bàn chuyện gì đó từ hôm trước.acp_statusxem tổng quan mức dùng ngữ cảnh và đoạn nào còn nén được.
Tác giả nhấn mạnh ba điểm khác với bộ tóm tắt có sẵn của từng công cụ: nén theo từng đoạn nhỏ (tăng dần), có thể giải nén theo nhu cầu, và giữ nguyên phần đầu (prefix) để cache của nhà cung cấp vẫn trúng. README ghi một phiên khoẻ mạnh giữ tỉ lệ trúng prefix-cache khoảng 95–97%, và bản thân việc nén tốn không quá 2%.
Ngoài ra, repo đi kèm một bài báo nghiên cứu (thư mục paper/) và các bản đánh giá độc lập. Theo README, trên bộ thử nghiệm 1.500 câu hỏi, billion-context đứng đầu ở ContextBench và giảm khoảng 58,3% chi phí so với đưa toàn bộ ngữ cảnh vào. Đây là số liệu do tác giả công bố, bạn nên xem như tham khảo.
Bảng tương thích khá rộng: pi, opencode, omp, dsh, kimi, hermes, zcode, claude, codex, jcode, gemini, iflow, qwen, antigravity, mcode, aider, copilot, amp, kiro, crush, zed, goose. Với công cụ không có hook ngữ cảnh, README bảo dùng bili <client> hoặc tiền tố /bili/.
II.Cần chuẩn bị gì
- Node.js 20 trở lên
package.jsonyêu cầu>=20. Cần cónpmđi kèm. - Một agent lập trình đang dùng đượcví dụ Claude Code, pi, opencode, codex… billion-context không thay agent, nó chỉ đứng giữa agent và API.
- Tài khoản/API key của chính agent đóREADME đoạn mình có không nói billion-context đòi key riêng. Bạn vẫn dùng đăng nhập hoặc key sẵn có của client.
- Hệ điều hànhREADME hướng dẫn riêng cho Linux/macOS và Windows. Repo còn có
Dockerfileở thư mục gốc nếu bạn thích chạy bằng container. - Phần cứngtư liệu không nhắc yêu cầu GPU. Đây là proxy chạy trên máy bạn nên mình nghĩ không cần, nhưng README chưa khẳng định.
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, gồm cả mã nguồn và có thể cả key. Chỉ cài từ nguồn bạn tin, và đừng dùng nó trên máy chứa dữ liệu mật nếu chưa đọc kỹ cách nó hoạt động.
III.Cài đặt từng bước
- Kiểm tra NodeĐảm bảo máy có Node 20 trở lên
- Cài billion-contextChạy một lệnh npm để có lệnh bili
- Kiểm tra PATHChắc chắn lệnh bili gọi được trong terminal
- Chọn cách dùngPlugin gốc, launcher hoặc đổi URL
- Khởi động agentChạy client như bình thường hoặc qua bili
A.Kiểm tra Node
Mở terminal (Terminal trên macOS/Linux, PowerShell trên Windows) và xem phiên bản Node. Cần từ 20 trở lên.
node --versionB.Cài billion-context
Với Linux/macOS, README khuyên cài vào thư mục người dùng. Cách này không cần sudo, không đụng cấu hình npm, và tính năng tự cập nhật của bili không bị lỗi quyền.
npm install -g billion-context --prefix=~/.localVới nvm hoặc Homebrew Node, thư mục mặc định đã thuộc quyền người dùng, nên chạy lệnh thường là đủ:
npm install -g billion-contextTrên Windows, README ghi thư mục mặc định (%APPDATA%\npm) cũng ghi được, nên dùng lệnh thường:
npm install -g billion-contextLệnh này cài ra bili. Tên bili-proxy được giữ làm bí danh.
C.Kiểm tra PATH
Với cách cài có --prefix=~/.local, lệnh bili nằm ở ~/.local/bin. Hầu hết bản Linux đã 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, rồi mở lại terminal:
export PATH="$HOME/.local/bin:$PATH"Bạn gặp EACCES vì trước đây cài bằng prefix thuộc quyền root? README bảo cài lại với --prefix=~/.local và tránh sudo. Các lần cài lại sau này cũng nên thêm cờ đó.
D.Chọn cách dùng
README đưa ra ba hướng. Chọn một:
- Plugin gốc
bili plugin install <client>. bili trở thành plugin bên trong client, bạn cứ mở client như thường. - Launchergõ
bili <client>, nó bật proxy và client cùng lúc mà không sửa file cấu hình thật của bạn. - Đổi URLthêm tiền tố địa chỉ proxy +
/bili/vào baseURL của client. Cách này dùng được với mọi client.
Ví dụ cài dạng plugin gốc cho các client được README liệt kê:
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 zcodeMuốn gỡ thì dùng:
bili plugin remove <client>Bản cấu hình gốc được sao lưu thành file .bili-bak.
Nếu bạn dùng Claude Code, repo này còn là một marketplace plugin. Gõ lần lượt trong Claude Code:
/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.
E.Khởi động agent
Với launcher, chỉ cần gõ tên client sau bili:
bili claude
bili codex
bili opencodeVới codex có lưu ý riêng: nếu dùng bili plugin install codex thì phải chạy bili trước, vì phần vỏ MCP không tự bật proxy. Launcher bili codex là cách đầy đủ nhất.
Cổng mạng: bili start (chạy tay) dùng cổng 8787. Các launcher và hook tự bật proxy sẽ dùng vùng cổng bắt đầu từ 18787, trùng thì tự nhảy sang cổng kế. Bạn thường không phải chỉnh gì.
Quan trọng: plugin gốc (bili plugin install ...) và các extension độc lập (billion-context-pi, opencode-acp) loại trừ nhau. Bật cả hai sẽ nén hai lần. Trình cài đặt sẽ thay các mục cũ giúp bạn, nhưng bản cài ở cấp dự án thì bạn phải gỡ tay.
Phần chi tiết cho từng client README dẫn sang docs/clients.md. Cấu hình nâng cao có trong CONFIGURATION.md ở gốc repo. Mục chạy bằng Docker README nhắc tới nhưng đoạn mình có đã bị cắt, nên bạn mở thẳng README để xem.
IV.Kiểm tra đã chạy được chưa
Tư liệu mình có không ghi lệnh kiểm tra phiên bản riêng, nên mình chỉ nêu những gì chắc chắn:
- Gõ
bilitrong terminal. Nếu báo không tìm thấy lệnh thì quay lại bước PATH. - Chạy client qua
bili claude(hoặc client bạn chọn) và làm việc như bình thường. Nếu client mở lên và trả lời được, proxy đang thông. - Trong phiên làm việc, gõ
/acphoặc/acp-cache. README nói hai lệnh này dùng để xem phân tích cache. Bạn cũng có thể nhờ mô hình gọiacp_statusđể xem mức dùng ngữ cảnh. - Sau khi phiên đã dài, nhìn tỉ lệ trúng cache. README nói mức khoẻ mạnh là khoảng 95–97%.
Chưa thấy nén ngay sau vài tin nhắn đầu là bình thường, vì mô hình chỉ nén khi ngữ cảnh bắt đầu lớn.
V.Dùng vào việc thật
A.Lập trình viên làm một dự án lớn nhiều ngày
Bạn đang refactor một codebase lớn bằng Claude Code. Cứ vài giờ là ngữ cảnh đầy, phải mở phiên mới và dặn lại bối cảnh. Với billion-context, bạn chạy:
bili claudeBạn làm việc như thường. Khi ngữ cảnh lớn dần, mô hình tự gọi compress để gom các bước đã xong thành bản tóm tắt. Kết quả là bạn giữ được một phiên liền mạch lâu hơn, và vẫn có thể bảo mô hình tìm lại một quyết định cũ.
Không phải cắt bỏ ký ức, mà là gấp nó lại để khi cần thì mở ra.
Ông T
B.Người mới muốn cắm vào Claude Code thật nhanh
Bạn không thích gõ bili mỗi lần và muốn cài một lần cho xong. Dùng đường marketplace trong Claude Code:
/plugin marketplace add ranxianglei/billion-context
/plugin install billion-context@billion-context
/billion-context:bili-setupSau khi khởi động lại Claude Code, bạn mở nó như thường ngày. README ghi plugin này không tự thêm hook hay MCP riêng nên không bị đăng ký trùng.
C.Người đang trả tiền theo token và muốn kiểm tra cache
Bạn thấy hoá đơn API cao bất thường trong phiên dài. Trong phiên làm việc, gõ:
/acp-cacheREADME nói nếu tỉ lệ trúng cache thấp kéo dài, các nguyên nhân thường gặp theo thứ tự là: cache phía nhà cung cấp hết hạn, đổi mô hình giữa chừng, lỗi của bili (nên báo cho tác giả), hoặc không rõ. Việc biết nguyên nhân giúp bạn tránh đổi mô hình giữa phiên một cách vô ý.
D.Dùng với công cụ không có plugin
Bạn xài aider, Gemini CLI hoặc Goose, những công cụ không có chỗ cắm plugin. README chỉ dùng launcher:
bili aider
bili gemini
bili gooseVới các công cụ này, bili làm việc ở tầng mạng nên một số tính năng bên trong vòng lặp có thể bị hạn chế. README ghi rõ aider và gemini không có chế độ native. Chi tiết từng công cụ xem docs/clients.md.
VI.Lỗi hay gặp và cách xử lý
EACCESkhi cài npmdo thư mục cài đặt thuộc quyền root. Cách an toàn là cài lại vớinpm install -g billion-context --prefix=~/.local, không dùngsudo.- Gõ
bilibáo không tìm thấy lệnhthư mục~/.local/binchưa nằm trong PATH. Thêmexport PATH="$HOME/.local/bin:$PATH"vào~/.bashrchoặc~/.zshrcrồi mở terminal mới. - Bị nén hai lần, phản hồi lạbạn đang bật cả plugin gốc lẫn extension độc lập như
billion-context-pihoặcopencode-acp. Chạy lạibili plugin install <client>để trình cài thay mục cũ. Nếu bản cũ nằm ở cấp dự án, gỡ tay. - Tỉ lệ cache thấp kéo dàidùng
/acphoặc/acp-cacheđể xem nguyên nhân. Kiểm tra xem bạn có đổi mô hình giữa chừng không, và nhớ rằng cache phía nhà cung cấp cũng có hạn. - Cổng bị chiếmnếu
bili startkhông lên cổng8787, kiểm tra xem tiến trình nào đang giữ cổng. Các launcher tự nhảy sang cổng khác bắt đầu từ18787.
VII.Có nên dùng không
Điểm mạnh. Cách nén tăng dần, có thể hoàn lại, giữ cache là cách tiếp cận đáng thử cho người hay chạy phiên dài. Danh sách client được hỗ trợ rất rộng. Số liệu tác giả công bố, từ nghiên cứu thực tế dài tháng đến các bài đánh giá, cho thấy họ làm khá nghiêm túc. Repo có tài liệu riêng cho cấu hình, vòng đời và kỹ thuật.
Giới hạn. Số lượng chế độ cài (plugin gốc, launcher, đổi URL) và ghi chú riêng cho từng client khiến người mới dễ rối. Với các client chỉ dùng được qua launcher hoặc cert-MITM, bạn phải chấp nhận proxy can thiệp tầng mạng. README hiện không ghi rõ giấy phép ở phần mình có, dù repo có file LICENSE (riêng bài báo là MIT), nên nếu dùng trong công ty, bạn nên mở file đó ra xem. Mọi con số hiệu quả là do tác giả công bố, bạn nên tự đo trên phiên của mình.
Khi nào chọn cách khác. Nếu bạn chỉ chat ngắn, phiên hiếm khi chạm giới hạn ngữ cảnh, thì không cần thêm một lớp proxy. Nếu dữ liệu quá nhạy cảm và bạn không muốn thêm bất kỳ thành phần nào đứng giữa, hãy dùng chức năng tóm tắt có sẵn của client. Còn nếu phiên của bạn thường xuyên tràn hoặc tốn token, đây là công cụ đáng cài thử trước.
Câu hỏi thường gặp
billion-context có miễn phí không?
Gói npm billion-context cài được bằng lệnh npm thông thường và README không nhắc phí bản quyền. Tuy vậy bạn vẫn phải trả tiền API cho mô hình mà agent của bạn gọi. Về giấy phép, đoạn README mình có không ghi rõ, repo có file LICENSE để bạn tự kiểm tra.
Có cần GPU không?
Tư liệu không nêu yêu cầu GPU. billion-context là proxy/plugin viết bằng TypeScript, chạy trên Node 20 trở lên, và mô hình vẫn chạy ở phía nhà cung cấp API. Chưa có thông tin chi tiết hơn về phần cứng.
Chạy trên Windows được không?
Được. README có hướng dẫn riêng cho Windows: thư mục npm mặc định thuộc quyền người dùng nên chỉ cần chạy npm install -g billion-context. Mức hỗ trợ cụ thể cho từng client trên Windows bạn xem thêm trong docs/clients.md.
Dữ liệu của tôi có an toàn không?
Công cụ đứng giữa agent và API mô hình, nên nó nhìn thấy nội dung hội thoại. README đoạn mình có không bàn về bảo mật dữ liệu, nên chưa có kết luận. Hãy đọc mã nguồn và tài liệu kỹ thuật trước khi dùng với dự án nhạy cảm.
Khác gì tính năng tóm tắt có sẵn của Claude Code hay các agent khác?
Theo tác giả, nén ở đây là tăng dần, có thể giải nén lại khi cần và giữ nguyên prefix để cache vẫn trúng. Bộ tóm tắt có sẵn của client thường không có cả ba đặc điểm này. Chính mô hình quyết định khi nào và nén đoạn nào.
Nên chọn plugin gốc hay launcher?
Plugin gốc (bili plugin install) cài một lần rồi mở client như bình thường, nhưng chỉ có cho một số client như pi, omp, opencode, dsh, kimi, hermes, zcode và claude. Launcher (bili <client>) không đụng file cấu hình thật và dùng được với nhiều client hơn. Đừng bật cả plugin gốc lẫn extension độc lập cùng lúc vì sẽ nén hai lần.
Cần Node phiên bản nào?
package.json yêu cầu Node từ phiên bản 20 trở lên. Kiểm tra bằng lệnh node --version trước khi cài.


