Chương 22Phần 6: Tổng hợp
Thuật ngữ và nguồn tham khảo
Thuật ngữ dùng thống nhất trong tài liệu, nơi định nghĩa trong code, và nguồn tham khảo.
Trong chương này4 mục
Bảng dưới gom các thuật ngữ dùng trong tài liệu, cách gọi tiếng Việt được dùng thống nhất, nghĩa ngắn gọn, và nơi chúng được định nghĩa trong code. Khi gặp một từ lạ ở bất kỳ chương nào, hãy quay lại đây rồi bấm vào định nghĩa.
Mô hình và vòng lặp#
| Thuật ngữ | Trong tài liệu | Nghĩa | Định nghĩa |
|---|---|---|---|
| harness | harness | Phần mềm bao quanh mô hình: system prompt, tool, vòng lặp, lớp phiên dịch. | Lịch sử và triết lý |
| API, provider | API (giao thức), provider (nhà cung cấp) | API là giao thức dây (Anthropic Messages, OpenAI Responses…); provider là bên cung cấp (anthropic, openai, openrouter…). Một provider có thể dùng API của provider khác. Bản đồ đầy đủ ở chương Provider. | Model |
| context | ngữ cảnh (của một request) | System prompt, danh sách tin nhắn và tool gửi cho mô hình trong một lần gọi. | Context |
| message | tin nhắn | Một trong bốn vai: system, user, assistant, toolResult. | Message |
| tool call | lời gọi tool | Khối nội dung trong tin nhắn assistant: tên tool, id, đối số. | ToolCall |
| usage | usage | Số token vào/ra, đọc/ghi cache và chi phí của một phản hồi. | Usage |
| stop reason | lý do dừng | stop, length, toolUse, error, aborted, deferred… | StopReason |
| assistant message event | sự kiện stream | Các sự kiện bắt đầu, delta văn bản, delta suy nghĩ, delta tool call, kết thúc, lỗi. | AssistantMessageEvent |
| thinking level | mức suy nghĩ | Mức lý luận yêu cầu mô hình dùng, ánh xạ sang tham số riêng của từng provider. | ThinkingLevel |
| agent loop | vòng lặp agent | Gọi mô hình, chạy các tool nó gọi, lặp lại tới khi nó không gọi tool nữa. | runLoop |
| turn, run | lượt, lần chạy | Lượt: một phản hồi của mô hình cùng các tool call của nó. Lần chạy: các lượt từ một input tới câu trả lời cuối. | AgentEvent |
| agent message | tin nhắn agent | Tin nhắn của LLM cộng các loại tin nhắn tuỳ biến mà ứng dụng khai báo thêm. | AgentMessage |
| steering, follow-up | tin nhắn steer, follow-up | Steer chen vào sau lượt đang chạy; follow-up chờ agent làm xong rồi mới vào. | Agent |
Coding agent#
| Thuật ngữ | Trong tài liệu | Nghĩa | Định nghĩa |
|---|---|---|---|
| AgentSession | AgentSession | Bộ điều phối của coding agent: nối Agent, session, cài đặt, mô hình, extension, tool. | AgentSession |
| session, entry | session, entry | File JSONL của một hội thoại; mỗi dòng sau header là một entry có id và parentId. | SessionEntry |
| branch, leaf | nhánh, lá | Lá là entry hiện tại; nhánh hoạt động là đường từ gốc tới lá. Rẽ nhánh là dời lá về một entry cũ. | branch() |
| compaction | compaction (nén ngữ cảnh) | Thay phần lịch sử cũ bằng một bản tóm tắt; bản gốc vẫn nằm trong file. | CompactionEntry |
| branch summary | tóm tắt nhánh | Bản tóm tắt của nhánh vừa rời đi, gắn vào chỗ rẽ nhánh mới. | BranchSummaryEntry |
| context edit | chỉnh sửa ngữ cảnh | Entry chỉ-nối-thêm thay hoặc bỏ phần đóng góp vào ngữ cảnh của một entry cũ. | ContextEditEntry |
| extension | extension | Module TypeScript chạy trong tiến trình Pi, đăng ký tool, lệnh, sự kiện, giao diện. | ExtensionAPI |
| skill | skill | Thư mục chỉ dẫn (SKILL.md) chỉ được nạp toàn văn khi cần; system prompt chỉ liệt kê tên và mô tả. | Skill |
| prompt template | prompt template | File Markdown được mở rộng thành tin nhắn khi gõ /tên. | PromptTemplate |
| project trust | project trust | Quyết định có nạp cài đặt và tài nguyên của thư mục dự án hay không; không phải sandbox. | security.md |
| component | component (TUI) | Đơn vị giao diện terminal: nhận độ rộng, trả về các dòng văn bản. | Component |
| codemode | codemode | Tool cho mô hình viết JavaScript chạy trong sandbox QuickJS để gọi các tool khác. | chương Codemode |
| tool exposure | mức hiển thị tool | Tool được khai báo thẳng cho mô hình, chỉ cho codemode, trì hoãn tới khi tìm, hay ẩn. | chương Codemode |
Chord và Pi Durable#
| Thuật ngữ | Trong tài liệu | Nghĩa | Định nghĩa |
|---|---|---|---|
| Context (Chord) | Context của Chord | Đối tượng mang tín hiệu huỷ và span telemetry, truyền qua mọi lời gọi bất đồng bộ của Durable. Khác với “context” của pi-ai. | Context, BACKGROUND_CONTEXT |
| Harness | Harness | Một storage đang mở cùng bộ máy chạy agent trên nó. | Harness |
| conversation | hội thoại (conversation) | Một transcript; có thể là fork của hội thoại khác hoặc do một task sở hữu. | ConversationRecord |
| entry (Durable) | entry | Bản ghi bất biến của transcript, tách model (cho mô hình) và data (cho ứng dụng). | EntryRecord |
| head marker | head marker | Entry có trường head (reset, compaction) chọn điểm bắt đầu của ngữ cảnh hoạt động. | ContextBounds |
| submission | submission | Một input hoặc một lần ghi entry được đưa vào hội thoại; có trạng thái queued, placed, done, unanswered. | SubmissionRecord |
| task, checkpoint | task, checkpoint | Máy trạng thái bền; mỗi bước lưu checkpoint để chạy tiếp sau khi khởi động lại. | TaskState, defineTask |
| document | document | State JSON có kiểu, lưu cạnh transcript và thay đổi trong cùng commit. | DocumentRecord, defineDoc |
| extension (Durable) | extension | Gói có tên gồm tool, section của system prompt, hook, wrapper và task. | defineExtension |
| replay | phát lại (replay) | Chạy lại một tool sau sự cố; chỉ với tool khai báo replay: "safe". | chương Durable: task |
| execution environment | môi trường thực thi | Nơi tool đọc ghi file và chạy tiến trình: máy cục bộ, máy từ xa qua pi-env, sandbox. | ExecutionEnv |
Nguồn tham khảo#
Mã nguồn và tài liệu chính thức#
- github.com/earendil-works/pi: monorepo, MIT. Tài liệu này dùng tag
v1.4.0. - pi.dev và pi.dev/docs/latest: trang chủ và tài liệu người dùng (bản xuất bản của
packages/coding-agent/docs). - rfc.earendil.com: các RFC công khai về Pi (telemetry, bộ cài khoá dependency, cờ thử nghiệm, cấu hình mô hình động…).
- Tài liệu trong repo đáng đọc trọn: how-pi-works.md, session-format.md, compaction.md, extensions.md, durable/README.md, durable/docs/spec.md (đặc tả chuẩn của Pi Durable), chord/docs/guide.md.
Blog#
- Mario Zechner, What I learned building an opinionated and minimal coding agent (2025-11-30).
- Armin Ronacher, Pi: The Minimal Agent Within OpenClaw (2026-01-31).
- Earendil, Announcing Pi & Lefos (2026-04-08).
- Earendil, Prompt Caching In Agents (2026-07-22).
- Earendil, The Session You Cannot Take With You (2026-07-30).
- Earendil, Pi, Minimal and Performant (2026-08-04).
- Earendil, How Compaction Works in Pi (2026-08-13).
- Earendil, What is a Harness? (2026-08-20).
- Earendil, There are many agent harnesses, but this one is mine. (2026-09-01).
- Earendil, You Said No MCP! (2026-09-29).
- Earendil, Pi 1.0 và Pi Durable (2026-10-01).
- Earendil, There are many themes, but this one is yours (2026-10-09).
- Earendil, Pi Durable on Cloudflare (2026-10-16), kèm repo mẫu earendil-works/pi-durable-cloudflare.
Dữ liệu và hệ sinh thái#
- Các phiên làm việc thật của Mario khi phát triển Pi được công bố tại huggingface.co/datasets/badlogicgames/pi-mono (README.md:182). Đây là nguồn rất tốt để xem session JSONL thật trông thế nào.
- Trên npm đã có các package bên thứ ba xây trên Pi Durable, ví dụ backend PostgreSQL, môi trường thực thi trên Fly.io Sprites, host trên Cloudflare Durable Object hay subagent bền. Chúng là mã của cộng đồng, không thuộc repo và không được kiểm chứng trong tài liệu này.