# 灵隙协议实现规范：数字分段错误码系统

> 版本：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 章