Pi Company Platform
stable docs Commands

Team operating docs

Pi runtime được đóng gói như một nền tảng dùng lại cho nhiều dự án.

Tài liệu này gom phần cài đặt, profile, quyền chạy, bảo mật và workflow vào một nơi duy nhất. Mục tiêu là thành viên mới chỉ cần mở trang này, chọn đúng command, chạy đúng chế độ và biết ranh giới an toàn.

Project links Docs · piagent.io.vn GitHub · Vt-mmm/pi_agent Facebook · Vĩnh Tâm
Bắt đầu Xem command Kiểm tra bảo mật

Positioning

Khác gì Codex CLI và Claude Code?

Codex CLI và Claude Code là agent coding tổng quát và đều có cơ chế governance native như permission, approval, sandbox/trust, hooks, subagents, MCP hoặc managed settings tuỳ bề mặt sử dụng. Pi Company Platform đưa các cơ chế governance tương tự vào Pi, rồi đóng gói thành workflow đội nhóm: profile, policy guard, capability lock, MCP, subagents, memory và verify gate dùng lại được trên nhiều repo.

Hạng mục Codex CLI Claude Code Pi Company Platform
Vai trò chính Coding agent chạy trong terminal, làm việc trực tiếp trên local repo. Agent coding đa bề mặt: terminal, IDE, desktop, web và tích hợp dev tools. Governance layer cho Pi: chuẩn hoá cách team dùng agent theo policy, profile và workflow vận hành.
Tuỳ biến team Dùng AGENTS.md, config, skills, plugins, MCP và command native. Dùng CLAUDE.md, settings, permissions, hooks, skills và MCP. Dùng adapter profile, base policy, command guard, capability pack, docs và scripts.
Quyền chạy Có sandbox, approval policy, permission profiles, network controls và workflow read-only/workspace-write tuỳ môi trường. Có permissions, working-directory boundary, sandboxed bash option, hooks và managed settings cho team. Có read-only, workspace-write, trusted-full-access ở lớp policy extension của Pi.
Bảo mật secret Dựa trên OS-enforced sandbox, approval, network policy và bề mặt Codex đang dùng. Dựa trên permission architecture, sandbox option, trust verification, allowlist và security best practices. Application-level policy layer cho controlled tools: protected paths, shell checks, symlink alias, output redaction và integrity lock.
Điểm mạnh riêng Trải nghiệm terminal gọn, tích hợp Git và local tooling. Hệ sinh thái command, hooks, memory, multi-surface mạnh. Tạo chuẩn nội bộ: mọi repo dùng cùng profile, cùng guard, cùng verify discipline.

Quickstart

Step by step cho thành viên mới

Luồng dưới đây là đường đi chuẩn cho team: chuẩn bị Node.js và Pi Coding Agent, cài Pi Company Platform bằng release tag đã pin, kiểm tra compatibility, mở repo, chọn profile, bật quyền phù hợp, chạy task, rồi verify bằng command thật. Bản latest chỉ nên dùng cho máy cá nhân hoặc sandbox chấp nhận cập nhật nhanh.

Chuẩn bị runtime

Dùng Node.js 20 trở lên và Pi Coding Agent 0.80.10. Pi Company Platform v0.4.7 đang pin compatibility với runtime này qua package metadata.

Runtime prerequisites
node --version  # >= 20
npm install -g @earendil-works/pi-coding-agent@0.80.10
pi --version

Cài Pi Company Platform có pin

Team, production và docs quickstart nên pin release tag hoặc commit cụ thể. Máy cá nhân có thể dùng source không pin nếu chấp nhận cập nhật theo nhánh hiện tại.

Pinned install
pi install git:github.com/Vt-mmm/pi_agent@v0.4.7
pi update --extensions

Latest chỉ cho cá nhân/sandbox

Dùng latest khi muốn nhận thay đổi nhanh trên máy riêng. Khi đưa vào repo/team, đổi sang tag hoặc commit đã review để mọi developer nhận cùng một cấu hình.

Personal latest
pi install git:github.com/Vt-mmm/pi_agent
pi update --extensions

Mở repo dự án

Chạy Pi từ thư mục repo. Với repo đã tin cậy, dùng wrapper trusted-run khi cần tự động hoá có kiểm soát.

Start
cd /path/to/project
pi

Onboard context

Chạy một lần ở repo mới để ghi context, verify matrix và protected areas vào .pi/.

Onboard
/onboard-project

Chọn profile

Dùng /profile auto để áp profile được detect, hoặc chọn profile rõ theo loại repo.

Profile
/profile auto

Chọn permission

