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

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ộcNhận
~1.2.0Chỉ bản vá, tức 1.2.x
^1.2Từ 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.0Mộ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.

json
{
  "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.

bash
ph tara install

Lệ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.

bash
ph tara keys

Trướ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ó.

bash
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.

Chuỗi tin cậy của chữ ký số. Khi người duyệt bấm Duyệt, Tara ký bản khai của gói. Khi thu hồi một version, Tara ký lại danh sách thu hồi. Phillip, Bandum và Ryoma kiểm chữ ký bằng khóa tin cậy do quản trị phát, kiểm thu hồi và đối chiếu sha256 trong phillip.lock trước khi nạp. Gói hợp lệ thì được nạp, ký sai hoặc đã thu hồi thì bị từ chối.TaraDuyệt và kýkhóa Ed25519,cùng lúc duyệtThu hồi và ký lạiký cả danh sách,serial tăng dầnGói và bản khaitên, version, sha256Danh sách thu hồicó ký, có serialTrước khi nạpPhillip, Bandum vàRyoma kiểm chữ ký,thu hồi, sha256khớp phillip.lockkhớp phillip.lockNạpgói hợp lệTừ chốiký sai hoặcđã thu hồiKhóa tin cậykhóa công khai do quản trị phát,không lấy từ Tara lúc kiểmphillip.lockkhóa version và sha256của từng tài nguyên

Vuốt ngang để xem hết sơ đồ.

Bên kiểm giữ sẵn khóa công khai và không lấy khóa từ Tara lúc kiểm. Vì vậy 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ý.

Một version đi qua những trạng thái nào? ​

Trạng tháiNghĩaCài được
submitted, checkingVừa gửi, đang kiểm tự độngKhông
checks_failedKiểm tự động có lỗi, cần gửi version mớiKhông
awaiting_reviewChờ platform staff (chỉ kho chính thức)Không
changes_requestedBị trả lại kèm lý doKhông
publishedĐã qua kiểm tra (và duyệt, ở kho chính thức), ký và phát hànhCó
deprecatedNgừng hỗ trợ, ẩn khỏi kênh mới nhất, lock cũ vẫn dùng đượcCó, kèm cảnh báo
yankedThu hồi vì lỗi nghiêm trọng, vào danh sách thu hồiTải được, nhưng bên kiểm có khóa sẽ từ chối nạp
rejected, removedPhát hiện mã độc, gói bị xóaKhông

Đọc thêm ​