灵隙(synapse) v1.0.0 版本

This commit is contained in:
lychang
2026-06-27 14:08:30 +08:00
parent a73ff857bb
commit 713292489f
44 changed files with 21884 additions and 0 deletions

525
proto/synapse.proto Normal file
View File

@@ -0,0 +1,525 @@
syntax = "proto3";
package synapse;
option go_package = "synapse/grpcapi;synapse";
import "google/protobuf/any.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/empty.proto";
import "google/api/annotations.proto";
import "protoc-gen-openapiv2/options/annotations.proto";
// =============================================================================
// Synapse gRPC Protocol Definition
// =============================================================================
option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
info: {
title: "Synapse Protocol API";
version: "1.0.0";
description: "Synapse (灵隙) - Multi-agent collaboration protocol with gRPC and HTTP gateway support";
};
schemes: HTTPS;
consumes: "application/json";
produces: "application/json";
};
// =============================================================================
// Core Enums
// =============================================================================
enum TransportMode {
TRANSPORT_MODE_UNSPECIFIED = 0;
TRANSPORT_MODE_CALLBACK = 1;
TRANSPORT_MODE_POLLING = 2;
TRANSPORT_MODE_SYNC = 3;
TRANSPORT_MODE_HYBRID = 4;
}
enum MessageType {
MESSAGE_TYPE_UNSPECIFIED = 0;
MESSAGE_TYPE_P2P_TASK_REQUEST = 1;
MESSAGE_TYPE_P2P_TASK_COMPLETE = 2;
MESSAGE_TYPE_P2P_TASK_FAILED = 3;
MESSAGE_TYPE_P2P_STATUS_UPDATE = 4;
MESSAGE_TYPE_P2P_INFO_MISSING = 5;
MESSAGE_TYPE_P2P_ACK = 6;
MESSAGE_TYPE_P2P_NACK = 7;
MESSAGE_TYPE_GROUP_INVITE = 8;
MESSAGE_TYPE_GROUP_JOIN = 9;
MESSAGE_TYPE_GROUP_LEAVE = 10;
MESSAGE_TYPE_GROUP_TASK_SPLIT = 11;
MESSAGE_TYPE_GROUP_SUBTASK_RESULT = 12;
MESSAGE_TYPE_GROUP_RESULT_MERGE = 13;
MESSAGE_TYPE_GROUP_VOTE_INITIATE = 14;
MESSAGE_TYPE_GROUP_VOTE_SUBMIT = 15;
MESSAGE_TYPE_GROUP_VOTE_RESULT = 16;
MESSAGE_TYPE_HIL_DECISION_REQUEST = 17;
MESSAGE_TYPE_HIL_DECISION_RESPONSE = 18;
MESSAGE_TYPE_HEARTBEAT = 19;
}
enum TaskStatus {
TASK_STATUS_UNSPECIFIED = 0;
TASK_STATUS_RECEIVED = 1;
TASK_STATUS_PROCESSING = 2;
TASK_STATUS_COMPLETED = 3;
TASK_STATUS_FAILED = 4;
TASK_STATUS_CANCELLED = 5;
TASK_STATUS_REJECTED = 6;
TASK_STATUS_WAITING = 7;
}
// =============================================================================
// Core Messages
// =============================================================================
message AgentEndpoint {
string agent_id = 1;
string agent_name = 2;
string system_id = 3;
string endpoint = 4;
string version = 5;
}
message SynapseMessage {
string id = 1;
string version = 2;
MessageType type = 3;
AgentEndpoint sender = 4;
AgentEndpoint receiver = 5;
string correlation_id = 6;
string reply_to = 7;
string group_id = 8;
google.protobuf.Timestamp timestamp = 9;
google.protobuf.Any payload = 10;
string signature = 11;
}
message TaskPayload {
string task_id = 1;
string task_type = 2;
google.protobuf.Any payload = 3;
string external_task_id = 4;
}
message TaskResult {
string task_id = 1;
string task_type = 2;
google.protobuf.Any result = 3;
string summary = 4;
}
message TaskStatusUpdate {
string task_id = 1;
TaskStatus status = 2;
int32 progress = 3;
string message = 4;
google.protobuf.Any details = 5;
}
// =============================================================================
// Task Service
// =============================================================================
service TaskService {
// SubmitTask 提交任务
rpc SubmitTask(SubmitTaskRequest) returns (SubmitTaskResponse) {
option (google.api.http) = {
post: "/api/v1/synapse/task"
body: "*"
};
}
// SubmitTaskWithFiles 提交带文件的任务(Multipart)
rpc SubmitTaskWithFiles(SubmitTaskWithFilesRequest) returns (SubmitTaskResponse) {
option (google.api.http) = {
post: "/api/v1/synapse/task/multipart"
body: "*"
};
}
// GetTask 获取任务详情
rpc GetTask(GetTaskRequest) returns (TaskStatusResponse) {
option (google.api.http) = {
get: "/api/v1/synapse/task/{task_id}"
};
}
// GetTaskStatus 获取任务状态(简化)
rpc GetTaskStatus(GetTaskRequest) returns (TaskStatusResponse) {
option (google.api.http) = {
get: "/api/v1/synapse/task/{task_id}/status"
};
}
// ListTasks 任务列表
rpc ListTasks(ListTasksRequest) returns (ListTasksResponse) {
option (google.api.http) = {
get: "/api/v1/synapse/tasks"
};
}
// CancelTask 取消任务
rpc CancelTask(CancelTaskRequest) returns (CancelTaskResponse) {
option (google.api.http) = {
post: "/api/v1/synapse/task/{task_id}/cancel"
};
}
// StreamTaskStatus 流式获取任务状态(双向流)
rpc StreamTaskStatus(stream TaskStatusStreamRequest) returns (stream TaskStatusUpdate);
}
// =============================================================================
// Task Request/Response Messages
// =============================================================================
message SubmitTaskRequest {
string task_type = 1;
google.protobuf.Any payload = 2;
string external_task_id = 3;
string priority = 4;
string callback_url = 5;
string callback_token = 6;
TransportMode preferred_transport = 7;
}
message SubmitTaskResponse {
bool success = 1;
string task_id = 2;
TaskStatus status = 3;
string message = 4;
string error_code = 5;
}
message SubmitTaskWithFilesRequest {
SubmitTaskRequest request = 1;
repeated FileUpload files = 2;
}
message FileUpload {
string field_name = 1;
string filename = 2;
string mime_type = 3;
bytes data = 4;
}
message GetTaskRequest {
string task_id = 1;
}
message TaskStatusResponse {
bool success = 1;
TaskInfo task = 2;
string error_code = 3;
string error_message = 4;
}
message TaskInfo {
string id = 1;
string type = 2;
TaskStatus status = 3;
int32 progress = 4;
string message = 5;
google.protobuf.Timestamp created_at = 6;
google.protobuf.Timestamp updated_at = 7;
google.protobuf.Timestamp completed_at = 8;
google.protobuf.Timestamp eta = 9;
google.protobuf.Any result = 10;
TaskError error = 11;
string external_task_id = 12;
}
message TaskError {
string code = 1;
string message = 2;
}
message ListTasksRequest {
string status = 1;
int32 limit = 2;
int32 offset = 3;
}
message ListTasksResponse {
bool success = 1;
repeated TaskInfo tasks = 2;
int32 total = 3;
int32 limit = 4;
int32 offset = 5;
bool has_more = 6;
}
message CancelTaskRequest {
string task_id = 1;
}
message CancelTaskResponse {
bool success = 1;
string task_id = 2;
TaskStatus status = 3;
string message = 4;
}
// =============================================================================
// Stream Messages
// =============================================================================
message TaskStatusStreamRequest {
string task_id = 1;
bool subscribe = 2; // true=订阅, false=取消订阅
}
// =============================================================================
// Synapse Message Service
// =============================================================================
service SynapseMessageService {
// SendMessage 发送Synapse消息(Unary)
rpc SendMessage(SendMessageRequest) returns (SendMessageResponse) {
option (google.api.http) = {
post: "/api/v1/synapse/message"
body: "*"
};
}
// StreamMessages 双向流式消息传输
rpc StreamMessages(stream SynapseMessage) returns (stream SynapseMessage);
// ReceiveCallback 接收回调消息
rpc ReceiveCallback(google.protobuf.Empty) returns (stream SynapseMessage) {
option (google.api.http) = {
post: "/api/v1/synapse/callback"
body: "*"
};
}
}
message SendMessageRequest {
SynapseMessage message = 1;
}
message SendMessageResponse {
bool success = 1;
string message_id = 2;
string error = 3;
}
// =============================================================================
// Capabilities Service
// =============================================================================
service CapabilitiesService {
// GetCapabilities 获取Agent能力
rpc GetCapabilities(google.protobuf.Empty) returns (CapabilitiesResponse) {
option (google.api.http) = {
get: "/api/v1/synapse/capabilities"
};
}
// QueryAgent 查询特定Agent的能力
rpc QueryAgent(QueryAgentRequest) returns (CapabilitiesResponse) {
option (google.api.http) = {
get: "/api/v1/synapse/agents/{agent_id}"
};
}
// ListAgents 列出可用Agent
rpc ListAgents(google.protobuf.Empty) returns (ListAgentsResponse) {
option (google.api.http) = {
get: "/api/v1/synapse/agents"
};
}
}
message CapabilitiesResponse {
bool success = 1;
AgentCapabilities capabilities = 2;
string error = 3;
}
message AgentCapabilities {
string agent_id = 1;
string agent_name = 2;
string system_id = 3;
string protocol_version = 4;
repeated SupportedTaskType supported_task_types = 5;
repeated string supported_content_types = 6;
repeated TransportMode supported_transport_modes = 7;
int64 max_file_size = 8;
int32 max_concurrent_tasks = 9;
int32 max_task_duration_seconds = 10;
bool support_progress_updates = 11;
bool support_streaming = 12;
bool support_hil = 13;
bool support_groups = 14;
}
message SupportedTaskType {
string type = 1;
string name = 2;
string description = 3;
string estimated_time = 4;
string input_schema = 5;
string output_schema = 6;
repeated string capabilities = 7;
}
message QueryAgentRequest {
string agent_id = 1;
}
message ListAgentsResponse {
bool success = 1;
repeated AgentInfo agents = 2;
int32 total = 3;
}
message AgentInfo {
string id = 1;
string agent_id = 2;
string agent_name = 3;
string system_id = 4;
string endpoint = 5;
bool is_active = 6;
int32 trust_level = 7;
}
// =============================================================================
// Group Service
// =============================================================================
service GroupService {
// CreateGroup 创建群组
rpc CreateGroup(CreateGroupRequest) returns (CreateGroupResponse) {
option (google.api.http) = {
post: "/api/v1/synapse/group"
body: "*"
};
}
// JoinGroup 加入群组
rpc JoinGroup(JoinGroupRequest) returns (JoinGroupResponse) {
option (google.api.http) = {
post: "/api/v1/synapse/group/{group_id}/join"
body: "*"
};
}
// LeaveGroup 离开群组
rpc LeaveGroup(LeaveGroupRequest) returns (LeaveGroupResponse) {
option (google.api.http) = {
post: "/api/v1/synapse/group/{group_id}/leave"
body: "*"
};
}
// DisbandGroup 解散群组
rpc DisbandGroup(DisbandGroupRequest) returns (DisbandGroupResponse) {
option (google.api.http) = {
post: "/api/v1/synapse/group/{group_id}/disband"
body: "*"
};
}
// ListGroupMembers 列出群组成员
rpc ListGroupMembers(ListGroupMembersRequest) returns (ListGroupMembersResponse) {
option (google.api.http) = {
get: "/api/v1/synapse/group/{group_id}/members"
};
}
// StreamGroupMessages 群组消息流
rpc StreamGroupMessages(stream SynapseMessage) returns (stream SynapseMessage);
}
message CreateGroupRequest {
string name = 1;
string description = 2;
string coordinator_id = 3;
repeated string initial_members = 4;
}
message CreateGroupResponse {
bool success = 1;
string group_id = 2;
GroupInfo group = 3;
string error = 4;
}
message GroupInfo {
string id = 1;
string name = 2;
string description = 3;
string coordinator_id = 4;
string status = 5;
google.protobuf.Timestamp created_at = 6;
}
message JoinGroupRequest {
string group_id = 1;
AgentEndpoint agent = 2;
}
message JoinGroupResponse {
bool success = 1;
string error = 2;
}
message LeaveGroupRequest {
string group_id = 1;
string agent_id = 2;
}
message LeaveGroupResponse {
bool success = 1;
string error = 2;
}
message DisbandGroupRequest {
string group_id = 1;
}
message DisbandGroupResponse {
bool success = 1;
string error = 2;
}
message ListGroupMembersRequest {
string group_id = 1;
}
message ListGroupMembersResponse {
bool success = 1;
repeated GroupMember members = 2;
}
message GroupMember {
string agent_id = 1;
string agent_name = 2;
string role = 3;
string status = 4;
google.protobuf.Timestamp joined_at = 5;
}
// =============================================================================
// Health Service
// =============================================================================
service HealthService {
// HealthCheck 健康检查
rpc HealthCheck(google.protobuf.Empty) returns (HealthCheckResponse) {
option (google.api.http) = {
get: "/api/v1/synapse/health"
};
}
}
message HealthCheckResponse {
string status = 1;
string version = 2;
int64 uptime_seconds = 3;
int32 active_tasks = 4;
}