灵隙(synapse) v1.0.0 版本
This commit is contained in:
192
README.md
Normal file
192
README.md
Normal file
@@ -0,0 +1,192 @@
|
||||
<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 get github.com/synapse/sdk
|
||||
|
||||
# 编写 Agent
|
||||
```
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"synapse/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)
|
||||
|
||||
// 发送任务
|
||||
taskID, _ := client.SendTaskRequest(
|
||||
context.Background(),
|
||||
types.AgentEndpoint{AgentID: "agent-002", Endpoint: "http://agent-002:8080"},
|
||||
"text_generation",
|
||||
map[string]any{"prompt": "写一首诗"},
|
||||
)
|
||||
|
||||
// 等待结果
|
||||
result, _ := client.WaitForTaskA2A(context.Background(), taskID, 5*time.Minute)
|
||||
println(result.Message)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 协议文档
|
||||
|
||||
| 文档 | 说明 |
|
||||
|------|------|
|
||||
| [docs/v1/index.md](docs/v1/index.md) | 协议索引与概览 |
|
||||
| [docs/v1/raw-protocol.md](docs/v1/raw-protocol.md) | 原始协议(公共基础) |
|
||||
| [docs/v1/a2a-protocol.md](docs/v1/a2a-protocol.md) | A2A 协议(点对点) |
|
||||
| [docs/v1/a2n-protocol.md](docs/v1/a2n-protocol.md) | A2N 协议(群组协作) |
|
||||
| [docs/v1/p2a-protocol.md](docs/v1/p2a-protocol.md) | P2A 协议(外部调用) |
|
||||
| [docs/v1/identity-protocol-draft.md](docs/v1/identity-protocol-draft.md) | 去中心化身份与寻址(草案) |
|
||||
| [docs/v1/components.md](docs/v1/components.md) | 七大组件层规范 |
|
||||
| [docs/v1/error-codes.md](docs/v1/error-codes.md) | 数字分段错误码 |
|
||||
|
||||
---
|
||||
|
||||
## 许可证
|
||||
|
||||
Apache 2.0
|
||||
|
||||
---
|
||||
|
||||
*灵隙之间,万物相连 — Synapse Protocol Suite v1.0.0*
|
||||
Reference in New Issue
Block a user