Ai Quality Gate

AI Quality Gate

用于 AI 代码质量自动化的 MCP 服务。

---

功能

AI 编写代码 → 调用 quality_fix → 服务修复可修复的问题 → 向 AI 报告剩余问题。

混合方案：

• 阶段 1： ESLint + 627 条规则 + Prettier（约 2-8 秒，始终运行）
• 阶段 2： SonarQube Server（约 30-60 秒，可选）

重要：ESLint 与 Prettier 的区别

工具	来源	配置
ESLint	项目的配置（如果存在），否则使用 MCP 内置配置	.eslintrc.* / eslint.config.* / MCP 内置配置
Prettier	项目自有配置	项目的 prettier.config.mjs

ESLint 规则由 MCP 控制，以确保质量门禁的一致性。 Prettier 使用项目的配置，使格式化结果符合项目偏好。

阶段 1 规则覆盖范围：

插件	规则数	描述
SonarJS	201	安全、缺陷、代码异味
Unicorn	127	现代 JavaScript 最佳实践
ESLint Core	108	JavaScript 基础知识
TypeScript-ESLint	99	TypeScript 专属规则
RegExp	60	正则表达式最佳实践
Import	11	导入/导出规则
Promise	10	Async/await 最佳实践
Node.js (n)	9	Node.js 专属规则
Unused Imports	2	自动移除未使用的导入
总计	627

---

安装

前提条件

• Node.js 20.10+ 或 21.1+，且已添加到 PATH 中（node -v）。
• 已启用 MCP 的 Cursor、Antigravity、OpenCode（或其他支持 MCP 的编辑器）。

省略 PROJECT_ROOT 时会自动检测项目根目录：服务会从 MCP 进程的工作目录逐级向上查找，直到找到 package.json 或 tsconfig.json。只有在要分析的目录树与推断出的根目录不同时，才需在 env 中设置 PROJECT_ROOT。

---

MCP 配置（Cursor）

打开设置 → 工具与 MCP → 编辑（用户级 mcp.json）。添加一个服务配置块；以下示例与 .cursor/mcp.json.example 一致（使用带注释的 JSONC — 如果编辑器不接受注释，只复制下面的 JSON 配置块）。

服务名称与工具名称： mcpServers 下的键（例如 "ai-quality-gate"）仅用作 Cursor 中此连接的标签。Agent 调用的 MCP 工具始终是 quality_fix — 该名称由此软件包固定，与服务键及 ai-quality-gate 相互独立。

A) 推荐：npx（无需全局安装）

始终运行已发布的软件包，适合团队和类似 CI 的设置。

{
  "mcpServers": {
    "ai-quality-gate": {
      "command": "npx",
      "args": ["-y", "ai-quality-gate"]
    }
  }
}

B) 可选：全局 npm 安装

运行 npm i -g ai-quality-gate 后，ai-quality-gate 二进制文件会位于 PATH 中：

{
  "mcpServers": {
    "ai-quality-gate": {
      "command": "ai-quality-gate",
      "args": []
    }
  }
}

C) SonarQube（阶段 2）

需要正在运行的 SonarQube 实例、可用的 sonar-scanner（参见 SonarQube 设置），以及下方的全部三个变量。阶段 1 仍会先运行。

{
  "mcpServers": {
    "ai-quality-gate": {
      "command": "npx",
      "args": ["-y", "ai-quality-gate"],
      "env": {
        "SONAR_HOST_URL": "http://localhost:9000",
        "SONAR_TOKEN": "your_sonar_token",
        "SONAR_PROJECT_KEY": "your_project_key"
      }
    }
  }
}

D）可选环境变量（适用于任何服务）

需要覆盖配置时，添加一个 "env" 对象。配置的合并顺序为 默认值 → .quality-gate.yaml / .quality-gate.json → 环境变量。

