1. 项目概述为AI编程助手打造的“质量守门员”如果你和我一样日常重度依赖 Claude Code、Cursor 这类 AI 编程助手来写代码那你肯定也遇到过这个头疼的问题助手写的代码语法上没问题但一跑静态检查满屏都是警告。更糟心的是这些警告里90% 都是项目里积压已久的历史“技术债”跟助手刚写的代码压根没关系。结果就是你不得不花大量时间手动在一堆无关的噪音里分辨哪些是真正由本次修改引入的新问题。这就是 Quality Guardian MCP 要解决的核心痛点。它不是一个全新的代码分析工具而是一个聚合层和智能过滤器。简单说它把 Semgrep、PHPStan、Knip、PHPMetrics、Deptrac 这些你本来就在用的单点工具通过 Model Context Protocol 协议整合成一个统一的“质量守门员”服务。然后它引入了一个“基线”概念能自动识别并过滤掉项目里已有的、被标记为“技术债”的老问题只把本次新增或修改的代码所引入的质量问题清晰地反馈给你的 AI 助手。想象一下你的项目有 1 万个静态检查问题基线。当你用 AI 助手修改了UserService.php文件后Quality Guardian 不会把那 1 万个问题都扔给助手它只会说“嘿你刚才的改动在UserService.php:45引入了一个新的空指针风险在UserService.php:102可能有个未使用的变量。” 这样助手的注意力就能 100% 集中在“修复自己刚搞出来的问题”上效率提升立竿见影。2. 核心设计思路为什么是“聚合”而非“替代”2.1 现有工具生态的困境在接触 Quality Guardian 之前我尝试过几种方案来让 AI 助手具备代码质量感知能力但都不够理想单点工具直接集成比如在 Claude Code 里单独配置 Semgrep MCP 和 PHPStan MCP。问题在于每个工具都要单独调用结果格式不统一而且每个工具都看不到全局的“基线”。助手会被重复的、跨工具的问题报告搞晕更无法区分新旧问题。重量级 SaaS 平台比如 SonarQube。它的分析能力很强也有基线功能。但最大的问题是反馈环路太长。AI 助手写完代码你需要提交、推送到远程、触发 CI、等平台分析、再在 PR 评论里看到结果。这时候错误的代码模式可能已经在助手的上下文中被“固化”了修正成本很高。它不是在“编码时”实时介入而是在“评审时”事后诸葛亮。手动脚本拼接自己写个脚本在本地依次运行各种检查工具然后解析结果。这解决了聚合问题但如何把结果实时、结构化地喂给 AI 助手如何让助手能按需查询特定文件或模块的质量状态这需要自己实现一套复杂的通信协议。Quality Guardian 的设计聪明在它没有重复造轮子而是精准地填补了“专业分析工具”和“AI 助手工作流”之间的空白。它扮演了一个“翻译官”和“调度员”的角色。2.2 基线机制质量管理的核心“基线”是 Quality Guardian 的灵魂也是它区别于简单工具聚合器的关键。它的实现思路非常务实生成指纹对每一个检查出的问题Violation根据工具名|规则ID|文件路径|行号容错±3行|问题信息生成一个 SHA256 哈希值作为唯一指纹。这个指纹是稳定的即使因为其他修改导致代码行号稍有偏移±3行内也能被识别为同一个问题。建立基线通过npm run baseline:seed命令将当前代码库中所有检查到的问题都记录到本地的 SQLite 数据库data/quality.db中并标记为“已基线化”。这相当于对项目当前的质量状态拍了一张快照并承认“这些是我们已知且暂时接受的技术债。”增量比对后续任何扫描都会将新发现的问题指纹与基线数据库进行比对。只有那些指纹不在基线数据库中的问题才会被认定为“新问题”并呈现给 AI 助手。这个机制带来了几个巨大优势零噪音干扰AI 助手从此只关心自己引入的变更历史包袱不再成为干扰。渐进式改善团队可以设定目标例如“每个新功能模块新增问题数为 0”从而确保代码库质量不会恶化并有机会逐步偿还技术债将基线中的老问题逐个解决并移出基线。责任清晰在代码审查时可以明确看到本次提交引入了哪些新问题讨论焦点更集中。2.3 MCP 协议无缝嵌入 AI 助手工作流Model Context Protocol 是 Anthropic 推出的一套标准它允许像 Quality Guardian 这样的外部服务以“工具”的形式将自己暴露给 Claude、Cursor 等兼容 MCP 的 AI 助手。这比传统的 CLI 调用或 Webhook 先进得多。对于 AI 助手来说Quality Guardian 提供的qg_scan_file,qg_digest等就像搜索互联网、读取文件一样是它原生能力的一部分。助手可以在编写代码的任何时刻主动调用这些工具来获取质量反馈实现了真正的“编码时质量防护”。3. 部署与核心配置详解3.1 环境准备与安装Quality Guardian 基于 Node.js并协调多种后端分析工具。安装过程需要细致一些确保所有依赖就位。# 1. 克隆项目 git clone https://github.com/tehprof/quality-guardian-mcp.git cd quality-guardian-mcp # 2. 安装 Node.js 依赖 (项目核心) npm install # 3. 安装捆绑的分析引擎 # Semgrep 是其核心分析工具之一通过 pipx 安装确保环境隔离 pipx install semgrep-mcp # 4. 对于 PHP 项目需要确保 PHP 分析工具可用 # 假设你使用 macOS 且已安装 Homebrew brew install php brew install composer # 通过 Composer 全局安装 PHP 工具可选也可在项目内安装 composer global require phpstan/phpstan # Deptrac 和 PHPMetrics 通常下载 phar 文件即可Quality Guardian 的配置中可指定路径注意pipx是推荐的管理 Python 命令行工具的方式它能避免包冲突。如果没安装pipx可以用pip install --user pipx安装并确保pipx的二进制路径通常是~/.local/bin已加入系统的 PATH 环境变量。3.2 项目专属配置Quality Guardian 采用“默认配置本地覆盖”的模式这很好地将通用设置和敏感/项目特定的设置分离开。# 复制默认配置模板 cp config.default.json config.local.json现在打开config.local.json进行编辑。这是最关键的一步配置决定了 Quality Guardian 如何扫描你的项目。{ scan: { rootPath: /Users/yourname/Projects/your-php-project, includeGlobs: [**/*.php, **/*.js, **/*.ts, **/*.vue], excludeGlobs: [**/vendor/**, **/node_modules/**, **/tests/**, **/*.min.js] }, tools: { semgrep: { enabled: true, config: [p/ci, r/php.lang.security, rules/generic/] // 启用通用规则集和安全规则 }, phpstan: { enabled: true, level: 5, // PHPStan 分析级别数字越大越严格 paths: [src, lib] // 指定 PHPStan 分析的目录 }, knip: { enabled: true, // 用于 JS/TS 项目的死代码检测 config: ./knip.json // 指向你的 Knip 配置文件 } }, customDetectors: { deadI18nKeys: { enabled: true, i18nFiles: [./resources/lang/en.json, ./resources/lang/zh_CN.json], usagePattern: __\\([\]([^\])[\]\\) // 根据你的 i18n 调用函数调整正则 }, deadDbColumns: { enabled: true, schemaPath: ./database/schema.sql // 你的数据库 schema 文件路径 } }, baseline: { dbPath: ./data/quality.db, // 基线数据库位置 autoUpdate: false // 建议手动控制基线更新而非自动 } }配置要点解析rootPath务必使用绝对路径。这是许多错误的根源。AI 助手和 MCP 服务器可能在不同的工作目录下运行。includeGlobs/excludeGlobs使用 glob 模式。**/表示递归所有子目录。合理排除vendor,node_modules,tests等目录可以大幅提升扫描速度并减少无关干扰。但请注意如果你希望分析测试代码的质量则不应排除tests。工具配置每个工具都有其特定的配置项。例如phpstan.level对应 PHPStan 的规则严格级别。你需要查阅各工具的文档来设置最适合你项目的级别。一开始可以从较低的级别开始避免基线过于庞大。自定义检测器这是 Quality Guardian 的杀手锏。deadI18nKeys和deadDbColumns能帮你发现跨栈的死代码。配置的关键在于usagePattern它是一个正则表达式用于在源代码中匹配国际化键名或数据库字段名的使用。你需要根据项目实际使用的函数名如__()、t()、trans()来调整这个模式。3.3 初始化基线配置完成后就可以建立质量基线了。# 运行一次全量扫描并将所有发现的问题录入基线数据库 npm run baseline:seed这个过程可能会花费一些时间取决于项目大小和启用的工具数量。执行完成后查看data/quality.db文件里面已经存储了当前项目的所有“已知问题”。从此以后只有新出现的问题才会被报告。实操心得在第一次建立基线前建议先单独运行各分析工具如phpstan analyse处理掉一些显而易见的、容易修复的严重问题。这样建立的基线会更“干净”避免基线里包含大量低级错误从而让后续的“新问题”报告更有价值。4. 集成到 AI 开发环境4.1 集成 Claude CodeClaude Code 通过本地 JSON 配置文件来管理 MCP 服务器。找到或创建 Claude Code 的配置文件。通常在~/.claude.jsonmacOS/Linux或%APPDATA%\.claude.jsonWindows。添加 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, QG_TRANSPORT: stdio } } } }重启 Claude Code 应用。这是关键步骤配置更改后必须重启才能生效。重启后在 Claude Code 的聊天界面你应该能看到可用的工具列表里出现了mcp__quality-guardian__开头的工具。4.2 集成 CursorCursor 的 MCP 服务器配置方式与 Claude Code 几乎完全相同。配置文件通常位于macOS:~/Library/Application Support/Cursor/User/globalStorage/mcp.jsonWindows:%APPDATA%\Cursor\User\globalStorage\mcp.jsonLinux:~/.config/Cursor/User/globalStorage/mcp.json将上述同样的配置块添加到mcp.json文件的mcpServers对象中然后重启 Cursor 即可。4.3 验证集成集成成功后最直接的验证方式就是询问你的 AI 助手。例如在 Claude Code 中你可以输入“请使用 quality guardian 工具查看当前项目的质量摘要。”助手应该会调用qg_digest工具并返回类似这样的信息质量摘要基线问题 1245 个新发现问题 0 个。严重问题 0 个主要问题 0 个。这表示集成成功并且你当前的修改没有引入超出基线的新问题。5. 核心工具使用指南与实战场景Quality Guardian 向 AI 助手暴露了一系列工具每个工具都有其特定的使用场景。理解这些场景才能让 AI 助手用得恰到好处。5.1qg_digest会话启动时的“健康检查”这是使用频率最高的工具。它被设计为在 AI 助手开始一个新的编码会话时自动触发通过 SessionStart 钩子或者在用户手动询问项目整体状态时调用。AI 助手调用时机当用户打开一个新文件或者说“我们来开发一个新功能”时。输出内容一个高度浓缩的单行摘要显示基线问题总数、本次会话新增问题数并按严重等级CRITICAL, HIGH, MEDIUM, LOW分类。实战价值让开发者和 AI 助手在开始工作前对代码库的“清洁度”有一个即时认知。如果显示有新的“严重”问题助手应该优先建议修复它们然后再进行新功能的开发。5.2qg_scan_file编辑前的“安全扫描”这是最具防御性的工具。在 AI 助手准备修改某个特定文件之前应该先调用此工具。AI 助手调用时机当用户指令涉及修改UserController.php文件时助手在生成代码前先调用qg_scan_file({“path”: “src/Controller/UserController.php”})。输出内容返回该文件当前已存在的所有质量问题包括基线内的。如果这个文件本身已经“千疮百孔”助手在修改时就需要格外小心避免雪上加霜。同时扫描结果也会作为后续判断“新问题”的参照。实战价值实现“编辑感知”。助手知道这个文件的历史包袱可能会建议“这个文件有 10 个未使用的导入基线内。我将在修改时注意不增加新的未使用导入。另外第 45 行有一个空值风险基线内我本次的改动会避开那附近区域。”5.3qg_scan_module架构视角的“质量视图”对于大型项目按文件扫描可能太细碎。qg_scan_module允许你定义一个“逻辑模块”例如“用户认证模块”、“支付网关模块”并扫描该模块下的所有文件。配置方式需要在config.local.json中定义modules映射将模块名映射到文件路径通配符。modules: { auth: [src/Auth/**/*.php, src/Models/User.php], payment: [src/Payment/**/*.php, src/Gateways/**/*.php] }AI 助手调用时机当任务集中在某个功能模块时例如“优化支付模块的代码”助手可以调用qg_scan_module({“module”: “payment”})来获取该模块的集中质量报告。实战价值便于进行模块级别的重构或优化。助手可以针对一个模块的所有问题给出系统性的重构建议而不是零敲碎打。5.4qg_baseline_status与qg_list_open质量趋势与问题管理这两个工具更偏向于项目管理。qg_baseline_status查看基线趋势。例如过去一周有多少问题被加入基线有多少问题从基线中移除被修复。这有助于衡量团队偿还技术债的进度。qg_list_open列出所有“未解决”的问题即当前扫描到但不在基线中的新问题。可以按严重性、文件路径前缀进行过滤。AI 助手可以用它来生成一个待修复问题的清单。5.5 自定义规则实战捕捉领域特定问题Quality Guardian 内置的通用规则很好但真正的威力在于自定义规则。它允许你使用 Semgrep 的 YAML 语法定义针对自己项目业务逻辑的规则。场景在一个多租户 SaaS 项目中所有数据库查询都必须包含tenant_id字段以防止数据越权。创建规则文件在项目根目录下创建rules/your-project/目录your-project替换为你的项目名然后新建must-include-tenant-id.yaml。rules: - id: must-include-tenant-id message: Database query missing tenant_id in WHERE clause languages: [php] severity: CRITICAL pattern: | $queryBuilder-...-where(...); pattern-not: | $queryBuilder-...-where(..., tenant_id, ...); metadata: category: security domain: multi-tenancy这是一个简化示例实际规则需要更精确地匹配你的 ORM 或查询构建器用法。更新配置在config.local.json的tools.semgrep.config数组中添加你的自定义规则路径。tools: { semgrep: { enabled: true, config: [p/ci, r/php.lang.security, rules/your-project/] } }生效重启 Quality Guardian 服务或重新扫描。现在任何遗漏了tenant_id的查询都会被 AI 助手在编写时即时捕获并警告将安全左移到了编码阶段。6. 高级技巧与避坑指南在实际部署和使用 Quality Guardian 的过程中我积累了一些文档里没写的经验和教训。6.1 性能调优让扫描快如闪电全量扫描qg_scan_full在大型项目上可能较慢。以下策略可以优化体验精细化排除路径充分利用excludeGlobs。除了vendor和node_modules还可以排除文档目录、构建输出目录如dist,build、缓存目录等。按需启用工具如果你是一个纯 PHP 项目可以在config.local.json中将knip(JS/TS 工具) 的enabled设为false。使用增量扫描在开发过程中AI 助手主要依赖qg_scan_file这是增量且极快的。将qg_scan_full配置到 CI/CD 流水线中在每次提交或合并时运行作为守门员。调整工具级别例如将 PHPStan 的level从最高的 8 调整为适合项目的 5能显著减少分析时间。6.2 基线管理策略何时更新基线基线不是一成不变的。随着项目发展你需要更新它。何时“加”入基线当你引入一个庞大的、包含已知问题的第三方库时。当你接手一个历史遗留项目并决定暂时接受其当前状态时使用npm run baseline:seed。团队经过讨论决定将某个低优先级、广泛存在且修复成本高的问题类型如某种代码风格警告暂时纳入技术债。何时“移”出基线当你修复了某个基线中的问题后不要手动修改数据库。只需在修复代码后重新运行npm run baseline:seed。Quality Guardian 会进行全量扫描由于该问题已不存在它的指纹会自动从新的扫描结果中消失。接着你需要手动或通过脚本将数据库中该问题的记录状态更新或删除。通常一个简单的策略是定期如每周用最新的全量扫描结果去“覆盖”基线数据库这样被修复的问题就会自然清除。重要提示直接删除quality.db文件并重新种子化会丢失所有基线历史。建议编写一个小脚本将修复后不再出现的问题标记为“已解决”而非直接删除。6.3 处理误报与规则调优静态分析工具难免有误报。当 Quality Guardian 报告一个你认为不是问题的问题时可以细化规则如果是自定义 Semgrep 规则调整规则的pattern使其更精确。使用工具原生抑制注释例如对于 PHPStan可以在代码行上方使用// phpstan-ignore-line。Quality Guardian 在收集结果时这些被抑制的问题通常不会被上报。在基线中豁免特定问题如果某个误报是特定文件、特定行的你可以选择将它加入基线。但这只是“眼不见为净”最好还是从根源上解决误报。6.4 与 CI/CD 流水线集成Quality Guardian 不仅服务于本地开发也能成为 CI 门禁。# 例如在 GitHub Actions 中的 job 步骤 - name: Quality Gate Check run: | npm run scan # 生成与主分支或上次成功构建的差异报告 # 这里假设你有一个脚本能比较当前扫描结果与基准分支的基线差异 npm run digest -- --formatjson --new-only new_issues.json # 如果 new_issues.json 不为空且包含 CRITICAL 或 HIGH 级别问题则失败 if [ -s new_issues.json ] [ $(jq [.[] | select(.severityCRITICAL or .severityHIGH)] | length new_issues.json) -gt 0 ]; then echo ❌ 发现新的严重质量问题构建失败。 cat new_issues.json exit 1 fi你需要编写额外的脚本来计算“新问题”例如对比当前分支的扫描结果和main分支的基线快照。社区未来可能会提供更官方的 CI 集成方案。7. 常见问题排查实录即使按照指南操作也可能会遇到问题。下面是我遇到的一些典型情况及其解决方法。问题 1AI 助手提示“无法连接到 MCP 服务器”或工具列表里没有 Quality Guardian 工具。检查步骤配置文件路径确保~/.claude.json或 Cursor 的mcp.json中所有路径都是绝对路径。这是最常见的问题。配置文件位置确认配置文件放在了正确的、AI 助手能读取的目录下。环境变量确保QG_CONFIG环境变量指向的config.local.json文件存在且格式正确。可以尝试在终端中手动运行node /path/to/src/index.js看是否有错误输出。重启应用修改 MCP 配置后必须完全退出并重启 Claude Code 或 Cursor。查看日志启动 AI 助手时查看其控制台或日志输出看是否有加载 MCP 服务器失败的报错信息。问题 2npm run baseline:seed运行失败提示某个工具找不到如semgrep。原因虽然用pipx安装了semgrep-mcp但 Quality Guardian 可能调用的是全局的semgrep命令。解决用pipx ensurepath确保pipx的二进制目录在 PATH 中。或者直接使用pip install semgrep安装全局的 semgrep。对于 PHP 工具确保phpstan,deptrac.phar等可在命令行中直接执行。可能需要通过 Composer 全局安装 (composer global require ...) 或将它们的路径添加到系统的 PATH 中。问题 3扫描速度非常慢尤其是qg_scan_full。优化检查config.local.json中的excludeGlobs确保排除了所有不需要分析的目录如vendor,node_modules,build,.git。在tools配置中暂时禁用你不关心的语言对应的分析器例如纯后端项目禁用knip。考虑升级硬件。静态分析是 CPU 和 I/O 密集型操作使用 SSD 会有帮助。问题 4自定义死代码检测器如deadDbColumns没有报告任何问题。检查确认enabled设为true。确认schemaPath指向的 SQL 文件路径正确并且文件包含完整的CREATE TABLE语句。最关键的一步检查usagePattern正则表达式。它必须匹配你代码中使用数据库列名的方式。例如如果你使用 Laravel 的 Eloquent列名可能直接作为对象属性访问$user-email这个模式很难精准匹配。你可能需要调整检测器的逻辑或者编写更复杂的、基于抽象语法树的分析规则。一开始可以尝试一个简单的模式来验证检测器是否正常工作例如匹配代码中出现的任意字符串字面量。问题 5基线似乎没起作用AI 助手仍然看到所有老问题。排查确认npm run baseline:seed成功运行并且data/quality.db文件大小不为零。运行qg_digest或qg_scan_full查看输出中是否区分了“基线问题”和“新问题”。如果所有问题都被标记为新问题说明基线数据库未被正确读取或指纹计算不匹配。检查config.local.json中baseline.dbPath的路径是否正确以及运行 Quality Guardian 服务的用户是否有该文件的读写权限。尝试删除data/quality.db并重新运行baseline:seed建立一个全新的基线进行测试。这个工具的核心价值在于它将专业的代码质量检查无缝、实时地编织进了 AI 辅助编程的工作流中。它不追求替代 SonarQube 这样功能全面的平台而是精准地解决了“AI 编码时代”的新痛点——让智能助手在创造的同时也能即时地进行自我审查。