name: quality-gates description: 在提交或部署前运行全面的质量检查，包括代码检查、类型检查、测试和安全审计 version: 1.0.0 author: AI-Vibe-Prompts tags: [质量, 测试, 代码检查, 安全, 持续集成持续部署] auto_invoke: true

质量门禁技能

目标

通过运行自动化检查来强制执行代码质量标准，这些检查必须在代码提交、合并或部署之前通过。充当代码库一致质量的守护者。

何时使用此技能

自动触发时机：

用户完成功能实现时
创建提交或拉取请求之前
用户要求“测试”、“验证”、“检查质量”或“确认”时
部署或发布之前
重大重构之后

质量门禁级别

级别 1：提交前门禁（快速，< 30 秒）

每次提交前运行的基本检查。

级别 2：推送前门禁（中等，< 2 分钟）

推送到远程仓库前的全面检查。

级别 3：部署前门禁（彻底，< 5 分钟）

生产部署前的完整验证。

门禁执行工作流

门禁 1：代码检查（JavaScript/TypeScript）

目的：强制执行代码风格并捕获常见错误

工具：Bash, Read

流程：

检测检查器，通过检查：
- ESLint: .eslintrc*, eslint.config.*
- Biome: biome.json
- 无：跳过此门禁

读取 package.json 以查找检查脚本：

"scripts": {
  "lint": "eslint .",
  "lint:fix": "eslint . --fix"
}

执行检查器：

# 尝试运行检查脚本
npm run lint

# 如果失败，尝试直接命令
npx eslint . || npx biome check .

解析结果：
- 退出码 0：✅ 通过
- 退出码非零：❌ 失败
- 提取错误数量和文件位置
自动修复尝试（如果发现失败）：
```
npm run lint:fix || npx eslint . --fix
```

成功标准：零个检查错误（警告可接受）

门禁 2：类型检查（TypeScript）

目的：验证类型安全并捕获类型错误

工具：Bash, Read, Grep

流程：

检测 TypeScript，通过检查：
- tsconfig.json
- 依赖项中的 TypeScript
读取 tsconfig.json 以检查严格性：
- strict: true
- noImplicitAny, strictNullChecks 等

执行类型检查器：

# 尝试运行类型检查脚本
npm run typecheck || npm run type-check

# 如果没有脚本，直接运行
npx tsc --noEmit

解析结果：
- 退出码 0：✅ 通过
- 退出码非零：❌ 失败
- 提取错误数量和位置

成功标准：零个类型错误

门禁 3：单元与集成测试

目的：验证代码功能并防止回归

工具：Bash, Read, Grep

流程：

检测测试框架：
- Vitest: vitest.config.*, 依赖项中的 vitest
- Jest: jest.config.*, 依赖项中的 jest
- 原生测试：Node.js 20+ 的 --test 标志

统计测试文件：

# 使用 Grep 查找测试文件
find . -name "*.test.*" -o -name "*.spec.*" | wc -l

执行测试：

# 运行单元测试（快速）
npm run test || npm run test:unit

# 或直接命令
npx vitest run || npx jest --ci

解析结果：
- 运行的总测试数
- 通过 / 失败 / 跳过的数量
- 覆盖率百分比（如果可用）

覆盖率检查（如果已配置）：

npm run test:coverage

# 检查是否达到阈值（例如，80%）

成功标准：

所有测试通过（100%）
覆盖率 ≥ 配置的阈值（如果设置）

门禁 4：构建验证

目的：确保代码编译和构建无错误

工具：Bash

流程：

检测构建系统：
- Next.js: next build
- Vite: vite build
- Webpack: webpack --mode production
- TypeScript: tsc
执行构建：
```
npm run build
```
检查构建产物：
- 验证输出目录是否存在：dist/, build/, .next/
- 检查日志中的构建错误

清理（可选）：

# 删除构建产物以节省空间
rm -rf dist/ build/ .next/

成功标准：构建以退出码 0 完成

门禁 5：安全审计

目的：识别依赖项中的已知漏洞

工具：Bash, Read

流程：

运行 npm/pnpm 审计：
```
npm audit --json || pnpm audit --json
```
解析审计结果：
- 严重漏洞：0
- 高危漏洞：0
- 中危漏洞：< 阈值
- 低危漏洞：信息性
检查特定漏洞：
- 原型污染
- 远程代码执行 (RCE)
- SQL 注入
- 跨站脚本 (XSS)

建议修复：

npm audit fix
# 或
npm audit fix --force  # （如果安全）

成功标准：

零个严重/高危漏洞
中危漏洞已确认或修复

门禁 6：代码复杂度分析（可选）

目的：标记可能需要进行重构的过于复杂的代码

工具：Grep, Bash

流程：

检测代码复杂度工具：
- eslint-plugin-complexity
- SonarQube
- CodeClimate

基本复杂度检查：

# 查找行数过多的文件
find src -name "*.{ts,tsx,js,jsx}" -exec wc -l {} \; | awk '$1 > 500'

# 查找深度嵌套的代码（>5 层）
grep -rn "^[[:space:]]\{20,\}" src/