变量	设置时机
QUALITY_GATE_CONFIG	指向特定 .quality-gate.yaml 或 .quality-gate.json 的绝对路径（跳过目录遍历）。
PROJECT_ROOT	自动检测不适合你的项目布局时，强制指定项目根目录。
SONAR_HOST_URL	SonarQube 服务 URL（用于 Phase 2）。
SONAR_TOKEN	SonarQube 令牌（用于 Phase 2）。
SONAR_PROJECT_KEY	SonarQube 项目密钥（用于 Phase 2）。
SONAR_SCANNER_PATH	sonar-scanner 不在 PATH 中时，指定其完整路径。
PHASE1_TIMEOUT	Phase 1 超时时间（毫秒），默认值为 30000。
PHASE2_TIMEOUT	Phase 2 超时时间（毫秒），默认值为 300000。
ENABLE_I18N_RULES	true / false — 为 i18n 项目启用更严格的 JSX 字面量检查。

---

MCP 配置

Cursor、Antigravity 等

{
  "mcpServers": {
    "ai-quality-gate": {
      "command": "npx",
      "args": ["-y", "ai-quality-gate"]
    }
  }
}

（OpenCode）

创建或编辑 OpenCode 配置（通常为 ~/.config/opencode/opencode.json 或项目级配置）：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "ai-quality-gate": {
      "type": "local",
      "enabled": true,
      "command": ["npx", "-y", "ai-quality-gate"]
    }
  }
}

如有需要，可在服务配置下添加环境变量（参见上文 C）SonarQube（Phase 2））。

---

本地开发（此仓库）

如需试用或参与贡献：

1. yarn build — 生成 dist/server.js。
2. 将 MCP 指向构建后的文件（使用绝对路径）：

{
  "mcpServers": {
    "ai-quality-gate-dev": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/ai-quality-gate/dist/server.js"]
    }
  }
}

3. 重新加载 MCP。仅当你分析的仓库与推断出的根目录不同时，才使用 env.PROJECT_ROOT。

---

2. 添加 AI 规则

Settings → Rules and Commands → Add Rule：

After every code change, before telling the user "done",
AI must call the quality_fix MCP tool. This is mandatory.

3. 使用

AI writes code → calls quality_fix → Fixes errors → "Done ✅"

---

CLI：交互式配置（--setup）

交互式向导无需手动编辑，即可创建或更新 .quality-gate.yaml：它会引导你设置项目根目录、可选的 SonarQube 配置（主机 URL 和项目密钥；令牌不会保存到磁盘 — 请在环境中使用 SONAR_TOKEN）、要启用的 Phase 1 工具（ESLint、大括号 / 箭头 AST 修复器、Prettier、JSON 验证器）、超时时间和 i18n 规则。生成的文件包含一个 fixers: 块，你之后可以调整。

运行 yarn build（或从 npm 安装）后，在目标项目目录（或其下的任意路径）运行：

node dist/server.js --setup

未设置时会推断 PROJECT_ROOT（参见 MCP 配置）。使用与 MCP 服务相同的入口点（node dist/server.js 或 npx ai-quality-gate）；只有 --setup 标志会切换到向导模式。在终端中回答提示；成功后，你会在项目根目录旁获得一份可直接使用的配置文件。

其他 CLI 模式： --check（只读 Phase 1）、--fix（使用 CLI 质量检查时的默认行为）、--phase1-only、--phase2-only — 参见 docs/DEVELOPMENT.md。

---

可选：SonarQube Server（Phase 2）

按照上文 C）SonarQube（Phase 2） 中的说明，在 MCP 中配置 Sonar 环境，或从 .cursor/mcp.json.example 复制配置。你需要在计算机上安装 sonar-scanner 以进行分析（见下文）。

SonarQube 配置

Docker（推荐）

# Start SonarQube
docker run -d --name sonarqube -p 9000:9000 sonarqube:community

# First login: admin/admin → change password
# http://localhost:9000

Docker Compose

