Bỏ qua tới nội dung
Ông T.vn

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

10 phút đọcCập nhật

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 →

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

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.

Plugin

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 đủ.

★ 7.2kTypeScript
Xem repo trên GitHub

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.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.

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

  1. Cài góiChạy npm install -g để có lệnh bili
  2. Kiểm tra PATHBảo đảm thư mục chứa bili nằm trong PATH
  3. Chọn cách dùngNative plugin, launcher hoặc đổi URL
  4. 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:

Terminal
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:

Terminal
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

B.Đư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:

Terminal
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 pluginbili trở 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:

Terminal
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:

Terminal
/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.

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:

Terminal
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.

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:

  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.

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:

Terminal
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

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ư:

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.

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ụ:

Terminal
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.

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.

4.1/5 · Ông T chấm

Chưa có độc giả chấm

Bài này có ích với bạn không?

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%.

Chuyển nhanh tới mục

  1. I.billion-context làm được gì
  2. II.Cần chuẩn bị gì
  3. III.Cài đặt từng bước
    1. A.Cài gói bằng npm
    2. B.Đưa lệnh bili vào PATH
    3. C.Chọn một trong ba cách dùng
    4. D.Cách 1: cài native plugin
    5. E.Cách 2: dùng launcher
    6. F.Cách 3: đổi URL
    7. G.Chạy bằng Docker
  4. IV.Kiểm tra đã chạy được chưa
  5. V.Dùng vào việc thật
    1. A.Lập trình viên làm refactor kéo dài nhiều ngày
    2. B.Tìm lại một chi tiết cũ
    3. C.Người dùng mô hình có cửa sổ nhỏ
    4. D.Giữ chi phí trong tầm kiểm soát
  6. VI.Lỗi hay gặp và cách xử lý
    1. A.Lỗi EACCES khi cài npm
    2. B.Gõ bili báo không tìm thấy lệnh
    3. C.Nén hai lần vì cài trùng
    4. D.Cài tay trên OpenCode 2.x không nạp được
    5. E.Tỉ lệ trúng cache thấp
  7. VII.Có nên dùng không

Repo & Skill · 13/11/2026 · 11 phút đọc

Garden Skills: bộ skill thiết kế web, tạo ảnh, làm video cho AI — hướng dẫn cài đặt và dùng

Garden Skills là bộ sưu tập Agent Skills (kỹ năng cho AI) của tác giả ConardLi, dùng được với Claude Code, Cursor, Codex và các AI coding agent khác. Mỗi skill dạy agent làm tốt một việc như thiết kế trang web, tạo ảnh, làm video bằng code, biến tài liệu thành bài viết đẹp. Cài không khó, nhưng README có nhiều cách cài nên bạn cần chọn một cách hợp với công cụ đang dùng.

Repo & Skill · 13/11/2026 · 15 phút đọc

thesysdev/openui: xây giao diện AI dạng streaming — hướng dẫn cài đặt và dùng

OpenUI là framework full-stack, độc lập framework, giúp mô hình AI sinh giao diện có cấu trúc và hiển thị dần khi dữ liệu streaming về. Bạn có thể dựng nhanh một ứng dụng chat bằng CLI hoặc cài từng gói cho React, Vue, Svelte, Angular và LangChain. Việc bắt đầu khá đơn giản nếu máy có đúng phiên bản Node; README chưa ghi đầy đủ lệnh chạy ứng dụng sau khi scaffold.

Repo & Skill · 13/11/2026 · 11 phút đọc

Ruflo: điều phối nhóm agent AI cho Claude Code và Codex — hướng dẫn cài đặt và dùng

Ruflo (trước đây là Claude Flow) là một agent harness: lớp công cụ bao quanh Claude Code và Codex, bổ sung nhiều agent chuyên biệt, bộ nhớ qua các phiên và khả năng chia việc cho nhóm agent. Cài bằng một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên. Cài khá dễ, nhưng hệ thống rất rộng nên bạn nên bắt đầu từ một tác vụ nhỏ.