graphql-inspector-ci（GraphQL CI/CD自动化验证技能）Skill 是什么？如何配置？

graphql-inspector-ci（GraphQL CI/CD 自动化验证技能）：在代码合并之前拦截 GraphQL 破坏性变更

核心定位：这是一个面向 CI/CD 流水线的 GraphQL 质量保障知识技能，专门解决「模式（Schema）改动上线后把客户端打挂」的常见事故。
覆盖平台广：内容涵盖官方 GitHub App、GitHub Actions、GitLab CI、CircleCI 四类主流集成方式，并提供可直接套用的 YAML 示例。
三大验证动作：diff（模式差异与破坏性变更检测）、validate（操作文档与模式的合规校验）、audit（操作审计与查询复杂度控制）。
配置可统一：所有命令均可通过一份 .graphql-inspector.yaml 管理规则、阈值与通知，避免流水线脚本散乱。
上手门槛低：只要团队会写 YAML、会用 Node.js，就能在半天内搭起一套 GraphQL 质量门；其余边界信息以官方说明为准。

1. 该技能叫什么？如何下载安装 AI 技能提升开发效率？

1.1 基本信息

项目	内容
中文名	GraphQLInspectorCI/CD自动化验证技能Skill
英文名	graphql-inspector-ci
技能 ID	13954
技能类型	领域专业知识型 AI 技能（提供 CI/CD 集成方案与配置知识）
允许使用的工具	Read、Write、Edit、Bash、Glob、Grep
调用方式	该技能标注为不可由用户手动调用，通常由 AI 在识别到相关任务上下文时自动启用，具体以官方说明为准

1.2 它到底解决什么问题

GraphQL 的模式（Schema）就是前后端之间的契约。现实中经常出现这样的场面：后端同学为了清理冗余字段，在 PR 里删掉了一个 deprecated 的字段；Code Review 通过了，CI 也构建成功了，部署上线后，移动端首页一片空白。原因很简单——旧客户端还在查询那个已被删除的字段。

传统做法有三种，但都不够好：

靠人眼看：在 Code Review 里逐行比对 schema.graphql，字段一多就形同虚设；
靠约定：在文档里写「不许删字段」，但没人执行；
靠回归测试：等测试环境发现问题时，往往已经浪费了半天的联调时间。

这个技能的价值，就是把「模式契约」变成流水线里一道自动化的门禁：凡是破坏性变更，要么被显式抑制，要么被拦在合并之前。

1.3 「一键安装」的思路与步骤

这里的「安装」其实分两层，请区分清楚：

第一层：安装 AI 技能本身

在 AI 技能市场、技能库或技能管理入口中，按技能名 graphql-inspector-ci 或技能 ID 13954 检索并安装（具体入口地址与安装命令以官方说明为准）。安装完成后，当你向 AI 描述「帮我在 GitHub Actions 里配置 GraphQL 模式校验」「怎么在 GitLab CI 里拦截破坏性变更」这类需求时，技能就会被自动调用，输出对应的配置方案。

第二层：安装技能所落地的工具链

技能文档中给出的真实安装方式有两类，可任选其一：

CLI 方式（最通用）：在 CI 环境的 Node.js 20 上执行全局安装：

npm install -g @graphql-inspector/cli

GitHub App 方式（最省心）：从 GitHub Marketplace 的 GraphQL Inspector 页面安装应用（地址以官方说明为准），随后在仓库中提交 .github/graphql-inspector.yaml 配置文件。

安装前提：

Node.js 20 环境（GitHub Actions 可用 actions/setup-node@v4，GitLab 可用 node:20 镜像，CircleCI 可用 cimg/node:20.0）；
仓库中已有 schema.graphql 且已被提交（未被 .gitignore 忽略）；
若要做分支差异比较，需要 actions/checkout@v4 配置 fetch-depth: 0 拉取完整 Git 历史，否则会报 Git 引用「权限被拒绝」。

验证是否生效：

