Pi là gì: lịch sử và triết lý

Pi tự mô tả bằng đúng một câu ở đầu README: “a minimal, extensible agent harness that you can make your own”, một harness cho agent, tối giản, mở rộng được, và để bạn biến thành của riêng mình (README.md:15). Để hiểu mã nguồn, trước hết cần hiểu ba từ trong câu đó, và vì sao những người viết ra Pi chọn chúng.

Harness là phần mềm bao quanh một mô hình ngôn ngữ để biến nó thành agent. Bài “What is a Harness?” của Earendil tóm lại bằng công thức Agent = Model + Harness và liệt kê bốn việc mà mọi harness đều làm: đưa ra chỉ dẫn (system prompt), mô tả và cung cấp công cụ (tools), điều khiển vòng lặp agent (agentic loop), và một lớp phiên dịch để chạy được với nhiều mô hình khác nhau (earendil.com, 2026-08-20). Cả tài liệu này thực chất là đi xem Pi làm bốn việc đó như thế nào, ở mức từng dòng code.

Dòng thời gian#

Pi bắt đầu là dự án cá nhân của Mario Zechner (tác giả libGDX), trong một monorepo tên pi-mono, các package npm mang scope @mariozechner. Lịch sử git trong bản clone ghi lại khá rõ quá trình đó; các ngày dưới đây lấy từ commit và tag của repo (trừ các bài blog, có ghi nguồn).

Tính tới v1.4.0, repo có 7.042 commit và 331 tag. Mario Zechner là tác giả của khoảng 3.955 commit, Armin Ronacher khoảng 910 (theo git shortlog -sn trên bản clone). Bài công bố Pi 1.0 nói Pi có “hàng trăm nghìn” người dùng mỗi tuần (earendil.com/posts/pi-1-0); con số này là tuyên bố của Earendil, không có trong repo.

Vì sao Pi ra đời#

Mario viết Pi vì các coding agent thương mại thời điểm đó đi ngược cách anh làm việc: tính năng ngày càng nhiều, system prompt thay đổi liên tục giữa các phiên bản, và người dùng gần như không thấy được mô hình thực sự nhận được gì. Bài blog năm 2025 liệt kê những thứ anh muốn có (mariozechner.at):

• Kiểm soát ngữ cảnh. “Context engineering is paramount”: cái gì vào cửa sổ ngữ cảnh phải do người dùng quyết định, không bị harness chèn thêm.
• Nhìn thấy mọi tương tác với mô hình, điều mà theo anh hầu như không harness nào cho phép.
• Một định dạng session được tài liệu hoá rõ ràng, để có thể xử lý lại bằng công cụ khác.
• Dễ dựng giao diện khác trên cùng một lõi agent (terminal, web, Slack…).
• Chạy tốt với mô hình tự host, nhất là phần gọi tool, thứ mà các harness dựa trên lớp trừu tượng chung thường làm kém.

Nguyên tắc chọn tính năng được anh nói thẳng: “if I don't need it, it won't be built”. Bốn năm tháng sau, khi Pi đã là sản phẩm của Earendil, nguyên tắc đó vẫn giữ nhưng được diễn đạt lại thành “độ phức tạp phải tự chứng minh giá trị của nó” (bài “Pi, Minimal and Performant”).

Bảy nguyên tắc thiết kế#

Đọc code Pi sẽ dễ hơn nhiều khi biết các nguyên tắc sau, vì phần lớn quyết định kỹ thuật là hệ quả trực tiếp của chúng.

1. Lõi tối giản, mặc định mạnh#

Pi chỉ có bốn công cụ mặc định và một system prompt ngắn; bài blog năm 2025 cho biết system prompt cộng định nghĩa tool lúc đó dưới 1.000 token. README nói rõ Pi “bỏ qua” những tính năng mà các agent khác coi là hiển nhiên, như sub-agent và plan mode, và mời bạn tự xây hoặc cài package làm điều đó theo cách của bạn (README.md:19). Những tính năng bị “bỏ qua” này vẫn tồn tại, nhưng dưới dạng ví dụ extension (chương Extensions đi qua plan-mode và subagent).

2. Người dùng làm chủ ngữ cảnh, và giữ prefix ổn định#

Pi tránh tự ý sửa những gì đã gửi cho mô hình. Lý do không chỉ là minh bạch mà còn là tiền: prompt cache của provider chỉ trúng khi phần đầu (prefix) của chuỗi token giống hệt lần trước. Bài “Prompt Caching In Agents” giải thích Pi ưu tiên bản ghi chỉ-nối-thêm (append-oriented), không cắt tỉa ngữ cảnh cũ một cách hung hăng, và coi compaction là một lần “reset cache” có chủ đích (earendil.com/posts/prompt-caching). Nhiều tính năng của bản 1.0, như thông điệp hệ thống giữa hội thoại và nạp tool trì hoãn, tồn tại chính để giữ prefix không đổi (chương Pi 1.0).

