# Command reference tiếng Việt
<!-- language: vi; english-index: docs-site/content/en/commands.html -->

> Nếu cần flow đầy đủ theo thứ tự dùng thật, đọc `docs/operator-manual-vietnamese.md`. File này chỉ là bảng tra cứu command.

File này là bảng tra cứu command chính cho Pi Agent Platform. Mục tiêu là khi anh/team mở Herdr, `cd` vào project, chạy `pi`, thì biết rõ lệnh nào dùng cho việc gì.

## Cách đọc command

Từ bản 1.9.0, công việc được yêu cầu bằng **lời thường**: không còn `/workflow`,
`/task`, `/scout`, `/fresh`, `/onboard`, `/commands` hay `/model-options`, và
session không tạo task contract. Slash command còn lại chỉ để xem trạng thái hoặc
đổi thiết lập; không command nào mở lượt model.

Có 4 loại cần phân biệt:

| Loại | Gõ ở đâu | Ví dụ | Ý nghĩa |
|---|---|---|---|
| Yêu cầu thường | Bên trong Pi TUI hoặc WebUI | `Scout luồng thanh toán FE/BE, chỉ đọc, không sửa` | Agent làm việc trực tiếp; guard vẫn áp quyền và xác nhận. |
| Runtime slash command | Bên trong Pi TUI | `/usage` | Extension chạy ngay, hiện kết quả/menu, **không gọi model**. |
| Terminal command | Terminal đã có Bash | `piagent-mcp --preset core` | Cài, kiểm tra, hoặc cấu hình máy/project từ bên ngoài Pi. |
| Pi native/hotkey | Bên trong Pi TUI | `/model`, `Ctrl+L` | Điều khiển native Pi như model/session/MCP. |

Nếu không chắc một slash command có sẵn chưa, mở Pi và gõ `/` để xem danh sách command của session hiện tại. Command có thể khác nhau theo package đã install, provider đã login, và project trust.

## Native Pi vs PiAgent

PiAgent không chiếm các command native đang dùng của Pi. Những command này để Pi xử lý trực tiếp:

| Pi native | Vai trò |
|---|---|
| `/login` | Đăng nhập provider/OAuth. |
| `/model`, `Ctrl+L` | Chọn model/provider. |
| `/name` | Đặt tên session; Piagent nhận rename event để map Agent Watch/report. |
| `/new` | Mở session mới, ví dụ khi session hiện tại đã nặng. |
| `/session` | Xem session id/name/token/cost/context hiện tại. |
| `/resume` | Resume session cũ bằng UI/native flow. |
| `/compact` | Nén context bằng Pi native compaction. |
| `/mcp`, `/mcp-auth` | Kiểm tra/kết nối MCP live và OAuth. |

Command ngắn của PiAgent cho thiết lập và guard local:

| PiAgent runtime | Vai trò |
|---|---|
| `/usage` | Usage live/history/preflight/compact/logs/efficiency. |
| `/context` | Smart index/rebuild/search/pack/impact/efficiency/preflight/compact. |
| `/permission` | Permission mode của session. |
| `/fast` | Xem/bật/tắt OpenAI Codex Fast service tier cho session; không đổi model/thinking và không gọi model khi chạy command. |
| `/profile` | Profile và tech stack. |
| `/memory` | Project memory policy. |
| `/piagent-status` | Profile, guard, runtime và trạng thái model đã xác thực. |
| `/piagent-inspector` | Menu quan sát file diff, command, safety và context của session. |

Riêng MCP governance vẫn giữ `/piagent-mcp` vì `/mcp` đã là command native của Pi.

## Flow hằng ngày ngắn nhất

Lần đầu trên một project:

```bash
cd /path/to/project
pi
```

Trong Pi:

```text
/login
/model
/profile
/context index
/context rebuild
/memory
```

Rồi nhờ agent onboard project bằng lời thường:

```text
Đọc project này (chỉ đọc) và ghi lại project context.
```

Agent đọc project và ghi `.pi/project-context.md` bằng tool onboarding của Piagent.

Các lần sau chỉ cần nói việc cần làm:

```text
Implement <task cụ thể>. Chạy test của project sau khi sửa.
```

Nếu chỉ scout/audit:

```text
Scout mapping payment FE với BE. Chỉ đọc, không sửa source.
```

Nếu task còn mơ hồ, nói rõ là muốn bàn hoặc lập kế hoạch trước:

```text
Chưa sửa gì cả. Hỏi lại những điểm chưa rõ rồi đề xuất kế hoạch cho <goal>.
```

Nếu session đang nặng hoặc Pi báo context overflow, mở session mới bằng `/new`
(hoặc `/compact`) rồi nói lại yêu cầu.

## Nguyên tắc command/UX

Pi Agent dùng ít namespace nhưng mỗi namespace có subcommand/menu rõ:

- Công việc (implement, scout, review, commit, PR) là yêu cầu thường; agent dùng tool bình thường và guard kiểm tra từng tool call.
- `/usage` gom live usage, history/report hint, preflight, compact, logs, efficiency.
- Pi native `/name` đặt tên session theo task; Piagent nhận rename event để Agent Watch/report map đúng việc.
- `/context` gom architecture map, code index, search, context pack, test impact, efficiency, preflight và semantic compact.
- `/permission` gom permission status/read-only/workspace-write/full-access.
- `/profile` là namespace duy nhất cho profile và tech stack.
- `/piagent-inspector` là một namespace quan sát duy nhất; mở menu để tránh sinh thêm command rời.
- Khi user cần chọn, ưu tiên select option. Khi UI select không khả dụng, trả exact command.
- Hành động rủi ro như stage rộng, push, PR write, deploy, publish, thay đổi database hoặc external-provider write vẫn cần xác nhận người vận hành.

