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

Xử lý sự cố ​

Bạn tìm lỗi của mình theo thông báo hoặc triệu chứng bên dưới. Trước khi nhờ giúp ở Liên hệ, hãy chạy ph forge doctor và gửi kèm kết quả.

Chưa đăng nhập Tara ​

Bạn gặp lỗi này khi thấy "not signed in to Tara", "Tara refused the request (401)", hoặc dòng ✗ Tara trong ph forge doctor. Nguyên nhân là chưa đăng nhập, hoặc phiên đã hết hạn. Phiên đăng nhập bằng trình duyệt sống khá ngắn, khoảng 12 giờ, để bảo vệ các việc cần quyền cao. Bạn đăng nhập lại như sau:

bash
ph login                 # mở trình duyệt, click Allow
ph tara whoami           # in tài khoản, tổ chức và hạn phiên

Một lần đăng nhập thuộc về một tổ chức. Nếu bạn thuộc nhiều tổ chức, ph login hỏi bạn chọn từ danh sách đánh số, hoặc bạn gõ ph login --org <slug> (bắt buộc khi không có terminal, như trong CI). Nếu bạn chưa thuộc tổ chức nào, lệnh in địa chỉ Portal <tara>/get-started để bạn tạo tổ chức hoặc nhận lời mời. Muốn đổi tổ chức sau này, bạn dùng ph org switch <slug>.

Nếu máy không có trình duyệt, như qua SSH hay trong CI, bạn tạo token cá nhân trên Portal Tara (menu tài khoản, Access tokens (token truy cập)), chạy ph tara login --token-stdin rồi dán token vào.

Nếu không kết nối được tới Tara, bạn kiểm tra địa chỉ có https:// không, rồi kiểm tra mạng hoặc VPN.

Chưa thuộc tổ chức nào (no_org) ​

Bạn thấy thông báo "you do not belong to any organization yet", hoặc mã no_org (HTTP 409), khi chạy ph login hay tạo token. Nguyên nhân là tài khoản đã đăng nhập nhưng chưa là thành viên của tổ chức nào. Đăng nhập chỉ cho biết bạn là ai. Bạn không mất gì: mã đăng nhập chưa bị dùng hết, nên làm xong bước dưới bạn chạy lại lệnh là được.

Trên Portal: bạn mở <tara>/get-started. Bạn có thể tạo tổ chức (nhập tên và slug như acme, bạn thành Owner), hoặc mở đường dẫn lời mời mà Owner hay Admin đã gửi.

Bằng Phillip: bạn tạo tổ chức bằng ph org create acme (cần đăng nhập bằng trình duyệt), hoặc nhận lời mời trên Portal trước. Rồi đăng nhập lại:

bash
ph org create acme --name "Acme Inc."
ph login

Cần chọn tổ chức (org_required) ​

Bạn thấy "Choose an organization first", hoặc mã org_required (HTTP 409). Nguyên nhân là bạn thuộc nhiều tổ chức mà lúc đăng nhập chưa nói là tổ chức nào. Trong terminal, ph login hiện danh sách đánh số cho bạn chọn. Không có terminal, như trong CI hay qua SSH, lệnh in danh sách rồi dừng vì không hỏi bạn được.

Bằng Phillip: bạn nêu tên tổ chức.

bash
ph org list                # các tổ chức bạn thuộc về
ph login --org acme

Trong CI, bạn đặt PHILLIP_ORG=acme cạnh PHILLIP_TARA_TOKEN. Trên Portal: bạn chọn tổ chức ở bộ chuyển đầu trang.

Hết seat (seat_limit) ​

Bạn thấy seat_limit (HTTP 409) khi mời người, nhận lời mời hoặc đổi vai trò. Nguyên nhân là tổ chức đã dùng hết seat. Owner, Admin và Member mỗi người dùng một seat, và gói Free có 7 seat. Viewer không dùng seat. Gói Team không giới hạn seat: Owner có thể nâng gói.

Owner hoặc Admin xử lý theo một trong các cách sau:

  • Trên Portal: mở trang thành viên của tổ chức. Bạn xóa người đã rời đi, hoặc đổi người chỉ cần dùng trình duyệt (BA, PO, PM) sang Viewer. BA, PO, PM mới thì mời với vai trò Viewer.
  • Bằng Phillip:
