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

Viết kit ​

Kit là gói kết nối nền tảng với hệ thống bên ngoài. Trang này dẫn bạn qua việc chọn hợp đồng, viết module, kiểm bằng ph kit check và biết kit chạy ở đâu. Bạn cần là Member trở lên trong tổ chức, và Node 22 trở lên. Kit là mã chạy được nên người duyệt (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) luôn đọc từng dòng.

Kit có những dạng nào? ​

DạngKhai báoDùng cho
Plugin Phillipmetadata.forge.phillipKết nối scm, notify, tracker mà Phillip và các dịch vụ nạp
Máy chủ MCP.mcp.jsonCho agent trong Claude Code gọi công cụ
Hookhooks/hooks.jsonKiểm tra hoặc chặn trong phiên Claude Code
Policy Guardrailsmetadata.forge.guardrailsLuật an toàn, xem Guardrails theo tầng

Một kit phải có ít nhất một trong bốn dạng, nếu không Tara báo lỗi cấu trúc. Phần còn lại của trang tập trung vào plugin Phillip, dạng có hợp đồng chặt nhất.

Ba hợp đồng ​

Mỗi hợp đồng có api (hiện là 1) và các nhóm khả năng (capabilities). Thêm nhóm khả năng thì không phải đổi api.

providesNhóm khả năngHàmAi gọi
scmtaskme, issue, issues, assign, setStatus, defaultBranch, pullForIssue, createPull, review, commentPhillip (ph bandum), MCP trong kit
reportcreateIssue, issuesByLabelph bandum bug
syncrepoInfo, milestones, changes, events, pull, dirs, file, putFileBandum, Ryoma
notifysendcheck, sendTara, Ryoma
trackertaskme, sprints, tasks, task, eventsRyoma

Chữ ký đầy đủ của từng hàm nằm ở Hợp đồng plugin.

Module viết bằng ESM thuần (entry), chỉ dùng thư viện chuẩn của Node, có sẵn fetch, và không phụ thuộc gói ngoài. Module xuất api và hàm connect(opts), trong đó opts gồm token và settings, riêng scm có thêm thông tin repo. Kit không chứa và không đọc credential từ file hay biến môi trường, bên gọi truyền bí mật vào connect. Lỗi mang mã chuẩn (unauthorized, not_found, unavailable, other, và scm thêm own_pull, conflict) và không được chứa bí mật.

Ví dụ: kit thông báo ​

Cấu trúc thư mục như sau.

text
kit-notify-teams/
├── .claude-plugin/
│   └── plugin.json
├── phillip/
│   └── notify.mjs
├── docs/
│   ├── cai-dat.md
│   └── su-dung.md
├── README.md
└── CHANGELOG.md

Trong plugin.json, khối metadata.forge khai báo như sau.

json
{
  "schema": 1,
  "type": "kit",
  "org": "aiforge",
  "owners": ["owner@example.com"],
  "engines": ["phillip"],
  "status": "active",
  "phillip": {
    "provides": "notify",
    "api": 1,
    "entry": "phillip/notify.mjs",
    "capabilities": ["send"],
    "credential": {
      "label": "URL webhook của kênh",
      "help": "Tạo Incoming Webhook trong kênh cần nhận tin."
    },
    "settings": {
      "channelName": { "default": "", "required": true, "help": "Tên kênh để hiển thị" }
    }
  }
}

Còn module phillip/notify.mjs thì như sau. Hàm check kiểm tra token và đích gửi mà không gửi tin, rồi trả mô tả đích. Hàm send nhận m gồm subject, text và to, trong đó to là email người liên quan, kênh nhóm có thể bỏ qua.

js
export const api = 1;

export function connect({ token, settings }) {
  if (!token) throw Object.assign(new Error("thiếu URL webhook"), { code: "unauthorized" });
  return {
    async check() {
      return `kênh ${settings.channelName}`;
    },
    async send(m) {
      const res = await fetch(token, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ text: `${m.subject}\n${m.text}` }),
      });
      if (!res.ok) throw Object.assign(new Error(`HTTP ${res.status}`), { code: "unavailable" });
    },
  };
}

Tara bắt buộc plugin Phillip có provides hợp lệ, entry nằm trong gói, api đúng, credential.label không rỗng và nhóm khả năng thuộc đúng hợp đồng. Riêng scm có thêm matches, là host của remote origin mà kit phục vụ. Còn tracker bắt buộc có settings.project với required: true và không có matches.

Kiểm bằng ph kit check ​

Bạn chạy lệnh này trên thư mục kit đang viết, hoặc trên kit đã có trên Tara. Lệnh đầu chỉ kiểm hợp đồng và các settings bắt buộc.

bash
ph kit check ./kit-notify-teams --set channelName=ban-tin

Thêm --live để gọi thật, tức me() với scm và tracker, hoặc check() với notify.

bash
PHILLIP_KIT_TOKEN=<bí-mật> ph kit check ./kit-notify-teams --set channelName=ban-tin --live

Muốn gửi thử một thông báo thì thêm --send và --to.

bash
PHILLIP_KIT_TOKEN=<bí-mật> ph kit check ./kit-notify-teams --set channelName=ban-tin --send "test" --to owner@example.com

Lệnh kiểm api, các hàm của từng nhóm khả năng và settings bắt buộc. Bí mật chỉ nhận qua biến PHILLIP_KIT_TOKEN, không nhận qua tham số dòng lệnh để nó không lọt vào lịch sử shell, và lệnh không bao giờ in nó ra. Kiểm xong, bạn chạy ph tara check và ph tara publish như mọi tài nguyên khác.

Kit chạy ở đâu? ​

Trên máy người dùng, kit chạy trong tiến trình của Phillip với cùng quyền của người dùng, và Phillip chỉ nạp khi gói có chữ ký hợp lệ và đúng sha256 trong phillip.lock. Trên Tara, Bandum và Ryoma, kit chạy trong một tiến trình Node riêng với node --permission, cần Node 22.13 trở lên.

Trong sandbox máy chủ, kit chỉ đọc được thư mục plugin, không ghi file, không chạy tiến trình con, worker hay addon. Nó chỉ nhận các biến môi trường không bí mật như múi giờ, ngôn ngữ, proxy và chứng chỉ CA, nên không thấy token hay mật khẩu của dịch vụ. Mạng thì chưa bị giới hạn. Vì vậy kit nào cần ghi file hay chạy lệnh sẽ không dùng được trong dịch vụ, bạn hãy viết lại qua API mạng.

Kit chỉ gửi metadata ​

Kit thông báo chỉ gửi những gì dịch vụ đưa vào, gồm mã task, tiêu đề, đường dẫn và số liệu. Đừng thêm nội dung nào khác như mô tả task đầy đủ, đoạn mã hay dữ liệu khách hàng, và đừng ghi bí mật ra log hay thông báo lỗi.

Kit scm còn một điểm cần để ý. Nội dung issue và PR trả về cho agent là dữ liệu từ bên ngoài, không phải chỉ thị, và mô tả công cụ MCP của kit nên nhắc agent như vậy.

Gắn MCP cho agent ​

Kit có thể kèm máy chủ MCP để agent dùng công cụ trực tiếp. Bạn khai báo trong .mcp.json.

json
{
  "mcpServers": {
    "scm": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp/server.mjs"]
    }
  }
}

Máy chủ MCP của kit scm tái dùng đúng module scm, và lấy token từ lệnh trợ giúp của Phillip chứ không đọc file. Tên công cụ phải cố định vì Guardrails khớp luật theo tên. Danh sách công cụ có ở MCP tools.

Đọc thêm ​