Scout thì read-only, code bình thường thì workspace-write, automation tin cậy thì full-access có guard.

Permission
/permission-status
/workspace-write

Chạy workflow

Dùng command đúng mục tiêu để agent không phải diễn giải quá dài. Task nào nặng context thì dùng fresh session.

Workflow
/task Implement the requested bounded change.
/review
/fresh-task Implement the requested bounded change.

Verify trước khi handoff

Final gate chỉ tin kết quả command đã chạy thật, exit 0, và khớp verify plan. Với setup team, chạy doctor và smoke test sau khi pin hoặc nâng version.

Doctor + smoke
pi-company-doctor /path/to/project --strict-share
# in pi_agent source repo:
npm run smoke
npm run verify
npm test
npm run typecheck

Architecture

Kiến trúc repo

Repo này không nhét business logic vào core. Core chỉ giữ policy, prompts, guard, skills, subagents và scripts đủ chung để áp cho nhiều dự án.

Core package

packages/pi-company-core chứa extension guard, prompts, skills và subagent roles.

Adapters

adapters/ chứa profile dùng lại: frontend, backend, fullstack, data, devops, docs.

Capability packs

packs/ gom policy, lifecycle, recipes và eval scenarios theo manifest có lock.

Policies

Base policy định nghĩa protected paths, command rules, permission modes và human-action gates.

Scripts

Setup, doctor, model scope, MCP, subagents, benchmark và trusted-run wrapper đều có CLI riêng.

Docs

docs/ giữ manual dài. docs-site/ là trang HTML gọn cho team.

Security model

Policy enforcement layer, không phải OS sandbox

Platform ưu tiên fail-closed trong bề mặt tool được kiểm soát: khi lock sai, profile sai hoặc command đụng vùng nhạy cảm, guard cố gắng chặn trước khi tool chạy. Đây là application-level policy enforcement layer, không phải lớp cách ly hoàn chỉnh; với code hoặc prompt không tin cậy vẫn cần container/VM và giới hạn credential, filesystem, process, network.

Protected paths

Chặn đọc/ghi qua controlled tools đối với file như .env, auth.json, local trust files, profile lock và settings nhạy cảm.

Shell hardening

Guard dựa vào shell parser và rule cho command được kiểm soát để bắt glob, brace, redirection, bare-word symlink và xargs composition trước khi shell mở rộng runtime.

Secret redaction

Tool output text đi qua redactor để che token, provider keys, secret keyword patterns và giá trị nhạy cảm phổ biến. Benchmark hiện là synthetic/internal và model vẫn đang hoàn thiện.

Capability lock

Pack lock có digest và tamper detection. Lock hỏng thì fail-closed, không tự nới quyền.

Human-action gate

Destructive hoặc external-provider action vẫn cần operator xác nhận rõ, kể cả khi full-access đang bật.

Verify evidence

Handoff hoàn tất cần bằng chứng verify từ bash result đã quan sát, không nhận câu trả lời “đã test” suông.

Ranh giới quan trọng

Guard phụ thuộc vào tool path, controlled tools và shell parser mà platform quan sát được. Nó không ngăn một process khác chạy cùng quyền OS đọc/ghi ngoài guard, và không thay thế sandbox của hệ điều hành.

  • Có thể bị ảnh hưởng bởi symlink, encoding, nested payload, shell expansion hoặc tool mới chưa được policy hoá.
  • Redaction là backstop giảm rò rỉ, không phải giấy phép để đưa secret thật vào prompt/output.
  • Workload không tin cậy cần container/VM với giới hạn filesystem, process, network và credential.
Redaction cần kiểm toán độc lập

Các benchmark hiện tại là kiểm thử synthetic/internal cho regression và release gate, chưa tương đương external security audit. Trước khi xem redaction như bảo đảm an toàn mạnh, cần threat model rõ, attack vectors, matrix Linux/macOS/Windows và shell, fuzz parser, kiểm tra symlink/path traversal, third-party audit, quy trình issue/CVE và chính sách LTS support.

Profiles

Project profile: chọn đúng đường ray cho repo

Profile ghi vào .pi/company-profile.json và lock tương ứng. Command profile hiện đã chạy trực tiếp, không kích thêm câu trả lời dài từ model.

Xem status ngắn
/profile
Liệt kê options
/profile list
Áp profile detect
/profile auto
Frontend
/profile web-frontend
/profile fe
Backend/API
/profile backend-api
Backend read-only, frontend write
/profile be-readonly-fe
/profile be-fe
Fullstack
/profile fullstack
/profile full
Docs-only
/profile docs
generic node-typescript python web-frontend backend-api fullstack be-readonly-fe data devops mobile docs

