From 6d1234efffef02748b475c0bcb96f72276357b03 Mon Sep 17 00:00:00 2001 From: lychang <632945494@qq.com> Date: Sun, 28 Jun 2026 23:20:00 +0800 Subject: [PATCH] =?UTF-8?q?=E7=81=B5=E9=9A=99(synapse)=20v1.0.0=20?= =?UTF-8?q?=E7=89=88=E6=9C=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 192 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..5ce10e5 --- /dev/null +++ b/README.md @@ -0,0 +1,192 @@ + + + 灵隙 Synapse + + +# 灵隙(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*