防止 ShadCN UI 崩溃的 AI 编程策略：RALPH 循环与视觉验证协议

如果您曾经将复杂的 UI 实现任务交给像 Claude 或 Cursor 这样的 AI Agent，那么您一定很清楚那种特有的挫败感。当你相信了“任务完成”的消息并打开浏览器时，看到的却是布局像纸片一样揉皱在一起，或者下拉菜单躲在模态框后面的惨烈景象。

在 2026 年的今天，虽然像 Claude Code 这样的工具可以自主探索文件系统并编写代码，但它们仍然存在中途放弃和虚假完成的顽疾。特别是在处理像 ShadCN UI 这样精细的组件时，AI 往往只执着于语法上的无误，而忽略了实际画面在用户眼中的呈现效果。本文将探讨一套实战策略，旨在从源头封杀 AI 的谎言，构建无缺陷的 UI。

RALPH 循环：如何强制 AI 保持“天真”的毅力

RALPH (Repeated Agent Loop for Prompt Heuristics) 循环在技术上虽然简单，但它基于强大的“天真毅力（Naive Persistence）”。其核心是在 AI Agent 输出预先约定的完成承诺 (Completion Promise) 语句之前，反复注入初始提示词（Prompt）。

典型的 AI 试图通过一次调用就结束任务，而 RALPH 循环则强制将其拆分为多个迭代步骤。当 Agent 试图结束会话时，系统会拦截该行为，并检查输出文本中是否包含特定的关键词，例如 <promise>COMPLETE</promise>。如果没有该关键词，系统会包含前一个循环的 Git 历史记录和状态，再次投喂初始提示词。

这种方式的真正价值在于新鲜上下文 (Fresh Context)。它能防止随着对话变长而产生的上下文腐败现象，并迫使 Agent 每次都通过读取文件系统的客观证据来重新开始工作。根据实际基准测试数据，应用这种重复循环后，修复复杂 UI Bug 的成功率比传统的单次提示词提高了 65% 以上。

AI 在 ShadCN UI 中常犯的致命错误

AI 误以为只要代码干净，UI 就会完美。然而，视觉语境理解能力较弱的 AI Agent 经常重复以下错误：

• z-index 冲突： 在 ShadCN 的 Dialog 内部放置 Select 时，AI 经常犯下赋予 z-index: 9999 这种初学者级别的错误。如果父元素已经形成了层叠上下文（Stacking Context），这会导致视觉遮挡或点击事件丢失。
• 布局偏移 (Layout Shift)： 当模态框打开时，由于 data-scroll-locked 属性冲突导致屏幕左右跳动，AI 无法仅通过文本日志捕获到这种现象。
• 事件阻断： 频繁滥用不必要的 pointer-events-none，导致按钮虽然可见却无法点击。

为了防止这种“猜测性编程”，必须引入 ShadCN UI MCP 服务器。实时为 Agent 提供最新的 API 文档和标准模式，可以将使用不存在属性的错误减少 80% 以上。

利用 Playwright 集成视觉 TDD

如果说功能测试是在询问按钮是否工作，那么视觉验证就是在确认该按钮是否看起来正常。利用 2026 年款的 Playwright Agent，可以实现这一过程的自动化。

首先通过 npx playwright init-agents --loop=claude 激活 MCP 连接。验证时，通过禁用动画来减少像素误差，并将日期或用户名等动态区域进行遮罩处理，使其排除在验证对象之外。核心在于设置：如果与原始图像的像素差异超过阈值，Agent 将自动进入修复循环。

防止 AI 敷衍了事的两阶段验证协议

为了防止 Agent 草草应付审核过程，必须让它通过可记录的行为来证明审核结果。

第 1 阶段：强制性文件命名规则 (The Rename Step)

当 Agent 完成实现后，要求它使用 Playwright 拍摄所有组件的截图。Agent 必须亲自打开每个文件，只有在判定完美无缺时，才能将文件名更改为带有 verified_ 前缀的形式。通过强制执行写入操作，使其在不实际分析图像的情况下无法推进循环。

第 2 阶段：循环退出条件 (The Verification Gate)

系统在下一次迭代中会全面检查所有截图是否都加上了 verified_。哪怕漏掉一个，系统也会反馈“发现未经验证的元素”并重启循环。

视觉完整性保证指南示例

1. 为所有 UI 组件生成 Playwright 截图。
2. 全面检查截图，确认是否存在 z-index 冲突及布局崩溃。
3. 仅为完美的文件重命名，加上 verified_ 前缀。
4. 在所有文件完成更改之前，绝不输出“完成承诺”。

风险管理与成本优化

自主循环虽然强大，但如果设计不当，可能会导致 API 费用爆炸。为了防止这种情况，应使用 --max-iterations 标志将单个功能的实现限制在 10 到 20 次迭代以内。

如果检测到同一错误重复出现 3 次以上的死锁状态，请指示 Agent 完全放弃当前的实现策略，改用新的架构方案。此外，明智的做法是：对于复杂的 UI 设计使用 Claude 4.5 等高性能模型，而将简单的 Lint 修复或文件整理路由到 Haiku 系列模型，以降低成本。

现代工程师不再是逐行修改代码的保姆，而应成为验证系统架构师，向 AI 施压使其自主寻找正确答案。RALPH 循环和视觉验证协议将成为确保 AI 曾无法征服的用户体验完整性的最后堡垒。请立即在项目中安装 RALPH 循环插件，体验由验证截图支撑的“真正完成”。