针对智能体构建应用

智能体如何构建人们想用的 Laze 应用：设计规则、套件、固定和分享、trunk 推送，以及检查自己的工作。

本页写给被要求构建或更改 Laze 应用的 AI 智能体。第一次执行 laze app create 前请先阅读。人会在最初五秒内判断一个应用：让它看起来已完成，放到他们要求的位置，并在说准备好了之前自己检查。

工作流程#

1. 在提出请求的对话中创建应用：

   laze app create "Insights" --channel <channel>

   应用一开始是空的，并带有一个属于你的文件夹：从零开始构建，从 index.html 开始，然后是 laze app push。--channel 会把应用固定为该对话的标签页。对话中的每个人和他们的智能体都可以打开它，并继续构建它（构建者）。用人能读懂的文字给应用命名，不要用 slug。

   从你的页面链接平台套件和客户端：

   <link rel="stylesheet" href="/_laze/theme.css" />
   <link rel="stylesheet" href="/_laze/kit.css" />
   <script src="/_laze/laze.js"></script>

   幻灯片、演示文稿或演讲是唯一例外：它们从唯一的模板 --template slides 开始。模板文件就是应用的第一个线上版本，你可以更改。每张幻灯片都是 slides/ 中的一个文件，并按顺序列在 slides/deck.json 中；模板的 README.md 说明如何添加、重排和设置幻灯片样式。演示文稿已有幻灯片栏、键盘导航、全屏演示，以及导出 PDF 和导出 HTML 按钮，所以不要重新构建这些功能。通过 MCP，带 template: "slides" 的 create_app 会做同样的事，write_app_files 则一次更改一张幻灯片。

   幻灯片模板只用于新的演示文稿。当有人发送的文件本身已经是页面或演示文稿时（HTML 导出文件、包含 index.html 的 zip、静态站点），按原样发布它们：创建应用时不要使用 --template，用 index.html 放在顶部把文件解压到应用文件夹，把它从 CDN 加载的任何脚本复制进来，然后推送。带附件的“把它们移到这里”或“把这个放在这里”就是字面意思：直接做，不要问是什么意思。

2. 已经存在的应用要通过固定放进对话，而不是发一条带链接的消息：

   laze app pin <app> --channel <channel>

   --role editor 允许成员更改数据但不能更改代码，--view-only 只允许他们查看。laze app pins <channel> 会列出标签页。不要再次固定一个被人取消固定的应用。

3. 在 laze.app.json 中设计数据结构：每类事物一个集合，包含带类型的字段和几条种子记录。数据存在记录中，绝不写在页面代码里。把数字、行或文本硬编码在页面里的做法是错误的：数据变化时，应用必须不经推送就随之变化。

4. 更改页面，然后在上线前先本地查看（见检查自己的工作）。

5. 推送：

   laze app push -m "Added the pipeline board" --seed

   每次推送都会立即成为线上应用。没有草稿、分支或拉取请求：应用基于主干开发。消息要用一句普通的话说明对人来说有什么变化。--seed 只会填充尚无记录的集合。

6. 返回错误推送之前：laze app versions，然后 laze app revert <version> -m "<why>"。这会成为新的线上版本；不会丢失任何记录。应用内的 git 历史只用于此目的。

谁可以打开它#

新应用默认为受限。固定在对话中的应用可由该对话中的所有人打开，所以固定通常就是团队应用所需的全部共享方式。如果有人在频道中要求创建应用，不要只把应用共享给提出请求的人：把它固定在该频道。只有在被要求时才用 laze app access visibility internal|public 扩大范围；命令会说明何时需要管理员批准。laze app members 会显示现在谁可以打开它。在告诉大家应用已准备好之前先检查它。

设计规则#

从应用要表达的内容出发，而不是从布局出发。想想关心这个主题的人会如何在白板上画它，然后构建那个东西：威胁模型是攻击地图，路线图是时间线，预算是资金流，流程是图表。满页指标块和项目符号列表读起来像报告，而这正是要避免的应用。

尽量做到高度可视化：能用动态图形和流程图的地方就用，一步一步引导大家，直到完全理解。绝不要写大段文字：需要文字的地方，用简单的短句。应用是为了让人看懂，不是用来倾倒你脑子里的内容。

Laze 套件来自平台（/_laze/theme.css、/_laze/kit.css、/_laze/laze.js）。它是工具箱，不是要你填满的布局：取用其中的 token 和你需要的控件，然后在自己的文件里叠加自己的 CSS。绝不要把套件复制到应用中。

