platform-api-contract

What problem does it solve?

It prevents frontend/backend/API drift by making the AgentHub Platform HTTP API contract explicit, discoverable, and enforceable through OpenAPI as the single source of truth.

Core Features & Use Cases

• OpenAPI 事实源: 强制使用 docs/contracts/openapi.yaml 作为唯一事实源，并要求稳定 operationId、schema 可复用、securitySchemes 完整。
• 公开/内部边界隔离: 规范公开的 /api/，禁止把 /internal/、/orchestrator/、/a2a/ 等内部接口泄漏到公开 OpenAPI。
• 统一响应与错误体系: 规定成功与错误 envelope、错误码域与 HTTP status 策略，保证鉴权与对象级权限的一致性。
• 资源化与可扩展策略: 给出 Conversation/Message/Agent/Artifact/Run 等平台资源的字段形态、分页排序搜索、以及 Run.status 枚举约束。
• 前端类型与 Handler 一致性: 要求前端 API client 与类型由 OpenAPI 生成，并通过 contract test 校验不返回 OpenAPI 未定义字段。

Quick Start

Update docs/contracts/openapi.yaml first, then implement Gateway Handlers to match the schema, using mocks and contract tests to verify auth, permission, success, and error responses.