ai/synapse

Fork 0

Files

lychang 65710a4536 灵隙(synapse) v1.0.0 版本

2026-06-29 02:12:44 +08:00

10 KiB

Raw Permalink Blame History

灵隙（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 协议规范
│   ├── 00-record/          # 会议与决策记录
│   ├── 01-draft/           # 草案与方案提议
│   ├── 02-guide/           # 实现指南参考
│   └── 03-asset/           # 资源附件（海报等）
├── 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

10 KiB Raw Permalink Blame History Unescape Escape