本地执行 graphql-inspector --version 能打印版本号即安装成功；
手工跑一次差异比较：graphql-inspector diff 'git:origin/main:schema.graphql' 'schema.graphql'，能输出变更列表即说明 Git 引用与模式路径都正确；
在 PR 上故意删一个字段，观察流水线是否变红、是否留下评论。

2. 该技能的主要功能和特点

多平台集成方案全覆盖：一份技能知识同时覆盖 GitHub App、GitHub Actions、GitLab CI、CircleCI，不需要在四个平台上分别翻四份文档。
破坏性变更检测（diff）：把当前分支的模式与基线（如 git:origin/main:schema.graphql）对比，识别字段删除、类型变更、必填参数新增等破坏性变化。
快速失败模式：支持 --onlyBreaking，只关注关键问题，避免大量「安全变更」把关键告警淹没。
操作文档校验（validate）：校验 src/**/*.graphql 中的查询语句是否符合当前模式，并可设置 --maxDepth 10 等阈值，提前拦住过深的嵌套查询。
操作审计（audit）：对存量查询做批量审计，发现已经失效或存在性能隐患的操作。
PR 自动评论：流水线失败时可通过 actions/github-script 自动在 PR 中留言提醒，GitLab 侧则通过 API 在合并请求上打 note。
矩阵式多模式校验：支持 strategy.matrix 一次并行校验 users、orders、products 等多个微服务的模式。
统一配置文件：.graphql-inspector.yaml 集中管理 schema 路径、diff 规则、validate 阈值、audit 范围与 Slack 通知。
多环境对比：既能比 Git 分支的本地模式，也能直接比远程生产端点 https://api.production.example.com/graphql，并支持通过环境变量传入鉴权头。
工程化细节齐全：包含 npm 缓存加速、Slack 通知、必需状态检查与分支保护、故障排除清单等实践性内容。

和普通「写个脚本跑一下」相比，它强在规则化、可复用、可阻断：不是打印一堆日志让人自己判断，而是直接产出可以卡住合并的质量门。

3. 如何使用该技能？

步骤一：明确需求并触发技能

在 AI 对话中直接描述场景，例如：

「我们的 GraphQL 仓库在 GitHub 上，想在 PR 时自动检测破坏性模式变更，检测到就阻止合并并通知 Slack。」

技能会自动给出对应的 GitHub Actions 工作流与配置文件。

步骤二：选择集成形态

只想「看一眼」→ 用 CLI 手工集成到已有流水线；
想「零脚本」→ 装 GitHub App，提交配置文件即可；
GitLab / CircleCI 用户 → 使用文档中对应的 YAML 模板。

步骤三：落地基础工作流

以 GitHub Actions 为例：

name: GraphQL模式检查
on:
  pull_request:
    paths:
      - 'schema.graphql'
      - '**/*.graphql'

jobs:
  schema-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g @graphql-inspector/cli
      - name: 检查破坏性变化
        run: |
          graphql-inspector diff \
            'git:origin/main:schema.graphql' \
            'schema.graphql'

步骤四：补齐完整验证流水线

在同一个 job 里追加三段：diff --onlyBreaking（并设 continue-on-error: true 以便后续步骤继续执行）、validate 'src/**/*.graphql' schema.graphql --maxDepth 10、audit 'src/**/*.graphql'。最后用 if: steps.diff.outcome == 'failure' 判断，在 PR 上自动评论「⚠️ 检测到破坏性 GraphQL 模式变化！」。

步骤五：接入统一配置

在仓库根目录创建 .graphql-inspector.yaml，把 schema 路径、diff 规则（如 suppressRemovalOfDeprecatedField）、failOnBreaking: true、failOnDangerous: false、validate 的 maxDepth / maxAliasCount / maxComplexityScore、audit 的文档范围全部写进去。

步骤六：设为必需检查

进入仓库「设置 → 分支 → 分支保护规则」，启用「要求状态检查通过」，并把「GraphQL模式检查」这个 job 加为必需项。至此，破坏性变更将无法合并。

输入与输出说明

