OpenAPI Contract-Driven Development

一句话：让前端 agent 连犯错的机会都没有。

解决的问题

pm-agent 漏需求 → 架构漏设计 → 前端自造端点 → 后端没实现 → 用户看到 500

          ↓ 本 Skill 在此切断
          
OpenAPI YAML 是唯一契约 → 代码生成 → 前端只能调生成的函数 → 编译期暴露缺口

核心原理

快速开始

1. 安装

# 安装本 skill（在 skills/ 目录下）
cp -r openapi-contract-driven ~/.openclaw/workspace/skills/

# 安装 openapi-typescript（前端代码生成用，可选）
npm install -D openapi-typescript

2. 从模板生成项目 OpenAPI 规范

cp references/openapi-template.yaml standards/{project}-openapi.yaml
# 编辑 YAML，定义你的端点

3. 生成前端 API Client

# 手动编写 apiClient.ts（或基于 YAML 自动生成）
# 模板见 references/apiClient-template.ts

# 或使用 openapi-typescript 生成类型文件
npx openapi-typescript standards/{project}-openapi.yaml -o frontend/src/api/generated/schema.d.ts

4. 配置 Agent 团队

将 references/agent-templates/ 下的 AGENTS.md 片段合并到对应角色的 Agent 配置中：

5. 验证

# 规范检查
bash scripts/check-api-rules.sh standards/{project}-openapi.yaml

# 期望输出：✅ 6/7 通过 (日期 format 为建议项，不阻塞)

工作流

                    ┌─────────────────────────────┐
                    │  pm-agent: 产品需求           │
                    └──────────────┬──────────────┘
                                   ▼
                    ┌─────────────────────────────┐
                    │  arch-agent: 架构设计         │
                    │  → 输出 OpenAPI YAML (强制)   │
                    └──────────────┬──────────────┘
                                   ▼
                    ┌─────────────────────────────┐
                    │  coordinator: 对照审计         │
                    │  前端期望 vs YAML 定义         │
                    └──────────────┬──────────────┘
                           ┌───────┴───────┐
                           ▼               ▼
              ┌──────────────────┐ ┌──────────────────┐
              │ frontend-agent    │ │ backend-agent     │
              │ 只 import 生成的   │ │ 对照 YAML 实现    │
              │ apiClient         │ │ Controller        │
              └────────┬─────────┘ └────────┬─────────┘
                       │                    │
                       └────────┬───────────┘
                                ▼
                    ┌─────────────────────────────┐
                    │  ops-agent: 部署后验证        │
                    │  ① check-api-rules.sh        │
                    │  ② curl 逐端口逐端点          │
                    └─────────────────────────────┘

7 条核心规则

.spectral.yaml 规则集（不与 Spectral CLI 耦合，bash 脚本可独立运行）：

1. operationId 完整性 — 前端代码生成强依赖（error）
2. ApiResponse 强制 wrapper — 防止「有的返回 T，有的返回 {data:T}」（error）
3. ErrorResponse 标准模型 — 前端不用猜 error shape（warn）
4. 分页参数统一 — PageParam + SizeParam + SortParam（warn）
5. health 端点 — 每个服务必须暴露（warn）
6. 日期格式显式标注 — format: date-time（warn）
7. BearerAuth securityScheme — 统一认证声明（error）

跨项目验证

已在两个项目上跑通：

参考资料

• Zalando REST API Guidelines — 企业级 API 规范
• Azure API Style Guide — Spectral 规则集实践
• OpenAPI 3.0 Specification — 协议标准