Ngày đầu với Pi: từ cài đặt đến một task thật trong repo của bạn

# Ngày đầu với Pi: từ cài đặt đến một task thật trong repo của bạn Nguồn: https://modernengineer.dev/vi/library/pi-first-day-setup-to-real-task > **Tóm tắt nhanh:** Ngày đầu với Pi, coding agent mã nguồn mở chạy trong terminal do Earendil Works phát triển, gồm năm bước: cài Pi, mở Pi trong repo và quyết định project trust, chạy `/login` rồi chọn model, giao một việc nhỏ, hôm sau mở lại phiên bằng `pi --continue`. Pi không hỏi trước mỗi tool call, nên hãy làm trên repo có git sạch, hoặc chạy cả Pi trong container nếu repo không phải của bạn. [Phần 1](https://modernengineer.dev/vi/library/pi-coding-agent-is-it-for-you) giúp bạn quyết định có dùng Pi hay không. Bài này đi cùng bạn từ lúc quyết định dùng thử: mở terminal và làm từng bước cho tới khi Pi xong một việc thật trong repo của bạn. *Viết cho Pi 1.3.0, dựa trên quickstart, tài liệu, mã nguồn và CHANGELOG chính thức. Các lệnh cài trong bài cài bản mới nhất, không ghim 1.3.0, nên nếu bản bạn cài mới hơn, hãy đối chiếu với CHANGELOG.* Vài lựa chọn lúc cài đặt trông nhỏ nhưng quan trọng. Pi chạy mọi tool call với toàn bộ quyền của tài khoản đang mở nó. Vì vậy, nơi bạn chạy Pi và những file project bạn chọn tin sẽ quyết định một chỉ dẫn sai có thể gây hại tới đâu. Vì vậy mình tách ngày đầu thành từng bước, mỗi bước kèm một dấu hiệu để bạn tự kiểm trước khi đi tiếp. ## Cần chuẩn bị gì trước khi cài Pi? Để làm theo bài này, bạn cần ba thứ: một terminal, một cách truy cập model và một repo có git. Pi chạy được trong thư mục thường, nhưng git giúp bạn thấy và hoàn tác thay đổi. - **Terminal:** macOS, Linux hoặc Windows đều được. Pi cần Node.js 22.19 trở lên; installer chính thức trên macOS, Linux và Windows có thể cài Node.js giúp bạn nếu máy chưa có ([README](https://github.com/earendil-works/pi/blob/v1.3.0/README.md)). Trên Windows, cài thêm Git for Windows để Pi có Git Bash cho tool `bash` và lệnh `!`, hoặc chạy Pi trong WSL ([Windows](https://github.com/earendil-works/pi/blob/v1.3.0/packages/coding-agent/docs/windows.md)). - **Truy cập model:** một subscription có sẵn (Claude Pro hoặc Max, ChatGPT, GitHub Copilot, theo [pi-ai README](https://github.com/earendil-works/pi/blob/v1.3.0/packages/ai/README.md)), một API (Application Programming Interface) key của provider, hoặc model chạy trên máy qua llama.cpp ([Models](https://github.com/earendil-works/pi/blob/v1.3.0/packages/coding-agent/docs/models.md)). - **Một repo có git, working tree sạch:** quickstart của Pi khuyên dùng version control hoặc backup cho việc quan trọng. Chạy `git status` trước, để sau task bạn thấy rõ Pi đã đổi gì bằng `git diff`. ## Năm bước từ cài đặt tới task đầu tiên là gì? Năm bước đi theo thứ tự bạn sẽ gặp trong ngày đầu: cài, mở Pi trong repo, đăng nhập, giao việc, rồi quay lại hôm sau. Mỗi bước kết thúc bằng một dấu hiệu đúng; đừng bỏ qua nó, vì lỗi ở bước trước thường chỉ lộ ra ở bước sau.  *Mỗi bước trong ngày đầu có một lệnh và một dấu hiệu để tự kiểm; chưa thấy dấu hiệu thì dừng lại sửa trước khi đi tiếp.* ### Bước 1: Cài Pi bằng cách nào? Cách nhanh nhất là installer chính thức. Installer ghim mọi phụ thuộc và sau này cập nhật được bằng `pi update`. ```bash curl -fsSL https://pi.dev/install.sh | sh ``` Trên Windows, chạy trong PowerShell, theo [README](https://github.com/earendil-works/pi/blob/v1.3.0/README.md): ```powershell powershell -c "irm https://pi.dev/install.ps1 | iex" ``` Hai cách khác, theo [quickstart](https://github.com/earendil-works/pi/blob/v1.3.0/packages/coding-agent/docs/quickstart.md): - **Qua npm:** `npm install -g --ignore-scripts @earendil-works/pi-coding-agent`. Cách này cần Node.js 22.19 trở lên và không ghim phụ thuộc gián tiếp (transitive dependency) như installer. - **Qua Nix trên macOS hoặc Linux:** `nix profile add github:earendil-works/pi/stable`. Nix build Pi từ mã nguồn. Nix bản cũ dùng `nix profile install` thay cho `nix profile add`. Muốn ghim một bản cụ thể thì thay `stable` bằng một tag, ví dụ `v1.3.0`. > **Dấu hiệu đúng:** chạy `pi --version` in ra số phiên bản. > **Lỗi hay gặp ở bước này:** > > - Cài qua npm mà Node.js cũ hơn 22.19: nâng Node.js hoặc chuyển sang installer. - Cài qua Nix rồi chạy `pi update`: lệnh này không cập nhật được bản Nix. Dùng `nix profile upgrade pi`. ### Bước 2: Mở Pi trong repo và chọn project trust thế nào? Nếu repo không phải của bạn, đọc phần [chạy Pi trong container](https://modernengineer.dev/vi/library/pi-first-day-setup-to-real-task#khi-nao-nen-chay-pi-trong-container) trước khi làm bước này. Với repo của bạn, chuyển vào thư mục repo rồi chạy `pi`. Pi dùng thư mục này để tìm file, đọc hướng dẫn, nạp cấu hình và nhóm các session đã lưu. ```bash cd ~/code/my-repo pi ``` Với cấu hình mặc định, Pi hỏi bạn có tin thư mục này không trước khi nạp cấu hình hay tài nguyên riêng của project. Đó là các file như `.pi/settings.json`, `.pi/mcp.json`, `.pi/extensions`, `.pi/skills`, hoặc skill trong `.agents/skills`, ở thư mục hiện tại hay một thư mục cha. Pi không hỏi lại nếu bạn đã lưu quyết định cho thư mục đó hoặc một thư mục cha. Đây là project trust ([Security](https://github.com/earendil-works/pi/blob/v1.3.0/packages/coding-agent/docs/security.md)). Nếu thư mục `.pi` trống, Pi sẽ không hỏi gì. | Repo | Chọn | Pi làm gì | | --- | --- | --- | | Của bạn hoặc của nhóm, bạn biết ai viết file trong `.pi` và `.agents/skills` | Tin | Nạp extension, skill, MCP (Model Context Protocol) server và cấu hình của project. | | Vừa clone từ người lạ | Không tin | Vẫn chạy nhưng bỏ qua extension, skill, MCP server và cấu hình của project. | Ngoại lệ duy nhất là `sessionDir` trong `.pi/settings.json` của repo, cài đặt chọn thư mục lưu file phiên. Pi cần biết lưu phiên ở đâu ngay lúc khởi động, trước khi hỏi bạn về trust, nên vẫn dùng cài đặt này dù bạn chọn không tin. Vì vậy repo lạ vẫn quyết định được nơi Pi ghi file phiên. Nếu không có những thứ trên thì Pi không hỏi. Khi hỏi, Pi cho chọn lưu quyết định cho thư mục, hoặc chỉ áp dụng cho phiên này (các lựa chọn có chữ "this session only") ([trust-manager.ts](https://github.com/earendil-works/pi/blob/v1.3.0/packages/coding-agent/src/core/trust-manager.ts)). Quyết định đã lưu nằm trong `~/.pi/agent/trust.json`; muốn đổi thì gõ `/trust`, quyết định mới áp dụng cho các lần mở Pi sau. Có hai điều project trust không làm mà người mới dễ hiểu nhầm. Thứ nhất, nó không chặn tool call: khi Pi đã chạy, tool vẫn có toàn quyền của tài khoản đang mở Pi. Thứ hai, file hướng dẫn như `AGENTS.md` hay `CLAUDE.md` vẫn được nạp dù bạn không tin thư mục, nên nội dung trong đó vẫn có thể lái model. > **Dấu hiệu đúng:** giao diện hiện ra với vùng hội thoại, ô nhập ở dưới và footer ghi thư mục hiện tại, model, mức dùng context. Header lúc khởi động liệt kê các file hướng dẫn và tài nguyên Pi đã nạp. > **Lỗi hay gặp ở bước này:** trên Windows chạy trực tiếp, Pi không tìm thấy Bash nên tool `bash` và lệnh `!` lỗi. Cài Git for Windows rồi mở lại Pi. ### Bước 3: Đăng nhập và chọn model ra sao? Trong Pi, gõ: ```text /login ``` Chọn provider rồi làm theo hướng dẫn: đăng nhập bằng subscription qua trình duyệt, hoặc dán API key. Pi lưu thông tin này trong `~/.pi/agent/auth.json`, nên đừng commit hay chia sẻ file đó. Sau đó gõ `/model` để chọn model. Trong danh sách, bấm `Ctrl+S` để lưu model đó làm mặc định cho các phiên sau. `/thinking` chọn mức suy luận. Pi chỉ cho chọn những mức model hiện tại hỗ trợ. > **Dấu hiệu đúng:** footer hiện đúng model bạn vừa chọn. > **Lỗi hay gặp ở bước này:** > > - **Danh sách model trống hoặc thiếu:** `/model` chỉ hiện model của những provider đã xác thực hợp lệ, dù xác thực đó đến từ `/login`, biến môi trường hay `models.json` ([Models](https://github.com/earendil-works/pi/blob/v1.3.0/packages/coding-agent/docs/models.md)). Kiểm tra lại cách bạn xác thực provider đó, hoặc chạy lại `/login`. Một số provider còn lọc model theo quyền của key, ví dụ với endpoint OpenRouter mặc định, Pi chỉ liệt kê những chat model mà key đó được dùng ([Providers](https://github.com/earendil-works/pi/blob/v1.3.0/packages/coding-agent/docs/providers.md)); trường hợp này đăng nhập lại không giúp gì. - **Đăng nhập trên máy không có trình duyệt, ví dụ qua SSH:** callback OAuth có thể không về được Pi. Khi Pi hỏi, dán URL chuyển hướng cuối cùng hoặc mã xác thực vào ([Providers](https://github.com/earendil-works/pi/blob/v1.3.0/packages/coding-agent/docs/providers.md)). - **Dùng subscription Anthropic:** Pi có cảnh báo `warnings.anthropicExtraUsage`, bật mặc định, báo khi lượt dùng có thể tính vào phần usage trả thêm ([Settings](https://github.com/earendil-works/pi/blob/v1.3.0/packages/coding-agent/docs/settings.md)). Đừng tắt nó khi chưa hiểu gói của mình tính tiền thế nào. ### Bước 4: Giao việc đầu tiên thế nào cho an toàn? Việc đầu tiên nên là việc chỉ đọc, để bạn quen cách Pi làm việc mà chưa có gì bị sửa. Quickstart của Pi gợi ý một câu như sau: ```text Explain how this repository is structured and how to run its checks. ``` Pi hiện từng lần đọc file, tìm kiếm, chạy lệnh và sửa file trong lúc làm. Bấm `Ctrl+O` để mở hoặc thu gọn đầu ra của tool. Khi câu trả lời hợp lý, giao một thay đổi nhỏ có thể kiểm được, ví dụ sửa một lỗi chính tả trong README hoặc thêm một test cho một hàm đơn giản. Vài thao tác dùng nhiều trong lúc Pi làm ([Usage](https://github.com/earendil-works/pi/blob/v1.3.0/packages/coding-agent/docs/usage.md)): | Bạn muốn | Thao tác | | --- | --- | | Đưa một file vào prompt | Gõ `@` rồi tìm tên file | | Chạy lệnh và gửi output cho model | `!git status` | | Chạy lệnh mà không gửi output cho model | `!!git status` | | Chỉnh hướng task đang chạy | Gõ tin nhắn rồi `Enter` | | Xếp thêm việc sau task hiện tại | Gõ tin nhắn rồi `Alt+Enter` (Windows và WSL: `Ctrl+Q`) | | Dừng task | `Escape` | Khi Pi đang chạy, tin nhắn gửi bằng `Enter` đợi lượt trả lời hiện tại và các tool call của lượt đó xong, rồi mới điều chỉnh hướng cho lượt kế tiếp. Tin nhắn xếp việc (`Alt+Enter` hoặc `Ctrl+Q`) thì đợi tới khi cả task xong. > **Dấu hiệu đúng:** `git status --short` chỉ liệt kê những file bạn dự kiến thay đổi. `git diff` cho thấy đúng thay đổi bạn yêu cầu. Nếu Pi thêm test, tự chạy test đó một lần, vì đọc diff không chứng minh test chạy được. Mở từng file mới (đánh dấu `??`), vì `git diff` không hiện file chưa được track. Nếu thấy gì lạ, chạy `git restore <file>` để bỏ thay đổi ở file đã track, tự xóa file mới không mong muốn, rồi viết lại yêu cầu rõ hơn. > **Lỗi hay gặp ở bước này:** Windows Terminal dành `Alt+Enter` cho chế độ toàn màn hình, nên trên Windows và WSL Pi dùng `Ctrl+Q` để xếp việc. Trên macOS, WezTerm và Alacritty cần cấu hình để chuyển tổ hợp phím này cho Pi. Tài liệu [Terminal Setup](https://github.com/earendil-works/pi/blob/v1.3.0/packages/coding-agent/docs/terminal-setup.md) có cách cấu hình cho từng terminal. ### Bước 5: Hôm sau mở lại phiên bằng lệnh nào? Dùng `pi --continue` trong đúng thư mục repo. Pi tự lưu session, bạn không cần làm gì khi thoát. ```bash cd ~/code/my-repo pi --continue ``` Ba lệnh giúp bạn không lạc giữa nhiều phiên ([Sessions](https://github.com/earendil-works/pi/blob/v1.3.0/packages/coding-agent/docs/sessions.md)): - **Đặt tên:** `/name` đặt tên cho phiên hiện tại, để sau này tìm lại. - **Đổi phiên:** `/resume` mở danh sách phiên để chọn phiên khác. - **Xem phiên:** `/session` cho xem file phiên, số tin nhắn, lượng token đã dùng và chi phí. > **Dấu hiệu đúng:** sau `pi --continue`, hội thoại hôm qua hiện lại. Pi khôi phục model cùng mức thinking của phiên. Nếu model cũ không còn dùng được, ví dụ vì mất xác thực, Pi báo không khôi phục được và chuyển sang một model thay thế còn dùng được. Nếu không còn model nào, Pi báo không có model. Mức thinking cũng được giới hạn lại theo model thực tế ([sdk.ts](https://github.com/earendil-works/pi/blob/v1.3.0/packages/coding-agent/src/core/sdk.ts)). > **Lỗi hay gặp ở bước này:** `pi --continue` mở phiên gần nhất của thư mục bạn đang đứng. Chạy ở thư mục khác thì bạn nhận phiên của thư mục đó, không phải phiên bạn cần. Nếu thư mục chưa có phiên nào, Pi mở phiên mới. Luôn `cd` vào đúng repo trước. ## Khi nào nên chạy Pi trong container? Khi repo không phải của bạn, khi để Pi tự chạy không ai giám sát, hoặc khi máy có credential quan trọng. Pi không có hệ thống quyền dựng sẵn, và tài liệu Security nói rõ project trust hay việc xem lại thay đổi đều không phải ranh giới an toàn. Ranh giới thật là giới hạn file, credential và mạng mà Pi chạm được. Với repo của bạn, git sạch và bạn theo dõi màn hình trong lúc Pi làm, sẵn sàng bấm `Escape` để dừng khi thấy lệnh lạ, thì chạy Pi trực tiếp là chấp nhận được. Cách đơn giản nhất là Docker ([Containerization](https://github.com/earendil-works/pi/blob/v1.3.0/packages/coding-agent/docs/containerization.md)). Tạo `Dockerfile.pi`: ```dockerfile FROM node:24-bookworm-slim RUN apt-get update \ && apt-get install -y --no-install-recommends bash ca-certificates git ripgrep \ && rm -rf /var/lib/apt/lists/* RUN npm install -g --ignore-scripts @earendil-works/pi-coding-agent WORKDIR /workspace ENTRYPOINT ["pi"] ``` Build rồi chạy từ thư mục repo (cú pháp bash): ```bash docker build -t pi-sandbox -f Dockerfile.pi . docker run --rm -it \ -e ANTHROPIC_API_KEY \ -v "$PWD:/workspace" \ -v pi-agent-my-repo:/root/.pi/agent \ pi-sandbox ``` - **Credential:** thay `ANTHROPIC_API_KEY` bằng biến của provider bạn dùng, và biến đó phải có giá trị trong shell. Dùng subscription thì bỏ dòng `-e` và chạy `/login` trong container. Đừng mount `~/.pi/agent` của máy thật vào container. - **Mở lại phiên:** thêm `--continue` sau `pi-sandbox`. Đặt tên volume riêng cho mỗi repo, vì repo nào cũng nằm ở `/workspace` nên dùng chung volume dễ mở nhầm phiên. - **Container không cô lập hoàn toàn:** repo được mount có quyền ghi, Pi sửa được cả `.git` (ví dụ chèn hook chạy ở lần commit sau), và container vẫn ra được mạng nên có thể gửi API key ra ngoài. Việc chỉ cần đọc thì mount `:ro`, và chỉ đưa vào container credential mà task cần. > **Dấu hiệu đúng:** trong Pi, chạy `!pwd` ra `/workspace`. ## Đọc gì tiếp khi phiên bắt đầu dài ra? Sau ngày đầu, bạn đã có Pi chạy trong repo, một model mặc định, một task làm xong và cách mở lại phiên. Nguyên tắc quan trọng nhất cần nhớ: giới hạn của Pi đến từ môi trường bạn dựng, không đến từ prompt hay hướng dẫn, nên git sạch và container là hai thói quen nên giữ từ đầu. Khi bạn làm việc lâu hơn trong một phiên, sẽ tới lúc agent quên quyết định đã chốt hoặc context đầy. Phần 3 của series (sắp ra) sẽ giải thích session, nhánh và compaction trong Pi, kèm bảng triệu chứng và cách xử lý. Từ phần 3 trở đi, các bài Inside Pi dành cho Subscriber.