## Command chính cho team

Các command này đến từ package `piagent-core`; tất cả chạy ngay và không gọi model.

| Command | Dùng khi nào | Kết quả mong đợi |
|---|---|---|
| `/profile` | Xem/áp profile và chọn tech. | Chạy ngay, không gọi model. |
| `/profile setup` | Chọn profile + tech bằng option. | Ghi profile/lock/tech manifest. |
| `/usage` | Xem live usage hoặc report hint. | Menu live/history/preflight/compact/logs/efficiency. |
| `/task-preflight` | Xem preflight deterministic cho một yêu cầu. | Context và shadow route có schema/version; không gọi model. |
| `/piagent-status` | Xem trạng thái Piagent. | Profile, guard, runtime và model đã xác thực. |
| `/piagent-inspector` | Muốn xem Piagent đang làm gì, sửa file nào, diff bao nhiêu dòng, command nào fail/block và context còn bao nhiêu. | Mở menu `summary/files/commands/security/context/toggle`; read-only, không gọi model. |
| `/piagent-orchestration` | Xem chính sách helper/subagent. | Mode, giới hạn helper, review lens, Field Guide; không gọi model. |
| `/context` | Xem index/search/pack/impact/efficiency/preflight/compact. | Menu context, không gọi model. |
| `/permission` | Xem/đổi quyền runtime. | Menu status/read-only/workspace-write/full-access. |
| `/fast status\|on\|off` | Xem/bật/tắt Fast service tier cho session OpenAI Codex. | Chạy ngay, 0 model token; giữ nguyên model/thinking. Session trống mặc định tắt, environment override hoặc state đã lưu khi resume có thể được ưu tiên. |
| `/memory` hoặc `/memory-policy` | Xem memory policy. | Chạy ngay, không gọi model. |
| `/piagent-mcp` | Xem/quản trị MCP trong Pi. | Menu MCP, không gọi model. |
| `/piagent-update` | Kiểm tra bản Piagent mới ngay (Terminal tự hỏi mỗi giờ, giữa các lượt). | Hỏi "Cập nhật ngay / Để sau"; cập nhật xong nhắc mở lại `pi` hoặc `piagent studio`. Không gọi model. |
| `/bypass [on\|off\|status]` | Chỉ trong `piagent studio`: bật/tắt Bypass cho cuộc trò chuyện công ty (giống công tắc trên dashboard). | Bypass: lệnh cần internet chạy luôn, vẫn hỏi việc bắt buộc (đẩy/gửi ra ngoài, migration, xoá không rõ đích, sudo). Footer hiện "Bypass". Không gọi model. |

`/piagent-inspector` không thêm bước bắt buộc nào. Panel bốn dòng tự hiện sát
phía trên footer native từ lúc mở session và dùng working-tree status (bản ghi
task cũ, nếu có, chỉ còn để xem lịch sử). Gõ command không kèm option để mở menu,
hoặc dùng trực tiếp:

Panel dùng màu theo mức độ: file cyan, test magenta, dòng thêm xanh lá, dòng
xóa đỏ; command pass xanh lá, blocked vàng, failed và safety warning đỏ. Context
dưới 60% là xanh lá, từ 60% là vàng và từ 80% là đỏ. Có thể đặt `NO_COLOR=1`
nếu terminal cần output không màu.

```text
/piagent-inspector summary
/piagent-inspector files
/piagent-inspector commands
/piagent-inspector security
/piagent-inspector context
/piagent-inspector toggle
/piagent-inspector --json summary
```

`files` tách source/test và hiển thị `+/-`. `commands` tách requested/executed/
passed/failed/blocked. `security` chỉ hiện policy block, secret redaction và
integrity warning đã quan sát. `context` dùng exact usage theo turn/session mà Pi
cung cấp; token theo từng built-in tool call luôn ghi unavailable, không ước lượng.

Alias còn giữ:

| Alias | Command chính |
|---|---|
| `/setname <name>` | Pi native `/name <name>` |
| `/context-index` | `/context index` |
| `/permission-status`, `/read-only`, `/workspace-write`, `/full-access` | `/permission ...` |

Các command và alias đã bỏ từ bản 1.9.0: `/workflow`, `/task`, `/scout`,
`/be-to-fe`, `/discuss`, `/plan`, `/review`, `/commit`, `/pr`, `/fresh`,
`/fresh-task`, `/fresh-scout`, `/fresh-be-to-fe`, `/onboard`,
`/onboard-project`, `/commands`, `/piagent-commands`, `/model-options`,
`/profiles`, `/profile-tech`. Gõ chúng bây giờ sẽ được gửi như tin nhắn thường.

Git flow của Pi cố ý không dùng namespace `/git-*`. Cứ nói tự nhiên:

```text
Commit hai file docs vừa sửa với message "docs: update onboarding notes".
Tạo draft PR cho branch này, title "Add guarded git notes".
```

Commit chỉ tạo local commit. `git push` và thao tác ghi lên GitHub (tạo PR,
comment…) luôn hỏi xác nhận trước. Các lệnh stage rộng như `git add .`,
`git add -A`, `git add --all`, `git add -- .`, `git add :/` cũng bị đưa qua
confirmation để tránh gom nhầm file riêng tư hoặc unrelated diff.

## Image/screenshot input

