goaiapi/proto/contract/v1/contract.proto

syntax = "proto3";
package contract.v1;
option go_package = "goaiapi/proto/contract/v1;contractv1";

// ─── 通用服务：每个插件都必须实现 ───
service PluginManifest {
  rpc GetManifest(GetManifestRequest) returns (GetManifestResponse);
  rpc HealthCheck(HealthCheckRequest) returns (HealthCheckResponse);
}

message GetManifestRequest {}
message GetManifestResponse {
  string name              = 1; // 插件唯一名，如 "echo-base"
  string version           = 2; // semver，如 "1.0.0"
  PluginTier tier          = 3; // 声明的层级（内核会用 DAG 复算校验）
  repeated Dependency deps = 4;
  repeated Capability caps = 5; // 本插件提供的 gRPC service 名
}

enum PluginTier {
  TIER_UNSPECIFIED = 0;
  TIER_BASE        = 1; // 无插件依赖
  TIER_MID         = 2; // 仅依赖 base
  TIER_COMPLEX     = 3; // 依赖至少一个非 base
}

message Dependency {
  string name               = 1; // 依赖的插件名
  string version_constraint = 2; // semver 约束，如 ">=1.0.0 <2.0.0"
}

message Capability {
  string service_name = 1; // 如 "EchoService"
}

message HealthCheckRequest {}
message HealthCheckResponse {
  bool   healthy = 1;
  string message = 2;
}

// ─── 调用代理：由内核托管，被插件调用 ───
service InvocationBroker {
  rpc Invoke(InvokeRequest) returns (InvokeResponse);
  rpc ListPlugins(ListPluginsRequest) returns (ListPluginsResponse);
}

message InvokeRequest {
  string target_plugin = 1; // 目标插件名
  string method        = 2; // 目标方法全路径，如 "/contract.v1.EchoService/Echo"
  bytes  payload       = 3; // 已序列化的请求（proto wire 字节）
}
message InvokeResponse {
  bytes  result = 1; // 已序列化的响应
  string error  = 2;
}

message ListPluginsRequest {}
message ListPluginsResponse { repeated PluginInfo plugins = 1; }
message PluginInfo {
  string     name    = 1;
  string     version = 2;
  PluginTier tier    = 3;
  bool       healthy = 4;
}

// ─── 样板服务 ───

// 基本插件
service EchoService { rpc Echo(EchoRequest) returns (EchoResponse); }
message EchoRequest  { string message = 1; }
message EchoResponse { string message = 1; string echoed_by = 2; }

// 依赖基本（内部调 Echo）
service TransformService { rpc Transform(TransformRequest) returns (TransformResponse); }
message TransformRequest  { string text = 1; string operation = 2; } // upper|lower|reverse
message TransformResponse { string result = 1; string via_echo = 2; }

// 复杂（依赖 base+mid，含 server-streaming，验证 SSE-over-gRPC）
service StreamingDemo {
  rpc UnaryPing(PingRequest) returns (PingResponse);
  rpc StreamEvents(StreamRequest) returns (stream StreamEvent);
}
message PingRequest  { string message = 1; }
message PingResponse { string message = 1; string pipeline = 2; }
message StreamRequest { int32 count = 1; int32 interval_ms = 2; }
message StreamEvent   { int32 sequence = 1; string payload = 2; int64 timestamp_ns = 3; }

// ─── Relay 业务服务（核心能力下沉为插件） ───

// 一条请求-响应留存记录的可序列化表示（跨插件传递用）。
message TrafficEntry {
  int64               id            = 1;
  int64               timestamp_ms  = 2;
  string              client_ip     = 3;
  string              method        = 4;
  string              path          = 5;
  map<string,string>  req_header    = 6;
  bytes               req_body      = 7;
  int32               status        = 8;
  map<string,string>  resp_header   = 9;
  bytes               resp_body     = 10;
  int64               duration_ms   = 11;
  string              api_format    = 12; // openai | claude | ollama | unknown
  string              model         = 13;
  int32               input_tokens  = 14;
  int32               output_tokens = 15;
  int32               total_tokens  = 16;
  bool                is_stream     = 17;
  string              blob_path     = 18;
}

// UsageInfo：从响应体解析出的用量信息。
message UsageInfo {
  string api_format    = 1;
  string model         = 2;
  int32  input_tokens  = 3;
  int32  output_tokens = 4;
  int32  total_tokens  = 5;
}

// ── RecorderService（BASE）：留存 + 查询 ──
service RecorderService {
  rpc Save(SaveRequest)           returns (SaveResponse);
  rpc List(ListRequest)           returns (ListResponse);
  rpc ReadBlob(ReadBlobRequest)   returns (ReadBlobResponse);
  rpc Stats(StatsRequest)         returns (StatsResponse);
}
message SaveRequest      { TrafficEntry entry = 1; }
message SaveResponse     { int64 id = 1; string error = 2; }
message ListRequest      { int32 limit = 1; int32 offset = 2; string model = 3; string format = 4; int32 status = 5; }
message ListResponse     { repeated TrafficEntry records = 1; int32 total = 2; }
message ReadBlobRequest  { int64 id = 1; }
message ReadBlobResponse { TrafficEntry entry = 1; string error = 2; }
message StatsRequest     {}
message ModelStat        { string model = 1; int32 count = 2; int64 input_tokens = 3; int64 output_tokens = 4; int64 total_tokens = 5; }
message StatsResponse    {
  int32 total_requests = 1;
  int32 success_count  = 2;
  int32 error_count    = 3;
  int64 total_tokens   = 4;
  repeated ModelStat by_model = 5;
}

// ── UsageService（BASE）：用量解析（非流式整体 / 流式全文） ──
service UsageService {
  rpc ParseBody(ParseBodyRequest)   returns (UsageInfo);
  rpc ParseStream(ParseStreamRequest) returns (UsageInfo);
}
message ParseBodyRequest   { bytes body = 1; string path = 2; }
message ParseStreamRequest { bytes raw = 1; string path = 2; } // raw = 拼回的全量 SSE 原文

// ── ProxyService（COMPLEX）：内核把外部请求转发到此，由它转上游并触发留存 ──
service ProxyService {
  rpc Handle(HandleRequest) returns (HandleResponse);
}
message HandleRequest {
  string             method     = 1;
  string             path       = 2;
  string             query      = 3;
  map<string,string> req_header = 4;
  bytes              req_body   = 5;
  string             client_ip  = 6;
}
message HandleResponse {
  int32              status      = 1;
  map<string,string> resp_header = 2;
  bytes              resp_body   = 3;
  string             error       = 4;
}

// ── DashboardService（MID，依赖 recorder）：只读管理界面 ──
service DashboardService {
  rpc Render(RenderRequest) returns (RenderResponse);
}
message RenderRequest  { string path = 1; string query = 2; }
message RenderResponse {
  int32              status       = 1;
  string             content_type = 2;
  bytes              body         = 3;
}