Quality Guardian MCP：为AI编程助手设计的实时代码质量聚合与基线管理工具

1. 项目概述为AI编程助手打造的代码质量守门员如果你和我一样日常重度依赖 Claude Code、Cursor 这类 AI 编程助手来写代码那你肯定也遇到过这个头疼的问题AI 助手确实能快速生成代码但它对项目里已有的“技术债”一无所知。你让它改一个文件它可能会在已经有一堆静态分析警告的代码上再引入新的、同类型的低级错误。最后你不得不在提交前自己手动跑一遍 PHPStan、Semgrep、ESLint 等等工具把 AI 生成的代码和项目里陈年老“债”混在一起的报告看一遍再人工筛选出哪些是这次新引入的问题。这个过程不仅打断了流畅的编码体验也让 AI 助手的价值大打折扣。Quality Guardian MCP 就是为了解决这个痛点而生的。它不是一个全新的代码分析工具而是一个“聚合层”或者说“翻译官”。它的核心思路非常巧妙把 Semgrep、PHPStan、Knip、PHPMetrics、Deptrac 这些你已经在用的单点优秀工具通过 Model Context Protocol 协议整合成一个统一的 MCP 服务器。然后它引入了一个“基线”概念将当前代码库中所有已知的问题也就是技术债记录下来。当 AI 助手通过 MCP 调用它时它只会报告相对于这个基线新出现的或未解决的问题。想象一下这个场景你打开 Claude Code准备修改一个模块。在会话开始的瞬间Quality Guardian 会自动提供一个摘要“当前有 3 个 CRITICAL 级别的新问题需要关注分别位于文件 X、Y、Z”。AI 助手在编辑文件前可以主动询问“这个文件目前有已知问题吗” 得到回答后它就能在生成代码时刻意避开那些老旧的坏模式专注于解决当前任务而不是在泥潭里打滚。这才是真正让 AI 融入开发生命周期的关键。2. 核心设计思路为什么“聚合”与“基线”是关键市面上的代码质量方案大致分两类但都有其局限性这正是 Quality Guardian 要填补的空白。2.1 单点工具之困AI 调用成本太高像 PHPStan、Semgrep 这样的工具非常专业但它们是“孤岛”。AI 助手如果想全面评估代码需要分别调用每一个工具的 MCP 服务器如果它们有的话理解每种不同的输出格式然后自己拼凑出一份完整的报告。更麻烦的是每个工具的报告都包含了项目历史遗留的所有问题。AI 需要自己实现一套复杂的“基线对比”逻辑才能知道哪些问题是这次修改新引入的。这个“胶水逻辑”的编写和维护成本对于每个使用 AI 的开发者或团队来说都是重复劳动。2.2 重型平台之隔反馈循环太慢SonarQube、DeepSource 这类平台功能强大能聚合多种分析。但它们通常作为 CI/CD 流水线的一部分在代码提交、发起 Pull Request 之后才运行。对于 AI 助手来说这个反馈来得太晚了。当 AI 在编辑器里一行行写代码时它处于一个“盲写”状态。直到代码被推送到远程平台分析完成它或者说开发者才知道写错了。这时候错误的代码已经成型修正成本远高于在编写时就得到提示。注意这里说的“反馈慢”是相对于 AI 编码的实时性而言的。传统开发中CI 反馈是可以接受的但 AI 编码需要更紧密的、在编辑循环内的质量干预。2.3 Quality Guardian 的破局点内置的聚合与内存基线Quality Guardian 的设计哲学是“把质量门禁搬到 AI 手边”。它通过几个核心机制实现统一协议接口它本身是一个符合 MCP 标准的服务器对外只暴露一套简单的工具如qg_scan_file,qg_digest。AI 助手无需关心背后有多少个分析引擎。基线快照在项目初始化时运行一次全量扫描将所有发现的问题无论新旧计算一个“指纹”并存入本地 SQLite 数据库 (quality.db)。这个数据库就是“基线”代表了团队已接受的技术债务现状。增量比对后续任何扫描无论是全量还是针对单个文件都会将结果与基线进行比对。只有那些指纹不在基线中的问题才会被标记为“新的”或“开放的”问题呈现给 AI。跨栈死代码检测这是它超越传统工具的一大亮点。除了分析源代码它还能通过自定义检测器关联数据库 Schema、国际化键名、CSS 类名找出那些在源代码中已不再使用但在其他系统层仍被引用的“僵尸”资源。这对于全栈项目维护至关重要。这个架构使得 AI 助手能在“编码时”就获得精准的、上下文相关的质量反馈真正实现了“左移”的质量控制。3. 详细配置与部署实操要让 Quality Guardian 在你的项目中跑起来需要经过环境准备、配置调整和与 AI 客户端集成几个步骤。下面我会以一个典型的 PHP JavaScript 项目为例带你走一遍。3.1 环境准备与依赖安装Quality Guardian 是 Node.js 编写的但它调用的底层工具涉及多种语言环境。确保你的系统满足以下条件Node.js ≥ 20这是运行 Quality Guardian 主服务器的环境。建议使用 nvm 管理 Node 版本。Python 3.10 与 pipx用于安装 Semgrep 的 MCP 服务器。pipx能将 Python 应用安装到独立隔离的环境避免依赖冲突非常推荐。PHP 8.x 与 Composer如果你需要分析 PHP 代码这是运行 PHPStan、PHPMetrics、Deptrac 所必需的。安装步骤# 1. 克隆仓库 git clone https://github.com/tehprof/quality-guardian-mcp.git cd quality-guardian-mcp # 2. 安装 Node.js 依赖 npm install # 3. 通过 pipx 安装 Semgrep MCP 服务器。 # 这一步很关键它确保了 Semgrep 能以 MCP 服务器模式被调用。 pipx install semgrep-mcp # 4. 可选但推荐为你的 PHP 项目安装分析工具。 # 进入你的项目目录通过 Composer 安装开发依赖。 cd /path/to/your/php-project composer require --dev phpstan/phpstan # Knip 是 JS/TS 的 dead code 检测工具如果你的项目有前端部分 npm install --save-dev knip3.2 项目配置文件详解Quality Guardian 使用双层配置系统这很好地分离了默认设置和项目特定设置。config.default.json仓库自带的默认配置被 Git 跟踪。它定义了所有可配置项的默认值不建议直接修改。config.local.json你的本地项目配置默认在.gitignore中。所有针对你项目的路径、规则启用与否的设置都在这里。首先复制默认配置创建本地配置cp config.default.json config.local.json接下来是配置的核心部分。打开config.local.json你需要关注以下几个部分{ “scan”: { “rootPath”: “/absolute/path/to/your/project/root“, “includeGlobs”: [“**/*.php“, “**/*.js“, “**/*.ts“, “**/*.vue“], “excludeGlobs”: [ “**/vendor/**“, “**/node_modules/**“, “**/tests/**“, “**/*.test.js“, “storage/**“, “public/build/**“ ] }, “tools”: { “semgrep”: { “enabled”: true, “severityMapping”: { “ERROR”: “CRITICAL“, “WARNING”: “MAJOR“ } }, “phpstan”: { “enabled”: true, “level”: 5, “configPath”: “phpstan.neon.dist“ }, “knip”: { “enabled”: true, “configPath”: “knip.json“ } }, “baseline”: { “dbPath”: “./data/quality.db“, “autoUpdate”: false }, “customDetectors”: { “deadDbColumns”: { “enabled”: true, “schemaFile”: “./database/schema.sql“ }, “deadI18nKeys”: { “enabled”: true, “i18nFiles”: [“./resources/lang/en.json“, “./resources/lang/zh_CN.json“], “usagePattern”: “__\\([\“]([^\”])[\“]\\)“ } } }关键配置解析scan.rootPath必须使用绝对路径。这是所有分析工具的起始工作目录。scan.includeGlobs根据你的项目语言调整。注意这里只是告诉 Quality Guardian 关注哪些文件具体分析能力取决于对应工具是否启用。tools在这里精细控制每个分析器。例如你可以将 PHPStan 的级别 (level) 调高以获得更严格的检查或者为 Semgrep 自定义严重级别映射。customDetectors这是发挥其跨栈分析威力的地方。你需要提供数据库 Schema 文件、i18n 语言文件的路径以及代码中引用这些键名的正则表达式模式。这个模式需要包含一个捕获组来提取键名。实操心得配置usagePattern时最好先在项目的代码库里用grep -P测试一下你的正则表达式确保它能准确匹配到像__(‘user.name’)或$t(‘login.title’)这样的调用并成功捕获引号内的键名。匹配不准会导致大量误报或漏报。3.3 初始化基线接纳技术债务配置完成后最重要的一步是建立基线。运行以下命令npm run baseline:seed这个命令会执行一次全量扫描调用所有已启用的工具然后将发现的所有问题计算哈希指纹存入quality.db数据库。这意味着当前代码库中的所有现存问题都将被标记为“已接受”不会在后续报告中对 AI 助手造成干扰。基线是可以更新的当你修复了一批历史问题后可以重新运行此命令来更新基线。4. 与 AI 编辑器深度集成Quality Guardian 的价值只有在与 AI 编码助手无缝集成时才能完全体现。以下以 Claude Code 和 Cursor 为例。4.1 集成到 Claude CodeClaude Code 通过~/.claude.json配置文件来管理 MCP 服务器。打开或创建~/.claude.json文件。在mcpServers部分添加 Quality Guardian 的配置。务必使用绝对路径。{ “mcpServers”: { “quality-guardian”: { “type”: “stdio“, “command”: “node“, “args”: [“/absolute/path/to/quality-guardian-mcp/src/index.js“], “env”: { “QG_CONFIG”: “/absolute/path/to/quality-guardian-mcp/config.local.json“, “NODE_ENV”: “production“ } } } }保存文件并完全重启 Claude Code 应用不仅仅是重启插件。重启后在 Claude Code 的聊天界面你应该能看到可用的工具列表里出现了mcp__quality-guardian__开头的工具。4.2 集成到 CursorCursor 的配置方式与 Claude Code 几乎完全相同因为二者都遵循相同的 MCP 客户端规范。配置文件通常位于~/.cursor.json或~/.cursor/mcp.json具体请参考 Cursor 文档。配置内容与上述~/.claude.json完全一致。4.3 核心 MCP 工具使用场景集成成功后AI 助手可以调用以下工具。你可以通过自然语言指导 AI 使用它们qg_digest最常用。在编码会话开始时调用获取项目质量快照。AI 助手通常会主动在系统提示词中加入类似“在开始前请使用 qg_digest 工具检查当前代码库状态”的指令。它会返回类似CRITICAL: 2, MAJOR: 15的摘要让 AI 对问题规模有数。qg_scan_file在编辑或审查一个特定文件前调用。AI 会问“我要修改src/Service/Payment.php这个文件目前有质量问题吗” 这个工具只扫描该文件并与基线比对快速反馈。qg_scan_module适用于模块化架构。如果你有一个“用户认证”模块这个工具可以只扫描该模块相关的文件提供聚焦的报告。qg_baseline_status用于评估趋势。AI 可以询问“相比上次基线我们的代码质量是变好了还是变差了” 这对于持续集成或定期评估很有用。注意事项qg_scan_full工具会触发全量扫描比较耗时不建议在编辑循环中频繁使用。更适合配置为夜间定时任务 (cron)用于更新基线或生成完整报告。5. 自定义规则与检测器实战Quality Guardian 的另一个强大之处在于其可扩展性。你可以为其添加两类规则基于 Semgrep 的代码模式规则和自定义的跨栈死代码检测规则。5.1 添加项目特定的 Semgrep 规则假设你的项目规定所有数据库查询都必须包含tenant_id以确保数据隔离。你可以创建一个自定义的 Semgrep 规则。在 Quality Guardian 项目目录下创建rules/your-project-name/目录your-project-name可自定义。在该目录下创建 YAML 文件例如must-include-tenant-id.yamlrules: - id: must-include-tenant-id message: Database query must include tenant_id for multi-tenancy. languages: [php] severity: ERROR patterns: - pattern: | DB::table($TABLE)-... - pattern-not: | ...-where(..., $TENANT_ID)-... fix: | # 这里可以提供一个简单的修复建议但AI助手会基于此进行更智能的修复 // Ensure tenant scope is applied.在config.local.json中确保tools.semgrep的enabled为true。Quality Guardian 会自动加载rules/目录下的所有 YAML 文件。之后任何违反此规则的查询且未包含tenant_id条件都会被 Semgrep 检测到并通过 Quality Guardian 报告给 AI。AI 在生成 SQL 查询代码时就会收到实时提醒。5.2 配置死代码检测器以死 i18n 键为例这个功能非常实用能清理掉无用的翻译键节省维护成本。准备数据源确保你的config.local.json中的customDetectors.deadI18nKeys.i18nFiles路径指向正确的语言文件如resources/lang/en.json。定义使用模式usagePattern是关键。你需要写一个正则表达式来匹配代码中是如何引用这些翻译键的。例如在 Laravel 项目中常用__(‘key’)或lang(‘key’)在 Vue 项目中可能是$t(‘key’)。对于__(‘user.name’)模式可以是__\\([‘\“]([^’\”])[‘\“]\\)。对于$t(‘button.submit’)模式可以是\\$t\\([‘\“]([^’\”])[‘\“]\\)。运行与验证配置好后运行一次npm run scan。Quality Guardian 会提取所有 i18n 文件中的键名然后在代码中搜索匹配usagePattern的字符串。那些在代码中找不到任何引用记录的 i18n 键就会被标记为“死键”。处理结果AI 助手在调用qg_digest时会看到这些死键报告。你可以指示 AI“请帮我清理deadI18nKeys检测器报告出的未使用的翻译键。” AI 可以定位到具体的语言文件并建议删除相应的条目。同样的原理可以应用于检测未被任何 CSS 选择器使用的 CSS 类名需要提供 CSS 文件列表和 HTML/JSX 中类名的使用模式以及数据库中已无代码引用的表字段需要提供数据库 Schema 导出文件。6. 常见问题排查与性能优化在实际使用中你可能会遇到一些问题。以下是一些常见情况的排查思路。6.1 工具集成失败问题现象可能原因解决方案npm start报错提示找不到 Semgrep MCPpipx安装的semgrep-mcp不在 PATH 中或未安装。1. 确认pipx install semgrep-mcp成功。2. 尝试通过pipx run semgrep-mcp --help测试。3. 在config.local.json中为semgrep配置器指定command的绝对路径如果 pipx 路径特殊。PHPStan 扫描无结果或报错PHPStan 配置文件路径错误或所需依赖未在扫描根目录安装。1. 检查config.local.json中phpstan.configPath是否指向正确的phpstan.neon文件。2. 确保在scan.rootPath指定的项目根目录下运行过composer install。3. 尝试在项目根目录手动运行./vendor/bin/phpstan analyse --error-formatjson看是否正常。自定义检测器未报告任何问题usagePattern正则表达式不匹配实际代码或文件路径配置错误。1. 使用在线正则测试工具如 regex101.com验证你的模式是否能匹配代码片段。2. 检查i18nFiles、schemaFile等路径是否正确文件是否存在且可读。3. 查看 Quality Guardian 的运行日志启动时加DEBUG*环境变量看检测器是否被加载和执行。6.2 性能与使用技巧全量扫描慢首次baseline:seed或运行qg_scan_full时会调用所有工具扫描所有文件速度取决于项目大小和工具本身。对于大型项目数千文件耗时 1-3 分钟是正常的。策略将其配置为 CI 的夜间任务而非实时操作。增量扫描快qg_scan_file和qg_scan_module只针对少数文件速度极快通常 1 秒非常适合在编辑时实时调用。数据库文件增长quality.db会记录每次扫描的结果用于趋势分析。如果磁盘空间紧张可以定期清理data/目录下的旧数据或调整配置减少历史记录保留。与现有 CI 流程共存Quality Guardian 不替代你的 SonarQube 或 GitHub Actions CI。它可以作为 CI 的一个步骤运行npm run scan并生成 JSON 报告然后通过脚本判断是否有“新问题”来失败构建。它的优势在于为 AI 提供实时反馈而 CI 用于团队协作和质量趋势把控。6.3 基线管理的注意事项基线是 Quality Guardian 的核心管理不当会导致问题漏报或误报。基线过期当你修复了大量历史缺陷后基线并未更新。这会导致 AI 助手仍然“看到”这些已修复的问题因为它们不在基线中会被视为“新问题”。解决定期或在重大重构后重新运行npm run baseline:seed。基线污染如果你在代码存在大量新错误时错误地更新了基线这些错误就会被“接受”。解决在运行baseline:seed前先确保当前代码通过基本的质量检查例如没有语法错误。你也可以手动编辑quality.db不推荐或使用qg_baseline_status工具查看变化趋势决定何时更新。跨分支基线quality.db默认存储在本地。在团队协作中不同开发者或不同 Git 分支可能需要不同的基线。策略可以考虑将基线文件纳入.gitignore但为每个主要分支或发布版本在 CI 中生成并存储一份对应的基线快照在切换分支时手动替换。我个人在几个项目中部署 Quality Guardian 后最大的体会是它并没有减少代码问题的总数但它极大地改变了问题被发现和解决的时机。AI 助手从“问题的制造者”变成了“问题的早期发现者”甚至“预防者”。以前需要等到 Code Review 或 CI 失败才暴露的代码异味和潜在 Bug现在在编写的瞬间就被提示修正成本几乎为零。这种开发体验的流畅度提升是任何单纯的静态分析工具都无法提供的。它真正让 AI 编程从“玩具”走向了“工程化”的协作。