SuperAPI AI 工具集

workhuman-sdk-patterns

编程与开发

查看项目

更新于 10-16 07:07

技能介绍

用途

Workhuman 契约驱动适配器模式用于在已记录的租户能力周围创建一个狭窄、可测试的边界,同时将供应商传输、业务策略和记录系统保持分离。该技能适用于从客户授权的 API 或连接器契约设计强类型的 Workhuman 集成适配器,不假设存在公开 SDK。

主要能力

  • 清点所需操作,并将每个操作映射到确切的授权契约部分和所属系统。
  • 固定模式或映射指纹、环境、租户、获取日期和兼容性承诺。
  • 在工件支持时生成类型;否则定义最小的请求和响应类型,不添加推测性字段。
  • 分离传输、认证、序列化、重试、幂等性、策略和业务编排。
  • 在规范化错误联合中保留供应商状态和安全关联字段。
  • 验证响应信封,容忍已记录的可选字段,拒绝不安全的类型强制转换。
  • 测试重复、部分应用、超时、节流、授权撤销、模式漂移和重试资格。
  • 仅暴露已批准工作流所需的操作,并记录弃用所有权。

使用方式

前提条件

  • 当前客户授权的 API 模式、托管连接器映射或集成规范。
  • 已定义的操作、数据分类、所有者和兼容性窗口。
  • 所有支持的结果和失败的合成夹具。

工具纪律

使用 Read、Glob 和 Grep 检查契约和消费者,使用 WebFetch 获取当前第一方上下文,使用 Write 或 Edit 处理类型、适配器代码、测试和脱敏回执。

当前契约

Workhuman 描述了开放 API,但在引用的公开页面上未发布通用公共 SDK 或稳定的路由目录。仅从客户授权的工件生成或手工构建,并固定工件身份。

认证

在运行时注入已记录的授权提供方。将秘密获取保持在适配器之外,防止跨租户重用,并从错误中脱敏授权和劳动力数据。

指令

  1. 清点所需操作,并将每个操作映射到确切的授权契约部分和所属系统。
  2. 固定模式或映射指纹、环境、租户、获取日期和兼容性承诺。
  3. 在工件支持时生成类型;否则定义最小的请求和响应类型,不添加推测性字段。
  4. 分离传输、认证、序列化、重试、幂等性、策略和业务编排。
  5. 在规范化错误联合中保留供应商状态和安全关联字段。
  6. 验证响应信封,容忍已记录的可选字段,拒绝不安全的类型强制转换。
  7. 测试重复、部分应用、超时、节流、授权撤销、模式漂移和重试资格。
  8. 仅暴露已批准工作流所需的操作,并记录弃用所有权。

审批边界

在构建适配器时,不要添加未记录的操作、从不受信任的模式生成、发布客户工件或执行租户写入。

输出

返回固定的契约身份、操作映射、类型边界、认证注入点、错误模型、夹具覆盖、兼容策略和未解决字段。

错误处理

条件 响应
契约没有稳定版本 固定其摘要和检索日期,并在重新生成前要求明确审查。
响应包含未知字段 将其保留在安全遥测中并评估兼容性;不要静默重新映射含义。
写入结果不明确 停止自动重试,直到幂等性或对账证明安全。

示例

脱敏的完成回执可能如下所示:

artifact=customer-openapi@sha256:...; operations=3; auth=injected; fixtures=14; unknown-fields=tolerated; ambiguous-writes=blocked

适用场景

  • 需要为 Workhuman 集成创建可复用、可测试的适配器边界。
  • 拥有客户授权的 API 模式或连接器映射,但不存在公开 SDK。
  • 需要将供应商传输、认证、业务策略与记录系统分离。
  • 需要在本地和 CI 通道中使用适配器,然后再提议金丝雀租户部署。

限制

  • Workhuman 未发布通用公共 SDK 或稳定的路由目录,因此不能假设存在公开 SDK。
  • 仅能从客户授权的工件生成或手工构建,并固定工件身份。
  • 不得添加未记录的操作、从不受信任的模式生成、发布客户工件或执行租户写入。
  • 秘密获取必须保持在适配器之外,防止跨租户重用。
  • 写入结果不明确时,必须停止自动重试,直到幂等性或对账证明安全。
  • 资源包括 Workhuman 集成和开放 API、Workhuman 安全与隐私。
  • 下一步:在提议金丝雀租户部署之前,在本地和 CI 通道中使用适配器。