Hợp đồng plugin
Phillip, Bandum và Ryoma không viết cứng GitHub, Telegram hay Jira. Mỗi kết nối như vậy là một kit phát hành trên Tara, và kit phải làm đúng hợp đồng của giao diện nó cung cấp. Trang này tả từng hợp đồng để bạn viết kit mới hoặc hiểu kit có sẵn đang làm gì.
Bảng tổng hợp
Bảng này sinh tự động từ tài liệu thiết kế plugin, nên luôn khớp với bản mới nhất.
Phần chung của mọi giao diện
Kit khai báo trong metadata.forge.phillip các trường provides, api, entry và credential. Từng trường nghĩa là gì, bạn xem ở Định dạng tài nguyên.
Kit không chứa bí mật và không đọc bí mật từ file. Bên gọi truyền token vào hàm connect() lúc kết nối, và kit chỉ nhận đúng phần của mình. Mỗi giao diện có số api riêng. Nếu kit khai báo api khác số lõi hỗ trợ, lõi từ chối nạp và hướng dẫn nâng cấp.
Gói kit bất biến, khóa theo sha256 và có chữ ký số. Trước khi phát hành hoặc đưa kit vào cấu hình dịch vụ, bạn nên chạy ph kit check. Lệnh này kiểm hợp đồng và các settings bắt buộc.
ph kit check ./kit-notify-teams
ph kit check kit-scm-github --liveKit đang viết dở trong thư mục thì bạn truyền đường dẫn như dòng đầu, kit đã có trên Tara thì truyền tên kit. Thêm --live thì lệnh gọi thật hàm me() (scm, tracker) hoặc check() (notify) bằng token đã lưu. Kit notify còn nhận --send "test" để gửi một thông báo thật. Token cho lệnh này chỉ nhận qua biến PHILLIP_KIT_TOKEN, không nhận qua tham số dòng lệnh để khỏi lọt vào lịch sử shell.
scm v1
Giao diện scm nối Phillip với nơi giữ mã nguồn và task, hiện là GitHub và GitLab. Kit khai báo matches là các host của remote origin mà nó phục vụ. Nếu dự án dùng GitHub Enterprise, bạn thêm host đó qua cấu hình của kit.
Module entry là file ESM không phụ thuộc gói ngoài, xuất api = 1 và hàm connect({ token, repo, settings }). Hàm này trả về đối tượng có các hàm của nhóm task như bảng dưới.
| Hàm | Việc |
|---|---|
me() | Trả login của chủ token |
issue(n), issues({ milestone }) | Đọc một task, hoặc liệt kê task cho board |
assign(n, login) | Giao task cho một người |
setStatus(n, s) | Đổi trạng thái sang in progress, review, approved hoặc rejected |
defaultBranch() | Tên nhánh mặc định của repo |
pullForIssue(n) | PR (GitLab là MR) của task, hoặc null |
createPull({ title, head, base, body }) | Mở PR |
review(pr, event, body, commit) | Duyệt, yêu cầu sửa hoặc bình luận trên PR |
comment(n, body) | Bình luận vào task |
Hai hàm tùy chọn là tokenInfo() và checks. ph connect gọi tokenInfo() để cảnh báo khi token thiếu quyền, và kit cũ không có hàm này thì lõi bỏ qua bước kiểm. Kit cũng có thể khai báo credential.tokenPrefixes để nhận thêm tiền tố token cá nhân hợp lệ ngoài những tiền tố lõi đã biết.
Lỗi mang mã trong ScmError.code để lõi xử lý giống nhau với mọi nhà cung cấp. Các mã là unauthorized, not_found, own_pull (không tự duyệt PR của mình) và conflict. Tên label status: … và mã GH-n là quy ước của Bandum nằm trong kit, nên GitLab có thể dùng scoped label mà lõi không phải đổi.
Nhóm khả năng
Kit khai báo capabilities trong metadata.forge.phillip, và bỏ trống nghĩa là chỉ có task. Thêm nhóm mới không đổi api, nên lõi cũ vẫn nạp được kit mới.
| Nhóm | Người gọi | Việc |
|---|---|---|
task | Phillip | Các hàm ở bảng trên |
report | Phillip, lệnh ph bandum bug | createIssue để báo bug ngoài phạm vi task, issuesByLabel để tìm issue trùng |
sync | Bandum và Ryoma | Đồng bộ bản sao task và ghi kết quả kiểm thử tay |
Nhóm sync gồm repoInfo, milestones, changes, events, pull, dirs, file và putFile. Bandum và Ryoma gọi các hàm đọc bằng token dịch vụ chỉ đọc. Còn khi người kiểm thử bấm Approve hoặc Send back trên web Bandum, các hàm ghi chạy bằng token của chính người bấm.
Kit SCM còn có thể kèm máy chủ MCP cho agent. Các công cụ đó nằm ở trang MCP tools.
notify v1
Giao diện notify gửi thông báo, ví dụ cảnh báo hạn mức của Ryoma hay bài gửi chờ duyệt của Tara. Kit không khai báo matches. Nhóm khả năng duy nhất là send.
Module entry xuất api = 1 và connect({ token, settings }), trả về đối tượng có hai hàm. check() kiểm tra token và đích gửi mà không gửi gì, rồi trả mô tả đích. send({ subject, text, to }) gửi thông báo, với to là email những người liên quan (kênh nhóm bỏ qua trường này).
Trong settings, mục nào có required: true là bắt buộc, và dịch vụ không khởi động nếu thiếu. Kit chạy được mà không cần bí mật, ví dụ SMTP nội bộ, thì khai báo credential.optional: true. Lỗi có bốn mã là unauthorized, not_found (không có đích gửi), unavailable (tạm thời, lần sau thử lại) và other. Thông báo lỗi không được chứa bí mật.
Tara có sẵn bốn kit: kit-notify-telegram, kit-notify-email, kit-notify-slack và kit-notify-zalo. Cách bật chúng cho dịch vụ nằm ở Thông báo. Zalo có vài giới hạn của chính Zalo OA, ghi trong README của kit.
tracker v1
Giao diện tracker cho dịch vụ đọc task từ hệ thống quản lý công việc không phải SCM, như Jira, trong khi mã nguồn vẫn nằm ở GitHub hoặc GitLab. Giao diện chỉ đọc và chỉ có nhóm task.
Dữ liệu trả về có hình dạng gần giống task của nhóm sync bên scm, nhờ vậy phần tính số liệu Flow dùng lại được mà không cần biết nhà cung cấp. Module entry xuất api = 1 và connect({ token, settings }), trong đó settings.project là khóa dự án và bắt buộc. Đối tượng trả về có năm hàm.
| Hàm | Việc |
|---|---|
me() | Định danh chủ token, cùng kiểu với assignees |
sprints() | Danh sách sprint, tương đương milestones() của scm |
tasks({ sprint, since }) | Task theo sprint, hoặc task cập nhật từ mốc since, cũ trước |
task(key) | Một task, có thêm phần mô tả bằng văn bản thuần |
events(key) | Lịch sử chuyển trạng thái |
Kit tự quy trạng thái của hệ thống task về bộ trạng thái của Bandum: todo, in progress, review, approved, rejected, done. Task thêm vào labels các nhãn dạng level: M và type: bug, nên phần mã đã đọc level: và type: từ label chạy tiếp mà không sửa. Lịch sử cũng được quy về đúng dạng event của scm (vào hay rời trạng thái là labeled hoặc unlabeled), để tính thời gian ở từng trạng thái và tỷ lệ làm lại như thường.
Tara kiểm kit tracker chặt hơn một chút: capabilities chỉ được có task, không có matches, và settings.project phải có required: true. kit-tracker-jira là kit có sẵn, dùng được với Jira Cloud lẫn Server hoặc Data Center.
guardrails
Kit chứa policy cho Guardrails khai báo khối metadata.forge.guardrails thay vì phillip.
"guardrails": { "schema": 1, "level": "company", "policy": "<đường dẫn file luật trong gói>" }level là company hoặc project, và policy trỏ tới file luật trong gói. Luật là dữ liệu chứ không phải code chạy: hook server của Guardrails đọc file này và tự đánh giá. Vì vậy bạn không cần viết module entry, cũng không có hàm nào để cài đặt.
Policy của nền tảng là mức sàn (mức company, chỉ nhân sự nền tảng được duyệt). Policy của tổ chức hoặc dự án chỉ được siết thêm, không được nới. Trước khi gửi gói lên Tara, bạn chạy ph guardrails check <thư mục gói>. Lệnh này kiểm định dạng luật và cho biết gói đang siết hay nới so với mức sàn.
Kit chạy ở đâu và được cách ly thế nào
Chỗ chạy khác nhau thì mức cách ly khác nhau.
Trên máy chủ, tức Tara, Bandum service và Ryoma, kit chạy trong một tiến trình Node.js riêng với node --permission, cần Node.js 22.13 trở lên. Kit chỉ đọc được thư mục plugin, không ghi được file, không chạy được tiến trình con và không thấy biến môi trường chứa bí mật của dịch vụ. Token và mật khẩu của kit đi qua connect(). Vì vậy kit nào cần ghi file hay chạy lệnh thì không chạy được trên máy chủ, bạn viết lại bằng API mạng. Quyền mạng của kit hiện chưa bị giới hạn.
Dịch vụ chỉ nạp kit đúng sha256 đã ghim, có chữ ký số hợp lệ và chưa nằm trong danh sách thu hồi. Chi tiết cách ký nằm ở Chữ ký số và thu hồi.
Trên máy bạn, Phillip nạp kit ngay trong tiến trình của bạn nên kit chạy với quyền của bạn và cầm token của bạn. Phillip chỉ nạp kit đã ký số từ kho riêng của bạn hoặc từ một tổ chức trên Tara, với sha256 khóa trong phillip.lock. Kit từ kênh cộng đồng thì Phillip không nạp. Phillip không ghi token vào log và rút gọn lỗi của kit trước khi in.