用途
Fullstack Debugger 是一个专家级调试技能，用于对现代 Web 技术栈进行系统化、基于证据的故障排查。其目标技术栈包括 Next.js 15、Cloudflare Workers、Supabase 以及边缘部署。它适用于定位和修复认证、缓存、Workers、RLS、CORS 和构建等方面的问题。
该技能在以下触发词出现时激活："debug"、"not working"、"broken"、"error"、"500 error"、"401"、"403"、"cache issue"、"CORS error"、"RLS policy"、"auth not working"、"blank page"、"hydration error"、"build failed"、"worker not responding"。它不适用于功能开发（应使用语言技能）、架构设计（应使用 system-architect）或性能优化（应使用 performance-engineer）。
主要能力
该技能遵循一套调试哲学：先复现问题，再隔离故障层，收集日志/网络/状态证据，提出假设，逐一测试验证，做最小修复，最后验证修复不会破坏其他功能。
它按五个架构层级组织排查：
- 第 1 层：浏览器/客户端——控制台错误、网络面板、React DevTools、localStorage/sessionStorage 状态、React Query 缓存状态。
- 第 2 层：Next.js 应用——服务端组件与客户端组件、构建输出与静态生成、API 路由、水合不匹配。
- 第 3 层：Cloudflare Workers——Worker 日志（wrangler tail）、KV 缓存状态、CORS 头、速率限制。
- 第 4 层：Supabase——认证状态与 JWT 令牌、RLS 策略（最常见问题）、数据库查询与索引、实时订阅。
- 第 5 层：外部 API——第三方服务可用性、API 速率限制、响应格式变化。
该技能提供快速诊断命令，包括一次性检查构建、TypeScript、Lint 和 Git 状态；Supabase RLS 诊断脚本；Worker 健康检查（curl 检查状态码、CORS 头、wrangler tail 流式日志）；以及 Cloudflare KV 缓存检查（列出、获取、删除缓存键）。
常见问题与解决方案
技能覆盖十类常见问题，每类均包含症状、诊断方法和修复方案：
- RLS 策略阻止数据（最常见）——查询返回空数组但无错误、在 Supabase 仪表板可用但应用不可用、部分用户可用部分不可用。诊断包括查询 pg_policies、以 anon 和 authenticated 角色测试。修复示例包括允许公开读取、允许认证用户读取、允许用户读取自己的数据。
- CORS 错误——fetch 被 CORS 策略阻止、Postman 可用但浏览器不可用、预检请求失败。修复示例为在 Cloudflare Worker 中设置 CORS 头并处理 OPTIONS 预检。
- 认证状态不持久——登录后刷新显示未登录、本地可用但生产不可用、会话随机消失。诊断包括在浏览器控制台检查 session、user 和 localStorage。修复包括检查 Supabase URL 匹配、验证站点 URL 设置、检查 cookie 阻止、确保 AuthContext 包裹组件。
- 水合不匹配——初始 UI 不匹配导致水合失败、页面加载时内容闪烁、服务端与客户端内容不同。修复示例为使用仅客户端渲染。
- Worker 未部署——部署命令成功但更改未生效、旧代码仍在运行、新旧行为交替。诊断包括检查部署状态、查看当前 Worker 代码、检查多环境。修复包括强制重新部署和清除 Cloudflare 缓存。
- TypeScript 缓存问题——错误引用已删除/更改的代码、类型与当前代码不匹配、现有文件报“Cannot find module”。修复为清除 .next、node_modules/.cache、tsconfig.tsbuildinfo 等缓存。
- 静态导出问题——页面无法静态渲染、动态路由在静态导出中失败、API 路由部署后不工作。修复示例为设置 dynamic = 'force-dynamic' 或使用 generateStaticParams。
- 速率限制问题——多次请求后出现 429 错误、初始可用后停止、不同 IP 行为不同。诊断包括检查速率限制头和 KV 键。修复包括清除某 IP 的速率限制、调整 wrangler.toml 中的限制。
- 会议/位置数据问题——某些区域找不到会议、会议数据陈旧、缓存显示错误数据。诊断包括检查缓存状态头、强制缓存刷新、检查 Supabase 会议数量。
- Cloudflare Pages 构建失败——本地可用但部署失败、模块未找到错误、内存超限。诊断包括本地生产构建、检查条件导入、检查包大小。修复示例为调整 next.config.ts 内存和 webpack 外部依赖。
使用方式
该技能提供调试脚本，包括 scripts/diagnose.sh（运行环境、依赖、TypeScript、构建、Workers、Supabase 全部诊断）和 scripts/check-rls.js（检查 RLS 策略是否正确工作，检查 profiles、meetings、forum_posts、journal_entries 等关键表）。
它还提供验证清单：能否一致复现问题、确定失败层级、检查浏览器控制台、检查网络面板、检查 Worker 日志、验证 RLS 策略、用全新浏览器/无痕模式测试、清除所有缓存、检查环境变量与生产匹配、验证 CORS 头、在生产 URL 测试、创建最小复现案例。
调试输出应始终包含：根本原因、证据（日志/错误/查询）、修复（最小代码更改）、验证方法、预防措施。
可用工具包括：Read、Write、Edit（文件操作）、Bash（运行命令、curl、wrangler）、Grep、Glob（搜索代码库）、WebFetch（测试端点）、mcp__supabase__（直接 Supabase 操作）、mcp__playwright__（浏览器自动化 UI 测试）。
适用场景
适用于使用 Next.js 15、Cloudflare Workers、Supabase 和边缘部署的现代 Web 应用在开发或生产环境中出现故障时进行系统化排障，尤其适合处理认证、缓存、RLS、CORS、构建和部署类问题。
限制
该技能不用于功能开发、架构设计或性能优化。其诊断命令和修复示例中的 URL、密钥、表名、命名空间 ID 等均为占位符，需替换为实际值。部分修复方案（如 CORS 允许来源、速率限制数值）需根据实际环境调整。