# 灵隙协议组件实现规范：七大组件层

> 版本：1.0.0 | 层级：实现层 | 依赖：v1 各核心协议

根据 [v0/06-implementation-details.md](file:///e:/code/go/synapse/docs/v0/06-implementation-details.md) 的第1章内容，分别创建以下7个组件的规范（每组包含：定位说明、核心功能表、数据结构定义）。

---

## 1. 灵脉 Meridian - 寻址与路由层

### 定位说明

Agent 之间虽有空隙（灵隙），但暗中有能量流动的轨迹（脉）。此层负责维护全局路由表。

### 核心功能

| 功能 | 方法 | 说明 |
|-----|------|------|
| Agent 注册 | `Register(endpoint)` | Agent "通脉"入网 |
| Agent 注销 | `Unregister(agentID)` | Agent "断脉"离场 |
| Agent 查询 | `GetAgent(agentID)` | 获取 Agent 端点信息 |
| Agent 列表 | `ListAgents()` | 列出所有活跃 Agent |
| 心跳保活 | `Heartbeat(agentID)` | 刷新 Agent TTL |
| 按能力查找 | `FindByCapability(capability)` | 查找具备特定能力的 Agent |

### 数据结构定义

```go
// AgentEndpoint - Agent 端点信息
type AgentEndpoint struct {
    AgentID      string                 // Agent 唯一标识
    AgentName    string                 // Agent 名称
    SystemID     string                 // 所属系统 ID
    Endpoint     string                 // 回调端点 URL
    Version      string                 // Agent 版本
    Capabilities []string               // 能力标签列表
    Metadata     map[string]interface{} // 扩展元数据
}

// RegistryConfig - 注册表配置
type RegistryConfig struct {
    DefaultTTL time.Duration // 默认存活时间（5分钟）
}
```

### 拓扑管理

```go
// 拓扑类型
type TopologyType string
const (
    TopologyStar   = "star"   // 星型拓扑（中心协调）
    TopologyMesh   = "mesh"   // 网状拓扑（全互联）
    TopologyRing   = "ring"   // 环形拓扑（环形传递）
    TopologyTree   = "tree"   // 树形拓扑（层级管理）
    TopologyHybrid = "hybrid" // 混合拓扑
)

// 拓扑管理接口
type TopologyManager interface {
    CreateTopology(id, name string, topologyType TopologyType) *NetworkTopology
    AddNode(topologyID, nodeID string) error
    AddEdge(topologyID, from, to string) error
    GetNeighbors(topologyID, nodeID string) ([]string, error)
}
```

---

## 2. 灵玺 Sigil - 身份与凭证层

### 定位说明

皇帝的玉玺是最高凭证。每个 Agent 的初始身份都需经过"铸玺"过程，每一次交互都要"验玺"。

### 核心功能

| 功能 | 方法 | 说明 |
|-----|------|------|
| 创建身份 | `CreateIdentity(agentID, ...)` | "铸玺" - 创建身份凭证 |
| 获取身份 | `GetIdentity(agentID)` | 获取 Agent 身份信息 |
| 撤销身份 | `RevokeIdentity(agentID)` | "废玺" - 撤销身份 |
| 检查撤销 | `IsRevoked(agentID)` | 检查身份是否已撤销 |
| 签名消息 | `SignMessage(msg)` | 对消息签名 |
| 验证签名 | `VerifySignature(msg)` | 验证消息签名 |
| 颁发令牌 | `IssueToken(agentID, ...)` | 颁发认证令牌 |
| 验证令牌 | `ValidateToken(signedToken)` | 验证令牌有效性 |

### 数据结构定义

```go
// AgentIdentity - Agent 身份凭证
type AgentIdentity struct {
    AgentID     string     // Agent 唯一标识
    AgentName   string     // Agent 名称
    SystemID    string     // 所属系统 ID
    PublicKey   string     // 公钥（可选）
    PrivateKey  string     // 私钥（本地保存）
    AuthSecret  string     // HMAC 密钥
    Roles       []string   // 角色列表
    Permissions []string   // 权限列表
    CreatedAt   time.Time  // 创建时间
    ExpiresAt   *time.Time // 过期时间
    RevokedAt   *time.Time // 撤销时间
}

// AuthToken - 认证令牌
type AuthToken struct {
    TokenID   string    // 令牌 ID
    AgentID   string    // 所属 Agent
    SystemID  string    // 所属系统
    Roles     []string  // 角色列表
    IssuedAt  time.Time // 颁发时间
    ExpiresAt time.Time // 过期时间
}
```

### 签名算法

```go
// 支持的签名算法
type SignatureAlgorithm string
const (
    AlgHMACSHA256 SignatureAlgorithm = "HMAC-SHA256" // 默认
    AlgHMACSHA512 SignatureAlgorithm = "HMAC-SHA512" // 可选
)

// 签名内容格式
// signature_content = sender_id | receiver_id | timestamp | payload_json
```

---

## 3. 灵鉴 Speculum - 共识与裁决层

### 定位说明

古有"以史为鉴"，今有"以智为鉴"。此层通过对比推理链的严密性来达成共识，如青天明镜。

### 核心功能

| 功能 | 方法 | 说明 |
|-----|------|------|
| 发起投票 | `InitiateVote(...)` | 创建投票议题 |
| 提交投票 | `SubmitVote(voteID, voterID, optionID, reasoning)` | 提交投票 |
| 关闭投票 | `CloseVote(voteID)` | 关闭并统计结果 |
| 获取投票 | `GetVote(voteID)` | 获取投票信息 |
| 仲裁争议 | `Arbitrate(ctx, dispute)` | 仲裁争议 |
| 提交推理链 | `SubmitReasoning(chain)` | 提交推理链到镜面 |
| 比较推理链 | `CompareReasonings(chainIDs)` | 比较推理链严密性 |

### 共识类型

```go
type ConsensusType string
const (
    ConsensusMajority      = "majority"      // 多数投票（>50%）
    ConsensusSupermajority = "supermajority" // 绝对多数（>67%）
    ConsensusUnanimity     = "unanimity"     // 一致同意（100%）
    ConsensusWeighted      = "weighted"      // 加权投票
    ConsensusRanked        = "ranked"        // 排序投票
)
```

### 数据结构定义

```go
// Vote - 投票
type Vote struct {
    VoteID       string              // 投票 ID
    Question     string              // 投票问题
    Options      []VoteOption        // 投票选项
    Type         ConsensusType       // 共识类型
    Initiator    string              // 发起者
    Participants []string            // 参与者列表
    Votes        map[string]string   // voter_id -> option_id
    Weights      map[string]float64  // voter_id -> 权重
    Status       VoteStatus          // 投票状态
    Deadline     time.Time           // 截止时间
    Result       *VoteResult         // 投票结果
    Reasoning    map[string]string   // voter_id -> 推理理由
}

// VoteResult - 投票结果
type VoteResult struct {
    Winner     string              // 获胜选项
    WinOption  VoteOption          // 获胜选项详情
    VoteCounts map[string]int      // 选项 -> 票数
    Passed     bool                // 是否通过
    Margin     float64             // 得票率
}
```

### 推理镜面

```go
// ReasoningChain - 推理链
type ReasoningChain struct {
    ChainID     string           // 推理链 ID
    AgentID     string           // Agent ID
    Topic       string           // 推理主题
    Steps       []ReasoningStep  // 推理步骤
    Score       float64          // 推理得分
    SubmittedAt time.Time        // 提交时间
}

// ReasoningStep - 推理步骤
type ReasoningStep struct {
    StepID      string    // 步骤 ID
    Description string    // 步骤描述
    Evidence    []string  // 证据列表
    Confidence  float64   // 置信度（0-1）
    Next        []string  // 下一步 ID 列表
}
```

---

## 4. 灵泊 Harbor - 异步队列与暂存层

### 定位说明

"泊"为船舶停靠。数据包遇风浪（网络抖动）时暂泊于此，待风平浪静再启航。

### 核心功能

| 功能 | 方法 | 说明 |
|-----|------|------|
| 消息入队 | `Enqueue(msg, target, priority)` | 消息入队（支持优先级） |
| 消息出队 | `Dequeue()` | 消息出队 |
| 标记送达 | `MarkDelivered(msgID)` | 标记消息已送达 |
| 标记失败 | `MarkFailed(msgID, err)` | 标记消息失败（触发重试） |
| 缓冲消息 | `BufferMessage(agentID, msg)` | 为离线 Agent 缓冲消息 |
| 清空缓冲 | `FlushBuffer(agentID)` | Agent 上线后清空缓冲 |
| 添加重试 | `AddRetry(msg, target)` | 添加重试条目 |

### 数据结构定义

```go
// QueueConfig - 队列配置
type QueueConfig struct {
    MaxSize           int           // 最大队列大小（10000）
    DefaultMaxRetries int           // 默认最大重试次数（5）
    DefaultRetryDelay time.Duration // 默认重试延迟（30s）
}

// 队列消息状态
type QueuedStatus string
const (
    QueuedPending    = "pending"    // 待处理
    QueuedProcessing = "processing" // 处理中
    QueuedDelivered  = "delivered"  // 已送达
    QueuedFailed     = "failed"     // 失败
    QueuedDead       = "dead"       // 死信
)
```

### 重试机制

```go
// RetryConfig - 重试配置
type RetryConfig struct {
    MaxRetries   int           // 最大重试次数（5）
    BaseDelay    time.Duration // 基础延迟（1s）
    MaxDelay     time.Duration // 最大延迟（5min）
    JitterFactor float64       // 抖动因子（0.1）
}

// 重试延迟算法：指数退避 + 抖动
// delay = min(BaseDelay * 2^(retryCount-1), MaxDelay) * (1 ± JitterFactor)
```

### 缓冲配置

```go
// BufferConfig - 缓冲配置
type BufferConfig struct {
    MaxPerAgent     int           // 每个 Agent 最大缓冲数（1000）
    MaxAge          time.Duration // 消息最大存活时间（24h）
    CleanupInterval time.Duration // 清理间隔（1h）
}
```

---

## 5. 灵瞰 Panorama - 可观测与度量层

### 定位说明

居高临下，俯瞰全局。如"天眼"般记录每一帧交互的耗时、置信度与资源消耗。

### 核心功能

| 功能 | 方法 | 说明 |
|-----|------|------|
| 开始追踪 | `StartTrace(traceID, name, agentID)` | 创建追踪链路 |
| 开始跨度 | `StartSpan(traceID, parentSpanID, name, agentID)` | 创建子跨度 |
| 结束跨度 | `EndSpan(traceID, spanID, status, err)` | 结束跨度 |
| 添加日志 | `AddSpanLog(traceID, spanID, message, fields)` | 添加跨度日志 |
| 记录指标 | `RecordMetric(name, type, value, labels)` | 记录指标 |
| 递增计数 | `IncrementCounter(name, labels, delta)` | 递增计数器 |
| 设置计量 | `SetGauge(name, labels, value)` | 设置计量值 |
| 健康检查 | `CheckAll(ctx)` | 检查所有组件健康状态 |

### 数据结构定义

```go
// Trace - 追踪链路
type Trace struct {
    TraceID   string                 // 追踪 ID
    RootSpan  *Span                  // 根跨度
    Spans     map[string]*Span       // 跨度集合
    StartTime time.Time              // 开始时间
    EndTime   *time.Time             // 结束时间
    Metadata  map[string]interface{} // 元数据
}

// Span - 追踪跨度
type Span struct {
    SpanID     string                 // 跨度 ID
    TraceID    string                 // 所属追踪 ID
    ParentID   string                 // 父跨度 ID
    Name       string                 // 跨度名称
    Service    string                 // 服务名
    AgentID    string                 // Agent ID
    StartTime  time.Time              // 开始时间
    EndTime    *time.Time             // 结束时间
    Duration   time.Duration          // 持续时间
    Status     SpanStatus             // 跨度状态
    Tags       map[string]string      // 标签
    Logs       []SpanLog              // 日志
    Attributes map[string]interface{} // 属性
}

// SpanStatus - 跨度状态
type SpanStatus string
const (
    SpanStatusPending   = "pending"   // 待定
    SpanStatusRunning   = "running"   // 运行中
    SpanStatusSuccess   = "success"   // 成功
    SpanStatusFailed    = "failed"    // 失败
    SpanStatusCancelled = "cancelled" // 已取消
)
```

### 指标类型

```go
type MetricType string
const (
    MetricCounter   = "counter"   // 计数器（累加）
    MetricGauge     = "gauge"     // 计量器（瞬时值）
    MetricHistogram = "histogram" // 直方图（分布）
)
```

### 健康状态

```go
type HealthStatus string
const (
    HealthStatusHealthy   = "healthy"   // 健康
    HealthStatusDegraded  = "degraded"  // 降级
    HealthStatusUnhealthy = "unhealthy" // 不健康
    HealthStatusUnknown   = "unknown"   // 未知
)
```

---

## 6. 灵衡 Libra - 价值结算与激励层

### 定位说明

权衡利弊，计量公平。将 Agent 间的"智力贡献"与"资源消耗"通证化，动态定价。

### 核心功能

| 功能 | 方法 | 说明 |
|-----|------|------|
| 创建账户 | `CreateAccount(agentID)` | 为 Agent 创建账户 |
| 获取余额 | `GetBalance(agentID)` | 查询账户余额 |
| 转账 | `Transfer(from, to, amount, ...)` | 执行转账 |
| 设置价格 | `SetPrice(taskType, capability, price)` | 设置任务价格 |
| 获取价格 | `GetPrice(taskType)` | 获取任务价格 |
| 计算成本 | `CalculateCost(taskType, complexity, duration)` | 计算任务成本 |
| 结算任务 | `SettleTask(taskID, ...)` | 结算单个任务 |
| 结算群组任务 | `SettleGroupTask(taskID, ...)` | 结算群组任务（分摊费用） |
| 奖励 | `Reward(agentID, amount, reason)` | 发放奖励 |

### 数据结构定义

```go
// Account - 账户
type Account struct {
    AgentID   string                 // Agent ID
    Balance   map[string]float64     // 余额（currency -> amount）
    CreatedAt time.Time              // 创建时间
    Metadata  map[string]interface{} // 元数据
}

// Transaction - 交易记录
type Transaction struct {
    TxID        string            // 交易 ID
    Type        TransactionType   // 交易类型
    FromAgentID string            // 发送方
    ToAgentID   string            // 接收方
    Amount      float64           // 金额
    Currency    string            // 货币（"SYN"）
    Description string            // 描述
    TaskID      string            // 关联任务 ID
    Timestamp   time.Time         // 时间戳
    Status      TransactionStatus // 交易状态
}

// TransactionType - 交易类型
type TransactionType string
const (
    TxTaskExecution     = "task_execution"      // 任务执行
    TxDataSharing       = "data_sharing"        // 数据共享
    TxAPIInvocation     = "api_invocation"      // API 调用
    TxGroupContribution = "group_contribution"  // 群组贡献
    TxDeposit           = "deposit"             // 充值
    TxWithdraw          = "withdraw"            // 提现
    TxReward            = "reward"              // 奖励
    TxPenalty           = "penalty"             // 惩罚
)
```

### 定价规则

```go
// 基础价格（默认）
var BasePrice = map[string]float64{
    "text_generation":   1.0,
    "image_generation":  5.0,
    "video_generation":  20.0,
    "audio_generation":  3.0,
    "analysis":          2.0,
    "translation":       1.5,
}

// 成本计算公式
// cost = basePrice * complexityFactor + durationFactor
// complexityFactor = complexity * 0.5
// durationFactor = duration_seconds * 0.01
```

---

## 7. 灵枢 Pivot - 紧急制动与治理层

### 定位说明

取自《灵枢经》。这是整个协议的"总闸"与"方向盘"，不轻易触发，但触发时能以最小代价重置网络状态。

### 核心功能

| 功能 | 方法 | 说明 |
|-----|------|------|
| 允许请求 | `Allow()` | 检查熔断器是否允许请求 |
| 记录成功 | `RecordSuccess()` | 记录成功（用于恢复） |
| 记录失败 | `RecordFailure()` | 记录失败（触发熔断） |
| 获取状态 | `State()` | 获取熔断器状态 |
| 重置 | `Reset()` | 重置熔断器 |
| 设置治理级别 | `SetLevel(level)` | 设置治理级别 |
| 封禁 Agent | `BanAgent(agentID, reason)` | 封禁 Agent |
| 解封 Agent | `UnbanAgent(agentID)` | 解封 Agent |
| 紧急停止 | `EmergencyStop(reason)` | 一键熔断所有 |
| 恢复正常 | `Resume()` | 恢复正常模式 |
| 应用升级 | `ApplyUpgrade(version)` | 应用协议升级 |
| 回滚升级 | `RollbackUpgrade(version)` | 回滚协议升级 |

### 数据结构定义

```go
// CircuitBreaker - 熔断器
type CircuitBreaker struct {
    name         string        // 熔断器名称
    state        CircuitState  // 状态
    failureCount int           // 失败计数
    successCount int           // 成功计数（半开状态）
    threshold    int           // 失败阈值（5）
    timeout      time.Duration // 熔断超时（30s）
}

// CircuitState - 熔断器状态
type CircuitState string
const (
    CircuitClosed   = "closed"    // 关闭：正常流通
    CircuitOpen     = "open"      // 打开：熔断，拒绝请求
    CircuitHalfOpen = "half_open" // 半开：尝试恢复
)

// 状态转换规则：
// Closed -> Open   ：失败次数 >= threshold
// Open -> HalfOpen ：超过 timeout 时间
// HalfOpen -> Closed：连续成功 3 次
// HalfOpen -> Open ：再次失败
```

### 治理级别

```go
type GovernanceLevel int
const (
    GovLevelNormal     = iota // 正常运行
    GovLevelWatch              // 观察模式（记录但不限制）
    GovLevelRestricted         // 受限模式（限流）
    GovLevelEmergency          // 紧急模式（仅白名单）
    GovLevelShutdown           // 停机模式（全部拒绝）
)
```

---

> 本文档对应 [v0/06-implementation-details.md](file:///e:/code/go/synapse/docs/v0/06-implementation-details.md) 第1章"七大组件层详细规范"，是 v1 协议栈组件实现的参考依据。