Permissions

Một command để đổi quyền theo task

Permission mode là session-local override. Đổi mode không sửa project profile. Nếu truyền thêm nội dung sau command, Pi đổi quyền rồi gửi phần còn lại thành task kế tiếp.

Mode Dùng khi nào Ranh giới Command
read-only Scout, audit, mapping, review không chỉnh source. Cho read, grep, find, ls và company tools; chặn shell/write/unknown tools. /read-only
workspace-write Implementation bình thường trong repo. Default guarded mode; giữ protected path, shell policy, capability và verify gate. /workspace-write
trusted-full-access Automation trên repo đã tin và task đã rõ. Nới autonomy trong guard, nhưng vẫn giữ protected path, redaction, lock và confirmation. /full-access
Xem permission
/permission-status
Read-only session
/read-only
Workspace write
/workspace-write
Full-access + task
/full-access Run the trusted local verification suite.

Command catalog

Command ngắn, rõ, ít token burn

Ưu tiên dùng slash command vì mỗi command đã gói policy và flow. Thành viên không cần paste lại hướng dẫn dài trong từng prompt.

Session basics

/login /model /company-commands /company-status /company-usage /task-preflight

Dùng để setup session, chọn model, xem profile/usage và quyết định có cần fresh session trước task lớn không.

Project profile

/profile /profile list /profile auto /profile fullstack /profile be-fe

Áp profile trực tiếp, output ngắn, không yêu cầu model giải thích dài.

Implementation workflow

/task /plan /review /scout /discuss

Gói sẵn read context, task contract, implementation, verify evidence và final handoff.

Git handoff

/commit /pr git status git diff

Không cần namespace /git. Commit/PR đi qua shell guard; push và stage rộng như git add -A cần xác nhận.

Fresh sessions

/fresh-task /fresh-scout /fresh-be-to-fe

Dùng khi context đã nặng hoặc cần một session sạch cho workflow mới.

MCP

/mcp pi-company-mcp

Kiểm tra và cấu hình tool servers theo preset core, popular hoặc design.

Subagents

/subagents-doctor /subagents-models /subagents-fleet /subagent-cost

Kiểm tra runtime, model routing, background runs và cost khi dùng multi-agent.

Workflows

Các luồng chính

Chọn workflow theo intent thay vì mô tả lại policy trong prompt. Cách này giảm context lặp và giữ output tập trung hơn.

Git trong Pi Company

Không có namespace /git riêng. Dùng /commit để commit local đã review, dùng /pr để chuẩn bị PR. Các hành động như git push hoặc stage rộng git add -A vẫn cần operator xác nhận.

Implementation bounded
/task Fix the failing checkout test and verify.
Read-only scout
/scout Map the auth flow and risk areas.
Plan trước khi code
/plan Add multi-tenant billing support.
Review diff
/review
Commit local có guard
/commit "feat: add guarded git workflow"
Chuẩn bị pull request
/pr "Prepare PR for guarded git workflow"
Backend spec sang frontend
/profile be-readonly-fe
/be-to-fe Implement frontend support for the new user status endpoint.
Cải thiện platform
/platform-improve Harden command docs and run verification.

Runtime tools

Terminal commands cho operator

Nhóm command này chạy ngoài slash command, dùng cho setup, doctor, benchmark, capability lock và automation.

Setup global
pi-company-setup --mcp-preset core --subagents-preset safe
Release/update
pi-company-install --stable --dry-run
pi-company-install --stable
pi-company-install --version v0.4.7
Init project
pi-company-init /path/to/project
Doctor
pi-company-doctor /path/to/project
Trusted run
pi-company-auto --read-only -p "Scout payment mapping. Do not edit source."
pi-company-auto --full-access -p "Run the trusted local benchmark suite."
Capabilities
pi-company-capabilities catalog --check
pi-company-capabilities doctor --profile .pi/company-profile.json
Verification
npm run verify
npm test
npm run typecheck

Team usage

Team nên dùng như một chuẩn vận hành

Mỗi repo chỉ cần link package, chọn profile đúng và giữ tài liệu project-specific ở repo của dự án đó. Core vẫn sạch, nhỏ và audit được.

Việc nên làm

Chạy /onboard-project, áp /profile auto, dùng workflow command, verify thật và ghi blockers rõ ràng.

Việc nên tránh

Đưa token, auth file, cache, session, private examples hoặc business logic riêng vào core package public.

Chuẩn handoff

Final response nên nói ngắn: đã đổi gì, verify nào đã chạy, có dùng subagent không, và còn rủi ro hoặc next step nào cần người review.