Khóa version và chữ ký số
Cả nhóm phải cài đúng cùng một bản tài nguyên, và Phillip phải biết gói mình tải về đúng là bản đã duyệt. Trang này giải thích phillip.lock, chữ ký số và việc thu hồi, những thứ bảo đảm hai điều đó.
Bốn lớp bảo đảm
Lớp đầu là version: phillip.lock trong repo giữ cho cả nhóm dùng cùng một bản. Lớp thứ hai là bất biến: gói chỉ lưu một lần, không sửa, không ghi đè, nên bản đã phát hành không đổi. Lớp thứ ba là toàn vẹn: sha256 ghi trong lock cho biết gói tải về có đúng gói đã duyệt không. Lớp cuối là xuất xứ: Tara ký gói bằng Ed25519, và máy bạn kiểm chữ ký bằng khóa công khai có sẵn.
Semver và ràng buộc phiên bản
Mọi version có dạng MAJOR.MINOR.PATCH. Khi cần một tài nguyên khác, bạn khai ràng buộc cùng cú pháp với npm và Claude Code.
| Ràng buộc | Nhận |
|---|---|
~1.2.0 | Chỉ bản vá, tức 1.2.x |
^1.2 | Từ 1.2.0 đến trước 2.0.0 |
=1.2.0 hoặc 1.2.0 | Đúng một bản |
>=1.0 <2.0, ^1.0 || ^2.0 | Một khoảng, hoặc hợp của nhiều khoảng |
Harness thường dùng ~ cho agent để môi trường ổn định. Muốn lên bản mới của một agent, chủ harness phát hành version mới của harness. Khi nào tăng số nào thì xem Quy tắc version.
phillip.lock
Ràng buộc chỉ cho biết bản nào chấp nhận được, còn lock ghi đúng bản đang dùng. Khi bạn chạy ph init hoặc ph tara add, Tara giải toàn bộ phụ thuộc, trả về một tập version chính xác, rồi Phillip ghi vào phillip.lock.
{
"schema": 1,
"tara": "https://tara.phillipcli.cloud",
"lockId": "ba8972f4…",
"marketplace": "ai-forge-ba8972f4",
"requirements": [
{ "name": "harness-rnd-sdlc", "version": "^1.5.0" }
],
"resources": [
{
"name": "aiforge/agent-dev",
"pluginId": "agent-dev",
"version": "1.1.1",
"kind": "agent",
"sha256": "61b00027…",
"requiredBy": ["harness-rnd-sdlc"]
}
]
}requirements là những gì dự án yêu cầu trực tiếp. Tên trong lock là tên đầy đủ (<org>/<tên>). Tên trần bạn yêu cầu được tìm trong aiforge trước, rồi đến tổ chức của bạn, không bao giờ sang tổ chức khác. Claude Code cần tên plugin không trùng, nên mỗi mục có pluginId: tên gốc, hoặc <org>-<tên> khi hai mục trùng tên (gói của aiforge luôn giữ tên gốc). resources là kết quả đã giải, kể cả phụ thuộc gián tiếp, và requiredBy cho biết tài nguyên nào kéo chúng vào. lockId tính từ nội dung gồm tên, version và sha256, nên cùng tập version thì ra cùng lockId. marketplace là tên marketplace riêng của lock. Mỗi lock cần một tên riêng vì Claude Code lưu tên marketplace dùng chung cho mọi dự án trên máy.
Bạn nên commit phillip.lock. Máy khác clone dự án về chỉ cần chạy lệnh sau.
ph tara installLệnh này cài đúng các version trong lock và không giải lại. Muốn lên bản mới trong phạm vi ràng buộc, bạn chạy ph tara outdated rồi ph tara upgrade. Muốn nới ràng buộc lên bản mới nhất thì dùng ph tara upgrade --latest.
Phát hành rồi thì không đổi được
Nội dung một version đã phát hành không bao giờ thay đổi. Muốn sửa, bạn gửi version mới, và số version đã dùng thì không dùng lại, kể cả khi bài gửi bị trả lại.
Khi "xóa" một tài nguyên, Tara không xóa gói mà chỉ ẩn nó khỏi danh mục. Nhờ vậy dự án đang khóa version cũ vẫn cài được.
Tara ký khi phát hành
Khi một version được phát hành (duyệt ở kho chính thức, hoặc qua bộ quét ở mọi nơi khác), Tara ký một bản khai bằng khóa Ed25519, trong cùng giao dịch. Nếu ký lỗi thì version không được phát hành. Bản khai (loại tara.package/v2) ghi tên, version, loại, org, kênh (official, org, user hoặc community), sha256 của gói, người duyệt (ngoài kho chính thức là bộ quét tự động) và thời điểm phát hành, kèm sha256 của tài liệu đi theo gói. Tên ở đây là tên trần, còn chủ nằm ở trường riêng tên org, chứa slug tổ chức hoặc tên người dùng. Kênh user là gói cá nhân private: chỉ chủ của nó cài được, và Phillip kiểm chủ khớp với người đang đăng nhập. Kênh community là gói public. Đổi tài nguyên giữa private hoặc internal và public thì các version được ký lại, vì kênh thay đổi. Bên kiểm không biết một kênh thì từ chối gói, đó là mặc định an toàn. Bản khai kiểu cũ tara.package/v1 vẫn được kiểm. Chúng được ký từ trước khi trung tâm được thay bằng tổ chức: trường center cũ có giá trị rnd ứng với aiforge (chính thức), giá trị khác ứng với tổ chức đó (kênh org), còn kênh community giữ nguyên là cộng đồng.
Khóa riêng nằm ngoài cơ sở dữ liệu và kho gói. Bạn có thể đặt nó trong KMS để khóa không bao giờ rời KMS.
Kiểm chữ ký trước khi nạp
Bên dùng gói giữ sẵn khóa công khai dạng ed25519:<base64>. Quản trị phát khóa này qua kênh tin cậy cùng với cấu hình môi trường, và bên kiểm không lấy khóa từ Tara lúc kiểm. Vì thế dù kho gói hoặc cơ sở dữ liệu của Tara bị sửa, kẻ tấn công cũng không giả được chữ ký.
Trên Phillip, bạn cấu hình khóa bằng ph tara keys trust <khóa> hoặc biến PHILLIP_TARA_KEYS. Bandum và Ryoma chạy plugin trên máy chủ, nên quản trị đặt biến cấu hình tương ứng cho chúng.
Khi đã có khóa tin cậy, bên kiểm từ chối gói chưa ký, gói ký bằng khóa lạ và gói có bản khai không khớp tên, version hay sha256. Nếu chưa có khóa thì chỉ kiểm sha256 và cảnh báo. Bạn xem các khóa đang tin cậy bằng lệnh sau.
ph tara keysTrước khi tin một khóa mới, bạn nên đối chiếu vân tay của nó với trưởng nhóm. Có một giới hạn cần biết: nếu bạn cài thẳng bằng claude plugin mà không qua Phillip thì không có bước kiểm chữ ký, và lớp bảo vệ duy nhất còn lại là bộ quét tự động và, ở kho chính thức, bước duyệt.
Danh sách thu hồi có ký
Khi một version có lỗi nghiêm trọng, nhân sự nền tảng hoặc Admin, Owner của tổ chức sở hữu sẽ thu hồi nó.
ph tara yank agent-dev@1.1.1 --reason "lộ đường dẫn nội bộ trong prompt"Sau đó Tara ký lại toàn bộ danh sách các version bị thu hồi, gồm org, tên, version, sha256 và lý do. Kho riêng của mỗi tổ chức có danh sách riêng ở GET /v1/orgs/{org}/revocations, chỉ thành viên của tổ chức đọc được, vì các bản bị thu hồi ở đó không công khai (bản bị thu hồi của kho cá nhân nằm trong danh sách riêng của chủ). Danh sách có số thứ tự serial tăng dần. Bên kiểm có khóa tin cậy sẽ giữ bản có serial cao nhất mình từng thấy và không quay về bản cũ hơn. Nếu Tara không trả lời, họ dùng bản đã lưu. Gói nằm trong danh sách thì bị từ chối nạp, kể cả khi gói đã nằm sẵn trong bộ đệm và chữ ký vẫn hợp lệ.
Bandum và Ryoma kiểm danh sách này khi khởi động (Bandum kiểm cả danh sách của tổ chức mình), còn ph tara list cảnh báo các bản bị thu hồi có trong lock của bạn.
Vuốt ngang để xem hết sơ đồ.
Một version đi qua những trạng thái nào?
| Trạng thái | Nghĩa | Cài được |
|---|---|---|
submitted, checking | Vừa gửi, đang kiểm tự động | Không |
checks_failed | Kiểm tự động có lỗi, cần gửi version mới | Không |
awaiting_review | Chờ platform staff (chỉ kho chính thức) | Không |
changes_requested | Bị trả lại kèm lý do | Không |
published | Đã qua kiểm tra (và duyệt, ở kho chính thức), ký và phát hành | Có |
deprecated | Ngừng hỗ trợ, ẩn khỏi kênh mới nhất, lock cũ vẫn dùng được | Có, kèm cảnh báo |
yanked | Thu hồi vì lỗi nghiêm trọng, vào danh sách thu hồi | Tải được, nhưng bên kiểm có khóa sẽ từ chối nạp |
rejected, removed | Phát hiện mã độc, gói bị xóa | Không |