灵隙(synapse) v1.0.0 版本

This commit is contained in:
lychang
2026-06-29 00:53:42 +08:00
parent db716f94ac
commit 2c59efe0ca
19 changed files with 19 additions and 19 deletions

View File

@@ -0,0 +1,521 @@
# 灵隙协议实现规范:gRPC 传输协议
> 版本:1.0.0 | 层级:实现层
---
## 1. Proto 定义位置说明
Synapse 协议的 gRPC 服务定义统一存放于以下位置:
```
proto/
├── synapse.proto # 主 proto 文件,包含所有服务与消息定义
├── synapse_common.proto # 公共消息类型(可选拆分)
├── google/
│ └── api/
│ ├── annotations.proto # Google HTTP 注解依赖
│ └── http.proto
└── protoc-gen-openapiv2/
└── options/
└── annotations.proto # OpenAPI v2 注解依赖(可选)
```
主定义文件 [`synapse.proto`](file:///proto/synapse.proto) 包含:
- 5 个 gRPC 服务(TaskService、SynapseMessageService、CapabilitiesService、GroupService、HealthService)
- 20 个 RPC 方法
- 对应的请求/响应消息类型
- `google.api.http` 注解,用于通过 gRPC Gateway 生成 HTTP REST 端点
通过 `buf` 或 `protoc` 工具链编译生成:
| 生成产物 | 说明 |
|---------|------|
| `synapse.pb.go` | gRPC 服务端/客户端桩代码 |
| `synapse.pb.gw.go` | gRPC Gateway 反向代理代码 |
| `synapse.swagger.json` | OpenAPI v2 规范文档(可选) |
---
## 2. 服务定义
### 2.1 TaskService(任务服务)
任务服务是协议核心,负责任务的提交、查询、取消与状态流式推送。
```protobuf
service TaskService {
// 提交任务(JSON payload)
rpc SubmitTask(SubmitTaskRequest) returns (SubmitTaskResponse);
// 提交任务(含文件附件,Multipart)
rpc SubmitTaskWithFiles(SubmitTaskWithFilesRequest) returns (SubmitTaskResponse);
// 获取任务完整信息
rpc GetTask(GetTaskRequest) returns (TaskStatusResponse);
// 获取任务状态(轻量查询)
rpc GetTaskStatus(GetTaskRequest) returns (TaskStatusResponse);
// 获取任务列表(支持分页和过滤)
rpc ListTasks(ListTasksRequest) returns (ListTasksResponse);
// 取消任务
rpc CancelTask(CancelTaskRequest) returns (CancelTaskResponse);
// 流式监听任务状态变化(双向流)
rpc StreamTaskStatus(stream TaskStatusStreamRequest) returns (stream TaskStatusUpdate);
}
```
**RPC 方法列表:**
| # | 方法名 | 请求类型 | 响应类型 | 流式 |
|---|--------|---------|---------|------|
| 1 | `SubmitTask` | `SubmitTaskRequest` | `SubmitTaskResponse` | 否 |
| 2 | `SubmitTaskWithFiles` | `SubmitTaskWithFilesRequest` | `SubmitTaskResponse` | 否 |
| 3 | `GetTask` | `GetTaskRequest` | `TaskStatusResponse` | 否 |
| 4 | `GetTaskStatus` | `GetTaskRequest` | `TaskStatusResponse` | 否 |
| 5 | `ListTasks` | `ListTasksRequest` | `ListTasksResponse` | 否 |
| 6 | `CancelTask` | `CancelTaskRequest` | `CancelTaskResponse` | 否 |
| 7 | `StreamTaskStatus` | `stream TaskStatusStreamRequest` | `stream TaskStatusUpdate` | 双向流 |
### 2.2 SynapseMessageService(消息服务)
消息服务负责 Agent 间的异步消息传递、流式对话以及回调推送。
```protobuf
service SynapseMessageService {
// 发送单条消息
rpc SendMessage(SendMessageRequest) returns (SendMessageResponse);
// 流式消息交换(双向流,适用于多轮对话)
rpc StreamMessages(stream SynapseMessage) returns (stream SynapseMessage);
// 接收服务端推送的回调消息(服务器推送流)
rpc ReceiveCallback(google.protobuf.Empty) returns (stream SynapseMessage);
}
```
**RPC 方法列表:**
| # | 方法名 | 请求类型 | 响应类型 | 流式 |
|---|--------|---------|---------|------|
| 8 | `SendMessage` | `SendMessageRequest` | `SendMessageResponse` | 否 |
| 9 | `StreamMessages` | `stream SynapseMessage` | `stream SynapseMessage` | 双向流 |
| 10 | `ReceiveCallback` | `google.protobuf.Empty` | `stream SynapseMessage` | 服务端流 |
### 2.3 CapabilitiesService(能力服务)
能力服务提供 Agent 能力查询与发现机制。
```protobuf
service CapabilitiesService {
// 获取当前 Agent 自身的能力声明
rpc GetCapabilities(google.protobuf.Empty) returns (CapabilitiesResponse);
// 查询指定 Agent 的能力
rpc QueryAgent(QueryAgentRequest) returns (CapabilitiesResponse);
// 列出网络中所有活跃 Agent
rpc ListAgents(google.protobuf.Empty) returns (ListAgentsResponse);
}
```
**RPC 方法列表:**
| # | 方法名 | 请求类型 | 响应类型 | 流式 |
|---|--------|---------|---------|------|
| 11 | `GetCapabilities` | `google.protobuf.Empty` | `CapabilitiesResponse` | 否 |
| 12 | `QueryAgent` | `QueryAgentRequest` | `CapabilitiesResponse` | 否 |
| 13 | `ListAgents` | `google.protobuf.Empty` | `ListAgentsResponse` | 否 |
### 2.4 GroupService(群组服务)
群组服务支持 Agent 群的创建、成员管理与群内消息流。
```protobuf
service GroupService {
// 创建群组
rpc CreateGroup(CreateGroupRequest) returns (CreateGroupResponse);
// 加入群组
rpc JoinGroup(JoinGroupRequest) returns (JoinGroupResponse);
// 离开群组
rpc LeaveGroup(LeaveGroupRequest) returns (LeaveGroupResponse);
// 解散群组(仅群主/管理员)
rpc DisbandGroup(DisbandGroupRequest) returns (DisbandGroupResponse);
// 列出群组成员
rpc ListGroupMembers(ListGroupMembersRequest) returns (ListGroupMembersResponse);
// 流式收发群组消息(双向流)
rpc StreamGroupMessages(stream SynapseMessage) returns (stream SynapseMessage);
}
```
**RPC 方法列表:**
| # | 方法名 | 请求类型 | 响应类型 | 流式 |
|---|--------|---------|---------|------|
| 14 | `CreateGroup` | `CreateGroupRequest` | `CreateGroupResponse` | 否 |
| 15 | `JoinGroup` | `JoinGroupRequest` | `JoinGroupResponse` | 否 |
| 16 | `LeaveGroup` | `LeaveGroupRequest` | `LeaveGroupResponse` | 否 |
| 17 | `DisbandGroup` | `DisbandGroupRequest` | `DisbandGroupResponse` | 否 |
| 18 | `ListGroupMembers` | `ListGroupMembersRequest` | `ListGroupMembersResponse` | 否 |
| 19 | `StreamGroupMessages` | `stream SynapseMessage` | `stream SynapseMessage` | 双向流 |
### 2.5 HealthService(健康服务)
健康服务提供存活探针与健康状态检查。
```protobuf
service HealthService {
// 健康检查
rpc HealthCheck(google.protobuf.Empty) returns (HealthCheckResponse);
}
```
**RPC 方法列表:**
| # | 方法名 | 请求类型 | 响应类型 | 流式 |
|---|--------|---------|---------|------|
| 20 | `HealthCheck` | `google.protobuf.Empty` | `HealthCheckResponse` | 否 |
---
## 3. HTTP 路由映射表
通过 `google.api.http` 注解,每个 gRPC 方法映射为对应的 HTTP REST 端点。gRPC Gateway 在启动时读取这些注解,自动生成反向代理,使同一套后端可同时服务于 gRPC 和 HTTP 客户端。
### 3.1 完整映射表
| # | gRPC 方法 | HTTP 方法 | HTTP 路径 | 说明 |
|---|-----------|----------|----------|------|
| 1 | `SubmitTask` | `POST` | `/api/v1/synapse/task` | 提交任务 |
| 2 | `SubmitTaskWithFiles` | `POST` | `/api/v1/synapse/task/multipart` | 提交含附件的任务 |
| 3 | `GetTask` | `GET` | `/api/v1/synapse/task/{task_id}` | 获取任务详情 |
| 4 | `GetTaskStatus` | `GET` | `/api/v1/synapse/task/{task_id}/status` | 获取任务状态 |
| 5 | `ListTasks` | `GET` | `/api/v1/synapse/tasks` | 列出任务(支持分页) |
| 6 | `CancelTask` | `POST` | `/api/v1/synapse/task/{task_id}/cancel` | 取消任务 |
| 7 | `StreamTaskStatus` | `GET` | `/api/v1/synapse/task/{task_id}/stream` | SSE 流式监听任务状态 |
| 8 | `SendMessage` | `POST` | `/api/v1/synapse/message` | 发送消息 |
| 9 | `StreamMessages` | `GET` | `/api/v1/synapse/messages/stream` | WebSocket/SSE 流式消息交换 |
| 10 | `ReceiveCallback` | `GET` | `/api/v1/synapse/messages/callback` | SSE 接收服务端回调推送 |
| 11 | `GetCapabilities` | `GET` | `/api/v1/synapse/capabilities` | 获取自身能力声明 |
| 12 | `QueryAgent` | `GET` | `/api/v1/synapse/agents/{agent_id}` | 查询指定 Agent 能力 |
| 13 | `ListAgents` | `GET` | `/api/v1/synapse/agents` | 列出所有活跃 Agent |
| 14 | `CreateGroup` | `POST` | `/api/v1/synapse/group` | 创建群组 |
| 15 | `JoinGroup` | `POST` | `/api/v1/synapse/group/{group_id}/join` | 加入群组 |
| 16 | `LeaveGroup` | `POST` | `/api/v1/synapse/group/{group_id}/leave` | 离开群组 |
| 17 | `DisbandGroup` | `POST` | `/api/v1/synapse/group/{group_id}/disband` | 解散群组 |
| 18 | `ListGroupMembers` | `GET` | `/api/v1/synapse/group/{group_id}/members` | 列出群组成员 |
| 19 | `StreamGroupMessages` | `GET` | `/api/v1/synapse/group/{group_id}/messages/stream` | WebSocket/SSE 流式群组消息 |
| 20 | `HealthCheck` | `GET` | `/api/v1/synapse/health` | 健康检查 |
### 3.2 路由特性说明
**路径参数绑定**:
| 路径参数 | 绑定字段 | 示例值 |
|---------|---------|-------|
| `{task_id}` | `GetTaskRequest.task_id` | `"task-abc123"` |
| `{agent_id}` | `QueryAgentRequest.agent_id` | `"agent-xyz789"` |
| `{group_id}` | `JoinGroupRequest.group_id` | `"group-demo-001"` |
**请求体映射规则**:
- **POST 请求**:除路径参数外,剩余字段映射为 HTTP 请求体(JSON)
- **GET 请求**:非路径参数字段映射为 URL 查询参数(query string)
**流式端点说明**:
| 流式 RPC | HTTP 协议映射 | 说明 |
|---------|-------------|------|
| `StreamTaskStatus` | SSE(Server-Sent Events) | 服务端单向推送任务状态变更 |
| `StreamMessages` | WebSocket | 全双工流式消息交换 |
| `ReceiveCallback` | SSE(Server-Sent Events) | 服务端单向推送回调消息 |
| `StreamGroupMessages` | WebSocket | 全双工群组消息流 |
对于双向流 RPC(`StreamMessages`、`StreamGroupMessages`),HTTP REST 映射通过 WebSocket Upgrade 实现;对于服务端流 RPC(`StreamTaskStatus`、`ReceiveCallback`),通过 SSE(`text/event-stream`)实现。
### 3.3 路由前缀约定
所有 Synapse 协议 REST API 遵循以下 URL 前缀约定:
```
/api/v1/synapse/
```
- `api`:标识为 API 请求
- `v1`:API 版本号
- `synapse`:命名空间,区分 Synapse 协议与其他业务 API
版本升级时(如 v1 → v2),路径前缀同步更新为 `/api/v2/synapse/`,新旧版本可并行部署。
### 3.4 HTTP 状态码与 gRPC 状态码映射
| HTTP 状态码 | gRPC 状态码 | 说明 |
|------------|-------------|------|
| `200 OK` | `OK` | 请求成功 |
| `201 Created` | `OK` | 资源创建成功(SubmitTask、CreateGroup) |
| `400 Bad Request` | `InvalidArgument` | 请求参数无效 |
| `401 Unauthorized` | `Unauthenticated` | 认证失败 |
| `403 Forbidden` | `PermissionDenied` | 权限不足 |
| `404 Not Found` | `NotFound` | 资源不存在 |
| `409 Conflict` | `AlreadyExists` / `Aborted` | 资源冲突 |
| `429 Too Many Requests` | `ResourceExhausted` | 限流触发 |
| `500 Internal Server Error` | `Internal` | 服务端内部错误 |
| `503 Service Unavailable` | `Unavailable` | 服务不可用 |
gRPC Gateway 自动完成上述状态码转换,客户端无需额外处理。
---
## 4. 协议缓冲区消息结构概览
以下列出各服务核心 RPC 的请求与响应消息结构(仅示意字段分类,完整定义以 `.proto` 文件为准):
### 4.1 任务相关消息
```protobuf
// SubmitTask 请求
message SubmitTaskRequest {
string task_type = 1; // 任务类型
string payload_json = 2; // JSON 负载
string callback_url = 3; // 回调地址(可选)
int32 ttl_seconds = 4; // 任务 TTL(可选)
string idempotency_key = 5; // 幂等键(可选)
}
// SubmitTask 响应
message SubmitTaskResponse {
string task_id = 1; // 任务 ID
string status = 2; // 初始状态
string message = 3; // 附加信息
}
// 任务状态查询响应(通用)
message TaskStatusResponse {
string task_id = 1;
string status = 2;
int32 progress = 3; // 0-100
string result_json = 4; // 执行结果(JSON)
string error_message = 5;
string created_at = 6;
string updated_at = 7;
string etag = 8; // 用于增量查询
}
// 任务流式更新
message TaskStatusUpdate {
string task_id = 1;
string event_type = 2; // status_update / progress / log / error / complete
string data_json = 3;
}
```
### 4.2 消息相关消息
```protobuf
// SendMessage 请求
message SendMessageRequest {
string receiver_id = 1;
string content_type = 2; // text / json / code / file
string payload_json = 3;
string correlation_id = 4; // 关联 ID(可选)
string conversation_id = 5; // 会话 ID(可选)
}
// SendMessage 响应
message SendMessageResponse {
string message_id = 1;
string status = 2;
}
// 统一消息信封(用于流式传输)
message SynapseMessage {
string id = 1;
string sender_id = 2;
string receiver_id = 3;
string content_type = 4;
string payload_json = 5;
string correlation_id = 6;
string conversation_id = 7;
int64 timestamp = 8;
}
```
### 4.3 能力相关消息
```protobuf
message CapabilitiesResponse {
string agent_id = 1;
string agent_name = 2;
string protocol_version = 3;
repeated string supported_task_types = 4;
repeated string supported_content_types = 5;
int64 max_file_size = 6;
int32 max_concurrent_tasks = 7;
bool support_streaming = 8;
bool support_hil = 9;
bool support_groups = 10;
}
message QueryAgentRequest {
string agent_id = 1;
}
message ListAgentsResponse {
repeated AgentInfo agents = 1;
int32 total = 2;
}
message AgentInfo {
string agent_id = 1;
string agent_name = 2;
string endpoint = 3;
repeated string capabilities = 4;
string status = 5; // online / offline / busy
}
```
### 4.4 群组相关消息
```protobuf
message CreateGroupRequest {
string name = 1;
string description = 2;
repeated string initial_members = 3;
}
message CreateGroupResponse {
string group_id = 1;
string status = 2;
}
message JoinGroupRequest {
string group_id = 1;
string agent_id = 2;
}
message LeaveGroupRequest {
string group_id = 1;
string agent_id = 2;
}
message DisbandGroupRequest {
string group_id = 1;
string agent_id = 2; // 需群主或管理员权限
}
message ListGroupMembersRequest {
string group_id = 1;
}
message ListGroupMembersResponse {
string group_id = 1;
repeated GroupMember members = 2;
}
message GroupMember {
string agent_id = 1;
string role = 2; // owner / admin / member
string joined_at = 3;
}
```
### 4.5 健康检查消息
```protobuf
message HealthCheckResponse {
string status = 1; // SERVING / NOT_SERVING
string version = 2;
int64 uptime_seconds = 3;
}
```
---
## 5. 传输配置与使用指引
### 5.1 gRPC 客户端连接配置
```go
// 推荐 gRPC 客户端配置
conn, err := grpc.Dial(
target,
grpc.WithInsecure(), // 开发环境;生产环境使用 TLS
grpc.WithDefaultCallOptions(
grpc.MaxCallRecvMsgSize(10*1024*1024), // 最大接收消息 10MB
grpc.MaxCallSendMsgSize(10*1024*1024), // 最大发送消息 10MB
),
grpc.WithKeepaliveParams(keepalive.ClientParameters{
Time: 30 * time.Second, // 每 30s 发送心跳
Timeout: 10 * time.Second, // 心跳超时 10s
PermitWithoutStream: true, // 无活跃流时也发送心跳
}),
)
```
### 5.2 HTTP REST 客户端调用示例
```bash
# SubmitTask
curl -X POST http://localhost:8080/api/v1/synapse/task \
-H "Content-Type: application/json" \
-d '{"task_type":"text_generation","payload_json":"...","callback_url":"..."}'
# GetTask
curl http://localhost:8080/api/v1/synapse/task/task-abc123
# 流式监听任务状态(SSE)
curl -N http://localhost:8080/api/v1/synapse/task/task-abc123/stream
# HealthCheck
curl http://localhost:8080/api/v1/synapse/health
```
### 5.3 幂等性支持
对于 `SubmitTask` 和 `CreateGroup` 等写操作,建议通过 `idempotency_key` 字段实现幂等:
- 客户端为每个写操作生成唯一幂等键(如 UUID v4)
- 服务端缓存幂等键及其响应,相同键的重复请求返回缓存结果
- 幂等键缓存 TTL 默认为 24 小时
---
## 附录:gRPC Gateway 集成方式
```
┌─────────────────────────────────────────────────────┐
│ 外部客户端 │
│ gRPC Client HTTP Client (REST) │
└────────┬───────────────────────────────┬────────────┘
│ gRPC (h2) │ HTTP/1.1
▼ ▼
┌─────────────────┐ ┌──────────────────────┐
│ gRPC Server │ │ gRPC Gateway │
│ (直接服务) │◄────────►│ (反向代理 / 协议转换) │
└────────┬────────┘ └──────────────────────┘
│ 内部 gRPC 调用
▼
┌─────────────────────────────────────────────────────┐
│ Synapse 业务逻辑层 │
│ TaskService / MessageService / Capabilities ... │
└─────────────────────────────────────────────────────┘
```
推荐集成方式:
1. 在 Go 服务端使用 `grpc-gateway` 库,通过一行代码注册反向代理
2. 启动时同时监听两个端口(例:gRPC 端口 `9090`,HTTP 端口 `8080`)
3. HTTP 端口同时提供 REST API 和 Swagger UI(开发环境)
---
**文档结束**