bash
ph org current                          # gói và số seat đã dùng
ph org members                          # ai đang trong tổ chức
ph org members set-role <login> viewer  # nhả một seat
ph org members remove <login>
ph org invite <email> --role viewer

Nếu bạn không phải Owner hay Admin, hãy nhờ một trong hai người làm giúp.

Tên chỉ có ở tổ chức khác ​

Bạn thấy "did you mean beta/skill-foo?", hoặc mã not_found_hint (HTTP 404), khi cài hay khóa một tài nguyên bằng tên trần. Nguyên nhân là không có tài nguyên tên skill-foo ở kho chính thức hay trong tổ chức của bạn, nhưng một tổ chức khác có tài nguyên cộng đồng công khai cùng tên. Tên trần cố ý không bao giờ khớp với tài nguyên của tổ chức khác, để không ai chiếm được tên. Thông báo liệt kê tối đa năm tên đầy đủ.

Bạn dùng tên đầy đủ <org>/<tên>. Trên Portal: kho cộng đồng hiện tên đầy đủ của từng tài nguyên. Bằng Phillip:

bash
ph tara search skill-foo --channel community
ph tara add beta/skill-foo

Nếu lỗi đến từ một phụ thuộc trong manifest, bạn ghi tên đầy đủ vào dependencies. Tài nguyên cộng đồng sẽ hỏi xác nhận trước khi thêm.

Mở tổ chức bị 404 ​

Bạn mở <tara>/acme/... hoặc chạy lệnh cho một tổ chức rồi nhận 404 Not found. Nguyên nhân là bạn chưa là thành viên của tổ chức đó, hoặc gõ sai slug. Tara trả cùng một 404 cho cả hai trường hợp, để người ngoài không biết tổ chức có tồn tại hay không.

  1. Chạy ph org list hoặc xem bộ chuyển tổ chức để biết các slug bạn thuộc về.
  2. Nếu đáng ra bạn phải là thành viên, bạn nhờ Owner hoặc Admin mời, rồi nhận lời mời.
  3. Nếu bạn đã là thành viên, chuyển sang bằng ph org switch <slug>, vì đăng nhập và token của bạn có thể đang thuộc tổ chức khác.

Không thấy lệnh ph (PATH) ​

Lỗi này hiện ra dưới dạng ph: command not found, hoặc terminal tích hợp của VS Code báo không tìm thấy ph, hoặc extension VS Code báo chưa cài Phillip dù bạn đã cài. Lý do là npm install -g đặt ph vào thư mục bin của npm, mà thư mục đó chưa nằm trong PATH. VS Code mở từ Dock hoặc menu Start cũng thường có PATH tối giản hơn terminal của bạn.

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

  2. Tìm thư mục cần thêm:

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

    bash
    echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
  4. Riêng VS Code thì bạn thoát hẳn rồi mở lại từ terminal bằng code ., hoặc chạy ph setup để extension nhận đường dẫn.

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.

Nếu khi cài gặp 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. Script cài không tự dùng sudo, nên bạn cho npm cài vào thư mục của mình:

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

Sau đó bạn chạy lại lệnh cài.

Node cũ hơn 22 ​

Khi thấy "Node v… is too old. Phillip needs Node 22 or later", hoặc dòng ✗ Node trong ph forge doctor, bạn nâng Node lên 22 trở lên rồi chạy lại lệnh cài.

bash
node --version           # cần v22 trở lên
nvm install 22 && nvm use 22   # nếu dùng nvm; hoặc fnm, brew install node, trình cài từ nodejs.org

Nếu máy có nhiều phiên bản Node, hãy chắc rằng terminal và VS Code cùng dùng bản 22.

Bị Guardrails chặn ​

Khi một thao tác của agent bị từ chối hoặc bị hỏi lại, thông báo sẽ kèm tên luật và lý do. Bị chặn chưa chắc là bạn làm sai, vì có khi luật chặn nhầm. Bạn đọc thông báo để biết luật nào và vì sao, rồi thử nhờ agent làm theo một hướng an toàn khác cho cùng mục đích.

Nếu tin luật chặn nhầm, bạn gửi phản hồi kèm lý do để đội phụ trách xem. Phillip che bí mật trong ghi chú trước khi gửi.

bash
ph guardrails feedback <id luật> --note "Why I think this is a false positive"

