用途：让 API 规范文件与后端实现保持一致，在前后端协作中检测破坏性变更、生成类型安全客户端，并保证文档可靠。
适用场景：处理 OpenAPI/Swagger 规范文件（.yaml、.json）；管理 GraphQL schema（.graphql、.gql）；在 PR 中审查 API 变更；从规范生成 TypeScript 类型或客户端代码；校验实现是否与文档一致；区分破坏性与非破坏性变更；制定 API 版本策略；帮助新成员理解 API 驱动代码库。
主要能力：
- 规范校验：检查 OpenAPI/Swagger 语法结构、是否符合 3.0/3.1、端点描述、请求响应 schema、安全定义、参数类型与约束；GraphQL 侧解析校验 SDL、检查 stitching、resolver 覆盖、循环依赖、输入输出类型一致性。
- 实现匹配：从规范提取端点，用 Grep 在代码中查找 Express、FastAPI、Django、Spring Boot 等路由定义，分类为匹配、漂移、缺失、未文档化，并生成覆盖率报告。
- 破坏性变更检测：对比两版规范，识别删除端点、删除必填参数、改参数类型、可选变必填、删除响应属性、改状态码、重命名、更严校验等破坏性变更，以及新增端点、可选参数、放宽必填、扩展枚举等非破坏性变更，并输出迁移指南。
- 客户端代码生成：从规范生成 TypeScript 接口、API 客户端函数，可选生成 React Query/SWR hooks，并加入 JSDoc。
- 覆盖率分析：统计已文档化与已实现端点数量及百分比，列出缺失、未文档化与签名不一致项，按严重度排序。
- 迁移指南：按端点分组破坏性变更，说明影响、需改代码与前后对比示例。
使用方式：读取规范文件，解析结构，检查常见问题并给出行号与建议；必要时用 Grep 查找路由处理器做比对；对比新旧规范生成变更报告。可用工具包括 npx @stoplight/spectral-cli lint openapi.yaml、npx graphql-inspector validate schema.graphql、npx openapi-diff old.yaml new.yaml、npx graphql-inspector diff old.graphql new.graphql；代码生成推荐 openapi-typescript、graphql-code-generator、orval。
限制：基础校验与对比无需额外依赖，高级功能可能建议通过 npm 安装工具；最佳效果需要代码库中存在规范文件、后端有结构化路由，TypeScript 类型生成为可选但推荐。其他细节暂未提供。