• 视觉优先。 把主题的图像本身做成应用：内联 SVG、canvas、地图、时间线、图表，或者人们可以点击探索的东西。让它有自己的外观，在套件 token 之上使用你自己的布局和动效。
• 每屏一个任务。 第一屏回答应用存在的那个问题。第二个任务放到标签页（lz-tabs）中，不要放在第一个任务下面。
• 合适的形态。 当人们需要浏览或移动行时使用表格（lz-table）或看板（lz-board）；当一个数字就是重点时使用指标块（lz-stats、lz-stat-value）；随时间变化的数字使用图表（lz-chart）；短流程使用编号步骤（lz-steps）。超过三行的文本应放在文档里，而不是应用里。
• 真实数据。 展示人们关心的记录，使用真实名称和日期。不要使用“Lorem”、“Item 1”或占位图表。页面上的每个论断都来自记录或链接。
• 字号层级。 一个页面标题（lz-title）、标题下的一行文字（lz-lede）、分区标题（lz-h2 或 lz-card-title）、正文。不要添加其他字号。
• 间距。 使用页面（lz-page）、卡片（lz-card lz-card-body）和网格（lz-grid、lz-row）类；它们会保持 12 到 20 px 的节奏。不要在卡片里再堆叠卡片。
• 两种主题。 颜色只能来自 token（var(--color-fg)、var(--color-bg-surface)、var(--color-primary)、var(--color-border) 以及 lz-badge-* 色调）。十六进制颜色会破坏深色模式。
• 窄宽度。 应用会在约 380 px 宽的侧边面板中打开。给表格单元格加上 data-label，让行可以堆叠，并保持表头为一行。
• 空状态和错误状态。 空列表要说明将出现什么，以及如何添加第一项。调用失败时显示 Laze.fail(error)，绝不要显示空白页。
• 用徽章表示状态。 用 lz-badge 和色调（-success、-warning、-danger、-info、-primary）显示状态，不要使用彩色文字。
• 表单不要挡路。 把“新建项目”放在按钮后面；列表才是主要内容。

套件参考#

脚本只能从应用自己的源加载：CDN <script> 会被拒绝，所以把需要的库复制到应用文件夹中。移植 claude.ai artifact 或另一个 React 页面时，在推送前编译其 JSX（例如 npx esbuild app.jsx --bundle --minify --outfile=app.js），并链接构建后的文件。浏览器内 Babel 也能用，但每次打开都会加载数 MB 内容。

在页面脚本中，Laze.records("<collection>") 会列出、创建、更新和移除记录，Laze.subscribe 会在更改时重新加载，Laze.h 会构建元素，Laze.mount 会绘制它们。

键盘快捷键#

除非你的应用自行处理，否则 Laze 会把属于 Laze 的快捷键从你的应用传回 Laze，这样人们可以按 Cmd+K（Windows 和 Linux 上为 Ctrl+K）离开应用，而无需先点击应用外部。会传递的快捷键包括 Cmd+K、Cmd+[ 和 Cmd+]、Cmd+1 到 Cmd+9、Cmd+Shift+A、Cmd+Shift+T、Cmd+Shift+M、Cmd+Shift+D、Cmd+. 和 Cmd+/，以及文本字段外的 Alt+Up 和 Alt+Down。其他所有按键都会留在你的应用中。

如果要把其中一个快捷键留给你的应用，请处理该按键并调用 event.preventDefault()；Laze 之后就不会管它：

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

检查自己的工作#

推送每个更改前先查看它：

laze app serve --port 4173

它会在 http://127.0.0.1:4173/ 提供你的文件夹，并带上平台套件和线上应用的记录，且为只读。它需要先有一个线上版本，所以先运行一次 laze app push。用你的浏览器工具打开它，并在两种主题和面板宽度下截图，例如：

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

查看每张图片。修复溢出的文本、放不下的列、在深色模式中消失的颜色，以及任何仍然写着“demo”的内容。

发布应用消息前：

• 它已固定在被要求的位置，并且 laze app members 列出了应该能打开它的人。
• 第一屏无需滚动就能回答请求。
• 浅色、深色和 390 px 截图看起来都已完成。
• 你的消息给出应用名称，并用一行说明它的作用。对话中的标签页就是链接。

不确定时先问#

问对方一个简短问题，而不是构建错误的东西。不要等待他们对已经要求的步骤说“开始吧”：如果他们要求在这个频道中创建应用，就在这里创建、固定并告诉他们。