输入：一份基线模式 + 一份当前模式（或一个远程端点）、操作文档的 glob 路径、阈值参数；
输出：变更/破坏性变更清单、校验失败项、审计结果，以及流水线状态与 PR 评论。

4. 同类型竞品对比分析

方案名称	定位	核心功能	安装/使用门槛	适用场景	优势与不足
graphql-inspector-ci（本技能）	CI/CD 中 GraphQL 模式与操作质量门	diff、validate、audit、GitHub App、多平台 YAML 模板、配置文件、Slack 通知	需要 Node.js 20 与 YAML 基础，CLI 全局安装即可，学习曲线平缓	自建 CI、多平台混用、需要自由定制规则	优势：平台覆盖广、配置透明、可嵌入任意流水线；不足：需要自己维护工作流与通知脚本
Apollo GraphOS Schema Checks	商业化的模式注册与检查服务	模式注册、变更检查、操作安全分析、指标联动	需要接入托管服务与账号体系，配置项较多	已经深度使用 Apollo 生态的团队	优势：与 Apollo 客户端/网关联动紧密、有调用量指标；不足：绑定生态，非 Apollo 项目迁移成本高
GraphQL Hive	开源的模式注册与变更检测平台	模式版本管理、变更检查、使用量统计	可自托管或使用云版，需部署服务	需要集中式模式注册表的团队	优势：开源自托管可控；不足：需要额外运维一套服务
graphql-eslint	基于 ESLint 的 GraphQL 静态检查	语法与规范类检查（如命名、弃用字段使用）	依赖 ESLint 生态，配置成本中等	前端仓库内的 GraphQL 代码规范治理	优势：与现有 lint 流程天然融合；不足：不做跨分支的模式差异比较，无法替代模式契约门禁

选型建议：如果你的核心诉求是「挡住破坏性变更」，本技能是最轻量、最贴近 CI 原生的方案；如果还需要统一的模式注册表与调用量分析，可以再叠加 Hive 或 GraphOS；而 graphql-eslint 更适合做代码规范层面的补充，而不是替代。

5. 该技能的典型应用场景与实际体验情况

场景一：中小团队的 GraphQL 仓库做「模式契约门禁」

角色与痛点：3～5 人的全栈小团队，前后端同仓，谁都能改 Schema，但没人有时间逐行 Review 字段删除。
使用方式：装 GitHub App，提交一份 .github/graphql-inspector.yaml，把 failOnBreaking 设为 true，并把检查设为必需状态。
实际体验：上手难度极低，一个下午就能跑通。效果最明显的是「幽灵故障」归零——以前那种上线后客户端报字段不存在的工单基本消失。注意点：初期建议先用 --onlyBreaking 观察一周，避免历史遗留的大量「危险但不破坏」变更把流水线永久标红。

场景二：微服务架构下的多 Schema 并行校验

角色与痛点：平台工程团队，用户、订单、商品三套 GraphQL 服务分属三个小组，每次发版都要人工确认哪个服务动了模式。
使用方式：使用矩阵策略，在 strategy.matrix 中列出三个服务的名称与模式路径，diff 步骤引用 ${{ matrix.service.schema }}。
实际体验：本来需要三份重复的工作流，用矩阵后压缩成一份，维护成本下降明显。注意点：矩阵任务的名称建议带上服务名，否则失败时很难一眼看出是哪套模式出了问题。

场景三：GitLab 团队在 MR 上自动留痕

角色与痛点：使用 GitLab 自建实例，团队希望变更结论直接出现在合并请求里，而不是让人去翻流水线日志。
使用方式：按文档的 GitLab CI 配置，捕获 diff 输出，若包含 Breaking 关键字，则通过 curl 调用 GitLab API 在该 MR 上创建 note。
实际体验：效果直接，Reviewer 打开 MR 就能看到红色告警。注意点：GITLAB_TOKEN 必须放进 CI 变量中妥善保管，脚本里要用 2>&1 || true 兜住非零退出码，否则脚本会在捕获输出前就中断。