# docker-compose.yml
version: '3'
services:
  sonarqube:
    image: sonarqube:community
    ports:
      - '9000:9000'
    volumes:
      - sonarqube_data:/opt/sonarqube/data
      - sonarqube_logs:/opt/sonarqube/logs
      - sonarqube_extensions:/opt/sonarqube/extensions

volumes:
  sonarqube_data:
  sonarqube_logs:
  sonarqube_extensions:

docker-compose up -d

创建 SonarQube 令牌

1. http://localhost:9000 → 登录（admin）
2. 我的帐户 → 安全 → 生成令牌
3. 选择令牌类型：全局分析令牌
4. 复制令牌 → 用作 SONAR_TOKEN

安装 sonar-scanner

平台	方法	命令
Windows	npm (global)	npm install -g sonarqube-scanner
Windows	Chocolatey	choco install sonar-scanner
macOS	npm (global)	npm install -g sonarqube-scanner
macOS	Homebrew	brew install sonar-scanner
Linux	npm (global)	npm install -g sonarqube-scanner
Docker	容器	docker run sonarsource/sonar-scanner-cli

自定义路径：SONAR_SCANNER_PATH 环境变量

---

配置

可选文件（从推断出的项目根目录向上遍历查找——使用与 package.json / tsconfig.json 相同的算法——或在设置了 PROJECT_ROOT 时从该目录开始查找）：.quality-gate.yaml（优先）或 .quality-gate.json。字段与环境变量相同（camelCase）；你可以将 Sonar 设置嵌套在 sonar: { hostUrl, token, projectKey, scannerPath } 下。

合并顺序：默认值 → 配置文件 → 环境变量（冲突时以 ENV 为准）。

设置 QUALITY_GATE_CONFIG 为显式路径以跳过自动查找。

自定义规则（customRules）

可选的针对可检查文件的按行正则表达式检查（阶段 1）。每个匹配项都会作为问题报告，rule 设置为 custom:<id>（并包含在 quality_fix 的 remaining 中）。示例：

customRules:
  - id: no-console
    message: 'Console.log is not allowed'
    pattern: 'console\\.log\\('
    severity: error
  - id: no-debugger
    message: 'Debugger statement found'
    pattern: 'debugger'
    severity: warning

模式使用 JavaScript RegExp 源码（在 YAML 字符串中按需转义反斜杠）。无效模式会被跳过，并在 warnings 中说明。

JSON 验证器和 i18n 区域设置文件

启用 fixers.jsonValidator 并传入与区域设置模式匹配的 JSON 路径（例如 locales/en.json / locales/tr.json）时，工具会比较这些文件中的键。

• 语法错误、无效的 UTF-8 BOM 等 → 报告为 issues，并在修复前导致阶段 1 / quality_fix 失败。
• 区域设置文件之间缺失或多余的键 → 在验证器结果中收集为 i18nIssues，并在阶段 1 期间作为 警告输出到 stderr。它们不会将 passed: false，也不会阻止门禁通过。

除非你另外添加自己的 CI 检查，否则请将 i18nIssues 视为提示信息。

---

环境变量

所有变量均为可选，除非使用 Phase 2；Phase 2 要求同时设置 SONAR_HOST_URL、SONAR_TOKEN 和 SONAR_PROJECT_KEY。

变量	描述	示例
QUALITY_GATE_CONFIG	.quality-gate.yaml 或 .quality-gate.json 文件的绝对路径。跳过向上遍历父目录以发现配置。	/app/ci/quality-gate.yaml
PROJECT_ROOT	覆盖检测到的项目根目录。默认：从进程 cwd 开始向上遍历，直到找到 package.json 或 tsconfig.json。	/Users/me/my-repo
SONAR_HOST_URL	SonarQube 服务基础 URL（Phase 2）。	http://localhost:9000
SONAR_TOKEN	SonarQube 身份验证令牌（Phase 2）。建议使用环境变量 / 密钥存储；避免提交。	sqa_xxx...
SONAR_PROJECT_KEY	SonarQube 项目密钥（Phase 2）。	my-project
SONAR_SCANNER_PATH	sonar-scanner 可执行文件的完整路径（如果它不在 PATH 中）。	/opt/sonar-scanner/bin/sonar-scanner
PHASE1_TIMEOUT	Phase 1 子进程超时时间，单位为毫秒。	30000（默认值）
PHASE2_TIMEOUT	Phase 2（Sonar）超时时间，单位为毫秒。	300000（默认值）
ENABLE_I18N_RULES	设为 true，以启用 ESLint 规则，标记 JSX 中的原始字符串字面量（适用于 i18n 工作较多的应用）。	false（默认值）

