330 lines
9.8 KiB
Markdown
330 lines
9.8 KiB
Markdown
<picture>
|
||
<source media="(prefers-color-scheme: dark)" srcset="docs/poster.svg">
|
||
<img src="docs/poster.svg" alt="灵隙 Synapse" width="100%">
|
||
</picture>
|
||
|
||
# 灵隙（Synapse）— 智能体协作协议栈
|
||
|
||
> **灵隙之间，万物相连**
|
||
> 一套开放、安全、可扩展的 AI 智能体协作协议栈
|
||
|
||
---
|
||
|
||
## 什么是灵隙？
|
||
|
||
灵隙，英文名 **Synapse**，是一套专为 AI 智能体（Agent）设计的**协作协议栈**。
|
||
|
||
"灵隙"的含义：
|
||
|
||
- **灵** — 智能体的智慧与能力
|
||
- **隙** — 智能体之间的空间与连接
|
||
|
||
灵隙不是某一个 Agent 的实现，而是**定义了 Agent 之间如何对话、如何协作、如何信任**的通用规则。
|
||
|
||
---
|
||
|
||
## 用它来做什么？
|
||
|
||
灵隙解决的核心问题：**AI 智能体之间如何协同完成复杂任务？**
|
||
|
||
### 典型场景
|
||
|
||
| 场景 | 说明 |
|
||
|-------------------|----------------------------------------|
|
||
| 🤖 **多 Agent 协作** | 一个 Agent 负责分析，另一个负责生成，第三个负责审核，协同完成一份报告 |
|
||
| 🔗 **系统集成** | 后端服务通过 REST API 调用 Agent 能力，无需实现完整协议 |
|
||
| 🧩 **任务分解** | 复杂任务拆分为多个子任务，分配给不同 Agent 并行执行 |
|
||
| 👥 **群体决策** | 多个 Agent 对同一问题进行投票，达成共识后再执行 |
|
||
| 🛡️ **人工兜底** | Agent 遇到无法决策的情况时，升级给人类做最终决定 |
|
||
|
||
---
|
||
|
||
## 核心协议
|
||
|
||
灵隙协议栈包含三个子协议和一个公共基础：
|
||
|
||
### A2A — 点对点通信
|
||
|
||
两个 Agent 之间直接的任务协作：
|
||
|
||
```go
|
||
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 协同工作：
|
||
|
||
```go
|
||
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：
|
||
|
||
```go
|
||
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 级治理级别，保障系统稳定 |
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
# 初始化项目
|
||
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
|
||
|
||
```go
|
||
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 间点对点协作
|
||
|
||
```go
|
||
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/00_index.md) | 协议索引与概览 |
|
||
| [docs/v1/01_raw-protocol.md](docs/v1/01_raw-protocol.md) | 原始协议（公共基础） |
|
||
| [docs/v1/02_a2a-protocol.md](docs/v1/02_a2a-protocol.md) | A2A 协议（点对点） |
|
||
| [docs/v1/03_a2n-protocol.md](docs/v1/03_a2n-protocol.md) | A2N 协议（群组协作） |
|
||
| [docs/v1/04_p2a-protocol.md](docs/v1/04_p2a-protocol.md) | P2A 协议（外部调用） |
|
||
| [docs/v1/05_identity-protocol-draft.md](docs/v1/05_identity-protocol-draft.md) | 去中心化身份与寻址（草案） |
|
||
| [docs/v1/components.md](docs/v1/components.md) | 七大组件层规范 |
|
||
| [docs/v1/content-system.md](docs/v1/content-system.md) | 内容类型系统 |
|
||
| [docs/v1/capabilities-system.md](docs/v1/capabilities-system.md) | 能力发现系统 |
|
||
| [docs/v1/error-codes.md](docs/v1/error-codes.md) | 数字分段错误码 |
|
||
| [docs/v1/hil-mechanism.md](docs/v1/hil-mechanism.md) | 人工干预机制 (HiL) |
|
||
| [docs/v1/grpc-transport.md](docs/v1/grpc-transport.md) | gRPC 传输规范 |
|
||
| [docs/v1/transport-modes.md](docs/v1/transport-modes.md) | 传输模式说明 |
|
||
| [docs/v1/message-extensions.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
|
||
```
|
||
|
||
---
|
||
|
||
## 开发
|
||
|
||
### 编译
|
||
|
||
```bash
|
||
go build ./...
|
||
```
|
||
|
||
### 运行测试
|
||
|
||
```bash
|
||
# 运行所有测试（跳过自动生成代码的 vet 检查）
|
||
go test -vet=off ./...
|
||
|
||
# 运行特定包测试
|
||
go test -v ./pkg/types/...
|
||
go test -v ./internal/agent/p2p/...
|
||
```
|
||
|
||
### 重新生成 gRPC 代码
|
||
|
||
如果修改了 `proto/synapse.proto`，需要重新生成 Go 代码：
|
||
|
||
```bash
|
||
# 安装必要工具
|
||
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*
|