| Tình huống | Cách dùng | Kết quả |
|---|---|---|
| Chat box trả ra local path ảnh | `Xem lỗi UI trong ảnh ~/Documents/team-screenshots/screenshot.png, chỉ đọc` | Platform attach ảnh nếu file ở trong project hoặc folder đã cấp bằng `additionalReadRoots`, rồi rewrite path thành `[image1]`. |
| Nhiều ảnh trong cùng prompt | Dán tối đa 4 path ảnh | Prompt có `[image1]`, `[image2]`, ... |
| Ảnh quá lớn | Dùng Pi `read` tool trên file ảnh hoặc resize ảnh trước | Tránh nhồi ảnh quá lớn vào chat input. |

Định dạng hỗ trợ: `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.bmp`. Giới hạn
mặc định: 4 ảnh/input, 8 MB/ảnh. Protected path, symlink đi khỏi readable root,
file ngoài capability read scope và file chỉ giả đuôi ảnh đều bị từ chối trước
khi bytes được attach.

Profile name nên biết:

| Profile | Dùng khi nào |
|---|---|
| `generic` | Repo chưa rõ cấu trúc. |
| `web-frontend` | Chỉ FE. |
| `backend-api` | Chỉ BE/API. |
| `be-readonly-fe` | BE đọc-only, FE là nơi sửa. |
| `fullstack` | FE và BE đều có thể sửa nếu task cho phép. |
| `node-typescript` | Tooling/lib Node TypeScript. |
| `python` | Python app/lib. |
| `data` | ETL, dbt, data pipeline, notebook. |
| `devops` | Docker, Terraform, K8s, CI/CD. |
| `mobile` | React Native/Flutter. |
| `docs` | Docs/manual/portal. |

Tech stack option theo profile:

| Profile | Role bắt buộc chọn | Ví dụ |
|---|---|---|
| `web-frontend` | Frontend + database optional | `frontend=nextjs database=none` |
| `backend-api` | Backend + database optional | `backend=nestjs database=prisma` |
| `fullstack` | Frontend + backend + database optional | `frontend=nextjs backend=nestjs database=prisma` |
| `be-readonly-fe` | Frontend + backend + database optional | `frontend=react-vite backend=fastapi database=postgres` |
| `mobile` | Mobile | `mobile=react-native` |
| `devops` | DevOps | `devops=docker` |
| `data` | Data + database optional | `data=dbt database=postgres` |
| `docs` | Docs | `docs=mintlify` |

Sau khi chọn tech, platform tạo `.pi/tech-stack.json` và các file `.pi/tech-context/<tech>.json`. Khi agent onboard project (nhờ trong chat), tool onboarding đưa các pointer này vào `.pi/context-index.json`. File context chỉ nên chứa tóm tắt ngắn/citation từ Context7, không lưu nguyên văn docs dài, token, session, hoặc secret.

## Đọc tài liệu ngoài project

Tài liệu tải về `~/Downloads` rồi kéo vào CLI thường không đọc được, vì mặc định agent chỉ làm việc trong project. Tool `piagent_document_read` mở đúng một khe: đọc **tài liệu**, **chỉ đọc**, trong các folder đã cấp trước.

| Thành phần | Giá trị |
|---|---|
| Tool | `piagent_document_read` |
| Input | `path` — absolute, `~/...`, hoặc relative theo project |
| Định dạng | `.md`, `.markdown`, `.txt`, `.text`, `.csv`, `.tsv`, `.json`, `.yaml`, `.yml`, `.pdf`, `.docx` |
| Giới hạn | 12 MB/file; 400.000 ký tự sau khi trích, dài hơn thì cắt và báo `truncated` |
| Cấp quyền | `additionalReadRoots` trong `.pi/piagent-profile.json`, hoặc biến môi trường `PIAGENT_ADDITIONAL_READ_ROOTS` |

Cấp folder cố định trong profile:

```json
{
  "additionalReadRoots": ["~/Downloads", "~/Documents/specs"]
}
```

Cấp tạm cho một session, ngăn cách bằng `:` giống `PATH`:

```bash
PIAGENT_ADDITIONAL_READ_ROOTS="$HOME/Downloads:$HOME/Documents/specs" pi
```

Sau đó nói thẳng path là được: `Đọc ~/Downloads/spec-v2.docx rồi tóm tắt yêu cầu`.

Bốn ràng buộc không đổi khi cấp thêm root:

- **Chỉ đọc.** Root được cấp không mở quyền ghi, xoá, hay chạy lệnh trong đó.
- **Chỉ tài liệu.** File nằm trong root được cấp nhưng sai đuôi — `.pem`, `.sh`, `.env` — vẫn bị từ chối.
- **`protectedPaths` luôn thắng.** Root được cấp không mở được path mà project đang bảo vệ.
- **Nội dung là dữ liệu, không phải lệnh.** Text trả về đã qua redaction và có header nói rõ đây là dữ liệu người dùng; câu lệnh viết trong tài liệu không được thi hành.

Cả hai kiểm tra — nằm trong root và đúng đuôi — đều chạy trên path đã canonical hoá. Nên symlink trong root mà trỏ ra ngoài bị chặn, và symlink tên `notes.md` trỏ vào `id_rsa` cũng bị chặn.

`.docx` đọc trực tiếp, không cần cài gì; text bị xoá bởi tracked change chưa accept sẽ không lẫn vào nội dung. `.pdf` cần `pdftotext` (macOS `brew install poppler`, Debian/Ubuntu `apt install poppler-utils`); thiếu binary thì tool báo thiếu chứ không trả tài liệu rỗng.

## Command native của Pi

Các command này thuộc Pi core hoặc package Pi chính. Tên/availability có thể phụ thuộc version Pi.

