Bộ công cụ pi agent: năm package, công thức SDK, bảng phán quyết và checklist thứ Hai

TL;DR

• pi là một monorepo giấy phép MIT, đóng gói một coding agent harness thành năm package riêng: lớp API model, vòng lặp agent, thư viện terminal UI, bản coding agent hoàn chỉnh và một package telemetry. Bạn có thể lấy một mảnh hoặc cả năm.
• CLI là một coding agent đầy đủ ngay từ ngày đầu: bốn tool mặc định, lịch sử session dạng cây có fork và resume, bộ đếm chi phí trực tiếp, và nó đọc luôn AGENTS.md hoặc CLAUDE.md đang có trong repo của bạn.
• Giá trị thật nằm ở phía SDK: createAgentSession cùng một model runtime và một session manager cho ra một agent chạy được chỉ với khoảng mười dòng TypeScript, còn defineTool thêm một tool tùy biến có kiểu mà không cần process hay giao thức riêng.
• Cái giá của sự minh bạch đó là công sức: không có hộp thoại xin quyền tích hợp sẵn, việc cô lập môi trường do bạn lo, phiên bản còn trước 1.0 (v0.84) và khoảng một trăm issue đang mở.
• Cứ giữ harness bạn dùng hằng ngày, và dùng pi làm bàn thử để thấy những gì harness đó giấu đi. Chỉ xây sản phẩm trên pi nếu bạn chấp nhận tự lo phần guardrail.

Các nguồn nói gì

pi là một monorepo: một repository chứa năm package được xuất bản riêng, mỗi package phụ trách một tầng của harness s2. pi-ai là API thống nhất tới các nhà cung cấp model (OpenAI, Anthropic, Google và nhiều bên khác sau cùng một giao diện), lo việc streaming phản hồi, các khối reasoning cùng mức thinking và việc tự khám phá các model mà mỗi nhà cung cấp đang có s2. pi-agent-core là chính vòng lặp agent: trạng thái hội thoại và chu trình gửi một message, đọc các tool call, thực thi rồi đưa kết quả ngược lại s2. pi-tui là thư viện render terminal với differential rendering, nên chỉ vẽ lại phần đã thay đổi trên màn hình s2. pi-coding-agent ghép các mảnh đó thành CLI bạn cài, còn pi-telemetry cho phép bạn tự gắn số liệu sử dụng mà không phụ thuộc vào nhà cung cấp nào s3.

Các con số về mức độ sử dụng củng cố cho thiết kế này: 92 123 sao, 11 400 fork và hơn 5 700 commit, tất cả dưới giấy phép MIT, cho phép sử dụng, chỉnh sửa và phân phối lại, kể cả bên trong sản phẩm thương mại s1. Nhịp phát hành giữ vững suốt mùa hè: ba bản phát hành trong hai tuần đầu tháng Tám, với v0.84.2 ra ngày 14 s4.

Cài đặt chỉ một lệnh, npm install -g --ignore-scripts @earendil-works/pi-coding-agent, và cờ ignore-scripts có ý nghĩa: nó chặn các dependency chạy install script của chúng, một trong những bề mặt tấn công được dùng nhiều nhất trên npm s3. Sau khi kết nối với nhà cung cấp bằng lệnh login, thanh dưới cùng hiện thư mục hiện tại, session, số token đã dùng và chi phí theo thời gian thực, nên mỗi request được tính giá ngay khi gửi đi thay vì cuối tháng mới biết s3.

Session là tính năng đặc trưng. Mỗi cuộc hội thoại được lưu dạng JSONL trong thư mục home của bạn, sắp theo project, và lịch sử là một cái cây chứ không phải một đường thẳng: fork quay về bất kỳ điểm nào và rẽ nhánh, tree di chuyển giữa các nhánh, và resume mở lại bất kỳ session cũ nào, kể cả vài tuần sau, vì mọi thứ đều lưu cục bộ s3. Model chỉ nhận bốn tool theo mặc định: read, write, edit và bash, rất ít so với các agent trên thị trường, và là cố ý như vậy s3. Cấu hình theo cùng logic: một settings.json toàn cục trong home, một settings.json theo project ghi đè lên nó, và một cơ chế trust sẽ hỏi trước khi áp dụng settings cục bộ của một thư mục bạn mở lần đầu. CLI cũng nạp AGENTS.md hoặc CLAUDE.md của project làm ngữ cảnh, nên các chỉ dẫn sẵn có dùng được mà không cần viết lại s3.