curl -fsSL https://pi.dev/install.sh | sh

powershell -c "irm https://pi.dev/install.ps1 | iex"

cd ~/code/my-repo
pi

/login

Explain how this repository is structured and how to run its checks.

cd ~/code/my-repo
pi --continue

FROM node:24-bookworm-slim

RUN apt-get update \
  && apt-get install -y --no-install-recommends bash ca-certificates git ripgrep \
  && rm -rf /var/lib/apt/lists/*
RUN npm install -g --ignore-scripts @earendil-works/pi-coding-agent

WORKDIR /workspace
ENTRYPOINT ["pi"]

docker build -t pi-sandbox -f Dockerfile.pi .
docker run --rm -it \
  -e ANTHROPIC_API_KEY \
  -v "$PWD:/workspace" \
  -v pi-agent-my-repo:/root/.pi/agent \
  pi-sandbox

Đọc bài "Ngày đầu với Pi: từ cài đặt đến một task thật trong repo của bạn" trên modernEngineer rồi áp dụng vào repo này.
1. Gọi tool content_get của MCP server modernengineer với locale "vi", slug "pi-first-day-setup-to-real-task". Nếu chưa nối MCP hoặc bị từ chối quyền, đọc thẳng trang https://modernengineer.dev/vi/library/pi-first-day-setup-to-real-task.
2. Tóm tắt các bước chính của bài, chỉ ra bước nào áp dụng được cho repo này.
3. Đề xuất thay đổi cụ thể và hỏi tôi trước khi sửa file.

claude mcp add --transport http modernengineer \
  https://api.modernengineer.dev/mcp \
  --header "Authorization: Bearer <API key>"