Tạo ứng dụng, cho các tác tử

Cách tác tử tạo ứng dụng Laze mà mọi người muốn dùng: quy tắc thiết kế, bộ công cụ, ghim và chia sẻ, đẩy lên trunk và tự kiểm tra việc của mình.

Trang này dành cho một tác tử AI được yêu cầu tạo hoặc thay đổi một ứng dụng Laze. Hãy đọc trước laze app create đầu tiên của bạn. Mọi người đánh giá một ứng dụng trong năm giây đầu tiên: làm cho ứng dụng trông hoàn chỉnh, đặt đúng nơi họ yêu cầu và tự kiểm tra trước khi nói rằng ứng dụng đã sẵn sàng.

Quy trình làm việc

Tạo ứng dụng trong cuộc trò chuyện đã yêu cầu:
```
laze app create "Insights" --channel <channel>
```
Ứng dụng bắt đầu trống, với một thư mục của riêng bạn: xây dựng từ đầu, bắt đầu tại index.html, rồi laze app push. --channel ghim ứng dụng thành một tab của cuộc trò chuyện đó. Mọi người trong đó, và tác tử của họ, có thể mở ứng dụng và xây tiếp trên đó (Người tạo). Đặt tên ứng dụng bằng từ ngữ mọi người đọc được, không phải một slug.

Liên kết bộ kit nền tảng và client từ trang của bạn:
```
<link rel="stylesheet" href="/_laze/theme.css" />
<link rel="stylesheet" href="/_laze/kit.css" />
<script src="/_laze/laze.js"></script>
```
Trang chiếu, một bộ slide hoặc một bài thuyết trình là ngoại lệ duy nhất: chúng bắt đầu từ --template slides, mẫu duy nhất. Các tệp của mẫu là phiên bản live đầu tiên của ứng dụng, thuộc về bạn để thay đổi. Mỗi trang chiếu là một tệp trong slides/, được liệt kê theo thứ tự trong slides/deck.json; README.md của mẫu nói cách thêm, sắp xếp lại và tạo kiểu cho trang chiếu. Bộ slide có thanh trang chiếu, điều hướng bằng bàn phím, Present toàn màn hình, và các nút Export PDF và Export HTML, nên đừng xây lại các phần đó. Qua MCP, create_app với template: "slides" làm cùng việc, và write_app_files thay đổi từng trang chiếu một.

Mẫu trang chiếu chỉ dành cho một bộ slide mới. Khi một người gửi các tệp vốn đã là một trang hoặc một bộ slide (một bản xuất HTML, một tệp zip có index.html, một site tĩnh), hãy đưa chúng lên đúng như vậy: tạo ứng dụng không có --template, giải nén các tệp vào thư mục của ứng dụng với index.html ở cấp trên cùng, sao chép vào mọi script mà nó tải từ CDN, rồi đẩy lên. “Di chuyển chúng vào đây” hoặc “đặt cái này ở đây” kèm tệp đính kèm có nghĩa đúng như vậy: hãy làm, đừng hỏi ý nghĩa là gì.
Một ứng dụng đã tồn tại sẽ được đưa vào cuộc trò chuyện bằng một ghim, không phải một tin nhắn có liên kết:
```
laze app pin <app> --channel <channel>
```
--role editor cho phép thành viên thay đổi dữ liệu nhưng không thay đổi mã, --view-only chỉ cho phép họ xem. laze app pins <channel> liệt kê các tab. Đừng bao giờ ghim lại một ứng dụng mà một người đã bỏ ghim.
Định hình dữ liệu trong laze.app.json: mỗi loại thứ dùng một collection, với trường có kiểu và vài bản ghi mẫu. Dữ liệu nằm trong bản ghi, không bao giờ nằm trong mã của trang. Một trang mã hóa cứng số liệu, hàng hoặc văn bản là sai: khi dữ liệu thay đổi, ứng dụng phải thay đổi mà không cần đẩy lên.
Thay đổi trang, rồi xem cục bộ trước khi đưa live (xem Tự kiểm tra công việc).
Đẩy lên:
```
laze app push -m "Added the pipeline board" --seed
```
Mỗi lần đẩy lên lập tức là ứng dụng live. Không có bản nháp, nhánh hay pull request: ứng dụng dùng mô hình trunk-based. Viết thông điệp như một câu đơn giản về điều đã thay đổi cho mọi người. --seed chỉ điền các collection chưa có bản ghi.
Quay lại khi một lần đẩy lên bị sai: laze app versions, rồi laze app revert <version> -m "<why>". Đó là một phiên bản live mới; không bản ghi nào bị mất. Lịch sử git bên trong ứng dụng chỉ dùng cho việc này.

Ai có thể mở ứng dụng

Phạm vi hiển thị	Ai mở được
Bị hạn chế	Người, tác tử và cuộc trò chuyện được chia sẻ hoặc được ghim ứng dụng, cộng với Chủ sở hữu và Admin của không gian làm việc
Kênh	Thành viên trong kênh của ứng dụng
Nội bộ	Mọi người trong không gian làm việc
Công khai	Bất kỳ ai có địa chỉ

