核心定位
qa-gate-vercel 是面向现代全栈应用的生产发布前质量关卡（Quality Gate）。它不同于单测工具（如 test-sentinel），而是扮演高级 QA 架构师角色：统筹生成测试计划、编排自动化验证流程、聚合多维度检查结果，最终给出结构化的 go/no-go 发布决策。
核心能力
1. 智能测试计划生成
- 自动扫描项目结构（API 路由、Server Actions、页面、认证流、LLM 调用点）
- 输出标准化 JSON 测试计划，覆盖 7 大验证面：API、Server Actions、UI 页面、吐司通知、认证流程、LLM 功能、数据库完整性
2. 多框架适配验证
- 检测 Vitest/Jest、Playwright/Cypress 等现有测试框架
- 生成隔离的验证测试套件（
qa-tests/目录），不污染主代码库
3. 全栈表面覆盖
- API 验证：状态码、响应 Schema、错误处理、限流、鉴权守卫
- UI/吐司验证：渲染、响应式布局、加载/错误状态、吐司出现/类型/自动消失/防重复
- 认证流验证：登录/登出完整链路、错误 case、受保护路由重定向
- Supabase 专项：RLS 策略验证、服务角色权限分离、数据库健康检查
4. LLM 输出质量双轨评估
- 规则层：长度、token 预算、延迟、必填章节、禁止模式（PII/代码泄漏/截断标记）、格式合规
- LLM-as-Judge：调用 OpenRouter（默认 google/gemini-flash-1.5）进行相关性、准确性、完整性、语调、安全性五维评分
5. 基础设施健康检查
- Vercel 部署状态（生产/预览环境就绪性）
- Supabase 数据库可达性、Auth 服务健康、Realtime 连接
6. 结构化决策报告
- JSON 机器报告 + Markdown 人工可读报告双输出
- 三级裁决：GO（无阻塞项）、NO-GO（高危阻塞）、CONDITIONAL（中危可协商）
- 自动识别 blockers/warnings，附带严重等级与修复建议
显著优势
- 发布风险可控：强制 go/no-go 决策机制，杜绝未经评估的带病上线
- LLM 质量可量化：首创规则+模型双轨评估，解决生成式 AI 输出黑盒难题
- 零侵入集成：验证代码隔离存放，不修改现有测试配置
- 现代栈深度适配：原生支持 Vercel Edge、Supabase RLS、Firebase Auth、Sonner/Shadcn Toast 等流行方案
潜在局限
- 依赖环境变量：
OPENROUTER_API_KEY、VERCEL_TOKEN、SUPABASE_URL等需用户自行配置，缺失时对应功能降级或标记为 review - 吐司检测启发式：通过 CSS 选择器匹配常见库（Sonner、react-hot-toast、Shadcn），自定义实现可能需手动补充选择器
- LLM-as-Judge 成本：每次评估消耗额外 token，高频 CI 场景建议采样或仅保留规则层
- 无自动修复：仅检测与报告，不执行代码修改（符合 QA 闸门定位）
适合人群
- 采用 Vercel + Supabase/Firebase 全栈方案的敏捷团队
- 集成 LLM 功能（内容生成、智能客服等）需输出质量保障的产品
- 缺乏专职 QA、需自动化发布把关的初创/中小团队
- 追求可审计发布流程、需标准化质量报告的企业合规场景
常规风险与建议
| 风险场景 | 缓解建议 |
|---------|---------|
| 环境变量泄露 | 所有凭证仅通过 `process.env` 在生成代码中引用，报告自动脱敏 |
| 误报吐司重复 | 为自定义吐司组件添加 `data-qa-toast` 等测试标识属性 |
| LLM 评分波动 | 设置 `temperature: 0.1` 并固定 judge 模型版本，关键场景人工复核 |
| 生产数据污染 | 强制使用测试账号与种子数据，技能内置禁止删除生产数据规则 |