Bỏ qua, đến phần nội dung

Cài đặt chi tiết ​

Trang này đi qua cách cài Phillip trên từng hệ điều hành, cách sửa PATH, nâng cấp, gỡ cài đặt và cài extension VS Code. Nếu cần đi từ đầu đến task đầu tiên thì xem Dev và Test.

Máy cần những gì ​

Bạn cần Node 22 trở lên kèm npm (kiểm tra bằng node --version), git, và một trong ba hệ điều hành macOS, Linux hoặc Windows. Bạn cũng cần quyền ghi vào thư mục cài toàn cục của npm, vì script cài không dùng sudo (xem Thư mục cài của npm). Cuối cùng là địa chỉ Tara của tổ chức, trong tài liệu này viết là https://tara.phillipcli.cloud. Bạn hỏi trưởng nhóm hoặc đội vận hành để biết địa chỉ thật.

Cài từ Tara ​

Tara phục vụ script cài và đã ghi sẵn địa chỉ của chính nó vào script. Script không đi qua dịch vụ gói bên ngoài nào.

curl -fsSL https://tara.phillipcli.cloud/install.sh | sh

Khi chạy, script lần lượt làm các việc sau.

  1. Kiểm tra Node 22 trở lên và npm. Thiếu hoặc cũ thì dừng và chỉ cách cài.
  2. Tải thông tin bản Phillip mới nhất (latest.json) và gói .tgz từ Tara.
  3. Đối chiếu sha256 của gói với giá trị Tara công bố. Không khớp thì không cài.
  4. Chạy npm install -g với gói đó.
  5. Kiểm tra thư mục bin của npm đã nằm trong PATH chưa, và cảnh báo nếu lệnh ph trên máy đang trỏ tới chương trình khác.
  6. Ghi địa chỉ Tara và khóa công khai của Tara vào cấu hình người dùng của Phillip, giữ nguyên các khóa khác trong cấu hình.

Cài xong, bạn kiểm tra và thiết lập như sau:

bash
ph --version          # phiên bản Phillip rồi phiên bản Claude Code đi kèm
ph setup              # đăng nhập Tara, chọn harness, kết nối GitHub/GitLab, kiểm tra máy (chạy trong thư mục repo)
ph forge doctor       # kiểm tra môi trường

Nếu bạn thuộc nhiều tổ chức, ph setup (qua ph login) sẽ hỏi dùng tổ chức nào. Trong CI, hãy chỉ rõ bằng ph login --org acme hoặc đặt PHILLIP_ORG=acme. Muốn đổi sau này, dùng ph org switch <slug>. Người chưa có tổ chức nào thì tạo ở màn hình Get started trên Portal, hoặc bằng ph org create <slug>.

Lệnh cài theo hệ điều hành ​

Hệ điều hànhLệnh càiCấu hình người dùng lưu ở
macOS, Linuxcurl -fsSL https://tara.phillipcli.cloud/install.sh | sh~/.config/phillip/config.json (hoặc theo XDG_CONFIG_HOME)
Windows (PowerShell)irm https://tara.phillipcli.cloud/install.ps1 | iex%APPDATA%\phillip\config.json

Muốn đổi thư mục cấu hình thì đặt biến môi trường PHILLIP_HOME trước khi chạy script. Máy không có curl thì script tự dùng wget. Trên Windows, nếu chưa có Node, script gợi ý chạy winget install OpenJS.NodeJS.

Cài bằng npm ​

Nếu trưởng nhóm đưa bạn file gói .tgz, hoặc bạn không muốn dùng script, hãy cài thẳng:

bash
npm install -g ./phillip-<phiên-bản>.tgz

Cách này chưa ghi địa chỉ Tara vào cấu hình. Vì vậy ở bước thiết lập, bạn chạy ph setup --tara https://tara.phillipcli.cloud để Phillip lấy địa chỉ và khóa công khai.