Về phía SDK, createAgentSession nhận một ModelRuntime và một SessionManager rồi trả về một agent chạy được. SessionManager là lựa chọn về lưu trữ: trong bộ nhớ cho script dùng một lần, trên đĩa để tìm lại các cuộc hội thoại qua nhiều lần chạy, và các session do SDK tạo có cùng cấu trúc với session của chính CLI s8. Danh sách option của createAgentSession còn cho phép chọn chính xác bộ tool được mở ra, thậm chí cả system prompt thông qua một ResourceLoader khi bạn muốn bắt đầu từ trang trắng s8. Tool tùy biến đi qua defineTool: một tên, một mô tả, một schema tham số có kiểu và một hàm execute, truyền vào createAgentSession qua customTools. Với model, tool xuất hiện y hệt read hay bash, schema có kiểu cho bạn autocomplete trong editor và agent nhận đầu vào đã được kiểm tra hợp lệ. Cơ chế này giống một MCP server, chỉ khác là mọi thứ nằm trong file của bạn, không có process riêng hay giao thức ở giữa s8.

Bản thân CLI được tùy biến qua bốn cơ chế, đều đặt trong các thư mục của project hoặc của home: extension (các module TypeScript đăng ký tool, slash command, phím tắt hoặc phần tử UI, nạp lúc khởi động từ thư mục extensions), skill (các gói năng lực theo chuẩn Agent Skills, do model gọi hoặc tự gọi bằng tay, nên skill sẵn có dùng lại nguyên trạng), prompt template, và theme được nạp lại khi CLI đang chạy s3. README nêu triết lý trong một dòng: điều chỉnh pi theo workflow của bạn thay vì ngược lại, không cần fork hay đụng vào phần lõi s3. Trong khi các harness lớn gộp sub-agent, plan mode và permission vào sản phẩm, pi cố ý bỏ chúng ra, để bạn tự viết thành extension hoặc cài từ cộng đồng s3.

Các giới hạn do chính dự án ghi lại. Không có hộp thoại xin quyền tích hợp sẵn: theo mặc định agent có thể chạy một lệnh bash mà không hỏi. Hướng dẫn containerization chính thức thừa nhận điều này và đề xuất ba mẫu cô lập, trong đó có Docker, nhưng việc dựng một cái trước khi thả agent vào máy quan trọng là việc của bạn s5. Độ trưởng thành là cái giá còn lại: v0.84 chứ chưa phải 1.0, khoảng một trăm issue đang mở, và các API vẫn đánh dấu experimental như remote session client được thêm trong những tuần trước đó s7. Chính những mảnh này đã phục vụ một sản phẩm khác: pi-chat dùng chúng cho tự động hóa hội thoại s6.

Phán quyết: giữ, thử hay bỏ qua

Việc cần làm vào thứ Hai

• Cài CLI bằng npm install -g --ignore-scripts @earendil-works/pi-coding-agent, chạy pi, kết nối một provider bằng lệnh login, và theo dõi thanh chi phí trong một tác vụ thật.
• Mở một repo đã có AGENTS.md hoặc CLAUDE.md và kiểm tra pi có nhận nó không; so sánh những câu trả lời đầu tiên của agent với harness quen dùng của bạn trên cùng một prompt.
• Chạy một cuộc hội thoại, rồi fork từ một node trước đó và đi theo hướng khác; liệt kê ~/.pi/agent/sessions/ để xem các file JSONL và thư mục project của chúng.
• Viết một file our-agent.ts hai mươi dòng: import createAgentSession, truyền vào một ModelRuntime và một SessionManager trong bộ nhớ, hỏi nó thư mục hiện tại chứa gì, chạy bằng npx tsx.
• Thêm một defineTool đọc dữ liệu từ hệ thống của bạn (API nội bộ, một database view, một file CSV) và truyền vào customTools; xác nhận agent tự gọi nó khi gặp câu hỏi liên quan.
• Trước mọi lần chạy có bật bash trên máy quan trọng, chọn một trong ba mẫu cô lập trong hướng dẫn containerization và dựng nó lên.
• Phác thảo extension đầu tiên chặn các lệnh bash và hỏi xác nhận với lệnh có tính phá hủy; để nó trong thư mục extensions của project, dưới version control.
• Lướt qua danh sách open issues một lần để biết phần nào còn thay đổi trước khi bạn xây lên trên.

