# 灵隙协议实现规范：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（开发环境）

---

**文档结束**