40 lines
1.5 KiB
Markdown
40 lines
1.5 KiB
Markdown
---
|
||
title: "Handoff Contract"
|
||
type: concept
|
||
tags: [workflow, system-integration, contract, reliability]
|
||
last_updated: 2026-04-25
|
||
---
|
||
|
||
## Definition
|
||
交接合同——两个系统、服务或 Agent 之间每次交接时必须明确定义的接口规范，确保交接的每个环节都有明确的成功/失败/超时约定，防止隐式假设导致级联故障。
|
||
|
||
## Contract Elements（合同要素）
|
||
|
||
```
|
||
HANDOFF: [From] -> [To]
|
||
PAYLOAD: { field: type, field: type, ... }
|
||
SUCCESS: { field: type, ... }
|
||
FAILURE: { error: string, code: string, retryable: bool }
|
||
TIMEOUT: Xs — treated as FAILURE
|
||
ON FAILURE: [recovery action]
|
||
```
|
||
|
||
### 字段说明
|
||
|
||
| 字段 | 说明 |
|
||
|------|------|
|
||
| `PAYLOAD` | 交接时传递的数据结构，必须包含类型注解 |
|
||
| `SUCCESS` | 成功时的返回数据结构 |
|
||
| `FAILURE` | 失败时的标准错误格式（含错误码和可重试标识）|
|
||
| `TIMEOUT` | 超时阈值，超时视为失败 |
|
||
| `ON FAILURE` | 失败后的恢复动作（重试、清理、escalation）|
|
||
|
||
## Why It Matters
|
||
没有显式交接合同的工作流边界是最常见的故障来源：
|
||
- 服务 A 假设服务 B 总是返回某个字段，但 B 偶尔不返回 → 静默故障
|
||
- 超时值未约定，一方认为 5s 合理，另一方认为 30s 才够 → 不匹配
|
||
- 失败后未约定恢复动作，部分场景重试有效，部分场景重试造成数据重复
|
||
|
||
## Source
|
||
- [[specialized-workflow-architect]]（Workflow Architect Agent）
|