Muốn xem tình trạng Guardrails trên máy, bạn chạy ph guardrails status. Đừng tìm cách tắt Guardrails, nếu cần ngoại lệ thì nhờ Owner hoặc Admin của tổ chức, hoặc project admin, để policy được cập nhật đúng quy trình. Xem thêm Khi bị Guardrails chặn.

Plugin sai chữ ký hoặc bị thu hồi ​

Có ba dấu hiệu. Thứ nhất là thông báo "the signature of … is invalid" hoặc "… has no signature" khi cài tài nguyên hoặc khi chạy ph bandum ui. Thứ hai là cảnh báo "no Tara signing key is configured, so only sha256 is checked". Thứ ba là ph tara list hay ph forge doctor báo một tài nguyên bị thu hồi hoặc ngừng hỗ trợ.

Triệu chứngLàm gì
Chữ ký sai hoặc thiếuKhông chạy gói này và báo Owner hoặc Admin. Kiểm khóa tin cậy bằng ph tara keys
Cảnh báo chưa kiểm chữ kýMáy chưa có khóa công khai. Lấy khóa từ Owner hoặc Admin rồi chạy ph tara keys trust ed25519:<khóa>
Tài nguyên bị thu hồiGói này có vấn đề an toàn. Chạy ph tara outdated rồi ph tara upgrade để lên bản không bị thu hồi, sau đó commit phillip.lock
Plugin scm báo no connector plugin for <host>Chạy ph connect để chọn nhà cung cấp cho máy chủ đó

Cơ chế này được giải thích ở Ký số và thu hồi.

Lỗi khi kết nối GitHub hoặc GitLab ​

ThấyCách xử lý
401 hoặc 403 khi kiểm tokenToken sai, hết hạn hoặc thiếu quyền, hoặc bạn chưa phải Developer của repo. Tạo lại bằng ph connect
404Không vào được máy chủ hoặc project. Kiểm tra --host và xem token đã được cấp vào project chưa
Token mới không có tác dụngBiến môi trường GITHUB_TOKEN hoặc GITLAB_TOKEN đang đè token đã lưu, bạn bỏ chúng khỏi shell

Lỗi khi chạy Bandum trên máy ​

ThấyCách xử lý
"port … is busy"Bỏ --port để Phillip tự chọn cổng trống
"--docker needs Docker installed and running"Bật Docker Desktop rồi chạy lại, hoặc bỏ --docker để dùng SQLite
"Bandum exited early"Đọc 20 dòng log mà Phillip in kèm, và chạy ph bandum ui logs
Bandum báo 401 từ GitHub hoặc GitLabChạy ph connect, rồi ph bandum ui stop và chạy lại ph bandum ui

Lỗi hằng ngày với task ​

ThấyCách xử lý
no open PR for GH-12Bạn chưa mở PR, hoặc nhánh không mang mã GH-12
branch ... does not have the latest commit pushedChạy git push -u origin HEAD rồi chạy lại lệnh
ph bandum check thoát với mã 2Sửa theo từng dòng báo lỗi, còn cảnh báo thì không chặn
The repo has no .bandum.jsonDự án chưa khai cách chạy ứng dụng, bạn dùng --cli hoặc hỏi Dev

Dòng cảnh báo trong ph forge doctor ​

Dòng ⚠ là tùy chọn, không làm thiết lập thất bại.

ph forge doctorNode         v24.22.0Claude Code  2.1.308 (Claude Code)git          git version 2.50.1 (Apple Git-155)Tara         maya.chen @ https://tara.phillipcli.cloudphillip.lock 17 resources locked (lock ba8972f416dd)Ryoma        https://ryoma.phillipcli.cloud: metrics receivedCollector    data received through RyomaGuardrails   not installed on this machine (the Guardrails dashboard will be empty). Install: sudo "$(command -v ph)" guardrails install --tara https://tara.phillipcli.cloud --ryoma https://ryoma.phillipcli.cloud --keys ed25519:<public key>
ThấyÝ nghĩa
⚠ RyomaPhiên chưa gửi số liệu, hoặc chưa đăng nhập Tara. Đăng nhập lại, nếu còn báo thì hỏi đội vận hành
⚠ GuardrailsMáy chưa cài Guardrails. Chạy đúng lệnh sudo … mà doctor in ra, hoặc hỏi xem bạn có bắt buộc cài không
⚠ CollectorCollector không nhận dữ liệu nên dashboard trống, nhờ đội vận hành kiểm tra