lavish

Lavish Editor

Lavish Editor 能協助 Agent 將豐富的 HTML Artifact 轉化為可供人類協同審閱的介面。每當你準備向使用者提供複雜、且透過豐富/互動式頁面會更容易理解的回答時，請考慮使用 Lavish Editor。首先根據使用者需求生成互動式 HTML Artifact，接著執行 npx -y lavish-axi <html-file>，讓使用者能在瀏覽器中進行視覺化審閱、標註元件或選取的文字、將 Prompt 加入佇列，並透過 npx -y lavish-axi poll 回傳意見。

你不需要全域安裝 lavish-axi，直接透過 npx -y lavish-axi <html-file> 呼叫即可。
若 lavish-axi 的輸出顯示後續命令以 lavish-axi 開頭，請改為執行 npx -y lavish-axi ...。
在受限的子程序沙盒、CI 或 Agent Harness（執行環境）中，若 npx -y 異常退出（例如回傳狀態碼 216），可以直接使用已安裝的版本：區域安裝請用 node "$(npm root)/lavish-axi/dist/cli.mjs" <html-file>，全域安裝請用 node "$(npm root -g)/lavish-axi/dist/cli.mjs" <html-file>，或者在安裝一次後直接執行 lavish-axi <html-file>。

Request

$ARGUMENTS

若上述 Request 不為空，代表使用者明確呼叫了 /lavish——請依照下方工作流程，立即為該需求建立 HTML Artifact。
若為空，請從對話內容中推論需要視覺化的內容。

時機（When to use）

當使用者要求視覺化 Artifact、HTML 解說頁面、互動式原型、審閱介面、產品或技術計畫、比較表、報告，或是基於瀏覽器的回饋循環時，請使用 lavish-axi。

工作流程（Workflow）

1. 建立 HTML Artifact（預設路徑為工作目錄下的 .lavish/<name>.html）。
2. 執行 npx -y lavish-axi <html-file> 以在瀏覽器中開啟或恢復審閱階段（Session）。
3. 執行 npx -y lavish-axi poll <html-file> 進行 Long-polling，等待使用者的標註、佇列中的 Prompt，以及經真實瀏覽器驗證、以 layout_warnings 回傳的嚴重排版缺失。
   第一次 Poll 時，建議加上 --agent-reply "<用一句話總結你建置的內容與建議先審閱的部分>"，以便對話面板開啟時帶有上下文。
   在使用者採取行動或真實瀏覽器證實關鍵內容無法存取/使用之前，Poll 會保持靜默——請讓它持續執行，切勿中途刪除或終止（Kill）。
   視覺美化、故意為之、暫時性、微小或不確定的觀察結果將保持靜默。
   預設將 Poll 保持在前景執行，讓它直接將回饋回傳給 Agent。
   僅有在 Harness 原生支援可追蹤的背景任務機制，且其完成結果保證能恢復或通知同一 Agent 時，才允許背景 Poll。
   切勿僅為了維持 Polling 而使用 nohup、Shell 的 &、disown、重導向後不理的程序，或沒有明確驗證回呼機制（Callback）的獨立終端機。
   若 Harness 沒有感知完成狀態的背景機制，請使用前景 Poll，或是先在周圍的 Supervisor 接上已驗證的喚醒回呼。
   在該喚醒路徑正式上線前，請勿告知使用者正在監控 Artifact。
   若 Poll 仍被終止或逾時，直接重新執行即可——佇列中的回饋絕不會遺失。
4. 若 Poll 回傳 layout_warnings，請遵循回傳的 next_step：在邀請人類參與前，先修復嚴重的排版錯誤並重新檢查。
5. 套用人類回饋後，再次執行包含 --agent-reply "<訊息>" 的 Poll，在瀏覽器中進行回覆，並在相同的前景或已驗證喚醒路徑規則下維持循環。
6. 審閱完成時，執行 npx -y lavish-axi end <html-file>。
7. 「Send & End」會結束 Session。其最終回饋仍會發送一次。在該回應之後，Polling 將停止，Agent 不得在未受邀請的情況下重新開啟 Session。請直接在本對話中發送任何剩餘的更新。

視覺指引（Visual guidance）

