Kiến trúc
Nếu bạn mới biết PhillipCLI, hãy đọc Giới thiệu trước. Nền tảng có bốn thành phần. Hai thành phần chạy trên máy bạn, hai thành phần chạy online, và dữ liệu chỉ đi theo một chiều từ máy bạn ra ngoài. Đọc xong bạn sẽ hiểu vì sao dịch vụ online không bao giờ cần truy cập vào máy của bạn.
Vuốt ngang để xem hết sơ đồ.
Bốn thành phần
Phillip chạy trên máy người dùng. Đó là CLI ph kèm extension VS Code, lo việc cài tài nguyên từ Tara, chạy Claude Code với cấu hình của dự án, nhận và giao task. Bandum cũng chạy trên máy người dùng và là nơi giữ bảng task, testcase, kiểm thử nghiệm thu và duyệt, do Phillip tải và chạy giúp bạn.
Tara và Ryoma chạy online. Tara là kho tài nguyên, nơi đăng nhập, ký số, duyệt kho chính thức, và là Portal cùng Knowledge base. Ryoma thu số liệu phiên AI và tiến độ giao hàng, theo từng tổ chức. Dashboard cho khách hàng nằm ở các trang Projects trong Portal.
Người dùng chia làm hai nhóm. Dev và Test dùng Phillip cùng Bandum trên máy. BA, PO và PM chỉ cần trình duyệt, vào Portal Tara và web Bandum.
Phillip
Phillip là cửa vào duy nhất trên máy. Bạn vẫn làm việc trong VS Code với Claude Code như thường, còn Phillip chuẩn bị môi trường phía sau.
Lệnh ph setup đăng nhập Tara, áp harness vào dự án và nối GitHub hoặc GitLab. Các lệnh ph tara add và ph tara install cài đúng những version đã khóa trong phillip.lock, và trước khi nạp, Phillip kiểm sha256 cùng chữ ký số. Khi bạn chạy Claude Code qua ph, Phillip bật telemetry gửi về Ryoma, nội dung gửi đi nằm ở Dữ liệu thu thập.
Hook server của Guardrails cũng là một phần của Phillip và chạy trên máy, xem Guardrails theo tầng. Để nói chuyện với GitHub, GitLab hay công cụ khác, Phillip nạp các plugin kết nối (kit). Lõi của Phillip không chứa mã riêng cho nhà cung cấp nào.
Bandum
Bandum lo khâu nghiệm thu: agent hoặc dev làm task, người kiểm thử duyệt hoặc trả lại. Nó chạy trên máy người dùng với SQLite, hoặc PostgreSQL trong Docker, và ph bandum ui sẽ tải về rồi khởi động giúp bạn.
Bandum không giữ dữ liệu gốc. Task là issue, trạng thái là nhãn, còn testcase và kết quả kiểm thử là file trong repo. Vì vậy xóa dữ liệu của Bandum đi thì vẫn dựng lại được từ repo. Định dạng file nằm ở Định dạng Bandum.
Tara
Tara là nơi online chung, và mọi thao tác trên Tara đều làm được từ Phillip.
Tara giữ kho tài nguyên gồm sáu loại tài nguyên, mỗi version bất biến. Mỗi tài nguyên phải qua kiểm tự động rồi mới được ký và phát hành, riêng kho chính thức còn có bước duyệt của platform staff, xem Tiêu chí duyệt. Tara cũng lo đăng nhập và tổ chức (Vai trò và quyền), và giữ Knowledge base theo tổ chức và project mà agent truy cập qua MCP (MCP tools). Portal là giao diện web với các mục Explore, Admin và Projects. Số liệu ở mục Projects lấy từ Ryoma.
Tara phục vụ marketplace theo chuẩn của Claude Code, nên tài nguyên cài vào Claude Code như mọi plugin khác.
Tổ chức và project
Tara phục vụ nhiều khách hàng trên cùng một hệ thống. Tổ chức là đơn vị khách hàng: có thành viên với role, gói cước với số seat, kho tài nguyên riêng (<org>/<tên>) và Guardrails riêng. Project thuộc đúng một tổ chức, đại diện cho một sản phẩm hoặc một repo, với task, số liệu và Guardrails của nó. Một tài khoản thuộc được nhiều tổ chức, và Phillip giữ một token riêng cho mỗi tổ chức.
Dữ liệu được cách ly theo tổ chức hai lớp. Ứng dụng truyền tổ chức lấy từ token vào mọi truy vấn, và cơ sở dữ liệu (Postgres Row-Level Security) chỉ trả các dòng của tổ chức đó. Kho chính thức (aiforge/<tên>) và tài nguyên cộng đồng công khai thì dùng chung, ai cũng chỉ đọc được. Tên tài nguyên mang theo chủ, là tổ chức hoặc một người, ví dụ acme/skill-review hay an/skill-notes; kho cá nhân của một người chỉ riêng họ thấy. Xem Sáu loại tài nguyên.
Ryoma
Ryoma chạy theo từng tổ chức: mọi số liệu gắn tổ chức lấy từ token của bạn, và mọi truy vấn đều lọc theo đó. Ryoma nhận telemetry OpenTelemetry của Claude Code và đọc tiến độ task từ GitHub hoặc GitLab. Từ đó nó tính số liệu theo Flow Framework và khung đo AI. Ryoma chỉ lưu số đếm và metadata, không lưu nội dung prompt hay câu trả lời. Cách đọc số liệu nằm ở trang Đo lường.
Dữ liệu đi theo hướng nào?
Dữ liệu chỉ đi ra từ máy người dùng. Dịch vụ online không bao giờ gọi vào máy bạn hay vào Bandum local.
| Hướng | Nội dung | Xác thực |
|---|---|---|
| Phillip tới Tara | Đăng nhập, tải gói đã ký, gửi bài, xem Knowledge base | Token Tara của bạn |
| Phillip tới Ryoma | Telemetry phiên AI, sự kiện Guardrails (chỉ metadata) | Token Tara của bạn, Ryoma gắn danh tính phía máy chủ |
| Phillip, Bandum tới GitHub/GitLab | Đọc và ghi issue, nhãn, PR | Token của chính bạn |
| Ryoma tới GitHub/GitLab | Đồng bộ task để tính số liệu | Token dịch vụ, chỉ đọc |
| Tara tới Ryoma | Số liệu hiển thị trong Portal | Token dịch vụ, chỉ đọc |
Thông báo qua Telegram, email, Slack hay Zalo đi ra từ Tara, Ryoma và Bandum, qua plugin kit notify. Chúng chỉ chứa metadata như mã task, tiêu đề và đường dẫn.
GitHub và GitLab giữ bản gốc
Nền tảng không giữ bản gốc của task hay mã nguồn. Task là issue, sprint là milestone, người phụ trách là assignee. Trạng thái là nhãn status: …, còn quyết định duyệt hay trả lại là review của PR. Testcase, kết quả nghiệm thu và bằng chứng là file trong nhánh của PR.
Ryoma và Bandum chỉ giữ bản sao để hiển thị và tính toán. Mất bản sao thì đồng bộ lại từ repo.
Plugin chạy ở đâu
Kit cài trên máy bạn chạy trong tiến trình của bạn với quyền của bạn, nên Phillip chỉ nạp khi chữ ký hợp lệ. Trên máy chủ của Tara, Bandum và Ryoma, cùng kit đó chạy trong tiến trình Node với node --permission. Lúc này nó chỉ đọc được thư mục plugin và không thấy bí mật của dịch vụ. Cách viết kit nằm ở Viết kit.