场景四：上线前的生产环境模式一致性核对

角色与痛点：SRE 想确认「即将发布的模式」与「生产线上真正跑着的模式」之间到底差多少。
使用方式：把 diff 的一端换成远程端点，另一端用仓库里的 schema.graphql，并通过 GRAPHQL_INSPECTOR_HEADERS 环境变量注入 Bearer Token。
实际体验：这是防止「代码回滚了但线上模式没回滚」这类漂移问题的有效手段。注意点：远程比较依赖网络与生产鉴权，建议单独放在定时任务里跑，而不是塞进每次 PR 的必跑链路。

6. 该技能能为用户带来的价值

把事故前置为告警：破坏性变更从「上线后由用户发现」变为「PR 阶段就被拦下」，一次生产事故的止损成本，通常远高于搭建流水线的时间成本。
降低协作门槛：AI 技能直接把可用的 YAML 模板与配置文件摆出来，不需要团队里有人专门去啃四个 CI 平台的文档，非资深工程师也能独立完成集成。
规则显性化：suppressRemovalOfDeprecatedField、failOnBreaking、maxDepth、maxComplexityScore 这些阈值写进配置文件后，团队对「什么算破坏性变更」有了统一定义，减少了 Review 时的口头争论。
长期可维护：统一配置文件 + 矩阵策略 + npm 缓存，让校验流水线随着服务数量增长仍保持可维护，而不是每加一个服务就复制一份 YAML。
可量化收益：以一次典型的「字段误删导致首页白屏」事故为例，排查 + 热修复 + 发版往往需要数小时，而这类事故正是该技能要拦下的目标类型；对于高频发版的团队，节省的是每月多次重复发生的时间损耗。

7. 常见问题 FAQ

Q1：这个技能怎么安装？需要付费吗？

分两步。第一步，在 AI 技能市场或技能库中安装 graphql-inspector-ci（技能 ID 13954），入口与方式以官方说明为准；第二步，在 CI 中安装工具链，最通用的是 npm install -g @graphql-inspector/cli，也可从 GitHub Marketplace 安装官方 GraphQL App。该技能文档本身未涉及价格信息，工具链的授权与收费情况请以官方说明为准。

Q2：我不是 GitHub 用户，GitLab 或 CircleCI 能用吗？

可以。技能文档中分别给出了 GitLab CI（node:20 镜像 + before_script 安装 + rules: changes 触发）与 CircleCI（cimg/node:20.0 + graphql-check job + workflows）的完整示例，只需替换模式路径与分支名即可。

Q3：为什么我的流水线报「权限被拒绝」或「模式未找到」？

前者几乎都是没有拉取完整 Git 历史，在 actions/checkout 中加上 fetch-depth: 0 即可。后者按三步排查：确认文件路径在仓库中真实存在、确认 schema.graphql 已被提交（没被 .gitignore 忽略）、相对路径失效时改用绝对路径。

Q4：本地跑通过，CI 上结果却不一样怎么办？

技能文档给出的排查方向是：确保两边 GraphQL Inspector 版本一致、Node.js 版本匹配（建议统一到 20）、以及 CI 环境中的 Git 引用确实可访问。建议在 CI 中固定版本号，避免依赖漂移。

Q5：它和 graphql-eslint、Apollo Schema Checks 怎么选？

三者定位不同。想拦截「跨分支的模式破坏性变更」，选本技能最轻量；想统一治理仓库内的 GraphQL 代码规范，叠加 graphql-eslint；如果团队已经深度使用 Apollo 生态并需要模式注册与调用量指标，再考虑 Apollo GraphOS。三者并不互斥，常见组合是「本技能做门禁 + eslint 做规范」。

Q6：适合谁用？

最适合三类人：维护 GraphQL 服务端、经常改动 Schema 的后端工程师；负责搭建 CI 流水线与质量门的平台/DevOps 工程师；以及希望把「契约变更」流程化的技术负责人。如果项目完全不用 GraphQL，这个技能没有用武之地。