| Command/hotkey | Dịch nghĩa | Dùng khi nào | Ghi chú |
|---|---|---|---|
| `/login` | Đăng nhập provider | Lần đầu dùng model OpenAI Codex hoặc model Anthropic Claude. | OAuth/session lưu local trong Pi, không commit repo. |
| `/model` | Chọn model | Muốn chọn OpenAI provider bằng native selector. | Đây là flow chính, không phải hỏi agent tự chọn thay. |
| `Ctrl+L` | Mở model selector | Đổi model nhanh. | Tương đương UI selector của Pi. |
| `/scoped-models` | Chỉnh danh sách model cycle | Muốn `Ctrl+P` chỉ xoay quanh vài model hay dùng. | Global setup seed sẵn provider model families. |
| `Ctrl+P` | Cycle model | Đổi model trong scope nhanh. | Dùng sau khi đã setup `enabledModels`. |
| `Shift+Ctrl+P` | Cycle model ngược | Quay lại model trước trong scope. | Tiện khi test provider. |
| `Shift+Tab` | Đổi thinking level | Chọn effort như `medium`, `high`, `xhigh`, `max` nếu model hỗ trợ. | Model không hỗ trợ level nào thì Pi có thể clamp. |
| `/name <name>` | Đặt tên session | Đối chiếu task trong Agent Watch/report và tìm lại khi resume. | Piagent theo dõi sự kiện rename; `/setname` là alias tương thích. |
| `/session` | Xem session hiện tại | Cần session id/name/token/cost/context. | Dùng sau `pi --name` hoặc `/name` để kiểm tra tên. |
| `/resume` | Resume session | Khi tắt nhầm Pi hoặc muốn nối lại work cũ. | Dựa vào session list/id/name của Pi. |
| `/compact` | Nén context | Khi context usage cao trước task dài. | Chỉ dùng khi cần; đọc lại context quan trọng sau compact. |
| `/mcp` | Xem MCP | Kiểm tra server/tool MCP trong Pi. | Cần `pi-mcp-adapter` hoặc MCP config tương ứng. |
| `/mcp setup` | Setup/refresh MCP | Khi MCP chưa nhận config. | Tùy adapter/version. |
| `/mcp tools` | List MCP tools | Muốn biết server expose tool nào. | Dùng trước khi bảo agent gọi tool ngoài. |
| `/mcp reconnect` | Kết nối lại MCP | Khi server lỗi, token mới, hoặc config đổi. | Không thay thế việc export secret env. |
| `/mcp-auth figma` | OAuth Figma remote MCP | Chỉ dùng khi Piagent đã được duyệt trong Figma MCP Catalog. | Nếu bị từ chối client, dùng `figma-desktop`. |
| `/piagent-mcp` | Menu MCP | Không nhớ subcommand, hoặc muốn xem có việc gì cần làm. | Menu dựng theo project; không có select UI thì in thẳng bảng trạng thái. |
| `/piagent-mcp status` | Danh sách MCP server + state | Muốn biết server nào đang có, ở scope nào, sẵn sàng chưa. | Đọc config, không kiểm tra kết nối live — cái đó là `/mcp`. |
| `/piagent-mcp get <name>` | Chi tiết một server | Trước khi duyệt, hoặc khi không rõ scope nào đang có hiệu lực. | Giá trị credential bị mask; `${VAR}` in nguyên vì là tên biến. |
| `/piagent-mcp doctor` | Server nào chưa chạy được và thiếu gì | Sau khi cài, hoặc khi tool call MCP bị chặn. | Không probe Docker daemon; chạy `piagent-mcp doctor` ở terminal cho việc đó. |
| `/piagent-mcp approve <name>` | Duyệt server repo khai | Khi mở một repo có `.mcp.json`. | In định nghĩa ra trước khi ghi quyết định. Pin theo digest. |
| `/piagent-mcp reject <name>` | Từ chối | Không tin server repo khai. | `reset` để quên quyết định. |
| `/piagent-mcp enable\|disable <name>` | Bật/tắt server | Tắt tạm mà không mất định nghĩa. | Cần `/reload` để adapter nhận thay đổi. |

`/piagent-mcp` chạy thẳng trong session, không qua model. Thêm/xoá server và preset ở terminal: `piagent-mcp add|remove|--preset`.

## Command subagent

Các command này đến từ package `pi-subagents`. Tên hơi “package terminology”, nên bảng dưới dịch ra nghĩa thực tế.

Quan trọng: Piagent mặc định parent-direct và helpers `off`. Các lệnh dưới đây phần lớn là capability upstream để inspect/debug. Piagent config chặn builtin, worker, nested và retry; operator có thể opt-in tối đa hai helper read-only context fresh. Ước tính tiết kiệm token chỉ là telemetry, không còn là điều kiện cho phép (bounded-delegation-v2).

