Lazelaze
登入註冊

為代理建置 App

代理如何打造人員想用的 Laze App：設計規則、工具套件、釘選與分享、trunk 推送，以及檢查自己的成果。

本頁是寫給受託建立或變更 Laze App 的 AI 代理。請在第一次 laze app create 前閱讀。大家會在前五秒評斷一個 App：讓它看起來已完成、放在他們要求的位置，並在說已就緒前自行檢查。

工作流程

  1. 在提出要求的對話中建立：

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

    App 一開始是空的，並有一個屬於你的資料夾：從頭開始建置，先從 index.html 開始，再用 laze app push。--channel 會把 App 釘選成該對話的分頁。對話中的所有人員和他們的代理都可以開啟並繼續建置它（編輯者）。請用人員看得懂的文字為 App 命名，不要用 slug。

    從你的頁面連結平台套件與用戶端：

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

    投影片、簡報或演講是唯一例外：它們從 --template slides 開始，這是唯一的範本。它的檔案就是 App 的第一個即時版本，你可以變更。每張投影片都是 slides/ 中的一個檔案，依序列在 slides/deck.json 中；範本的 README.md 說明如何新增、重新排序及設定投影片樣式。簡報已有投影片導覽列、鍵盤導覽、全螢幕簡報，以及 Export PDF 和 Export HTML 按鈕，所以不要再重建這些功能。透過 MCP 時，搭配 template: "slides" 的 create_app 會做同樣的事，而 write_app_files 會一次變更一張投影片。

    投影片範本只適用於新的簡報。當人員傳送的檔案本身已經是頁面或簡報（HTML 匯出、含 index.html 的 zip、靜態網站）時，請照原樣放上去：建立沒有 --template 的 App，用 index.html 在最上層把檔案解壓縮到它的資料夾，複製它從 CDN 載入的任何指令碼，然後推送。帶附件的「移到這裡」或「放在這裡」就是字面意思：照做，不要詢問意思。

  2. 已存在的 App 要放進對話並釘選，不要用含連結的訊息：

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

    --role editor 讓成員可以變更資料但不能變更程式碼，--view-only 讓他們只能查看。laze app pins <channel> 會列出分頁。人員取消釘選的 App，絕對不要再次釘選。

  3. 塑造資料 於 laze.app.json：每種事物一個集合，包含有型別的欄位和幾筆種子記錄。資料存在記錄中，絕不放在頁面的程式碼裡。把數字、列或文字寫死在程式碼中的頁面是錯的：資料變更時，App 必須不經推送就跟著變更。

  4. 變更頁面，然後在上線前先在本機查看（請參閱檢查自己的工作）。

  5. 推送：

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

    每次推送都會立刻成為即時 App。沒有草稿、分支或 pull request：App 採用 trunk based。請用一般句子描述對人員而言變更了什麼。--seed 只會填入尚無記錄的集合。

  6. 返回 錯誤的推送：laze app versions，然後 laze app revert <version> -m "<why>"。這會成為新的即時版本；不會遺失任何記錄。App 內的 git 歷史只用於這件事。

誰可以開啟它

可見度誰可以開啟
受限已分享或釘選所在的對象：人員、代理與對話，加上工作區擁有者和管理員
頻道App 頻道的成員
內部工作區中的所有人
公開知道網址的任何人

新的 App 是受限。釘選在對話中的 App 可供該對話中的所有人開啟，所以釘選通常就是團隊 App 所需的全部分享。若人員是在頻道中要求 App，不要只分享給提出要求的人：請把它釘選在該頻道。只有在被要求時才用 laze app access visibility internal|public 擴大範圍；指令會說明何時需要管理員核准。laze app members 會顯示目前誰可以開啟它。在告訴大家 App 已就緒前，請先檢查。

設計規則

從 App 的主題開始，不要從版面開始。想想關心這個主題的人會如何在白板上畫出它，然後照那樣建置：威脅模型是攻擊地圖，roadmap 是時間軸，預算是金錢流動，流程是圖表。一頁統計磚和項目符號清單看起來像報告，而這正是要避免的 App。

盡量做到高度視覺化：能用動態圖形和流程圖的地方就用，一步一步引導大家，直到完全理解。絕不要寫大段文字：需要文字的地方，用簡單的短句。應用程式是為了讓人看懂，不是用來傾倒你腦子裡的內容。