---

自动修复

Phase 1 会自动修复以下问题：

ESLint 自动修复（约 100 多条规则）

// var → const/let
var x = 1        →  const x = 1

// forEach → for...of (unicorn/no-array-for-each)
arr.forEach(x => f(x))  →  for (const x of arr) f(x)

// Nested ternary → extracted (unicorn/no-nested-ternary)
a ? b : c ? d : e  →  const temp = c ? d : e; a ? b : temp

// Unused imports removed
import { unused } from 'x'  →  (removed)

// Type imports (consistent-type-imports)
import { Type } from 'x'  →  import type { Type } from 'x'

// Optional chain (prefer-optional-chain)
a && a.b && a.b.c  →  a?.b?.c

// Regex optimization (regexp/*)
/[0-9]/  →  /\d/

AST 自动修复

// Remove unnecessary curly braces (single-line if)
if (x) { return true }  →  if (x) return true

Prettier 格式化

ESLint 修复后，Prettier 会运行以确保格式一致：

// ESLint removes braces but leaves awkward format:
if (x) return true

// Prettier fixes to single line:
if (x) return true

注意： Prettier 使用项目的配置，而不是 MCP 的配置。

其他所有问题： 报告给 AI，由 AI 修复。

---

API

工具：quality_fix

// Input
{
  files: string[] // File paths to check
}

// Output
{
  phase: "local" | "server" | "complete",
  success: boolean,
  message: string,
  fixed: {                 // a FixSummary: edits on disk, kept even when findings remain
    eslint: number,          // ESLint auto-fixes
    curlyBraces: number,   // AST: single-statement if braces
    singleLineArrow: number, // AST: arrow body style
    prettier: number,      // Prettier formatting
    json: number           // JSON files validated (not an edit, so not part of fixedCount)
  },
  fixedCount: number,      // Edits on disk: the sum of `fixed`, without `json`
  attempted?: FixSummary,  // same fields as `fixed`: edits tried before a rollback, not on disk after a successful one
  attemptedCount?: number, // The sum of `attempted`
  warnings?: string[],     // Things the gate could not do that do not fail the run (a file a fixer skipped, a custom rule it could not apply)
  remaining: Issue[],      // Findings left to fix by hand. Line numbers refer to the files as they are now (line 0 = location unknown)
  remainingCount: number,  // remaining.length
  totalIssues: number,     // fixedCount + remainingCount
  error?: {                // Set when the run could not finish: e.g. ROLLBACK_FAILED, SONAR_API_ERROR, PERSISTENT_FAILURE
    code: string,
    message: string,
    details?: object       // ROLLBACK_FAILED: { unrestoredFiles, restoredFiles }
  },
  checks?: object,         // Raw typecheck and lint results, in read-only check mode
  timing: {
    phase1: string,
    phase2?: string,
    total: string
  }
}

一次失败的运行会在磁盘上留下什么。 质量门禁会应用所有可应用的修复并保留它们。无法修复的问题（某条 lint 规则、自定义规则，或无法证明可以安全修改的 ==）会放入 remaining 并返回 success: false；保留的修复计入 fixed。只有修复器自身导致问题时，运行才会回滚：修复后出现类型错误、编译器拒绝某个 Vue 文件，或 ESLint、Prettier 无法运行。此时 fixed 为零，尝试过的编辑会列在 attempted 中。如果回滚本身失败，响应为 ROLLBACK_FAILED：error.details.unrestoredFiles 列出可能仍保留这些编辑的文件，phase 表示失败阶段，而 remaining 则列出失败项，不含位置。SonarQube（阶段 2）问题或无法连接服务，也不会撤销已通过验证的阶段 1 编辑：这些编辑会保留，问题会放入 remaining。

