开发文档 · API 与协议参考

Events、Errors 与 Schemas

事件顺序、错误语义和机器可读契约的当前权威与成熟度。

成熟度: Interaction 事件 Preview;跨协议统一错误与 Schema 体系仍在规范化。

本页是事件、错误和 Schema 的导航与边界说明,不手工维护一份与服务端重复的字段表。精确类型应来自对应模块的版本化机器可读契约;该统一生成链当前尚未完整提供。

职责

  • Events: 描述类型、顺序、终态、恢复和去重语义。
  • Errors: 区分认证、授权、缺失、冲突、限流、校验与内部失败,并标记可重试性。
  • Schemas: 约束请求、响应与事件,使服务端、SDK、文档和 conformance 使用同一来源。

当前可用

Fellow StreamEvent SSE 是 Interaction 的当前原生 wire,Gateway 的实际生产行为与测试是事实依据。@fellow.work/client 提供消费者类型和解析能力,但手写客户端 contract 可能滞后,不能反向覆盖服务端。

尚未统一

跨七模块的错误 envelope、稳定错误码全集、通用幂等键,以及完整 JSON Schema / OpenAPI 生成物尚未冻结。连接建立前的失败通常表现为 HTTP 错误;建立 SSE 后应由协议内终止事件表达业务失败,但具体行为须按当前实现验证。

信任与版本边界

事件、错误详情和 adapter payload 均视为不可信输入,必须校验并过滤密钥、Token、宿主路径和未授权内容。各模块独立版本化;adapter 可以转换形状,但不得丢失稳定错误码、因果链或改变原生事件语义。

相关文档