Dùng với AI agent

Mở project trong agent

Mở thư mục project (thư mục có webmati.toml) trong agent. clone đã viết sẵn hướng dẫn mà mọi coding agent đều đọc. Claude Code, Cursor và Codex đọc file gần với phần code chúng sửa nhất:

• AGENTS.md — một playbook, không phải sách hướng dẫn:
  • thông tin nằm ở đâu: mọi thứ agent cần đều ở .webmati/; agent đọc .webmati/reference/index.md trước khi tự đặt ra một cái tên, và báo bạn khi thiếu thứ nó cần thay vì đoán;
  • cách bắt đầu một phiên: webmati pull, webmati status, đọc .webmati/reference/site.md, đọc skill của việc cần làm, và hỏi bạn thế nào là "xong" khi yêu cầu còn mơ hồ;
  • bảng việc: với đổi màu, thêm section trang chủ, tạo loại section mới, thêm trang, header, bản dịch, chuyển hướng, ảnh, workflow, bảng dữ liệu, secret, tên miền và website mới, bảng ghi rõ file cần sửa, mục skill phải đọc trước, điều không được làm và cách kiểm tra;
  • tên các tool của nền tảng, đối chiếu với file trong thư mục;
  • luật cứng: không publish, không đẩy thay đổi live, không xoá gì nếu bạn không yêu cầu đúng việc đó; validate về 0 lỗi trước mỗi lần push; không nới lỏng bảo mật để cho chạy được; làm từng phần nhỏ;
  • thế nào là xong;
  • bốn ví dụ làm từ đầu đến cuối: thêm section cảm nhận khách hàng vào trang chủ, workflow form liên hệ ở POST /contact, đổi màu thương hiệu, một app React trên một trang.
• theme/AGENTS.md: luật section và schema, class màu, settings_data.json, kế thừa theme, một section mẫu, đặt tên và bảo mật.
• backend/AGENTS.md: đồ thị workflow, luật code node, bảng dữ liệu và thay đổi live, đặt tên, một danh sách kiểm tra bảo mật và test bằng fixtures.
• Một CLAUDE.md cạnh mỗi file, trỏ Claude Code tới đúng file đó.

Các playbook của chính nền tảng (các skill mà MCP của nền tảng phục vụ) đi kèm project trong .webmati/skills/, có index.md, để agent theo đúng luật mà trợ lý của nền tảng theo. webmati pull cập nhật những skill đã đổi trên server:

webmati skills                          # xem danh sách
webmati skills --refresh                # lấy bản mới nhất từ server ngay
webmati skills --update-instructions    # đề xuất các file AGENTS.md mới hơn của CLI, kèm diff

clone không bao giờ ghi đè AGENTS.md bạn đã sửa. --update-instructions hiện diff và chỉ thay file khi bạn đồng ý (--yes cho script).

Tài liệu tra cứu: .webmati/reference

Skill nói cách làm; .webmati/reference/ nói cái gì đang có, để agent không phải đoán một biến, một setting hay một cột. Mọi file đều sinh ra từ chính các tool của nền tảng và từ project, nên đúng với website này:

webmati pull và webmati skills --refresh viết lại thư mục này. Khi một tool không trả lời, bản cũ được giữ lại và index.md ghi rõ điều đó. Giống các skill, thư mục này là của riêng máy bạn và không đưa vào git.

Đặt tên và bảo mật

Mỗi AGENTS.md trong theme/ và backend/ có mục Naming gồm hai nửa. Nửa bắt buộc được in ra từ chính các bộ kiểm tra của nền tảng: mẫu cho mã bảng, cột, workflow, route và biến, đường dẫn file theme, loại section, id setting, template, loại nội dung và slug trang. Nửa còn lại là quy ước, ghi rõ là quy ước: tên bảng snake_case số nhiều, mã workflow dạng động_từ_danh_từ (create_order), route chữ thường và mỗi route một workflow, loại section dạng kebab-case.

backend/AGENTS.md kết thúc bằng danh sách kiểm tra bảo mật (chế độ xác thực, quyền sở hữu dòng dữ liệu, kiểm tra input, secret, webhook, gọi ra ngoài, SQL, file, realtime, key), mỗi mục trỏ tới mục skill giải thích nó. theme/AGENTS.md thêm phần của theme: file theme là công khai, storefront không tự escape output, và không thêm script bên thứ ba khi bạn chưa đồng ý.