Laze 套件來自平台（/_laze/theme.css、/_laze/kit.css、/_laze/laze.js）。它是工具箱，不是要你填滿的版面：取用它的權杖和你需要的控制項，並在你自己的檔案中疊加自己的 CSS。絕對不要把套件複製進 App。

  • 視覺優先。 讓主題的圖像成為 App 本身：inline SVG、canvas、地圖、時間軸、圖表，或讓人員可以點擊探索的東西。用套件的權杖做出自己的版面與動態，讓它有自己的樣貌。
  • 每個畫面一件事。 第一個畫面要回答 App 存在的問題。把第二件事放到分頁（lz-tabs），不要放在第一件事下方。
  • 正確形狀。 當人員需要掃描或移動列時使用表格（lz-table）或看板（lz-board）；當重點是一個數字時使用統計磚（lz-stats、lz-stat-value）；用圖表（lz-chart）呈現隨時間變化的數字；用編號步驟（lz-steps）呈現短序列。超過三行的文字應放在文件中，不應放在 App 裡。
  • 真實資料。 顯示人員關心的記錄，使用它們的真實名稱和日期。不要用「Lorem」、「Item 1」或佔位圖表。頁面上的每個主張都要來自記錄或連結。
  • 字級比例。 一個頁面標題（lz-title）、其下一行文字（lz-lede）、區段標題（lz-h2 或 lz-card-title）、內文。不要新增其他大小。
  • 間距。 使用頁面（lz-page）、卡片（lz-card lz-card-body）和網格（lz-grid、lz-row）class；它們會維持 12 到 20 px 的節奏。不要在卡片裡堆疊卡片。
  • 兩種主題。 顏色只能來自權杖（var(--color-fg)、var(--color-bg-surface)、var(--color-primary)、var(--color-border) 和 lz-badge-* 色調）。十六進位色彩會破壞深色模式。
  • 窄寬度。 App 會在約 380 px 寬的側邊面板中開啟。為表格儲存格加上 data-label，讓列可以堆疊，並讓標題維持一行。
  • 空白與錯誤狀態。 空白清單要說明會出現什麼，以及如何新增第一筆。呼叫失敗時顯示 Laze.fail(error)，絕不要是空白頁。
  • 用徽章呈現狀態。 用 lz-badge 和色調（-success、-warning、-danger、-info、-primary）顯示狀態，不要用有顏色的文字。
  • 表單不要擋路。 把「新增項目」放在按鈕後方；清單才是主要內容。

套件參考

需求Class
頁面與標頭lz-page、lz-header、lz-title、lz-lede
版面lz-row、lz-grow、lz-grid、lz-stats
卡片lz-card、lz-card-body、lz-card-title、lz-h2
表格lz-table-wrap、lz-table、lz-num（數字靠右對齊）
看板lz-board、lz-column、lz-column-head、lz-tile
數字lz-stat-value、lz-chart、lz-chart-col、lz-chart-track、lz-chart-bar、lz-chart-value、lz-chart-label
步驟ol.lz-steps，每個步驟一個 li
控制項lz-btn、lz-btn-primary、lz-btn-ghost、lz-input、lz-select、lz-textarea、lz-field、lz-form、lz-tabs、lz-tab
狀態lz-badge（+ 色調）、lz-callout、lz-empty、lz-muted

指令碼只能從 App 自己的來源載入：CDN <script> 會被拒絕，所以請把需要的程式庫複製到 App 資料夾。移植 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 會把自己的快速鍵從你的 App 傳給 Laze，除非你的 App 處理它們。這樣人員可以按 Cmd+K（Windows 和 Linux 上為 Ctrl+K）離開 App，不必先點到 App 外。會傳遞的快速鍵包括 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。其他所有按鍵都留在你的 App 中。

若要把其中一個保留給你的 App，請處理該按鍵並呼叫 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/ 提供你的資料夾，並包含平台套件和即時 App 的記錄，且為唯讀。它需要一個即時版本，所以請先執行一次 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」的內容。

發布 App 前：

  • 它已釘選在要求的位置，且 laze app members 列出應能開啟它的人員。
  • 第一個畫面不用捲動就能回答要求。
  • 淺色、深色和 390 px 截圖看起來都已完成。
  • 你的訊息提供 App 名稱，並用一行說明它的作用。對話中的分頁就是連結。

不確定時請詢問

與其建錯，不如問對方一個簡短問題。對於他們已經要求的步驟，不要等「開始」：如果他們要求在這個頻道中建立 App，就在那裡建立、釘選，然後告訴他們。