Ứng dụng mới có phạm vi Bị hạn chế. Ứng dụng được ghim trong một cuộc trò chuyện sẽ mở được cho mọi người ở đó, nên một ghim thường là toàn bộ phần chia sẻ mà ứng dụng nhóm cần. Đừng chia sẻ ứng dụng chỉ với người đã yêu cầu khi họ yêu cầu ứng dụng trong một kênh: hãy ghim ứng dụng ở đó. Mở rộng bằng laze app access visibility internal|public chỉ khi được yêu cầu; lệnh sẽ cho biết khi nào admin phải phê duyệt. laze app members cho biết ai có thể mở ứng dụng ngay bây giờ. Hãy kiểm tra trước khi bạn nói với mọi người rằng ứng dụng đã sẵn sàng.

Quy tắc thiết kế

Bắt đầu từ nội dung của ứng dụng, không phải từ bố cục. Hãy hỏi một người quan tâm đến chủ đề đó sẽ vẽ nó trên bảng trắng như thế nào, rồi xây theo đó: mô hình mối đe dọa là bản đồ tấn công, lộ trình là dòng thời gian, ngân sách là luồng tiền, quy trình là sơ đồ. Một trang gồm các ô thống kê và danh sách gạch đầu dòng trông như báo cáo, và đó là kiểu ứng dụng cần tránh.

Hãy thật trực quan: dùng đồ họa chuyển động và sơ đồ luồng bất cứ khi nào có thể, và dẫn dắt mọi người từng bước một cho đến khi họ hiểu hết. Đừng bao giờ viết những bức tường chữ: chỗ nào cần chữ, hãy dùng câu đơn giản và ngắn. Ứng dụng là để mọi người hiểu, không phải để bạn trút hết những gì trong đầu.

Bộ kit Laze đến từ nền tảng (/_laze/theme.css, /_laze/kit.css, /_laze/laze.js). Đây là hộp công cụ, không phải bố cục để điền vào: lấy token và điều khiển bạn cần, rồi đặt CSS riêng của bạn trong tệp riêng phía trên. Đừng bao giờ sao chép bộ kit vào ứng dụng.

Ưu tiên hình ảnh. Biến hình ảnh của chủ đề thành chính ứng dụng: SVG inline, canvas, bản đồ, dòng thời gian, sơ đồ, hoặc thứ gì đó mọi người bấm vào và khám phá. Tạo diện mạo riêng cho nó, với bố cục và chuyển động của bạn trên các token của bộ kit.
Mỗi màn hình một việc. Màn hình đầu tiên trả lời câu hỏi mà ứng dụng tồn tại để giải quyết. Đặt việc thứ hai vào một tab (lz-tabs), không đặt bên dưới việc đầu tiên.
Đúng hình dạng. Dùng bảng (lz-table) hoặc bảng công việc (lz-board) khi mọi người quét hoặc di chuyển các hàng, ô thống kê (lz-stats, lz-stat-value) khi một con số là điểm chính, biểu đồ (lz-chart) cho số liệu theo thời gian và các bước được đánh số (lz-steps) cho một chuỗi ngắn. Văn bản dài hơn ba dòng thuộc về tài liệu, không phải ứng dụng.
Dữ liệu thật. Hiển thị các bản ghi mà mọi người quan tâm, với tên và ngày thật. Không dùng “Lorem”, “Item 1” hay biểu đồ giữ chỗ. Mọi khẳng định trên trang đều đến từ một bản ghi hoặc một liên kết.
Thang chữ. Một tiêu đề trang (lz-title), một dòng bên dưới (lz-lede), tiêu đề phần (lz-h2 hoặc lz-card-title), văn bản nội dung. Đừng thêm cỡ chữ khác.
Khoảng cách. Dùng các lớp page (lz-page), card (lz-card lz-card-body) và grid (lz-grid, lz-row); chúng giữ nhịp 12 đến 20 px. Đừng xếp thẻ bên trong thẻ.
Cả hai theme. Màu chỉ đến từ token (var(--color-fg), var(--color-bg-surface), var(--color-primary), var(--color-border) và các tông lz-badge-*). Màu hex làm hỏng chế độ tối.
Chiều rộng hẹp. Ứng dụng mở trong bảng bên rộng khoảng 380 px. Gán data-label cho ô bảng để hàng có thể xếp chồng, và giữ tiêu đề trên một dòng.
Trạng thái trống và lỗi. Danh sách trống nói điều gì sẽ xuất hiện và cách thêm mục đầu tiên. Lệnh gọi thất bại hiển thị Laze.fail(error), không bao giờ là trang trống.
Trạng thái dùng huy hiệu. Hiển thị trạng thái bằng lz-badge và một tông (-success, -warning, -danger, -info, -primary), không dùng văn bản có màu.
Biểu mẫu không cản đường. Đặt “Mục mới” sau một nút; danh sách là nội dung chính.

Tham chiếu bộ kit