• 利用視覺層級（Visual hierarchy），讓最重要的決策、風險、權衡與下一步行動一目了然
• 使用區塊、卡片、表格、圖表、帶標註的程式碼片段及左右對比等視覺結構，取代長篇大論的文字
• 有意識地選擇字體、間距、顏色與排版，使 Artifact 具有清晰的觀點
• 防止在每個巢狀層級發生水平溢出（Horizontal overflow）：巢狀的 Grid/Flex 子元件也需要 minmax(0, 1fr) 軌道與 min-width: 0，特別是在 Badge、標籤或狀態文字使用較寬的像素字型或等寬字型時；請主動對無法斷行的長文字進行換行（Wrap）、裁切（Truncate）或限制（Contain）
• 當 Artifact 需要描述現有或當前的 UI/狀態時，請直接展示出來：截取真實頁面的螢幕截圖（必要時以唯讀模式執行 App）並嵌入其中，而不是用文字解釋當前的外觀；將文字留給無法展示的內容，例如理由、權衡與未決問題

劇本（Playbooks）

執行 npx -y lavish-axi playbook <id> 可獲得上述任何項目的針對性詳細指引。
單一 Artifact 通常會結合多個 Playbook（例如包含比較表與圖表的計畫），因此在撰寫 HTML 之前必須開啟每個匹配的 Playbook。
對於流程圖、架構圖、狀態圖或時序圖，切勿使用 Div/Flexbox 手動構建方塊與箭頭；請開啟 Diagram Playbook，並使用來自 npx -y lavish-axi design 的主題感知型 Mermaid 片段，除非需要 SVG 來呈現帶有豐富標註的節點。

• diagram - 梳理關聯、流程、狀態與架構
• table - 將密集的紀錄轉化為易於掃視審閱的介面
• comparison - 展示方案、權衡以及當前與目標行為的差異
• plan - 在實作前解釋產品或技術計畫
• code - 在 Lavish Artifact 內渲染原始碼、程式碼檔案、Patch、PR Diff 以及前後對比程式碼
• input - 當 Agent 需要在 Artifact 內部收集使用者對於決策、選擇、偏好、分類、範圍或其他結構化回饋的輸入時必須使用
• slides - 當要求提供簡報時，建立精緻的簡報展示

指令與規則（Commands & rules）