| Command | Dịch nghĩa dễ hiểu | Dùng khi nào | Kết quả mong đợi |
|---|---|---|---|
| `/subagents-doctor` | Health check subagent | Khi mới setup, sau update, hoặc subagent không chạy. | Kiểm tra package, config, agent files, runtime readiness. |
| `/subagents-models` | Bản đồ model của subagent | Khi muốn biết mỗi agent đang inherit model nào hoặc override gì. | Hiện model/thinking/routing đang áp dụng cho subagents. |
| `/subagents` | Catalog/admin agents | Khi muốn xem agent nào có sẵn. | List builtin + piagent agents, có thể inspect metadata. |
| `/subagents-fleet` | Dashboard đội agent đang chạy | Khi có background/parallel subagents. | Hiện active/done runs, id, status, transcript/result nếu hỗ trợ. |
| `/subagent-cost` | Chi phí/token subagents | Khi muốn biết parent + child agents tiêu hao ra sao. | Hiện usage/cost theo runs nếu package/provider expose stats. |
| `/subagents-watchdog` | Giám sát run bị treo | Khi background agents có nguy cơ stuck/timeout. | Theo dõi/nhắc trạng thái tùy package. |
| `/subagents-watchdog recommend-model` | Gợi ý model watchdog | Khi muốn watchdog dùng model mạnh bổ sung với model chính. | Trả gợi ý model/thinking hiện tại. |
| `/subagents-watchdog on` | Bật watchdog | Khi muốn adversarial review ở cuối turn cho session/project. | Watchdog review repo edits ở `agent_end`; có thể tốn thêm token. |
| `/subagents-profiles` | List profiles | Khi team có nhiều provider/quota profile. | Hiện profiles trong `~/.pi/agent/profile/pi-subagents/`. |
| `/subagents-refresh-provider-models <provider>` | Refresh model catalog | Khi model registry/provider thay đổi. | Probe/cache catalog provider. |
| `/subagents-generate-profiles <provider>` | Sinh quota/quality profiles | Khi muốn profile model theo quota/chất lượng. | Tạo profile cho provider. |
| `/subagents-check-profile <name>` | Check profile | Khi profile/model có thể stale. | Re-check model availability/auth. |
| `/run <agent> "<task>"` | Chạy 1 subagent | Khi cần 1 scout/reviewer/planner riêng context. | Child session chạy task rồi trả summary về parent. |
| `/run <agent> "<task>" --bg` | Capability upstream | Piagent không bật async mặc định. | Không dùng trong governed default. |
| `/run <agent> "<task>" --fork` | Capability upstream | Inherit history trái policy context fresh. | Piagent từ chối. |
| `/parallel ...`, `/chain ...`, `/run-chain ...` | Capability upstream | Nhân số turn/context. | Piagent config giới hạn 1 và không dispatch parallel/chain. |
| `/parallel-review`, `/review-loop`, `/parallel-research`, `/parallel-context-build`, `/parallel-handoff-plan` | Capability upstream | Tạo nhiều helper hoặc retry loop. | Piagent config không cho dùng. |
| `/gather-context-and-clarify` | Scout rồi hỏi đúng câu | Khi requirement chưa rõ nhưng cần đọc trước. | Trả clarification questions có evidence. |
| `/parallel-cleanup` | Cleanup review sau implement | Khi muốn rà cleanup đáng làm. | Có thể thêm `autofix`. |

Glossary:

| Từ | Nghĩa trong repo mình |
|---|---|
| `doctor` | Kiểm tra sức khỏe/setup, không sửa logic task. |
| `models` | Cho biết model/thinking từng subagent sẽ dùng. |
| `fleet` | “Đội” child sessions đang chạy hoặc vừa chạy xong. |
| `scout` | Agent đọc/map code read-only. |
| `planner` | Agent lập plan và verify gate, không sửa code. |
| `worker` | Metadata compatibility; bị Piagent disable. |
| `reviewer` | Agent review diff/test/scope. |
| `oracle` | Agent phản biện/risk challenge. |
| `researcher` | Builtin agent nghiên cứu web/docs có nguồn; cần `pi-web-access`. |
| `context-builder` | Builtin agent tạo context/meta-prompt handoff cho task lớn. |
| `chain` | Làm A rồi dùng kết quả A để làm B. |
| `parallel` | Làm nhiều nhánh độc lập cùng lúc. |
| `bg` | Background run, không block parent ngay. |
| `fork` | Capability upstream; Piagent cấm vì helper phải context fresh. |
| `watchdog` | Opt-in adversarial reviewer ở cuối turn; không phải `reviewer` subagent. |
| `worktree` | Checkout riêng cho parallel writers để tránh đè file nhau. |

Piagent subagents:

| Agent | Khi dùng | Write policy |
|---|---|---|
| `piagent-scout` | Map repo/module/spec trước khi sửa. | Read-only. |
| `piagent-planner` | Lập implementation plan. | Read-only. |
| `piagent-worker` | Compatibility metadata; bị Piagent config disable. | Không dispatch. |
| `piagent-reviewer` | Review diff, verify coverage, scope drift. | Review-first. |
| `piagent-oracle` | Challenge architecture/risk. | Read-only. |

## Exact subagent control syntax

Dùng khi muốn chính xác hơn slash command:

```text
subagent({ agent: "piagent-scout", task: "Map the auth flow. Read-only.", context: "fresh" })
```

Status:

```text
subagent({ action: "status" })
subagent({ action: "status", id: "<run-id>", view: "transcript" })
```

Điều khiển run:

```text
subagent({ action: "steer", id: "<run-id>", message: "Focus only on tests." })
subagent({ action: "stop", id: "<run-id>" })
subagent({ action: "resume", id: "<run-id>", message: "Continue after this clarification." })
```

Rule thực tế: dùng slash/natural prompt cho hầu hết task; dùng tool syntax khi cần debug run id hoặc steer/stop chính xác.

Một số option hữu ích:

```text
/run reviewer[model=anthropic/claude-sonnet-5:high] "Review this diff"
/run scout[output=context.md,outputMode=file-only] "Map auth flow"
subagent({ action: "status", view: "fleet" })
subagent({ action: "status", id: "<run-id>", view: "transcript", lines: 120 })
```

`outputMode=file-only` hữu ích khi child tạo report dài: parent chỉ nhận đường dẫn file, không bị nhồi full report vào context.

## Khi nào nên spawn subagent

Trong Piagent, helper chỉ được dispatch khi tất cả điều kiện sau đúng:

- operator đã bật `PIAGENT_HELPERS_MODE=on`;
- tổng số helper của phiên chưa quá 2, và chỉ chạy read-only;
- handoff context fresh, không inherit history, tối đa 2.048 token.

