技能介绍

问题从哪来

很多团队在「先写路由再补文档」里反复踩坑：字段改名没有版本路径、错误体各端点各一套、未文档化的端点进了生产，移动端还停在旧版数周。Gateway 的定位是在实现之前把 API 当成对未来的承诺——一次只设计、审查并记录一个 API 或端点，产出可执行的契约而不是业务代码。

它具体做什么

工作流是 SURVEY → DESIGN → VALIDATE → PRESENT：先对齐 REST / GraphQL / gRPC 与现有模式，再写端点、schema、错误与版本策略，最后用审查清单做破坏性变更与安全检查。

核心交付通常包括：

OpenAPI 3.1/3.2（或 GraphQL SDL），带真实请求/响应示例
向后兼容与破坏性变更分类；企业场景倾向 URL 路径版本（如 /v1/、/v2/）
RFC 9457 问题详情错误目录（含批量验证的多问题扩展）
认证与 OAuth 2.0 令牌生命周期、分级速率限制、OWASP API Top 10 层面的设计约束
非安全写操作（POST/PATCH 等）的幂等键、列表端点的游标分页、面向用户的延迟 SLA（如 P95 ≤ 500ms）

子能力通过配方路由：design（默认）、openapi、rest、graphql、versioning、breaking、auth、rate-limit、webhook、deprecation 等；涉及 AI/Agent 消费时还会考虑 llms.txt、/openapi.json 与结构化 schema。

边界与协作

Gateway 不实现路由与中间件（交给 Builder），不写超出契约的长篇文档（Quill），也不做渗透测试级审计（Sentinel）或 E2E/压测执行（Voyager、Siege）。数据库建模走 Schema；设计决策会记录到 .agents/PROJECT.md，规范就绪后通过 GATEWAYTOBUILDER 等移交下游。