用途:在前后端各自的 LLD 都存在后(.maestro/<slug>/lld/backend.md 与 .../frontend.md),于设计阶段之后、实现之前,把两侧边界合并为一份权威 OpenAPI 契约,并输出 QA 可自动化的验收标准。不设计内部实现(那是 LLD 的职责),也不实现代码,不虚构两侧 LLD 都未要求的操作。
输入:feature、feature_slug、可选 hld_path;backend_lld、frontend_lld 两个路径;产物路径由 skills.config.yaml 的 artifacts.contract 与 artifacts.acceptance 解析(.maestro/<slug>/openapi.yaml、.maestro/<slug>/acceptance-criteria.md)。
主要能力:读取两份 LLD、已有 openapi.yaml 与 HLD 中的验收意图;对齐后端暴露与前端消费的 API,对形状、字段、分页、错误等分歧显式裁决并注明哪一侧需调整;按标准精确规定契约并写成 OpenAPI;编写含负向路径的验收标准;根据存在的 LLD 判断 affected_repos;以平实语言标注每处破坏性变更。
契约标准覆盖:操作(方法/路径或事件/主题、请求响应 DTO、状态码)、统一错误信封与错误码映射、认证与权限(方案及每操作所需权限)、字段校验(类型、必填、格式、min/max、枚举)、分页与上限(page/cursor 形状、默认与最大页大小、载荷上限)、限流(配额与超限响应 429 + retry-after)、幂等键语义、并发(乐观锁/ETag/版本字段)、版本与向后兼容(默认增量,标注破坏性变更与迁移/弃用路径)。边界情况需定义:空/缺失/null 输入、超大载荷、重复提交、分页边界、不稳定排序、鉴权拒绝、令牌过期、权限不足、跨租户尝试、限流耗尽、下游依赖错误透出,以及前端需要但后端未暴露(或反之)的字段——须解决而非掩盖。
外部技能:读取 skills.config.yaml 的 lld.external.research(技能名如 deep-research 或 none),若设置则用于研究契约须遵循的协议/标准,否则仅依据 LLD。
输出:写入 .maestro/<slug>/openapi.yaml(契约,事实来源)与 .maestro/<slug>/acceptance-criteria.md(含负向路径);返回 contract_path、contract_summary(标注破坏性变更)、affected_repos(name 恰为 backend/frontend 的对象)与 acceptance_criteria。完成标准:契约覆盖上述全部条目、无未定义字段/错误,前后端 API 已对齐无隐性不匹配,验收标准含负向路径,最后提出人工契约审批请求,不进入实现。