深解)
從不誤吵醒 Agent 的被動檢測lavish-axi iframe 布局審計實現(xiàn)深解【免費下載鏈接】lavish-axiHTML is the new markdown. Lavish is the new editor for your HTML artifacts.項目地址: https://gitcode.com/gh_mirrors/la/lavish-axilavish-axi是一款面向人與 AI Agent 協(xié)作的本地優(yōu)先HTML 編輯器Agent 寫好 HTML 產(chǎn)物用戶在本地瀏覽器里審閱可以點選元素、選中文字把反饋發(fā)回給 Agent。其中最精巧的設(shè)計是它的iframe 布局審計——一套被動檢測機制能發(fā)現(xiàn)文字被裁切、按鈕被剪掉、內(nèi)容跑出視口等嚴重布局故障但永遠不會因為發(fā)現(xiàn)了問題就去吵醒 Agent 。什么是被動檢測先看兩種思路Agent 生成的 HTML 經(jīng)?？粗芘?、實際有傷一段標(biāo)題溢出了卡片、一個按鈕被容器剪掉一半。傳統(tǒng)思路是檢測到問題就立刻通知 Agent 修復(fù)但這會帶來兩個麻煩誤報即騷擾檢測邏輯稍有噪音Agent 就會被反復(fù)喚醒去修并不存在的問題浪費輪次用戶可能只是掃一眼根本不想修。lavish-axi 選擇了另一條路檢測永遠是被動發(fā)生的。審計在 iframe 里靜默運行發(fā)現(xiàn)的結(jié)果只落進頂部的Layout issues收件箱只有當(dāng)用戶手動勾選問題并點擊Queue selected fixes時Agent 才會通過常規(guī)的長輪詢通道收到一條layout-warnings提示。源碼里把這個原則寫得很直白檢測從不返回lavish-axi poll從不喚醒 Agent只有用戶排隊修復(fù)才會。這個約定見 src/layout-warnings.js 文件頭部的注釋也是整個模塊的設(shè)計基石。審計盯住哪 6 類嚴重布局故障審計只報告有直接渲染證據(jù)的嚴重失敗規(guī)則與用戶看到的大白話描述在 src/layout-warnings.js 中一一對應(yīng)規(guī)則含義用戶看到的描述page-horizontal-overflow頁面整體橫向溢出頁面比視口寬內(nèi)容跑到了屏幕外clipped-text文字片段越過容器裁剪邊界文字被容器裁掉了clipped-control必要控件被容器剪掉一部分按鈕的一部分無法使用viewport-unreachable-control必要控件在視口之外控件夠不到viewport-unreachable-content文字片段在視口之外這段文字讀不到overlapping-text文字被不透明兄弟元素大面積遮擋文字被蓋住讀不了只有severity: error的發(fā)現(xiàn)才會入箱見 src/layout-warnings.js輕微抖動一律忽略——寧可漏報小瑕疵不可誤報。審計如何等到穩(wěn)定時刻再出手瀏覽器里做布局測量最大的坑是測得太早字體還沒加載完、動畫還沒結(jié)束、響應(yīng)式布局還沒算完。審計入口 auditLayout() 之前有一整串穩(wěn)壓器全部位于注入到沙盒 iframe 的 SDK 中src/artifact-sdk.js等字體document.fonts.ready——字體切換會顯著改變文字幾何等尺寸穩(wěn)定用ResizeObserver監(jiān)聽前 800 個元素180ms 無變化才算穩(wěn)定最多等 2 秒等有限動畫結(jié)束入場動畫、過渡最多等 4 秒無限動畫如持續(xù)旋轉(zhuǎn)的裝飾則放行但動畫關(guān)聯(lián)的元素會被整體排除在檢測之外采樣兩到三輪先測一遍間隔 120ms 再測一遍若 DOM 仍在水合MutationObserver 觀察到變化則等其靜止后再測第三輪最后只發(fā)布兩輪都穩(wěn)定存在的發(fā)現(xiàn)findStableLayoutFindings。審計會在load、resize、animationend、transitionend等事件后自動重排startLayoutAudit所以用戶手動縮小窗口觸發(fā)的響應(yīng)式塌陷也會被捕獲。如何避免誤報一份精心設(shè)計的豁免清單這是該模塊最見功力的部分——大量看起來越界的布局其實是作者意圖審計會主動豁免src/artifact-sdk.js??顯式省略號 / line-clamp作者想截斷就不算事故標(biāo)準(zhǔn) visually-hidden 無障礙文本2px 裁剪的 sr-only 寫法有意的橫向滾動容器輪播、橫向列表及其后代蒙版 / 圓角裁剪mask、clip-path、帶圓角的 overflow 容器屬于裝飾手法?裝飾性重疊海報式疊字不產(chǎn)生文本遮擋發(fā)現(xiàn)正在運動的元素動畫未結(jié)束時的中間態(tài)不算證據(jù)。閾值也經(jīng)過校準(zhǔn)文本要越過裁剪邊界 1px 以上且中心點在界外或超過 20%才算嚴重classifySevereTextOverflow頁面級橫向溢出必須同時滿足有真實內(nèi)容逃出且超出max(24px, 視口寬度 5%)isMaterialPageOverflow。遮擋檢測則是對文字片段取 9 個采樣點做elementFromPoint不透明遮擋占比 ≥90% 且樣本 ≥5才報isNearTotalOcclusion。為什么告警不會誤消也不會重復(fù)刷屏發(fā)現(xiàn)落庫后applyDiagnosticPass 按一套刻意保守的生命周期來維護記錄穩(wěn)定指紋規(guī)則 歸一化目標(biāo) 視口檔位layoutWarningFingerprint生成 16 位哈希同一個問題反復(fù)檢測只會更新同一條記錄絕不虛增計數(shù)——溢出量甚至被刻意排除在指紋之外視口隔離mobile / compact / desktop三檔視口互不干擾桌面端的通過永遠不能清除手機端的告警只有正向證據(jù)能解決Resolved要求更新的產(chǎn)物加載 同一視口的一輪完整審計不再檢出。審計失敗、頁面沒加載完、換了一個視口統(tǒng)統(tǒng)只會把記錄標(biāo)成Unverified未驗證而非清除狀態(tài)機Open → Queued for fix → Still present / Returned外加Unverified / Dismissed / Obsolete / Resolved完整枚舉見 src/layout-warnings.js每次狀態(tài)遷移都寫入有界的歷史軌跡方便回看這條告警是怎么來的。這套規(guī)則有完整的單測覆蓋test/layout-warnings.test.js 里的用例名本身就是一份需求文檔例如a different viewport class can never clear a warning、a newer complete matching-viewport pass without the finding resolves it。用戶視角從徽章到 Agent 修復(fù)的完整鏈路審計完成后頂欄出現(xiàn)Layout issues按鈕與未解決計數(shù)沒有問題時按鈕直接隱藏打開抽屜每條問題展示嚴重程度、大白話解釋、受影響視口、組件標(biāo)識、最后出現(xiàn)時間與狀態(tài)并提供Reveal在產(chǎn)物中高亮定位與Dismiss僅對當(dāng)前產(chǎn)物版本生效勾選若干條或Select all點擊Queue selected fixes——整批問題合并成一條普通排隊提示標(biāo)簽為layout-warnings隨用戶下次發(fā)送走常規(guī)反饋通道Agent 收到的是結(jié)構(gòu)化載荷每條帶選擇器、軸方向、溢出像素、視口檔位layoutWarningPromptPayload并要求一次修完、保存一次讓審閱頁只刷新一次。交互細節(jié)可見 test/layout-warning-inbox.browser.test.js。打開時的布局閘門只擋一瞬間打開審閱頁時產(chǎn)物會先被遮罩蓋住只等第一輪真實的 iframe 審計完成就立刻揭開——無論查到什么問題。第一次完成的客戶端檢查即放行絕不讓網(wǎng)絡(luò)往返或修復(fù)請求綁架審閱超時有兜底超時自動放行用戶還能隨時點Show anyway。用--no-gate可以跳過這層幕布見 README.md 的Open-time layout gate一節(jié)?？渴裁幢ＷC不誤報、不吵人真實瀏覽器回歸測試項目用真瀏覽器對一整組夾具頁做回歸test/layout-audit-browser.test.js夾具就在 test/fixtures/layout-audit/control-broken-*四類故意做壞的頁面溢出、裁切、可達性、遮擋必須在桌面 移動視口下各報出預(yù)期條數(shù)real-*-clean一組真實但健康的頁面產(chǎn)品計劃、儀表盤、雜志排版、輪播、動畫入場必須保持沉默斷言里有一行點睛之筆detection alone must never wake an agent——檢測到問題后執(zhí)行 poll 仍然返回waiting修復(fù)后的產(chǎn)物重新加載并通過完整審計計數(shù)歸零——全程 Agent 從未被喚醒。小結(jié)lavish-axi 的 iframe 布局審計把檢測和修復(fù)徹底解耦對 Agent 安靜檢測永不觸發(fā)輪詢返回只有用戶排隊修復(fù)才產(chǎn)生提示對用戶有用每條告警都有大白話解釋、可定位、可忽略、可批量修復(fù)對狀態(tài)誠實只有正向證據(jù)能清除告警失敗與不確定一律顯式標(biāo)記。如果你也在做AI 生成 HTML 人工審閱的產(chǎn)品這套 src/layout-warnings.js src/artifact-sdk.js 的被動檢測 保守生命周期設(shè)計值得完整讀一遍源碼?！久赓M下載鏈接】lavish-axiHTML is the new markdown. Lavish is the new editor for your HTML artifacts.項目地址: https://gitcode.com/gh_mirrors/la/lavish-axi創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 從不誤吵醒 Agent 的被動檢測：lavish-axi iframe 布局審計實現(xiàn)深解
從不誤吵醒 Agent 的被動檢測lavish-axi iframe 布局審計實現(xiàn)深解【免費下載鏈接】lavish-axiHTML is the new markdown. Lavish is the new editor for your HTML artifacts.項目地址: https://gitcode.com/gh_mirrors/la/lavish-axilavish-axi是一款面向人與 AI Agent 協(xié)作的本地優(yōu)先HTML 編輯器Agent 寫好 HTML 產(chǎn)物用戶在本地瀏覽器里審閱可以點選元素、選中文字把反饋發(fā)回給 Agent。其中最精巧的設(shè)計是它的iframe 布局審計——一套被動檢測機制能發(fā)現(xiàn)文字被裁切、按鈕被剪掉、內(nèi)容跑出視口等嚴重布局故障但永遠不會因為發(fā)現(xiàn)了問題就去吵醒 Agent 。什么是被動檢測先看兩種思路Agent 生成的 HTML 經(jīng)?？粗芘?、實際有傷一段標(biāo)題溢出了卡片、一個按鈕被容器剪掉一半。傳統(tǒng)思路是檢測到問題就立刻通知 Agent 修復(fù)但這會帶來兩個麻煩誤報即騷擾檢測邏輯稍有噪音Agent 就會被反復(fù)喚醒去修并不存在的問題浪費輪次用戶可能只是掃一眼根本不想修。lavish-axi 選擇了另一條路檢測永遠是被動發(fā)生的。審計在 iframe 里靜默運行發(fā)現(xiàn)的結(jié)果只落進頂部的Layout issues收件箱只有當(dāng)用戶手動勾選問題并點擊Queue selected fixes時Agent 才會通過常規(guī)的長輪詢通道收到一條layout-warnings提示。源碼里把這個原則寫得很直白檢測從不返回lavish-axi poll從不喚醒 Agent只有用戶排隊修復(fù)才會。這個約定見 src/layout-warnings.js 文件頭部的注釋也是整個模塊的設(shè)計基石。審計盯住哪 6 類嚴重布局故障審計只報告有直接渲染證據(jù)的嚴重失敗規(guī)則與用戶看到的大白話描述在 src/layout-warnings.js 中一一對應(yīng)規(guī)則含義用戶看到的描述page-horizontal-overflow頁面整體橫向溢出頁面比視口寬內(nèi)容跑到了屏幕外clipped-text文字片段越過容器裁剪邊界文字被容器裁掉了clipped-control必要控件被容器剪掉一部分按鈕的一部分無法使用viewport-unreachable-control必要控件在視口之外控件夠不到viewport-unreachable-content文字片段在視口之外這段文字讀不到overlapping-text文字被不透明兄弟元素大面積遮擋文字被蓋住讀不了只有severity: error的發(fā)現(xiàn)才會入箱見 src/layout-warnings.js輕微抖動一律忽略——寧可漏報小瑕疵不可誤報。審計如何等到穩(wěn)定時刻再出手瀏覽器里做布局測量最大的坑是測得太早字體還沒加載完、動畫還沒結(jié)束、響應(yīng)式布局還沒算完。審計入口 auditLayout() 之前有一整串穩(wěn)壓器全部位于注入到沙盒 iframe 的 SDK 中src/artifact-sdk.js等字體document.fonts.ready——字體切換會顯著改變文字幾何等尺寸穩(wěn)定用ResizeObserver監(jiān)聽前 800 個元素180ms 無變化才算穩(wěn)定最多等 2 秒等有限動畫結(jié)束入場動畫、過渡最多等 4 秒無限動畫如持續(xù)旋轉(zhuǎn)的裝飾則放行但動畫關(guān)聯(lián)的元素會被整體排除在檢測之外采樣兩到三輪先測一遍間隔 120ms 再測一遍若 DOM 仍在水合MutationObserver 觀察到變化則等其靜止后再測第三輪最后只發(fā)布兩輪都穩(wěn)定存在的發(fā)現(xiàn)findStableLayoutFindings。審計會在load、resize、animationend、transitionend等事件后自動重排startLayoutAudit所以用戶手動縮小窗口觸發(fā)的響應(yīng)式塌陷也會被捕獲。如何避免誤報一份精心設(shè)計的豁免清單這是該模塊最見功力的部分——大量看起來越界的布局其實是作者意圖審計會主動豁免src/artifact-sdk.js??顯式省略號 / line-clamp作者想截斷就不算事故標(biāo)準(zhǔn) visually-hidden 無障礙文本2px 裁剪的 sr-only 寫法有意的橫向滾動容器輪播、橫向列表及其后代蒙版 / 圓角裁剪mask、clip-path、帶圓角的 overflow 容器屬于裝飾手法?裝飾性重疊海報式疊字不產(chǎn)生文本遮擋發(fā)現(xiàn)正在運動的元素動畫未結(jié)束時的中間態(tài)不算證據(jù)。閾值也經(jīng)過校準(zhǔn)文本要越過裁剪邊界 1px 以上且中心點在界外或超過 20%才算嚴重classifySevereTextOverflow頁面級橫向溢出必須同時滿足有真實內(nèi)容逃出且超出max(24px, 視口寬度 5%)isMaterialPageOverflow。遮擋檢測則是對文字片段取 9 個采樣點做elementFromPoint不透明遮擋占比 ≥90% 且樣本 ≥5才報isNearTotalOcclusion。為什么告警不會誤消也不會重復(fù)刷屏發(fā)現(xiàn)落庫后applyDiagnosticPass 按一套刻意保守的生命周期來維護記錄穩(wěn)定指紋規(guī)則 歸一化目標(biāo) 視口檔位layoutWarningFingerprint生成 16 位哈希同一個問題反復(fù)檢測只會更新同一條記錄絕不虛增計數(shù)——溢出量甚至被刻意排除在指紋之外視口隔離mobile / compact / desktop三檔視口互不干擾桌面端的通過永遠不能清除手機端的告警只有正向證據(jù)能解決Resolved要求更新的產(chǎn)物加載 同一視口的一輪完整審計不再檢出。審計失敗、頁面沒加載完、換了一個視口統(tǒng)統(tǒng)只會把記錄標(biāo)成Unverified未驗證而非清除狀態(tài)機Open → Queued for fix → Still present / Returned外加Unverified / Dismissed / Obsolete / Resolved完整枚舉見 src/layout-warnings.js每次狀態(tài)遷移都寫入有界的歷史軌跡方便回看這條告警是怎么來的。這套規(guī)則有完整的單測覆蓋test/layout-warnings.test.js 里的用例名本身就是一份需求文檔例如a different viewport class can never clear a warning、a newer complete matching-viewport pass without the finding resolves it。用戶視角從徽章到 Agent 修復(fù)的完整鏈路審計完成后頂欄出現(xiàn)Layout issues按鈕與未解決計數(shù)沒有問題時按鈕直接隱藏打開抽屜每條問題展示嚴重程度、大白話解釋、受影響視口、組件標(biāo)識、最后出現(xiàn)時間與狀態(tài)并提供Reveal在產(chǎn)物中高亮定位與Dismiss僅對當(dāng)前產(chǎn)物版本生效勾選若干條或Select all點擊Queue selected fixes——整批問題合并成一條普通排隊提示標(biāo)簽為layout-warnings隨用戶下次發(fā)送走常規(guī)反饋通道Agent 收到的是結(jié)構(gòu)化載荷每條帶選擇器、軸方向、溢出像素、視口檔位layoutWarningPromptPayload并要求一次修完、保存一次讓審閱頁只刷新一次。交互細節(jié)可見 test/layout-warning-inbox.browser.test.js。打開時的布局閘門只擋一瞬間打開審閱頁時產(chǎn)物會先被遮罩蓋住只等第一輪真實的 iframe 審計完成就立刻揭開——無論查到什么問題。第一次完成的客戶端檢查即放行絕不讓網(wǎng)絡(luò)往返或修復(fù)請求綁架審閱超時有兜底超時自動放行用戶還能隨時點Show anyway。用--no-gate可以跳過這層幕布見 README.md 的Open-time layout gate一節(jié)?？渴裁幢ＷC不誤報、不吵人真實瀏覽器回歸測試項目用真瀏覽器對一整組夾具頁做回歸test/layout-audit-browser.test.js夾具就在 test/fixtures/layout-audit/control-broken-*四類故意做壞的頁面溢出、裁切、可達性、遮擋必須在桌面 移動視口下各報出預(yù)期條數(shù)real-*-clean一組真實但健康的頁面產(chǎn)品計劃、儀表盤、雜志排版、輪播、動畫入場必須保持沉默斷言里有一行點睛之筆detection alone must never wake an agent——檢測到問題后執(zhí)行 poll 仍然返回waiting修復(fù)后的產(chǎn)物重新加載并通過完整審計計數(shù)歸零——全程 Agent 從未被喚醒。小結(jié)lavish-axi 的 iframe 布局審計把檢測和修復(fù)徹底解耦對 Agent 安靜檢測永不觸發(fā)輪詢返回只有用戶排隊修復(fù)才產(chǎn)生提示對用戶有用每條告警都有大白話解釋、可定位、可忽略、可批量修復(fù)對狀態(tài)誠實只有正向證據(jù)能清除告警失敗與不確定一律顯式標(biāo)記。如果你也在做AI 生成 HTML 人工審閱的產(chǎn)品這套 src/layout-warnings.js src/artifact-sdk.js 的被動檢測 保守生命周期設(shè)計值得完整讀一遍源碼?！久赓M下載鏈接】lavish-axiHTML is the new markdown. Lavish is the new editor for your HTML artifacts.項目地址: https://gitcode.com/gh_mirrors/la/lavish-axi創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考