Thêm vào PATH ​

ph và phillip là hai tên của cùng một chương trình, nằm trong thư mục bin của npm. Nếu terminal báo ph: command not found thì thư mục đó chưa có trong PATH.

  1. Mở một terminal mới, vì shell chỉ đọc lại cấu hình khi khởi động.

  2. Xem thư mục cần thêm:

    bash
    echo "$(npm prefix -g)/bin"
  3. Thêm thư mục đó vào PATH. Ví dụ với zsh:

    bash
    echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

    Bash thì dùng ~/.bashrc trên Linux hoặc ~/.bash_profile trên macOS. Trên Windows, bạn thêm thư mục mà npm prefix -g in ra vào biến Path của người dùng rồi mở lại PowerShell.

  4. Chạy ph --version để kiểm tra.

Nếu máy có chương trình khác cũng tên ph, script cài sẽ cảnh báo. Lúc đó bạn dùng phillip thay cho ph, hoặc đưa thư mục bin của npm lên trước trong PATH.

Thư mục cài của npm ​

Lỗi EACCES nghĩa là npm đang cài vào thư mục hệ thống mà bạn không có quyền ghi. Đừng dùng sudo npm, hãy cho npm cài vào thư mục của bạn:

bash
mkdir -p "$HOME/.npm-global"
npm config set prefix "$HOME/.npm-global"
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

Trên Windows, bạn chạy npm config set prefix "$env:APPDATA\npm" rồi thêm thư mục đó vào Path. Sau đó chạy lại lệnh cài.

Nâng cấp và gỡ cài đặt ​

Muốn nâng cấp, bạn chạy lại đúng lệnh cài ở trên. Script lấy bản mới nhất của Tara, kiểm sha256 và cài đè, còn cấu hình và đăng nhập của bạn vẫn giữ nguyên. Bandum chạy trên máy thì nâng cấp riêng bằng ph bandum ui upgrade, và tài nguyên trong dự án thì dùng ph tara outdated rồi ph tara upgrade.

Muốn gỡ, bạn chạy:

bash
npm uninstall -g @phillipcli/phillip

Nếu muốn xóa luôn cấu hình và dữ liệu, trước hết đăng xuất bằng ph tara logout để thu hồi phiên và xóa token khỏi máy, sau đó xóa thư mục cấu hình ở bảng trên. Máy có Guardrails do tổ chức cài bằng quyền quản trị thì gỡ theo hướng dẫn của đội vận hành, vì ph guardrails uninstall cần sudo.

Cài extension VS Code ​

Extension Phillip cho VS Code là một file .vsix mà Tara phát cạnh gói Phillip. Bạn tải về rồi cài bằng hai lệnh:

bash
curl -fsSLo phillip-vscode.vsix https://tara.phillipcli.cloud/phillip/phillip-vscode-latest.vsix
code --install-extension phillip-vscode.vsix

Nếu Tara của bạn bắt đăng nhập mới được tải, bạn đăng nhập Tara trước rồi mở cùng địa chỉ trên trình duyệt để lưu file.

Hoặc trong VS Code, bạn mở Extensions, bấm menu ... rồi chọn Install from VSIX.... Extension không giữ token riêng mà chạy lệnh ph giúp bạn, nên bạn cần cài và đăng nhập Phillip trước. Xem thêm Extension VS Code.

Đọc kết quả ph forge doctor ​

ph forge doctor cho biết môi trường đã đủ chưa.

DòngÝ nghĩa
✗ Node, ✗ Claude Code, ✗ git, ✗ TaraBắt buộc, sửa rồi chạy lại
⚠ Ryoma, ⚠ Collector, ⚠ GuardrailsTùy chọn, có gợi ý cách sửa

Môi trường đạt khi không còn dòng ✗, còn dòng ⚠ không chặn bạn. Gặp lỗi khác thì xem Xử lý sự cố.

Đọc thêm ​