409 lines
16 KiB
Markdown
409 lines
16 KiB
Markdown
# 灵隙协议实现规范：数字分段错误码系统
|
||
|
||
> 版本：1.0.0 | 层级：实现层
|
||
|
||
---
|
||
|
||
## 1. 错误码分段总览
|
||
|
||
灵隙协议将错误码按照功能领域划分为 9 个分段，每个分段占用 1000 个编码空间（即一个十进制千位段），便于程序化路由、国际化映射和监控告警分类。
|
||
|
||
| 分段范围 | 类别 | 常量标识 | 说明 |
|
||
|---------|------|---------|------|
|
||
| 1000-1999 | SYSTEM_ERROR | 系统错误 | 服务端基础设施类错误，包括内部错误、维护状态等 |
|
||
| 2000-2999 | TASK_ERROR | 任务错误 | 任务生命周期相关错误，包括查找、取消、超时等 |
|
||
| 3000-3999 | INFO_ERROR | 信息错误 | 请求信息/数据类错误，包括字段缺失、格式错误等 |
|
||
| 4000-4999 | CAPABILITY_ERROR | 能力错误 | Agent 能力相关错误，包括不支持的任务类型、资源繁忙等 |
|
||
| 5000-5999 | SECURITY_ERROR | 安全错误 | 认证与授权类错误，包括签名验证、权限不足等 |
|
||
| 6000-6999 | COMMUNICATION_ERROR | 通信错误 | 网络通信类错误，包括端点不可达、回调失败等 |
|
||
| 7000-7999 | GROUP_ERROR | 群组错误 | 群组协作类错误，包括成员管理、共识失败等 |
|
||
| 8000-8999 | HIL_ERROR | HiL 错误 | 人工介入（Human-in-the-Loop）相关错误 |
|
||
| 9000-9999 | VALIDATION_ERROR | 验证错误 | 通用参数验证错误 |
|
||
|
||
分类映射逻辑由 `SynapseErrorCode.Category()` 方法实现，通过错误码范围自动推导所属类别。
|
||
|
||
---
|
||
|
||
## 2. 系统错误（1000-1999）
|
||
|
||
系统错误表示服务端基础设施层面的异常，通常需要运维人员介入处理。
|
||
|
||
| 错误码 | 常量名称 | 说明 |
|
||
|-------|---------|------|
|
||
| 1000 | ErrSystemError | 通用系统错误，无法归类的系统级异常 |
|
||
| 1001 | ErrInternalError | 内部错误，服务端内部处理逻辑异常 |
|
||
| 1002 | ErrMaintenance | 系统维护中，服务暂不可用 |
|
||
|
||
**适用场景**：
|
||
- 数据库连接失败、磁盘写入异常等基础设施故障
|
||
- 未捕获的运行时异常
|
||
- 计划内维护窗口或突发性服务不可用
|
||
|
||
---
|
||
|
||
## 3. 任务错误（2000-2999）
|
||
|
||
任务错误表示与任务生命周期管理相关的异常，涵盖任务的创建、执行、完成和取消等阶段。
|
||
|
||
| 错误码 | 常量名称 | 说明 |
|
||
|-------|---------|------|
|
||
| 2001 | ErrTaskNotFound | 任务不存在，指定的任务 ID 无效或已过期 |
|
||
| 2002 | ErrTaskAlreadyCompleted | 任务已完成，无法对已完成的任务执行变更操作 |
|
||
| 2003 | ErrTaskCancelled | 任务已取消，任务已被发起方或系统取消 |
|
||
| 2004 | ErrTaskTimeout | 任务超时，执行时长超过最大允许时间 |
|
||
| 2005 | ErrTaskInvalidParams | 任务参数无效，提交任务时提供的参数不符合要求 |
|
||
|
||
**适用场景**：
|
||
- 查询不存在的任务状态
|
||
- 对已结束的任务发起取消或修改
|
||
- 任务执行超过最大持续时间阈值
|
||
- 提交任务时缺少必要参数或参数格式错误
|
||
|
||
---
|
||
|
||
## 4. 信息错误（3000-3999）
|
||
|
||
信息错误表示请求中携带的信息不完整或不符合规范，通常由调用方修正后重试。
|
||
|
||
| 错误码 | 常量名称 | 说明 |
|
||
|-------|---------|------|
|
||
| 3001 | ErrRequiredFieldMissing | 必填字段缺失，请求中缺少协议要求的必需字段 |
|
||
| 3002 | ErrInvalidFieldFormat | 字段格式无效，字段值不符合预期的格式规范 |
|
||
| 3003 | ErrInfoNotProvided | 信息未提供，需要的信息未被提供 |
|
||
|
||
**适用场景**：
|
||
- 消息中缺少 `sender`、`receiver` 等必填字段
|
||
- 邮箱、URL、时间戳等字段格式校验失败
|
||
- 上下文信息不足以完成任务处理
|
||
|
||
---
|
||
|
||
## 5. 能力错误（4000-4999）
|
||
|
||
能力错误表示接收方 Agent 无法处理请求所要求的能力或资源不可用。
|
||
|
||
| 错误码 | 常量名称 | 说明 |
|
||
|-------|---------|------|
|
||
| 4001 | ErrUnsupportedTaskType | 不支持的任务类型，Agent 未声明支持该类型的任务 |
|
||
| 4002 | ErrCapabilityLacking | 能力不足，Agent 不具备执行请求所需的某项能力 |
|
||
| 4003 | ErrResourceBusy | 资源繁忙，Agent 当前正在处理其他任务，无法接受新请求 |
|
||
| 4004 | ErrQuotaExceeded | 配额超限，请求超出 Agent 设定的资源配额限制 |
|
||
|
||
**适用场景**：
|
||
- 向只支持文本生成的 Agent 提交图像生成任务
|
||
- 调用未在 `AgentCapabilities` 中声明的能力
|
||
- Agent 已达到 `MaxConcurrentTasks` 上限
|
||
- 文件大小超过 `MaxFileSize` 或任务时长超过 `MaxTaskDuration`
|
||
|
||
---
|
||
|
||
## 6. 安全错误（5000-5999）
|
||
|
||
安全错误表示认证、授权或安全策略相关的异常，涉及身份验证和访问控制。
|
||
|
||
| 错误码 | 常量名称 | 说明 |
|
||
|-------|---------|------|
|
||
| 5001 | ErrAuthFailed | 认证失败，身份凭证验证未通过 |
|
||
| 5002 | ErrSignatureInvalid | 签名无效，消息签名验证失败，内容可能被篡改 |
|
||
| 5003 | ErrPermissionDenied | 权限不足，当前身份不具备执行操作所需的权限 |
|
||
| 5004 | ErrPolicyViolation | 策略违规，请求违反系统安全策略或合规要求 |
|
||
|
||
**适用场景**：
|
||
- 令牌过期、密钥错误等认证失败
|
||
- HMAC 签名不匹配或签名算法不一致
|
||
- 角色（Role）不具备操作所需的权限（Permission）
|
||
- 违反数据访问策略、IP 白名单限制等安全规则
|
||
|
||
---
|
||
|
||
## 7. 通信错误（6000-6999）
|
||
|
||
通信错误表示网络传输层面的异常，通常涉及 Agent 之间的消息投递和回调机制。
|
||
|
||
| 错误码 | 常量名称 | 说明 |
|
||
|-------|---------|------|
|
||
| 6001 | ErrEndpointUnreachable | 端点不可达，目标 Agent 的回调端点无法连接 |
|
||
| 6002 | ErrCallbackFailed | 回调失败，回调请求发送成功但返回错误响应 |
|
||
| 6003 | ErrMessageFormatInvalid | 消息格式无效，接收到的消息不符合协议格式要求 |
|
||
| 6004 | ErrTTLExpired | TTL 过期，消息的存活时间已过期，已被丢弃 |
|
||
|
||
**适用场景**：
|
||
- 目标 Agent 离线或网络不可达
|
||
- 回调端点返回非 2xx 状态码
|
||
- 消息结构解析失败、JSON 格式错误
|
||
- 消息在灵泊（Harbor）队列中停留超过 TTL
|
||
|
||
---
|
||
|
||
## 8. 群组错误（7000-7999）
|
||
|
||
群组错误表示群组协作场景中的异常，涵盖群组生命周期管理和成员操作。
|
||
|
||
| 错误码 | 常量名称 | 说明 |
|
||
|-------|---------|------|
|
||
| 7001 | ErrGroupNotFound | 群组不存在，指定的群组 ID 无效或已解散 |
|
||
| 7002 | ErrGroupNotActive | 群组未激活，群组当前处于非活跃状态 |
|
||
| 7003 | ErrMemberNotFound | 成员不存在，指定的成员不在群组中 |
|
||
| 7004 | ErrNotGroupMember | 不是群组成员，当前 Agent 不属于该群组 |
|
||
| 7005 | ErrConsensusNotReached | 未达成共识，群组投票未达到共识阈值 |
|
||
| 7006 | ErrRoleNotFound | 角色不存在，指定的角色在群组中未定义 |
|
||
| 7007 | ErrAlreadyMember | 已是成员，Agent 已经加入该群组 |
|
||
| 7008 | ErrGroupFull | 群组已满，群组成员数量已达上限 |
|
||
|
||
**适用场景**：
|
||
- 查询或操作不存在的群组
|
||
- 向未激活的群组发送消息
|
||
- 查询群组中不存在的成员信息
|
||
- 非群组成员尝试执行仅成员可用的操作
|
||
- 投票结果未达到 `ConsensusMajority` 或 `ConsensusSupermajority` 阈值
|
||
- 重复加入同一群组
|
||
- 群组人数超过 `MaxMembers` 限制
|
||
|
||
---
|
||
|
||
## 9. HiL 错误（8000-8999）
|
||
|
||
HiL（Human-in-the-Loop）错误表示人工介入流程中的异常情况，涵盖人工决策超时、拒绝和升级级别错误。
|
||
|
||
| 错误码 | 常量名称 | 说明 |
|
||
|-------|---------|------|
|
||
| 8001 | ErrHumanTimeout | 人工决策超时，在规定时间内未收到人工响应 |
|
||
| 8002 | ErrHumanDeclined | 人工拒绝，人工决策者明确拒绝了请求 |
|
||
| 8003 | ErrEscalationLevel | 升级级别错误，指定的升级级别无效或不适用 |
|
||
|
||
**适用场景**：
|
||
- Level 1/2/3 超时未响应（超时时间依据级别分别为 24h/12h/72h）
|
||
- 人工批复结果为 `rejected`
|
||
- 升级级别超出定义范围（1-3）或与升级原因不匹配
|
||
|
||
**级别超时默认值**：
|
||
|
||
| 级别 | 默认超时 | 紧急超时 |
|
||
|-----|---------|---------|
|
||
| Level 1 | 24 小时 | — |
|
||
| Level 2 | 12 小时 | 2 小时 |
|
||
| Level 3 | 72 小时 | — |
|
||
|
||
---
|
||
|
||
## 10. 验证错误（9000-9999）
|
||
|
||
验证错误表示通用参数验证未通过，适用于多个层级的输入校验。
|
||
|
||
| 错误码 | 常量名称 | 说明 |
|
||
|-------|---------|------|
|
||
| 9001 | ErrInvalidParams | 参数无效，通用参数校验失败 |
|
||
|
||
**适用场景**：
|
||
- 请求参数类型不匹配
|
||
- 枚举值超出允许范围
|
||
- 数值超出允许的上下界
|
||
- 字符串长度超出限制
|
||
|
||
---
|
||
|
||
## 11. 错误响应结构
|
||
|
||
灵隙协议定义了两层错误响应结构：`SynapseError` 承载单一错误的完整信息，`ErrorResponse` 作为统一的 API 响应信封。
|
||
|
||
### 11.1 SynapseError
|
||
|
||
`SynapseError` 是协议中所有错误的标准载体，包含错误码、类别、人类可读消息以及扩展信息。
|
||
|
||
```go
|
||
type SynapseError struct {
|
||
Code SynapseErrorCode `json:"code"` // 数字错误码，如 1000、2001
|
||
Category string `json:"category"` // 错误类别，如 "SYSTEM_ERROR"、"TASK_ERROR"
|
||
Message string `json:"message"` // 错误描述，人类可读的英文消息
|
||
Details any `json:"details,omitempty"` // 错误详情，可选，可包含结构化补充信息
|
||
RetryAfter *int `json:"retry_after,omitempty"` // 建议重试等待时间（秒），可选
|
||
Timestamp Timestamp `json:"timestamp"` // 错误发生时间戳
|
||
}
|
||
```
|
||
|
||
**字段说明**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|-----|------|-----|------|
|
||
| `code` | SynapseErrorCode | 是 | 数字错误码，属于预定义的 9 个分段之一 |
|
||
| `category` | string | 是 | 由 `SynapseErrorCode.Category()` 自动推导的类别常量 |
|
||
| `message` | string | 是 | 面向开发者的英文错误描述，便于日志和调试 |
|
||
| `details` | any | 否 | 可选的扩展信息，可包含字段级别的验证错误等结构化数据 |
|
||
| `retry_after` | *int | 否 | 对可重试错误，建议调用方等待的秒数（如资源繁忙时） |
|
||
| `timestamp` | Timestamp | 是 | 错误生成的时间戳，用于追踪和时序分析 |
|
||
|
||
### 11.2 ErrorResponse
|
||
|
||
`ErrorResponse` 是所有 API 响应的统一错误信封，通过 `success` 字段标识请求处理状态。
|
||
|
||
```go
|
||
type ErrorResponse struct {
|
||
Success bool `json:"success"` // 固定为 false
|
||
Error *SynapseError `json:"error"` // 错误详情
|
||
}
|
||
```
|
||
|
||
**JSON 序列化示例**：
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"error": {
|
||
"code": 4003,
|
||
"category": "CAPABILITY_ERROR",
|
||
"message": "Agent is currently busy processing other tasks",
|
||
"details": {
|
||
"current_tasks": 5,
|
||
"max_concurrent": 5
|
||
},
|
||
"retry_after": 30,
|
||
"timestamp": "2026-06-28T10:30:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 11.3 ToMap() 方法
|
||
|
||
`SynapseError` 提供 `ToMap() map[string]any` 方法，将错误结构转换为扁平化的 map 结构，便于在不同上下文中进行 JSON 序列化或格式转换。
|
||
|
||
**转换规则**：
|
||
|
||
| 源字段 | map 中的 key | 条件 |
|
||
|-------|-------------|------|
|
||
| `Code` | `"code"` | 始终包含 |
|
||
| `Category` | `"category"` | 始终包含 |
|
||
| `Message` | `"message"` | 始终包含 |
|
||
| `Timestamp` | `"timestamp"` | 始终包含 |
|
||
| `Details` | `"details"` | 仅当 `Details != nil` 时包含 |
|
||
| `RetryAfter` | `"retry_after"` | 仅当 `RetryAfter != nil` 时包含 |
|
||
|
||
**方法签名**：
|
||
|
||
```go
|
||
func (e *SynapseError) ToMap() map[string]any
|
||
```
|
||
|
||
**Go 实现**：
|
||
|
||
```go
|
||
func (e *SynapseError) ToMap() map[string]any {
|
||
m := map[string]any{
|
||
"code": e.Code,
|
||
"category": e.Category,
|
||
"message": e.Message,
|
||
"timestamp": e.Timestamp,
|
||
}
|
||
if e.Details != nil {
|
||
m["details"] = e.Details
|
||
}
|
||
if e.RetryAfter != nil {
|
||
m["retry_after"] = *e.RetryAfter
|
||
}
|
||
return m
|
||
}
|
||
```
|
||
|
||
### 11.4 工厂函数
|
||
|
||
协议提供两个工厂函数用于构造 `SynapseError`：
|
||
|
||
| 函数 | 说明 |
|
||
|-----|------|
|
||
| `NewSynapseError(code, message, details)` | 创建标准错误，自动填充 `Category` 和 `Timestamp` |
|
||
| `NewSynapseErrorWithRetry(code, message, details, retryAfter)` | 创建带重试提示的错误 |
|
||
|
||
### 11.5 预定义错误实例
|
||
|
||
`types/errors.go` 中定义了一系列预构建的错误实例，供实现直接引用：
|
||
|
||
| 变量名 | 对应错误码 | 默认消息 |
|
||
|-------|-----------|---------|
|
||
| `ErrTaskNotFoundError` | 2001 | "Task not found" |
|
||
| `ErrTaskAlreadyCompletedError` | 2002 | "Task has already been completed" |
|
||
| `ErrTaskCancelledError` | 2003 | "Task has been cancelled" |
|
||
| `ErrTaskTimeoutError` | 2004 | "Task execution timed out" |
|
||
| `ErrRequiredFieldMissingError` | 3001 | "Required field is missing" |
|
||
| `ErrUnsupportedTaskTypeError` | 4001 | "Task type is not supported by this agent" |
|
||
| `ErrCapabilityLackingError` | 4002 | "Agent lacks the required capability" |
|
||
| `ErrResourceBusyError` | 4003 | "Agent is currently busy processing other tasks" |
|
||
| `ErrAuthFailedError` | 5001 | "Authentication failed" |
|
||
| `ErrSignatureInvalidError` | 5002 | "Message signature verification failed" |
|
||
| `ErrPermissionDeniedError` | 5003 | "Permission denied" |
|
||
| `ErrEndpointUnreachableError` | 6001 | "Callback endpoint is unreachable" |
|
||
| `ErrMessageFormatInvalidError` | 6003 | "Message format is invalid" |
|
||
| `ErrGroupNotFoundError` | 7001 | "Group not found" |
|
||
| `ErrNotGroupMemberError` | 7004 | "Agent is not a member of this group" |
|
||
| `ErrGroupNotActiveError` | 7002 | "Group is not active" |
|
||
| `ErrAlreadyMemberError` | 7007 | "Agent is already a member of this group" |
|
||
| `ErrGroupFullError` | 7008 | "Group has reached maximum capacity" |
|
||
| `ErrMemberNotFoundError` | 7003 | "Member not found in group" |
|
||
| `ErrInvalidParamsError` | 9001 | "Invalid parameters" |
|
||
| `ErrHumanTimeoutError` | 8001 | "Human decision timed out" |
|
||
|
||
---
|
||
|
||
## 附录：错误码常量定义
|
||
|
||
```go
|
||
type SynapseErrorCode int
|
||
|
||
// 系统错误
|
||
const ErrSystemError SynapseErrorCode = 1000
|
||
const ErrInternalError SynapseErrorCode = 1001
|
||
const ErrMaintenance SynapseErrorCode = 1002
|
||
|
||
// 任务错误
|
||
const ErrTaskNotFound SynapseErrorCode = 2001
|
||
const ErrTaskAlreadyCompleted SynapseErrorCode = 2002
|
||
const ErrTaskCancelled SynapseErrorCode = 2003
|
||
const ErrTaskTimeout SynapseErrorCode = 2004
|
||
const ErrTaskInvalidParams SynapseErrorCode = 2005
|
||
|
||
// 信息错误
|
||
const ErrRequiredFieldMissing SynapseErrorCode = 3001
|
||
const ErrInvalidFieldFormat SynapseErrorCode = 3002
|
||
const ErrInfoNotProvided SynapseErrorCode = 3003
|
||
|
||
// 能力错误
|
||
const ErrUnsupportedTaskType SynapseErrorCode = 4001
|
||
const ErrCapabilityLacking SynapseErrorCode = 4002
|
||
const ErrResourceBusy SynapseErrorCode = 4003
|
||
const ErrQuotaExceeded SynapseErrorCode = 4004
|
||
|
||
// 安全错误
|
||
const ErrAuthFailed SynapseErrorCode = 5001
|
||
const ErrSignatureInvalid SynapseErrorCode = 5002
|
||
const ErrPermissionDenied SynapseErrorCode = 5003
|
||
const ErrPolicyViolation SynapseErrorCode = 5004
|
||
|
||
// 通信错误
|
||
const ErrEndpointUnreachable SynapseErrorCode = 6001
|
||
const ErrCallbackFailed SynapseErrorCode = 6002
|
||
const ErrMessageFormatInvalid SynapseErrorCode = 6003
|
||
const ErrTTLExpired SynapseErrorCode = 6004
|
||
|
||
// 群组错误
|
||
const ErrGroupNotFound SynapseErrorCode = 7001
|
||
const ErrGroupNotActive SynapseErrorCode = 7002
|
||
const ErrMemberNotFound SynapseErrorCode = 7003
|
||
const ErrNotGroupMember SynapseErrorCode = 7004
|
||
const ErrConsensusNotReached SynapseErrorCode = 7005
|
||
const ErrRoleNotFound SynapseErrorCode = 7006
|
||
const ErrAlreadyMember SynapseErrorCode = 7007
|
||
const ErrGroupFull SynapseErrorCode = 7008
|
||
|
||
// HiL 错误
|
||
const ErrHumanTimeout SynapseErrorCode = 8001
|
||
const ErrHumanDeclined SynapseErrorCode = 8002
|
||
const ErrEscalationLevel SynapseErrorCode = 8003
|
||
|
||
// 验证错误
|
||
const ErrInvalidParams SynapseErrorCode = 9001
|
||
```
|
||
|
||
---
|
||
|
||
> 本文档对应源码：[types/errors.go](file:///e:/code/go/synapse/types/errors.go)
|
||
>
|
||
> 参考文档：[06-implementation-details.md](file:///e:/code/go/synapse/docs/v0/06-implementation-details.md) 第 6 章
|