灵隙(synapse) v1.0.0 版本

This commit is contained in:
lychang
2026-06-29 00:48:45 +08:00
parent 6d1234efff
commit db716f94ac
6 changed files with 334 additions and 107 deletions

269
README.md
View File

@@ -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
```
---