HXA Connect 开发规范（多仓协同）

March 13, 2026 · View on GitHub

目标：统一 HXA Connect 生态多仓库的职责边界、设计原则、变更流程与交付质量，避免协议漂移、重复实现和跨仓不一致。

1. 适用仓库

  • hxa-connect（Hub 服务端 + B2B Protocol）
  • hxa-connect-sdk（通用能力 SDK）
  • openclaw-hxa-connect（OpenClaw 接入层）
  • zylos-hxa-connect（Zylos 接入层）

2. 仓库定位与职责

2.1 hxa-connect（协议真相源 + 服务端实现）

职责：

  • 定义并实现 API / WebSocket 协议
  • 维护 docs/B2B-PROTOCOL.md 作为协议唯一真相源
  • 维护安全模型（鉴权、权限、租户隔离）

不负责：

  • 各 runtime 的策略选择（例如是否预下载媒体）

2.2 hxa-connect-sdk（能力抽象层）

职责：

  • 将协议能力封装为稳定、可复用接口
  • 提供跨 runtime 的默认安全实现（超时、限流/限额、资源清理等）
  • 降低接入端重复实现成本

不负责：

  • 业务策略决策（什么时候调用某能力）

2.3 connectors（openclaw / zylos）

职责：

  • 将 SDK 能力映射到具体 runtime 消息模型
  • 承担策略层决策（触发条件、优先级、缓存策略等）
  • 保持与 SDK 的兼容升级

不应做：

  • 重复实现通用基础能力（应优先复用 SDK）

3. 分层原则（必须遵守）

  • Protocol（hxa-connect）：定义契约（Contract）
  • SDK（hxa-connect-sdk）：提供能力（Capability）
  • Connector（各接入层）：定义策略（Policy）

设计判断规则：

  1. 这是“所有接入端都需要”的能力吗？是 → 放 SDK
  2. 这是“某 runtime 特有”的行为吗？是 → 放 connector
  3. 这是“请求/响应语义变化”吗？是 → 先改 Protocol 文档

4. 协议一致性规则

出现以下任一情况，必须更新 docs/B2B-PROTOCOL.md：

  • 新增/删除 endpoint
  • 请求或响应字段变化
  • 鉴权或权限语义变化
  • 错误码语义变化
  • WebSocket 事件契约变化

仅以下情况可不更新协议文档：

  • 内部重构（外部契约不变）
  • connector 策略调整（不改变协议行为）

5. 安全与健壮性基线

所有仓库统一遵守：

  1. 认证优先
  • 默认拒绝匿名访问
  • 严格按 scope / role 校验
  1. 租户隔离
  • 一切资源访问需进行 org 边界验证
  1. 超时与取消
  • 网络请求必须支持 timeout 与 abort
  1. 资源清理
  • 提前返回/异常路径必须清理 response body、句柄、临时文件
  1. 异常隔离
  • 异步事件处理器必须 try/catch，防止 unhandled rejection
  1. 流式优先
  • 大体积 I/O 采用 streaming，避免 OOM

6. ID 与 URL 合约规范

  • 协议中的资源 ID（如 :id）对客户端视为 opaque（不透明）
  • 禁止在 SDK/connector 假设固定编码格式（UUID/hex/固定长度）
  • URL 解析应基于路径语义，不应收窄合法 ID 空间

7. 开发与评审流程（跨仓）

7.1 变更流程

  1. 先判断变更层级：Protocol / SDK / Connector
  2. 通用能力优先进入 SDK，再由 connector 接入
  3. 若有协议影响，先更新 Protocol 文档再实现
  4. 提交 PR 时标注：
    • 变更层级
    • 是否影响协议
    • 是否影响下游仓库
    • 回滚方案

7.2 评审清单

  • 是否破坏向后兼容
  • 是否引入跨仓重复实现
  • 是否覆盖鉴权/边界/异常路径测试
  • 是否满足超时、取消、清理要求
  • 文档是否已同步

8. 测试与发布要求

8.1 测试要求

  • 单测覆盖：正常路径 + 失败路径 + 边界条件
  • 对 I/O 类能力，必须覆盖：超时、取消、资源清理、超限保护
  • 对协议类变更，必须有契约测试或集成测试

8.2 发布要求

  • main 分支可发布标准：
    • 构建通过
    • 关键测试通过
    • 文档同步完成
    • 跨仓影响已确认

8.3 版本依赖声明（必须）

  1. SDK 必须声明 Hub 最低兼容版本
  • 在 hxa-connect-sdk 的 README 明确写出：
    • Requires hxa-connect >= X.Y.Z
  • 与 package.json 中兼容字段（如 hxa-connect.server）保持一致
  1. Connector 必须声明 SDK 最低版本
  • 在 openclaw-hxa-connect / zylos-hxa-connect 的 package.json 依赖里，声明本次发版所需的 SDK 最低版本（例如 ^1.4.0）
  • Connector README 需同步说明最低 SDK 要求（必要时）
  1. 禁止隐式依赖新能力
  • 若 connector 使用了 SDK 新增接口，必须先完成 SDK 发版并发布到 npm，再提升 connector 的依赖版本并发版

8.4 跨仓发版顺序（推荐）

涉及“Hub + SDK + Connector”联动时，按以下顺序发布：

  1. hxa-connect（若协议/服务端有变更）
  2. hxa-connect-sdk（封装并发布 npm）
  3. openclaw-hxa-connect / zylos-hxa-connect（升级 SDK 最低版本并发版）

发布前核对清单：

  • SDK README 兼容版本声明已更新
  • connector package.json 依赖版本已提升并锁定最低要求
  • connector release note 明确升级前置条件（Hub/SDK 最低版本）

9. 文档治理

  • 本文件是多仓协同开发规范
  • 协议细节以 docs/B2B-PROTOCOL.md 为准
  • SDK 用法以 hxa-connect-sdk 的 API/Guide 文档为准
  • 若本规范与协议文档冲突，以协议文档为准，并及时修订本规范

10. 版本管理

  • 规范更新应采用“最小必要改动”
  • 每次更新在 PR 描述中说明：
    • 变更背景
    • 影响范围
    • 生效方式（立即/渐进）

通过以上规范，确保：

  • 协议稳定
  • 能力可复用
  • 策略可演进
  • 多仓实现长期一致。