Nhu cầu	Lớp
Trang và tiêu đề	`lz-page`, `lz-header`, `lz-title`, `lz-lede`
Bố cục	`lz-row`, `lz-grow`, `lz-grid`, `lz-stats`
Thẻ	`lz-card`, `lz-card-body`, `lz-card-title`, `lz-h2`
Bảng	`lz-table-wrap`, `lz-table`, `lz-num` (số căn phải)
Bảng công việc	`lz-board`, `lz-column`, `lz-column-head`, `lz-tile`
Số liệu	`lz-stat-value`, `lz-chart`, `lz-chart-col`, `lz-chart-track`, `lz-chart-bar`, `lz-chart-value`, `lz-chart-label`
Các bước	`ol.lz-steps` với một `li` cho mỗi bước
Điều khiển	`lz-btn`, `lz-btn-primary`, `lz-btn-ghost`, `lz-input`, `lz-select`, `lz-textarea`, `lz-field`, `lz-form`, `lz-tabs`, `lz-tab`
Trạng thái	`lz-badge` (+ tông), `lz-callout`, `lz-empty`, `lz-muted`

Script chỉ tải từ origin của chính ứng dụng: CDN <script> sẽ bị từ chối, nên hãy sao chép thư viện bạn cần vào thư mục ứng dụng. Khi chuyển một artifact claude.ai hoặc một trang React khác, hãy biên dịch JSX của nó trước khi đẩy lên (ví dụ npx esbuild app.jsx --bundle --minify --outfile=app.js) và liên kết tệp đã build. Babel trong trình duyệt cũng hoạt động, nhưng nó tải hàng megabyte mỗi lần mở.

Trong script của trang, Laze.records("<collection>") liệt kê, tạo, cập nhật và xóa bản ghi, Laze.subscribe tải lại khi có thay đổi, Laze.h tạo phần tử và Laze.mount vẽ chúng.

Phím tắt

Laze chuyển các phím tắt của chính Laze từ ứng dụng của bạn sang Laze, trừ khi ứng dụng của bạn xử lý chúng, để mọi người có thể nhấn Cmd+K (Ctrl+K trên Windows và Linux) để rời ứng dụng mà không cần bấm ra ngoài trước. Các phím tắt được chuyển tiếp là Cmd+K, Cmd+[ và Cmd+], Cmd+1 đến Cmd+9, Cmd+Shift+A, Cmd+Shift+T, Cmd+Shift+M, Cmd+Shift+D, Cmd+. và Cmd+/, cộng với Alt+Up và Alt+Down bên ngoài trường văn bản. Mọi phím khác ở lại trong ứng dụng của bạn.

Để giữ một trong các phím này cho ứng dụng của bạn, hãy xử lý phím đó và gọi event.preventDefault(); khi đó Laze sẽ để yên:

document.addEventListener("keydown", (event) => {
  if ((event.metaKey || event.ctrlKey) && event.key === "k") {
    event.preventDefault();
    openSearch();
  }
});

Tự kiểm tra công việc

Xem mọi thay đổi trước khi bạn đẩy lên:

laze app serve --port 4173

Lệnh này phục vụ thư mục của bạn tại http://127.0.0.1:4173/ với bộ kit nền tảng và các bản ghi của ứng dụng live, ở chế độ chỉ đọc. Nó cần một phiên bản live, nên trước tiên hãy chạy laze app push một lần. Mở bằng công cụ trình duyệt của bạn và chụp màn hình ở cả hai theme và ở chiều rộng bảng, ví dụ:

npx -y playwright install chromium   # once
npx -y playwright screenshot --viewport-size=1100,800 http://127.0.0.1:4173/ light.png
npx -y playwright screenshot --viewport-size=1100,800 "http://127.0.0.1:4173/?theme=dark" dark.png
npx -y playwright screenshot --viewport-size=390,800 http://127.0.0.1:4173/ narrow.png

Xem từng ảnh. Sửa văn bản bị tràn, cột không vừa, màu biến mất trong chế độ tối và mọi thứ vẫn còn ghi “demo”.

Trước khi bạn đăng ứng dụng:

Ứng dụng được ghim đúng nơi đã được yêu cầu, và laze app members liệt kê những người cần mở được ứng dụng.
Màn hình đầu tiên trả lời yêu cầu mà không cần cuộn.
Ảnh chụp sáng, tối và 390 px trông hoàn chỉnh.
Tin nhắn của bạn nêu tên ứng dụng và một dòng về việc ứng dụng làm gì. Tab trong cuộc trò chuyện là liên kết.

Hỏi khi không chắc

Hãy hỏi người đó một câu hỏi ngắn thay vì xây nhầm thứ. Đừng chờ một lời “làm đi” cho các bước họ đã yêu cầu rồi: nếu họ yêu cầu một ứng dụng trong kênh này, hãy tạo ở đó, ghim và cho họ biết.

Tạo ứng dụng, cho các tác tử

Quy trình làm việc#

Ai có thể mở ứng dụng#

Quy tắc thiết kế#

Tham chiếu bộ kit#

Phím tắt#

Tự kiểm tra công việc#

Hỏi khi không chắc#