灵隙(synapse) v1.0.0 版本
This commit is contained in:
269
README.md
269
README.md
@@ -15,6 +15,7 @@
|
||||
灵隙,英文名 **Synapse**,是一套专为 AI 智能体(Agent)设计的**协作协议栈**。
|
||||
|
||||
"灵隙"的含义:
|
||||
|
||||
- **灵** — 智能体的智慧与能力
|
||||
- **隙** — 智能体之间的空间与连接
|
||||
|
||||
@@ -28,13 +29,13 @@
|
||||
|
||||
### 典型场景
|
||||
|
||||
| 场景 | 说明 |
|
||||
|------|------|
|
||||
| 场景 | 说明 |
|
||||
|-------------------|----------------------------------------|
|
||||
| 🤖 **多 Agent 协作** | 一个 Agent 负责分析,另一个负责生成,第三个负责审核,协同完成一份报告 |
|
||||
| 🔗 **系统集成** | 后端服务通过 REST API 调用 Agent 能力,无需实现完整协议 |
|
||||
| 🧩 **任务分解** | 复杂任务拆分为多个子任务,分配给不同 Agent 并行执行 |
|
||||
| 👥 **群体决策** | 多个 Agent 对同一问题进行投票,达成共识后再执行 |
|
||||
| 🛡️ **人工兜底** | Agent 遇到无法决策的情况时,升级给人类做最终决定 |
|
||||
| 🔗 **系统集成** | 后端服务通过 REST API 调用 Agent 能力,无需实现完整协议 |
|
||||
| 🧩 **任务分解** | 复杂任务拆分为多个子任务,分配给不同 Agent 并行执行 |
|
||||
| 👥 **群体决策** | 多个 Agent 对同一问题进行投票,达成共识后再执行 |
|
||||
| 🛡️ **人工兜底** | Agent 遇到无法决策的情况时,升级给人类做最终决定 |
|
||||
|
||||
---
|
||||
|
||||
@@ -50,8 +51,8 @@
|
||||
import "synapse/sdk"
|
||||
|
||||
client := sdk.NewClient(sdk.Config{
|
||||
Protocol: sdk.ProtoA2A,
|
||||
AgentEndpoint: myEndpoint,
|
||||
Protocol: sdk.ProtoA2A,
|
||||
AgentEndpoint: myEndpoint,
|
||||
})
|
||||
|
||||
taskID, _ := client.SendTaskRequest(ctx, targetAgent, "text_generation", payload)
|
||||
@@ -64,8 +65,8 @@ result, _ := client.WaitForTaskA2A(ctx, taskID, 5*time.Minute)
|
||||
|
||||
```go
|
||||
client := sdk.NewClient(sdk.Config{
|
||||
Protocol: sdk.ProtoA2N,
|
||||
AgentEndpoint: myEndpoint,
|
||||
Protocol: sdk.ProtoA2N,
|
||||
AgentEndpoint: myEndpoint,
|
||||
})
|
||||
|
||||
group, _ := client.CreateGroup(ctx, "分析小组", topology, nil, members)
|
||||
@@ -78,9 +79,9 @@ subtasks, _ := client.SubmitGroupTask(ctx, group.GroupID, "analysis", req, "majo
|
||||
|
||||
```go
|
||||
client := sdk.NewClient(sdk.Config{
|
||||
Protocol: sdk.ProtoP2A,
|
||||
BaseURL: "http://agent-service:8080",
|
||||
APIKey: "sk-xxx",
|
||||
Protocol: sdk.ProtoP2A,
|
||||
BaseURL: "http://agent-service:8080",
|
||||
APIKey: "sk-xxx",
|
||||
})
|
||||
|
||||
result, _ := client.CreateAndWait(ctx, "text_generation", payload, 5*time.Second)
|
||||
@@ -94,28 +95,28 @@ result, _ := client.CreateAndWait(ctx, "text_generation", payload, 5*time.Second
|
||||
|
||||
## 七大组件层
|
||||
|
||||
| 组件 | 名称 | 职责 |
|
||||
|------|------|------|
|
||||
| 灵脉 | Meridian | 寻址与路由 |
|
||||
| 灵玺 | Sigil | 身份与凭证 |
|
||||
| 灵鉴 | Speculum | 共识与裁决 |
|
||||
| 灵泊 | Harbor | 异步队列与暂存 |
|
||||
| 灵瞰 | Panorama | 可观测与度量 |
|
||||
| 灵衡 | Libra | 价值结算与激励 |
|
||||
| 灵枢 | Pivot | 紧急制动与治理 |
|
||||
| 组件 | 名称 | 职责 |
|
||||
|----|----------|---------|
|
||||
| 灵脉 | Meridian | 寻址与路由 |
|
||||
| 灵玺 | Sigil | 身份与凭证 |
|
||||
| 灵鉴 | Speculum | 共识与裁决 |
|
||||
| 灵泊 | Harbor | 异步队列与暂存 |
|
||||
| 灵瞰 | Panorama | 可观测与度量 |
|
||||
| 灵衡 | Libra | 价值结算与激励 |
|
||||
| 灵枢 | Pivot | 紧急制动与治理 |
|
||||
|
||||
---
|
||||
|
||||
## 特色能力
|
||||
|
||||
| 能力 | 说明 |
|
||||
|------|------|
|
||||
| 🔐 **去中心化身份** | 公钥派生 AgentID,无需中心化注册 |
|
||||
| 🧠 **三级 HiL 升级** | Agent 建议 → 人工决策 → 专家仲裁 |
|
||||
| 📦 **内容类型系统** | 文本 / JSON / 代码 / 文件 / 内容包 |
|
||||
| 🔢 **数字分段错误码** | 9 大类 35+ 个错误码,便于国际化 |
|
||||
| 🛤️ **双传输模式** | gRPC + HTTP REST,gRPC-Gateway 桥接 |
|
||||
| ⚡ **熔断与治理** | 熔断器 + 5 级治理级别,保障系统稳定 |
|
||||
| 能力 | 说明 |
|
||||
|------------------|----------------------------------|
|
||||
| 🔐 **去中心化身份** | 公钥派生 AgentID,无需中心化注册 |
|
||||
| 🧠 **三级 HiL 升级** | Agent 建议 → 人工决策 → 专家仲裁 |
|
||||
| 📦 **内容类型系统** | 文本 / JSON / 代码 / 文件 / 内容包 |
|
||||
| 🔢 **数字分段错误码** | 9 大类 35+ 个错误码,便于国际化 |
|
||||
| 🛤️ **双传输模式** | gRPC + HTTP REST,gRPC-Gateway 桥接 |
|
||||
| ⚡ **熔断与治理** | 熔断器 + 5 级治理级别,保障系统稳定 |
|
||||
|
||||
---
|
||||
|
||||
@@ -125,44 +126,93 @@ result, _ := client.CreateAndWait(ctx, "text_generation", payload, 5*time.Second
|
||||
# 初始化项目
|
||||
go mod init my-agent
|
||||
|
||||
# 引入灵隙 SDK
|
||||
go get github.com/synapse/sdk
|
||||
|
||||
# 编写 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"
|
||||
"synapse/sdk"
|
||||
"synapse/pkg/types"
|
||||
"context"
|
||||
"fmt"
|
||||
"time"
|
||||
|
||||
"synapse/pkg/sdk"
|
||||
)
|
||||
|
||||
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(sdk.Config{
|
||||
Protocol: sdk.ProtoP2A,
|
||||
BaseURL: "http://agent-service:8080",
|
||||
APIKey: "sk-xxx",
|
||||
})
|
||||
|
||||
client := sdk.NewClient(cfg)
|
||||
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)
|
||||
}
|
||||
```
|
||||
|
||||
// 发送任务
|
||||
taskID, _ := client.SendTaskRequest(
|
||||
context.Background(),
|
||||
types.AgentEndpoint{AgentID: "agent-002", Endpoint: "http://agent-002:8080"},
|
||||
"text_generation",
|
||||
map[string]any{"prompt": "写一首诗"},
|
||||
)
|
||||
### A2A — Agent 间点对点协作
|
||||
|
||||
// 等待结果
|
||||
result, _ := client.WaitForTaskA2A(context.Background(), taskID, 5*time.Minute)
|
||||
println(result.Message)
|
||||
```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)
|
||||
}
|
||||
```
|
||||
|
||||
@@ -170,16 +220,103 @@ func main() {
|
||||
|
||||
## 协议文档
|
||||
|
||||
| 文档 | 说明 |
|
||||
|------|------|
|
||||
| [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) | 数字分段错误码 |
|
||||
| 文档 | 说明 |
|
||||
|--------------------------------------------------------------------------------|---------------|
|
||||
| [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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user