Pi Agent Platform

English

Pi Agent Platform là reusable Pi harness dành cho project onboarding, workflow theo profile, guarded tool usage, MCP, multi-agent orchestration, memory policy, Context Engine và task verification.

Tài liệu public: piagent.io.vn

Cài đặt

Yêu cầu Node.js >=22.19.0. Chạy từ project cần sử dụng:

npm install -g @piagent/platform
piagent-setup

Sau khi setup:

cd /path/to/project
pi

Trong session Pi đầu tiên của project, chạy /onboard. Hằng ngày, dùng /workflow để chọn luồng và /usage để xem session, model, thinking và token.

Nguyên tắc vận hành

• Mỗi task dùng một session có tên rõ ràng.
• Slash command chỉ chạy handler đã đăng ký; agent không phải scout lại command.
• Prompt hướng dẫn model, còn policy quan trọng được enforce tại runtime.
• MCP config không chứa token hoặc OAuth credential.
• Task source-changing cần scope, verify evidence và final gate.
• Local state nằm trong .pi/piagent-state/, có owner-only permission và bounded retention.
• Project-specific business logic nằm trong project profile hoặc adapter, không đưa vào core.

Command chính

Command	Mục đích
/workflow	Chọn workflow task, scout, plan, review, commit, PR hoặc onboarding
/profile	Xem hoặc đổi project profile
/permission	Đổi permission mode trong session
/context	Xem Context Engine, index, retrieval và telemetry
/usage	Xem session, model, thinking và context usage
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
/onboard	Khởi tạo project profile và context

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, task, context và state.
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:

npm run architecture:check

Đọc chi tiết:

• Architecture tiếng Việt
• Maintainer guide tiếng Việt
• Tài liệu tiếng Việt
• Operator manual tiếng Việt
• Command reference tiếng Việt

Verification

npm run verify

Gate này chạy architecture check, test, typecheck, capability validation, runtime smoke và docs consistency trước khi release.

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.