从不误吵醒 Agent 的被动检测lavish-axi iframe 布局审计实现深解【免费下载链接】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 协作的本地优先HTML 编辑器Agent 写好 HTML 产物用户在本地浏览器里审阅可以点选元素、选中文字把反馈发回给 Agent。其中最精巧的设计是它的iframe 布局审计——一套被动检测机制能发现文字被裁切、按钮被剪掉、内容跑出视口等严重布局故障但永远不会因为发现了问题就去吵醒 Agent 。什么是被动检测先看两种思路Agent 生成的 HTML 经常看着能跑、实际有伤一段标题溢出了卡片、一个按钮被容器剪掉一半。传统思路是检测到问题就立刻通知 Agent 修复但这会带来两个麻烦误报即骚扰检测逻辑稍有噪音Agent 就会被反复唤醒去修并不存在的问题浪费轮次用户可能只是扫一眼根本不想修。lavish-axi 选择了另一条路检测永远是被动发生的。审计在 iframe 里静默运行发现的结果只落进顶部的Layout issues收件箱只有当用户手动勾选问题并点击Queue selected fixes时Agent 才会通过常规的长轮询通道收到一条layout-warnings提示。源码里把这个原则写得很直白检测从不返回lavish-axi poll从不唤醒 Agent只有用户排队修复才会。这个约定见 src/layout-warnings.js 文件头部的注释也是整个模块的设计基石。审计盯住哪 6 类严重布局故障审计只报告有直接渲染证据的严重失败规则与用户看到的大白话描述在 src/layout-warnings.js 中一一对应规则含义用户看到的描述page-horizontal-overflow页面整体横向溢出页面比视口宽内容跑到了屏幕外clipped-text文字片段越过容器裁剪边界文字被容器裁掉了clipped-control必要控件被容器剪掉一部分按钮的一部分无法使用viewport-unreachable-control必要控件在视口之外控件够不到viewport-unreachable-content文字片段在视口之外这段文字读不到overlapping-text文字被不透明兄弟元素大面积遮挡文字被盖住读不了只有severity: error的发现才会入箱见 src/layout-warnings.js轻微抖动一律忽略——宁可漏报小瑕疵不可误报。审计如何等到稳定时刻再出手浏览器里做布局测量最大的坑是测得太早字体还没加载完、动画还没结束、响应式布局还没算完。审计入口 auditLayout() 之前有一整串稳压器全部位于注入到沙盒 iframe 的 SDK 中src/artifact-sdk.js等字体document.fonts.ready——字体切换会显著改变文字几何等尺寸稳定用ResizeObserver监听前 800 个元素180ms 无变化才算稳定最多等 2 秒等有限动画结束入场动画、过渡最多等 4 秒无限动画如持续旋转的装饰则放行但动画关联的元素会被整体排除在检测之外采样两到三轮先测一遍间隔 120ms 再测一遍若 DOM 仍在水合MutationObserver 观察到变化则等其静止后再测第三轮最后只发布两轮都稳定存在的发现findStableLayoutFindings。审计会在load、resize、animationend、transitionend等事件后自动重排startLayoutAudit所以用户手动缩小窗口触发的响应式塌陷也会被捕获。如何避免误报一份精心设计的豁免清单这是该模块最见功力的部分——大量看起来越界的布局其实是作者意图审计会主动豁免src/artifact-sdk.js✂️显式省略号 / line-clamp作者想截断就不算事故标准 visually-hidden 无障碍文本2px 裁剪的 sr-only 写法有意的横向滚动容器轮播、横向列表及其后代蒙版 / 圆角裁剪mask、clip-path、带圆角的 overflow 容器属于装饰手法️装饰性重叠海报式叠字不产生文本遮挡发现正在运动的元素动画未结束时的中间态不算证据。阈值也经过校准文本要越过裁剪边界 1px 以上且中心点在界外或超过 20%才算严重classifySevereTextOverflow页面级横向溢出必须同时满足有真实内容逃出且超出max(24px, 视口宽度 5%)isMaterialPageOverflow。遮挡检测则是对文字片段取 9 个采样点做elementFromPoint不透明遮挡占比 ≥90% 且样本 ≥5才报isNearTotalOcclusion。为什么告警不会误消也不会重复刷屏发现落库后applyDiagnosticPass 按一套刻意保守的生命周期来维护记录稳定指纹规则 归一化目标 视口档位layoutWarningFingerprint生成 16 位哈希同一个问题反复检测只会更新同一条记录绝不虚增计数——溢出量甚至被刻意排除在指纹之外视口隔离mobile / compact / desktop三档视口互不干扰桌面端的通过永远不能清除手机端的告警只有正向证据能解决Resolved要求更新的产物加载 同一视口的一轮完整审计不再检出。审计失败、页面没加载完、换了一个视口统统只会把记录标成Unverified未验证而非清除状态机Open → Queued for fix → Still present / Returned外加Unverified / Dismissed / Obsolete / Resolved完整枚举见 src/layout-warnings.js每次状态迁移都写入有界的历史轨迹方便回看这条告警是怎么来的。这套规则有完整的单测覆盖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 修复的完整链路审计完成后顶栏出现Layout issues按钮与未解决计数没有问题时按钮直接隐藏打开抽屉每条问题展示严重程度、大白话解释、受影响视口、组件标识、最后出现时间与状态并提供Reveal在产物中高亮定位与Dismiss仅对当前产物版本生效勾选若干条或Select all点击Queue selected fixes——整批问题合并成一条普通排队提示标签为layout-warnings随用户下次发送走常规反馈通道Agent 收到的是结构化载荷每条带选择器、轴方向、溢出像素、视口档位layoutWarningPromptPayload并要求一次修完、保存一次让审阅页只刷新一次。交互细节可见 test/layout-warning-inbox.browser.test.js。打开时的布局闸门只挡一瞬间打开审阅页时产物会先被遮罩盖住只等第一轮真实的 iframe 审计完成就立刻揭开——无论查到什么问题。第一次完成的客户端检查即放行绝不让网络往返或修复请求绑架审阅超时有兜底超时自动放行用户还能随时点Show anyway。用--no-gate可以跳过这层幕布见 README.md 的Open-time layout gate一节。靠什么保证不误报、不吵人真实浏览器回归测试项目用真浏览器对一整组夹具页做回归test/layout-audit-browser.test.js夹具就在 test/fixtures/layout-audit/control-broken-*四类故意做坏的页面溢出、裁切、可达性、遮挡必须在桌面 移动视口下各报出预期条数real-*-clean一组真实但健康的页面产品计划、仪表盘、杂志排版、轮播、动画入场必须保持沉默断言里有一行点睛之笔detection alone must never wake an agent——检测到问题后执行 poll 仍然返回waiting修复后的产物重新加载并通过完整审计计数归零——全程 Agent 从未被唤醒。小结lavish-axi 的 iframe 布局审计把检测和修复彻底解耦对 Agent 安静检测永不触发轮询返回只有用户排队修复才产生提示对用户有用每条告警都有大白话解释、可定位、可忽略、可批量修复对状态诚实只有正向证据能清除告警失败与不确定一律显式标记。如果你也在做AI 生成 HTML 人工审阅的产品这套 src/layout-warnings.js src/artifact-sdk.js 的被动检测 保守生命周期设计值得完整读一遍源码。【免费下载链接】lavish-axiHTML is the new markdown. Lavish is the new editor for your HTML artifacts.项目地址: https://gitcode.com/gh_mirrors/la/lavish-axi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考