重试。 如果同一故障连续三次原样出现（相同文件、相同内容、相同问题），MCP 服务会返回 error.code: "PERSISTENT_FAILURE"，并告知调用方停止重试，转而询问人工处理。修改文件或问题发生变化后，计数会重新开始。fixedCount 只统计编辑；JSON 验证通过的项目记录在 fixed.json 中，不算修复。

重叠调用。 对文件集合有重叠的 quality_fix 调用，MCP 服务会按到达顺序依次运行，因此一次调用的回滚绝不会用较旧的副本覆盖另一次调用保留的编辑。针对不同文件的调用仍会并行运行。

---

功能标志

ENABLE_I18N_RULES

对于启用了国际化（i18n）的项目，可启用字面字符串检测：

{
  "env": {
    "ENABLE_I18N_RULES": "true"
  }
}

启用后：

// ⚠️ Warning
<h1>Hello World</h1>

// ✅ OK
<h1>{t('hello')}</h1>

---

故障排查

MCP：未显示 quality_fix

1. Node.js 20.10+ 或 21.1+ — 运行 node -v 和 npx --version。
2. 重新加载 Cursor（编辑 mcp.json 后），或使用 MCP 刷新控件。
3. JSON — 文件必须是有效的 JSON（不能有尾随逗号）。如不确定，请复制 MCP 配置部分的内容。
4. 全局安装 — 如果使用 "command": "ai-quality-gate"，请运行一次 npm i -g ai-quality-gate，以确保二进制文件存在。

Windows

“npx not found”错误：

# Node.js must be in PATH
# Check in PowerShell:
where.exe npx

权限被拒绝：

# Run PowerShell as Administrator

macOS / Linux

“Permission denied”错误：

# Fix npm global directory
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

“sonar-scanner not found”错误：

# Install via Homebrew
brew install sonar-scanner

# Or via npm
npm install -g sonarqube-scanner

SonarQube

“Insufficient privileges”错误：

• SonarQube → Administration → Security → Global Permissions
• 授予 Anyone 组 Browse 和 Execute Analysis 权限

“Project not found”错误：

• 首次分析时手动创建项目：Projects → Create Project → Manually

---

克隆与构建（贡献者）

git clone https://github.com/mustafacagri/ai-quality-gate.git
cd ai-quality-gate
yarn install
yarn build

如需让 MCP 指向 dist/server.js，请参阅本地开发（本仓库）。

---

文档

• SETUP.md — 本地设置（如果你的目录树中包含此文件）
• AGREEMENTS.md、docs/ARCHITECTURE.md 等 — 可选；精简克隆中可能省略某些文件。运行已发布的包只需 README 和 .cursor/mcp.json.example。

---

原则

• ✅ 627 条 ESLint 规则（SonarJS、Unicorn、TypeScript-ESLint 等）
• ✅ 集成 Prettier（使用项目配置）
• ✅ 基于 AST 的转换（不使用正则表达式）
• ✅ 每次修复后进行验证
• ✅ 出错时回滚
• ✅ 自动发现 ESLint 配置（如果可用则使用项目配置，否则使用内嵌配置）
• ✅ 无需变通方案
• ✅ Principal 级别

---

许可证

MIT © Mustafa Çağrı Güven

---

v0.0.1 — 首个版本！MCP quality_fix、阶段 1/2 流水线、CLI、配置文件、自定义规则（参见 CHANGELOG）

只读本地验证