Đọc thêm

• Đọc tài liệu SDK để xem đầy đủ danh sách option của createAgentSession: bộ tool, system prompt qua ResourceLoader, các session manager s8.
• Nghiên cứu ba mẫu cô lập trong hướng dẫn containerization trước khi phát hành bất cứ thứ gì chạy bash trên máy của người dùng s5.
• Xem pi-chat để thấy cùng năm package được sắp xếp lại cho tự động hóa hội thoại thay vì lập trình s6.
• Duyệt thư mục packages và đọc riêng pi-agent-core: đó là phiên bản dễ đọc nhất, nhỏ nhất của vòng lặp mà mọi harness đóng gói sẵn đều chạy s2.
• Theo dõi trang releases: v0.84.0 đến v0.84.2 ra trong vòng hai tuần của tháng Tám, nên hãy chờ các ghi chú thay đổi ảnh hưởng đến extension s4.
• Dùng danh sách open issues như bản đồ những phần còn experimental, bắt đầu từ remote session client s7.
• Dùng lại các skill bạn đã viết cho công cụ khác: thư mục skills của pi theo chuẩn Agent Skills s3.

Nguồn

• pi: the agent toolkit (repository), Earendil Works. Lý do nên đọc: README với danh sách package, số sao, số fork và giấy phép MIT.
• pi monorepo packages, Earendil Works. Lý do nên đọc: năm package đặt cạnh nhau, cách nhanh nhất để thấy mỗi tầng do package nào phụ trách.
• pi-coding-agent package README, Earendil Works. Lý do nên đọc: lệnh cài đặt, tool mặc định, session và bốn cơ chế mở rộng.
• pi releases, Earendil Works. Lý do nên đọc: nhịp phát hành và changelog của dòng v0.84.
• pi containerization guide (isolation patterns), Earendil Works. Lý do nên đọc: ba mẫu cô lập cần áp dụng trước khi bật bash ở bất kỳ nơi nào quan trọng.
• pi-chat: the same bricks applied to conversation automation, Earendil Works. Lý do nên đọc: sản phẩm thứ hai xây từ cùng các package, hữu ích để đánh giá mức độ tái sử dụng của chúng.
• pi open issues, Earendil Works. Lý do nên đọc: danh sách trực tiếp những gì chưa ổn định hoặc còn experimental trong phiên bản hiện tại.
• pi-coding-agent SDK documentation (createAgentSession options), Earendil Works. Lý do nên đọc: tên option chính xác của createAgentSession, defineTool và các session manager.

FAQ

Hôm nay pi có thay được coding agent hằng ngày của tôi không?

Chưa thể thay thẳng. Nó không có hộp thoại xin quyền, việc cô lập do bạn lo, và phiên bản còn trước 1.0 với khoảng một trăm issue đang mở. Hãy giữ harness hiện tại cho công việc và chạy pi bên cạnh.

Tôi có cần MCP để thêm tool tùy biến cho pi không?

Không. 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, rồi tool được truyền vào createAgentSession qua customTools. Nó hoạt động như một tool tích hợp sẵn, không cần process hay giao thức riêng.

AGENTS.md, CLAUDE.md và các skill sẵn có của tôi có dùng được không?

Có. CLI tự nạp AGENTS.md hoặc CLAUDE.md trong project của bạn, và thư mục skills của nó theo chuẩn Agent Skills, nên skill sẵn có nạp nguyên trạng.

Tại sao chỉ có bốn tool mặc định?

read, write, edit và bash là toàn bộ bộ mặc định, ít hơn nhiều so với các agent trên thị trường, và dự án coi đó là một lựa chọn. Mọi thứ khác được thêm có chủ đích qua customTools hoặc một extension.