Ước tính tiết kiệm token vẫn được ghi để theo dõi nhưng không quyết định cho phép.

Không nên spawn bừa khi:

- task nhỏ, một file, verify đơn giản;
- nhiều writer cùng sửa chung vùng source;
- requirement chưa rõ;
- cần quyết định product/architecture từ user;
- repo đang dirty mà chưa hiểu thay đổi của ai.

Default của platform là an toàn:

- `maxSubagentDepth: 1`: parent spawn child, child không fan-out tiếp.
- `parallel.concurrency: 1`: compatibility ceiling, không chạy song song.
- `asyncByDefault: false`: không tự chạy background nếu anh không yêu cầu.
- Tối đa 2 read-only helper, 0 worker, 0 retry.

Nếu anh không bật gì thêm, một yêu cầu thường chạy parent-direct và không tạo model turn phụ.

## Prompt mẫu cho bài toán thật

### Platform/package improvement

```text
Improve onboarding, model scope, MCP setup, and verification docs for team usage. Keep everything public, project-agnostic, and verifiable.
```

Khi muốn tách rõ agents:

```text
Use piagent-scout to map current platform docs/scripts read-only.
Use piagent-scout to inspect relevant external source context read-only when the user provides it.
Then use piagent-planner to produce an implementation plan.
Only after plan is clear, use piagent-worker for implementation.
Use piagent-reviewer before final.
```

### BE spec lên FE, không sửa BE

```text
/profile be-readonly-fe
Implement FE support for <endpoint/spec>. Scout backend read-only, map contract, then edit frontend only.
```

Nếu muốn parallel read-only:

```text
Keep the parent direct. If helper mode is enabled, run one fresh read-only piagent-scout for the highest-value independent lane.
```

### Review trước khi ship

```text
Review diff hiện tại: correctness, test còn thiếu, scope drift. Chỉ đọc, không sửa.
```

Hoặc chia reviewer:

```text
/parallel piagent-reviewer "Review correctness and edge cases" -> piagent-reviewer "Review tests and verification gaps" -> piagent-reviewer "Review scope drift and protected paths"
```

## Terminal commands

Các lệnh này chạy ngoài Pi.

