灵隙（Synapse）— 智能体协作协议栈

灵隙之间，万物相连
一套开放、安全、可扩展的 AI 智能体协作协议栈

---

什么是灵隙？

灵隙，英文名 Synapse，是一套专为 AI 智能体（Agent）设计的协作协议栈。

"灵隙"的含义：

• 灵 — 智能体的智慧与能力
• 隙 — 智能体之间的空间与连接

灵隙不是某一个 Agent 的实现，而是定义了 Agent 之间如何对话、如何协作、如何信任的通用规则。

---

用它来做什么？

灵隙解决的核心问题：AI 智能体之间如何协同完成复杂任务？

典型场景

场景	说明
🤖 多 Agent 协作	一个 Agent 负责分析，另一个负责生成，第三个负责审核，协同完成一份报告
🔗 系统集成	后端服务通过 REST API 调用 Agent 能力，无需实现完整协议
🧩 任务分解	复杂任务拆分为多个子任务，分配给不同 Agent 并行执行
👥 群体决策	多个 Agent 对同一问题进行投票，达成共识后再执行
🛡️ 人工兜底	Agent 遇到无法决策的情况时，升级给人类做最终决定

---

核心协议

灵隙协议栈包含三个子协议和一个公共基础：

A2A — 点对点通信

两个 Agent 之间直接的任务协作：

import "synapse/sdk"

client := sdk.NewClient(sdk.Config{
Protocol:      sdk.ProtoA2A,
AgentEndpoint: myEndpoint,
})

taskID, _ := client.SendTaskRequest(ctx, targetAgent, "text_generation", payload)
result, _ := client.WaitForTaskA2A(ctx, taskID, 5*time.Minute)

A2N — 群组协作

一个 Coordinator 协调多个 Worker 协同工作：

client := sdk.NewClient(sdk.Config{
Protocol:      sdk.ProtoA2N,
AgentEndpoint: myEndpoint,
})

group, _ := client.CreateGroup(ctx, "分析小组", topology, nil, members)
subtasks, _ := client.SubmitGroupTask(ctx, group.GroupID, "analysis", req, "majority")

P2A — 外部调用

非 Agent 系统通过 REST API 调用 Agent：

client := sdk.NewClient(sdk.Config{
Protocol: sdk.ProtoP2A,
BaseURL:  "http://agent-service:8080",
APIKey:   "sk-xxx",
})

result, _ := client.CreateAndWait(ctx, "text_generation", payload, 5*time.Second)

RAW — 原始协议（基础）

所有协议共享的基础设施：统一消息信封、Agent 身份标识、HMAC 签名、时间格式。

---

七大组件层

组件	名称	职责
灵脉	Meridian	寻址与路由
灵玺	Sigil	身份与凭证
灵鉴	Speculum	共识与裁决
灵泊	Harbor	异步队列与暂存
灵瞰	Panorama	可观测与度量
灵衡	Libra	价值结算与激励
灵枢	Pivot	紧急制动与治理

---

特色能力

能力	说明
🔐 去中心化身份	公钥派生 AgentID，无需中心化注册
🧠 三级 HiL 升级	Agent 建议 → 人工决策 → 专家仲裁
📦 内容类型系统	文本 / JSON / 代码 / 文件 / 内容包
🔢 数字分段错误码	9 大类 35+ 个错误码，便于国际化
🛤️ 双传输模式	gRPC + HTTP REST，gRPC-Gateway 桥接
⚡ 熔断与治理	熔断器 + 5 级治理级别，保障系统稳定

---

快速开始

# 初始化项目
go mod init my-agent

# 引入灵隙 SDK（在项目中）
go mod edit -replace synapse=./path/to/synapse
go get synapse/pkg/sdk
go get synapse/pkg/types

P2A — 外部调用 Agent

package main

import (
	"context"
	"fmt"
	"time"

	"synapse/pkg/sdk"
)

func main() {
	client := sdk.NewClient(sdk.Config{
		Protocol: sdk.ProtoP2A,
		BaseURL:  "http://agent-service:8080",
		APIKey:   "sk-xxx",
	})

	result, err := client.CreateAndWait(
		context.Background(),
		"text_generation",
		map[string]any{"prompt": "写一首关于AI的诗"},
		5*time.Second,
	)
	if err != nil {
		panic(err)
	}
	fmt.Printf("任务完成: %+v\n", result.Result)
}

