Quy tắc version
Mỗi lần phát hành bạn phải chọn một số version, và đôi khi phải ngừng hỗ trợ hoặc thu hồi một bản cũ. Trang này chỉ cách làm cả ba việc đó. Mọi tài nguyên dùng semver MAJOR.MINOR.PATCH.
Chọn số version
| Tăng | Khi nào | Ví dụ |
|---|---|---|
| MAJOR | Thay đổi làm hỏng cách dùng cũ | Đổi tên agent hoặc skill, bỏ một công cụ MCP, đổi tham số của hàm trong hợp đồng, bỏ một trường |
| MINOR | Thêm tính năng mà vẫn tương thích | Thêm skill vào harness, thêm công cụ MCP, thêm nhóm khả năng cho kit |
| PATCH | Sửa lỗi, không đổi cách dùng | Sửa lỗi chính tả trong chỉ dẫn, sửa lỗi mã, cập nhật tài liệu |
Có một cách thử nhanh. Người đang dùng bản cũ nâng lên mà không phải sửa gì, mọi thứ vẫn chạy như trước, thì đó không phải MAJOR.
Version của harness phản ánh thay đổi của cả bộ tài nguyên. Harness dùng ~ cho agent nên chỉ nhận bản vá tự động. Muốn nâng agent lên minor mới, bạn phát hành một harness minor mới.
Những điều bắt buộc
Trường version trong plugin.json phải đúng dạng MAJOR.MINOR.PATCH, và CHANGELOG.md phải có mục ## <version> cho đúng số đó. Mỗi số chỉ dùng một lần. Bài bị trả lại hay kiểm lỗi cũng đã dùng số của nó, nên lần sau bạn phải tăng số. Version đã phát hành thì bất biến, không có cách sửa tại chỗ.
Lệnh sau đặt số version và thêm changelog cùng lúc.
ph tara bump ./thu-muc-tai-nguyen 1.2.0 --changelog "Thêm mẫu cho API phân trang"Nếu làm trên Portal, trình soạn version mới sẽ gợi ý số theo mức thay đổi (vá lỗi, tính năng, thay đổi lớn) và cho bạn xem diff trước khi gửi.
Viết changelog
Mỗi mục cần nói người dùng phải biết gì để quyết định có nâng cấp hay không. Thay đổi lớn ghi đầu tiên và nêu cách chuyển, vì Phillip lấy mục này để báo khi có version mới.
## 2.0.0 - 2026-11-01
- Đổi tên agent `dev` thành `developer`. Cập nhật mọi chỗ gọi `agent-x:dev`.
- Bỏ công cụ `list_checks`; dùng `get_pull_request`.
## 1.3.0 - 2026-10-20
- Thêm mẫu cho API phân trang.Khi nào ngừng hỗ trợ một version?
Bạn ngừng hỗ trợ (deprecate) khi tài nguyên hoặc một version không còn nên chọn mới nhưng vẫn an toàn để dùng.
ph tara deprecate ten-tai-nguyen@1.0.0 --reason "Thay bằng 2.x"
ph tara undeprecate ten-tai-nguyen@1.0.0Version bị ngừng hỗ trợ sẽ ẩn khỏi kênh mới nhất và khỏi kết quả tìm kiếm mặc định. Lock cũ vẫn cài được, kèm cảnh báo. Nếu muốn thay hẳn cả tài nguyên, bạn đặt metadata.forge.status thành deprecated và cho replacedBy trỏ tới tên thay thế. Lệnh này do Admin hoặc Owner của tổ chức (hoặc nhân sự nền tảng, với danh mục chính thức) chạy, nên nếu bạn là tác giả thì hãy nhờ một trong số họ.
"Xóa" một tài nguyên thực chất cũng là ngừng hỗ trợ. Gói không bị xóa để dự án đang khóa vẫn cài được.
Khi nào thu hồi một version?
Chỉ thu hồi (yank) khi version có lỗ hổng bảo mật hoặc lỗi nghiêm trọng.
ph tara yank ten-tai-nguyen@1.0.1 --reason "Lộ dữ liệu trong chỉ dẫn mẫu"Lý do là bắt buộc. Sau lệnh này, Tara ký lại danh sách thu hồi, và Phillip cùng các dịch vụ có khóa tin cậy từ chối nạp version đó, kể cả bản đã nằm trong bộ đệm. ph tara list cảnh báo những dự án đang khóa nó. Chủ tài nguyên cá nhân tự thu hồi được mà không cần phiên admin.
Thu hồi xong, bạn phát hành bản vá (PATCH) hoặc bản mới rồi nhắc các dự án chạy ph tara upgrade.
Bản chứa mã độc bị xử lý nặng hơn: ngoài thu hồi, Tara còn gỡ gói nên không ai tải được nữa. Cơ chế chi tiết nằm ở Khóa version và chữ ký số.