流水线概述

该流水线通过 GitHub Actions（validate-and-release.yml）每天 UTC 时间早上 6 点定时运行，并在每次推送到 main 分支且涉及 scripts/、config/ 或 pyproject.toml 的变更时触发。也可以手动触发，并提供强制发布或跳过实时 API 测试的选项。

流水线阶段

 下载              验证                Spectral 检查
 ┌──────┐        ┌──────────┐      ┌─────────────┐
 │ 获取  │───────▶│Schemathesis│────▶│   发现      │
 │ 规范  │        │  约束检查  │     │   违规项    │
 └──────┘        └──────────┘      └─────────────┘
                                          │
                 Spectral 门控       协调
                ┌─────────────┐    ┌──────────┐
                │   执行      │◀───│ 对规范    │
                │   阈值检查  │    │ 应用修复  │
                └─────────────┘    └──────────┘
                       │
                    发布
                 ┌──────────┐
                 │  打包    │
                 │  & 标签  │
                 └──────────┘

1. 下载

scripts/download.py 从 docs.cloud.f5.com 获取官方 F5 XC OpenAPI 规范 ZIP 文件。它使用 HTTP ETag 头进行条件 GET 请求——如果上游包未发生变化，则跳过下载。解压后的 JSON 规范文件存放在 specs/original/ 目录中。

2. 验证

scripts/validate.py 针对实时 F5 XC API 编排两类测试：

Schemathesis —— 基于属性的测试，根据规范生成随机的有效/无效载荷，检查 API 是否符合规范中定义的约束。
约束验证 —— 针对全部 10 个 OpenAPI 约束类别的定向测试（字符串长度、正则模式、数值范围、必填字段、枚举、数组范围、对象结构、组合、依赖关系、数据类型）。

发现的差异会写入 reports/validation_report.json。

3. Spectral 检查（发现）

scripts/spectral_lint.py --mode discover 使用 spectral-pipeline.yaml 对原始规范运行 Spectral CLI。此阶段查找 OAS3 质量问题——缺少 servers 块、缺少联系信息、未标记的操作、未使用的组件 schema、重复的 operationId、无效的示例以及描述中的 script 标签。

违规项被转换为 Discrepancy 对象并写入 reports/spectral_report.json。完整的规则集请参阅 Spectral 规则。

4. 协调

scripts/reconcile.py 读取两份报告文件并对每个规范应用修复：

约束修复 根据观察到的 API 行为调整 schema 约束（放宽、收紧、添加、移除）。参见已应用的修复。
Spectral 修复 为规范补充 servers、联系信息、标签、安全元数据，并移除无用的组件。
安全元数据 在 security_scheme 配置存在时始终注入，即使 Spectral 未标记相关问题。

修复后的规范写入 release/specs/ 并在保存前使用 openapi-spec-validator 进行验证。如果修复后的规范验证失败，则回退使用原始规范。

5. Spectral 门控

scripts/spectral_lint.py --mode gate 对 release/specs/ 中已协调的规范重新运行 Spectral。门控检查错误和警告数量是否符合可配置的阈值（validation.yaml 中的 spectral.gate.max_errors 和 spectral.gate.max_warnings）。

6. 发布

scripts/release.py 将协调后的规范打包为版本化的 ZIP 归档文件。版本号使用 YYYY.MM.DD-<patch> 格式，源自上游规范元数据日期。发布内容包括：

单独的领域规范文件（268 个 JSON 文件）
合并了所有领域的 openapi.json 文件
列出所有已应用修复的 CHANGELOG.md
VALIDATION_REPORT.md 摘要

CI 任务会创建一个附带 ZIP 文件的 GitHub Release，标签为 v<version>。内容哈希可防止在没有变化时重复发布。

文档更新

一个并行的 CI 任务使用 scripts/generate_docs.py 从验证报告生成 docs/01-validation-report.mdx，然后在内容发生变化时开启 PR。