| Command | Dùng khi nào |
|---|---|
| `npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.87.1` | Cài Pi CLI tương thích với release hiện tại. |
| `npm install -g --ignore-scripts @piagent/platform@1.27.0` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
| `pi install git:github.com/Vt-mmm/piagent@v1.27.0` | Cài pinned release khi cần reproducible team setup. |
| `pi install git:github.com/Vt-mmm/piagent` | Cài latest package platform cho máy cá nhân/sandbox. |
| `piagent-update --check` | Báo version hiện tại vs version sẽ lên cho cả ba thành phần; không cài gì. |
| `piagent-update` | Full update global một lệnh cho cả máy: Pi host → npm-global helper → Pi package, đúng thứ tự release yêu cầu. |
| `piagent-update --version X.Y.Z` | Update tới đúng một release thay vì latest; dùng cho rollout theo lô hoặc rollback. |
| `piagent-update --project <path>` | Bước phụ sau global update: migrate project cũ nếu có rồi chạy doctor strict-share cho project đó. |
| `piagent-update --npm-prefix ~/.pi/npm-global` | Ép updater cài host/helper vào npm global prefix của user; hữu ích khi `/usr/local/lib/node_modules` không ghi được. |
| `npm exec -y --package @piagent/platform@X.Y.Z -- piagent-update --version X.Y.Z --force` | Bootstrap/update global cho máy chưa có `piagent-update`; chạy từ Terminal, không cần mở Pi. |
| `PIAGENT_NO_UPDATE_CHECK=1` | Tắt notice "có bản mới" ở đầu session Pi. Mặc định bật, hỏi registry nhiều nhất một lần mỗi 24 giờ ở tiến trình nền. |
| Cài exact Pi host của release, rồi `npm install -g --ignore-scripts @piagent/platform@X.Y.Z` và `piagent-install --stable` | Sequence thủ công tương đương. Thứ tự bắt buộc: `piagent-install` fail nếu Pi host lệch bản pin và không tự cài host. Version pin của từng release nằm trong [release/install policy](release-install-policy.md). |
| Cài exact Pi host ghi trong release cũ, rồi helper `vPREVIOUS` và `piagent-install --stable` | Full rollback; đánh giá dependency risk của host cũ trước khi hạ version. |
| `piagent-install --stable --dry-run` | Preview Pi package matching với helper hiện tại; stable resolve tag → commit SHA. |
| `piagent-install --stable` | Cài Pi package matching với helper hiện tại bằng resolved commit SHA. |
| `piagent-install --version vX.Y.Z --resolve-tag` | Chỉ đổi Pi package; npm-global helper giữ nguyên version. |
| `piagent-install --version vX.Y.Z` | Chỉ đổi Pi package theo exact tag literal khi cần giữ behavior cũ. |
| `piagent-install --dev` | Theo moving source cho máy cá nhân/sandbox; không commit vào `.pi/settings.json`. |
| `pi update --extensions` | Refresh package đã cài; với pinned tag/commit, muốn nâng version thì chạy lại install bằng ref mới. |
| `pi list --approve` | Xem package Pi đã install. |
| `piagent-auto` | Mở Pi với project trust `--approve` cho lần chạy hiện tại; guard vẫn bật. |
| `piagent-auto --read-only -p "<task>"` | Auto-run scout/read-only; guard chặn shell/write/unknown tool. |
| `piagent-auto --full-access -p "<task>"` | Trusted automation style; không tắt protected paths/redaction/human gates. |
| `pi` rồi `/permission full-access <task>` | Một lệnh trong Pi để bật full-access cho session và giao task. Alias `/full-access <task>` vẫn chạy. |
| `pi --list-models` | Xem model Pi thấy được theo credentials hiện tại. |
| `piagent-install --with-mcp --with-subagents` | Cài global package + MCP + subagent baseline từ package bin. |
| `piagent-setup <project> --profile auto` | Setup đầy đủ cho một project khi muốn preseed bằng bin. |
| `piagent-init <project> --profile generic` | Init project files tối thiểu. |
| `piagent-models` | Xem catalog model seeded bởi platform. |
| `piagent-route --prompt "<task>" --json` | Tính capability/model/effort trước task từ authenticated catalog; không gọi model và không lưu raw prompt. |
| `piagent-route --prompt-file <file> --execute --yes -- --approve` | Explicit prelaunch adaptive task; giữ hard pin và fail closed nếu preflight/catalog không đủ. |
| `piagent-model-scope --preset full` | Re-apply full provider model scope. |
| `piagent-mcp --preset core --scope global --replace` | Apply the governed MCP core baseline: Context7, Chrome DevTools, GitHub. |
| `piagent-mcp --preset popular --scope global --replace` | Apply the governed MCP popular baseline: core + Playwright + Figma desktop. |
| `piagent-mcp --list` | List MCP presets. |
| `piagent-subagents --preset safe` | Re-apply subagent safe config. |
| `pi install npm:pi-web-access@0.17.0` | Cấp web/search/fetch tools cho builtin `researcher`; platform setup/update cài mặc định từ `v1.2.8`. |
| `piagent-setup <project> --no-web-access` | Setup project nhưng bỏ web access khi máy không được phép browse/fetch external source. |
| `piagent-usage /path/to/project` | Lấy exact usage của session mới nhất từ terminal khác. |
| `piagent-usage --history /path/to/project --days 7` | Tổng usage lịch sử của project, gồm session đã end. |
| `piagent-usage --history --all-projects --days 7 --csv` | Xuất usage tuần toàn máy để đưa vào report. |
| `piagent-doctor /path/to/project --strict-share` | Kiểm tra project có share/open-source được không. |
| `piagent-uninstall` | Báo cáo những gì sẽ được gỡ. Dry run, không đụng gì. |
| `piagent-uninstall --apply` | Gỡ Pi package của platform khỏi Pi settings global. |
| `piagent-uninstall --apply --with-addons --with-host` | Gỡ thêm pi-mcp-adapter, pi-subagents, pi-web-access và Pi host. |
| `piagent-uninstall --apply --project /path/to/project` | Gỡ thêm state của platform trong project: profile, lock, `piagent-state/`. |
| `piagent-benchmark` | Chạy smoke suite `core-v1`: paired Piagent/controlled `codex-cli` bằng Luna/medium, 24 session, hidden grader + scope + workflow + exact usage. |
| `piagent-benchmark --dry-run` | Validate suite và xem số model session, không gọi model. |
| `npm run benchmark:deep -- --dry-run` | Validate `deep-logic-v1`: 7 family difficulty large × 3 repeat × Piagent/`codex-cli` = 42 session, khóa Luna/medium và chưa dùng quota. |
| `npm run benchmark:deep` | Chạy paired deep-logic benchmark Luna/medium cho event/state, scheduler, policy, context graph, stream recovery, transactional config và temporal usage billing chính xác. |
| `piagent-benchmark --production --dry-run` | Xem ma trận production 18 family x 3 variant x 2 surface = 108 session, chưa dùng quota. |
| `piagent-benchmark --production --preflight-only` | Trước lượt trả phí, tự chạy/cache bốn lane provider-free cùng exact source/tree/config/runner binding; lần đầu có long-horizon tối thiểu 30 phút, 0 provider call/model token. Digest S0 loại private vault/stage-window identity nên lượt paid và mọi resume dùng lại đúng receipt khi semantic không đổi. |
| `npm run benchmark:production-v2 -- --dry-run` | Validate ma trận 108 session Luna/medium Fast-vs-Fast; khóa Fast execution configuration bằng Piagent outbound telemetry và Codex identity-bound effective thread settings, upper-95 family `<=0.60` và pooled all-attempt net ratio `<=0.65`, chưa dùng model token. |
| `piagent-benchmark --production --surfaces piagent,codex-cli --model openai-codex/gpt-5.6-luna --thinking medium --piagent-treatment candidate` | Chạy production release gate đa domain/profile/lifecycle với controlled Codex; S12/S36/S72 chặn pooled fresh ratio >1.10, observed family >1.25 hoặc subagent vượt 1 attempt/5% traffic; S108 dùng upper-95 <=0.60. |
| `piagent-benchmark --piagent-treatment release-defaults\|local-safe\|candidate\|feature-off ...` | Pin treatment Piagent; chỉ surface `piagent` nhận feature env, manifest/resume/replay/report giữ nguyên treatment. |
| `piagent-benchmark --codex-mode native ...` | Đo UX Codex theo cấu hình operator; protocol gate fail closed nên report không được claim tiết kiệm token. |
| `piagent-benchmark --production --seed <value> ...` | Tái lập đúng generated variant của một production report riêng tư. |
| `piagent-benchmark --production --scenarios <id,id> --repeats 1 ...` | Chẩn đoán family/rubric đã chọn; không đủ điều kiện nhận production verdict. |
| `piagent-benchmark --production --infrastructure-retries 2 ...` | Diagnostic recovery run; retry chỉ áp lỗi process chết trước usage, được report đầy đủ và làm production claim fail. |
| `piagent-benchmark --production --retry-delay 60 ...` | Đặt backoff trước infrastructure retry; production mặc định 60 giây. |
| `bash scripts/verify-local.sh` | Verify repo platform trước khi commit/tag. |
| `bash scripts/verify-local.sh --offline` | Verify trong CI/máy sạch, bỏ qua local Pi model catalog. |
| `bash scripts/setup.sh <project> ...` | Preseed setup project; không bắt buộc cho daily flow. |
| `bash scripts/quality-benchmark.sh ...` | Legacy: ghi tay benchmark cho scenario project-specific. |

