在 WSL2 环境下使用 Claude Code、Roo 等 AI 编程工具时，工具需要通过 Windows 宿主机代理访问 API，却反复报 ConnectionRefused。解决防火墙问题后，又遇到两个隐藏坑。记录完整排查过程。

TL;DR​

WSL2 的 vEthernet (WSL) 虚拟网卡每次启动重建，Windows 防火墙无法为其分配 Network Profile，导致所有入站规则对这个接口都不生效（EnforcementStatus: NotApplicable）。不需要加规则，直接对接口禁用防火墙即可：

# 在 Windows PowerShell (管理员) 中执行
Set-NetFirewallProfile -DisabledInterfaceAliases "vEthernet (WSL)"

此外，修复防火墙后，还可能遇到两个额外坑：

1. 动态 IP 问题：宿主机 IP 在 WSL/Windows 重启后变化
2. 配置缓存问题：~/.claude.json 和 ~/.claude/settings.json 里缓存了旧 API key 导致认证冲突

在为客户开发 WordPress FSE Block Theme 并集成 WooCommerce 时，遇到 4 个 WooCommerce 静默篡改主题样式的陷阱。每个都很隐蔽，排查耗时。记录根因与解法，帮助同样开发 FSE + WooCommerce 主题的开发者避坑。

TL;DR​

1. 字号预设覆盖：WooCommerce 注册 small/medium/large/x-large 四个预设覆盖 theme.json，用 h-1~h-6 自定义 slug 规避
2. font-size class 连字符：has-h-1-font-size(48px) vs has-h1-font-size(20px)，手写 HTML 必须带连字符
3. contrast 颜色反转：--wp--preset--color--contrast 被 WooCommerce 改为浅色（#f8fafc），白色文字完全不可见
4. ul.products 伪元素：WooCommerce 注入 ::before/::after 破坏 CSS Grid 布局，需 display:none 清除

在使用 智谱 GLM 编码套餐 进行日常开发时，发现一个容易被忽视的额度消耗问题：智谱内置的 MCP 联网搜索和网页读取工具，每次调用都消耗编码套餐额度。本文记录排查过程和用 Tavily MCP 替代的方案。

TL;DR​

智谱 GLM 编码套餐内置 web-search-prime 和 web-reader 两个 MCP 服务，每次搜索/读取消耗对话额度。替换为 Tavily MCP 后，联网搜索使用独立免费额度（1000 次/月），不再挤占编码对话用量。

在为客户开发 WordPress FSE Block Theme 时，遇到风格预览显示异常和首页编辑白屏两个问题。记录根因与解法。

TL;DR​

1. Style variation 的 palette/gradients 是整体替换而非合并，只写 1 个颜色会丢失其余全部 -- 必须补全完整列表，只改需要变化的颜色。
2. front-page.html 模板硬编码 pattern 会导致 Site Editor 编辑白屏，且用户无法在编辑器中调整布局 -- 应改为页面内容驱动。

在为客户构建 AI Agent 系统时，我们发现不同任务对模型能力和成本的需求差异很大：图像分析用视觉模型、文本补全用轻量模型、内部数据查询用本地模型。MCP（Model Context Protocol）让每个能力变成独立的工具，AI 客户端按需调用。

TL;DR​

用 Python FastMCP 30 分钟搭建自定义 MCP Server，按场景和成本接入任意 OpenAI 兼容 API。本文以豆包视觉模型为例演示完整流程，并提供文本生成、图像生成、语音合成等场景的扩展模板。

在为客户开发 WordPress FSE Block Theme 时发现：博客列表页的卡片悬浮时文字区域发生偏移，但卡片外框不动，视觉上非常违和。记录根因与解法。

TL;DR​

通用卡片 hover 选择器 .wp-block-columns .wp-block-column > .wp-block-group:hover 会匹配到卡片内部嵌套的文字 group，导致悬浮时内层文字偏移而外层卡片不动。修复方式：用 .wp-block-post-template 前缀重置内层 group 的 hover 效果。

TL;DR​

用 ::before 伪元素实现容器背景装饰纹理（圆点/网格）时，必须同时设置 opacity、pointer-events: none 和 z-index: -1。缺少 opacity 导致纹理 100% 不透明，缺少 z-index 导致纹理覆盖按钮等子元素。

在为客户开发 WooCommerce FSE Block Theme 时遇到这两个问题：Cart Block 空车时页面白屏、商品无特色图片时卡片高度塌陷。记录根因与解法。

TL;DR​

1. Cart Block 必须显式声明 filled-cart-block 和 empty-cart-block 子块，否则空车时无任何内容输出。
2. 商品无特色图片时，FSE 的 post-featured-image 块渲染为空字符串，导致卡片高度塌陷。通过 post_thumbnail_html filter 补上 WooCommerce 占位图。

TL;DR​

WordPress FSE 主题的 Pattern/Template 文件中，HTML 注释里的 JSON 属性如果某个字符串值缺少闭合引号 "，花括号数量仍然平衡，但 parse_blocks() 会静默将该块的 attrs 置为 null。Gutenberg 的 save 函数因此不输出 inline style，触发 Block validation failed。用 json.loads() 验证 JSON 合法性即可定位。

在为客户开发 WordPress FSE 主题时遇到此问题，记录根因与解法。

TL;DR​

Gutenberg 升级后，gradient 的 CSS class 命名规则从 has-{slug}-gradient 变为 has-{slug}-gradient-background。手写 Pattern HTML 中的旧 class 与 Gutenberg 验证逻辑不匹配，导致 Site Editor 报错。解决方案是批量替换 class 名称。