# 统计 TODO/FIXME
grep -rn "TODO\|FIXME\|HACK" src/ | wc -l

成功标准：

无文件 > 500 行（仅警告）
无嵌套 > 5 层（仅警告）

门禁 7：Git 提交前检查

目的：确保提交质量并防止敏感数据泄露

工具：Bash, Grep

流程：

检查敏感数据：

# 搜索 API 密钥、密钥、令牌
git diff --cached | grep -i "api[_-]key\|secret\|password\|token"

# 检查是否提交了 .env 文件
git diff --cached --name-only | grep "\.env$"

验证提交消息（如果使用约定式提交）：
- 格式：type(scope): description
- 类型：feat, fix, docs, style, refactor, test, chore

检查文件大小：

# 标记 > 1MB 的文件
git diff --cached --name-only | xargs ls -lh | awk '$5 > 1000000'

成功标准：

差异中无密钥
无 .env 文件
无大文件 (> 1MB)

执行策略

顺序执行（默认）

按顺序运行门禁，在首次失败时停止：

检查 → 类型检查 → 测试 → 构建 → 审计

并行执行（快速模式）

同时运行独立门禁：

[检查 + 类型检查 + 测试] → 构建 → 审计

选择性执行

仅基于变更运行相关门禁：

.ts/.tsx 文件变更 → 类型检查
依赖项更新 → 审计
测试文件变更 → 仅测试

输出格式

# 质量门禁结果

## 摘要
✅ 5/7 门禁通过 | ❌ 2/7 门禁失败

## 门禁详情

### ✅ 门禁 1：代码检查
- **状态**：通过
- **耗时**：3.2秒
- **详情**：0 个错误，2 个警告

### ❌ 门禁 2：类型检查
- **状态**：失败
- **耗时**：5.1秒
- **错误**：发现 3 个类型错误
  - `src/components/Button.tsx:15` - 属性 'onClick' 缺失
  - `src/utils/api.ts:42` - 类型 'string' 无法分配给类型 'number'
  - `src/hooks/useAuth.ts:8` - 找不到名称 'User'

### ✅ 门禁 3：测试
- **状态**：通过
- **耗时**：12.4秒
- **测试**：124 个通过，0 个失败，2 个跳过
- **覆盖率**：87%（目标：80%）

### ⏭️ 门禁 4：构建
- **状态**：已跳过（前一门禁失败）

### ⏭️ 门禁 5：安全审计
- **状态**：已跳过（前一门禁失败）

## 需要采取的行动
在继续之前修复门禁 2 中的 3 个类型错误。

## 建议
1. 本地运行 `npm run typecheck` 以查看完整的错误详情
2. 考虑添加提交前钩子以更早地捕获这些错误
3. 当前代码覆盖率（87%）超过目标 - 干得漂亮！

与 Git 钩子集成

设置 Husky + lint-staged（推荐）

检查是否已安装：

test -d .husky && echo "Husky 已安装" || echo "未找到 Husky"

如果缺失，建议安装：

npm install --save-dev husky lint-staged
npx husky init

配置 .husky/pre-commit：

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

# 运行质量门禁
npm run lint
npm run typecheck
npm run test

替代方案：使用手动检查的 git commit -m

如果没有钩子，提示用户：

⚠️  未检测到提交前钩子。
您希望我在提交前运行质量门禁吗？（推荐）

渐进式质量门禁

级别 1：基本（始终运行）

代码检查
类型检查

级别 2：标准（推送前）

基本 +
单元测试
安全审计

级别 3：全面（部署前）

标准 +
集成测试
端到端测试
构建验证
性能测试

错误恢复

自动修复能力

检查错误：运行 eslint --fix 或 biome check --apply
格式错误：运行 prettier --write
安全漏洞：运行 npm audit fix

需要手动修复

类型错误
测试失败
构建错误

绕过（谨慎使用）

# 仅在紧急修复时跳过钩子
git commit --no-verify -m "紧急：修复关键错误"

最佳实践

快速失败：在首次关键失败时停止以节省时间
清晰反馈：始终显示哪个门禁失败及原因
可操作：提供修复问题的确切命令
可配置：尊重项目的质量阈值
性能：尽可能缓存结果
增量：在适当时仅检查已更改的文件

配置

从 package.json 读取

{
  "qualityGates": {
    "coverage": {
      "minimum": 80,
      "enabled": true
    },
    "audit": {
      "level": "moderate",
      "enabled": true
    },
    "complexity": {
      "maxLines": 500,
      "maxDepth": 5
    }
  }
}

默认设置

如果未找到配置，使用合理的默认值：

最低覆盖率：70%
审计级别：仅高危/严重
最大文件行数：500
最大嵌套层数：5 层

与其他技能的集成

codebase-analysis - 用于检测可用的质量工具
git-workflow - 与提交/推送流程集成
ci-cd-setup - 为 CI 流水线配置门禁

版本历史

1.0.0 (2025-01-03)：初始技能，包含 7 个质量门禁和渐进式执行