3. Dễ uốn nắn: agent tự viết phần mở rộng cho chính nó#

Extension là module TypeScript chạy ngay trong tiến trình Pi; factory của nó đăng ký tool, lệnh, phím tắt, provider, trình xử lý sự kiện và cả giao diện terminal (how-pi-works.md:43). Armin Ronacher mô tả cách dùng điển hình: thay vì cài extension của người khác, bạn bảo Pi tự viết hoặc chỉnh một extension có sẵn, tải lại nóng (hot reload), thử, và lặp lại. Để điều đó khả thi, Pi đi kèm tài liệu và ví dụ mà chính agent đọc được. Bài “What is a Harness?” cho biết cộng đồng đã chia sẻ hơn 5.000 extension.

4. Session là dữ liệu của bạn, mang đi được#

Session được lưu thành file JSONL; mỗi entry có ID và trỏ tới entry cha, nên cả session là một cái cây (how-pi-works.md:27). Một session có thể chứa tin nhắn của nhiều provider khác nhau, nên Pi tránh phụ thuộc vào các tính năng riêng của từng provider. Bài “The Session You Cannot Take With You” đẩy ý này thành nguyên tắc: nhật ký sự kiện cục bộ là bản gốc, và trạng thái mà provider niêm phong (lý luận mã hoá, compaction mờ đục) không được là nơi duy nhất chứa ý nghĩa; Pi không bao giờ chuyển compaction bị niêm phong của provider này sang provider khác (earendil.com/posts/session-portability).

5. Không có hệ thống phân quyền: an toàn đến từ ranh giới hệ điều hành#

Đây là quyết định gây tranh cãi nhất. Pi không có lớp phân quyền nào cho file, tiến trình, mạng hay credential; nó chạy với quyền của người đã khởi động nó (README.md:88–90). Lập luận của Mario: một agent đọc được dữ liệu, chạy được code và truy cập được mạng thì luôn có thể bị prompt injection lợi dụng để rò rỉ dữ liệu; các biện pháp như hỏi xác nhận từng lệnh hay danh sách tên miền chỉ cho cảm giác an toàn. Vì vậy tài liệu bảo mật yêu cầu coi lệnh và code do mô hình sinh ra là không đáng tin, và tìm an toàn ở container, máy ảo hoặc sandbox (security.md:3). Cơ chế project trust chỉ quyết định có nạp tài nguyên của thư mục dự án hay không, chứ không giới hạn những gì tool làm được (security.md:31–33).

6. Trung lập với mô hình#

Lớp phiên dịch pi-ai nói chuyện trực tiếp với API của từng provider thay vì đi qua một thư viện trừu tượng chung, và một session có thể đổi mô hình giữa chừng. Earendil coi đây là cách trả quyền lựa chọn cho người dùng: cùng một harness, bạn so được kết quả và chi phí của Anthropic, OpenAI hay mô hình mã nguồn mở trên cùng công việc. Ở v1.4.0, pi-ai định nghĩa sẵn 42 provider: hãng gốc, nền tảng cloud, gateway, gói thuê bao, và cả mô hình chạy trên máy bạn. Chương Provider vẽ bản đồ đó và mọi cách kết nối.

7. Tối giản để rẻ và nhanh#

Bài “Pi, Minimal and Performant” dẫn một benchmark nội bộ của Databricks: với cùng mô hình và mức suy nghĩ, Pi có tỷ lệ hoàn thành cao nhất với chi phí thấp hơn đáng kể so với Claude Code và Codex, và gửi ít ngữ cảnh hơn khoảng 3 lần mỗi lượt (earendil.com). Đây là số liệu do Earendil trích dẫn, không phải kết quả bạn kiểm chứng được từ repo.

Những điều Pi đã đổi ý, và những điều giữ nguyên#

Một dự án tối giản vẫn thay đổi khi bằng chứng thay đổi. Hiểu những lần “đổi ý” này giúp bạn nhận ra phần nào trong code là lớp mới đắp lên lõi cũ.

Pi 1.0 và Pi Durable#

Ngày 2026-10-01, Earendil phát hành Pi 1.0 như một harness “đã được tôi luyện” mà người và doanh nghiệp có thể dựa vào. Changelog của bản 1.0.0 khá ngắn, vì những thay đổi lớn đã vào từ 0.99.0 hai ngày trước đó:

