AIDiveAgent của bạn là hộp đen
Claude Code, Codex và Gemini CLI là những agent harness do người khác thiết kế — và nếu bạn dành cả ngày làm việc trong một trong số đó, bạn sống với quyết định thiết kế ấy. Muốn đổi một hành vi, thêm một tool, siết một quy tắc quyền hạn? Bạn chờ nhà cung cấp chịu ra bản. Bạn không biết trong system prompt có gì, không thấy vòng lặp chạy các tool, và không đổi được gì trong số đó, dù các tool này đã thành nơi làm việc chính của hàng ngàn lập trình viên.
Một dự án mã nguồn mở đi theo hướng ngược lại hẳn: pi, một toolkit cung cấp các mảnh ghép để tự lắp agent của riêng bạn, từ bộ kết nối mô hình đến giao diện. Nó đạt 92.000 sao GitHub trong năm đầu tiên và ra bản gần như mỗi tuần. Bài viết này nói về những gì pi thực sự cho vào hộp, cách tự xây agent của bạn bằng SDK của nó, và một đánh giá thẳng thắn so với các harness dựng sẵn.
Harness thực chất là gì
Harness là toàn bộ bộ máy quanh một mô hình ngôn ngữ biến nó thành một agent hoạt động được. Một mô hình đơn thuần chỉ làm một việc: đọc văn bản và tạo văn bản. Nó không đọc file của bạn, không chạy một lệnh nào, và không nhớ gì từ phiên này sang phiên khác. Mọi thứ còn lại là harness — system prompt đóng khung mô hình, các tool được cấp cho nó, vòng lặp chạy các lệnh gọi tool và trả kết quả về, và giao diện trong terminal của bạn.
Harness cũng quyết định các chi tiết tạo nên khác biệt mỗi ngày: lịch sử được nén thế nào khi context tràn, lỗi tool báo về mô hình ra sao, cái gì được ghi log và cái gì không. Claude Code là một harness. Codex cũng vậy. Khi một agent làm bạn ấn tượng, phần lớn công lao thuộc về bộ máy đó, không phải mô hình — gắn cùng một mô hình vào hai harness khác nhau và bạn có hai agent hoàn toàn không cùng đẳng cấp.
pi, do Earendil Works làm ra, cắt bộ máy đó thành các khối có thể tái sử dụng. Bạn có thể dùng coding agent của nó nguyên bản, hoặc lấy từng khối một để tự lắp agent riêng. Lựa chọn thứ hai mới là điều chúng tôi quan tâm.
Bên trong toolkit pi
pi là một monorepo — một repo duy nhất chứa năm gói được phát hành riêng — và mỗi gói phụ trách một tầng của harness:
| Gói | Chức năng |
|---|---|
| pi-ai | API thống nhất tới OpenAI, Anthropic, Google và phần còn lại: streaming phản hồi, các khối reasoning với các mức suy nghĩ, tự động dò các mô hình mỗi nhà cung cấp có. Đổi lab chỉ bằng đổi một đối số. |
| pi-agent-core | Chính là vòng lặp agent: trạng thái hội thoại, cộng chu trình gửi tin nhắn, đọc các lệnh gọi tool, chạy chúng và trả kết quả về đến khi xong việc. Các trường hợp éo le — tool bị lỗi, phản hồi bị cắt giữa chừng, các lệnh gọi đến song song — đã được xử lý sẵn. |
| pi-tui | Thư viện render terminal với differential rendering: chỉ vẽ lại phần thay đổi trên màn hình. |
| pi-coding-agent | Coding agent hoàn chỉnh lắp từ các khối trên — bằng chứng cho thấy toolkit đủ để xây một sản phẩm hoàn thiện. |
| pi-telemetry | Gắn số liệu sử dụng riêng mà không phụ thuộc nhà cung cấp. |
Vòng lặp agent chính là phần bạn sẽ viết tệ nếu làm lại từ đầu; viết nó cho đúng tốn hàng tuần, bạn có lại chỉ bằng một import. Đội ngũ áp dụng công thức này ở nơi khác: một repo riêng, pi-chat, dùng lại các khối đó cho tự động hóa hội thoại.
Các con số cho thấy công thức này hiệu quả:
| Chỉ số | Giá trị |
|---|---|
| Sao GitHub | 92.123 |
| Fork | 11.400 |
| Commit | 5.700+ |
| Giấy phép | MIT |
| Bản phát hành trong hai tuần đầu tháng 8/2026 | 3 (v0.84.2 ra ngày 14/8) |
Giấy phép MIT nghĩa là bạn có thể dùng, sửa và phân phối pi không giới hạn, kể cả trong sản phẩm thương mại. pi không phải chỉ thêm một framework: đây là một harness đầy đủ được giao dưới dạng từng mảnh, duy trì với nhịp độ ổn định.
CLI trong thực tế
CLI của pi là coding agent đã lắp sẵn mà bạn nhận được trước khi chạm vào bất kỳ dòng code nào, và đây là nơi bạn sẽ bắt đầu. Cài đặt chỉ một dòng, và cờ --ignore-scripts không phải chi tiết nhỏ: nó chặn dependency của bạn chạy script cài đặt của chúng, một trong những bề mặt tấn công bị lợi dụng nhiều nhất trên npm. Chạy pi, kết nối nhà cung cấp bằng lệnh login, và bạn có ngay một coding agent trong terminal của mình. Thanh trạng thái hiện thư mục hiện tại, phiên làm việc, token đã dùng và chi phí theo thời gian thực — bạn thấy giá mỗi yêu cầu ngay lúc nó gửi đi, thay vì phát hiện hóa đơn vào cuối tháng.
Các lệnh slash lo việc thường ngày: model để đổi mô hình giữa chừng, compact để tóm tắt lịch sử khi context phình to, export để lấy hội thoại ra, settings cho phần còn lại. Một file markdown trong thư mục prompts trở thành một lệnh bạn gọi bằng cách gõ tên nó.
Dấu ấn thật sự của pi nằm ở cách quản lý phiên. Mỗi hội thoại được lưu dạng JSONL trong thư mục home của bạn, sắp theo dự án — và lịch sử thực ra là một cái cây, không phải đường thẳng. Bạn có thể quay lại bất kỳ điểm nào của hội thoại và rẽ hướng khác bằng lệnh fork, rồi di chuyển giữa các nhánh bằng tree. Một prompt thất bại giờ không tốn gì nữa: quay về node trước đó và thử lại, không mất nhánh cũ. Vì mọi thứ được lưu ở máy local, resume đưa bạn về lại bất kỳ phiên cũ nào, dù mấy tuần sau. Cả Claude Code lẫn Codex đều không có điều hướng lịch sử dưới dạng này.
Mặc định, mô hình chỉ được cấp bốn tool: read, write, edit và bash. Rất ít so với các agent trên thị trường, và đó là chủ ý (chúng tôi sẽ quay lại chuyện này ở phần dưới). Cấu hình theo đúng logic đó: một file settings toàn cục trong thư mục home, một file theo từng dự án đè lên, và một hệ thống trust hỏi trước khi áp dụng cài đặt của một thư mục bạn mở lần đầu. Nếu bạn di cư, pi tự động nạp các file AGENTS.md hay CLAUDE.md có sẵn của bạn làm context, nên các chỉ dẫn cũ hoạt động mà không cần viết lại.
Ta tự lắp agent của mình
Xây một agent bằng SDK của pi bắt đầu với một import duy nhất: createAgentSession, được đưa cho một model runtime và một session manager, trả về một agent hoạt động được. Session manager là lựa chọn lưu trữ — trong bộ nhớ cho một script dùng rồi bỏ, hoặc trên ổ đĩa để tìm lại hội thoại của bạn từ lần chạy này sang lần khác.
Chúng tôi đã thử trên một dự án local. Script của chúng tôi hỏi thư mục hiện tại có gì; agent gọi tool read của nó, đọc thư mục và trả lời. Đó là toàn bộ vòng lặp, do chúng tôi viết, trong khoảng mười dòng TypeScript. Các phiên do SDK tạo ra có cùng cấu trúc cây như của CLI — mỗi tin nhắn gắn với tin nhắn cha — nên phân nhánh lịch sử cũng chạy được trong code của riêng bạn.
Custom tool là nơi mọi thứ trở nên thú vị. defineTool nhận một tên, một mô tả, một schema tham số có kiểu và một hàm execute, và tool của bạn hiện ra với mô hình y hệt read hay bash. Chúng tôi viết một tool truy vấn danh sách video của kênh, đưa vào customTools, và agent tự gọi nó ngay từ câu hỏi liên quan đầu tiên. Về cơ bản đây cùng cơ chế với một server MCP, chỉ khác là mọi thứ nằm trong file của bạn — không tách process riêng, không có protocol xen giữa. Vì schema tham số có kiểu, editor của bạn tự động điền đối số và agent nhận đầu vào đã được xác thực sẵn.
Bạn cũng điều khiển mô hình, mức suy nghĩ (từ tắt hẳn đến tối đa), danh sách chính xác các tool mà mô hình thấy được, và thậm chí toàn bộ system prompt qua một resource loader nếu muốn bắt đầu từ trang trắng. Để hiển thị, session.subscribe cho bạn mọi sự kiện — văn bản streaming, lệnh gọi tool, lỗi — mà bạn có thể định tuyến đến bất kỳ đâu: một terminal, một bot nhắn tin, hay một pipeline CI bình luận trên pull request của bạn. Chỉ trong một buổi chiều, bạn chuyển từ dùng agent sang tự viết một cái, và cuối cùng biết được mỗi vòng lặp diễn ra thế nào.
Mở rộng mà không fork
CLI của pi được tùy chỉnh qua bốn cơ chế, tất cả nằm trong các thư mục bình thường trong dự án hoặc home của bạn:
- Extensions — các module TypeScript đăng ký tool, lệnh slash, phím tắt hoặc phần tử UI. Bạn thả file vào thư mục extensions và nó nạp khi khởi động. Đây là nơi bạn viết một lớp bảo vệ quyền, chẳng hạn: một extension chặn các lệnh bash và hỏi xác nhận trước khi chạy lệnh nguy hiểm.
- Skills — gói năng lực theo chuẩn Agent Skills, cùng chuẩn mà Anthropic phổ biến, nên các skill có sẵn của bạn dùng lại được nguyên vẹn.
- Prompts — các prompt tái dùng dưới dạng file markdown thuần túy.
- Themes — hot-reload trong lúc CLI đang chạy.
Tất cả cài đặt như bất kỳ gói nào: pi install nhận một gói npm hay repo git, và một lệnh cập nhật hết. Tài liệu tóm gọn triết lý này trong một câu: điều chỉnh pi theo workflow của bạn, không ngược lại, không fork hay vá bên trong.
Đây là ngược hẳn với các harness lớn. Nơi Claude Code đóng gói sub-agent, plan mode và phân quyền ngay trong sản phẩm, pi cố tình để chúng ở ngoài, để được xây dựng dưới dạng extension hoặc cài từ cộng đồng. Canh bạc rất rõ ràng: một lõi tối thiểu gần như không đổi, và toàn bộ tùy biến nằm về phía bạn, trong các file bạn quản lý phiên bản cùng dự án.
Giới hạn thật sự
Sự minh bạch của pi được trả bằng công sức, và cái giá đó đến từ ba phần.
Trước hết là guardrail: mặc định không có hộp thoại xin quyền, nên agent có thể chạy một lệnh bash mà không hỏi gì bạn. Tài liệu chính thức thừa nhận điều đó và đề xuất ba mẫu cô lập, gồm cả Docker — nhưng thiết lập chúng trước khi thả agent vào một máy quan trọng là việc của bạn.
Rồi đến độ chín: đây là v0.84, không phải 1.0, với khoảng một trăm issue mở và vài API vẫn còn gắn nhãn thử nghiệm, như remote session client mới thêm trong mấy tuần gần đây. Cái hoạt động hôm nay có thể hỏng ở bản phát hành sau; đó là cái giá bình thường của một dự án tiến nhanh thế này.
Và cuối cùng, thời gian. Mọi tiện nghi mà Claude Code cho sẵn ngay từ đầu — plan mode, sub-agent, phân quyền chi tiết — ở đây là dự án bạn phải tự xây, hoặc gói cộng đồng bạn phải săn tìm và hy vọng được duy trì. Hệ sinh thái extension mới một năm tuổi: bạn sẽ thấy nhiều lỗ hổng cần lấp hơn là gói dựng sẵn. Ngay cả việc cài đặt cũng dạy bạn mức cảnh giác cần có, với cờ --ignore-scripts, và bạn phải giữ mức đó xuyên suốt cả chuỗi. Nếu mục tiêu của bạn là ra code tối nay, pi sẽ làm bạn chậm lại trước khi tăng tốc — đừng thay harness chính chỉ vì video này trong tuần này.
pi thực sự dành cho ai
pi dành cho những lập trình viên xây sản phẩm với nhiều agent, không chỉ với một. Với họ, đây có lẽ là khoản đầu tư học hỏi tốt nhất lúc này: cài CLI, viết một agent hai mươi dòng bằng SDK, và cho nó một tool của riêng bạn. Làm vậy và bạn sẽ hiểu Claude Code rõ hơn phần lớn người dùng nó.
Nếu bạn chỉ muốn một trợ lý năng suất hôm nay, hãy giữ harness tích hợp và quay lại khi 1.0 mang guardrail tới: giá trị của pi nằm ở việc hiểu và kiểm soát, không phải tiện lợi tức thì. Giữa hai lựa chọn đó có một con đường an toàn — giữ Claude Code cho công việc, và dùng pi làm bàn thử để hiểu thứ mà công cụ chính của bạn đang giấu bạn.
Điều rút ra nhiều nhất là các harness không còn là hộp đen nữa: các mảnh ghép nằm trên bàn, có tài liệu, giấy phép MIT. Lần sau khi một agent làm bạn ấn tượng hay khó chịu, bạn sẽ biết chính xác mảnh nào cần xem.