webmati validate cảnh báo những lỗi nhìn thấy rõ trong file, và không bao giờ chặn vì chúng: quy ước đặt tên không được theo, route public ghi dữ liệu mà không kiểm tra input, email gửi tới địa chỉ lấy từ request, chuỗi trông như secret trong code node, file theme hay biến, và input của khách in ra trong Liquid mà không có | escape.

Sau đó chỉ cần giao việc: "đổi màu nút ở section hero, validate, push lên bản nháp và gửi mình link xem trước". Agent sẽ báo đã đổi gì, link xem trước, và những gì còn chờ bạn đồng ý (publish, thay đổi live).

Gọi tool của platform từ shell

Mọi tool của platform (sản phẩm, trang, content, thống kê, backend…) gọi được thẳng từ shell, JSON vào và JSON ra:

webmati tool list pages                    # tìm tool theo từ khoá
webmati tool describe list_pages           # tham số, kiểu kết quả, ví dụ
webmati tool call list_pages --json '{}'   # gọi

--select giữ lại đúng phần cần, trước khi kết quả tới agent: đây là cách tiết kiệm token lớn nhất. Cú pháp là một phần của jq:

webmati tool call list_pages --json '{}' --select '.storePages[] | {id, slug, title}'
webmati tool call list_pages --json '{}' --select '.storePages | length'
webmati tool call list_pages --json '{}' --select '.storePages[] | select(.status == "draft") | .slug'
webmati tool call list_backend_tables --json '{}' --select '.backendTables[] | {id, code, label}'
webmati tool call get_context --json '{}' --select '{store_id, theme_id}'

Hỗ trợ: .a, ."khoá lạ", .[0], .[-1], .[1:3], .[], .., ?, |, ,, {a, b: biểu_thức}, [biểu_thức], length, keys, first, map(…), select(…) với == != < <= > >=, and, or và ngoặc.

Tham số dài thì để trong file (--json @args.json) hoặc đưa qua stdin (--json -). Mỗi lần gọi được ghi vào .webmati/logs/tools.jsonl.

Tài liệu tool dạng file: .webmati/sdk

webmati sdk

viết .webmati/sdk/index.md cùng một file .md và một .d.ts cho từng tool. Agent đọc mục lục trước, rồi chỉ mở tool nó cần, thay vì nạp cả danh sách tool vào ngữ cảnh. Project tải từ zip đã có sẵn thư mục này.

Code mode: webmati exec

Một script TypeScript gọi nhiều tool một lúc, và chỉ giá trị nó return được in ra:

// draft-pages.ts — script là thân của một hàm async: dùng await, return kết quả
const r = await webmati.list_pages({});
const drafts = r.storePages.filter((p) => p.status === "draft");
return drafts.map((p) => ({ id: p.id, slug: p.slug }));

webmati exec draft-pages.ts

Gọi tool theo tên: await webmati.call("get_context", {}). Script chạy trong một tiến trình riêng, không bao giờ thấy key, không có fetch, import hay hệ thống file. Mặc định nó chỉ đọc:

Mỗi lần chạy ghi nhật ký vào .webmati/logs/exec-<thời điểm>.jsonl. Đưa script qua stdin bằng webmati exec -.

MCP gọn: webmati mcp

Với agent muốn dùng tool MCP thay vì shell, webmati mcp phục vụ một MCP chỉ có 8 tool trên stdio:

search_tools  describe_tool  call_tool  execute  status  pull  push  validate

Danh sách tool nhỏ hơn 97,4% so với MCP đầy đủ (182 tool); agent tìm tool khi cần (search_tools, describe_tool) rồi gọi (call_tool có selector, execute chạy một script code mode). Tự đo:

webmati mcp --measure

Thêm vào Claude Code: chạy trong thư mục project:

claude mcp add webmati-local -- webmati mcp

Thêm vào Cursor: .cursor/mcp.json trong thư mục project:

{
  "mcpServers": {
    "webmati-local": { "command": "webmati", "args": ["mcp"] }
  }
}

MCP này làm việc với project ở thư mục hiện tại; bốn tool status, pull, push, validate chỉ có khi nó được chạy bên trong một project. Muốn cố định một project, dùng webmati --dir /đường/dẫn/my-shop mcp.

• webmati mcp --full phục vụ toàn bộ tool (như MCP của platform), qua key của CLI.
• Lệnh xoá, publish, restore được hỏi lại trước; --allow-destructive cho chúng qua không hỏi.