用途
Workhuman 契约驱动适配器模式用于在已记录的租户能力周围创建一个狭窄、可测试的边界,同时将供应商传输、业务策略和记录系统保持分离。该技能适用于从客户授权的 API 或连接器契约设计强类型的 Workhuman 集成适配器,不假设存在公开 SDK。
主要能力
- 清点所需操作,并将每个操作映射到确切的授权契约部分和所属系统。
- 固定模式或映射指纹、环境、租户、获取日期和兼容性承诺。
- 在工件支持时生成类型;否则定义最小的请求和响应类型,不添加推测性字段。
- 分离传输、认证、序列化、重试、幂等性、策略和业务编排。
- 在规范化错误联合中保留供应商状态和安全关联字段。
- 验证响应信封,容忍已记录的可选字段,拒绝不安全的类型强制转换。
- 测试重复、部分应用、超时、节流、授权撤销、模式漂移和重试资格。
- 仅暴露已批准工作流所需的操作,并记录弃用所有权。
使用方式
前提条件
- 当前客户授权的 API 模式、托管连接器映射或集成规范。
- 已定义的操作、数据分类、所有者和兼容性窗口。
- 所有支持的结果和失败的合成夹具。
工具纪律
使用 Read、Glob 和 Grep 检查契约和消费者,使用 WebFetch 获取当前第一方上下文,使用 Write 或 Edit 处理类型、适配器代码、测试和脱敏回执。
当前契约
Workhuman 描述了开放 API,但在引用的公开页面上未发布通用公共 SDK 或稳定的路由目录。仅从客户授权的工件生成或手工构建,并固定工件身份。
认证
在运行时注入已记录的授权提供方。将秘密获取保持在适配器之外,防止跨租户重用,并从错误中脱敏授权和劳动力数据。
指令
- 清点所需操作,并将每个操作映射到确切的授权契约部分和所属系统。
- 固定模式或映射指纹、环境、租户、获取日期和兼容性承诺。
- 在工件支持时生成类型;否则定义最小的请求和响应类型,不添加推测性字段。
- 分离传输、认证、序列化、重试、幂等性、策略和业务编排。
- 在规范化错误联合中保留供应商状态和安全关联字段。
- 验证响应信封,容忍已记录的可选字段,拒绝不安全的类型强制转换。
- 测试重复、部分应用、超时、节流、授权撤销、模式漂移和重试资格。
- 仅暴露已批准工作流所需的操作,并记录弃用所有权。
审批边界
在构建适配器时,不要添加未记录的操作、从不受信任的模式生成、发布客户工件或执行租户写入。
输出
返回固定的契约身份、操作映射、类型边界、认证注入点、错误模型、夹具覆盖、兼容策略和未解决字段。
错误处理
| 条件 | 响应 |
|---|---|
| 契约没有稳定版本 | 固定其摘要和检索日期,并在重新生成前要求明确审查。 |
| 响应包含未知字段 | 将其保留在安全遥测中并评估兼容性;不要静默重新映射含义。 |
| 写入结果不明确 | 停止自动重试,直到幂等性或对账证明安全。 |
示例
脱敏的完成回执可能如下所示:
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 通道中使用适配器。