## [1.0.0] - 2026-10-01### New Features- **Fullscreen by default** — The TUI now runs fullscreen. Set `tuiMode` to `"regular"` to keep the terminal's normal scrollback. See [Terminal and display](docs/settings.md#terminal-and-display).- **Leaner codemode** — About 40% fewer prompt tokens, and errors that tell the model how to recover. See [Codemode](docs/codemode.md).- **Image generation in codemode** — Scripts call `models.generateImages()` with the session's credentials. See [Generate images](docs/codemode.md#generate-images) and [Use image models](docs/models.md#use-image-models).- **Radius in `/login`** — Sign in with Radius and set up its MCP server in one step. See [Radius](docs/providers.md#radius).- **Anthropic copy code login** — Sign in when the browser runs on another machine. See [Authenticate interactively](docs/providers.md#authenticate-interactively).- **MCP OAuth hardening** — `oauth.authServerMetadataUrl`, RFC 9207 `iss` checks, credentials per server, and step-up sign-in that keeps granted scopes. See [Authenticate with OAuth](docs/mcp.md#authenticate-with-oauth).- **Header-only quiet startup** — `quietStartup: "header"` keeps the version and key hints and hides the rest. See [Terminal and display](docs/settings.md#terminal-and-display).

Bài công bố liệt kê các điểm mới tính gộp cả 0.99: codemode với MCP, mô hình không phải LLM (bộ phân loại Jev) và mô hình sinh ảnh, virtual model, nạp tool trì hoãn, làm ấm cache cho Anthropic, thông điệp hệ thống giữa hội thoại, theme mới và chế độ toàn màn hình. Chương Pi 1.0 đi qua từng tính năng và cơ chế của nó trong code.

Cùng ngày, Pi Durable ra mắt như một package riêng, gắn nhãn thử nghiệm (durable/CHANGELOG.md:185). Bài công bố mô tả rõ vấn đề nó giải quyết: coding agent chạy trên một máy, trong một terminal, do một người điều khiển; nếu tiến trình chết, bạn xem chuyện gì đã xảy ra rồi bảo nó làm tiếp. Earendil muốn một harness chạy được ở bất cứ đâu, với được từ nhiều bề mặt, giữ được số cuộc hội thoại gần như không giới hạn, sống sót qua lỗi bên trong lẫn bên ngoài, và cho nhiều người cùng điều khiển một agent. Thay vì bẻ cong coding agent, họ viết một nền mới, nơi “mọi thứ harness chạy, từ gọi mô hình tới chạy một tool, đều là một task” được ghi lại trước khi hiển thị (earendil.com/posts/pi-durable). Pi Durable không thay thế coding agent; nó dùng chung pi-ai và triết lý, còn trạng thái thì dựa trên Chord. Các chương Chord, Pi Durable và So sánh đi sâu vào phần này.

Văn hoá kỹ thuật bạn sẽ thấy trong code#

File AGENTS.md ở gốc repo là quy tắc chung cho cả người lẫn agent đóng góp vào Pi. Vài quy tắc giải thích những đặc điểm bạn sẽ gặp khi đọc code:

• Cách giải thích thiết kế: vấn đề, ví dụ cụ thể hoặc một vết chạy ngắn, rồi mới tới giải pháp và lý do nó cần thiết (AGENTS.md:10–11). Tài liệu này cũng cố gắng giải thích theo đúng khuôn đó.
• Chỉ dùng cú pháp TypeScript “xoá được”: không enum, không namespace, không parameter property, để Node chạy thẳng mã nguồn bằng chế độ bỏ kiểu (type stripping) mà không cần biên dịch (AGENTS.md:24). Vì vậy bạn sẽ thấy các class khai báo field tường minh rồi gán trong constructor.
• Nhiều agent cùng làm việc trong một thư mục: quy tắc git giả định nhiều phiên pi chạy song song trên cùng working tree, nên cấm git add -A, git stash hay reset --hard (AGENTS.md:54). Pi được phát triển phần lớn bằng chính Pi; thư mục .pi/ của repo chứa prompt template và skill mà maintainer dùng hằng ngày (chương Bản đồ monorepo).
• Issue và PR của người mới bị tự động đóng, maintainer xem lại mỗi ngày và mở lại những cái đạt chất lượng; lý do được ghi thẳng là chống quá tải và chống “slop” do agent sinh ra (CONTRIBUTING.md:79–81).
• Coi thay đổi dependency là code cần review: ghim phiên bản chính xác, chặn bản phát hành npm trong ngày, khoá dependency bắc cầu cho bộ cài chính thức (README.md:168–180).

Tóm tắt#

• Pi là một harness: system prompt, tool, vòng lặp agent và lớp phiên dịch mô hình, được giữ tối giản có chủ đích.
• Dự án đi từ pi-mono cá nhân của Mario Zechner (2025) tới earendil-works/pi sau khi Earendil mua lại (2026-04), rồi 1.0 ngày 2026-10-01.
• Các nguyên tắc cốt lõi: lõi nhỏ, người dùng kiểm soát ngữ cảnh và giữ prefix ổn định cho prompt cache, mở rộng bằng extension mà agent tự viết, session mang đi được, không có hệ thống phân quyền (an toàn đến từ ranh giới hệ điều hành), trung lập mô hình.
• Pi Durable là một nền riêng cho agent chạy lâu, bền trước sự cố, nhiều người cùng lái; nó dùng chung pi-ai và xây trạng thái trên Chord.