A2A — Agent 间点对点协作

package main

import (
	"context"
	"fmt"
	"time"

	"synapse/pkg/sdk"
	"synapse/pkg/types"
)

func main() {
	cfg := sdk.Config{
		Protocol: sdk.ProtoA2A,
		AgentEndpoint: types.AgentEndpoint{
			AgentID:  "agent-001",
			Endpoint: "http://localhost:8080",
		},
		AuthSecret: "my-secret-key",
	}

	client := sdk.NewClient(cfg)

	target := types.AgentEndpoint{
		AgentID:  "agent-002",
		Endpoint: "http://agent-002:8080",
	}

	// 发送任务
	taskID, err := client.SendTaskRequest(
		context.Background(),
		target,
		"text_generation",
		map[string]any{"prompt": "写一首诗"},
	)
	if err != nil {
		panic(err)
	}

	// 等待结果
	state, err := client.WaitForTaskA2A(context.Background(), taskID, 5*time.Minute)
	if err != nil {
		panic(err)
	}
	fmt.Printf("任务状态: %s, 结果: %v\n", state.Status, state.Result)
}

---

协议文档

文档	说明
docs/v1/00_index.md	协议索引与概览
docs/v1/01_raw-protocol.md	原始协议（公共基础）
docs/v1/02_a2a-protocol.md	A2A 协议（点对点）
docs/v1/03_a2n-protocol.md	A2N 协议（群组协作）
docs/v1/04_p2a-protocol.md	P2A 协议（外部调用）
docs/v1/05_identity-protocol-draft.md	去中心化身份与寻址（草案）
docs/v1/components.md	七大组件层规范
docs/v1/content-system.md	内容类型系统
docs/v1/capabilities-system.md	能力发现系统
docs/v1/error-codes.md	数字分段错误码
docs/v1/hil-mechanism.md	人工干预机制 (HiL)
docs/v1/grpc-transport.md	gRPC 传输规范
docs/v1/transport-modes.md	传输模式说明
docs/v1/message-extensions.md	消息扩展机制

---

项目结构

synapse/
├── cmd/                    # 命令行入口（待实现）
├── configs/                # 配置文件目录
├── docs/                   # 文档
│   ├── v0/                 # v0 版本协议文档
│   ├── v1/                 # v1 版本协议文档
│   └── poster*.svg         # 宣传海报（多种配色）
├── internal/               # 内部实现代码
│   ├── agent/              # Agent 协议实现
│   │   ├── group/          # A2N 群组协议
│   │   └── p2p/            # A2A 点对点协议
│   ├── api/                # API 层
│   │   ├── externalapi/    # P2A 外部 HTTP API
│   │   └── grpcapi/        # gRPC API
│   ├── capabilities/       # 能力发现
│   ├── components/         # 七大核心组件
│   │   ├── harbor/         # 灵泊 - 异步队列
│   │   ├── libra/          # 灵衡 - 价值结算
│   │   ├── meridian/       # 灵脉 - 寻址路由
│   │   ├── panorama/       # 灵瞰 - 可观测性
│   │   ├── pivot/          # 灵枢 - 熔断治理
│   │   ├── sigil/          # 灵玺 - 身份凭证
│   │   └── speculum/       # 灵鉴 - 共识裁决
│   ├── hil/                # 人工干预机制
│   ├── routing/            # 路由层
│   └── transport/          # 传输层
├── pkg/                    # 公共库
│   ├── sdk/                # 统一 SDK
│   └── types/              # 核心类型定义
├── proto/                  # Protocol Buffers 定义
├── test/                   # 测试数据和集成测试
├── go.mod
├── go.sum
├── CHANGELOG.md
└── README.md

---

开发

编译

go build ./...

运行测试

# 运行所有测试（跳过自动生成代码的 vet 检查）
go test -vet=off ./...

# 运行特定包测试
go test -v ./pkg/types/...
go test -v ./internal/agent/p2p/...

重新生成 gRPC 代码

如果修改了 proto/synapse.proto，需要重新生成 Go 代码：

# 安装必要工具
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway@latest
go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2@latest

# 生成代码
protoc -I proto/ \
  --go_out=. --go_opt=module=synapse \
  --go-grpc_out=. --go-grpc_opt=module=synapse \
  proto/synapse.proto

---

许可证

Apache 2.0

---

灵隙之间，万物相连 — Synapse Protocol Suite v1.0.0