Cách dùng tài liệu này

Đây là tài liệu học về Pi, một coding agent chạy trong terminal, cùng các thư viện bên dưới nó: Pi 1.0, Pi Durable và Chord. Mục tiêu không phải hướng dẫn sử dụng, mà là giúp bạn hiểu Pi từ bên trong: nó hoạt động thế nào, được triển khai ra sao, vì sao được thiết kế như vậy, và dữ liệu của nó có hình dạng gì. Mỗi khẳng định kỹ thuật đều trỏ tới code thật, kèm đường dẫn file và số dòng, để bạn mở đúng chỗ đó và tự kiểm chứng.

Bạn sẽ đọc thoải mái nhất nếu đã quen TypeScript (kiểu, async/await, generic) và biết sơ qua cách gọi API của mô hình ngôn ngữ: tin nhắn theo vai trò, gọi tool (tool calling), và stream. Những khái niệm khác được định nghĩa khi xuất hiện lần đầu.

Nguồn sự thật: một bản clone ghim cố định#

Toàn bộ code trong tài liệu được trích tự động từ bản clone của github.com/earendil-works/pi tại tag v1.4.0 (commit 4a080252f, phát hành 2026-10-21), bản phát hành mới nhất lúc viết tài liệu. Pi đổi rất nhanh (từ 1.0 lên 1.4 chỉ trong ba tuần), nên số dòng chỉ đúng với đúng commit này. Bản clone nằm ở thư mục pi/ cạnh tài liệu; nếu cần tạo lại:

git clone https://github.com/earendil-works/pi.git
cd pi
git checkout v1.4.0     # detached HEAD tại 4a080252f; mọi số dòng trong tài liệu khớp với trạng thái này

Thứ tự tin cậy khi các nguồn mâu thuẫn: code ở v1.4.0, rồi tới tài liệu trong repo (README và thư mục docs/ của từng package; trang pi.dev/docs là bản xuất bản của packages/coding-agent/docs), cuối cùng là blog của Earendil và các tác giả. Ý kiến hay số liệu lấy từ blog luôn được ghi rõ nguồn.

Cách đọc một khối code#

Mỗi khối code là một đoạn file thật, được build script đọc thẳng từ bản clone theo số dòng và kiểm tra rằng nó chứa đúng thứ được mô tả. Ví dụ, đây là toàn bộ file điểm vào của pi-agent-core:

export * from "./agent.ts";export * from "./agent-loop.ts";export * from "./proxy.ts";export { setDefaultStreamFn } from "./stream-fn.ts";export * from "./types.ts";

• Đường dẫn như pi/packages/agent/src/index.ts là vị trí trong bản clone. Bấm vào nó để mở đúng các dòng đó trên GitHub, tại đúng commit được ghim, nên liên kết không bao giờ trỏ lệch dù repo đã đổi.
• Số dòng bên trái là số dòng thật trong file. Dòng được tô nền (như dòng 2 ở trên) là dòng văn bản đang nói tới.
• Chép vị trí chép chuỗi dạng pi/packages/agent/src/index.ts:1; dán vào editor để mở đúng chỗ, chẳng hạn code -g pi/packages/agent/src/agent-loop.ts:172 với VS Code hoặc vim +172 pi/packages/agent/src/agent-loop.ts. Chép code chép phần code, không kèm số dòng.
• Dòng “⋯ lược bớt dòng a–b” nghĩa là đoạn giữa bị bỏ qua để giữ phần đầu và phần cuối của một hàm dài. Khối dài hơn 40 dòng được thu gọn, bấm Hiện đủ để xem hết.
• Thụt lề chung của đoạn trích được cắt bớt để dễ đọc; trong file gốc, code dùng tab.

Trong văn bản, những tham chiếu nhỏ màu xanh dạng packages/agent/src/agent-loop.ts:172 cũng là liên kết tới đúng dòng trên GitHub; rê chuột để thấy đường dẫn trong bản clone.

Quy ước trong văn bản#

• Khối chữ đơn cách không có đường dẫn file và được ghi “Ví dụ minh hoạ” là ví dụ viết tay (một dòng JSONL mẫu, một chuỗi sự kiện) để minh hoạ; nó khớp với kiểu dữ liệu thật nhưng không phải code của Pi. Chỉ những khối có đường dẫn pi/… mới là code trích từ repo.
• Thuật ngữ tiếng Anh chuẩn được giữ nguyên và giải nghĩa ở lần đầu: vòng lặp agent (agent loop), lượt (turn), lời gọi tool (tool call), cửa sổ ngữ cảnh (context window), compaction (nén ngữ cảnh)… Chương cuối gom tất cả thành bảng thuật ngữ.
• Tên định danh trong code luôn đặt trong khung code và giữ nguyên chữ hoa chữ thường.

Ba lộ trình đọc#

Tài liệu được sắp từ nền lên ngọn, khớp với đồ thị phụ thuộc giữa các package (chương Bản đồ monorepo). Bạn có thể đọc tuần tự, hoặc chọn một lộ trình:

Chương So sánh và lộ trình học ở cuối có thêm các bài tập lần theo code, để bạn kiểm tra mình đã hiểu tới đâu.