Install
openclaw skills install openapi-contract-drivenOpenAPI Contract-Driven Development
OpenAPI 契约驱动开发工作流。解决多 Agent 协作中「前端自造端点，后端漏实现」 这个系统性缺陷。Use when: (1) 新项目启动或已有项目需要规范 API 协作， (2) 频繁出现"页面空白 / 500 / 502"但找不到根因， (3) 需要在多人/AI agent 团队中建立 API 契约体系。 NOT for: 单人项目、临时脚本、非 REST API 项目。
OpenAPI Contract-Driven Development
一句话：让前端 agent 连犯错的机会都没有。
解决的问题
pm-agent 漏需求 → 架构漏设计 → 前端自造端点 → 后端没实现 → 用户看到 500
↓ 本 Skill 在此切断
OpenAPI YAML 是唯一契约 → 代码生成 → 前端只能调生成的函数 → 编译期暴露缺口
核心原理
| 防线 | 机制 | 拦截什么 |
|---|---|---|
| ① 契约层 | check-api-rules.sh 7条规则 | operationId缺失、ApiResponse未包裹、ErrorResponse缺失 |
| ② 代码生成 | apiClient.ts 从前端唯一入口 | 手写 fetch/axios、自造端点 |
| ③ 运行时 | ops-agent 逐端口 curl | 路由错误、服务宕机、端口不匹配 |
| ④ 设计审计 | coordinator 前后端期望对照 | 架构漏设计、需求未覆盖 |
快速开始
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 配置中：
| 模板文件 | 合并到 |
|---|---|
architecture-agent.md | arch-agent / saas-arch-agent 的 AGENTS.md |
backend-agent.md | backend-agent / legal-backend-agent 的 AGENTS.md |
frontend-agent.md | frontend-agent / legal-frontend-agent 的 AGENTS.md |
ops-agent.md | ops-agent / saas-ops-agent 的 AGENTS.md |
coordinator.md | 小雨（main agent）的 coordinator-spawn-template.md |
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 脚本可独立运行）：
- operationId 完整性 — 前端代码生成强依赖（error）
- ApiResponse 强制 wrapper — 防止「有的返回 T，有的返回 {data:T}」（error）
- ErrorResponse 标准模型 — 前端不用猜 error shape（warn）
- 分页参数统一 — PageParam + SizeParam + SortParam（warn）
- health 端点 — 每个服务必须暴露（warn）
- 日期格式显式标注 —
format: date-time（warn） - BearerAuth securityScheme — 统一认证声明（error）
跨项目验证
已在两个项目上跑通：
| 项目 | 端点 | 规则检查 | apiClient |
|---|---|---|---|
| LexGuard（法律合同审查） | 30 | 6/7 ✅ | 11KB |
| 寓居智联（资产管理） | 46 | 6/7 ✅ | 17KB |
参考资料
- Zalando REST API Guidelines — 企业级 API 规范
- Azure API Style Guide — Spectral 规则集实践
- OpenAPI 3.0 Specification — 协议标准