用途
validate-openapi-spec 用于检查 OpenAPI 规范文件是否有效、是否存在错误。它通过 speakeasy lint 命令对规范进行校验，帮助用户在生成 SDK 之前发现并定位问题。
适用时机包括：
- 在生成 SDK 之前检查规范是否有效
- 识别阻塞 SDK 生成的错误
- 用户提出“validate spec”“lint spec”“is my spec valid”等需求时
主要能力
该技能会输出三类结果：
- 错误（Error）：阻塞 SDK 生成的问题，必须修复。
- 警告（Warning）：可能引发问题的事项，建议修复。
- 提示（Hint）：最佳实践建议，可考虑修复。
常见校验问题及解决方向：
- 缺少 operationId：添加 operationId，或使用 speakeasy suggest operation-ids
- 无效的 $ref：修复引用路径
- 缺少响应 schema：添加响应 schema 定义
- 重复的 operationId：使 operation ID 唯一
使用方式
输入：OpenAPI 规范文件路径（必填，通过 -s 参数指定）。
命令：
speakeasy lint openapi --non-interactive -s <path-to-spec>
面向 AI 的输出优化：对于输出量较大的命令，可通过管道过滤以减少上下文，例如：
speakeasy lint openapi --non-interactive -s ./openapi.yaml 2>&1 | grep -E "(error|warning)"
适用场景
- 在 SDK 生成前进行规范校验
- 排查导致 SDK 生成失败的规范错误
- 获取规范改进的最佳实践建议
限制与注意事项
- 不要在不理解根因的情况下逐个修复错误。
- 不要忽略警告，它们往往指示真实问题。
- 如果规范由外部管理，不要在未询问的情况下修改源文件。
故障排查
- “file not found”：规范路径无效，检查文件路径是否存在。
- 大量重复错误：可能是共享 schema 问题，应修复根 schema，而非逐个引用。
- “$ref not found”：引用损坏，检查引用路径是否与实际位置匹配。
相关技能
- diagnose-generation-failure：当 lint 错误导致生成失败时使用
- fix-validation-errors-with-overlays：在不修改源规范的情况下修复问题
- get-ai-suggestions：获取 AI 驱动的改进建议