Trong output `piagent-install`, `currentRelease` là version của terminal helper đang chạy, không phải lời xác nhận rằng npm-global helper vừa được update. Checklist đầy đủ nằm tại [release/install policy](release-install-policy.md).

Khi đang develop chính repo `piagent`, có thể dùng npm scripts tương ứng:

| Command | Tương đương |
|---|---|
| `npm run verify` | `bash scripts/verify-local.sh` |
| `npm run setup -- <project>` | `bash scripts/setup.sh <project>` |
| `npm run install-global` | `bash scripts/install-global.sh` |
| `npm run init-project -- <project>` | `bash scripts/init-project.sh <project>` |
| `npm run doctor -- <project> --strict-share` | `bash scripts/team-doctor.sh <project> --strict-share` |
| `npm run benchmark -- ...` | `node scripts/benchmark-runner.mjs ...` |
| `npm run benchmark:webui-parity` | Gate provider-free cho 10 workflow, 32 Project Controls, contract/security, bảy deterministic UI-stability suite, Chromium flow và ba cỡ performance stress. |
| `npm run usage -- <project>` | `bash scripts/pi-session-stats.sh <project>` |
| `npm run usage -- --history <project> --days 7` | `bash scripts/pi-session-stats.sh --history <project> --days 7` |
| `npm run models` | `bash scripts/pi-model-catalog.sh` |
| `npm run model-scope -- --preset full` | `bash scripts/configure-model-scope.sh --preset full` |
| `npm run mcp -- --preset core --scope global --replace` | `node scripts/mcp-manage.mjs --preset core --scope global --replace` |
| `npm run subagents -- --preset safe` | `bash scripts/configure-subagents.sh --preset safe` |

## MCP command quick map

| Muốn làm gì | Gõ |
|---|---|
| Kiểm tra MCP trong Pi | `/mcp` |
| Xem tool MCP | `/mcp tools` |
| Reconnect sau khi đổi config/env | `/mcp reconnect` |
| Apply global Context7/Chrome/GitHub baseline | `piagent-mcp --preset core --scope global --replace` |
| Apply Figma/Playwright baseline | `piagent-mcp --preset popular --scope global --replace` |
| Xem preset | `piagent-mcp --list` |

Secret phải để trong env, không commit:

```bash
export CONTEXT7_API_KEY=ctx7sk_...
export GITHUB_PERSONAL_ACCESS_TOKEN=<github-token>
```

## Token/context command quick map

| Câu hỏi | Lệnh |
|---|---|
| Session này đang dùng model gì? | `/session` hoặc `/usage` |
| Đặt/đổi tên session đang mở? | `/name <task/session name>` |
| Tắt nhầm, mở lại session gần nhất? | `pi --continue` |
| Chọn lại session cũ theo tên/id? | `pi --resume` hoặc `pi --session <id-or-file>` |
| Context window đang còn bao nhiêu? | `/usage` |
| Output test/build dài bị nén thì xem ở đâu? | `/logs` |
| Exact token/cost từ terminal khác? | `piagent-usage /path/to/project` |
| Tổng token/cost các session cũ? | `piagent-usage --history /path/to/project --days 7` |
| CSV report cuối tuần toàn máy? | `piagent-usage --history --all-projects --days 7 --csv` |
| Subagents tốn bao nhiêu? | `/subagent-cost` |
| Có nên compact chưa? | Xem `contextUsage.percent`; trên 75% mới cân nhắc `/compact`. |

Không claim tiết kiệm token/cost nếu chưa có paired evidence cùng scenario. Dùng
`piagent-benchmark`; smoke suite chỉ cho phép verdict khi quality/reliability đạt
ít nhất `9/10`, safety/workflow đạt tuyệt đối, quality không giảm và có ít nhất
ba cặp cùng model với exact usage. Production gate giữ safety `10`, yêu cầu
quality/reliability/workflow và mọi category ít nhất `9.5`, đồng thời bắt từng
task cùng mọi category/profile/lifecycle/difficulty band lớn hơn `9.5`, đủ 18
paired family và cận trên 95% của token ratio không vượt baseline. Report vẫn
liệt kê từng workflow check bị hụt để ngưỡng tổng không che mất hành vi cần xem
lại.

## Source rule cho subagent/custom agent

Mental model chuẩn:

1. Parent Pi là coordinator: giữ requirement, quyết định, final output.
2. Subagent là child session: có context riêng, có thể dùng model/tool riêng hoặc inherit parent.
3. Child trả summary/result về parent; parent không nên bị nhồi toàn bộ log trung gian.
4. Dùng read-only subagents trước: scout, docs research, review, test-gap analysis.
5. Writer song song chỉ dùng khi có worktree isolation và write set không overlap.
6. Agent custom tốt phải có role hẹp, tool surface rõ, output contract rõ.

Đây là lý do platform mình có `piagent-scout`, `piagent-planner`, `piagent-worker`, `piagent-reviewer`, `piagent-oracle` thay vì một agent tổng quát làm tất cả.

## Tài liệu chính

- Pi usage docs: https://pi.dev/docs/latest/usage
- Pi packages: https://pi.dev/packages
- pi-subagents package: https://pi.dev/packages/pi-subagents