<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*