Dùng trợ lý lập trình#

Theme Liquid là tệp văn bản trong một thư mục, check có đầu ra JSON và mã thoát, còn dev cho một URL đọc được. Trợ lý lập trình chạy được cả vòng lặp.

Trang này viết để đưa thẳng cho trợ lý. Nếu bạn là người, đọc Phát triển trên máy trước.

1. Chuẩn bị (người làm, một lần)#

Trợ lý không tự lấy được khoá API. Bạn làm §1–§2 của Phát triển trên máy: cài CLI, tạo khoá sk_live_… với quyền template.view + template.manage.

Đừng dán khoá vào khung chat. Đặt vào biến môi trường của shell mà trợ lý chạy lệnh: export XSTORE_API_KEY=sk_live_…. Mọi lệnh dưới đây đọc biến này. Khoá nằm trong lịch sử chat là khoá đã lộ — thu hồi tại Quản trị → Nhà phát triển → Khoá API.

Kéo theme về trước khi giao việc, để trợ lý có mã thật để đọc:

xstore theme pull --set <slug> --dir ./theme

2. Vòng lặp#

pull ──► sửa tệp ──► check --json ──► push ──► mở link xem thử
              ▲            │                          │
              └── có error ┘                          │
              └─────────── trang hỏng ────────────────┘

check chặn được lỗi cú pháp và tên sai. Chỉ bản xem thử mới chứng minh trang dựng được — xem §5.

3. Hợp đồng check --json#

xstore theme check --dir ./theme --json

{
  "findings": [
    {
      "slot": "product/detail.html",
      "line": 42,
      "severity": "error",
      "message": "Bộ lọc không tồn tại: money_usd",
      "code": "unknown_filter"
    }
  ],
  "liquid_check": "Liquid được kiểm tra về cấu trúc…"
}

Mã thoát 1 khi có bất kỳ finding nào severity: "error", 0 nếu không. Dùng mã thoát làm cổng, đừng parse văn bản người đọc.

check cần khoá API kể cả với --json: danh mục slot nằm trên máy chủ, không nằm trong gói.

4. Những cái tên KHÔNG được đoán#

xStore dựng Liquid bằng PHP keepsuit/liquid, không phải Shopify Liquid. Đoán theo thói quen Shopify là kiểu lỗi hay gặp nhất, và nó im lặng: biến không tồn tại dựng thành chuỗi rỗng, nên trang vẫn trả HTTP 200 và chỉ bị thiếu nội dung.

Danh sách bẫy đầy đủ nằm ở THEME-NOTES.md mà xstore theme init sinh ra. Bốn cái cắn nhiều nhất:

• Truthiness. Liquid chỉ coi nil và false là sai. Chuỗi rỗng, mảng rỗng và số 0 đều đúng — {% if items %} với mảng rỗng vẫn vào nhánh. Dùng {% if items.size > 0 %}, {% if v != '' %}, {% if n > 0 %}. == blank không hoạt động.
• Bộ lọc trên nil thì ném lỗi, và lỗi in thẳng vào body kèm HTTP 200. Bọc null guard quanh bộ lọc: {% if price %}{{ price | money_vnd }}{% else %}—{% endif %}.
• {% include %} dùng chung một scope. assign sống sót qua include, nên include cùng một component hai lần mà không gán lại biến thì lần thứ hai kế thừa giá trị lần đầu.
• Thiếu tệp slot là trang trắng, không phải lỗi 500.

Tên biến của từng trang tra ở Biến theo trang, đối tượng dữ liệu ở Đối tượng dữ liệu, bộ lọc ở Bộ lọc. Tra bảng, đừng đoán — đó là lý do các trang đó tồn tại.

5. Vì sao phải mở bản xem thử#

check đọc cấu trúc: thẻ cân đối, tên thẻ và bộ lọc có thật, slot hợp lệ, asset không quá lớn. Nó không dựng trang. Mọi lỗi ở §4 đều qua được check sạch sẽ.

Sau push, CLI in một link xem thử. Mở nó và kiểm tra có nội dung thật, không chỉ có HTTP 200 — trang chủ, một trang sản phẩm, một trang danh mục, giỏ hàng, tìm kiếm, một trang nội dung.

Nếu trợ lý của bạn dùng được trình duyệt (Playwright, MCP…), đây là việc đáng tự động: lấy link xem thử, mở từng đường dẫn, và khẳng định trang có văn bản nhìn thấy được cùng phần tử bạn mong đợi. Một trang trắng trả HTTP 200 — nên đừng dừng ở mã trạng thái.

6. Ranh giới#

• push và activate là hành động của người. push tạo bản nháp mà khách không thấy; activate đổi thứ khách đang xem. Đừng để trợ lý activate mà không hỏi.
• push từ chối bộ giao diện đang phục vụ khách — đó là lưới chắn cuối, không phải quy trình. Xuất bản thành slug nháp mới.
• Khoá API là bí mật. Không commit, không dán vào chat, không ghi vào tệp trong repo.
• Đừng sửa assets/* để "sửa" lỗi Liquid. Trang trắng gần như luôn là §4, không phải CSS.

7. Lời nhắc gọn để dán cho trợ lý#

Theme Liquid của xStore nằm ở ./theme. Máy dựng là PHP keepsuit/liquid, KHÔNG phải Shopify.

Vòng lặp:
  1. xstore theme check --dir ./theme --json   (mã thoát 1 = có error; rẽ nhánh theo .code)
  2. sửa slot mà finding chỉ ra
  3. lặp cho tới khi mã thoát 0
  4. xstore theme push --dir ./theme           (slug trong theme.json phải là bản nháp)
  5. mở link xem thử và kiểm tra có nội dung thật, không chỉ HTTP 200

Không được đoán:
  {{ content }} chứ không phải content_for_layout
  {{ store.* }} chứ không phải shop.*
  {{ 'x.css' | asset_url | stylesheet_tag }} — asset_url trước
  Liquid chỉ coi nil và false là sai: '' , [] , 0 đều đúng
  bộ lọc trên nil thì ném lỗi và in vào trang kèm HTTP 200

Đừng chạy `xstore theme activate` — hỏi tôi trước.
Đừng in hay ghi giá trị XSTORE_API_KEY ra đâu cả.