# Pi Agent Platform [English](README.md) Pi Agent Platform cung cấp chat trực tiếp, công cụ có kiểm soát quyền, ngữ cảnh dự án và khung main/research/review cho tài khoản công ty. Tài liệu public: [piagent.io.vn](https://piagent.io.vn) ## Cài đặt Yêu cầu Node.js `>=22.19.0`. Chạy từ project cần sử dụng: ```bash npm install -g @piagent/platform piagent-setup ``` Sau khi setup: ```bash cd /path/to/project pi ``` Nhập yêu cầu bằng lời thường trong Pi hoặc WebUI. Từ bản 1.9.0 không còn bước `/task` hay `/workflow`, không còn task contract và không còn ngưỡng tiết kiệm token. ## Agent Watch Auto trên macOS Admin cấu hình model cho main, khảo sát và review trong Studio. Thành viên nhập URL/key ở Watch, chọn Piagent rồi Import. Mở **Piagent công ty** từ Watch hoặc chạy `piagent studio`; thêm `--web` để mở dashboard. Người dùng chọn mức suy luận; context theo model thực tế. Phiên cá nhân tiếp tục dùng `pi` và chọn model/OAuth riêng. Key công ty cần loại **Piagent công ty**. Key CLI trực tiếp cũ giữ nguyên; Studio có nút tạo key đi kèm dùng chung hạn mức. Không đổi tài khoản công ty sang cá nhân trong cùng hội thoại. Main có tối đa hai trợ lý chỉ đọc; không sinh nhánh con tiếp. Review gắn với bản chụp patch và báo hết hiệu lực khi code đổi. UI hiển thị token từng trợ lý. Bản macOS managed dùng công cụ cách ly và quyền ngắn hạn theo lượt; chế độ cá nhân vẫn là thực thi trên host. Bản local này chưa phải bản phát hành có Developer ID. [Trạng thái nghiệm thu](docs/managed-local-acceptance.md) phân biệt test nội bộ, gọi provider thật và phần còn thiếu. ## Windows Trên Windows, Piagent chạy trong WSL2 (Ubuntu): chế độ công ty với sandbox bubblewrap và Agent Watch cho Windows, và cả chế độ cá nhân. Một lệnh PowerShell cài tất cả. Chạy thẳng trên Windows mới là bản xem trước cho chế độ cá nhân. Cài đặt từng bước: [Windows](docs/vi/windows.md). ## Web search và vision Web research và đọc ảnh là hai capability tách biệt. Tích hợp `pi-web-access` được pin sẽ ưu tiên route `openai-codex` khi Pi đã xác thực và giữ fallback search tự động; credential không được đưa vào project hoặc browser state. Ảnh được gửi dưới dạng native image input cho model của session, không qua OCR service riêng do Piagent vận hành. Dashboard hiển thị đúng route tại **Cài đặt → Nhà cung cấp & model**: `Codex Web Search` khi route đó sẵn sàng, và `Codex Vision` chỉ khi model Codex hiện tại công bố hỗ trợ image input. ## Workspace tài liệu trên WebUI Session Hub cho phép đính kèm ảnh hoặc tài liệu do người dùng chọn vào cuộc trò chuyện mới hay session đang mở. File Markdown, text, PDF và DOCX được trích xuất cục bộ với giới hạn rõ ràng; chat chỉ giữ card file gọn, còn workspace **Tài liệu** hiển thị preview dễ đọc mà không tạo model turn. File vượt giới hạn gửi trực tiếp vẫn nằm trong workspace của project thay vì bị nhét vào prompt. Runtime tiếp tục áp protected path, redaction, session binding và attachment ref dùng một lần. Màn hình New chat gửi đúng nội dung người dùng nhập; WebUI không còn bộ chọn workflow. Trong **Cài đặt → Điều khiển project**, operator có thể xem runtime/usage, profile, Context Engine, memory và MCP governance mà không cần nhớ slash command. WebUI gửi đúng command vào Pi runtime; thao tác read-only được kiểm tra là 0 model token, còn thao tác ghi hoặc semantic compact bắt buộc xác nhận rõ ràng. Muốn onboard project, hãy nhờ agent trong chat đọc project (chỉ đọc) và ghi lại context. ## Command chính Công việc được yêu cầu bằng lời thường; các command dưới đây là thiết lập và màn hình chỉ đọc, không command nào mở lượt model. | Command | Mục đích | |---|---| | `/profile` | Xem hoặc đổi project profile; `/profile setup` chọn tech cho từng vai trò | | `/permission` | Đổi permission mode trong session | | `/context` | Xem Context Engine, index, retrieval và telemetry | | `/usage` | Xem session, model, thinking và context usage | | `/piagent-inspector` | Mở menu read-only để xem task diff, command fail/block, safety warning và context budget; panel bốn dòng tự hiện sát footer native, `toggle` để ẩn trong session | | Pi native `/name` | Đặt tên session; Piagent nhận rename event để map Agent Watch/report | | `/memory` | Xem hoặc cập nhật explicit project memory | | `/piagent-mcp` | Xem và quản lý MCP server, scope và phê duyệt | | `/piagent-status` | Xem profile, guard, runtime và trạng thái model đã xác thực | Các command workflow (`/workflow`, `/task`, `/scout`, `/fresh`, `/onboard`, `/commands`, `/model-options`) đã bỏ từ bản 1.9.0. Hãy nói điều mình cần, ví dụ "scout luồng thanh toán, chỉ đọc, không sửa", "review diff hiện tại", "commit hai file này". Session đã nặng thì mở session mới bằng `/new` của Pi. `git push`, thao tác ghi lên GitHub và publish đều hỏi xác nhận trước. ## Architecture Code được quản lý theo các layer: 1. Composition root đăng ký Pi extension. 2. Runtime adapter xử lý Pi hook, command, tool và session UI. 3. Core service xử lý policy, context và state (bản ghi task cũ chỉ còn để đọc lịch sử). 4. Integration quản lý MCP, capability và security primitive. 5. CLI trong `scripts/` chỉ parse argument và gọi use case. Chạy gate kiến trúc: ```bash npm run architecture:check ``` Đọc chi tiết: - [Architecture tiếng Việt](docs/vi/architecture.md) - [Maintainer guide tiếng Việt](docs/vi/maintainer-guide.md) - [Tài liệu tiếng Việt](docs/vi/README.md) - [Operator manual tiếng Việt](docs/operator-manual-vietnamese.md) - [Command reference tiếng Việt](docs/command-reference-vietnamese.md) ## Cấu trúc repository ```text piagent/ ├─ architecture/ quy tắc layer và giới hạn file cho máy kiểm tra ├─ adapters/ profile project tái sử dụng ├─ catalog/ capability index xác định ├─ docs/ tài liệu chuẩn EN/VI và hướng dẫn vận hành ổn định ├─ evals/ kịch bản đánh giá có governance ├─ packs/ capability manifest và recipe có version ├─ packages/ │ ├─ piagent-core/ Pi package: extension, runtime, skill, managed harness │ └─ piagent-webui/ dashboard: contract, client, server, gateway, ownership ├─ schemas/ JSON schema ├─ scripts/ setup, doctor và helper kiểm tra └─ templates/ template project/global ``` `piagent-core` là Pi extension và có thể chạy headless độc lập. `piagent-webui` là giao diện `piagent dashboard`, nằm trên một dependency spine riêng: WebUI đọc platform nhưng platform không phụ thuộc ngược vào WebUI, nên runtime vẫn hoạt động khi không mở dashboard. Cả hai sơ đồ layer đều được kiểm tra bằng `npm run architecture:check`; xem [Architecture](docs/vi/architecture.md). ## Adaptive model routing Adaptive model routing cho fresh task dùng `piagent-route --prompt "" --json`. Chỉ `--execute --yes` mới mở provider-backed Pi process; `/model`/CLI pin luôn được giữ và extension không đổi model giữa conversation. ## Verification ```bash npm run verify ``` Gate riêng cho parity WebUI/Terminal (không gọi provider) và suite logic sâu dùng baseline Luna/medium so với `codex-cli`: ```bash npm run benchmark:webui-parity npm run benchmark:deep -- --dry-run npm run benchmark:deep ``` `deep-logic-v1` có 7 scenario difficulty `large`, khóa Piagent/`codex-cli` ở Luna/medium và chạy 3 repeat trên 2 surface (42 model session). Suite phủ event reconciliation, fair dependency scheduling, layered policy, graph-aware context, resumable stream, transactional config và temporal usage billing chính xác; claim chỉ được phép khi đủ full suite, token và duration gate, đồng thời không có retry. Retry diagnostic vẫn được ghi rõ nhưng làm release gate fail. `--dry-run` chỉ validate kế hoạch, không dùng quota. Run production-v1 public của `v1.6.0`, `production-v1-20260824T040017Z-05b7cf`, được đo trên đúng commit `3bba8f0b3ff521bc2a355e1f6bef6d1bbdc09511` bằng GPT-5.6 Luna Medium với 108 session. Piagent hoàn thành 54/54 task, so với 48/54 của `codex-cli`. Tỷ lệ fresh token theo family fixed-workload chính là `0,3857` (thấp hơn 61,43%), với khoảng tin cậy 95% `0,3073..0,4840`; cận trên cho phép phát biểu thận trọng rằng Piagent dùng ít hơn ít nhất 51,60% fresh token trên đúng workload đã khai báo trước và đúng release này. Usage của cả 108 session đều exact và không có retry. Xem [bằng chứng benchmark](https://piagent.io.vn/benchmark) và [phương pháp](docs/quality-benchmark.md). Gate này chạy architecture check, test, typecheck, capability validation, runtime smoke và docs consistency trước khi release. Bản phát hành hiện tại là `v1.27.0`. Với team hoặc production, hãy pin tag này hoặc một commit đã review thay vì dựa vào nguồn package không cố định. ## Security Pi Agent Platform là application-level policy layer, không phải OS sandbox. Với untrusted code hoặc adversarial workload, vẫn cần container hoặc VM có filesystem, process, network và credential boundary riêng. Không commit OAuth token, API key, `auth.json`, session, cache, trust state hoặc dữ liệu nội bộ. ## License MIT License. Xem [LICENSE](LICENSE).