ai/synapse

Fork 0

Files

lychang 812f68d5aa 灵隙(synapse) v1.0.0 版本

2026-06-28 03:24:26 +08:00

16 KiB

Raw Blame History

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

版本：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 是协议中所有错误的标准载体，包含错误码、类别、人类可读消息以及扩展信息。

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 字段标识请求处理状态。

type ErrorResponse struct {
    Success bool          `json:"success"`          // 固定为 false
    Error   *SynapseError `json:"error"`            // 错误详情
}

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` 时包含

方法签名：

func (e *SynapseError) ToMap() map[string]any

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"

附录：错误码常量定义

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

参考文档：06-implementation-details.md 第 6 章

16 KiB Raw Blame History Unescape Escape

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

1. 错误码分段总览

2. 系统错误（1000-1999）

3. 任务错误（2000-2999）

4. 信息错误（3000-3999）

5. 能力错误（4000-4999）

6. 安全错误（5000-5999）

7. 通信错误（6000-6999）

8. 群组错误（7000-7999）

9. HiL 错误（8000-8999）

10. 验证错误（9000-9999）

11. 错误响应结构

11.1 SynapseError

11.2 ErrorResponse

11.3 ToMap() 方法

11.4 工厂函数

11.5 预定义错误实例

附录：错误码常量定义

16 KiB

Raw Blame History