• 執行 npx -y lavish-axi <html-file> 以開啟或恢復 Lavish Editor Session。若使用者已明確從瀏覽器結束 Session，此指令會拒絕重新開啟並說明原因，而非主動開啟——僅在使用者要求進一步審閱或有重要事項需要其視覺關注時，才傳入 --reopen
• 除非使用者指定其他位置，否則請在目前工作目錄的 .lavish/ 底下建立 HTML Artifact
• Lavish 透過本機 Express.js 伺服器提供 HTML 檔案服務。若你的 HTML 需要引用其他檔案系統資產（如圖片、CSS、字型和本機腳本），請將它們複製到與 HTML 檔案相同的目錄中，並使用該目錄的相對路徑進行引用。切勿在資產路徑前加上 /——根路徑無法運作
• 執行 npx -y lavish-axi poll <html-file> 以等待使用者回饋或經真實瀏覽器驗證的嚴重排版缺失。它會進行 Long-polling 並保持靜默，直到使用者發送回饋、結束 Session 或真實瀏覽器證實關鍵內容無法存取/使用為止，因此請讓它持續執行——切勿終止它。在邀請人類參與之前，修復並重新檢查每個回傳的排版缺失；視覺美化、故意為之、暫時性、微小或不確定的觀察結果保持靜默。預設將 Poll 保持在前景執行，讓它直接將回饋回傳給 Agent。僅有在 Harness 原生支援可追蹤的背景任務機制，且其完成結果保證能恢復或通知同一 Agent 時，才允許背景 Poll。切勿僅為了維持 Polling 而使用 nohup、Shell 的 &、disown、重導向後不理的程序，或沒有明確驗證回呼機制的獨立終端機。若 Harness 沒有感知完成狀態的背景機制，請使用前景 Poll，或是先在周圍的 Supervisor 接上已驗證的喚醒回呼。在該喚醒路徑正式上線前，請勿告知使用者正在監控 Artifact。若 Poll 仍被終止或逾時，直接重新執行即可——佇列中的回饋絕不會遺失。「Send & End」會結束 Session。其最終回饋仍會發送一次。在該回應之後，Polling 將停止，Agent 不得在未受邀請的情況下重新開啟 Session。
• 在 .mermaid 容器中渲染的 Mermaid 圖表會在瀏覽器中變成可嵌入、可編輯的 Excalidraw 白板（點擊圖表即可解鎖編輯；全螢幕操作可在整個視埠上開啟）——流程圖（Flowchart）、時序圖（Sequence）、類別圖（Class）、ER 圖與狀態圖（State）會轉換為可編輯的形狀；其他類型則嵌入為圖片以供繪製。畫景會在本地自動儲存；當重新載入檢測到變更的 Mermaid 源碼時，審閱者可明確選擇重新轉換並捨棄已儲存的編輯，或繼續編輯已儲存的畫景。獨立與導出的副本仍會渲染為純文本 Mermaid。佇列回饋會將 Prompt 新增至對話面板；當使用者發送時，Poll 會回傳標記為 "whiteboard" 的 Prompt，其中包含有限的編輯摘要以及本地 scenePath（.excalidraw JSON）與 previewPath（PNG）檔案——請先閱讀摘要，僅在需要時開啟檔案，接著透過更新 Artifact 中的 Mermaid 源碼來套用編輯（切勿嘗試將畫景寫回）
• 執行 npx -y lavish-axi end <html-file> 以 Agent 的身分結束 Session——以此方式結束後續仍允許直接重新開啟。當使用者改從瀏覽器結束時，後續的 npx -y lavish-axi <html-file> 在沒有 --reopen 的情況下會拒絕重新開啟
• 執行 npx -y lavish-axi export <html-file> [--out <path>] 以寫出 Artifact 的可攜式副本——單一 HTML 檔案且內嵌其「本機」資產——因此無需 Lavish 伺服器與同級檔案即可開啟。遠端 CDN/字型引用將保留為連結，因此渲染這些資源時需要網路連線。使用者也可以從瀏覽器外框的溢出選單中導出
• 執行 npx -y lavish-axi share <html-file> [--password <pw>] [--token <t>] 將 Artifact 發布至 ht-ml.app (https://ht-ml.app)（第三方託管服務，不屬於 Lavish），並取得可存取的 URL。分享預設為「公開」，因此任何擁有連結的人皆可開啟。傳入 --password 可發布受密碼保護的「私密」頁面；檢視者必須提供密碼才能檢視。本機資產會被內嵌；遠端引用透過網路載入。它會回傳 URL 以及用於後續管理頁面的金鑰 update_key。僅在擁有可選的 Bearer Token 時才使用 --token 或 LAVISH_AXI_HTML_APP_TOKEN；這絕非必需。使用者也可以從瀏覽器外框的溢出選單中發布
• 執行 npx -y lavish-axi stop 以關閉背景伺服器（在閒置或最後一個 Session 結束且無任何連線時，它也會自動停止）
• 執行 npx -y lavish-axi playbook <playbook_id> 以取得針對性的 Artifact 指引。單一 Artifact 通常會結合多個 Playbook（例如包含比較表與圖表的計畫），因此在撰寫 HTML 之前必須開啟每個匹配的 Playbook。
• Lavish 不會自動注入任何設計系統——Artifact 保持可攜性，因此在未執行 lavish-axi 的情況下直接開啟時，渲染效果完全一致。在撰寫任何 HTML 之前：按照以下嚴格的優先順序決定設計方向，且僅在當前步驟確實一無所獲時才進入下一步：(1) 若使用者要求特定的外觀或具名的設計系統，請直接使用；(2) 否則你必須先檢查 Artifact 所針對的專案——即其內容或 UI 所代表的主題或產品，這可能與你目前的工作目錄不同——並與該專案的設計系統比對匹配：Tailwind 或主題配置、共享的 CSS 變數或設計 Token、元件庫、品牌資產，或現有的帶樣式頁面。若 Artifact 預覽、提出或 Mock 特定 App 的 UI，請使用該 App 自有的設計系統進行渲染