运行 ai-quality-gate --check --phase1-only <selected-file ...> 可对本地文件进行只读验证。ESLint 仅检查明确选定的真实 .js、.jsx、.mjs、.cjs、.ts、.tsx、.mts、.cts 和 .vue 路径，包括可执行的 JS 配置文件和 TS 声明文件。它不会通过导入扩展 lint 范围。.vue 文件会原地进行 lint：vue-eslint-parser 仅对 <script> 和 <script setup> 应用脚本规则。模板和样式不是 JavaScript，也不会写入提取出的脚本文件。@vue/compiler-sfc 的 parse() 和 compileScript() 失败会作为诊断报告。结构无效的 SFC 会在 ESLint 运行前失败，因此缺少结束标签不会被报告为未使用的绑定。AST 编辑会保留箭头函数签名，并为没有花括号的 if 语句加上分号。启用 Prettier 时，会格式化整个 SFC。调用方必须先在隔离快照中将已删除文件和旧的重命名端点实体化为真实文件，并保留其基础内容和端点标识。

TypeScript 会在完整的最近 tsconfig.json 项目上下文中使用 --noEmit 进行检查；这可能包含导入文件和其他项目文件，但不会扩展 ESLint 的选定范围。含 TypeScript 脚本（lang="ts" 或 tsx）的 .vue 文件会通过 vue-tsc 检查，它也会检查模板表达式。会编译 .vue 文件的项目也会用 vue-tsc 检查其 .ts 文件，因此这些文件可以导入 .vue 模块；当项目的 include 匹配到任何 .vue 文件，或最近的 package.json 依赖 vue 时，该项目就视为会编译 .vue 文件的项目。项目是包含该文件的 tsconfig：对于仅列出 references 的 create-vue 风格根配置，项目指被引用的项目；而对于未被任何项目列入、但被某个被引用项目导入的共享辅助文件等，也会在该项目中检查。若某个 .vue 文件未被任何 tsconfig 包含，检查会失败，而不是未经检查就通过。纯 JavaScript 的 .vue 文件不进行类型检查，这与 .js 文件一样。.ts 文件也遵循这一规则：如果某个文件未被任何 tsconfig 直接或通过导入包含，检查会失败，并报告“Not included by ”，而不是未经检查就通过。程序中任何位置的类型错误都会导致检查失败，并全部报告（选定文件中的错误优先，最多 50 条）。纯 JavaScript 的 <script> 会按 .js 文件的规则进行 lint，lang="ts" 的脚本则按 TypeScript 规则进行 lint。不会对 .vue 文件应用需要类型信息的 ESLint 规则（例如 no-floating-promises）：这是有意为之，并非解析器的限制。TypeScript 增量元数据会重定向到项目外的临时文件夹，并在检查后删除。检查模式不会重写源文件、配置文件、锁文件或控制文件。MCP quality_fix 工具仍会修改文件；只读操作请使用 CLI 检查接口。

内嵌配置对 TS 源文件使用 typescript-eslint 的 recommendedTypeChecked 和 projectService。TS 文件必须属于真实的 tsconfig 项目。JavaScript 文件使用非类型化 lint 配置。命名导入别名（包括类型别名）由 AST 规则检查；未更改的命名导入允许保留。警告会导致严格验证失败（--max-warnings 0）。本地检查 JSON 包含 checks.typecheck，以及运行到相应阶段时的 checks.lint，并提供 PASS/FAIL/ERROR 状态、已检查项目和实际 lint 结果路径。现有的快速失败流程可能会在类型检查或自定义规则失败后停止运行 lint。 退出码 0 表示所有已执行的检查均成功；退出码 1 表示发现实际代码问题；退出码 2 表示配置、进程、解析器或覆盖率错误。空的或格式错误的 lint 输出、缺少选定文件、意外或重复的结果路径、致命的解析器错误以及失败的子进程，都不能被视为检查成功。 已安装的软件包包含内嵌解析器、lint 插件、解析器以及 TypeScript 运行时依赖项。支持的 Node 版本为 ^20.10.0 || >=21.1.0，这是保留的 lint 依赖基线所要求的交集。