在为客户开发 WordPress FSE 主题时遇到此问题，记录根因与解法。
Gutenberg 升级后，gradient 的 CSS class 命名规则从 has-{slug}-gradient 变为 has-{slug}-gradient-background。手写 Pattern HTML 中的旧 class 与 Gutenberg 验证逻辑不匹配，导致 Site Editor 报错。解决方案是批量替换 class 名称。
WordPress FSE Group 块的 layout 属性会自动生成 is-layout-* CSS 类，这些类的样式优先级高于普通自定义 CSS，导致尺寸设置失效。解决方案：1) 块注释中使用 "layout":{"type":"default"} 避免生成额外布局类；2) CSS 中使用 !important 强制覆盖；3) 关键：添加 padding: 0 !important 清除 Group 块默认内边距。
在为客户开发 WordPress FSE 企业主题时，发现 Footer 区块在多个 Style Variation 下文字几乎不可见。本文记录从 WCAG 对比度诊断到引入语义色、处理全局样式覆盖的完整修复过程。
问题：FSE 主题的 contrast 颜色 token 语义混乱，浅色主题中 contrast ≈ 浅灰 ≈ base（白色），导致 Footer 对比度仅 1.05:1。
解法：
surface 语义色，专用于深色区块背景wp_global_styles 中的覆盖样式结果：对比度从 1.05:1 提升至 15.8:1（WCAG AAA 级）。
在为客户开发 WordPress FSE 主题时，频繁遇到 Block Pattern 验证失败问题。本文总结 5 种常见原因与解决方案。
块验证失败通常是以下原因之一：颜色 slug 未定义、JSON 重复 key、Style Variation 调色板覆盖、HTML 属性与块注释不一致、全局样式覆盖 theme.json。逐一排查即可解决。
官方 WordPress Docker 镜像不含 WP-CLI。在 docker-compose.yml 中添加 command 配置，容器启动时自动下载安装 WP-CLI，无需手动进入容器操作。
在为客户构建 AI Agent 平台时遇到此问题：需要支持多个搜索提供商（Tavily、Serper、Brave、Bing），同时确保工具调用失败时不会中断 Agent 对话流程。
SearchProvider 抽象基类 + SearchResult 数据模型，统一接口和输出格式search() 方法，内部做响应字段映射SearchResult 对象，而非抛异常在构建 AI Agent 平台时遇到此问题，记录根因与解法。
使用 page.route() 拦截所有 API 请求，返回预定义的 mock 数据。测试不依赖真实后端，可以在任何环境稳定运行，且避免创建/删除数据等副作用。
在构建 AI Agent 平台时遇到此问题，记录根因与解法。
使用 Playwright 的 test.extend() 创建自定义 fixture，通过 page.addInitScript() 在页面加载前注入 auth token 到 localStorage。测试用 authenticatedPage 替代 page，自动获得登录状态，无需每个测试重复登录。
在为客户构建 AI Agent SaaS 平台时遇到此问题，记录根因与解法。
E2E 测试不应该依赖真实的 OAuth 登录流程。通过在 useAuth hook 中检测 localStorage 的测试标记，直接注入 mock 认证状态，跳过 Supabase 初始化。同时将 Zustand store 的 loading 默认值改为 false，避免 AuthGuard 卡在无限 spinner。
在开发 AI Agent 对话界面时遇到此问题，记录根因与解法。
Date.now() 毫秒级时间戳可能在同一毫秒内重复，作为 React 列表 key 会导致 DOM 报错。解决方案是添加随机后缀，或使用 crypto.randomUUID()。